viva-parsimony
Reusable process-bigraph packing of 3D whole-cell structural models. It wraps the parsimony engine (a cellPACK-style molecular packer) and turns a list of molecular ingredients + cell geometry into a packed 3D cell that the parsimony viewer (or any compatible viewer) can render.
It is organism-agnostic: the caller supplies which molecules, their abundances, names and categories, and the structure source for each. A whole-cell model such as v2ecoli provides those; viva-parsimony does the structure resolution, recipe authoring, and packing.
See it live
Explore a 3D whole-cell E. coli model in your browser →
Hundreds of molecular species packed at true abundance from a
v2ecoli cell state — ribosomes,
RNA polymerase, metabolic enzymes, the supercoiled chromosome, flagella. Switch
between a newborn cell and a pre-division cell (two segregated,
daughter-centered chromosomes), toggle/isolate species by functional category,
and "View in VR" on a Meta Quest. This whole scene is built by viva-parsimony
and rendered in the bundled viewer (viva_parsimony/viewer/).
What it does
- Resolve structures — RCSB PDB / mmCIF (large assemblies) or AlphaFold DB
(by UniProt accession), cached locally. (Also accepts a local
file.) - Mesh each to Van-der-Waals surface LODs (via
parsimony mesh). - Author a
2.1-parsimonyrecipe (capsule cell, interior/surface regions, supercoiled rod nucleoid) + a staged octree pipeline + an ingredient metadata sidecar (display names + categories). - Pack with the parsimony octree engine → a
*.pack.json.
Install
uv venv
uv pip install -e ".[dev]"
Requires Python >= 3.10. process-bigraph and bigraph-schema are pulled from
their main branches (see [tool.uv.sources] in pyproject.toml); use uv so
those sources are honored.
Runtime requirement: the parsimony binary
Packing shells out to the parsimony binary, which must be reachable. Set one of:
PARSIMONY_BIN— path to the binary, orPARSIMONY_HOME— the parsimony repo (built:cargo build --release), or- have
parsimonyonPATH.
(Structure relaxation additionally needs OpenMM; see StructureRelaxStep below.)
Interactive demo
Pack a small example cell (real PDB structures + a lipid membrane in a capsule) and explore it in the bundled 3D viewer:
PARSIMONY_HOME=/path/to/parsimony python -m viva_parsimony.demo
# or, after install: viva-parsimony-demo
It builds the pack, assembles a self-contained viewer app, and opens it in your
browser. The ingredient panel groups molecules by category, is searchable, and
lets you toggle/isolate each species. The same composite is catalogued at
viva_parsimony/composites/parsimony-demo.composite.yaml for the
vivarium-dashboard.
Python API
from viva_parsimony import build_pack, Ingredient, Capsule, Chromosome, StructureRef
ingredients = [
Ingredient("ribosome", count=6000, region="interior",
structure=StructureRef("cif", "4YBB"),
display_name="70S ribosome", category="Translation",
color=(0.95, 0.55, 0.25)),
Ingredient("ompA", count=20000, region="surface",
structure=StructureRef("alphafold", "P0A910"),
display_name="outer membrane protein A", category="Envelope",
color=(0.8, 0.55, 0.85)),
# lipids can use a cheap sphere proxy instead of a meshed structure:
Ingredient("lipid", count=6000, region="surface", sphere_radius=12.0),
]
result = build_pack(
ingredients,
Capsule.from_volume_fl(1.15), # cell volume in fL
Chromosome(genome_csv="ecoli_k12_genes.csv",
segment=StructureRef("pdb", "1BNA")),
out_dir="out/ecoli", name="ecoli_3d", scale=0.3,
)
print(result["n_placed"], result["pack_path"])
build_pack returns {pack_path, sidecar_path, recipe_path, pipeline_path, n_placed, ingredients}. Structures cache under <out_dir>/structures and meshes
under <out_dir>/meshes.
Passing envelope={"inner": Capsule(...), "outer": Capsule(...)} builds a
gram-negative two-membrane envelope; ingredients are then routed into nested
compartments by Ingredient.compartment (cytoplasm | periplasm |
inner_membrane | outer_membrane).
In a process-bigraph composite
from viva_parsimony import register_parsimony
register_parsimony(core) # makes local:ParsimonyPackStep / local:StructureRelaxStep resolve
ParsimonyPackStep— packs a cell from live molecularcounts(input) + a structuralspec(config), emitting the pack result on itspackoutput.StructureRelaxStep— opt-in upstream Step that rewrites each ingredient's fetched structure to a cached water-relaxed structure (OpenMM) before packing;relax=False(default) passes structures through unchanged.
API overview
Exported from the top-level viva_parsimony package:
build_pack— high-level entry point: resolve + mesh structures, author the recipe, and pack the cell.Ingredient— one molecular species to place (structure or sphere proxy, region/compartment, count, display metadata).Capsule— spherocylinder cell geometry;Capsule.from_volume_fl(...)sizes it to a cell volume.Chromosome— a supercoiled rod nucleoid (replication state, forks, nascent RNA/ribosome/peptide placements, septum constriction).StructureRef— a structure source:pdb/cif(RCSB id),alphafold(UniProt accession), orfile(local path).find_parsimony_bin/ParsimonyNotFound— locate the parsimony binary (raises if unreachable).ParsimonyPackStep/StructureRelaxStep/register_parsimony— the process-bigraph Steps and their registration helper.
A back-compatibility shim distribution (pbg-parsimony, under shim/)
re-exports viva_parsimony for the package's former name.
Links
- Repository: https://github.com/vivarium-collective/viva-parsimony
- parsimony engine: https://github.com/prismofeverything/parsimony
- process-bigraph: https://github.com/vivarium-collective/process-bigraph
A project of the Vivarium Collective.
Metadata
Release files for viva-parsimony 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| viva_parsimony-0.1.0.tar.gz | 102.7 kB | With provenance | Details for viva_parsimony-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| viva_parsimony-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for viva_parsimony-0.1.0-py3-none-any.whl |
Total release size: 203.7 kB
Release files / viva_parsimony-0.1.0.tar.gz
| Download URL | viva_parsimony-0.1.0.tar.gz |
|---|---|
| Size | 102.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7ee2d103fd2d159a71771cdbd1cfcd6840fdc7312791e2e708b1a8816c818688
|
|
BLAKE2b-256 checksum How to use checksums |
0ddbcd1783ec85ea5800390e3a16ac90f0f791b89e888b7d6c419906879e3aa0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / viva_parsimony-0.1.0-py3-none-any.whl
| Download URL | viva_parsimony-0.1.0-py3-none-any.whl |
|---|---|
| Size | 101.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a38c04a8bc313126fdbbcffc2703d5090d506d2c38a6535a5c996fc4550070a6
|
|
BLAKE2b-256 checksum How to use checksums |
99ece20d8ec170a2651eaec796f0bce5c8e0fa407a088cd91626cdaa310a913c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for viva-parsimony 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for viva_parsimony-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.