Why Simulation CI?​

Traditional CI pipelines focus on unit tests and integration tests, which are essential for ensuring that your code behaves as expected. However, these tests are usually static and focus on a binary result (pass/fail), often lacking the ability to capture the dynamic behavior of your system. MIL, SIL, and HIL testing, on the other hand, let you simulate the behavior of your system under various conditions, providing a more comprehensive validation of your algorithms.

With CppModel, the code you write is the model itself, so you can get significantly closer to MIL and SIL testing — and even HIL testing, if you have access to the hardware — while still staying in the code domain. This makes it easy to integrate simulation-based testing into your existing software pipelines and workflows, so you can catch issues early and break down test results into specific pass and fail time intervals, which is crucial for understanding how your system behaves over time.

Setting Up Simulation CI​

For this example, we will follow the process described in the previous blog post How do you fill a glass of water? which is already modeled in CppModel. As the code is already hosted on GitHub, we will use GitHub Actions to set up our CI pipeline.

Code setup​

We will focus on the Glass of Water simulation and prepare a short verification test that checks whether the simulation behaves as expected. To track the simulation result at every step of time, we will use CppModel.StepResult, which captures the current step result and lets us summarize the overall pass/fail status of the simulation. This gives us a clear, easy-to-integrate view of simulation performance in the CI pipeline. To make sure the executable runs as a test in the CI pipeline, we will use CMake's enable_testing() and add_test() functions, which let us run the simulation as part of our CI pipeline and check the results.

Here is the CMakeLists.txt file for the Glass of Water simulation, with the verification source and test setup added:

cmake_minimum_required(VERSION 3.12)

project(GlassOfWater_Project LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)

enable_testing()

add_definitions(-DCPPHTTPLIB_OPENSSL_SUPPORT)

include_directories(dependencies/include)
link_directories(dependencies/lib)

add_executable(GlassOfWaterSim GlassOfWaterSim.c GlassOfWaterLib.c GlassOfWaterVerification.c)

set_target_properties(GlassOfWaterSim PROPERTIES LINKER_LANGUAGE CXX)
if (WIN32)
    target_link_libraries(GlassOfWaterSim CppModelBase ixwebsocket crypto ssl z crypt32 ws2_32)
else()
    target_link_libraries(GlassOfWaterSim CppModelBase ixwebsocket crypto ssl z)
endif()

add_test(NAME GlassOfWaterSim_Test COMMAND GlassOfWaterSim)

I'll break the verification of the process down into three steps:

• Pre-filling - The simulation will not fail, as we have not yet initialized the inputs and started the process. Since we may be adding water to an already-filled glass, the glass's initial state is not important for this simulation.
• Filling - The simulation will fail if the tap is open and the level does not change (for this example we will ignore any transport delay that may be present in the system).
• Post-filling - To keep it simple, we will consider the simulation successful if the level is equal to or greater than the desired level.

The goal of this article is to present the CI workflow, so we won't get into the specifics of testing against exact time intervals or specific interface values. Instead, we'll break the steps down based on tap opening and closing. With this in mind, we can implement a simple state machine that initializes in the Pre-filling state and transitions to Filling when the tap opens, then to Post-filling when the tap closes.

#include "GlassOfWaterVerification.h"

typedef enum
{
    PRE_FILLING,
    FILLING,
    POST_FILLING
} FillingState_t;

static FillingState_t fillingState = PRE_FILLING;

uint8_t PreFillingCheck(unsigned long delta)
{
    // Before we start filling, the result is always satisfactory, as we haven't started yet.
    return 1;
}

uint8_t FillingCheck(unsigned long delta, float actualLevel, float previousLevel)
{
    return (actualLevel > previousLevel && actualLevel > 0.0f) ? 1 : 0;
}

uint8_t PostFillingCheck(unsigned long delta, float actualLevel, float desiredLevel)
{
    return (actualLevel >= desiredLevel) ? 1 : 0;
}

uint8_t VerifyGlassFilling(unsigned long cycleTime, float actualLevel, float desiredLevel, float tapOpening, float previousLevel)
{
    switch (fillingState)
    {
    case PRE_FILLING:
        if (tapOpening > 0.0f)
        {
            fillingState = FILLING;
        }
        else
            return PreFillingCheck(cycleTime);
    case FILLING:
        if (tapOpening <= 0.0f)
        {
            fillingState = POST_FILLING;
        }
        else
            return FillingCheck(cycleTime, actualLevel, previousLevel);
    case POST_FILLING:
        return PostFillingCheck(cycleTime, actualLevel, desiredLevel);
    default:
        return 0;
    }
}

Now we can use the CppModel.StepResult interface in our simulation code to capture the verification test's status at every point in time. I have also added a previousLevel variable to track the level from the previous step, which is used to check whether the level is increasing during the filling state. Here is how the RunCyclic function looks with the added verification logic:

void RunCyclic(CModelSimulation_ts *ctx, unsigned long cycleTime)
{
    float dt = ctx->stepTime_ms / 1000.0f; // Convert milliseconds to seconds

    float plumbingFlow = CppModel_getParameterF32(ctx, "plumbingFlow [l/min]", 15.0f) / 60.0f;   // Default plumbing flow is 15 liters per minute converted to liters per second
    float glassCapacity = CppModel_getParameterF32(ctx, "glassCapacity [ml]", 250.0f) / 1000.0f; // Default glass capacity is 250 ml converted to liters
    float openingSlope = CppModel_getParameterF32(ctx, "openingSlope [%/s]", 100.0f) * 0.01f;    // Default opening slope is 100% per second converted to a fraction
    float closingSlope = CppModel_getParameterF32(ctx, "closingSlope [%/s]", 400.0f) * 0.01f;    // Default closing slope is 400% per second converted to a fraction

    float desiredLevel = CppModel_getInputF32(ctx, "desiredLevel [0.01%]", 80.0f * 0.01f); // Default desired level is 80%

    // Control loop
    float error = desiredLevel - actualLevel;
    tapOpening = control(dt, openingSlope, closingSlope, tapOpening, error);
    actualFlow = actuator(plumbingFlow, tapOpening);
    actualVolume = glass(dt, glassCapacity, actualVolume, actualFlow);
    actualLevel = sensor(glassCapacity, actualVolume);

    CppModel_setOutputF32(ctx, "error [0.01%]", error);
    CppModel_setOutputF32(ctx, "tapOpening [0.01%]", tapOpening);
    CppModel_setOutputF32(ctx, "actualFlow [l/s]", actualFlow);
    CppModel_setOutputF32(ctx, "actualVolume [l]", actualVolume);
    CppModel_setOutputF32(ctx, "actualLevel [0.01%]", actualLevel);

    uint8_t stepResult = VerifyGlassFilling(cycleTime, actualLevel, desiredLevel, tapOpening);
    CppModel_setOutputI8(ctx, "CppModel.StepResult", stepResult);
}

As you may have guessed, the simulation was expected to fail in the post-filling state, since the actual level won't exactly equal the desired level once we account for the closing slope on the tap opening — in this case we significantly overshoot the desired level.

The overall test result is shown as a failure in the terminal where the executable ran — in my case, a red circle with a cross in it. That's the signal our CI workflow will use to determine pass or fail. Here is what the terminal output looks like when the simulation fails:

In real life, nobody complains about a few extra drops of water in the glass, so let's relax the post-filling check to consider the simulation successful if the actual level is equal to or greater than the desired level. This way, the simulation will pass in the post-filling state too.

    return (actualLevel >= desiredLevel) ? 1 : 0;

Here are the simulation results after the modification:

And just for completeness, here is what the terminal output looks like when the simulation passes (a blue dot in my case):

Integrating with GitHub Actions​

Before we jump into the workflow implementation, let's make sure our simulation won't try to run interactively and prompt for credentials. To do this, we'll store the credentials as GitHub secrets and pass them to the simulation as environment variables, keeping them secure while letting the simulation run non-interactively. By default, CppModel checks whether the CPPMODEL_USERNAME and CPPMODEL_PASSWORD environment variables are set and uses them to authenticate with the CppModel server. If they aren't set, the simulation falls back to interactive mode and prompts for credentials.

Next, we'll create a GitHub Actions workflow that runs our simulation and checks the results. If the CppModel credentials are set, the workflow will automatically submit the results to the CppModel workspace, where they can be observed and analyzed. Since we're focused on simulation-based CI and expect to see those results, we'll add a credential check to the workflow so it fails outright if the credentials aren't set.

      - name: Verify CppModel credentials are set
        env:
          CPPMODEL_USERNAME: ${{ secrets.CPPMODEL_USERNAME }}
          CPPMODEL_PASSWORD: ${{ secrets.CPPMODEL_PASSWORD }}
        run: |
          if [ -z "$CPPMODEL_USERNAME" ] || [ -z "$CPPMODEL_PASSWORD" ]; then
            echo "::error::CPPMODEL_USERNAME and CPPMODEL_PASSWORD secrets must be configured for this workflow"
            exit 1
          fi

The next step is to prepare the build environment. For this example we use the gcc16 container image, to which we additionally add git (required for the checkout action) and curl (to download and install the CppModel libraries). For CMake, we'll use the lukka/get-cmake action to install the latest version of CMake and Ninja. Here is how the build environment setup looks:

      - name: Install dependencies
        run: apt-get update && apt-get install -y git curl zlib1g-dev libssl-dev
      - name: Get latest CMake and ninja
        uses: lukka/get-cmake@v3.27.7

Downloading and installing the CppModel libraries is straightforward: we use curl to grab the latest release and extract it into the ./dependencies directory, matching what the CMakeLists.txt configuration expects. Here is how that step looks:

      - name: Download and extract CppModel libraries
        run: |
          curl -fsSL https://download.cppmodel.com/CppModel-latest-Linux-gcc16.tar.gz -o cppmodel.tar.gz
          mkdir -p dependencies
          tar -xzf cppmodel.tar.gz -C dependencies --strip-components=1
          rm cppmodel.tar.gz

The final part of the workflow builds and runs the simulation. We'll also add a timeout to this step in case the credentials are wrong or the simulation gets stuck.

      - name: Run CMake
        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
      - name: Build
        run: cmake --build build --config RelWithDebInfo --target all
      - name: Test
        timeout-minutes: 5
        working-directory: build
        env:
          CPPMODEL_USERNAME: ${{ secrets.CPPMODEL_USERNAME }}
          CPPMODEL_PASSWORD: ${{ secrets.CPPMODEL_PASSWORD }}
        run: ctest --output-on-failure

Note that the CPPMODEL_USERNAME and CPPMODEL_PASSWORD secrets need to be set in your GitHub repository for this workflow to run: go to Settings > Secrets and variables > Actions > New repository secret and add both.

All that's left is to commit the workflow file and push it to GitHub. Once triggered, the workflow runs the simulation and checks the results: if the simulation fails, the workflow fails and you're notified. If it succeeds, you can view the results under the corresponding user in the CppModel workspace, just as we did earlier.

Here is how the workflow looks in GitHub Actions:

Final Thoughts​

Bringing simulation into CI closes a real gap in how process-based code typically gets tested. A conventional unit test tells you a function returned the right value; it doesn't tell you whether your control loop overshoots, oscillates, or settles cleanly over time. By running the actual model as the test and capturing CppModel.StepResult at every step, you get that dynamic, time-resolved picture for free, in the same pipeline that already gates your merges.

The Glass of Water example is deliberately simple, but the pattern holds for anything process-based: define the states your system moves through, decide what "correct" means in each one, and let the simulation tell you when reality drifts from that definition. The state-machine approach we used here only checks pass/fail per phase — it doesn't yet look at how a value evolves against a reference trajectory, which is often where the more interesting bugs hide, like quantization-induced oscillation, which capturing CppModel.StepResult at every step already puts you in a position to catch.

The bigger win in this approach is structural: simulation results are no longer something you eyeball locally and forget. They run on every push, fail the build when the system misbehaves, and land in the CppModel workspace where the whole team can inspect them.

If you try wiring this into a process-based project of your own — or think the pass/fail checks should be structured differently — I'd love to hear about it. Reach out or leave a comment below.

Links​

• Simulation code

Take a glass, open the tap, and when the water level is high enough, close the tap. It sounds simple. It feels simple. Yet if we try to explain this process precisely enough for a machine to do it automatically, it turns out to have real structure underneath — the same structure engineers use to control much bigger things, like a thermostat keeping a room at the right temperature or a cruise control keeping a car at the right speed.

The glass itself​

Let's start with the thing being controlled — the glass. In engineering, we'd call this "the plant," but really it's just whatever we're trying to influence.

The idea is simple: the more water flows in, the fuller the glass gets, until it's full — after that, no matter how much more water flows, the glass doesn't get any fuller (it just overflows). So the glass's behavior can be described as a simple rule: given how much water is flowing in, and how full the glass already is, figure out how full it will be a moment later.

Written as a function, that rule looks like this:

volume = glass(capacity, filledVolume, waterFlow)

Breaking this into the four parts we'll use consistently throughout this post:

Settings, decided ahead of time and fixed while the process runs:

• capacity — the size of the glass

State, what the process remembers from one check to the next:

• filledVolume — how full the glass currently is

Input, what changes moment to moment from outside the process:

• waterFlow — how fast water is pouring in right now

Output, the result handed back:

• volume — the new fill level, after this moment's flow has had a chance to add water; this becomes the State going into the next check

Since a computer checks on things at discrete moments in time rather than continuously, we also need to say how much time has passed since the last check, dt:

volume = glass(dt, capacity, filledVolume, waterFlow)

And here's what that looks like as actual code — you don't need to be a programmer to follow the gist: add the water that flowed in during this brief moment, then cap the result at the glass's capacity so it doesn't "overflow" mathematically:

float glass(float dt, float capacity, float filledVolume, float waterFlow)
{
    float deltaVolume = waterFlow * dt;
    filledVolume += deltaVolume;
    if (filledVolume > capacity)
    {
        filledVolume = capacity;
    }
    return filledVolume;
}

Now that we have a model of the glass, we can simulate it with different steady flows. Here I fill a 250 ml glass three times, with the tap running at 5, 10, and then 10 liters per minute. Here's how each fill plays out over time:

Unsurprisingly, each run is a straight line climbing up to the glass's capacity, with a steeper slope for a faster flow. If you tried pouring at different, changing speeds — the way you probably experimented as a kid — you'd get more interesting, curvier lines. That's actually a common way engineers test a system: run it under different conditions and watch what happens.

This little piece of code is about as small as a model gets, and it happens to be written in the same programming language (C) that's often used for the real control logic driving mobile or even industrial machines. The same code would run just as well on a hobbyist kit like an Arduino or Raspberry Pi.

The controller: deciding how far to open the tap​

The controller is the part that decides what to do next. It looks at the gap between "how full we want the glass to be" and "how full it actually is" (we'll call that gap the error), and decides how far open the tap valve should be, as a percentage.

Think about how you actually do this by hand: when you start filling a glass, you open the tap a little, then gradually more, to avoid splashing — and as you get close to the level you want, you start closing it, finishing with a firm close right at the target. Often you close much faster than you opened: spilling is a concern with the first drops of water, not the last, so once you're near the target there's no need to stay gentle. In engineering terms, this is a controller whose behavior is different depending on whether it's opening or closing — a very ordinary thing for real controllers to do.

Here's the shape of that idea, again as a function:

opening = control(openingSlope, closingSlope, actualOpening, error)

Breaking this into the same four parts:

Settings, decided ahead of time:

• openingSlope — how quickly the valve opens, in percent per second
• closingSlope — how quickly the valve closes, in percent per second

State, what the controller remembers between checks:

• actualOpening — how far open the valve currently is

Input, what changes moment to moment:

• error — the gap between the desired and actual water level

Output, the result handed back:

• opening — the updated valve position; here it's the same value as the State above, since the valve position is both what the controller needs to remember and what it reports back to the rest of the system

Turning this into code, the controller nudges the valve open a bit if the glass isn't full enough yet, or closed a bit if it's gone past the target — always keeping the valve position between fully closed (0%) and fully open (100%):

float control(float dt, float openingSlope, float closingSlope, float actualOpening, float error)
{
    if (error > 0) // we need to open the tap
    {
        actualOpening += openingSlope * dt;
        if (actualOpening > 1.0) // limit to 100%
        {
            actualOpening = 1.0;
        }
    }
    else if (error < 0) // we need to close the tap
    {
        actualOpening -= closingSlope * dt; // error is negative, so this will decrease actualOpening
        if (actualOpening < 0.0)            // limit to 0%
        {
            actualOpening = 0.0;
        }
    }
    return actualOpening;
}

To check that this behaves sensibly, I simulated a 2-second burst where the error is pinned at 100% (as if the glass were completely empty and we wanted it completely full), using:

• opening speed: 100% per second
• closing speed: 200% per second

Here's the result:

With both pieces defined — the glass and the controller — we can connect them into a complete, self-correcting loop: the controller looks at the gap between the desired and actual level and adjusts the valve; the valve's opening determines the flow rate; and that flow rate is what fills the glass.

The go-betweens: sensor and actuator​

Two more small pieces connect the controller to the glass: a sensor and an actuator. They're not part of the "thinking" — they just translate between units.

The sensor converts the glass's water volume into a fill percentage (relative to its capacity) — like your eyes glancing at the glass and judging "it's about 80% full." The actuator converts a desired valve-opening percentage into an actual flow rate — like your hand turning the tap. In real life, sensors and actuators have their own quirks and delays, but for this example we'll treat them as perfect.

Fitting these into the same four parts, both are simpler than the glass or the controller: neither needs State, since neither has to remember anything between checks — each just turns its Input into an Output using a fixed Setting:

• sensor — Settings: capacity; Input: filledVolume; Output: fill percentage
• actuator — Settings: maxFlow; Input: valveOpening; Output: flow rate

Here's what they look like in code — each is just a one-line conversion:

float sensor(float capacity, float filledVolume)
{
    return filledVolume / capacity;
}

float actuator(float maxFlow, float valveOpening)
{
    return maxFlow * valveOpening;
}

Putting it all together​

Before wiring everything up, let's be clear about the goal: when you walk up to the tap, your intention is usually to fill the glass to some target, say 80% full. That target is called the setpoint.

In real life, your eyes are the sensor, judging the fill level, and your hand is the actuator, opening and closing the valve to some flow rate between zero and the maximum the plumbing can deliver. You probably don't think about that maximum flow much, but it's usually enough to fill a small glass in about a second — here I'll use 15 liters per minute. Put together, the controller's job is: look at the gap between the desired and actual level, and output how far open the valve should be. Here's what that whole system looks like as a block diagram:

I simulated this full system aiming for 80% full, with:

• Glass capacity: 250 ml
• Opening speed: 100% per second
• Closing speed: 400% per second
• Maximum tap flow: 15 liters per minute

With the rest of the functions already sitting in a file called GlassOfWaterLib.c (and its header, GlassOfWaterLib.h), here's the simulation code that wires them together using the CppModel framework — all in under 50 lines:

#include "GlassOfWaterLib.h"

#include "cppmodel/CModel.h"

float tapOpening = 0.0f;
float actualVolume = 0.0f;
float actualLevel = 0.0f;
float actualFlow = 0.0f;

void RunCyclic(CModelSimulation_ts *ctx, unsigned long cycleTime)
{
    float dt = ctx->stepTime_ms / 1000.0f; // Convert milliseconds to seconds

    float plumbingFlow = CppModel_getParameterF32(ctx, "plumbingFlow [l/min]", 15.0f) / 60.0f;   // Default plumbing flow is 15 liters per minute converted to liters per second
    float glassCapacity = CppModel_getParameterF32(ctx, "glassCapacity [ml]", 250.0f) / 1000.0f; // Default glass capacity is 250 ml converted to liters
    float openingSlope = CppModel_getParameterF32(ctx, "openingSlope [%/s]", 100.0f) * 0.01f;    // Default opening slope is 100% per second converted to a fraction
    float closingSlope = CppModel_getParameterF32(ctx, "closingSlope [%/s]", 400.0f) * 0.01f;    // Default closing slope is 400% per second converted to a fraction

    float desiredLevel = CppModel_getInputF32(ctx, "desiredLevel [0.01%]", 80.0f * 0.01f); // Default desired level is 80%

    // Control loop
    float error = desiredLevel - actualLevel;
    tapOpening = control(dt, openingSlope, closingSlope, tapOpening, error);
    actualFlow = actuator(plumbingFlow, tapOpening);
    actualVolume = glass(dt, glassCapacity, actualVolume, actualFlow);
    actualLevel = sensor(glassCapacity, actualVolume);

    CppModel_setOutputF32(ctx, "error [0.01%]", error);
    CppModel_setOutputF32(ctx, "tapOpening [0.01%]", tapOpening);
    CppModel_setOutputF32(ctx, "actualFlow [l/s]", actualFlow);
    CppModel_setOutputF32(ctx, "actualVolume [l]", actualVolume);
    CppModel_setOutputF32(ctx, "actualLevel [0.01%]", actualLevel);
}

int main()
{
    CModelSimulation_ts *sim = CppModel_create("Glass of Water", 2000, 10);

    CppModel_setRunStepFunction(sim, RunCyclic);

    CppModel_Simulate(sim);

    int result = CppModel_getSimulationResult(sim);

    return result;
}

Here's how it behaves over time:

You can see the glass filling as soon as the tap opens, and as it nears the 80% target, the tap starts closing. Because it closes faster than it opened, the system still slightly overshoots the target before settling. Tuning those opening and closing speeds can reduce that overshoot and make the fill smoother.

Final notes​

I chose to simulate this entire system directly in a general-purpose programming language, without any specialized physics or simulation software, to show just how little machinery is needed to model and test a real process — even one as ordinary as filling a glass. The same approach scales up to far more complex systems; the underlying ideas don't change. By understanding how the thing you're controlling behaves, and designing a controller that responds sensibly to it, you can get useful, predictable behavior out of all kinds of automated systems.

Keeping the simulation this lightweight also means it can double as the real production code and be run automatically as part of a software testing pipeline. And as AI tools become part of more engineering workflows, keeping the simulation and the real control logic written in the same language makes it easier to bring those tools to bear on implementing and improving the system.

If you enjoyed this and want to run your own simulations, please consider subscribing to one of our plans. I've prepared an archive with the code and data used in this post, ready to run all the simulations in this article. I'll be continuing this series with more processes and control systems, so let me know your thoughts — or how you'd have approached this differently.

Links​

• Simulation code