Evolution as syntax

This is what Flow exists for. When a system changes over time, write the rule it follows and let the compiler build the simulation.

Requires FLOW_HOST=python.

The form

flow Ball {
    state height      : f64 = 2.0     # m
    state velocity    : f64 = 0.0     # m/s
    param gravity     : f64 = 9.81    # m/s^2
    param restitution : f64 = 0.8

    height evolves as velocity
    velocity evolves as -gravity

    when height reaches 0.0 {
        velocity becomes -restitution * velocity
        height becomes 0.0
    }
}

• state is a value that changes and carries an initial condition.
• param is a constant of the model, held on the instance.
• x evolves as expr is the derivative of x.
• when guard reaches value { ... } is a discrete event.
• becomes assigns inside an event body.

Driving it

The compiler generates a constructor and a step function. The caller owns the instance and supplies dt.

function main() -> i32 {
    let dt: f64 = 0.001
    let mut ball: Ball = Ball_new()

    for k in 0 to 6000 {
        Ball_step(&ball, dt)
        if k % 500 == 0 {
            println(ball.height)
        }
    }
    return 0
}

Read state off the instance by field name: ball.height, ball.velocity.

FLOW_HOST=python flow run ball.flow

Semantics to state plainly

• Derivatives read the pre-step state. Continuous states advance together, so ordering inside the block does not create a dependency.
• Event assignments are staged and applied together. Both becomes lines above see the same pre-reset velocity.
• Zero crossing is detected at step granularity. The event fires at the end of the step in which the guard crossed. Event times carry O(dt) error. Say this whenever the timing matters, and shrink dt to show the error shrinking.
• The generated names X_new and X_step are part of the current lowering. Check docs/vision/north-star.md before assuming more.

Choosing a step size

Halve dt and rerun. If the answer moves, the step is too large. Report both runs. For a stiff system, say so and reach for a solver from lib/stdlib/dynamics/ rather than shrinking dt indefinitely.

When to hand-integrate instead

Write the loop yourself only when the point is to teach the lowering or to use a specialised numerical method the DSL does not cover. Compare the two:

• examples/evolution/bouncing_ball_evolves.flow is the declarative form.
• examples/evolution/bouncing_ball.flow solves the exact impact instant by hand and documents the difference.

Related library code

ls lib/stdlib/dynamics/
grep -rn --include='*.flow' "function dsys_" lib/stdlib/

lib/stdlib/dynamics/state_space.flow carries Matrix, DynamicalSystem, discretisation, controllability, Gramians, and similarity transforms. Use them for linear analysis and control design rather than writing matrix code inline.

import "stdlib/dynamics/state_space.flow"

let A: array<f64, 4> = [0.0, 1.0, -1.0, -0.3]
let B: array<f64, 2> = [0.0, 1.0]
let C: array<f64, 2> = [1.0, 0.0]
let sys: DynamicalSystem = dsys_continuous(2, 1, 1, 0.05,
    Matrix { data: A, rows: 2, cols: 2 },
    Matrix { data: B, rows: 2, cols: 1 },
    Matrix { data: C, rows: 1, cols: 2 })

Matrices are row-major fixed arrays with explicit rows and cols. Several routines take scratch arrays as arguments so they allocate nothing.

Worked examples to read first

ls examples/evolution/     # ball, pendulum, van der Pol, SIR, heat, traffic
ls examples/dynamics/      # controllability, Gramians, GA control, Lorenz
ls examples/circuits/      # RC, RLC, PLL, Chua, op-amp, transmission line
ls examples/morphogenesis/ # reaction diffusion, growth, pattern formation
ls examples/neuro/         # spiking neurons, networks

Verify the model, not the syntax

A simulation that runs is not a simulation that is right. Check at least one:

• a closed-form answer for a simplified case;
• a conserved quantity that should stay flat;
• a known qualitative behaviour, such as decaying bounce apexes or a limit cycle;
• agreement between two step sizes.

Put the check in main and return a distinct non-zero code per failure. That is how the shipped examples do it, and it makes the example a test.