BOL Documentation

BOL is a modular Python application with a simulation core and a web-based frontend. The simulation runs server-side in a background thread while the Flask web server provides real-time updates to the browser via polling APIs.

Simulation Pipeline (each step)

1. Diffusion — Molecules undergo Brownian motion in 3D space with periodic boundary conditions.
2. Energy — Energy sources (thermal, redox, UV, lightning) update their spatial fields and accumulate available energy.
3. Chemistry — Reaction encounters are sampled via spatial hashing; viable reactions fire stochastically based on Gibbs free energy coupling.
4. Assembly — Amphiphilic molecules cluster into micelles, promote to vesicles, accrete lipids, and dissolve if unstable.
5. Replication — RNA templates on mineral surfaces or inside vesicles copy with error-prone fidelity.
6. Metrics — Population counts, diversity indices, complexity scores, and fitness values are recorded.

Module Map

BOL models the key abiotic reaction pathways hypothesized to drive the origin of life. Each reaction rule specifies:

• Reactants & products — molecule types consumed and produced
• ΔG (Gibbs free energy) — thermodynamic barrier; negative = exergonic, positive = endergonic (needs energy coupling)
• Base rate — intrinsic reaction probability per encounter
• pH & temperature optima — Gaussian modifiers that peak at optimal environmental conditions
• Mineral requirement — whether the reaction requires mineral surface catalysis

Reaction Categories

Gibbs Free Energy Coupling

Reactions only proceed when their ΔG barrier is overcome by available energy. Exergonic reactions (ΔG < 0) proceed spontaneously with rate modulated by temperature. Endergonic reactions (ΔG > 0) require energy coupling — the available thermal, redox, UV, or lightning energy at the molecule's position must exceed the ΔG barrier.

Assembly Pathway

1. Free amphiphiles — Lipids and fatty acids diffuse in the 3D world.
2. Micelle formation — When amphiphile concentration exceeds the critical micelle concentration (CMC analog), nearby molecules cluster into micelles via spatial proximity detection.
3. Vesicle promotion — Micelles that accumulate enough lipids (≥ vesicle_threshold) undergo a phase transition to form bilayer vesicles with interior volume.
4. Encapsulation — At vesicle formation, all molecules inside the closing bilayer radius are trapped. This creates a compartment that isolates interior chemistry from the outside environment.
5. Lipid accretion — Free amphiphiles near existing vesicles join the membrane, growing the vesicle.
6. Membrane permeability — Small molecules (H₂O, CO₂, H₂, etc.) can cross the membrane. Semi-permeable molecules (amino acids, nucleotides) cross slowly, creating a net inward bias.
7. Division — Vesicles exceeding a size threshold divide into two daughter cells, randomly partitioning contents and membrane lipids.

Selection Pressure

Vesicle fitness is computed from their interior contents: catalytic RNA strands and peptides contribute to fitness. Fitter vesicles grow faster via osmotic influx of nutrients, attract more membrane lipids at greater distances, and produce daughters that inherit their competitive advantages.

Pages

REST API Endpoints

The AI Laboratory provides 27 deterministic analysis functions organised into 8 modules. Each function inspects live simulation state (molecules, reactions, vesicles, energy systems) and produces structured reports rendered with rich visual components (tables, bar charts, timelines, cards).

All actions are invoked via POST /api/ai/<module>/<action> and return JSON. Each module has a dedicated page accessible from the sidebar under AI Laboratory.

Modules & Actions

Visual Renderers

Each action has a dedicated renderer in ai-results.js (27 renderers total) that transforms raw JSON into rich visual components:

• Summary cards — Key metric highlights with colour-coded values
• Data tables — Sortable tables for reactions, vesicles, ribozymes, etc.
• Bar charts — Horizontal charts for yields, sensitivities, fitness rankings
• Timelines — Evolutionary event cascades and emergence tracking
• Hypothesis cards — Generated hypotheses with predictions and confidence indicators
• Depth profiles — Stacked gradient visualisations for T, pH, mineral, and energy fields

Projects let users create custom experiments by selecting molecules, configuring environments, and running simulations. Each project saves its configuration and full run history.

Project Lifecycle

1. Create — New project from the Projects page, or import an existing JSON file.
2. Configure — Molecule picker (25 types across 6 categories), environment settings (temperature, pH, pressure), energy source toggles, world size, reaction parameters, and replication error rate.
3. Run — Two modes: Run (synchronous, saves results to project) or Run & Watch Live (starts background simulation and opens the Dashboard with a project badge).
4. Review — Run history table shows timestamp, steps, seed, complexity, molecules, vesicles, diversity, and fitness for each run.
5. Export — Download as JSON for backup/sharing, or generate a PDF report with full configuration and summary statistics.

Features