trellis_runner/lib.rs
1//! # Trellis
2//!
3//! Trellis is a generic, event-driven numerical engine for iterative procedures.
4//!
5//! It provides a structured execution environment for algorithms that evolve a state over time,
6//! producing progress signals, convergence diagnostics, and termination conditions.
7//!
8//! # Policies
9//!
10//! Policies control solver execution.
11//!
12//! During a run, the engine collects progress information from the procedure and
13//! passes it to one or more policies. Policies inspect this information and
14//! decide whether the solver should:
15//!
16//! - continue running,
17//! - terminate successfully,
18//! - terminate early,
19//! - or request some other engine action.
20//!
21//! Policies are the primary mechanism used to implement convergence criteria,
22//! iteration limits, stagnation detection and timeout handling.
23//!
24//! ## Policies vs Observers
25//!
26//! Policies influence solver behaviour.
27//!
28//! Observers only observe solver behaviour.
29//!
30//! A policy may terminate a calculation. An observer may not.
31//!
32//! ```text
33//! Progress ──► Policy ──► Engine Action
34//! │
35//! └────► Observer
36//! ```
37//!
38//! ## Attaching Policies
39//!
40//! Policies are attached through the builder.
41//!
42//! ```rust
43//! use trellis_runner::{CancellationGuard, MaxIterationPolicy, StagnationPolicy, GenerateBuilder};
44//!
45//! struct MyProcedure;
46//! struct MyProblem;
47//! struct MyState;
48//!
49//! impl trellis_runner::Procedure<MyProblem> for MyProcedure {
50//! const NAME: &'static str = "My Procedure";
51//! type State = MyState;
52//! type Output = ();
53//!
54//! fn step(
55//! &self,
56//! _: &mut MyProblem,
57//! _: &mut Self::State,
58//! _guard: CancellationGuard<'_>,
59//! ) {
60//! ()
61//! }
62//!
63//! fn finalise(&self, _: &mut MyProblem, _: &Self::State) {}
64//! }
65//!
66//!
67//! impl trellis_runner::UserState for MyState {
68//! type Float = f64;
69//!
70//! fn progress(&self) -> trellis_runner::Progress<f64> {
71//! trellis_runner::Progress::Complete
72//! }
73//! }
74//!
75//! let engine = MyProcedure
76//! .build_for(MyProblem)
77//! .with_initial_state(MyState)
78//! .and_policy(MaxIterationPolicy::new(10_000))
79//! .and_policy(StagnationPolicy::new(10))
80//! .finalise();
81//! ```
82//!
83//! Multiple policies may be attached.
84//!
85//! The engine stops as soon as any policy requests termination.
86//!
87//! ## Built-in Policies
88//!
89//! Trellis provides several commonly useful policies.
90//!
91//! | Policy | Purpose |
92//! |---------|----------|
93//! | `MaxIterationPolicy` | Stop the engine after a fixed number of iterations |
94//! | `TimeoutPolicy` | Stops the engine after a maximum wall-clock duration |
95//! | `AbsoluteTolerancePolicy` | Stops the engine when the mean absolute error over a rolling window falls below a user-defined tolerance|
96//! | `RelativeTolerancePolicy` | Stops the engine when the mean relative error over a rolling window falls below a user-defined tolerance|
97//! | `StagnationPolicy` | Stops the engine when the improvement of the best observed value over a rolling window falls below a relative tolerance threshold |
98//! | `NoProgressPolicy` | Stops the engine when the best observed objective value fails to improve by a relative tolerance for a specified number of consecutive iterations |
99//! | `TargetValuePolicy` | Stops the engine when the mean absolute distance to a target value remains below a specified tolerance over a rolling window |
100//! | `CheckpointPolicy` | Define frequency of checkpoint generation |
101#![allow(dead_code)]
102
103mod procedure;
104
105mod engine;
106mod progress;
107mod result;
108mod watchers;
109
110mod state;
111
112pub(crate) use procedure::Infallible;
113
114pub use procedure::{FallibleProcedure, Procedure};
115
116pub use engine::{
117 AbsoluteTolerancePolicy, CancellationGuard, CheckpointPolicy, EngineFailure, GenerateBuilder,
118 GenerateBuilderFallible, InMemoryCheckpointStore, MaxIterationPolicy, NoProgressPolicy,
119 RelativeTolerancePolicy, StagnationPolicy, TargetValuePolicy, Termination, TimeoutPolicy,
120};
121
122#[cfg(feature = "writing")]
123pub use engine::JsonCheckpointStore;
124
125pub use result::{EngineOutput, EngineOutputWithSnapshot, RunSummary, TrellisError};
126
127pub use state::{Snapshotable, State, StateRestorer, UserState};
128
129pub use progress::{Progress, ProgressDiagnostics};
130
131pub use watchers::{Frequency, Observe, Tracer};
132
133#[cfg(feature = "writing")]
134pub use watchers::CsvProgressWriter;
135
136#[cfg(feature = "plotting")]
137pub use watchers::PlotObserver;
138
139pub trait TrellisFloat: std::fmt::Display + std::fmt::Debug + num_traits::float::FloatCore {}
140
141impl TrellisFloat for f32 {}
142impl TrellisFloat for f64 {}