Tasks and task results

Every opp_repl operation is a Task; every task produces a TaskResult. Batches return a MultipleTaskResults. These objects are your programmable handle on what the REPL just did.

Upstream references:

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

Task families

What a SimulationTask carries

• simulation_config + run_number -> identifies WHAT to run.
• mode -> release / debug / sanitize / coverage / profile.
• Time limits -> sim_time_limit, cpu_time_limit; plain strings

or callables (config, run_number) -> str.

• Runner -> subprocess (default), opp_env (auto when the project

is opp_env-managed), inprocess (CFFI), ide (auto when debug=True or a breakpoint parameter is set).

• Output overrides -> stdout / eventlog / .sca / .vec file paths.
• Knobs -> record_eventlog, record_pcap, user_interface

("Cmdenv" default or "Qtenv"), extra inifile_entries.

Inspecting a SimulationTaskResult

r = run_simulations(config_filter="PureAloha1", sim_time_limit="1s") t = r.results[0]

t.result_code # e.g. "DONE" t.expected_result # usually "DONE" t.is_expected() # actual == expected t.elapsed_time # wall clock t.cpu_time, t.cycles, t.instructions # from OMNeT++ CPU summary t.error_message, t.error_module # when ERROR t.last_event_number, t.last_simulation_time t.stdout_file, t.eventlog_file, t.sca_file, t.vec_file t.used_ned_types # sorted list of NED types instantiated t.subprocess_result # raw CompletedProcess

t.print_result() # colored one-line summary t.print_stdout(); t.print_stderr() # captured I/O t.get_description() # string form

Post-mortem trajectories:

ft = t.get_fingerprint_trajectory() # per-event fingerprint values st = t.get_stdout_trajectory() # event# <-> stdout lines (regex OK)

Result-data accessors (current opp_repl, >= commit 2e6835e):

df = t.get_scalars() # .sca file as a pandas DataFrame df = t.get_vectors() # .vec file as a pandas DataFrame df = t.get_histograms() # histograms from .sca

Signatures:

get_scalars(include_fields=True, include_runattrs=False, kwargs) get_vectors(include_runattrs=False, kwargs) get_histograms(include_runattrs=False, **kwargs)

See opp-repl-result-analysis for typical aggregation patterns, filter options, and fallbacks for older opp_repl.

MultipleTaskResults drill-down

r = run_simulations(sim_time_limit="1s")

r.get_done_results() r.get_error_results() r.get_unexpected_results() # excludes SKIP/CANCEL r.get_fail_results() # test-task specific (FAIL) r.is_all_results_done() r.is_all_results_expected()

r.filter_results( result_filter="ERROR", error_message_filter="Unknown parameter")

Every filter returns a new MultipleTaskResults, so chains compose.

Aggregated result-data accessors

MultipleSimulationTaskResults (current opp_repl) also exposes the same .get_scalars() / .get_vectors() / .get_histograms() methods. They concatenate per-run DataFrames across every DONE result:

r = run_simulations(sim_time_limit="1s") df = r.get_scalars() # one row per (run, module, name) df.groupby("name").value.mean() # aggregate across reps

Non-DONE results (SKIP, CANCEL, ERROR, FAIL) contribute nothing — the method silently skips them. Check r.is_all_results_done() first if your aggregation looks sparse.

Re-running

Both single and multiple results support .rerun(), optionally with parameter overrides:

r.rerun() # repeat everything r.get_error_results().rerun() # only failures r.results[0].rerun(mode="debug") # one task in debug

.recreate() produces a modified copy of the task without running it; useful when you want to tweak parameters and inspect before executing.

Hashing and caching

Every task computes a SHA-256 over its relevant inputs (project state, config, run number, mode, time limits). Higher-level machinery such as fingerprint tests uses these hashes to decide whether a cached baseline is still valid.

Git-bisecting a regression

opp_repl supports bisecting failing tests across git commits. The idea: given a known-good commit and a known-bad commit, the bisect machinery runs the test at each midpoint until the introducing commit is isolated. Use this for fingerprint / statistical / speed regressions where rerun times are feasible.

Treat the bisect helper as a facade over run_*_tests() + git-checkout; see help(bisect_fingerprint_tests) for the exact signature. The family of bisect functions is: bisect_fingerprint_tests, bisect_statistical_tests, bisect_smoke_tests, bisect_chart_tests, bisect_sanitizer_tests, bisect_speed_tests, bisect_simulations_between_commits. Their common signature is e.g.: bisect_fingerprint_tests(simulation_project, good_hash, bad_hash, update_good_results=True, **kwargs). The general pattern:

bisect_fingerprint_tests(simulation_project=inet_project, good_hash="v4.5", bad_hash="HEAD", config_filter="Vlan", sim_time_limit="1s")

Pitfalls

• Test tasks reuse simulation codes plus PASS/FAIL. A PASS test

can still have a DONE/ERROR simulation underneath — inspect .simulation_task_result when a test unexpectedly fails.

• SKIP on simulation = "requires user input / not runnable headless".

It is not the same as "build was up-to-date" (which is SKIP on a BuildTask).

• filter_results(error_message_filter=...) is a regex on the parsed

error message; include ^/$ to anchor.

• Reruns inherit the ORIGINAL task's parameters. Override via

kwargs: result.rerun(sim_time_limit="10s").

• `tr.stdout` / `tr.stderr` may be `None` on ERROR. They are

parsed from files the simulation writes (cmdenv-output-file, stderr capture) — if the process died before writing, the fields stay None. For EVERY ERROR result, go to the raw subprocess output:

print(tr.subprocess_result.returncode) print(tr.subprocess_result.stderr) print(tr.subprocess_result.stdout) print(tr.subprocess_result.args) # shows the exact cmd line

See opp-repl-troubleshooting for an exit-code-to-cause table.

See also

• opp-repl-concepts — where tasks sit in the hierarchy.
• opp-repl-running-simulations — creates SimulationTasks.
• opp-repl-comparing-simulations — CompareSimulationsTask.
• opp-repl-filtering — filter configs before tasks are created.
• Every opp-repl-*-tests skill — task-family details per test type.