New Analysis Contributor Path

This landing page is for contributors who want to add a new PolyzyMD analysis plugin or make a safe change to an existing plugin. It is a map of the contributor path, not the tutorial itself.

Use it if you know Python and molecular simulation concepts, but are still learning how PolyzyMD connects MDAnalysis trajectory work to replicate artifacts, condition aggregation, cross-condition comparison, and plotting.

Start

Begin here when you are new to contributing analysis code.

• Set Up a Contributor Environment — install the pixi-managed environment used by docs, tests, and local development.

• Contributing to PolyzyMD — learn the branch, review, and verification expectations for small, reviewable changes.

• Architecture — orient to the package layout before narrowing in on analysis plugins.

• How PolyzyMD analysis plugins work — understand the plugin lifecycle, public facades, artifacts, sidecars, and artifact-only plotting.

Build

Use these pages when you are creating your first plugin or replacing scaffolded placeholder logic with real analysis code.

• Scaffold your first analysis plugin — generate a single-file plugin and matching tests with a throwaway name such as solvent_shell.

• Build a simple scalar analysis plugin — connect one function job, collector, default aggregation path, and scalar comparison.

• Extend PolyzyMD with MDAnalysis-native analyses — use the full implementation guide for current scaffold patterns, public imports, MDAAnalysisJob, collectors, artifacts, default comparison, and artifact-only plotting.

Scale

Use these pages when a working plugin needs richer stored data or a larger module shape.

• Store large analysis outputs with artifact sidecars — persist NPZ arrays, CSV tables, and other bulky outputs beside artifacts without bloating JSON.

• Convert a plugin into an advanced package — split a single-file plugin into _mda.py, _plotters.py, _models.py, or _formatters.py helpers when reviewability improves.

Verify

Use these pages before opening a pull request or reviewing one.

• Test your analysis plugin contribution — cover discovery, settings validation, MDAnalysis jobs, collectors, artifacts, sidecars, aggregation, comparison metrics, and artifact-only plotting.

• Analysis plugin contribution checklist — confirm the plugin contract, import boundaries, tests, docs updates, and PR-ready commands.

Reference

Use these lookup pages when you need exact import paths, commands, or settings.

• API map for analysis plugin contributors — find stable public imports and the nearest API reference page without browsing internals.

• Analysis plugin API, analysis base classes, MDAnalysis integration, and shared analysis utilities — inspect the API reference directly.

• CLI reference and analysis plugin settings reference — look up commands and comparison.yaml plugin options.

Public and private import guardrails

Contributor-facing plugin code should use public facades:

• polyzymd.analyses.base for Analysis, lifecycle contexts, MetricValue, and comparison result models.

• polyzymd.analyses.mda for MDAnalysis jobs, frame selection, artifacts, artifact stores, aggregation helpers, and comparison helpers.

• documented utilities from polyzymd.analyses.shared when an existing shared helper fits the task.

Do not import from polyzymd.analyses._framework in contributor plugins. That package is an internal implementation detail behind the public facades.