Skip to main content

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

  1. Resolve structures — RCSB PDB / mmCIF (large assemblies) or AlphaFold DB (by UniProt accession), cached locally. (Also accepts a local file.)
  2. Mesh each to Van-der-Waals surface LODs (via parsimony mesh).
  3. Author a 2.1-parsimony recipe (capsule cell, interior/surface regions, supercoiled rod nucleoid) + a staged octree pipeline + an ingredient metadata sidecar (display names + categories).
  4. 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, or
  • PARSIMONY_HOME — the parsimony repo (built: cargo build --release), or
  • have parsimony on PATH.

(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 molecular counts (input) + a structural spec (config), emitting the pack result on its pack output.
  • 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), or file (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.

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)

Source distribution for viva-parsimony 0.1.0
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)

Table of built distributions (wheels) for viva-parsimony 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page