regelum 0.3.12

Add your description here

regelum

regelum is a framework for designing and simulating dynamic systems, feedback loops, DAGs, and dataflows as Phased Reactive Systems (PRS). A PRS has two levels of abstraction: low-level computational primitives called nodes, and high-level execution stages called phases. Nodes declare Inputs for values read from other nodes or system sources and State for values they own and publish; phases group node instances into executable slices, resolve their dependency graph, and move execution through explicit transitions. These transitions can be unconditional or conditional, so execution can branch to different phases depending on current system state.

The API is intentionally built from Python's own language features: type annotations, nested classes, descriptors, declarative function signatures, operator overloading, and ordinary Python objects. It is inspired by frameworks such as FastAPI, Typer, Pydantic, SQLModel, SQLAlchemy, and FastStream. The goal is to make system models look like regular Python while still giving the compiler enough structure to resolve dependencies, validate the graph, schedule execution, and integrate continuous dynamics.

The best entry point is the Learn overview:

• Docs: https://aidagroup.github.io/regelum/
• Learn overview: https://aidagroup.github.io/regelum/concepts/

Quick Example

import regelum as rg


class TemperatureSensor(rg.Node):
    class State(rg.NodeState):
        temperature: float = rg.var(init=19.0)

    def update(self) -> State:
        return self.State(temperature=21.5)


class HeaterController(rg.Node):
    class Inputs(rg.NodeInputs):
        temperature: float = rg.src(TemperatureSensor.State.temperature)

    class State(rg.NodeState):
        heater_on: bool

    def update(self, inputs: Inputs) -> State:
        return self.State(heater_on=inputs.temperature < 22.0)


class HeatingCycles(rg.Node):
    class Inputs(rg.NodeInputs):
        heater_on: bool = rg.src(HeaterController.State.heater_on)

    class State(rg.NodeState):
        count: int = rg.var(init=0)

    def update(self, inputs: Inputs, prev_state: State) -> State:
        return self.State(
            count=prev_state.count + int(inputs.heater_on),
        )


sensor = TemperatureSensor(name="room_sensor")
controller = HeaterController(name="heater_controller")
cycles = HeatingCycles(name="heating_cycles")

system = rg.PhasedReactiveSystem(
    phases=[
        rg.Phase(
            "control",
            nodes=(sensor, controller, cycles),
            transitions=(rg.Goto(rg.terminate),),
            is_initial=True,
        ),
    ],
)

system.step()
print(system.read(controller.State.heater_on))

Installation

Recommended: use uv.

uv add regelum

For local development from this repository:

uv sync --all-groups
uv run pytest tests
uv run mkdocs serve

Examples

uv run python examples/controlled_pendulum/standalone.py
uv run python examples/free_pendulum/standalone.py
uv run marimo edit examples/free_pendulum/rg-examples-free-pendulum.py
uv run marimo edit examples/controlled_pendulum/rg-examples-controlled-pendulum.py
uv run python examples/video_player/video_player.py
uv run python examples/instance_connect/instance_connect.py

Release Process

Create a GitHub Release tagged like v0.2.0. The publish workflow builds the package, derives the version from the tag, and uploads artifacts to PyPI.

After installation, users can verify the packaged version:

import regelum

print(regelum.__version__)