2026-08-17 13:40:09 +03:00

84 lines
2.7 KiB
Markdown

# Usage — external-simulator
The plugin implements the `SimulationPlugin` trait from
`lawsynth-plugin-api`:
```rust
pub trait SimulationPlugin: Send + Sync {
fn simulate(&self, request: SimulationRequest) -> Result<SimulationResponse, PluginError>;
}
```
## Constructing the simulator core
`LinearSimulator::new(matrix, bias, max_step)` builds an integrator for the
linear system `dx/dt = matrix · x + bias`:
```rust
use lawsynth_external_simulator::LinearSimulator;
// A damped harmonic oscillator: dx/dt = v, dv/dt = -x - 0.1 v
let simulator = LinearSimulator::new(
vec![vec![0.0, 1.0], vec![-1.0, -0.1]],
vec![0.0, 0.0],
0.01, // maximum Euler step
).unwrap();
```
Construction fails with `PluginError::InvalidData` if the matrix is not square,
the bias is empty, `max_step` is not finite and positive, or any parameter is
non-finite.
## Request / response contract
```rust
use lawsynth_plugin_api::{SimulationPlugin, SimulationRequest};
let request = SimulationRequest {
initial_state: vec![1.0, 0.0],
times: vec![0.0, 0.5, 1.0, 1.5, 2.0], // strictly increasing, finite
};
let response = simulator.simulate(request).unwrap();
// response.states[i] is the state vector at times[i].
```
The API validates both sides:
- `SimulationRequest::validate` — non-empty finite initial state, non-empty
finite strictly increasing times, and a point-count ceiling.
- `SimulationResponse::validate_for` — one state row per requested time, each
row the width of the initial state, and every value finite.
Divergence to a non-finite state during integration is reported as
`PluginError::InvalidData`.
## Running as an out-of-process worker
The manifest advertises `kind = "process"`. A worker binary wraps the core:
```text
loop {
read a length-delimited Frame from stdin
match frame.kind {
Hello => reply Hello (confirm protocol version 1)
Request => decode SimulationRequest, run simulator, reply Response/Error
Shutdown => drain and exit
}
}
```
Frame encode/decode is provided by `lawsynth_plugin_api::Frame`. The host owns
spawning, sandboxing, resource metering, and timeouts
(`crates/lawsynth-plugin-host` provides `ProcessSpec`/`ProcessHandle`). Payload
serialization inside a frame is agreed out of band — the API standardizes
framing and validation, not the wire format of the payload.
## Host integration
1. Discover and validate the manifest; confirm the `simulator` capability is
granted.
2. Spawn the entrypoint via the host's process module.
3. Drive the lifecycle to `Running`; dispatch `Request` frames.
4. Enforce `max_output_bytes` against `SimulationResponse` size — the API
provides `estimated_output_bytes` and `validate_for_with_limits` to help.