Skip to main content

Overview

CppModel is a code-first simulation framework for C and C++ control system software. You run your real production code with controlled inputs, record how it behaves over time, and review the results with your team in a shared workspace. CppModel has two parts:

  • The library, which you link into a small simulation program on your own machine.
  • The workspace at workspace.cppmodel.com, where results are stored, plotted and shared.

Your source code and binaries never leave your machine. Only the recorded inputs, outputs and parameters of a simulation are sent to the workspace.

How it works​

A simulation calls your code at a fixed cycle time, just as a real-time task would on the target:

  1. You create a simulation with a name, a total time and a step size (cycle time).
  2. The library calls your cyclic function once per step. In it you set the inputs, call the code under test and record its outputs.
  3. When the simulation finishes, the recorded data is uploaded to the workspace under the simulation's name, where it is shown as plots of inputs and outputs over time.

Because nothing but the simulation program runs locally, a simulation is an ordinary executable. You can build it with your usual toolchain, run it from your IDE and run it in CI.

The library​

The library is one self-contained shared library for Linux (x86_64, aarch64), Windows (x64, ARM64) and macOS (see Installation). It works with any common compiler on those platforms and has two APIs:

  • A C API (cppmodel/CModel.h) for embedded C code. This is the recommended starting point and what most examples in this documentation use.
  • A C++ API (cppmodel/cppmodel.hpp) with a cppmodel::Simulation base class.

Simulations can also be written in Python or JavaScript with the cppmodel packages on PyPI and npm (see Python and Node.js). They use the same library and record their results in the same workspace.

The library has verification built in, at several levels:

  • Each step: the simulation can mark every step as passed or failed. The workspace then shows exactly when the behaviour went wrong.
  • Behavior over time: verification rules check invariants, responses within a deadline, settling after a setpoint change, allowed mode transitions, oscillation, actuator wear, rate limits and energy budgets. Each rule reports a margin in physical units, so you see how close a passing run came to failing.
  • Requirements: a simulation can name the requirement IDs it verifies, and the library records which steps covered each one.
  • The whole run: the simulation program's exit code reports whether every step passed, so a simulation can act as a test in CTest or any CI system.

See Adding verification and Verification Rules for details.

A simulation can also run locally, with its inputs and parameters from a file and its results written to a file instead of the workspace. That is useful for trying values quickly; the run you keep is then recorded in the workspace (see Local runs).

The workspace​

The workspace keeps the latest results of every simulation in one place:

  • Inputs and outputs are plotted over time. When verification is used, an extra graph shows which steps passed (green) and which failed (red).
  • Parameters can be set in the workspace and are picked up by the next run. Developers, test engineers and project managers can tune a scenario without editing code.
  • Several developers can run the same simulation against different versions of the code, and everyone on the team sees the latest results.

Free accounts share one workspace, where results are visible to everyone else on the free tier. Every paid plan gives you a private workspace. See Pricing Models for plans.

Next steps​

  • Quick Start: export a ready-to-run project from the playground.
  • Installation: install the library.
  • Create Simulation: write your first simulation.
  • Verification Rules: check behavior over time and record the requirements a simulation verifies.
  • Command-line tool: query results, run parameter sweeps and record local runs from CI jobs and scripts.
  • Claude Code Plugin: let Claude Code set up your environment, write simulations, build plant models, run parameter sweeps and query results through the CppModel MCP server.