+
+
+ 
+
A video demonstration of the Simul8 Agent in action
+ +## Requirements + +### Installation + +#### 1. Clone the Repository and Navigate to the Working Directory + +```bash +git clone https://github.com/INTO-CPS-Association/simulation-bridge.git +cd simulation-bridge +``` + +#### 2. Install Poetry and Create Virtual Environment + +Ensure that Poetry is installed on your system. If it is not already installed, execute the following commands: + +```bash +python3 -m pip install --user pipx +python3 -m pipx ensurepath +pipx install poetry +``` + +Verify the installation by checking the Poetry version: + +```bash +poetry --version +``` + +Activate the virtual environment: + +```bash +poetry env activate +``` + +> **Important:** +> The command `poetry env activate` does not automatically activate the virtual environment; instead, it prints the command you need to run to activate it. +> You must copy and paste the displayed command, for example: + +```bash +source /path/to/virtualenv/bin/activate +``` + +Verify that the environment is active by checking the Python path: + +```bash +which python +``` + +#### 3. Install Project Dependencies + +Run the following command to install all dependencies defined in `pyproject.toml`: + +```bash +poetry install +``` + +### Configuration + +The configuration is specified in yaml format. A template file (`simul8_agent/config/config.yaml.template`) has been provided. It can be customized further. + +Explanation on different fields of the yaml template is given below. + +```yaml +agent: + agent_id: simul8 # Specifies the unique identifier for the agent. This ID is used to distinguish the agent in the system. + simulator: simul8 # Specifies the name of the simulator + +rabbitmq: + host: localhost # The hostname or IP address of the RabbitMQ server. + port: 5672 # The port number for RabbitMQ communication (default is 5672). + username: guest # The username for authenticating with RabbitMQ. + password: guest # The password for authenticating with RabbitMQ. + heartbeat: 600 # The heartbeat interval (in seconds) to keep the connection alive. + vhost: / # The virtual host to use for RabbitMQ connections. + +simulation: + path: /Users/foo/simulation-bridge/agents/simul8/simul8_agent/docs/examples # The file path to the folder containing simul8 simulation files. + +exchanges: + input: ex.bridge.output # The RabbitMQ exchange from which the agent receives commands. + output: ex.sim.result # The RabbitMQ exchange to which the agent sends simulation results. + +queue: + durable: true # Ensures that the queue persists across RabbitMQ broker restarts. + prefetch_count: 1 # Limits the number of unacknowledged messages the agent can receive at a time. + +logging: + level: INFO # Specifies the logging level. Options include DEBUG, INFO, and ERROR. + file: logs/simul8_agent.log # The file path where logs will be stored. + +tcp: + host: localhost # The hostname or IP address for TCP communication. + port: 5678 # The port number for TCP communication. + +response_templates: + success: + status: success # Indicates a successful simulation response. + simulation: + type: batch # Specifies the type of simulation (e.g., batch or streaming). + timestamp_format: "%Y-%m-%dT%H:%M:%SZ" # The timestamp format in ISO 8601 with a Z suffix for UTC. + include_metadata: true # Determines whether metadata is included in the response. + metadata_fields: # Specifies the metadata fields to include in the response. + - execution_time + - memory_usage + - simul8_version + + error: + status: error # Indicates an error response. + include_stacktrace: false # For security, stack traces are excluded in production environments. + error_codes: # Maps specific error scenarios to HTTP-like status codes. + invalid_config: 400 # Error code for invalid configuration. + simul8_start_failure: 500 # Error code for simul8 startup failure. + execution_error: 500 # Error code for simulation execution errors. + timeout: 504 # Error code for simulation timeout. + missing_file: 404 # Error code for missing files. + + timestamp_format: "%Y-%m-%dT%H:%M:%SZ" # The timestamp format in ISO 8601 with a Z suffix for UTC. + + progress: + status: in_progress # Indicates that the simulation is currently in progress. + include_percentage: true # Includes the percentage of completion in progress updates. + update_interval: 5 # Specifies the interval (in seconds) for sending progress updates. + timestamp_format: "%Y-%m-%dT%H:%M:%SZ" # The timestamp format in ISO 8601 with a Z suffix for UTC. +``` + +## Usage + +The agent requires a configuration file to run. You can start by copying the provided template and customizing it as needed. + +### Getting Started + +**Generate a configuration file template:** + +```bash +poetry run simul8-agent --generate-config +``` + +This command creates a `config.yaml` file in your current directory. If the file already exists, it will not be overwritten. + +**Generate Project Files:** + +To create a complete set of template files for your Simul8 agent project: + +```bash +poetry run simul8-agent --generate-project +``` + +This command creates the following structure in your current directory (existing files won't be overwritten): + +``` +. +├── config.yaml # Agent configuration settings +├── SimulationBatch.ms8 # Template for batch simulations +``` + +Each template file contains documentation and can be customized for your specific simulation requirements. + +### Running the Agent + +To start the Simul8 Agent with the default configuration: + +```bash +poetry run simul8-agent +``` + +To use a custom configuration file: + +```bash +poetry run simul8-agent --config-file
Digital Automation Engineering Student
University of Modena and Reggio Emilia, Department of Sciences and Methods for Engineering (DISMI)
Associate Professor
University of Modena and Reggio Emilia, Department of Sciences and Methods for Engineering (DISMI)
Postdoctoral Researcher
Aarhus University
Computer Engineering Student
Aarhus University