Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 9 additions & 29 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,46 +6,26 @@ Rust framework for numerical problem solving. See README.md for usage examples.

- **twine-core** (`crates/core`): Shared traits and types
- **twine-solvers** (`crates/solvers`): Solver implementations, organized by problem type
- **twine-observers** (`crates/observers`): Reusable `Observer` implementations

## Core Abstraction

```
Model::call(input) -> output
Problem::input(x) -> model_input
Problem::residuals|objective(input, output) -> metric
Solver::solve(model, problem, bracket, config, observer) -> Solution
```
Three problem types: equation (root-finding), optimization, and ODE. All follow the same pattern:

Solvers are generic over Model and Problem. Problems adapt solver variables (`x: [f64; N]`)
to model inputs and extract metrics from outputs.
- `Model::call(input) -> Result<output, error>`
- `Problem::input(x) -> model_input` — maps solver variables to model input
- `Problem` extracts a metric from input/output (residuals, objective, or derivative)

## Observer Pattern

Solvers emit events; observers optionally return actions.

```rust
trait Observer<Event, Action> {
fn observe(&mut self, event: &Event) -> Option<Action>;
}
Solvers are generic over `Model` and `Problem`.

impl<E, A> Observer<E, A> for () {
fn observe(&mut self, _: &E) -> Option<A> { None }
}
```
## Observer Pattern

Events expose solver state (current point, bracket, errors).
Actions steer behavior (stop early, assume sign/worse for recovery).
`Observer<E, A>` is defined in `twine-core`. Closures and `()` both implement it — `()` is the no-op observer. Solvers emit events; observers optionally return actions to steer behavior (stop early, assume worse, etc.).

## Solver Conventions

- Public functions: `solve`/`minimize`/`maximize` with observer, `*_unobserved` without
- Module structure: one file per concern (bracket, config, event, action, solution, error)
- Public API: `solve`/`minimize`/`maximize` (with observer) and `*_unobserved` variants
- Config validation at entry, not per-iteration
- `Solution` contains: status, solver variable, objective/residual, snapshot (input+output), iters

## Workflow notes

Feature branches may include temporary workflow docs (e.g. TODO.md). Do not merge them to main.

## Testing

Expand Down