Research data management and analysis for large-scale polymer molecular-dynamics simulations, built around the study of bacterial chromosome organization under macromolecular crowding.
A single parameter sweep in a coarse-grained LAMMPS study produces tens of thousands of files. The physics of each run — chain length, confinement geometry, crowder size and count, timestep, dump frequency — is encoded in its filename, and each physical state point is repeated across independent replicates that must eventually collapse into one number with an honest error bar.
That leaves two recurring problems, and PolyPhys is built around them:
- The filesystem is the database, but nothing can query it. Filenames carry the physics, yet they are opaque strings.
- Replicates must be reduced correctly. Averaging correlated molecular-dynamics frames with a naive standard error understates the uncertainty.
Every simulation artifact sits at one of five levels of a hierarchy, and each level is a well-defined aggregation of the one before it:
segment → whole → ensemble_long → ensemble → space
a chunk a full one state replicates the whole
of a run trajectory point, verbose collapsed parameter sweep
polyphys.manage.parser decodes a filename into typed physical attributes
and derives that artifact's ancestry, so a file knows which state point and
which sweep it belongs to. Once artifacts know their lineage,
polyphys.manage.organizer can walk the hierarchy and reduce it level by
level.
From v1.0.0, PolyPhys is on PyPI, and each release is archived on Zenodo:
python -m pip install polyphysWith uv, install it into the active environment, or add it as a dependency of a uv project:
uv pip install polyphys
uv add polyphysFrom v1.0.0, PolyPhys is also on conda-forge:
conda install -c conda-forge polyphysThe conda package installs the runtime dependencies only. mdanalysis is
needed by the probe layer and matplotlib-base by the viz layer's figure
helpers; install the ones you need alongside PolyPhys:
conda install -c conda-forge mdanalysis matplotlib-baseWhen they are installed, the package requires MDAnalysis 2.8 and matplotlib
3.8.4 or newer, the floors of the mda and viz extras.
Releases before v1.0.0 are not on PyPI; install one from its tag:
python -m pip install "git+https://github.com/amirhs1/PolyPhys.git@v1.0.0"For a development checkout:
git clone https://github.com/amirhs1/PolyPhys.git
cd PolyPhys
python -m pip install -e ".[dev,viz]"The viz extra installs matplotlib, which the doctests of polyphys/viz/
import; without it the documented test command stops with an ImportError.
Requires Python 3.11+. The runtime dependencies are NumPy 2.0 or newer, pandas
3.0 or newer, and SciPy 1.14.1 or newer. The probe layer, which reads LAMMPS
trajectories, needs MDAnalysis as well; the mda extra installs it:
python -m pip install "polyphys[mda]"The viz layer's figure helpers need matplotlib 3.8.4 or newer; the viz extra
installs it (the color lists in viz.colors need nothing extra):
python -m pip install "polyphys[viz]"A study declares a parser, a subclass of ParserBase that lists the
keywords of its file names. This short one reads a linear chain among
crowders in a cylinder; the
Studies page shows
the full declaration:
>>> from polyphys.manage.parser import KeywordSpec, ParserBase
>>> keys = ('N', 'D', 'ac', 'nc', 'bdump')
>>> class ChainCyl(ParserBase):
... """A linear chain among crowders in a cylinder."""
... _geometry = 'cylindrical'
... _topology = 'linear'
... _groups = ['bug']
... _dump_keywords = {'bug': 'bdump'}
... _keywords = {
... 'N': KeywordSpec('nmon', int),
... 'D': KeywordSpec('dcyl', float),
... 'ac': KeywordSpec('dcrowd', float),
... 'nc': KeywordSpec('ncrowd', int),
... 'bdump': KeywordSpec('bdump', int),
... 'ens': KeywordSpec('ensemble_id', int),
... 'j': KeywordSpec('segment_id', int),
... }
... _patterns = {
... 'segment': (*keys, 'ens', 'j'), 'whole': (*keys, 'ens'),
... 'ensemble_long': keys, 'ensemble': ('N', 'D', 'ac', 'nc'),
... 'space': ('N', 'D', 'ac'),
... }
... _project_attributes = dict.fromkeys(
... ('segment', 'whole', 'ensemble_long', 'ensemble', 'space'), [])A file name then decodes into typed physical attributes, and into the name of the artifact at every level of the lineage above it, without touching the file system:
>>> artifact = ChainCyl('N200D20ac2nc1000bdump2000ens1.j03',
... lineage='segment', group='bug')
>>> artifact.nmon, artifact.ncrowd, float(artifact.dcrowd)
(200, 1000, 2.0)
>>> for level in artifact.lineage_genealogy:
... print(f'{level:13} {getattr(artifact, level)}')
segment N200D20ac2nc1000bdump2000ens1.j03
whole N200D20ac2nc1000bdump2000ens1
ensemble_long N200D20ac2nc1000bdump2000
ensemble N200D20ac2nc1000
space N200D20ac2The segments of one run share their whole name, the replicates of one
state point their ensemble_long name, and the state points of one sweep
their space name, so the organizer groups and averages them by name. The
quickstart of
the documentation runs a small synthetic sweep from its segments to its
space table, and the
Lineage page shows
what else a parser derives, such as the cylinder size and the bulk volume
fractions.
One short purpose per module; each guide page and the API reference give the
details. probe needs the mda extra and viz.helpers the viz extra.
| Module | Purpose | Guide |
|---|---|---|
spec |
Study, probe, and analysis records shared across the workflow; no MDAnalysis. | Studies |
manage.parser |
File name to typed physical attributes and lineage names. | Lineage |
manage.organizer |
Join segments into wholes and reduce replicates to ensemble averages. | Workflow |
manage.utils |
File sorting, file opening, and number-density and volume-fraction conversions. | API |
manage.types |
Type aliases of the vocabulary, such as LineageT and PhaseT. |
API |
simulate.core |
The LAMMPS box and the readers' base error. | Simulate |
simulate.log |
Read LAMMPS log files into DataFrames. | Simulate |
simulate.dump |
Read LAMMPS text dumps, one frame at a time. | Simulate |
simulate.data |
Read and write LAMMPS data files. | Simulate |
simulate.build |
Build bead-spring start configurations for LAMMPS. | Simulate |
probe.core |
Open a whole's data file and dump as an MDAnalysis universe. | Probe |
probe.chain_size |
Chain size and shape in every frame. | Probe |
probe.binders |
Binding of two-patch binders to the chain in every frame. | Probe |
probe.histograms |
Spatial histograms of every species. | Probe |
probe.pairs |
Pair distances, contacts, and clusters of one species. | Probe |
analyze.measurer |
Per-frame structural measures and histograms of one frame. | Usage |
analyze.stats |
Errors of time averages over correlated frames, by blocking. | Statistics |
analyze.clusters |
Contacts, clusters, and binding statistics of one frame. | Clusters |
analyze.correlations |
Autocorrelations, decay fits, and bond correlations. | Correlations |
analyze.sumrule |
The density sum rule on a space's density profiles. | Density |
analyze.density |
Local number-density and volume-fraction profiles. | Density |
analyze.pipeline |
Reduce a space's probe artifacts down the lineage. | Pipeline |
viz.colors |
The color lists of the studies' figures. | Viz |
viz.helpers |
Matplotlib helpers for ticks, legends, and bands. | Viz |
The package ships no study's parser: each study declares its own
ParserBase subclass in its own folder. The parsers of the maintainer's
published studies are in the companion repository
polyphys-lab.
The full documentation, including the API reference, is at
polyphys.readthedocs.io. Its
quickstart runs a synthetic sweep from segments to a space table, and its
lineage, workflow, and studies pages explain the phases, the steps from
trajectories to a space, and how to add a study. To build it locally:
python -m pip install -e ".[docs]"
python -m sphinx -W -b html docs/source docs/_buildFrom 1.0.0, PolyPhys follows semantic versioning: a backward-incompatible
change to a stable module comes only in a major release, while polyphys.probe
and polyphys.viz stay provisional, as the
API stability page
sets out. It is used to produce published research results, and the parsing
and measurement layers are covered by tests that run against Python 3.11,
3.12, 3.13, and 3.14 on every pull request and every push to main; the probe
layer's tests run on Python 3.14 with MDAnalysis.
The Python examples above run as doctests in the test suite.
A study uses PolyPhys from outside the package rather than extending it: its parser and its specs live in its own folder, as polyphys-lab shows.
PolyPhys was migrated from the maintainer's private research code, which the documentation, docstrings, and tests call the research code; the documentation's Where PolyPhys comes from says what that means for a reader.
If you use PolyPhys in published work, please cite the archived release. The
DOI above resolves to the latest version; see CITATION.cff
for machine-readable metadata, or use GitHub's Cite this repository button.
PolyPhys is developed with the help of AI coding assistants. Every change is
reviewed and merged by the maintainer, who is accountable for the result; no AI
system is an author of this software or of any release. Numerical fixtures,
formulas, and citations are derived or verified rather than accepted from a
model — see AI-POLICY.md for the full policy, including what
is expected of AI-assisted contributions.
Each part has a tier, set by whether I can evaluate AI output there. The table records the checks or human review applied to each part:
- Instrumented — I could write it myself. AI is used for review, refactoring, and alternative implementations, not first drafts of core logic.
- Supervised — AI drafts; I read every line and set the acceptance criteria and test values.
- Delegated — AI generates; I can't fully evaluate it. It is covered by tests, kept isolated and low-risk, and not presented as my work.
| Part | Tier | Checks or human review |
|---|---|---|
polyphys/analyze/ |
Supervised | CI: flake8, mypy, pytest with doctests on Python 3.11–3.14; maintainer review of every line |
polyphys/manage/ |
Supervised | CI: flake8, mypy, pytest with doctests on Python 3.11–3.14; parser tests for filename-parsing changes; maintainer review of every line |
polyphys/simulate/ |
Supervised | CI: flake8, mypy, pytest with doctests on Python 3.11–3.14; tests against LAMMPS-written files; maintainer review of every line |
polyphys/probe/ |
Supervised | CI: flake8, mypy; pytest with doctests on Python 3.14 with MDAnalysis installed; maintainer review of every line |
polyphys/viz/ |
Supervised | CI: flake8, pytest with doctests on Python 3.11–3.14 with matplotlib installed; maintainer review of every line |
polyphys/tests/, .github/workflows/, pyproject.toml |
Supervised | CI on every pull request: lint, type-check, tests, docs build, package build; maintainer review of every line |
docs/ |
Supervised | CI: Sphinx build with warnings as errors for docs/source/; maintainer review of every line |
Nothing that handles security, credentials, private data, or published results, or that can block a merge, is Delegated. Where a tier is unclear, I treat the part as Supervised. Tiers last reviewed: 2026-11-08.
Instructions for AI agents: AGENTS.md.
Bug reports and questions are welcome via
issues. Please see
SECURITY.md for reporting suspected vulnerabilities privately.
See CONTRIBUTING.md for how to contribute.
MIT — see LICENSE.