Public facade

polyzymd.analyses.mda re-exports the public MDAnalysis extension-layer symbols used by analysis plugins. Contributors should import from this facade instead of importing private implementation modules directly.

Public MDAnalysis extension-layer primitives.

This package exposes import-light protocol and typing helpers for integrations that wrap MDAnalysis AnalysisBase objects without importing MDAnalysis at module import time.

class polyzymd.analyses.mda.AnalysisBaseLike(*args, **kwargs)

Bases: Protocol

Structural protocol for MDAnalysis AnalysisBase-style objects.

results: Any

run(**kwargs)

Run the analysis and return the analysis object.

Parameters:

**kwargs (Any) – Keyword arguments forwarded to the wrapped analysis object’s run() method.

Returns:

The analysis object after execution.

Return type:

AnalysisBaseLike

__init__(*args, **kwargs)

exception polyzymd.analyses.mda.MDAnalysisExtensionError

Bases: RuntimeError

Base runtime error for MDAnalysis extension-layer failures.

class polyzymd.analyses.mda.MDARunKwargs

Bases: TypedDict

Keyword arguments accepted by MDAnalysis.analysis.base.AnalysisBase.run.

The value types stay intentionally broad where MDAnalysis accepts multiple backend or frame-selector forms. This keeps the public extension-layer type import-light and independent of optional MDAnalysis runtime objects.

start: int | None

stop: int | None

step: int | None

frames: Any

verbose: bool | None

progressbar_kwargs: dict[str, Any] | None

backend: Any

n_workers: int | None

n_parts: int | None

unsupported_backend: bool | None

class polyzymd.analyses.mda.AggregatedMetric(*, name, values=<factory>, mean, sem, std, n)

Bases: BaseModel

Summary statistics for one metric across biological replicates.

name: str

values: list[float]

mean: float

sem: float

std: float

n: int

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.ExplicitReplicateMetricPolicy

Bases: object

Extract explicitly declared replicate-level scalar metrics.

The default policy deliberately reads only payload["metrics"] or payload["replicate_metrics"]. It does not reduce arrays, events, job tables, or frame-level values because those reductions are analysis-specific scientific choices.

extract_metrics(artifact)

Return validated scalar metrics from a replicate artifact.

Parameters:

artifact (ReplicateArtifact) – Artifact produced for one replicate.

Returns:

Validated replicate-level scalar metrics.

Return type:

Mapping[str, float]

class polyzymd.analyses.mda.MDAAggregationContext(analysis_name, condition_label, expected_replicates, settings_fingerprint=None, min_replicates=1, allow_partial=False, require_compatible_frame_selection=True, expected_frame_selection=None, validate_sidecars=True, artifact_stores=<factory>, source_replicates=(), skipped_replicates=())

Bases: object

Identity and provenance expected during condition aggregation.

analysis_name: str

condition_label: str

expected_replicates: tuple[int, ...]

settings_fingerprint: str | None = None

min_replicates: int = 1

allow_partial: bool = False

require_compatible_frame_selection: bool = True

expected_frame_selection: Mapping[str, Any] | None = None

validate_sidecars: bool = True

artifact_stores: Mapping[int, ArtifactStore]

source_replicates: Sequence[Mapping[str, Any]] = ()

skipped_replicates: Sequence[Mapping[str, Any]] = ()

__post_init__()

Normalize replicate identity and validate minimum count.

__init__(analysis_name, condition_label, expected_replicates, settings_fingerprint=None, min_replicates=1, allow_partial=False, require_compatible_frame_selection=True, expected_frame_selection=None, validate_sidecars=True, artifact_stores=<factory>, source_replicates=(), skipped_replicates=())

exception polyzymd.analyses.mda.MDAAggregationError

Bases: MDAnalysisExtensionError

Error raised when MDAnalysis replicate artifacts cannot be aggregated.

class polyzymd.analyses.mda.ReplicateMetricPolicy(*args, **kwargs)

Bases: Protocol

Protocol for reducing one replicate artifact to scalar metrics.

extract_metrics(artifact)

Extract one scalar value per metric from a replicate artifact.

Parameters:

artifact (ReplicateArtifact) – Artifact produced for one replicate.

Returns:

Metric names mapped to one replicate-level scalar each.

Return type:

Mapping[str, float]

__init__(*args, **kwargs)

polyzymd.analyses.mda.aggregate_replicate_artifacts(artifacts, ctx, policy=None)

Aggregate replicate artifacts into a condition artifact.

Parameters:

• artifacts (sequence of ReplicateArtifact) – Replicate artifacts to aggregate.

• ctx (MDAAggregationContext) – Expected condition identity and provenance.

• policy (ReplicateMetricPolicy or None, optional) – Metric extraction policy, by default ExplicitReplicateMetricPolicy.

Returns:

Aggregated condition artifact containing replicate-level statistics.

Return type:

ConditionArtifact

polyzymd.analyses.mda.aggregate_replicate_artifacts_from_disk(analysis_dir, ctx, policy=None, *, artifact_path='result.json')

Load replicate artifacts from disk and aggregate them.

Parameters:

• analysis_dir (Path) – Condition analysis directory containing run_N subdirectories.

• ctx (MDAAggregationContext) – Expected condition identity and aggregation policy controls.

• policy (ReplicateMetricPolicy or None, optional) – Optional custom metric extraction policy.

• artifact_path (str or Path, optional) – Store-relative replicate artifact filename, by default "result.json".

Returns:

Aggregated condition artifact.

Return type:

ConditionArtifact

class polyzymd.analyses.mda.ArtifactEnvelope(*, schema_version='1', artifact_type='artifact', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, **extra_data)

Bases: BaseModel

Extensible JSON envelope for MDAnalysis extension-layer artifacts.

schema_version: str

artifact_type: str

analysis_name: str

payload: dict[str, Any]

sidecars: list[ArtifactSidecarRef]

provenance: dict[str, Any]

metadata: dict[str, Any]

warnings: list[str]

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.ArtifactManifest(*, schema_version='1', analysis_name, artifact_id=None, artifact_type='manifest', polyzymd_version=None, mdanalysis_version=None, inputs=<factory>, provenance=<factory>, sidecars=<factory>, metadata=<factory>, **extra_data)

Bases: BaseModel

Manifest for one artifact directory and its sidecar files.

schema_version: str

analysis_name: str

artifact_id: str | None

artifact_type: str

polyzymd_version: str | None

mdanalysis_version: str | None

inputs: dict[str, Any]

provenance: dict[str, Any]

sidecars: list[ArtifactSidecarRef]

metadata: dict[str, Any]

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.ArtifactSidecarRef(*, path, sha256, size_bytes, media_type=None, metadata=<factory>, **extra_data)

Bases: BaseModel

Relative reference to a sidecar file owned by an artifact store.

path: str

sha256: str

size_bytes: int

media_type: str | None

metadata: dict[str, Any]

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.ComparisonArtifact(*, schema_version='1', artifact_type='comparison', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, conditions=<factory>, control_label=None, effective_control=None, **extra_data)

Bases: ArtifactEnvelope

Cross-condition comparison artifact.

artifact_type: Literal['comparison']

conditions: list[str]

control_label: str | None

effective_control: str | None

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.ConditionArtifact(*, schema_version='1', artifact_type='condition', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, condition_label, replicates=<factory>, source_replicates=<factory>, skipped_replicates=<factory>, **extra_data)

Bases: ArtifactEnvelope

Aggregated artifact produced for one simulation condition.

artifact_type: Literal['condition']

condition_label: str

replicates: list[int]

source_replicates: list[dict[str, Any]]

skipped_replicates: list[dict[str, Any]]

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.ReplicateArtifact(*, schema_version='1', artifact_type='replicate', analysis_name, payload=<factory>, sidecars=<factory>, provenance=<factory>, metadata=<factory>, warnings=<factory>, condition_label, replicate, **extra_data)

Bases: ArtifactEnvelope

Result artifact produced for one replicate trajectory.

artifact_type: Literal['replicate']

condition_label: str

replicate: int

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.analyses.mda.ArtifactStore(root)

Bases: object

Store JSON artifacts and relative sidecars under one root directory.

__init__(root)

Create an artifact store rooted at root.

Parameters:

root (str or Path) – Directory that owns artifact JSON files and sidecars.

write_replicate_result(artifact, path='result.json')

Write a replicate artifact JSON file.

Parameters:

• artifact (ReplicateArtifact) – Replicate artifact envelope to serialize.

• path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Absolute path to the written JSON file.

Return type:

Path

read_replicate_result(path='result.json')

Read a replicate artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Deserialized replicate artifact.

Return type:

ReplicateArtifact

write_condition_result(artifact, path='result.json')

Write a condition artifact JSON file.

Parameters:

• artifact (ConditionArtifact) – Condition artifact envelope to serialize.

• path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Absolute path to the written JSON file.

Return type:

Path

read_condition_result(path='result.json')

Read a condition artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Deserialized condition artifact.

Return type:

ConditionArtifact

write_comparison_result(artifact, path='result.json')

Write a comparison artifact JSON file.

Parameters:

• artifact (ComparisonArtifact) – Comparison artifact envelope to serialize.

• path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Absolute path to the written JSON file.

Return type:

Path

read_comparison_result(path='result.json')

Read a comparison artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "result.json".

Returns:

Deserialized comparison artifact.

Return type:

ComparisonArtifact

write_manifest(manifest, path='manifest.json')

Write an artifact manifest JSON file.

Parameters:

• manifest (ArtifactManifest) – Manifest to serialize.

• path (str or Path, optional) – Store-relative JSON path, by default "manifest.json".

Returns:

Absolute path to the written manifest.

Return type:

Path

read_manifest(path='manifest.json')

Read an artifact manifest JSON file.

Parameters:

path (str or Path, optional) – Store-relative JSON path, by default "manifest.json".

Returns:

Deserialized manifest.

Return type:

ArtifactManifest

register_sidecar(path, *, media_type=None, metadata=None)

Register an existing store-relative sidecar file.

Parameters:

• path (str or Path) – Store-relative sidecar path.

• media_type (str or None, optional) – Optional sidecar content type.

• metadata (dict[str, Any] or None, optional) – Sidecar metadata to copy into the reference.

Returns:

Relative sidecar reference with streamed SHA-256 and size metadata.

Return type:

ArtifactSidecarRef

write_npz_sidecar(path, *, compressed=True, media_type='application/x-npz', metadata=None, **arrays)

Write NumPy arrays to an NPZ sidecar and register it.

Parameters:

• path (str or Path) – Store-relative sidecar path.

• compressed (bool, optional) – Whether to use numpy.savez_compressed, by default True.

• media_type (str or None, optional) – Sidecar media type stored in the reference.

• metadata (dict[str, Any] or None, optional) – Additional sidecar metadata.

• **arrays (Any) – Named arrays forwarded to NumPy.

Returns:

Registered NPZ sidecar reference.

Return type:

ArtifactSidecarRef

resolve_sidecar(ref)

Resolve a sidecar reference to an absolute path under the store root.

Parameters:

ref (ArtifactSidecarRef or str or Path) – Sidecar reference or store-relative path.

Returns:

Absolute sidecar path under the store root.

Return type:

Path

validate_sidecar(ref)

Validate sidecar existence, size, path containment, and SHA-256.

Parameters:

ref (ArtifactSidecarRef) – Sidecar reference to validate.

Returns:

Absolute sidecar path when validation passes.

Return type:

Path

load_npz_sidecar(ref)

Validate and open an NPZ sidecar.

Parameters:

ref (ArtifactSidecarRef) – Sidecar reference to validate before loading.

Returns:

Open numpy.load handle. Callers should use it as a context manager to close the underlying file promptly.

Return type:

Any

source_artifact_ref(path='result.json')

Return a hashed reference for an artifact JSON file.

Parameters:

path (str or Path, optional) – Store-relative artifact path, by default "result.json".

Returns:

Relative path, SHA-256 digest, and size metadata for the artifact.

Return type:

dict[str, Any]

exception polyzymd.analyses.mda.ArtifactStoreError

Bases: MDAnalysisExtensionError

Error raised when artifact-store path or validation checks fail.

class polyzymd.analyses.mda.MDAComparisonContext(analysis_name, project_name, expected_condition_labels=None, expected_replicates_by_condition=None, control_label=None, effective_control=None, equilibration='0ns', settings_fingerprint=None, min_replicates=1, fdr_alpha=0.05, ttest_method='student', posthoc_method='ttest_bh')

Bases: object

Identity and statistical controls for condition-artifact comparison.

analysis_name: str

project_name: str

expected_condition_labels: Sequence[str] | None = None

expected_replicates_by_condition: Mapping[str, Sequence[int]] | None = None

control_label: str | None = None

effective_control: str | None = None

equilibration: str = '0ns'

settings_fingerprint: str | None = None

min_replicates: int = 1

fdr_alpha: float = 0.05

ttest_method: str = 'student'

posthoc_method: str = 'ttest_bh'

__post_init__()

Normalize expected identity inputs and reject ambiguous values.

__init__(analysis_name, project_name, expected_condition_labels=None, expected_replicates_by_condition=None, control_label=None, effective_control=None, equilibration='0ns', settings_fingerprint=None, min_replicates=1, fdr_alpha=0.05, ttest_method='student', posthoc_method='ttest_bh')

exception polyzymd.analyses.mda.MDAComparisonError

Bases: MDAnalysisExtensionError

Error raised when condition artifacts cannot be compared.

polyzymd.analyses.mda.compare_condition_artifacts(artifacts, ctx)

Compare aggregate condition artifacts with replicate-level statistics.

Parameters:

• artifacts (sequence of ConditionArtifact) – Condition artifacts produced by MDAnalysis extension-layer aggregation.

• ctx (MDAComparisonContext) – Comparison identity, expected condition labels, and statistical controls.

Returns:

Stable comparison artifact containing scalar statistics and provenance.

Return type:

ComparisonArtifact

class polyzymd.analyses.mda.FrameSelection(start=None, stop=None, step=None, frames=None, equilibration=None, equilibration_start=None, equilibration_ps=None, timestep_ps=None, first_frame_time_ps=None, selected_start_time_ps=None, equilibration_time_reference=None, n_frames_total=None, warning_message=None)

Bases: object

Validated MDAnalysis run() frame-selection arguments.

FrameSelection is the import-light bridge between PolyzyMD’s equilibration/window semantics and MDAnalysis AnalysisBase.run keyword arguments. Explicit frames selectors are mutually exclusive with start, stop, and step because MDAnalysis treats them as separate selection modes.

Parameters:

• start (int | None, optional) – Inclusive start frame passed to run(start=...).

• stop (int | None, optional) – Exclusive stop frame passed to run(stop=...).

• step (int | None, optional) – Frame stride passed to run(step=...).

• frames (Any, optional) – Explicit frame indices or boolean mask passed to run(frames=...).

• equilibration (str | None, optional) – Original equilibration setting used to derive this selection.

• equilibration_start (int | None, optional) – Start frame implied by equilibration alone.

• equilibration_ps (float | None, optional) – Equilibration time converted to picoseconds.

• timestep_ps (float | None, optional) – Trajectory timestep in picoseconds.

• first_frame_time_ps (float | None, optional) – Absolute MDAnalysis timestamp of loaded frame 0 in picoseconds, when available.

• selected_start_time_ps (float | None, optional) – Timestamp of the selected start frame in the active time reference.

• equilibration_time_reference (str | None, optional) – Time reference used to interpret equilibration.

• n_frames_total (int | None, optional) – Total trajectory frame count when known.

• warning_message (str | None, optional) – Non-fatal warning from equilibration/window validation.

start: int | None = None

stop: int | None = None

step: int | None = None

frames: Any = None

equilibration: str | None = None

equilibration_start: int | None = None

equilibration_ps: float | None = None

timestep_ps: float | None = None

first_frame_time_ps: float | None = None

selected_start_time_ps: float | None = None

equilibration_time_reference: str | None = None

n_frames_total: int | None = None

warning_message: str | None = None

n_frames_selected: int | None = None

__post_init__()

Validate mutually exclusive MDAnalysis frame-selection modes.

Raises:

ValueError – Raised when the selector would produce invalid MDAnalysis run keyword arguments or an empty known frame selection.

run_kwargs()

Return keyword arguments for MDAnalysis AnalysisBase.run.

Returns:

frames alone when explicit frames are set, otherwise the non-None start, stop, and step values.

Return type:

MDARunKwargs

classmethod from_trajectory_window(window)

Build a frame selection from a resolved PolyzyMD trajectory window.

Parameters:

window (TrajectoryWindow) – Existing validated shared trajectory window.

Returns:

Selection that forwards the same start, stop, and step values to MDAnalysis while preserving window provenance.

Return type:

FrameSelection

classmethod from_equilibration(*, equilibration, n_frames_total, timestep_ps, start=None, stop=None, step=1, min_frames=1, first_frame_time_ps=None)

Resolve PolyzyMD equilibration/window settings to a frame selection.

Finite first-frame timestamps make equilibration absolute in MDAnalysis trajectory time; missing timestamps keep the stale loaded-frame-relative origin.

Parameters:

• equilibration (str) – Equilibration time string such as "10ns".

• n_frames_total (int) – Total number of trajectory frames.

• timestep_ps (float) – Trajectory timestep in picoseconds.

• start (int | None, optional) – Absolute start frame. When None, equilibration determines the start frame.

• stop (int | None, optional) – Absolute exclusive stop frame. When None, the trajectory end is used.

• step (int, optional) – Frame stride, by default 1.

• min_frames (int, optional) – Minimum required number of selected frames, by default 1.

• first_frame_time_ps (float | None, optional) – Absolute MDAnalysis timestamp of loaded frame 0 in picoseconds.

Returns:

Validated selection suitable for MDAnalysis run().

Return type:

FrameSelection

__init__(start=None, stop=None, step=None, frames=None, equilibration=None, equilibration_start=None, equilibration_ps=None, timestep_ps=None, first_frame_time_ps=None, selected_start_time_ps=None, equilibration_time_reference=None, n_frames_total=None, warning_message=None)

class polyzymd.analyses.mda.MDAAnalysisJob(name, frame_selection=<factory>, analysis=None, analysis_factory=None, backend_policy=<factory>, universe_policy=<factory>)

Bases: object

Execute exactly one MDAnalysis AnalysisBase-compatible job.

A job receives either a ready analysis object or a zero-argument factory that constructs one. Execution merges FrameSelection.run_kwargs() with validated backend policy kwargs and calls analysis.run(**kwargs) once.

name: str

frame_selection: FrameSelection

analysis: Any = None

analysis_factory: Callable[[], Any] | None = None

backend_policy: MDABackendPolicy

universe_policy: MDAUniversePolicy

result: MDAJobResult | None = None

__post_init__()

Validate constructor misuse before execution.

Raises:

• ValueError – Raised when both or neither analysis inputs are supplied.

• TypeError – Raised when supplied inputs do not satisfy the job construction contract.

classmethod from_function(name, function, universe, *, frame_selection=None, backend_policy=None, universe_policy=None, function_kwargs=None)

Create a job from a function and already-loaded universe.

Parameters:

• name (str) – Job name used in result metadata and error messages.

• function (Callable[..., Any]) – Function called once by MDAFunctionAdapter.run.

• universe (Any) – Already-loaded universe or universe-like object.

• frame_selection (FrameSelection or None, optional) – Frame selection to forward to the function adapter.

• backend_policy (MDABackendPolicy or None, optional) – Backend policy for this job.

• universe_policy (MDAUniversePolicy or None, optional) – Lightweight universe provenance policy.

• function_kwargs (Mapping[str, Any] or None, optional) – Additional keyword arguments forwarded to the function.

Returns:

Job wrapping the function adapter.

Return type:

MDAAnalysisJob

property results: Any

Return completed job results.

Returns:

Results object from the completed analysis.

Return type:

Any

Raises:

MDAAnalysisJobError – Raised when the job has not run yet.

run()

Execute the wrapped analysis and store the completed job result.

Returns:

Completed job result reference.

Return type:

MDAJobResult

Raises:

MDAAnalysisJobError – Raised when factory construction, analysis execution, or result collection violates the runtime job contract.

execute()

Execute the job.

Returns:

Completed job result reference.

Return type:

MDAJobResult

__init__(name, frame_selection=<factory>, analysis=None, analysis_factory=None, backend_policy=<factory>, universe_policy=<factory>)

exception polyzymd.analyses.mda.MDAAnalysisJobError

Bases: MDAnalysisExtensionError

Runtime failure raised when an MDAnalysis job violates its contract.

class polyzymd.analyses.mda.MDABackendPolicy(backend=None, n_workers=None, n_parts=None, unsupported_backend=None, verbose=None, progressbar_kwargs=None)

Bases: object

Validated MDAnalysis internal backend options for one job.

The default policy forwards no backend-related keyword arguments so that PolyzyMD-level parallelism remains the default. Supplying worker, part, or unsupported-backend options requires an explicit backend to avoid ambiguous nested-parallelism requests.

backend: Any = None

n_workers: int | None = None

n_parts: int | None = None

unsupported_backend: bool | None = None

verbose: bool | None = None

progressbar_kwargs: Mapping[str, Any] | None = None

__post_init__()

Validate backend opt-in and worker/part counts.

Raises:

ValueError – Raised when worker/part counts are not positive or backend-specific options are supplied without an explicit backend.

run_kwargs()

Return keyword arguments for AnalysisBase.run.

Returns:

Non-None backend, worker, progress, and verbosity settings.

Return type:

MDARunKwargs

is_default()

Return whether the policy forwards no run() keyword arguments.

Returns:

True when no backend, progress, or verbosity options are set.

Return type:

bool

__init__(backend=None, n_workers=None, n_parts=None, unsupported_backend=None, verbose=None, progressbar_kwargs=None)

class polyzymd.analyses.mda.MDAFunctionAdapter(function, universe, *, function_kwargs=None)

Bases: object

Adapt a simple function to the MDAnalysis run()/results shape.

The function is called exactly once during run() as function(universe, **frame_kwargs, **function_kwargs). The adapter does not implement trajectory loops; functions that need frame iteration should use MDAnalysis primitives internally.

__init__(function, universe, *, function_kwargs=None)

Initialize the function adapter.

Parameters:

• function (Callable[..., Any]) – Function receiving the universe, frame kwargs, and function kwargs.

• universe (Any) – Already-loaded universe or universe-like object supplied by the caller.

• function_kwargs (Mapping[str, Any] or None, optional) – Additional keyword arguments forwarded after frame kwargs.

Raises:

TypeError – Raised when function is not callable.

results: dict[str, Any] | Any

run(**frame_kwargs)

Run the adapted function once and store normalized results.

Parameters:

**frame_kwargs (Any) – Frame-selection keyword arguments from FrameSelection.

Returns:

This adapter with results populated.

Return type:

MDAFunctionAdapter

Raises:

MDAAnalysisJobError – Raised when MDAnalysis backend or run-control kwargs are supplied directly to the function adapter.

class polyzymd.analyses.mda.MDAJobResult(name, analysis, results, run_kwargs, frame_selection, backend_policy, universe_policy)

Bases: object

Completed result reference for one MDAnalysis-compatible job.

name: str

analysis: Any

results: Any

run_kwargs: Mapping[str, Any]

frame_selection: FrameSelection

backend_policy: MDABackendPolicy

universe_policy: MDAUniversePolicy

__init__(name, analysis, results, run_kwargs, frame_selection, backend_policy, universe_policy)

class polyzymd.analyses.mda.MDAUniversePolicy(condition_label=None, replicate=None, provenance=None, metadata=<factory>)

Bases: object

Lightweight universe provenance and execution policy for one job.

This policy intentionally does not load universes. It carries only metadata and provenance from the layer that already resolved or supplied a universe.

condition_label: str | None = None

replicate: int | None = None

provenance: Any = None

metadata: Mapping[str, Any]

__post_init__()

Freeze metadata to avoid accidental mutation after job execution.

as_dict()

Serialize lightweight policy metadata to primitive values.

Returns:

Dictionary containing condition, replicate, provenance, and metadata.

Return type:

dict[str, Any]

__init__(condition_label=None, replicate=None, provenance=None, metadata=<factory>)

class polyzymd.analyses.mda.MDAReplicateJobContext(replicate_context, universe, frame_selection, universe_policy, artifact_store)

Bases: object

Context passed to Analysis.build_mda_jobs() for one replicate.

replicate_context: ReplicateContext

universe: Any

frame_selection: FrameSelection

universe_policy: MDAUniversePolicy

artifact_store: ArtifactStore

property output_dir: Path

Return the replicate output directory.

Returns:

Directory owned by this replicate analysis run.

Return type:

Path

property replicate: int

Return the one-indexed replicate ID.

Returns:

Replicate ID from the framework context.

Return type:

int

property settings: BaseModel

Return resolved plugin settings.

Returns:

Settings model supplied by the public lifecycle.

Return type:

BaseModel

property backend_policy: MDABackendPolicy

Return the MDAnalysis backend policy for job construction.

Returns:

Policy resolved from comparison configuration, or the serial default.

Return type:

MDABackendPolicy

__init__(replicate_context, universe, frame_selection, universe_policy, artifact_store)

class polyzymd.analyses.mda.PairDistanceSpec(label, selection_a, selection_b, atoms_a, atoms_b, mode_a, mode_b, threshold=None)

Bases: object

Resolved atom-group inputs for one pair-distance measurement.

Parameters:

• label (str) – Human-readable pair label.

• selection_a (str) – Original selection string for the first atom group or point.

• selection_b (str) – Original selection string for the second atom group or point.

• atoms_a (Any) – First MDAnalysis atom group.

• atoms_b (Any) – Second MDAnalysis atom group.

• mode_a (Any) – Position-reduction mode understood by shared selection helpers.

• mode_b (Any) – Position-reduction mode understood by shared selection helpers.

• threshold (float or None, optional) – Optional distance threshold in Å for downstream state summaries.

label: str

selection_a: str

selection_b: str

atoms_a: Any

atoms_b: Any

mode_a: Any

mode_b: Any

threshold: float | None = None

__init__(label, selection_a, selection_b, atoms_a, atoms_b, mode_a, mode_b, threshold=None)

polyzymd.analyses.mda.build_pair_distance_analysis(*, universe, pairs, use_pbc)

Build a lazy custom AnalysisBase for pair-distance matrices.

Parameters:

• universe (Any) – MDAnalysis universe for one trajectory.

• pairs (sequence of PairDistanceSpec) – Resolved pair specifications.

• use_pbc (bool) – Whether to request minimum-image distances from MDAnalysis.

Returns:

AnalysisBase instance whose results.distance_matrix has shape (n_pairs, n_frames) and whose results also include frame, time, and warning metadata.

Return type:

Any

polyzymd.analyses.mda.pair_distance_version()

Return the pair-distance primitive schema version.

Returns:

Version string for provenance records.

Return type:

str

class polyzymd.analyses.mda.MDAArtifactCollector(*args, **kwargs)

Bases: Protocol

Protocol for converting completed MDAnalysis jobs to an artifact.

__call__(ctx, completed_jobs)

Collect completed jobs into one replicate artifact.

Parameters:

• ctx (MDACollectorContext) – Framework-provided collector context for one replicate.

• completed_jobs (sequence of MDAJobResult) – Completed MDAnalysis-compatible jobs.

Returns:

PolyzyMD-owned artifact for this replicate.

Return type:

ReplicateArtifact

__init__(*args, **kwargs)

class polyzymd.analyses.mda.MDACollectorContext(analysis_name, replicate_context, frame_selection, universe_policy, artifact_store, settings_fingerprint=None, warnings=())

Bases: object

Context supplied to an MDAnalysis artifact collector.

The context contains framework identity and provenance for one replicate so collectors can map raw job results into PolyzyMD-owned artifacts without reaching back into the orchestrator.

analysis_name: str

replicate_context: ReplicateContext

frame_selection: FrameSelection

universe_policy: MDAUniversePolicy

artifact_store: ArtifactStore

settings_fingerprint: str | None = None

warnings: Sequence[str] = ()

__post_init__()

Freeze warning messages as strings for artifact reuse.

property condition_label: str

Return the simulation condition label.

Returns:

Condition label from the framework context.

Return type:

str

property replicate: int

Return the one-indexed replicate ID.

Returns:

Replicate ID from the framework context.

Return type:

int

property output_dir: Path

Return the replicate output directory.

Returns:

Directory owned by this replicate analysis run.

Return type:

Path

property result_path: Path

Return the canonical replicate result path.

Returns:

Canonical artifact JSON path for this replicate.

Return type:

Path

property settings: BaseModel

Return resolved plugin settings.

Returns:

Settings model supplied by the public lifecycle.

Return type:

BaseModel

__init__(analysis_name, replicate_context, frame_selection, universe_policy, artifact_store, settings_fingerprint=None, warnings=())

class polyzymd.analyses.mda.StrictJSONMDAResultCollector

Bases: object

Default collector for jobs that already return strict JSON values.

This collector preserves the P2-001 simple job behavior while rejecting raw MDAnalysis Results containers and other non-JSON values. Analyses with rich Results objects should implement a custom collector that maps data to primitive payloads and sidecars.

__call__(ctx, completed_jobs)

Collect completed jobs into a strict JSON artifact.

Parameters:

• ctx (MDACollectorContext) – Framework-provided collector context for one replicate.

• completed_jobs (sequence of MDAJobResult) – Completed MDAnalysis-compatible jobs.

Returns:

JSON-compatible replicate artifact.

Return type:

ReplicateArtifact

polyzymd.analyses.mda.frame_selection_payload(frame_selection)

Serialize frame-selection provenance to primitive values.

Parameters:

frame_selection (FrameSelection) – Frame selection used for a job or replicate context.

Returns:

JSON-compatible frame-selection metadata.

Return type:

dict[str, Any]

polyzymd.analyses.mda.strict_json_payload(value, *, analysis_name)

Convert supported values to strict JSON-compatible primitives.

Parameters:

• value (Any) – Candidate payload returned by an MDA job.

• analysis_name (str) – Analysis name for diagnostics.

Returns:

JSON-compatible primitive, list, or dictionary.

Return type:

Any

class polyzymd.analyses.mda.FileIdentity(path, format, size_bytes, mtime_ns)

Bases: object

Filesystem identity for an input topology or trajectory file.

path: Path

format: str | None

size_bytes: int

mtime_ns: int

classmethod from_path(path, file_format=None)

Create file identity metadata from a filesystem path.

Parameters:

• path (Path) – File path to identify.

• file_format (str or None, optional) – Format reported by the trajectory layout. When omitted, the file suffix is used without the leading dot.

Returns:

Path, format, size, and modification-time metadata.

Return type:

FileIdentity

as_dict()

Serialize the identity to JSON-compatible primitive values.

Returns:

Dictionary representation with the path converted to a string.

Return type:

dict[str, Any]

__init__(path, format, size_bytes, mtime_ns)

class polyzymd.analyses.mda.UniverseProvider(config, engine_override=None, loader=None, loader_factory=None)

Bases: object

Config-aware provider for MDAnalysis universes and input provenance.

config: SimulationConfig

engine_override: str | None = None

loader: _TrajectoryLoaderLike | None = None

loader_factory: LoaderFactory | None = None

__post_init__()

Validate loader injection settings after dataclass construction.

classmethod from_config(config, **kwargs)

Create a universe provider from a simulation configuration.

Parameters:

• config (SimulationConfig) – PolyzyMD simulation configuration.

• **kwargs (Any) – Optional provider settings such as engine_override, loader, or loader_factory.

Returns:

Provider that lazily instantiates the trajectory loader.

Return type:

UniverseProvider

load_universe(replicate, *, cache=True)

Load an MDAnalysis universe for a replicate through the existing loader.

Parameters:

• replicate (int) – Replicate index to load.

• cache (bool, optional) – Whether the underlying loader may reuse its universe cache, by default True.

Returns:

Loaded MDAnalysis universe from the underlying trajectory loader.

Return type:

Universe

provenance_for(replicate, *, refresh=False)

Return provenance for a replicate, computing it when needed.

Parameters:

• replicate (int) – Replicate index to inspect.

• refresh (bool, optional) – Recompute provenance even when cached, by default False.

Returns:

Input file identity and loader metadata for the replicate.

Return type:

UniverseProvenance

get_provenance(replicate)

Return cached provenance without triggering trajectory discovery.

Parameters:

replicate (int) – Replicate index whose cached provenance should be returned.

Returns:

Cached provenance when available, otherwise None.

Return type:

UniverseProvenance or None

__init__(config, engine_override=None, loader=None, loader_factory=None)

class polyzymd.analyses.mda.UniverseProvenance(replicate, working_directory, topology, trajectories, n_segments, loader_class, config_engine, engine_override=None, warnings=<factory>)

Bases: object

Provenance for one replicate universe loaded from PolyzyMD outputs.

replicate: int

working_directory: Path

topology: FileIdentity

trajectories: tuple[FileIdentity, ...]

n_segments: int

loader_class: str

config_engine: str | None

engine_override: str | None = None

warnings: tuple[str, ...]

as_dict()

Serialize provenance to JSON-compatible primitive values.

Returns:

Dictionary representation suitable for manifests and tests.

Return type:

dict[str, Any]

__init__(replicate, working_directory, topology, trajectories, n_segments, loader_class, config_engine, engine_override=None, warnings=<factory>)