swarmsim.config#

Lazy initialization of built-in types

Holds registry of classes for the initialization system. prior to first use. This is to avoid circular imports.

These modules can then be accessed via the store object and the getting functions in this module for use with initialization from .yaml files or config objects.

It also provides the interface for registering third-party types/classes.

See also

Config Registry

class swarmsim.config.LazyKnownModules[source]#

Holds the registry of known classes

This class is used internally by the config system.

Caution

Users should avoid adding new entries directly and instead use the functions in the config module.

The registry will be initialized with all the built-in classes just before the first access of any of its known types. This is to avoid circular imports.

Attributes:
agent_types
dictlike_types
world_types
initialized_natives[source]#

True after the registry has been initialized.

swarmsim.config.store = <swarmsim.config.LazyKnownModules object>[source]#

Holds the registry of known classes. Instance of LazyKnownModules

Functions#

swarmsim.config.get_agent_class(config)[source]#

Retrieve the agent class from the agent type registry

Parameters:

config (dict or config dataclass) – A config dict with a type entry, or a config dataclass with a associated_type field.

Returns:

  • type – The agent class which will be used to create the agent

  • AgentConfig – The config

Raises:

  • AttributeError – associated_type field not found on config dataclass or type entry not found in config dict

  • KeyError – Agent type not found in registry

  • TypeError – Found an entry in the registry for the requested agent type, but it’s not the correct format of (agent_class, agent_config_class)

Examples

cls, config = get_agent_class(config)
agent = cls(config, world)
swarmsim.config.get_class_from_dict(key: str, config: dict, copy=True, raise_errors=True) → tuple[object, dict] | None[source]#

Retrieve a class from the registry for a given config dict

Parameters:

  • key (str) – The namespace to look up, i.e. ‘controller’, ‘spawner’, etc.

  • config (dict) – The config dict containing a type key

  • copy (bool, optional) – Will copy the config dict before returning it, by default True

  • raise_errors (bool, optional) – If True, raise errors, by default True

Returns:

returns (type, modified_config_dict) * type: The class * modified_config_dict: The config dict with the type key removed

Return type:

tuple[object, dict] | None

Raises:

  • AttributeError – The config dict is missing the type key

  • KeyError – The namespace or type was not found in the registry.

  • TypeError – Received a config that is not of type(dict)

Examples

from swarmsim.config import get_class_from_dict
from swarmsim.agent.StaticAgent import StaticAgent, StaticAgentConfig

agent = StaticAgent(StaticAgentConfig(), world=None)

config = {'type': 'StaticController', 'output': [0.1, 0]}

cls = get_class_from_dict('controller', config)
controller = cls(agent, config)
swarmsim.config.register_agent_type(name: str, agent_type, agent_config=None)[source]#

Register an agent class with the config system

Parameters:

  • name (str) –

    The name of the agent type, i.e. ‘MazeAgent’

    We recommend choosing it as the name of the agent class, i.e. agent_type.__name__

  • agent_type (_type_) – The agent class to register

  • agent_config (_type_) – The agent config dataclass type to register

swarmsim.config.register_world_type(name: str, world_type, world_config=None)[source]#

Register a world class with the config system

Parameters:

  • name (str) –

    The name of the world type, i.e. ‘RectangularWorld’

    We recommend choosing it as the name of the world class, i.e. world_type.__name__

  • world_type (_type_) – The world class to register

  • world_config (_type_) – The world config dataclass type to register

swarmsim.config.register_dictlike_namespace(key: str)[source]#

Register a new namespace for classes configured using dicts

Parameters:

key (str) – The namespace to register, i.e. ‘controller’, ‘spawner’, etc.

swarmsim.config.register_dictlike_type(key: str, name: str, cls)[source]#

Register a class for a given namespace

Parameters:

  • key (str) – The namespace to register, i.e. ‘controller’, ‘spawner’, etc.

  • name (str) – The name of the class, i.e. ‘StaticController’

  • cls (_type_) – The class to register, i.e. StaticController itself

swarmsim.config.initialize_natives()[source]#

Makes the config system aware of all the built-in classes

Calling this function after the config system has been initialized will have no effect.

Decorators#

swarmsim.config.associated_type(type_name: str)[source]#

Decorate a config dataclass to add an associated_type field

Normally, dataclasses will raise an error if you try to create an instance with an argument that is not in the dataclass.

The decorator cause the dataclass to detect unexpected arguments and set them as attributes on the config object.

Examples

MyAgentConfig.py#
from dataclasses import dataclass
from swarmsim.config import associated_type, filter_unexpected_fields

@associated_type("MyAgent")
@filter_unexpected_fields  # optional
@dataclass
class MyAgentConfig:
    my_custom_field: int = 999

config = MyAgentConfig()
config.associated_type == "MyAgent"  # True
swarmsim.config.filter_unexpected_fields(cls)[source]#

Decorate a dataclass to filter out unexpected fields

Normally, dataclasses will raise an error if you try to create an instance with an argument that is not in the dataclass.

The decorator cause the dataclass to detect unexpected arguments and set them as attributes on the config object.

Examples

@filter_unexpected_fields
@dataclass
class MyAgentConfig:
    my_custom_field: int = 999

config = MyAgentConfig(unexpected_field="hello")
config.unexpected_field == "hello"  # True

See also

There is no swarmsim.config.get_world_class function, world type lookup is handled inside World_from_config.

Module Attributes

store

Holds the registry of known classes.

Functions

associated_type(type_name)

Decorate a config dataclass to add an associated_type field

filter_unexpected_fields(cls)

Decorate a dataclass to filter out unexpected fields

get_agent_class(config)

Retrieve the agent class from the agent type registry

get_class_from_dict(key, config[, copy, ...])

Retrieve a class from the registry for a given config dict

initialize_natives()

Makes the config system aware of all the built-in classes

register_agent_type(name, agent_type[, ...])

Register an agent class with the config system

register_dictlike_namespace(key)

Register a new namespace for classes configured using dicts

register_dictlike_type(key, name, cls)

Register a class for a given namespace

register_world_type(name, world_type[, ...])

Register a world class with the config system

Classes

LazyKnownModules()

Holds the registry of known classes

Modules

OutputTensorConfig

This class defines a configuration for how the World will output a large numpy array representing the pixels on the screen

ResultsConfig