YourSimulation Engine

Appearance

Engine API & CLI ​

@plantagoai/yoursim-engine is a zero-dependency TypeScript discrete-event simulation engine. Everything the hosted app computes — KPIs, percentiles, optimization, event traces — is in this package and runs headless.

Install ​

bash
npm install @plantagoai/yoursim-engine

Or clone this repo and run from source with tsx (no build step needed).

Library API ​

ts
import {
  buildSimulation,
  runExperiment,
  optimize,
  recordRun,
  type SimModel,
} from '@plantagoai/yoursim-engine';

buildSimulation(model, seed, emit?) → BuiltSimulation ​

Validates the model graph and constructs a runnable simulation. Throws on an invalid model (see the Blocks reference validation rules). BuiltSimulation exposes run(until), resetStats(), summaries(), nodes, and pools.

runExperiment(model, settings, onProgress?, options?) → ExperimentResult ​

Runs independent replications and returns each node's metrics as { mean, ci95 } (95% confidence interval). With options.detailed, it also returns percentiles (p50/p90/p95), histograms, and bucketed time-series.

ts
const r = runExperiment(model, { horizon: 480, warmup: 60, replications: 30, seed: 42 });
console.log(r.nodes['desk'].utilization.mean); // e.g. 0.79 ± 0.01

settings: { horizon, warmup, replications, seed } — horizon is total run length (includes warm-up); stats before warmup are discarded; replications independent runs are averaged; seed is the base RNG seed.

optimize(model, problem, settings, options?, ceSeed?, onProgress?) → OptimizeResult ​

The Cross-Entropy optimizer: searches integer design variables (server counts, queue capacities) for the cheapest configuration that meets your service constraints, evaluating each candidate by simulation with common random numbers. problem declares variables (node param, min/max, cost-per-unit) and constraints (node metric, soft/hard thresholds). See Cross-Entropy.

recordRun(model, settings) → RunRecording ​

Produces a deterministic event trace (arrival / move / depart / server / queue events) — the stream the app's watch-mode animation plays back.

CLI ​

From a clone of this repo:

bash
# validate the model graph (exit 1 + {ok:false, issues:[…]} on failure)
npx tsx packages/engine/src/cli.ts validate examples/bank.json

# run → KPIs JSON (add --pretty)
npx tsx packages/engine/src/cli.ts run examples/bank.json --pretty

# optimize parameters against a problem.json
npx tsx packages/engine/src/cli.ts optimize examples/airport.json problem.json --pretty

# record an event trace of one run
npx tsx packages/engine/src/cli.ts record examples/restaurant.json

A model path may be - to read from stdin (pipe a generator's output straight in). Settings come from the model's settings block, or override with --horizon N --warmup N --replications N --seed N.

Determinism ​

Every stochastic draw uses a per-node seeded RNG stream derived from seed, so runs are reproducible and the optimizer compares candidates under common random numbers. The engine is validated against closed-form queueing theory — see Queueing theory.

Next ​