scml.runner

Classes

WorldRunner

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

Functions

mean(→ float)

Calculates the mean

median(→ float)

Calculates the median

Module Contents

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

Calculates the mean

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

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)[source]

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

classmethod from_runner(src: WorldRunner, **kwargs) WorldRunner[source]

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[source]

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

property existing_config_names: list[str][source]

Existing configuration names.

property existing_type_names: list[str][source]

Existing type names tested so far.

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

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][source]

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[source]

Runs all worlds

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

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][source]

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]][source]
world_infos_of(type: AgentType | str | None = None, config: str | None = None) list[WorldInfo][source]

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][source]

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]][source]

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][source]

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.

property stats: pandas.DataFrame[source]

The statistics saved (must be constructed with save_stats)

property all_world_infos: list[WorldInfo][source]

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

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

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

property scores: pandas.DataFrame[source]

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.

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

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)[source]

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)[source]

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)[source]