Introduction

gradysim.simulator.extension

Simulator extensions or simply extensions are modules that extend the functionality of the python simulator. They are used to implement new features or to provide new ways to interact with the simulation environment.

Extensions are akin to plugins, but instead of expanding the functionality of a protocol they act on a simulation-level to implement new features that protocols can use. While plugins are designed to be environment-agnostic, extensions are tied to the python simulation environment, this is reflected in the fact that extensions are located within the simulator package. Extensions can be used to implement new simulation features, such as new types of sensors, actuators, or other simulation components.

Extensions are implemented as classes that inherit from the Extension class. Extensions are attached to a protocol instance but have ways of interacting with the simulation environment that the protocol does not. In practice, extensions can directly access handlers and modify the simulation environment.

Warning

Extensions are attached to an initialized protocol. Instantiating an extension on an uninitialized protocol will raise a ReferenceError.

Info

Most extensions rely on a specific handler being present in the simulation. Check their own documentation to see which handlers they rely on.

gradysim.simulator.extension.extension.Extension

Base class for all extensions. Extensions are classes that can be used to extend the functionality of the simulation environment. They are designed to be used by protocols to interact with the simulation environment in a more sophisticated way.

Source code in gradysim/simulator/extension/extension.py

class Extension:
    """
    Base class for all extensions. Extensions are classes that can be used to extend the functionality of the simulation
    environment. They are designed to be used by protocols to interact with the simulation environment in a more
    sophisticated way.
    """

    _provider: Optional[PythonProvider]

    def __init__(self, protocol: IProtocol):
        provider = protocol.provider

        if protocol.provider is None:
            raise ReferenceError("Protocol provider is not initialized. Make sure you are not creating this extension "
                                 "before the protocol's initialize method is called.")

        if not isinstance(provider, PythonProvider):
            warnings.warn("Extensions can only be ran in a python simulation environment. "
                          "Every functionality in this extension will be a no-op.")
            self._provider = None
        else:
            self._provider = provider