A Python package for systematic exploration of simulation models. This tool was used in the evaluation of traffic controller use cases and provides a framework for systematic parameter space exploration with adaptive sampling.

K. Kušić et al., "Evaluation of Traffic Controller Performance via Systematic Exploration," 2024 International Symposium ELMAR, Zadar, Croatia, 2024, pp. 165-168, doi: 10.1109/ELMAR62909.2024.10694499.

git clone https://github.com/SiLab-group/SimEx.git
cd SimEx

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Or run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

# Install with development dependencies
pip install -e ".[dev]"

# Or install from requirements
pip install -r requirements-dev.txt

from simex import Simex
from simex.components.simulator import Simulator
from simex.components.modifier import Modifier
from simex.components.validator import Validator

sim = Simex(instance_name='Func_A', smoothen=False)
file = sim.run_simex(
    simulator_function=Simulator.sim_func_A,
    modifier=Modifier.modifierA,
    validator=Validator.local_exploration_validator_A
)
print(f"Run finished. CSV file is {file}")

from simex import Simex
from simex.config.settings import SimexSettings

settings = SimexSettings(
    instance_name='custom_run',
    domain_min_interval=1000,
    domain_max_interval=5000,
    modifier_incremental_unit=10,
    vfs_threshold_y_fitting=20,
    ops_sigmoid_tailing=True
)
sim = Simex(instance_name='custom_run', smoothen=True)
sim.settings = settings

simex-run                              # basic run
python examples/simex_run.py custom    # custom settings
python examples/simex_run.py compare   # parallel vs sequential

# Run all tests
pytest

# Run with coverage
pytest --cov=simex

# Run specific test file
pytest tests/test_simex.py -v

# Format code with black
black simex/ tests/ examples/

# Check code style
flake8 simex/ tests/ examples/

simex/
├── simex/                  # Main package
│   ├── core/              # Core SimEx loop
│   ├── components/        # Simulators, modifiers, validators
│   ├── controllers/       # Modifier, simulator, validator controllers
│   ├── utils/             # Logging
│   └── config/            # Settings
├── examples/              # Usage examples
│   ├── simex_run.py       # Basic example
│   └── marl_vsl/          # SUMO/MARL VSL examples
└── tests/

• domain_min_interval / domain_max_interval: Exploration domain bounds
• modifier_incremental_unit: Minimum step size for exploration
• modifier_data_point: Initial step size for point generation
• vfs_threshold_y_fitting: Y-axis threshold for curve fitting
• vfs_degree / vfs_max_deg: Polynomial fitting degree range
• max_workers: Number of parallel processes for simulation

Results are written to results_dir_NAME_timestamp/ and include:

• CSV files: Final results with fitted polynomial coefficients
• PDF plots: Visualization of fitted curves and unfit intervals
• Log files: Detailed execution logs
• Pickle files: Intermediate results for analysis

The tool supports both sequential and parallel execution:

Runs SimEx with built-in mock simulators (sim_func_A/B) — no external dependencies required. Good starting point to understand the SimEx loop.

python examples/simex_run.py           # basic run
python examples/simex_run.py custom    # custom settings
python examples/simex_run.py compare   # parallel vs sequential

Interactive walkthrough of the SimEx API.

Traffic controller examples using SUMO via TraCI. Requires a sumo_config.ini copied and filled in from sumo_config_example.ini.

Simple VSL (run_vsl_simple.py): single SimEx run with a rule-based proportional VSL controller. No training required.

cd examples/marl_vsl
python run_vsl_simple.py

MARL VSL loop (run_vsl_loop.py): iterative SimEx loop that trains MARL agents on demand regions where the VSL controller underperforms a no-VSL baseline. Pre-trained weights are provided in marl_training_file/.

cd examples/marl_vsl
python run_vsl_loop.py

Notebook (SimEx_loop.ipynb): interactive version of the MARL VSL loop with a standalone cell for analysing bad regions from an existing VSL output CSV.

1. Copy the example config: cp sumo_config_example.ini sumo_config.ini
2. Edit sumo_config.ini with your local SUMO binary and model paths
3. Set SUMO_HOME to your SUMO installation (e.g. export SUMO_HOME=/path/to/sumo)

For issues and questions:

• GitHub Issues: https://github.com/SiLab-group/SimEx/issues
• Email: [email protected]