scml.runner

Module Contents

Classes

WorldRunner

A utility class to run controlled simulations for different agent types.

Functions

mean(→ float)	Calculates the mean
median(→ float)	Calculates the median

scml.runner.mean(lst: list[float]) → float

Calculates the mean

scml.runner.median(lst: list[float]) → float

Calculates the median

class scml.runner.WorldRunner(generator: scml.oneshot.context.BaseContext, n_configs: int = 10, n_repetitions: int = 1, save_worlds: bool = True, save_common_stats: bool = True, save_agent_stats: bool = True, combiner: Callable[[list[float]], float] = np.mean, control_all_agents: bool = False, shorten_names: bool = True, progress: bool = False)

A utility class to run controlled simulations for different agent types.

Parameters:

• generator – The Context used to generate world configurations

• n_configs – The number of configurations

• n_repetitions – Number of repetitions of each configuration

• one_offer_per_step – Whether one negotiation step is one offer. Pass as True when using RL

• save_worlds – If given worlds will be saved internally. You need this to use worlds_of and the like

• save_common_stats – Save general agent-independent statistics over time

• save_agent_stats – Save agent statistics over time

• combiner – How to combine scores and statistics if the number of agents of the tested type in a world is more than one

• control_all_agents – If given, the agent type(s) passed to __call__ will control the whole market.

• shorten_names – If given, shorter versions of type names will be used when compiling type-names

• progress – If given, a progress bar will be displayed for each world being run

property existing_config_names: list[str]

Existing configuration names.

property existing_type_names: list[str]

Existing type names tested so far.

property stats: pandas.DataFrame

The statistics saved (must be constructed with save_stats)

property all_world_infos: list[WorldInfo]

Information of all worlds simulated (including the agents evaluated for each world)

property all_worlds: list[scml.oneshot.world.SCMLBaseWorld]

Information of all worlds simulated (including the agents evaluated for each world)

property scores: pandas.DataFrame

The scores of all evaluated agents in all evaluated worlds

Remarks:

Other than the score, the returned data-frame will contain information about the production level, number of suppliers, number of consumers, number of competitors, etc about each agent.

classmethod from_runner(src: WorldRunner, **kwargs) → WorldRunner

Creates a WorldRunner from another one.

Remarks:

• It simply copies the configurations created by the source runner.

• You can override any parameters by passing them as keyword arguments

classmethod from_configs(world_type: type[scml.oneshot.world.SCMLBaseWorld], configs: tuple[dict[str, Any], Ellipsis], name: str | None = None, **kwargs) → WorldRunner

Creates a WorldRunner from a collection of configs.

Parameters:

• world_type – The world type to use.

• configs – The collection of configs to use.

Remarks:

• Uses a RepeatingContext internally.

• You can override any parameters of the new runner by passing them as keyword arguments

get_type_name(type_: type[AgentType] | str) → str

Used to get a name for the given type.

add(types: tuple[AgentType, Ellipsis] | list[AgentType] | AgentType, params: list[dict[str, Any]] | dict[str, Any] | None = None, name: str | None = None) → list[WorldInfo]

Used to add an agent type collection to the pool of tested agent types. Does not run the worlds

Parameters:

• types – In general, you can pass a collection of types here. Note that this collection will be used in every simulation. This means that the placeholder_types in the context used to create the runner must accept enough such agents. The usual use-case is that the placeholder_types in the context contain a single type and in this case, you can either pass a singelton collection of a single type or just pass the type directly.

• params – Parameters accepted by the constructor of the types passed.

• name – The name to call this type(s).

Returns:

A list of pairs each containing a world and a list of agents representing the worlds that were run and the agents corresponding to the passed type(s).

runall(progress: bool = False) → None

Runs all worlds

_runall(world_infos: list[WorldInfo], progress: bool = False) → None

Runs all worlds

__call__(types: tuple[AgentType, Ellipsis] | list[AgentType] | AgentType, params: list[dict[str, Any]] | dict[str, Any] | None = None, name: str | None = None, progress: bool = False) → list[WorldInfo]

Used to add an agent type collection to the pool of tested agent types.

Parameters:

• types – In general, you can pass a collection of types here. Note that this collection will be used in every simulation. This means that the placeholder_types in the context used to create the runner must accept enough such agents. The usual use-case is that the placeholder_types in the context contain a single type and in this case, you can either pass a singelton collection of a single type or just pass the type directly.

• params – Parameters accepted by the constructor of the types passed.

• name – The name to call this type(s).

Returns:

A list of pairs each containing a world and a list of agents representing the worlds that were run and the agents corresponding to the passed type(s).

_types_and_configs(type: AgentType | str | None = None, config: str | None = None) → tuple[list[str], list[str]]

world_infos_of(type: AgentType | str | None = None, config: str | None = None) → list[WorldInfo]

Returns the information of all worlds of the given type and config.

Remarks:

Note that you can also pass the name used when running the WorldRunner with the given type.

worlds_of(type: AgentType | str | None = None, config: str | None = None) → list[scml.oneshot.world.SCMLBaseWorld]

Returns the worlds of the given type and config.

Remarks:

Note that you can also pass the name used when running the WorldRunner with the given type.

agents_per_world_of(type: AgentType | str | None = None, config: str | None = None) → dict[str, list[AgentType]]

Returns the agents representing the type for each world of the given type and config.

Remarks:

Note that you can also pass the name used when running the WorldRunner with the given type.

agents_of(type: AgentType | str | None = None, config: str | None = None) → list[AgentType]

Returns the agents representing the type and config.

Remarks:

Note that you can also pass the name used when running the WorldRunner with the given type.

score_summary(percentiles=None, include=None, exclude=None, by: str | tuple[str, Ellipsis] = 'type', order_by: str | None = 'score', ascending: bool = False) → pandas.DataFrame

A summary of comparative scores of all agent types tested so far.

Parameters:

• percentiles – passed to groupby

• include – passed to groupby

• exclud – passed to groupby

• by – passed to groupby

• order_by – The method for sorting resulting scores. Possibilities: score, mean, min, max, 20%, 50%, 75%, median

• ascending – Ascending or descending scores.

Returns:

A dataframe that describes the scores of all evaluated types.

plot_stats(stats: tuple[str, Ellipsis] | str | None = None, by: tuple[str, Ellipsis] | str = 'type', agg: bool = True, legend: bool = True, ylegend: float = 1.8, legend_ncols=3, title: bool = True, order_by: str | None = 'score', ascending: bool = False, **kwargs)

Plots saves statistics (save_stats must be given)

Parameters:

• stats – The stats to be displayed. If not given, a default set will be chosen. Any statistic saved by the World or SCMLBaseWorld can be used. There are over 42 such statistics.

• by – Group the data by the given attribute (used as hue if agg is False and as x if agg is True).

• agg – Whether to aggregate over simulation steps or not.

• legend – whether or not to show a legend (only used if agg is False)

• legend_ncols – How many columns to use in the legend. Pass zero to disable the legend

• ylegend – The y-coordinate of the legend to control where it appears.

• title – Show stat names as title (instead of ylabel)

• order_by – The statistic to order with. Possibilities are score, mean, 50%, max, min, 20%, 75%, median

• ascending – If true, order ascendingly

• **kwargs – Any extra paramters to pass to the underlying seaborn method (lineplot in case agg=False and boxplot in case agg=True)

Returns:

The figure and axes used.

draw_worlds_of(type: AgentType | str | None, config: str | None = None, what=('contracts-signed',), n: int | None = 4, randomize: bool = False)

Draws the given set of worlds

Parameters:

• type – The type to filter by

• config – The config to filter by

• what – what stat to draw. See negmas.situated.World.draw_world for all options available

• n – Number of worlds to draw. If None, all of them will be drawn

• randomize – If given the worlds will be shuffled before display but only if not all worlds will be displayed

Returns:

figure and axes used.

process(info: WorldInfo)