{"id":49187626,"url":"https://github.com/thavlik/lyfe","last_synced_at":"2026-04-23T05:01:58.182Z","repository":{"id":352510645,"uuid":"1195396198","full_name":"thavlik/lyfe","owner":"thavlik","description":"A 2d simulator for molecular cell biology.","archived":false,"fork":false,"pushed_at":"2026-04-19T23:42:09.000Z","size":451,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-20T00:30:05.256Z","etag":null,"topics":["biology","chemistry","fluidsim","molecular-cell-biology","simulation"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thavlik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE-2.0","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T16:13:52.000Z","updated_at":"2026-04-20T00:21:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thavlik/lyfe","commit_stats":null,"previous_names":["thavlik/lyfe"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/thavlik/lyfe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thavlik%2Flyfe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thavlik%2Flyfe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thavlik%2Flyfe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thavlik%2Flyfe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thavlik","download_url":"https://codeload.github.com/thavlik/lyfe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thavlik%2Flyfe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32166660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biology","chemistry","fluidsim","molecular-cell-biology","simulation"],"created_at":"2026-04-23T05:01:57.099Z","updated_at":"2026-04-23T05:01:58.169Z","avatar_url":"https://github.com/thavlik.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lyfe\n[![Status: Actively Maintained](https://img.shields.io/badge/status-actively%20maintained-2ea44f)](https://github.com/thavlik/lyfe/pulse)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-0366d6)](https://github.com/thavlik/lyfe#license)\n\nLyfe is a GPU-accelerated 2D chemical transport sandbox written in Rust on top of Vulkan. The project currently includes a Lean-backed reaction layer, coarse semantic snapshots, thermal transport, membrane leak channels, and moving enzyme entities. It represents \"pre-production R\u0026D\" for a video game.\n\nAt a high level:\n\n- `fluidsim` runs the fine-grid simulation on the GPU.\n- `kinetics` builds coarse semantic snapshots and invokes Lean for low-frequency rule evaluation.\n- `lean` contains the `lyfe-rules` executable that decides which reactions are active.\n- `renderer` visualizes concentrations and temperature.\n- `demo` ties everything together into an interactive desktop application.\n\n## Screenshots\n\u003cp\u003e\n  \u003cimg width=\"200\" src=\"images/screenshot_0_enzymes.webp\"\u003e\n  \u003cimg width=\"200\" src=\"images/screenshot_1_leak_channels.webp\"\u003e\n\u003c/p\u003e\n\n## Current Feature Set\n\n### Fine-grid GPU simulation\n\n- Multi-species transport on a dense `[species][cell]` buffer layout.\n- Explicit diffusion on Vulkan compute shaders with ping-pong buffers.\n- Solid geometry and material masks for impermeable walls and embedded structures.\n- Per-cell temperature field with a separate thermal diffusion pass.\n- Optional charge-correction / electrochemical transport heuristics for ionic systems.\n- Shared render/simulation Vulkan context so rendering can bind live simulation buffers directly.\n\n### Lean-backed kinetics and semantics\n\n- `fluidsim` builds a coarse semantic snapshot once per simulated second.\n- `kinetics` serializes that snapshot to JSON and sends it to Lean (`lyfe-rules`)\n- Lean returns compact reaction directives instead of replacing the simulation state.\n- The returned directives can carry:\n  - Mass-action or Michaelis-Menten kinetics.\n  - Tile-local applicability.\n  - Thermodynamic metadata such as $\\Delta H$, $\\Delta G$, $\\Delta S$, and activation energy.\n- The GPU reaction pass consumes those directives and updates concentration and temperature fields in-place.\n\n### Chemistry currently implemented\n\n- Strong acid/base neutralization: $\\mathrm{H^+ + OH^- \\rightarrow H_2O}$.\n- Weak-acid buffer behavior for acetic acid / acetate systems.\n- Direct neutralization of acetic acid by hydroxide.\n- Catalyst-gated phosphorylation rule for hexokinase.\n- Michaelis-Menten support for catalyst-driven reactions.\n\n### Membranes, leaks, and enzymes\n\n- Leak channels embedded in solid boundaries for directional transport experiments.\n- Electrochemical leak heuristics that preserve directional flow while damping unstable local charge separation.\n- Moving enzyme entities with drift, rotation, and thermal/circulation heuristics.\n- Enzyme-specific GPU pass for entity-mediated catalysis separate from dissolved catalyst rules.\n\n### Inspection and debugging\n\n- Async coarse inspection readback for hover tooltips.\n- Detail mode with pinned probe callouts around the simulation viewport.\n- Thermal visualization overlay.\n- Performance overlay for frame-time monitoring.\n- Smoke-test mode that renders a few frames and exits.\n\n## Workspace Layout\n\n- `fluidsim`: core simulation crate.\n  - GPU transport, reaction, leak, enzyme, and thermal compute passes.\n  - Scenario builders and coarse semantic snapshot generation.\n  - Inspection, material, and species registries.\n- `kinetics`: low-frequency semantic evaluation crate.\n  - Snapshot/update types.\n  - Lean bridge and evaluator.\n  - Rule-engine configuration and diagnostics.\n- `lean`: Lean 4 rule engine.\n  - Owns the semantic rule definitions.\n- `renderer`: Vulkan rendering and egui overlay crate.\n- `demo`: interactive application and scenario runner.\n\n## Simulation Flow\n\nEach frame, the demo advances the fine-grid simulation on the GPU and renders the current concentration or temperature field. On a slower cadence, the simulation also performs a semantic pass:\n\n1. Build a coarse snapshot from the current grid.\n2. Send that snapshot to Lean through the `kinetics` crate.\n3. Receive reaction directives for the tiles where rules are active.\n4. Upload those directives back to the GPU.\n5. Continue the fine-grid simulation with updated kinetics parameters.\n\nThis split keeps high-frequency transport on the GPU while moving rule selection and reaction semantics into Lean.\n\n## Scenarios\n\nThe demo currently ships with six scenarios:\n\n- `basic`: the original Na/K/Cl transport demo inside a hollow titanium box with a temperature split.\n- `acid-base`: strong acid / strong base mixing with exothermic neutralization.\n- `buffers`: weak-acid buffer against NaOH, including acetate/acetic-acid equilibrium.\n- `catalyst`: dissolved hexokinase driving glucose phosphorylation.\n- `enzyme`: moving enzyme entities performing the same phosphorylation chemistry as localized actors.\n- `leak`: buffered ionic system with membrane leak channels for K+ and Na+ transport.\n\n## Building\n\n### Requirements\n\n- Rust 2024 edition toolchain.\n- Vulkan 1.2-capable GPU and working Vulkan driver.\n- Lean 4 and Lake.\n- Linux desktop environment with X11 or Wayland (other platforms may work but are untested).\n\n### Build the Lean rule engine\n\nThe simulation initializes the kinetics layer by default, so the Lean executable should be built before running the demo:\n\n```bash\ncd lean\nlake build\ncd ..\n```\n\nBy default, the Rust side looks for the binary in one of these locations:\n\n- `LYFE_LEAN_BINARY`\n- `lean/.lake/build/bin/lyfe-rules`\n- `../lean/.lake/build/bin/lyfe-rules`\n- `lyfe-rules` on `PATH`\n\nIf you build the Lean binary somewhere else:\n\n```bash\nexport LYFE_LEAN_BINARY=/absolute/path/to/lyfe-rules\n```\n\n### Build the Rust workspace\n\n```bash\ncargo build --release\n```\n\n## Running The Demo\n\nShow CLI help:\n\n```bash\ncargo run -p demo -- --help\n```\n\nRun the default scenario:\n\n```bash\ncargo run --release -p demo\n```\n\nRun a specific scenario:\n\n```bash\ncargo run --release -p demo -- acid-base\ncargo run --release -p demo -- buffers\ncargo run --release -p demo -- catalyst\ncargo run --release -p demo -- enzyme\ncargo run --release -p demo -- leak\n```\n\nUseful flags:\n\n- `--detail`: render the sim as an inset with pinned inspection probes.\n- `--smoke-test`: render 5 frames and exit.\n- `--present-mode auto|fifo|mailbox`: choose Vulkan present mode. `auto` prefers `fifo` on X11 for capture compatibility.\n\nExamples:\n\n```bash\ncargo run --release -p demo -- --detail leak\ncargo run --release -p demo -- --smoke-test basic\ncargo run --release -p demo -- --present-mode fifo enzyme\n```\n\n## Controls\n\nGeneral controls:\n\n- Mouse hover: inspect the coarse cell under the cursor.\n- `Space`: pause or resume the simulation.\n- `+` / `-`: increase or decrease the inspection mip factor.\n- Hold `T`: show the thermal view.\n- `Tab`: toggle the performance overlay.\n- `Shift+R`: reset the current scenario.\n- `Escape`: quit.\n\nLeak editor controls:\n\n- Use the egui `CREATE` panel to add leak channels.\n- Left click selects a leak channel or confirms placement/transform.\n- `R`: rotate a leak channel by 45 degrees while placing or transforming it.\n- With a leak channel selected, `T` enters transform mode.\n- `Delete`: remove the selected leak channel.\n\n## Tests And Probes\n\nThe `fluidsim` crate includes probe binaries and regression tests for the newer chemistry and transport paths:\n\n- `acid_base_probe`: checks center-window neutralization and exothermic heating.\n- `buffer_probe`: checks weak-acid / hydroxide consumption and acetate formation.\n- `leak_probe`: checks K+ inward flow, Na+ outward flow, mass conservation, and bounded local charge error.\n\nRun them with:\n\n```bash\ncargo test -p fluidsim\n```\n\n## Notes\n\n- The Lean layer is the source of truth for active semantic rules. Adding new rule families is intended to happen in Lean first, with Rust remaining mostly rule-agnostic.\n- The simulation is intentionally split into a fast fine-grid transport loop and a slower semantic reasoning loop.\n- The demo is Linux-focused today and assumes working Vulkan presentation support.\n- Capturing with OBS might not work properly due to use of low-level Vulkan presentation.\n- Chemical species are currently represented with molecular formulae. Plans are in motion to represent species as full structural formulae.\n\n## Contributing\n\nContributions are welcome. Feel free to open an issue to begin discussion on new features.\n\n## License\n\nAll of the code in this repository is released under Apache 2.0 / MIT dual-license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthavlik%2Flyfe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthavlik%2Flyfe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthavlik%2Flyfe/lists"}