Skip to content

overview.md

Latest commit

 

History

History
115 lines (88 loc) · 5.72 KB

overview.md

File metadata and controls

115 lines (88 loc) · 5.72 KB

Overview

This page lists the full feature set, the interactive workflow, and the available command-line tools. See Installation for setup and Getting started for a hands-on walkthrough.

Relationship to existing OMNeT++ tools

opp_repl is an umbrella around the standard OMNeT++ toolchain, not a replacement for it. It still calls opp_run, opp_makemake, opp_featuretool, and opp_scavetool under the hood; what it adds is a Python API and command-line driver for orchestrating them — discovering configs, running them concurrently or on a cluster, comparing results across projects or commits, maintaining test baselines, bisecting regressions, and exposing all of this to an interactive REPL or to AI assistants over MCP. It coexists with the OMNeT++ IDE and with hand-written test scripts, and does not modify the underlying simulation binaries.

Features

  • Build projects — build simulation binaries from Python
  • Run simulations — run all or filtered simulations from a project, sequentially or concurrently, on localhost or an SSH cluster
  • Simulation comparison — compare stdout trajectories, fingerprint trajectories, and scalar results between two projects, between two git commits, or across a sequence of commits
  • Parameter optimization — find simulation parameter values that produce desired results using derivative-free optimization
  • Smoke tests — verify that simulations start and terminate without crashing
  • Fingerprint tests — detect behavioral regressions by comparing event fingerprints against a stored baseline
  • Statistical tests — detect regressions in scalar results by comparing against stored baseline values
  • Comparison tests — detect regressions between two arbitrary projects or commits (or across a sequence of commits) without consulting any stored baseline
  • Speed tests — detect performance regressions by comparing CPU instruction counts against a baseline
  • Chart tests — detect visual regressions by comparing rendered analysis charts against baseline images
  • Sanitizer tests — find memory errors and undefined behavior using AddressSanitizer / UBSan instrumentation
  • Feature tests — verify that projects build and simulations set up correctly with different optional feature combinations
  • Release tests — run a comprehensive validation suite for release builds
  • Test bisect — find the git commit that introduced a test failure using binary search
  • Coverage reports — generate C++ line-coverage reports using LLVM's coverage tools
  • Overlay builds — out-of-tree builds using fuse-overlayfs on top of read-only source trees
  • SSH cluster execution — distribute simulation tasks across multiple machines using Dask
  • GitHub Actions integration — dispatch CI workflows from the REPL
  • IDE integration — connect to the OMNeT++ IDE via Py4J
  • MCP server — expose the REPL to AI assistants via the Model Context Protocol
  • Bundled project descriptors — pre-packaged .opp files for OMNeT++ sample projects, loadable via --load @opp

Using Python interactively

The opp_repl command launches an IPython interpreter with all simulation functions pre-loaded. You can also use any other Python interpreter and import opp_repl directly.

A typical session:

$ cd ~/workspace/omnetpp && . setenv
Environment for 'omnetpp-X.Y.Z' in directory '/home/user/workspace/omnetpp' is ready.
$ cd ~/workspace/opp_repl && . setenv
opp_repl is ready (added /home/user/workspace/opp_repl to PATH).
$ opp_repl --load ~/workspace/inet/inet.opp
INFO opp_repl.simulation.project Default project is set to inet
INFO opp_repl.repl OMNeT++ Python support is loaded.

In [1]:

Type run and press TAB for completion. The interpreter completes module names, function names, method names, and their parameters.

See The REPL for details on REPL-specific features (autoreload, convenience variables, user modules, etc.).

Command-line tools

Many REPL functions have corresponding command-line tools, grouped here by purpose:

Interactive shell:

  • opp_repl — interactive Python interpreter

Build / clean:

  • opp_build_omnetpp — build the OMNeT++ kernel
  • opp_build_project — build a simulation project
  • opp_clean_omnetpp — clean the OMNeT++ build output
  • opp_clean_project — clean a simulation project's build output

Run simulations and tests:

  • opp_run_simulations — run simulations matching a filter
  • opp_run_all_tests — run all tests
  • opp_run_smoke_tests — verify simulations start and terminate without crashing
  • opp_run_fingerprint_tests — detect behavioral regressions via event fingerprints
  • opp_run_statistical_tests — detect regressions in scalar results
  • opp_run_speed_tests — detect performance regressions via CPU instruction counts
  • opp_run_chart_tests — detect visual regressions in analysis charts
  • opp_run_sanitizer_tests — find memory errors and undefined behavior
  • opp_run_feature_tests — verify builds with different optional feature combinations
  • opp_run_release_tests — run a comprehensive validation suite

Update test baselines:

  • opp_update_fingerprint_test_results — update the fingerprint baseline
  • opp_update_speed_test_results — update the speed test baseline
  • opp_update_statistical_test_results — update the statistical test baseline
  • opp_update_chart_test_results — update the chart test baseline images

Overlays:

  • opp_mount — mount overlay file systems for .opp projects
  • opp_unmount — unmount previously-mounted overlay file systems

Misc:

  • opp_repl_self_test — run the opp_repl self-test suite

All tools print their options when run with -h.