negmas.inout

Defines import/export functionality

class negmas.inout.Scenario(outcome_space: ~negmas.outcomes.outcome_space.CartesianOutcomeSpace, ufuns: tuple[~negmas.preferences.crisp_ufun.UtilityFunction, ...], mechanism_type: type[~negmas.mechanisms.Mechanism] | None = <class 'negmas.sao.mechanism.SAOMechanism'>, mechanism_params: dict = NOTHING, info: dict[str, ~typing.Any] = NOTHING, stats: ~negmas.preferences.ops.ScenarioStats | None = None)

Bases: object

A class representing a negotiation domain

calc_extra_stats(max_cardinality: int = 10000000000) → dict[str, Any]

Calculates and returns several stats corresponding to the domain

Parameters:

max_cardinality (int) – The maximum number of outcomes considered when calculating the stats.

Returns:

A dictionary with the compiled stats

calc_stats() → ScenarioStats

Calc stats and save them.

Returns:

The result.

Return type:

ScenarioStats

discretize(levels: int = 10)

Discretize all issues

dumpas(folder: Path | str, type='yml', compact: bool = False, save_stats=True, save_info=True, include_pareto_frontier: bool = True) → None

Dumps the scenario in the given file format.

Parameters:

• folder – Destination folder path.

• type – File format (“yml”, “json”, or “xml”).

• compact – If True, use compact JSON formatting.

• save_stats – If True, save scenario statistics to stats.json.

• save_info – If True, save scenario info to info file.

• include_pareto_frontier – If True, include pareto_utils and pareto_outcomes in stats.json. If False, exclude them to save disk space. Default is True.

static from_genius_files(domain: PathLike, ufuns: Iterable[PathLike], info: PathLike | None = None, ignore_discount=False, ignore_reserved=False, safe_parsing=True) → Scenario | None

From genius files.

Parameters:

• domain – Domain.

• ufuns – Ufuns.

• info – Info.

• ignore_discount – Ignore discount.

• ignore_reserved – Ignore reserved.

• safe_parsing – Safe parsing.

Returns:

The result.

Return type:

Scenario | None

static from_genius_folder(path: PathLike | str, ignore_discount=False, ignore_reserved=False, safe_parsing=True) → Scenario | None

From genius folder.

Parameters:

• path – Path.

• ignore_discount – Ignore discount.

• ignore_reserved – Ignore reserved.

• safe_parsing – Safe parsing.

Returns:

The result.

Return type:

Scenario | None

static from_geniusweb_files(domain: PathLike, ufuns: Iterable[PathLike], info: PathLike | None = None, ignore_discount=False, ignore_reserved=False, use_reserved_outcome=False, safe_parsing=True) → Scenario | None

From geniusweb files.

Parameters:

• domain – Domain.

• ufuns – Ufuns.

• info – Info.

• ignore_discount – Ignore discount.

• ignore_reserved – Ignore reserved.

• use_reserved_outcome – Use reserved outcome.

• safe_parsing – Safe parsing.

Returns:

The result.

Return type:

Scenario | None

static from_geniusweb_folder(path: PathLike | str, ignore_discount=False, ignore_reserved=False, use_reserved_outcome=False, safe_parsing=True) → Scenario | None

From geniusweb folder.

Parameters:

• path – Path.

• ignore_discount – Ignore discount.

• ignore_reserved – Ignore reserved.

• use_reserved_outcome – Use reserved outcome.

• safe_parsing – Safe parsing.

Returns:

The result.

Return type:

Scenario | None

classmethod from_yaml_files(domain: PathLike, ufuns: Iterable[PathLike], info: PathLike | None = None, ignore_discount=False, ignore_reserved=False, safe_parsing=True, python_class_identifier='type') → Scenario | None

From yaml files.

Parameters:

• domain – Domain.

• ufuns – Ufuns.

• info – Info.

• ignore_discount – Ignore discount.

• ignore_reserved – Ignore reserved.

• safe_parsing – Safe parsing.

• python_class_identifier – Python class identifier.

Returns:

The result.

Return type:

Scenario | None

classmethod from_yaml_folder(path: PathLike | str, ignore_discount=False, ignore_reserved=False, safe_parsing=True) → Scenario | None

From yaml folder.

Parameters:

• path – Path.

• ignore_discount – Ignore discount.

• ignore_reserved – Ignore reserved.

• safe_parsing – Safe parsing.

Returns:

The result.

Return type:

Scenario | None

info: dict[str, Any]

classmethod is_loadable(path: PathLike | str)

Check if loadable.

Parameters:

path – Path.

is_normalized(to: tuple[float | None, float | None] = (None, 1.0), positive: bool = True, eps: float = 1e-06) → bool

Checks that all ufuns are normalized in the given range

property issue_names: list[str]

Issue names.

Returns:

The result.

Return type:

list[str]

property issues: tuple[Issue, ...]

Issues.

Returns:

The result.

Return type:

tuple[Issue, …]

classmethod load(folder: Path | str, safe_parsing=False, ignore_discount=False, load_stats=True, load_info=True, **kwargs) → Scenario | None

Loads the scenario from a folder with supported formats: XML, YML

load_info(folder: PathLike | str)

Load info.

Parameters:

folder – Folder.

load_info_file(file: Path)

Load info file.

Parameters:

file – File.

load_stats(folder: PathLike | str, calc_pareto_if_missing: bool = False)

Load stats.

Parameters:

• folder – Folder containing the stats file.

• calc_pareto_if_missing – If True and the loaded stats have no pareto frontier data, calculate it using this scenario’s utility functions.

Returns:

Self for method chaining.

Notes

Looks for stats in the following order (for backward compatibility): 1. _stats.yaml (new format) 2. stats.json (legacy format from cartesian_tournament < 0.14.0)

Handles stats files that may have been saved without pareto frontier data (when include_pareto_frontier=False was used during saving).

When calc_pareto_if_missing=True, the pareto frontier will be computed on-the-fly, which may be slow for large outcome spaces.

load_stats_file(file: Path, calc_pareto_if_missing: bool = False)

Load stats file.

Parameters:

• file – File path to load stats from.

• calc_pareto_if_missing – If True and the loaded stats have no pareto frontier data, calculate it using this scenario’s utility functions.

Returns:

Self for method chaining.

Notes

Handles stats files that may have been saved without pareto frontier data (when include_pareto_frontier=False was used during saving).

When calc_pareto_if_missing=True, the pareto frontier will be computed on-the-fly, which may be slow for large outcome spaces.

make_session(negotiators: Callable[[], Negotiator] | type[Negotiator] | list[Negotiator] | tuple[Negotiator, ...] | None = None, n_steps: int | float | None = None, time_limit: float | None = None, roles: list[str] | None = None, raise_on_failure_to_enter: bool = True, share_ufuns: bool = False, share_reserved_values: bool = False, **kwargs)

Generates a ready to run mechanism session for this domain.

mechanism_params: dict

mechanism_type: type[Mechanism] | None

property n_issues: int

N issues.

Returns:

The result.

Return type:

int

property n_negotiators: int

N negotiators.

Returns:

The result.

Return type:

int

normalize(to: tuple[float, float] = (0.0, 1.0)) → Scenario

Normalizes a utility function to the given range

Parameters:

rng – range to normalize to. Default is [0, 1]

outcome_space: CartesianOutcomeSpace

plot(**kwargs)

Plot.

Parameters:

**kwargs – Additional keyword arguments.

remove_discounting()

Removes discounting from all ufuns

remove_reserved_values(r: float = -inf)

Removes reserved values from all ufuns replaacing it with r

scale_max(to: float = 1.0) → Scenario

Normalizes a utility function to the given range

Parameters:

• ufun – The utility function to normalize

• outcomes – A collection of outcomes to normalize for

• rng – range to normalize to. Default is [0, 1]

• levels – Number of levels to use for discretizing continuous issues (if any)

• max_cardinality – Maximum allowed number of outcomes resulting after all discretization is done

scale_min(to: float = 1.0) → Scenario

Normalizes a utility function to the given range

Parameters:

• ufun – The utility function to normalize

• outcomes – A collection of outcomes to normalize for

• rng – range to normalize to. Default is [0, 1]

• levels – Number of levels to use for discretizing continuous issues (if any)

• max_cardinality – Maximum allowed number of outcomes resulting after all discretization is done

serialize() → dict[str, Any]

Converts the current scenario into a serializable dict.

Remarks:

Rturns a dictionary with the following keys:

• domain: The agenda/outcome-space

• ufuns: A list of utility functions

stats: ScenarioStats | None

to_genius_files(domain_path: Path, ufun_paths: list[Path])

Save domain and ufun files to the path as XML.

to_genius_folder(path: Path)

Save domain and ufun files to the path as XML.

to_json(folder: Path | str) → None

Saves the scenario as json :param folder: The destination path

to_numeric() → Scenario

Forces all issues in the domain to become numeric

Remarks:

• maps the agenda and ufuns to work correctly together

to_single_issue(numeric=False, stringify=True, randomize=False) → Scenario

Forces the domain to have a single issue with all possible outcomes

Parameters:

• numeric – If given, the output issue will be a ContiguousIssue otherwise it will be a DiscreteCategoricalIssue

• stringify – If given, the output issue will have string values. Checked only if Numeric and Mathematical Modules is False

• randomize – Randomize outcome order when creating the single issue

Remarks:

• maps the agenda and ufuns to work correctly together

• Only works if the outcome space is finite

to_yaml(folder: Path | str) → None

Saves the scenario as yaml :param folder: The destination path

ufuns: tuple[UtilityFunction, ...]

negmas.inout.find_genius_domain_and_utility_files(folder_name) → tuple[PathLike | None, list[PathLike]]

Finds the domain and utility_function files in a folder

negmas.inout.find_geniusweb_domain_and_utility_files(folder_name) → tuple[PathLike | None, list[PathLike]]

Finds the domain and utility_function files in a GeniusWeb formatted json folder

negmas.inout.get_domain_issues(domain_file_name: PathLike | str, n_discretization: int | None = None, safe_parsing=False) → Sequence[Issue] | None

Returns the issues of a given XML domain (Genius Format)

Parameters:

• domain_file_name – Name of the file

• n_discretization – Number of discrete levels per continuous variable.

• max_cardinality – Maximum number of outcomes in the outcome space after discretization. Used only if n_discretization is given.

• safe_parsing – Apply more checks while parsing

Returns:

List of issues

negmas.inout.load_genius_domain(domain_file_name: PathLike, utility_file_names: Iterable[PathLike] | None = None, ignore_discount=False, ignore_reserved=False, safe_parsing=True, **kwargs) → Scenario

Loads a genius domain, creates appropriate negotiators if necessary

Parameters:

• domain_file_name – XML file containing Genius-formatted domain spec

• utility_file_names – XML files containing Genius-fromatted ufun spec

• ignore_reserved – Sets the reserved_value of all ufuns to -inf

• ignore_discount – Ignores discounting

• safe_parsing – Applies more stringent checks during parsing

Returns:

A Domain ready to run

negmas.inout.load_genius_domain_from_folder(folder_name: str | PathLike, ignore_reserved=False, ignore_discount=False, safe_parsing=False, **kwargs) → Scenario

Loads a genius domain from a folder. See load_genius_domain for more details.

Parameters:

• folder_name – A folder containing one XML domain file and one or more ufun files in Genius format

• ignore_reserved – Sets the reserved_value of all ufuns to -inf

• ignore_discount – Ignores discounting

• safe_parsing – Applies more stringent checks during parsing

• kwargs – Extra arguments to pass verbatim to SAOMechanism constructor

Returns:

A domain ready for make_session

Examples

>>> import pkg_resources
>>> from negmas import load_genius_domain_from_folder

Try loading and running a domain with predetermined agents: >>> domain = load_genius_domain_from_folder( … pkg_resources.resource_filename(“negmas”, resource_name=”tests/data/Laptop”) … )

Try loading a domain and check the resulting ufuns >>> domain = load_genius_domain_from_folder( … pkg_resources.resource_filename(“negmas”, resource_name=”tests/data/Laptop”) … )

>>> domain.n_issues, domain.n_negotiators
(3, 2)

>>> [type(_) for _ in domain.ufuns]
[<class 'negmas.preferences.crisp.linear.LinearAdditiveUtilityFunction'>, <class 'negmas.preferences.crisp.linear.LinearAdditiveUtilityFunction'>]

Try loading a domain forcing a single issue space >>> domain = load_genius_domain_from_folder( … pkg_resources.resource_filename(“negmas”, resource_name=”tests/data/Laptop”) … ).to_single_issue() >>> domain.n_issues, domain.n_negotiators (1, 2) >>> [type(_) for _ in domain.ufuns] [<class ‘negmas.preferences.crisp.linear.LinearAdditiveUtilityFunction’>, <class ‘negmas.preferences.crisp.linear.LinearAdditiveUtilityFunction’>]

Try loading a domain with nonlinear ufuns: >>> folder_name = pkg_resources.resource_filename( … “negmas”, resource_name=”tests/data/10issues” … ) >>> domain = load_genius_domain_from_folder(folder_name) >>> print(domain.n_issues) 10 >>> print(domain.n_negotiators) 2 >>> print([type(u) for u in domain.ufuns]) [<class ‘negmas.preferences.crisp.nonlinear.HyperRectangleUtilityFunction’>, <class ‘negmas.preferences.crisp.nonlinear.HyperRectangleUtilityFunction’>] >>> u = domain.ufuns[0] >>> print(u.outcome_ranges[0]) {1: (7.0, 9.0), 3: (2.0, 7.0), 5: (0.0, 8.0), 8: (0.0, 7.0)}

>>> print(u.mappings[0])
97.0
>>> print(u([0.0] * domain.n_issues))
0
>>> print(u([0.5] * domain.n_issues))
186.0

negmas.inout.load_geniusweb_domain(domain_file_name: PathLike, utility_file_names: Iterable[PathLike] | None = None, ignore_discount=False, ignore_reserved=False, use_reserved_outcome=False, safe_parsing=True, **kwargs) → Scenario

Loads a geniusweb domain, creates appropriate negotiators if necessary

Parameters:

• domain_file_name – XML file containing Genius-formatted domain spec

• utility_file_names – XML files containing Genius-fromatted ufun spec

• ignore_reserved – Sets the reserved_value of all ufuns to -inf

• ignore_discount – Ignores discounting

• safe_parsing – Applies more stringent checks during parsing

• kwargs – Extra arguments to pass verbatim to SAOMechanism constructor

Returns:

A Domain ready to run

negmas.inout.load_geniusweb_domain_from_folder(folder_name: str | PathLike, ignore_reserved=False, ignore_discount=False, use_reserved_outcome=False, safe_parsing=False, **kwargs) → Scenario

Loads a genius-web domain from a folder. See load_geniusweb_domain for more details.

Parameters:

• folder_name – A folder containing one XML domain file and one or more ufun files in Genius format

• ignore_reserved – Sets the reserved_value of all ufuns to -inf

• ignore_discount – Ignores discounting

• safe_parsing – Applies more stringent checks during parsing

• kwargs – Extra arguments to pass verbatim to SAOMechanism constructor

Returns:

A domain ready for make_session

negmas.inout.scenario_size(self: Scenario)

Computes the scenario complexity as outcome space size times time steps.

Parameters:

self – The scenario to measure

Returns:

The estimated scenario size/complexity