Crate trellis_runner

Expand description

§Trellis

Trellis is a generic execution engine for iterative numerical algorithms.

Rather than implementing optimisation loops, integration loops or search loops directly, a procedure describes a single iteration of an algorithm while Trellis manages execution, convergence, termination, observation and checkpointing.

The library separates the concerns of:

algorithm implementation (Procedure)
problem definition (the problem supplied to the procedure)
algorithm state (UserState)
execution control (policies)
instrumentation (observers)

This separation allows algorithms to focus solely on their numerical method, while Trellis provides a reusable execution framework.

§Execution model

Every Trellis calculation follows the same execution model:

                Problem
                   │
                   ▼
             ┌───────────┐
             │ Procedure │
             └─────┬─────┘
                   │
             updates state
                   │
                   ▼
             ┌───────────┐
             │ UserState │
             └─────┬─────┘
                   │
           emits Progress events
                   │
        ┌──────────┴──────────┐
        ▼                     ▼
  Engine Policies        Observers
        │
        ▼
   Engine Actions

The principal abstractions are:

Problem — the specific problem instance being solved.
Procedure — performs a single iteration of the algorithm.
UserState — stores the evolving state of the computation and reports progress.
Policies — inspect progress and control execution.
Observers — inspect progress without affecting execution.

§A simple example

A calculation is configured using the builder returned by GenerateBuilder::build_for:

use trellis_runner::{
    GenerateBuilder, MaxIterationPolicy, RelativeTolerancePolicy,
    CancellationGuard, Procedure, Progress, UserState,
};

struct Problem;

#[derive(Default)]
struct State {
    value: f64,
}

impl UserState for State {
    type Float = f64;

    fn progress(&self) -> Progress<Self::Float> {
        Progress::Measure(self.value)
    }
}

struct Solver;

impl Procedure<Problem> for Solver {
    const NAME: &'static str = "Example";

    type State = State;
    type Output = ();

    fn step(
        &self,
        _: &mut Problem,
        _: &mut State,
        _: CancellationGuard<'_>,
    ) {}

    fn finalise(
        &self,
        _: &mut Problem,
        _: &State,
    ) {}
}
let engine = Solver
    .build_for(Problem)
    .with_initial_state(State::default())
    .and_policy(RelativeTolerancePolicy::new(1e-8, 10))
    .and_policy(MaxIterationPolicy::new(10_000))
    .finalise();

let result = engine.run();

The builder configures the execution environment rather than the numerical algorithm itself.

§Procedures

A Procedure implements the numerical algorithm.

Each call to step() performs a single iteration of the algorithm, while finalise() converts the final algorithm state into the value returned to the caller.

Both infallible and fallible procedures are supported.

§User state

UserState stores the evolving state of the computation.

In addition to algorithm-specific data, it reports progress to the engine via Progress, allowing policies and observers to monitor execution.

States implementing Snapshotable can additionally participate in checkpointing, allowing long-running computations to be resumed.

§Policies

Policies control solver execution.

During a run, the engine collects progress emitted by the procedure and passes it to one or more policies. Policies inspect this information and decide whether the solver should:

continue running,
terminate successfully,
terminate early,
request a checkpoint,
or perform another engine action.

Policies influence execution.

Observers do not.

Progress ──► Policy ──► Engine Action
           │
           └────► Observer

Multiple policies may be attached simultaneously.

The engine stops as soon as any policy requests termination.

Custom policies can be created implementing the EnginePolicy trait.

§Built-in policies

Policy	Description
`MaxIterationPolicy`	Stops after a fixed number of iterations.
`TimeoutPolicy`	Stops after a maximum wall-clock duration.
`AbsoluteTolerancePolicy`	Stops when the mean absolute error over a rolling window falls below a tolerance.
`RelativeTolerancePolicy`	Stops when the mean relative error over a rolling window falls below a tolerance.
`TargetValuePolicy`	Stops when the mean distance to a target value remains below a tolerance.
`NoProgressPolicy`	Stops when no meaningful improvement has been observed for a specified number of iterations.
`StagnationPolicy`	Stops when improvement over a rolling window falls below a relative threshold.
`CheckpointPolicy`	Requests periodic checkpoint generation.

§Observers

Observers receive every event emitted by the engine but never influence execution.

Typical applications include:

structured logging,
tracing,
CSV export,
plotting,
metrics collection,
progress reporting,
custom visualisation.

§Checkpointing

User states implementing Snapshotable may be checkpointed during execution.

Checkpoints may be requested by policies or generated manually, allowing interrupted computations to be resumed.

§Extending Trellis

Trellis is designed to be extended through traits.

Most applications only need to implement:

Procedure to define the numerical algorithm,
UserState to store algorithm state,
EnginePolicy for custom stopping criteria,
Observe for custom instrumentation.

These components compose naturally, allowing new algorithms, policies and observers to be combined without modifying the execution engine itself.

Structs§

AbsoluteTolerancePolicy
CancellationGuard
CancellationToken: A token which can be used to signal a cancellation request to one or more tasks.
CheckpointPolicy
EngineOutput: Result of a completed calculation.
EngineOutputWithSnapshot: Result of a completed calculation including a restart snapshot.
InMemoryCheckpointStore
MaxIterationPolicy
NoProgressPolicy
ProgressDiagnostics
RelativeTolerancePolicy
RunSummary: Summary information describing a completed engine run.
StagnationPolicy
State: Internal execution state of the solver.
TargetValuePolicy
TimeoutPolicy
Tracer: Structured tracing observer for engine execution.
TrellisError: Error returned when engine execution fails during procedure execution.

Enums§

EngineFailure
Frequency: Frequency control for observer execution.
Progress: Numerical signals emitted by a solver during execution.
Termination: Canonical reasons why a solver terminated.

Traits§

EnginePolicy
FallibleProcedure
GenerateBuilder
GenerateBuilderFallible
Observe: Core observer trait for the engine event system.
Procedure: Trait implemented by all problems solvable by Trellis
Snapshotable
StateRestorer
TrellisFloat
UserState: The user-defined state must implement this trait to be used as part of the trellis calculation loop