Skip to content

running_simulations.md

Latest commit

 

History

History
141 lines (99 loc) · 4.67 KB

running_simulations.md

File metadata and controls

141 lines (99 loc) · 4.67 KB

Running Simulations

Run simulations with various filters and modes, handle results, and manage project loading and cleanup.

Running Simulations

The run_simulations() function can run multiple simulations matching filter criteria. Simulations can run sequentially or concurrently, on the local computer or on an SSH cluster.

Tip: Every loaded project is available as a {name}_project variable (hyphens/dots become underscores). Use get_simulation_project_variable_names() to list them.

# Run all simulations from a project
run_simulations(simulation_project=fifo_project)

# Run with a config filter and time limit
run_simulations(simulation_project=aloha_project,
                config_filter="PureAlohaExperiment", sim_time_limit="1s")

# Run in debug mode
run_simulations(simulation_project=inet_project,
                working_directory_filter="examples/ethernet",
                mode="debug", sim_time_limit="10s")

The order of simulation runs may vary because they run in parallel utilizing all CPUs by default.

Using the default project

Setting a default simulation project simplifies function calls:

set_default_simulation_project(get_simulation_project("fifo"))
run_simulations()  # uses default project

The same effect can be achieved by starting the Python interpreter from the project directory, or by using the -p PROJECT command-line option.

Handling results

run_simulations() returns a MultipleTaskResults object:

r = run_simulations(config_filter="PureAloha", sim_time_limit="1s")

# Re-run the same simulations
r = r.rerun()

# Re-run only errored simulations
r.get_error_results().rerun()

Controlling execution

See Simulation tasks for details on build modes, runners, concurrency options, cancellation, and get_simulation_tasks().

Command Line

When no --load option is given, all *.opp files in the current working directory are loaded automatically. This means you can simply cd into a project directory that contains .opp files and run simulations without any extra arguments:

# Run all simulations from the fifo sample project (*.opp files loaded from CWD)
cd ~/workspace/omnetpp/samples/fifo
opp_run_simulations

# Explicitly load a .opp file from a different location
opp_run_simulations --load /path/to/aloha.opp --filter PureAloha -t 1s

# Load a directory of .opp files
opp_run_simulations --load ~/workspace/omnetpp/samples/aloha -t 1s

# Load the bundled .opp files shipped with opp_repl
opp_run_simulations --load @opp --filter PureAloha -t 1s

# Run on a SSH cluster in debug mode with a filter and time limit
opp_run_simulations -m debug -t 1s --filter PureAlohaExperiment --hosts node1.local,node2.local

Note: The OMNeT++ project is auto-detected from the __omnetpp_root_dir environment variable (set by the OMNeT++ setenv script). You only need to load an omnetpp.opp file explicitly when using a non-standard installation. See OMNeT++ projects — Automatic detection.

Building Projects

Building is implicit: run_simulations() automatically builds the project before running any simulation, so there is no need to build manually. Pass build=False to skip this step when you want to use the current binary regardless of whether it is up-to-date.

See Building for the full story on the build, mode, and build_engine parameters, recursive builds, the per-wrapper defaults, and build artifacts on disk.

Loading projects at runtime

Use load_opp_file() to load a single file, directory, glob pattern, or the @opp token. Use load_workspace() to scan a directory tree for *.opp files:

# Load a single .opp file
load_opp_file("/path/to/aloha.opp")

# Load all *.opp files from a directory
load_opp_file("/home/user/workspace/omnetpp/samples/aloha")

# Load all .opp files matching a glob pattern
load_opp_file("/home/user/workspace/omnetpp/samples/*/*.opp")

# Load the bundled .opp files shipped with opp_repl
load_opp_file("@opp")

# Scan a directory for *.opp files (like the automatic startup scan)
load_workspace("/home/user/other-workspace")

See Simulation workspaces for more details.

Cleaning Results

clean_simulation_results() deletes the results/ folder for each matching simulation config. It accepts the same filter parameters as run_simulations():

# Clean all result folders in a project
clean_simulation_results(simulation_project=inet_project)

# Clean results only under a specific directory
clean_simulation_results(simulation_project=inet_project,
                         working_directory_filter="examples/ethernet")