Building and running simulations

run_simulations() is the most-used opp_repl function. It selects configs, expands them into tasks, builds the project if needed, then runs the whole batch and hands back a MultipleTaskResults you can drill into.

Upstream references:

• https://github.com/omnetpp/opp_repl/blob/main/doc/running_simulations.md
• https://github.com/omnetpp/opp_repl/blob/main/doc/tasks.md

Building

Building is implicit — run_simulations() always rebuilds first unless you pass build=False. When you want a build without a run:

build_project(simulation_project=inet_project) build_project(simulation_project=inet_project, mode="debug")

Build modes map to binary suffixes:

build_project() recursively builds OMNeT++ and any used_projects first (toggle with recursive=False).

Running

Everything from the default project

run_simulations()

Explicit project + short time limit

run_simulations(simulation_project=aloha_project, sim_time_limit="1s")

Subset via filters

run_simulations(simulation_project=inet_project, working_directory_filter="examples/ethernet", config_filter="Vlan", sim_time_limit="10s")

Debug mode (one specific config)

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

See opp-repl-filtering for the full filter vocabulary.

Default project

Three ways to establish the default so you can drop simulation_project=:

1. cd into a project directory before launching the REPL.
2. Start with -p PROJECT on the command line.
3. Call set_default_simulation_project(inet_project) at runtime.

Concurrency

By default tasks run concurrently using all CPU cores. Controls:

• concurrent=False -- sequential (useful for debugging, clearer logs).
• scheduler="thread" (default) / "process" / "cluster".
• randomize=True -- shuffle execution order.
• Pressing Ctrl-C cancels the remaining tasks; already-collected

results stay in the returned object.

Running on an SSH/Dask cluster requires the cluster extra and cluster=SSHCluster(...) -- see opp-repl-ssh-cluster.

Result object

run_simulations() returns MultipleTaskResults. The workhorse methods:

r = run_simulations(config_filter="PureAloha", sim_time_limit="1s") r # prints summary + unexpected details r.get_error_results() # drill into ERRORs r.get_unexpected_results() # anything not matching expectation r.is_all_results_done() # bool r.rerun() # re-execute same tasks r.get_error_results().rerun() # re-run only the failures r.results[0].rerun(mode="debug") # re-run single task in debug

Full model in opp-repl-tasks-and-results.

Single-task shortcut

Use get_simulation_task() when you need EXACTLY one task (it errors if the filters match zero or >1 tasks). Handy for compare_simulations(), optimize_simulation_parameters(), and interactive debugging:

t = get_simulation_task(config_filter="PureAloha1", run_number=0, sim_time_limit="1s") r = t.run()

Cleaning result files

clean_simulation_results(simulation_project=inet_project) clean_simulation_results(simulation_project=inet_project, working_directory_filter="examples/ethernet")

Removes .sca, .vec, .vci, .elog, .log, .rt files from result folders of matching configs.

CLI equivalents

opp_build_project --load inet.opp -p inet -m debug opp_run_simulations --load inet.opp -p inet \ --working-directory-filter examples/ethernet \ -t 10s

See opp-repl-cli-tools for the full flag table.

Pitfalls

• sim_time_limit="1s" is a STRING with a unit — not a number.
• build=False + stale binary silently runs old code. Keep build

on unless you just built the same mode.

• `Exception: Building <X> failed` with no further info almost

always means "no Makefile yet" — call build_project(), which auto-generates the Makefile on current opp_repl. See opp-repl-troubleshooting §1 for the bootstrap sequence on older versions.

• ERROR (Non-zero exit code: 127) means the executable does not

exist (wrong name or not built). Inspect tr.subprocess_result.stderr for the real message; see opp-repl-troubleshooting §2.

• `tr.stdout` / `tr.stderr` may be `None` on early failures.

Always fall back to tr.subprocess_result.stdout / .stderr when diagnosing an ERROR. tr.stdout is only populated from the configured cmdenv-output-file, which doesn't exist if the process died before writing it.

• In concurrent mode the on-screen order of results does not match

task order. Use r.results[i].task to correlate.

• Interrupting (Ctrl-C) leaves partial result files in place; run

clean_simulation_results() to tidy up.

See also

• opp-repl-concepts — the object model.
• opp-repl-project-scaffolding — generate Makefile + required files

BEFORE the first build (prevents the most common build failure).

• opp-repl-filtering — narrow down which configs run.
• opp-repl-tasks-and-results — inspect and rerun results.
• opp-repl-result-analysis — read .sca/.vec files after a DONE run.
• opp-repl-troubleshooting — decode opaque errors into fixes.
• opp-repl-ssh-cluster — distribute to remote machines.
• opp-repl-cli-tools — shell wrappers for CI.