BioNetGen Playground

BioNetGen Playground is a browser-native modeling and simulation environment for BioNetGen (BNGL): build, simulate, analyze, and reproducibly share rule-based models from a URL — no installation, no server. models: edit BNGL, parse, generate networks, run simulations, and analyze results through multiple visualization and analysis tabs.

Live demo: https://ruleworld.github.io/bngplayground

Features

• BNGL editor + parser (client-side ANTLR4)
• Network generation and simulation in the browser (Web Worker + WASM)
• ODE Solvers: CVODE (SUNDIALS) for stiff ODEs, Rosenbrock23 with automatic fallback, RK4/RK45 for non-stiff systems
• Stochastic Solvers: SSA (Gillespie), PLA (partitioned leaping), PSA (hybrid ODE/SSA via Haseltine-Rawlings adaptive scaling)
• Network-Free Simulation: Integrated NFsim (WASM) for efficient simulation without network generation
• Large Network Support: Symmetry reduction using Nauty WASM for fast canonical labeling
• Multi-Compartment Support (cBNGL): Full support for compartmentalized models with molecule transport
• Visual Designer: Construct models using a structured visual interface
• What-If Comparison Mode: Run baseline vs modified-parameter simulations and compare trajectories in real-time
• Enhanced Example Gallery: 482 curated RuleHub models with semantic search across 426 embedded models (powered by TensorFlow.js)
• Interactive charts (series toggle / isolate, zoom, export)
• Analysis Modules: Parameter scan, dose-response, perturbation screen, linear noise approximation, first passage time, NFsim post-processing, identifiability (FIM), steady state, parameter estimation, flux analysis, verification
• Bayesian Inference: ABC-SMC parameter estimation with posterior predictive simulation and credible bands
• Provenance Recording: PROV-O JSON-LD export, RO-Crate packaging for reproducible workflows
• Hybrid UDE / Neural Rate Residuals: Universal differential equation support with neural network rate functions
• URL State Sharing: Compressed model sharing via pako-compressed URLs
• GPU-Accelerated Solvers: WebGPU ODE + SSA with CPU fallback for high-performance simulation
• Neural ODE Surrogates: TF.js-powered neural ODE approximations for fast inference
• Publication Figure Pipeline: Export figures with PLOS/Nature/Cell presets at 300 DPI
• CVODES Forward Sensitivity Analysis: Compute parameter sensitivities alongside ODE solutions
• Dynamic Contact Map: Interactive overlays with rule highlighting and animated simulations
• MCP Server: 44 tool endpoints for programmatic model analysis (parse, simulate, calibration, sensitivity, inference, verification, and multiscale workflows)

Quick Start

npm install
npm run build
npm run dev

MCP Client Installation

Cross-platform installation instructions for Claude Desktop, Claude Code, Codex, ChatGPT, Claude.ai, and Claude Cowork are in the MCP server guide.

MCP Capabilities Snapshot

The MCP package (packages/mcp-server) currently exposes 44 tools across:

• Core model lifecycle (parse, validate, network generation, simulation, parameter scans)
• Calibration workflows (parameter fitting, PEtab import, model reduction)
• Sensitivity and inference (Sobol analysis, identifiability, Bayesian inference, optimal experiment design)
• Intelligence assistance (model composition, editing, diagnosis, explanation)
• Advanced analysis and formal methods (verification, bifurcation, temporal information analysis, symbolic steady state, perturbation screening, dose-response, QSSA)
• Applied domains (PK/PD workflows and multiscale simulation)

For the authoritative tool list and schemas, see packages/mcp-server/README.md and packages/mcp-server/src/index.ts.

Scripts

Command	Description
npm run dev	Start the Vite dev server
npm run build	Production build (also generates semantic-search embeddings)
npm run build:quick	Production build without embeddings generation
npm run build:full	Full build including verification
npm run preview	Preview the production build
npm run test	Run Vitest once
npm run test:watch	Run Vitest in watch mode
npm run generate:gdat	Regenerate GDAT reference fixtures
npm run generate:embeddings	Generate public/model-embeddings.json for semantic search

Rebuilding WASM artifacts

CVODE (SUNDIALS) — stiff ODE solver:

cd wasm-sundials
./build_wasm.sh        # Linux/macOS
build_wasm.bat         # Windows

NFsim — network-free stochastic simulator:

# Requires NFSIM_SRC env var pointing to the akutuva21/nfsim C++ source
cd wasm-nfsim
./build_wasm.sh        # Linux/macOS
build_wasm.bat         # Windows

# Or fetch the latest pre-built artifacts from CI (requires GitHub CLI):
./tools/fetch-nfsim-wasm.sh

Build outputs land in public/nfsim.js and public/nfsim.wasm automatically.

Workflow

1. Pick a model from the Example Gallery (or paste your own BNGL).
2. Edit BNGL in the editor.
3. Click Parse to (re)parse the model.
4. Run a simulation (ODE, SSA, PLA, PSA, or NFsim) and explore results in the tabs.

Example Gallery + Semantic Search

The Example Gallery features a curated library of 250+ verified BioNetGen models, organized into biological and technical categories:

• Cancer Biology: Oncogenic signaling, tumor suppression, and DNA repair pathways.
• Immunology: TCR/BCR signaling, FcεRI degranulation, innate immunity, and cytokine networks.
• Neuroscience: Synaptic plasticity, ion channels (CaMKII), and neurotransmitter release.
• Cell Cycle & Death: Mitosis, apoptosis, and cell cycle checkpoints.
• Metabolism: Metabolic pathways, enzyme kinetics, and glucose homeostasis.
• Developmental Biology: Morphogens, differentiation, and tissue patterning.
• Ecology & Evolution: Predator-prey dynamics, food webs, infectious disease (Zombies), and spatial niche models.
• Mathematics & Physics: Strange attractors (Lorenz), N-body gravity, wave equations, bouncing balls, and quantum-inspired circuits.
• Computer Science & Algorithms: Encryption, Huffman coding, Regex engines, PID controllers, and even a BNGL-in-BNGL interpreter.
• Machine Learning & Signal Processing: Bio-inspired implementations of K-means, SVMs, Q-learning, Hopfield networks, Fourier synthesizers, and Kalman filters.
• Synthetic Biology: Molecular logic gates, pulse generators, counters, and edge detectors.
• RuleWorld Tutorials: Official BioNetGen tutorials and comprehensive grammar examples.
• Example Models: A complete set of 175 verified baseline models covering advanced features and edge cases.

Performance & Parity

We maintain high fidelity with canonical BioNetGen (BNG2.pl) and provide high-performance simulation capabilities:

• High Precision: Integrated CVODE (SUNDIALS) solver handles stiff ODE systems with adaptive time-stepping.
• Scalability: Accelerated by Nauty (WASM) for fast symmetry reduction and canonical labeling in large reaction networks.
• Network-Free: Native NFsim support for simulating models that are too large for network expansion.
• Multi-Compartment: Full support for cBNGL (Compartmental BioNetGen) across both ODE and stochastic solvers.
• Hybrid Simulation: PSA (Partitioned Stochastic Algorithm) adaptively partitions species between ODE and SSA based on copy number.

Search capabilities include:

• Keyword search: Fast text matching across model names and descriptions.
• Semantic search: Natural-language queries (e.g., "MAPK pathway with feedback") using Vector embeddings.

Semantic search uses a precomputed embeddings index at public/model-embeddings.json.

• npm run build regenerates embeddings automatically.
• Use npm run build:quick to skip embedding generation during rapid iteration.

Tabs

The UI exposes a small set of core tabs by default, with additional analysis tabs behind More →.

Core tabs (always visible)

• Time Courses

  • Plots observables vs time.
  • Interactive legend: click to toggle series, double-click to isolate/restore.
  • Drag-to-zoom and double-click to reset view.
  • Optional custom expressions (derived observables) via the Expression panel.

• Parameter Scan

  • 1D scan: sweep a parameter range and plot an observable vs parameter value (drag-to-zoom supported).
  • 2D scan: heatmap of an observable across two parameters (hover tooltip, click-to-pin, and it scales to fill the panel).
  • Optional surrogate training for fast sweeps on large parameter spaces.

• Regulatory Graph

  • Graph view of how rules influence molecular states.
  • Supports time-course overlay for selected influences.

Advanced tabs (shown via More →)

• What-If Compare: run a baseline vs modified-parameter simulation and compare trajectories (interactive legend).
• Contact Map: molecule-type interaction map; click edges to jump to representative rules.
• Rule Cartoons: compact visualizations of reaction rules (cartoon + compact view).
• Identifiability (FIM): Fisher Information Matrix analysis, eigen/sensitivity views, and heatmaps.
• Steady State: run an extended ODE sweep and detect steady state (result appears as the final point in Time Courses).
• Parameter Estimation: fit parameters to experimental time-series data (includes priors and convergence diagnostics).
• Flux Analysis: compute and visualize reaction flux contributions from the expanded reaction network.
• Verification: define constraints over observables (inequalities, equality, conservation) and check against simulation results.

Architecture

graph TD
    UI["React Frontend (App)"]
    AppSvc["App-level Services\n(services/)"]
    Engine["Engine Package\n(packages/engine — @bngplayground/engine)"]
    Worker["Web Workers"]
    Solvers["WASM Solvers\n(CVODE · NFsim · Nauty)"]
    Analysis["Analysis & Visualization"]

    UI --> AppSvc
    AppSvc --> Engine
    AppSvc --> Worker
    Worker --> Engine
    Worker --> Solvers
    AppSvc --> Analysis

Loading

The codebase is split into two layers:

Layer	Location	Purpose
App	App.tsx, components/, services/, hooks/	React UI, worker communication, visualization
Engine	packages/engine/ (@bngplayground/engine)	Core algorithms: parser, graph, solvers, analysis

Files in services/ and src/ that were moved into the engine are kept as thin re-export shims so existing imports continue to work without changes.

Directory Structure & Codebase Deep Dive

Top-level layout

bionetgen-web-simulator/
├── App.tsx / index.tsx       # React entry points
├── types.ts / constants.ts   # Shared app-level types and constants
├── components/               # React UI components and tabs
├── hooks/                    # Custom React hooks
├── services/                 # App-level services (worker comms, UI helpers)
│   ├── bnglService.ts        # Main worker communication layer
│   ├── parseBNGL.ts          # Parser API wrapper
│   ├── visualization/        # UI visualization helpers
│   ├── grammar/              # Visual Designer grammar parser
│   └── semanticSearch.ts     # TensorFlow.js semantic search
├── src/                      # Thin shims re-exporting from @bngplayground/engine
│   ├── parser/               # BNGLParserWrapper.ts shim
│   ├── services/             # Shims for graph, ODE, analysis, estimation
│   └── utils/                # Shims for utility functions
├── packages/
│   └── engine/               # @bngplayground/engine — all core algorithms
│       └── src/
│           ├── index.ts      # Public barrel export
│           ├── interfaces/   # SimulationEngine interface + EngineRegistry
│           ├── parser/       # ANTLR4 BNGL parser implementation
│           ├── services/
│           │   ├── graph/    # Network generation, matching, canonicalization (Nauty)
│           │   ├── simulation/ # ODE/SSA/PLA/PSA/NFsim solvers + SimulationLoop
│           │   ├── analysis/ # Dose-response, LNA, FPT, perturbation, FIM, flux, steady state
│           │   ├── inference/ # ABC-SMC, posterior predictive
│           │   ├── parity/   # BNG2.pl regression testing utilities
│           │   └── debugger/ # Rule-firing diagnostics
│           └── utils/        # Shared utility functions
├── wasm-nfsim/               # NFsim WASM build scripts (C++ source in akutuva21/nfsim)
│   ├── build_wasm.sh         # Linux/macOS build
│   ├── build_wasm.bat        # Windows build
│   └── build-wasm.github-actions-template.yml
├── wasm-sundials/            # CVODE (SUNDIALS) WASM build scripts + C source
├── tools/
│   └── fetch-nfsim-wasm.sh   # Fetch pre-built NFsim artifacts from CI
├── public/
│   ├── model-embeddings.json # Semantic search vector index (generated from RuleHub)
│   ├── cvode.wasm            # Pre-built CVODE solver
│   ├── nfsim.js / nfsim.wasm # Pre-built NFsim solver
│   └── nauty.wasm            # Pre-built Nauty canonical labeler
├── scripts/                  # Build-time and developer utilities
│   ├── generateEmbeddings.mjs
│   ├── parity_check.ts
│   └── layered_parity_check.ts
├── tests/                    # Vitest formal test suite (*.spec.ts)

Key entry points

• App.tsx — app shell and routing
• components/EditorPanel.tsx — BNGL editor and run controls
• components/VisualizationPanel.tsx — analysis tab container
• services/bnglService.ts — worker communication (parse / simulate)
• packages/engine/src/index.ts — engine public API
• scripts/generateEmbeddings.mjs — build-time semantic search embeddings

Services organization

App-level (services/) — interface between React and the engine:

• bnglService.ts / bnglWorker.ts: worker lifecycle, parse/simulate requests
• semanticSearch.ts: TensorFlow.js vector search
• cvode_loader.js / nauty_loader.js: WASM loader glue

Engine core (packages/engine/src/services/) — pure algorithmic implementations:

• graph/NetworkGenerator.ts: rule-based network expansion

• graph/core/: Species, Rxn, Matcher, canonical labeling (Nauty)

• simulation/ODESolver.ts: CVODE WASM integration (primary stiff solver)

• simulation/PSASimulator.ts: Hybrid ODE/SSA partitioned stochastic algorithm

• simulation/nfsim/: NFsim adapter and result parsing

• analysis/: dose-response, LNA, first passage time, perturbation screen, NFsim post-processing, FIM, flux, steady-state

• inference/: ABC-SMC Bayesian inference, posterior predictive simulation

• Concurrency: Distributed Web Worker pool for parsing, network generation, and simulation, ensuring 0 ms UI lag even during stiff ODE solving.

• WASM Acceleration: Native-speed solvers for CVODE, NFsim, and Nauty (canonical labeling).

• Semantic Search: Client-side vector embeddings via TensorFlow.js for natural-language model discovery.

• Parallel Trajectories: Core Comparison Engine for real-time "What-If" parameter perturbation analysis.

Architecture

BNG Playground uses a monorepo architecture with clear separation of concerns:

• Engine (packages/engine): Pure TypeScript, zero browser dependencies. Contains all core algorithms (parsing, simulation, analysis).
• MCP Server (packages/mcp-server): 44 tool endpoints for programmatic access.
• App Root: React UI with 27 analysis tabs, Web Worker orchestration, and WASM module loading.
• 7 WASM Modules: CVODE (SUNDIALS), NFsim, Nauty, and 4 additional solver modules for native-speed computation.

License:

MIT