Rewrite FrogSim as TypeScript web app with 3D visualization - #1
Open
ArvisPrime wants to merge 3 commits into
Open
Rewrite FrogSim as TypeScript web app with 3D visualization#1ArvisPrime wants to merge 3 commits into
ArvisPrime wants to merge 3 commits into
Conversation
The 2017 project was a Core-PHP CRUD demo whose README listed four tasks that were never built. This implements them as actual population ecology, with 2D, 2.5D and 3D interactive views. The original PHP app is preserved in legacy-php/. Engine (src/engine/) — deterministic, DOM-free, one simulated day per tick: - Post-metamorphic animals are individual agents; eggs and larvae are cohorts with a size CV, because one pond holds 10^4-10^5 tadpoles. - Richardson stochastic weather generator; Hamon PET; CBM photoperiod. - Stage-volume pond water balance (V = k*d^p), driving hydroperiod — the master variable structuring temperate amphibian communities. - Degree-day development on a Briere curve; growth from a grazed periphyton pool under scramble competition; Wilbur-Collins metamorphosis. - Holling Type III larval predation with size refuge and induced defences. - Acoustic mate choice inside a computed active space, giving an emergent mate-finding Allee effect rather than an imposed one. - Load-based Bd model with an environmental zoospore pool and thermal window. - Infinitesimal quantitative genetics with Wright's inbreeding recursion. Rendering (src/render/) — three views behind one interface: top-down analytical 2D with a scale bar, oblique depth-sorted 2.5D diorama, and instanced-mesh 3D. The 2.5D view is also the automatic fallback when WebGL is unavailable. Architecture: the engine runs in a Web Worker and posts flat typed-array snapshots, so a ~35 ms tick at 18k agents never blocks the 60 fps render loop. Interactivity: transport controls, click-to-inspect frogs and ponds, terrain brushes, pond editor, species editor, live parameters, seven scenarios. Tests: tests/ecology.test.ts pins the mathematics of each named model; tests/vitalRates.test.ts runs simulated decades and asserts that emergent vital rates land inside published field ranges. The latter is what caught every calibration bug found while building this. Docs: docs/MODEL.md is the full specification with equations and sources; docs/REFERENCES.md states explicitly which citation details are unverified. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PVhCMnzYeAk457moZNTEco
Each of these was found by the vital-rate suite, not by inspection: - Larval mass was unbounded when development lagged growth. A cohort in a cold pond kept growing while waiting for degree-days and produced "metamorphs" an order of magnitude heavier than any adult of their species. Mass is now capped at 1.15x maxMetaMass, which is also the correct representation of the overwintering-larva case that confines bullfrogs to permanent water. - Breeding values were unbounded. The infinitesimal model as usually written has no selection limit, so sustained sexual selection on male size drove growth breeding values past +7 SD. Clamped to +-4 founder SD, standing in for finite additive genetic variance. - The chart refresh interval depended on an object whose identity changed every render, so it was torn down faster than its own period and rarely fired. - The visual day/night clock chased a quantised sim clock and could run backwards. It now tracks absolute simulated time monotonically, rate-limited to one cycle per eight real seconds so it does not strobe at 60x. Two test assertions were wrong rather than the code, and the reasons are now documented in MODEL.md §6: - Density dependence is asserted on size at metamorphosis, not per-egg survival. Survival responds to scramble competition and predator satiation pulling in opposite directions; under a Type III response, per-prey risk peaks near 10 larvae/m^2 and falls above it, so at high stocking satiation wins and survival rises with density. Size at metamorphosis is unambiguous and is the signature Wilbur actually reported. - Road mortality is asserted across replicate seeds. Once the parameter differs the RNG streams diverge, so a single paired comparison is two different random trajectories and can come out either way. Also adds tests/interventions.test.ts: 21 tests covering everything a user can trigger from the UI, including destroying every pond, culling the entire landscape, running with zero ponds or zero species, and extreme parameters. Realised vital rates over a 15-year run now sit inside published field ranges: egg->metamorph 3.9%, metamorph->adult 4.4%, egg->breeding adult 0.17%. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PVhCMnzYeAk457moZNTEco
The suite ran for over 20 minutes and three assertions were still wrong. Both problems are fixed; all 82 tests now pass in ~75 seconds. Speed: the expensive simulations lived directly in `describe` bodies, so they ran during vitest's *collection* phase — every fixture in the file executed even when a single test was selected with `-t`. They are now lazy and memoised, which took a targeted run from 196 s to under 4 s. The vital-rate fixture is also sized to what its assertions need rather than to realism: two two-year-maturing species over six years. Longer horizons are the headless script's job. Correctness — in each case the model was right and the test was wrong: - Density dependence is now asserted on size at metamorphosis, in a predator-free pond, which is how Wilbur's experiments were actually run. With predators present the Type III response culls the cohort early, so the survivors are no longer crowded and both densities reach maximum metamorph size. That interaction is real; it just masks the competition signal, exactly as it would confound a field enclosure. - The metamorph-to-adult assertion failed on a five-year run containing a four-year-maturing species: the rate is a whole-run cumulative, so every metamorph from the second half of the run counts as a failure to mature. - Road mortality is asserted across three replicate seeds. Once the parameter differs the RNG streams diverge, making a single paired comparison two different random trajectories. The analysis panel now reports maturation-dependent rates as "too early" until five simulated years have passed, instead of flagging a structural zero as out-of-range. MODEL.md §6 records each of these, because they are properties of the model rather than of the code. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PVhCMnzYeAk457moZNTEco
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Complete rewrite of FrogSim from a PHP CRUD application into a sophisticated individual-based amphibian population simulation engine with interactive 2D, 2.5D, and 3D visualizations. The new implementation is built in TypeScript with React, runs in the browser with a Web Worker simulation backend, and includes comprehensive ecological modeling backed by peer-reviewed literature.
Key Changes
Core Simulation Engine
Ecological Models
Interactive Visualization
User Interface
Architecture
Documentation
docs/MODEL.mdwith equations, sources, and calibration constantsdocs/REFERENCES.mdNotable Implementation Details
https://claude.ai/code/session_01PVhCMnzYeAk457moZNTEco