Metadata-Version: 2.4
Name: regelum
Version: 0.3.11
Summary: Add your description here
Author-email: Anton Bolychev <bolychev.anthon@yandex.ru>
Requires-Python: >=3.13
Requires-Dist: casadi>=3.7.2
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: numpy>=2.3.0
Requires-Dist: scienceplots>=2.1.1
Requires-Dist: scipy>=1.17.1
Requires-Dist: z3-solver>=4.16.0.0
Description-Content-Type: text/markdown

<p align="center">
  <img
    src="https://raw.githubusercontent.com/aidagroup/regelum/main/docs/assets/logo/logo_big.png"
    alt="regelum"
    width="360"
  >
</p>

<p align="center">
  <a href="https://aidagroup.github.io/regelum/">
    <img alt="docs" src="https://img.shields.io/badge/docs-mkdocs%20material-526CFE?logo=materialformkdocs&logoColor=white">
  </a>
  <img alt="tests" src="https://img.shields.io/badge/tests-pytest-0A9EDC?logo=pytest&logoColor=white">
  <img alt="python" src="https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white">
  <img alt="uv" src="https://img.shields.io/badge/managed%20with-uv-6A5ACD">
</p>

# 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](https://fastapi.tiangolo.com/),
[Typer](https://typer.tiangolo.com/), [Pydantic](https://docs.pydantic.dev/),
[SQLModel](https://sqlmodel.tiangolo.com/), [SQLAlchemy](https://www.sqlalchemy.org/),
and [FastStream](https://faststream.ag2.ai/latest/). 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

```python
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`.

```bash
uv add regelum
```

For local development from this repository:

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

## Examples

```bash
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:

```python
import regelum

print(regelum.__version__)
```
