CppModel for Python

Write CppModel simulations in Python. Every run fetches the inputs and parameters posted for it in your CppModel workspace and submits its execution there, just like a C or C++ simulation built with the CppModel SDK.

pip install cppmodel

Wheels are available for Linux (x86_64 and aarch64, glibc 2.28+), Windows (x64 and ARM64) and macOS 11+ (Apple silicon and Intel), for Python 3.9 and later. Each wheel contains the CppModel library, so nothing else needs installing.

A simulation

import sys
import cppmodel


class Heater(cppmodel.Simulation):
    def init(self):
        self.temperature = 20.0

    def step(self, time_ms):
        setpoint = self.inputs.get("Setpoint", 22.0)        # input, with its fallback
        gain = self.parameters.get("HeaterGain", 0.05)      # parameter, with its fallback

        heater_on = self.temperature < setpoint             # the controller under test
        self.temperature += gain if heater_on else -0.01

        self.outputs["Temperature"] = self.temperature
        self.outputs["HeaterOn"] = heater_on
        self.outputs["CppModel.Step"] = time_ms
        self.outputs["CppModel.StepResult"] = self.temperature < setpoint + 1.0


with Heater("Example - Heater (Python)", total_time_ms=60_000, step_ms=100) as simulation:
    sys.exit(simulation.run())

run() fetches the pending inputs and parameters, calls init(), then step(time_ms) for every step from 0 to total_time_ms, then finalize(), and submits the execution. It returns 0 when every step passed, otherwise the CppModel.Step of the first step whose CppModel.StepResult was 0.

An exception raised in init(), step() or finalize() (Ctrl-C included) aborts the run, submits nothing and is re-raised by run().

Instead of subclassing, you can pass functions that take the simulation as their first argument:

def ramp(sim, time_ms):
    sim.outputs["Ramp"] = time_ms

sim = cppmodel.Simulation("Ramp", total_time_ms=1000, step_ms=100, step=ramp)
sim.run()

Inputs, outputs and parameters

Inputs and outputs are numbers. Parameters keep their JSON type: numbers, bools, strings, lists, dicts and None. All three support in, len(), iteration and keys().

Workspace access

A run needs to sign in to your workspace:

• Scripts, CI: set CPPMODEL_USERNAME and CPPMODEL_PASSWORD.
• Without the workspace: create the simulation with offline=True. Nothing is fetched or submitted.

Without credentials, the first run prints a sign-in link and waits until you've signed in. The link goes to the process's standard output, which Jupyter doesn't show, so use credentials in notebooks.

Fingerprint

Each execution records a CppModel.BinaryFingerprint of the simulation's code, so the workspace can tell runs of the same code from runs of changed code. It is the fingerprint of the file your Simulation subclass (or step function) is defined in. Set sim.fingerprint_file to use another file.

Errors

A failing library call raises cppmodel.CppModelError; its status is a cppmodel.Status.

License

The CppModel library is proprietary software of Control Edge AB, used under the CppModel Terms of Service; see LICENSE. The package also contains third-party components under their own licenses, in licenses/.