1. Sequence Diagram of an experiment run

../_images/experiment_sequence_diagram.svg

Each experiment run can be split up in three parts:

  1. The initialization

  2. The main loop

  3. Shutdown

1.1. Initialization

After starting an experiment run with the CLI using the command palaestrai experiment-start path/to/experiment, the initialization process starts by handing the experiment path over to the Executor’s execute() method. The Executor first launches the RunGovernor and sends an ExperimentStartRequest to it afterwards. The RunGovernor handles most of the initialization:

  1. It sets up the SimulationController, EnviornmentConductor, and AgentConductor (in order)

  2. Sends a SimulationStartRequest to the SimulationController, which proceeds to request the initialization of the Enviornment from the EnvironmentConductor, and starts it afterwards.

  3. Then the SimulationController sends a AgentSetupRequest to the AgentConductor, which now initializes all needed brains and muscles for the experiment.

After receiving an AgentSetupResponse from the AgentConductor, the RunGovernor changes back into the Transceiving state and waits for new Requests. This concludes the initialization part of the experiment run.

1.2. Main Loop

The Main Loop is mainly a back and forth between the SimulationController and the Environment or The SimulationController sends either an :class:`~EnvironmentUpdateRequest to the Environment, which then updates and responds with an EnvironmentUpdateResponse, or an AgentUpdateRequest to a muscle, which then sends a MuscleUpdateRequest to its corresponding brain. After receiving a MuscleUpdateResponse from its brain, the muscle can finally respond to the SimulationController with an AgentUpdateResponse.

1.3. Shutdown

The shutdown usually gets initialized by an EnvironmentUpdateResponse with the is_terminal=True flag. The Executor then sends an ExpermimentRunShutdownRequest to the RunGovernor. The RunGovernor forwards this request in form of a SimulationStopRequest to the SimulationController which in turn will send shutdown requests to all muscles, which forward those to their brains, Environments and finally Agent- and EnvironmentConductors. After receiving a shutdown response from everyone the SimulationController sends a SimulationStopResponse to the RunGovernor and gets terminated. The RunGovernor forwards the Response as ExperimentShutdownResponse to the Executor then cleans up any left over sub processes and shuts down aswell.