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

2.7 KiB

Usage — external-simulator

The plugin implements the SimulationPlugin trait from lawsynth-plugin-api:

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:

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

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:

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.