viva-cpm 0.1.1__tar.gz

viva_cpm-0.1.1/Cargo.lock

@@ -0,0 +1,331 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cpm-bench"
+version = "0.1.0"
+dependencies = [
+ "cpm-core",
+ "rayon",
+]
+
+[[package]]
+name = "cpm-core"
+version = "0.1.0"
+dependencies = [
+ "rand",
+ "rayon",
+ "smallvec",
+]
+
+[[package]]
+name = "cpm-py"
+version = "0.1.0"
+dependencies = [
+ "cpm-core",
+ "pyo3",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
+[[package]]
+name = "either"
+version = "1.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rand"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
+dependencies = [
+ "libc",
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+dependencies = [
+ "getrandom",
+]
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]

viva_cpm-0.1.1/Cargo.toml

@@ -0,0 +1,12 @@
+[workspace]
+resolver = "2"
+members = ["crates/cpm-core", "crates/cpm-py"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+
+[workspace.dependencies]
+cpm-core = { path = "crates/cpm-core" }
+rand = "0.8"

viva_cpm-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivarium Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

viva_cpm-0.1.1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: viva-cpm
+Version: 0.1.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Dist: process-bigraph>=1.8.3
+Requires-Dist: bigraph-schema>=1.4.4
+Requires-Dist: bigraph-viz>=2.0.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema[format-nongpl]>=4.21
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pypdf>=4.0
+Requires-Dist: matplotlib
+Requires-Dist: plotly
+Requires-Dist: vivarium-workbench
+Requires-Dist: viva-cpm[sbml,ftu] ; extra == 'all'
+Requires-Dist: pytest>=7 ; extra == 'dev'
+Requires-Dist: viva-cpm[sbml,ftu] ; extra == 'dev'
+Requires-Dist: numpy ; extra == 'ftu'
+Requires-Dist: matplotlib ; extra == 'ftu'
+Requires-Dist: libroadrunner>=2.9 ; extra == 'sbml'
+Requires-Dist: tellurium>=2.2 ; extra == 'sbml'
+Requires-Dist: viva-tellurium ; extra == 'sbml'
+Provides-Extra: all
+Provides-Extra: dev
+Provides-Extra: ftu
+Provides-Extra: sbml
+License-File: LICENSE
+Summary: A process-bigraph Cellular Potts Model framework: a fast Rust CPM engine (2D/3D) with pluggable subcellular models, structural constraints, and metrics.
+Keywords: cellular-potts-model,process-bigraph,multiscale,tissue,vivarium
+Author: Vivarium Collective
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/vivarium-collective/viva-cpm
+Project-URL: Repository, https://github.com/vivarium-collective/viva-cpm
+
+# viva-cpm
+
+<!-- BEGIN dashboard -->
+> ## 📊 [**Live dashboard →**](https://vivarium-collective.github.io/viva-cpm/dashboard/)
+> Browse every investigation & study interactively, or read the [published investigation reports](https://vivarium-collective.github.io/viva-cpm/). Auto-published from `main` on every merge.
+<!-- END dashboard -->
+
+A [process-bigraph](https://github.com/vivarium-collective/process-bigraph) **Cellular Potts Model** framework — a fast Rust CPM engine (2D/3D, thousands of cells) with a Python layer for pluggable subcellular models, structural constraints, schema-driven world construction, and analysis metrics. A modern, composable remake of CompuCell3D built to do better in 3D, and a **research workspace** where CPM models are wrapped as typed processes, composed, run as studies, and graded against acceptance-criteria tests.
+
+## ▶ Live viewer
+
+**[Explore the demos interactively in your browser →](https://vivarium-collective.github.io/viva-cpm/dashboard/)**
+A living 3D colonic crypt (stem cells dividing at the base, differentiating, and sloughing at the mouth), 3D cell sorting, chemotaxis, growth & division, the structural-integrity constraints, and real tissue initialized from Human Reference Atlas / MIBI-TOF imaging — each rotatable, scrubbable, and cell-inspectable.
+
+## Install
+
+The importable engine is `cpm` (a compiled Rust extension) and the research package is `viva_cpm_studies`. Install from the repo:
+
+```bash
+# with uv (recommended)
+uv pip install "viva-cpm @ git+https://github.com/vivarium-collective/viva-cpm.git"
+
+# extras: [sbml] SBML/ODE subcellular models · [ftu] Human Reference Atlas FTU→CPM · [all] everything
+uv pip install "viva-cpm[all] @ git+https://github.com/vivarium-collective/viva-cpm.git"
+```
+
+From source (editable, requires a Rust toolchain + [maturin](https://www.maturin.rs)):
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install maturin
+maturin develop -m crates/cpm-py/Cargo.toml   # builds viva_cpm.cpm_core
+pytest                                          # Python suite; `cargo test` for the Rust core
+```
+
+## Use the engine from another project
+
+```python
+from viva_cpm import load_world, cpm_core
+
+spec = {
+    "potts": {"dims": [50, 50, 1], "boundary": "periodic",
+              "neighbor_order": 2, "temperature": 12.0, "seed": 0},
+    "cells": [
+        {"type": 1, "target_volume": 25, "lambda_volume": 1.0,
+         "target_surface": 0, "lambda_surface": 0, "seed_block": [5, 5, 0, 13, 13, 1]},
+    ],
+    "contact": [{"a": 0, "b": 1, "j": 12.0}],
+}
+world = load_world(spec)
+world.step(100)                     # run 100 Monte-Carlo sweeps
+print(world.cell_volumes())
+```
+
+The engine itself is `viva_cpm.cpm_core` (a compiled Rust extension). `load_world` builds a
+world from a plain dict spec (cells or a seeded label array, contact energies, diffusion
+fields, connectivity, basement membrane). Chemotaxis can operate on the raw field or, via
+`set_chemotaxis_occupancy`, in receptor-**occupancy** space — the substrate for fold-change
+detection (see the recruitment investigation below).
+
+## Process-bigraph composites
+
+Cells are wired as process-bigraph processes via import-path addresses, so any
+process-bigraph `Composite` can embed them:
+
+- `local:!viva_cpm.processes.cpm_process.CPMProcess` — the CPM step as a process
+- `local:!viva_cpm.subcellular.sbml.SBMLSubcell` — a per-cell SBML/ODE model (needs `[sbml]`)
+- `local:!viva_cpm.subcellular.boolean.BooleanSubcell` — a per-cell Boolean fate network
+- `local:!viva_cpm.subcellular.adaptive_receptor.AdaptiveReceptorSubcell` — a per-cell receptor with slow adaptation
+
+See `cpm/composites/crypt.py` for a full crypt-differentiation composite (CPM + SBML
+stemness ODE + Boolean fate switch), run with the process-bigraph `Composite` engine.
+
+## Research workspace: investigations & studies
+
+`workspace/` is a process-bigraph research workspace: composites in `viva_cpm_studies/`,
+studies under `workspace/studies/`, grouped into **investigations**. Each study carries a
+model, readouts, simulation runs, and acceptance-criteria **behavior tests** that grade a
+run into a signed pass/fail verdict. Two investigations ship today (browse them live on the
+[dashboard](https://vivarium-collective.github.io/viva-cpm/dashboard/)):
+
+- **glazier-graner-1993** — an 11-study reproduction of the classic Glazier–Graner
+  differential-adhesion results (annealing, global equilibration, checkerboard, cell
+  sorting, engulfment, position reversal, partial sorting, dispersal, vacancy nucleation).
+- **chemotactic-recruitment** — a secreted cue recruits responder cells, realized at three
+  levels: a phenomenological chemotaxis-λ (baseline + inhibited + adversarial controls), a
+  Kd-calibrated receptor-occupancy model (receptor-baseline + blocked), and an **adaptive**
+  fold-change-detection refinement built by an agentic model-building loop. That loop —
+  author a contract of tests → audit → feasibility spike → lock → build/run/evaluate →
+  navigate — climbs an emergent mechanism ladder (`static → hill_occupancy → adaptive`) in
+  which occupancy-space chemotaxis makes the fixed-`kd` rung collapse at high background and
+  adaptation rescues it; the run is captured as a `model_build_trajectory`. The
+  calibration tooling (`viva_cpm_studies/model_building/calibrate.py`) is a sensitivity
+  screen + common-random-numbers + refine, not a hand grid.
+
+The loop, contract, audit, and grading machinery live in
+[viva-superpowers](https://github.com/vivarium-collective/viva-superpowers); this repo is one
+of its research workspaces.
+
+## Structural constraints
+
+- **Connectivity** (E1): forbids copy attempts that would fragment a cell or pinch off
+  interior medium (gaps). `spec["connectivity"] = {"types": [1, 2], "medium": true}`.
+- **Basement membrane** (E3a): a basal anchor energy keeping epithelial cells in a thin
+  band hugging a fixed membrane surface. `spec["membrane"] = {"anchors": [...], "k": ...,
+  "band": ..., "types": [...]}`.
+
+## Layout
+
+```
+crates/            Rust workspace: cpm-core (engine) + cpm-py (pyo3 bindings → viva_cpm.cpm_core)
+cpm/               Python framework: schema, processes, subcellular, composites, metrics, ftu
+viva_cpm_studies/   research package: composites, model-building mechanisms + calibrate, visualizations
+workspace/         the research workspace: studies/, investigations/, references/, reports/
+demos/             runnable demos (each validates + exports a viewer model)
+viewer/            browser 2D/3D viewer for the exported models
+docs/              specs & implementation plans
+tests/             Rust (cargo test) + Python (pytest) suites
+```
+
+## License
+
+MIT
+

viva_cpm-0.1.1/README.md

@@ -0,0 +1,123 @@
+# viva-cpm
+
+<!-- BEGIN dashboard -->
+> ## 📊 [**Live dashboard →**](https://vivarium-collective.github.io/viva-cpm/dashboard/)
+> Browse every investigation & study interactively, or read the [published investigation reports](https://vivarium-collective.github.io/viva-cpm/). Auto-published from `main` on every merge.
+<!-- END dashboard -->
+
+A [process-bigraph](https://github.com/vivarium-collective/process-bigraph) **Cellular Potts Model** framework — a fast Rust CPM engine (2D/3D, thousands of cells) with a Python layer for pluggable subcellular models, structural constraints, schema-driven world construction, and analysis metrics. A modern, composable remake of CompuCell3D built to do better in 3D, and a **research workspace** where CPM models are wrapped as typed processes, composed, run as studies, and graded against acceptance-criteria tests.
+
+## ▶ Live viewer
+
+**[Explore the demos interactively in your browser →](https://vivarium-collective.github.io/viva-cpm/dashboard/)**
+A living 3D colonic crypt (stem cells dividing at the base, differentiating, and sloughing at the mouth), 3D cell sorting, chemotaxis, growth & division, the structural-integrity constraints, and real tissue initialized from Human Reference Atlas / MIBI-TOF imaging — each rotatable, scrubbable, and cell-inspectable.
+
+## Install
+
+The importable engine is `cpm` (a compiled Rust extension) and the research package is `viva_cpm_studies`. Install from the repo:
+
+```bash
+# with uv (recommended)
+uv pip install "viva-cpm @ git+https://github.com/vivarium-collective/viva-cpm.git"
+
+# extras: [sbml] SBML/ODE subcellular models · [ftu] Human Reference Atlas FTU→CPM · [all] everything
+uv pip install "viva-cpm[all] @ git+https://github.com/vivarium-collective/viva-cpm.git"
+```
+
+From source (editable, requires a Rust toolchain + [maturin](https://www.maturin.rs)):
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install maturin
+maturin develop -m crates/cpm-py/Cargo.toml   # builds viva_cpm.cpm_core
+pytest                                          # Python suite; `cargo test` for the Rust core
+```
+
+## Use the engine from another project
+
+```python
+from viva_cpm import load_world, cpm_core
+
+spec = {
+    "potts": {"dims": [50, 50, 1], "boundary": "periodic",
+              "neighbor_order": 2, "temperature": 12.0, "seed": 0},
+    "cells": [
+        {"type": 1, "target_volume": 25, "lambda_volume": 1.0,
+         "target_surface": 0, "lambda_surface": 0, "seed_block": [5, 5, 0, 13, 13, 1]},
+    ],
+    "contact": [{"a": 0, "b": 1, "j": 12.0}],
+}
+world = load_world(spec)
+world.step(100)                     # run 100 Monte-Carlo sweeps
+print(world.cell_volumes())
+```
+
+The engine itself is `viva_cpm.cpm_core` (a compiled Rust extension). `load_world` builds a
+world from a plain dict spec (cells or a seeded label array, contact energies, diffusion
+fields, connectivity, basement membrane). Chemotaxis can operate on the raw field or, via
+`set_chemotaxis_occupancy`, in receptor-**occupancy** space — the substrate for fold-change
+detection (see the recruitment investigation below).
+
+## Process-bigraph composites
+
+Cells are wired as process-bigraph processes via import-path addresses, so any
+process-bigraph `Composite` can embed them:
+
+- `local:!viva_cpm.processes.cpm_process.CPMProcess` — the CPM step as a process
+- `local:!viva_cpm.subcellular.sbml.SBMLSubcell` — a per-cell SBML/ODE model (needs `[sbml]`)
+- `local:!viva_cpm.subcellular.boolean.BooleanSubcell` — a per-cell Boolean fate network
+- `local:!viva_cpm.subcellular.adaptive_receptor.AdaptiveReceptorSubcell` — a per-cell receptor with slow adaptation
+
+See `cpm/composites/crypt.py` for a full crypt-differentiation composite (CPM + SBML
+stemness ODE + Boolean fate switch), run with the process-bigraph `Composite` engine.
+
+## Research workspace: investigations & studies
+
+`workspace/` is a process-bigraph research workspace: composites in `viva_cpm_studies/`,
+studies under `workspace/studies/`, grouped into **investigations**. Each study carries a
+model, readouts, simulation runs, and acceptance-criteria **behavior tests** that grade a
+run into a signed pass/fail verdict. Two investigations ship today (browse them live on the
+[dashboard](https://vivarium-collective.github.io/viva-cpm/dashboard/)):
+
+- **glazier-graner-1993** — an 11-study reproduction of the classic Glazier–Graner
+  differential-adhesion results (annealing, global equilibration, checkerboard, cell
+  sorting, engulfment, position reversal, partial sorting, dispersal, vacancy nucleation).
+- **chemotactic-recruitment** — a secreted cue recruits responder cells, realized at three
+  levels: a phenomenological chemotaxis-λ (baseline + inhibited + adversarial controls), a
+  Kd-calibrated receptor-occupancy model (receptor-baseline + blocked), and an **adaptive**
+  fold-change-detection refinement built by an agentic model-building loop. That loop —
+  author a contract of tests → audit → feasibility spike → lock → build/run/evaluate →
+  navigate — climbs an emergent mechanism ladder (`static → hill_occupancy → adaptive`) in
+  which occupancy-space chemotaxis makes the fixed-`kd` rung collapse at high background and
+  adaptation rescues it; the run is captured as a `model_build_trajectory`. The
+  calibration tooling (`viva_cpm_studies/model_building/calibrate.py`) is a sensitivity
+  screen + common-random-numbers + refine, not a hand grid.
+
+The loop, contract, audit, and grading machinery live in
+[viva-superpowers](https://github.com/vivarium-collective/viva-superpowers); this repo is one
+of its research workspaces.
+
+## Structural constraints
+
+- **Connectivity** (E1): forbids copy attempts that would fragment a cell or pinch off
+  interior medium (gaps). `spec["connectivity"] = {"types": [1, 2], "medium": true}`.
+- **Basement membrane** (E3a): a basal anchor energy keeping epithelial cells in a thin
+  band hugging a fixed membrane surface. `spec["membrane"] = {"anchors": [...], "k": ...,
+  "band": ..., "types": [...]}`.
+
+## Layout
+
+```
+crates/            Rust workspace: cpm-core (engine) + cpm-py (pyo3 bindings → viva_cpm.cpm_core)
+cpm/               Python framework: schema, processes, subcellular, composites, metrics, ftu
+viva_cpm_studies/   research package: composites, model-building mechanisms + calibrate, visualizations
+workspace/         the research workspace: studies/, investigations/, references/, reports/
+demos/             runnable demos (each validates + exports a viewer model)
+viewer/            browser 2D/3D viewer for the exported models
+docs/              specs & implementation plans
+tests/             Rust (cargo test) + Python (pytest) suites
+```
+
+## License
+
+MIT

viva_cpm-0.1.1/crates/cpm-core/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "cpm-core"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lib]
+name = "cpm_core"
+
+[dependencies]
+rand = { workspace = true, features = ["small_rng"] }
+smallvec = "1"
+rayon = "1"