resim

A high-performance, discrete-time resource and process simulation engine and visual optimization studio powered by a declarative, human-readable domain-specific language (.reson).

---

📖 Table of Contents

• The RISC Simulation Philosophy
• Repository Architecture
• Quick Start
  • 1. CLI Simulation Engine (Rust)
  • 2. Visual IDE & Genetic Optimizer (Web)
• The .reson Domain-Specific Language
• Multi-Core Genetic Optimization Engine
• Component Documentation Links
• Developer Guidelines

---

🎯 The RISC Simulation Philosophy

Instead of bloating the domain language with hundreds of domain-specific keywords for money, machines, scrap, taxes, or perishable goods, resim models any real-world physical, biological, financial, or logistic system using just two fundamental atoms:

1. Resource (State / Inventory / Pools / Capital / Laborers)
2. Process (Transitions / Converters / Actions / Assembly Lines)

                       ┌────────────────────────┐
                       │        Resource        │
                       │ (State / Stock / Pool) │
                       └───────────┬────────────┘
                                   │
                 consumed (use)    │    generated (produce)
                       ▼           ▼           ▼
                       ┌────────────────────────┐
                       │        Process         │
                       │ (Action / Transition)  │
                       └───────────┬────────────┘
                                   │
                       constrained (catalyze)
                                   ▼
                       ┌────────────────────────┐
                       │        Resource        │
                       │ (Equipment / Laborers) │
                       └────────────────────────┘

• Working Capital & Currency $\to$ A Resource without decay or storage limits (e.g. cad, usd).
• Machinery & Labor $\to$ A Resource used as a non-consumed catalyze constraint.
• Scrap & Defects $\to$ A Process with multi-resource outputs (e.g. produce chip 85, scrap 15).
• Perishability & Maintenance $\to$ Handled via discrete decay batches (life 5 y) and scheduled repair processes.
• Holding / Storage Costs $\to$ A periodic Process that consumes currency per stored unit.

---

📂 Repository Architecture

resim/
├── src/                     # Core Rust simulation engine & CLI binary
│   ├── core/                # Models, discrete simulation tick loop, parser, expressions
│   ├── optimize/            # Parallel batch runner (Rayon) and genetic optimizer
│   ├── wasm/                # WebAssembly bridge for in-browser execution
│   └── README.md            # In-depth engine & architecture documentation
├── web/                     # Visual IDE & Genetic Optimizer Studio
│   ├── src/components/      # React Flow graph, Inspector, Optimizer Modal, Telemetry
│   ├── src/engine/          # Web simulation engine, multi-core Web Worker pool
│   └── README.md            # Web Studio & WorkerPool guide
├── example/                 # Example industrial models (.reson)
│   ├── simple_pencil.reson  # Pencil manufacturing & supply chain
│   ├── food_factory.reson   # Commercial bakery with perishable dough decay
│   ├── semiconductor_fab.reson # Silicon wafer fab with photolithography steppers
│   ├── ev_gigafactory.reson # Lithium battery cell assembly line
│   └── README.md            # DSL syntax reference & grammar specification
└── tests/                   # Integration, regression, and unit test suites

---

🚀 Quick Start

1. CLI Simulation Engine (Rust)

# Clone and build
git clone https://github.com/GoVed/resim.git
cd resim
cargo build --release

# Run a simulation model (1 hour horizon, logging every 1s)
cargo run --release -- reson_file=example/simple_pencil.reson start_time=1700000000 write_every=1 run_for=3600

The engine outputs discrete-second states directly to output.csv.

---

2. Visual IDE & Genetic Optimizer (Web)

cd web
npm install
npm run dev

Open http://localhost:5173 to explore:

• Interactive Node Graph: Clean non-overlapping DAG layout with catalyst equipment rows and skyward sales feedback loops.
• Live Playback Controls: Real-time play, step, speed control ($1\times$ to $1000\times$), and telemetry curves.
• Visual Inspector Panel: Edit and add resources, processes, rates, and catalyst requirements without editing code.
• Genetic Improvement Engine: Multi-objective parameter search utilizing 100% of your machine's CPU cores via Web Workers.

---

📝 The .reson Domain-Specific Language

Here is a complete model of a pencil manufacturing line with raw material sourcing, equipment catalysts, discrete WIP assembly durations, and sales cashflow:

# --- RESOURCES ---
cad
    resource
    unit $
    amount 10000

wood
    resource
    unit kg
    amount 500

pencil
    resource
    unit count
    amount 0

pencil_machine
    resource
    unit count
    amount 2
    max 5
    life 5 y

# --- PROCESSES ---
purchase_wood
    process
    use
        cad 50
    produce
        wood 100
    period 1 h

manufacture_pencil
    process
    use
        wood 10
    produce
        pencil 20
    catalyze 2
        pencil_machine 1
    period 1 s
    duration 3 s

sell_pencil
    process
    use
        pencil 20
    produce
        cad 80
    period 2 s

---

🧬 Multi-Core Genetic Optimization Engine

Resim includes an autonomous evolutionary search engine to solve complex multi-variable production trade-offs:

1. Multi-Objective Formulation: $$\text{Fitness}(\vec{x}) = \sum_{i=1}^k w_i \cdot \text{Score}i(\vec{x}) - \sum{j=1}^m \text{Penalty}_j(\vec{x})$$
   • Maximizes working capital (cad, usd) with customizable objective weights.
   • Minimizes payroll and labor waste (labor, work_hour).
   • Balances finish-good buffer targets.
2. Operational Constraints:
   • Solvency Floors: Guarantees working capital never breaches a safety threshold throughout the entire simulation horizon.
   • Brownfield Zero-Capex: Locks machinery to current capacity, optimizing strictly through scheduling, batch sizing, and recipe ratios.
   • Storage Bounds & Sourcing Ceilings: Prevents warehouse overflow or supply breaches.
3. 100% CPU Utilization (Multi-Threaded Worker Pool):
   • Slices candidate populations and dispatches evaluations across all logical CPU cores in parallel via dedicated background Web Workers.
   • Streams generation progress, live convergence charts, and discovered parameter diffs in real time.

---

📚 Component Documentation Links

• 🦀 Rust Engine & Core Architecture (src/README.md): Deep dive into the discrete tick lifecycle, decay FIFO queues, expressions, and Rayon parallel batch execution.
• 🌐 Resim Web Studio (web/README.md): Guide to the React Flow node editor, Inspector panel, and multi-threaded Web Worker pool.
• 📄 DSL Specification & Industrial Examples (example/README.md): Comprehensive grammar reference and walkthroughs of the sample factory models.

---

🛠️ Developer Guidelines

• Zero-Panic Policy: Return Result<T, ResimError> with full line numbers and context; never use .unwrap() in the core engine.
• Safe Arithmetic: Guard against floating-point precision drift and unsigned integer underflow (u64).
• Test Coverage: All features and bug fixes must be covered by integration tests in tests/ and Vitest suites in web/.

# Run all Rust tests
cargo test

# Run all Web unit and UI tests
cd web && npm run test