Package Structure and Release Guide

Use this page when you need to understand how PolyzyMD is packaged, why the project is pixi-first, and what release automation expects from contributors.

Packaging model

PolyzyMD uses standard Python packaging for metadata and distributions, but the full molecular-simulation stack is managed by pixi. A wheel can be built with pyproject.toml, but pip alone is not the recommended full install path because OpenMM, OpenFF, AmberTools, RDKit, PACKMOL, CUDA, and full simulation workflows are supported through conda-forge environments.

For contributor and user workflows, prefer:

pixi install -e build
pixi run -e build polyzymd --help

Use pip-only installs for package metadata checks, lightweight import checks, release validation jobs that intentionally avoid the simulation stack, and best-effort analysis-only workflows through the analysis extra:

pip install ".[analysis]"

The analysis extra may install MDAnalysis and MDTraj for trajectory-analysis workflows. Label those instructions as best-effort and analysis-only; use pixi for supported full-stack science and simulation workflows.

Repository layout

PolyzyMD uses the src/ layout so tests import the installed package instead of accidentally importing files from the repository root.

polyzymd/
├── .github/workflows/        # CI, full-test, and release workflows
├── docs/source/              # Sphinx + MyST documentation
│   ├── get_started/          # Installation and quickstart pages
│   ├── tutorials/            # Learning-oriented walkthroughs
│   ├── how_to/               # Task-oriented guides
│   ├── reference/            # CLI, schema, and data-layout reference
│   ├── explanation/          # Architecture and design rationale
│   ├── contributor_guide/    # Contributor documentation
│   └── api/                  # Autodoc API pages
├── src/polyzymd/
│   ├── analyses/             # Analysis plugin system and built-in plugins
│   ├── builders/             # Molecular system construction
│   ├── cli/                  # Click command-line interface
│   ├── config/               # Pydantic configuration schema and loading
│   ├── core/                 # Shared core types
│   ├── data/                 # Bundled data and solvent/co-solvent libraries
│   ├── engines/              # Engine-specific execution/export helpers
│   ├── exporters/            # Format exporters
│   ├── simulation/           # Simulation runners and continuation support
│   ├── templates/            # Project and config templates
│   ├── utils/                # Shared utilities
│   └── workflow/             # SLURM and orchestration helpers
├── tests/
│   ├── analyses/             # Plugin and analysis-framework tests
│   ├── cli/                  # CLI tests
│   ├── config/               # Configuration tests
│   ├── engines/              # Engine integration/export tests
│   ├── exporters/            # Exporter tests
│   ├── regression/           # Regression coverage
│   ├── simulation/           # Runner and continuation tests
│   ├── utils/                # Utility tests
│   └── workflow/             # SLURM/workflow tests
├── pixi.toml                 # Conda-forge environments and tasks
├── pyproject.toml            # Python package metadata and tool config
└── README.md

pyproject.toml

pyproject.toml defines the Python package metadata, build backend, CLI entry point, and development-tool configuration.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "polyzymd"
version = "1.3.0"
requires-python = ">=3.12"

[project.scripts]
polyzymd = "polyzymd.cli.main:main"

The project currently keeps the release version in three places:

  • pyproject.toml

  • pixi.toml

  • src/polyzymd/__init__.py

When preparing a release, update all three to the same version, for example 1.3.1.

Pixi environments

Current pixi environments are:

Environment

Use

build

Local contributor environment with docs, packaging tools, molecular builders, analysis tools, NumPy 2, and flexible non-CUDA OpenMM. Use this for editing, docs, configuration, system-building checks, and package validation.

analysis

User-facing trajectory analysis, comparison, and plotting environment with Python 3.12 and NumPy 2.

test

CI/local test environment with Python 3.12, NumPy 2, builders, analysis tools, and lint/docs tools.

sim-cuda-12-4

Linux-only CUDA 12.4 simulation runtime with Python 3.12, NumPy 1.x, and OpenMM 8.1.x for clusters such as CU Boulder Blanca.

sim-cuda-12-6

Linux-only CUDA 12.6 simulation runtime with Python 3.12, NumPy 2, and current OpenMM for clusters such as PSC Bridges2.

Install the local contributor environment with:

pixi install -e build

For GPU cluster work, prepare systems in build, run simulations in the CUDA runtime environment that does not exceed the cluster driver version, then run analysis in analysis:

pixi install -e sim-cuda-12-6
pixi shell -e sim-cuda-12-6

Do not put analysis-only dependencies into sim-cuda-* environments. Those environments are intentionally lean so CUDA/OpenMM binary constraints do not force the package and analysis stack off Python 3.12 + NumPy 2. The package metadata allows numpy>=1.26,<3 so editable installs can work in both the NumPy 1.x CUDA 12.4 runtime and the NumPy 2 build/analysis/test environments; pixi features enforce the stricter per-workflow NumPy policy.

Full-stack scientific dependencies must remain pixi-managed. Do not add OpenMM, OpenFF, AmberTools, PACKMOL, RDKit, CUDA, or full simulation-stack installation instructions that ask contributors to install them into a system Python. MDAnalysis and MDTraj pip instructions are acceptable only through the .[analysis] extra and must be labeled best-effort analysis-only.

AmberTools is not part of the default v1.3 NumPy 2 build/analysis/test solve. Current AmberTools builds conflict with that stack, so document charging workflows as NAGL/OpenFF or pre-charged-molecule workflows unless a dedicated AmberTools/AM1-BCC environment is designed in response to a user issue.

Lazy imports for heavy dependencies

PolyzyMD keeps package imports lightweight by importing heavy dependencies only inside functions or methods that need them. This lets CI, docs, and metadata checks import modules that do not actually run simulations.

def load_trajectory(topology_path, trajectory_path):
    import MDAnalysis as mda

    return mda.Universe(str(topology_path), str(trajectory_path))

Avoid module-level imports of OpenMM, OpenFF, MDAnalysis, ParmEd, PDBFixer, or other simulation-stack packages in new code.

CI workflows

ci.yml

The main CI workflow runs on pushes and pull requests to main and dev.

  • Lint: installs black and ruff, then runs ruff check, black --check, and ruff format --check against the source tree.

  • Type check: installs lightweight Python dependencies and runs mypy against src/polyzymd/config/. This job is informational and currently uses continue-on-error because many simulation-stack packages do not provide full type stubs.

  • Build package: builds the sdist/wheel with python -m build and validates distributions with twine check.

  • Docs build: uses the pixi build environment and treats Sphinx warnings as errors with SPHINXOPTS="-W --keep-going".

  • Test installation: installs the built wheel, checks basic imports, and verifies polyzymd --help and polyzymd --version.

full-test.yml

The full test workflow runs on pushes and pull requests to main and dev, on a weekly schedule, and by manual dispatch. It uses the pixi test environment on Ubuntu and macOS with Python 3.12, then runs:

pixi run -e test pytest -v --cov=polyzymd --cov-report=xml --color=yes tests/

Coverage upload is attempted with Codecov but does not fail the workflow if the upload fails.

release.yml

The release workflow runs when a tag matching v*.*.* is pushed. It:

  1. builds and twine checks the distributions,

  2. publishes non-prerelease tags to PyPI through trusted publishing, and

  3. creates a GitHub release with generated notes and attached distributions.

Release checklist

For a normal version bump:

  1. Update the version in pyproject.toml, pixi.toml, and src/polyzymd/__init__.py.

  2. Run focused checks for the changed files, then at minimum run the docs build before handing off for release review:

    pixi run -e build make -C docs clean html

  3. Commit the version bump with a focused message, such as chore(release): bump version to 1.3.1.

  4. After review, tag the release, for example v1.3.1. The tag triggers release.yml.

Best practices

  • Keep __init__.py lightweight and preserve lazy imports.

  • Keep the full simulation stack in pixi environments.

  • Keep pip analysis-extra instructions clearly labeled as best-effort analysis-only workflows.

  • Use src/ layout conventions for new package modules.

  • Update docs, tests, CLI help, and configuration reference pages when behavior changes.

  • Do not commit generated caches, trajectories, build artifacts, or local environment files.

See also