Plugin lifecycle and collectors

MDAReplicateJobContext is passed to Analysis.build_mda_jobs(). It carries the loaded universe, frame selection, universe policy, settings, replicate identity, and artifact output location.

MDACollectorContext is passed to Analysis.build_mda_collector(). A collector maps completed MDAJobResult objects into one ReplicateArtifact. Collectors must convert raw MDAnalysis Results objects into JSON-compatible payloads or sidecars before returning the artifact.

Lifecycle bridge between PolyzyMD replicates and MDAnalysis jobs.

class polyzymd.analyses.mda.lifecycle.MDAReplicateJobContext(replicate_context, universe, frame_selection, universe_policy, artifact_store)[source]

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)

polyzymd.analyses.mda.lifecycle.build_mda_replicate_job_context(analysis, ctx, replicate)[source]

Build the MDAnalysis job context for one replicate.

Parameters:

analysis (Any) – Analysis instance requesting an MDAnalysis job context.
ctx (ReplicateContext) – Framework-provided replicate context.
replicate (int) – One-indexed replicate ID.

Returns:

Context containing the loaded universe, resolved frame selection, universe policy, and artifact store.

Return type:

MDAReplicateJobContext

polyzymd.analyses.mda.lifecycle.run_mda_replicate_jobs(analysis, ctx, replicate)[source]

Run MDAnalysis jobs for one replicate and collect a strict artifact.

Parameters:

analysis (Any) – Analysis instance with a build_mda_jobs() hook.
ctx (ReplicateContext) – Framework-provided replicate context.
replicate (int) – One-indexed replicate ID.

Returns:

Collected replicate artifact, or None when the hook declines the MDA path.

Return type:

ReplicateArtifact or None

Collector interfaces for MDAnalysis job outputs.

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

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__()[source]

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.plugin.MDAArtifactCollector(*args, **kwargs)[source]

Bases: Protocol

Protocol for converting completed MDAnalysis jobs to an artifact.

__call__(ctx, completed_jobs)[source]

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.plugin.StrictJSONMDAResultCollector[source]

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)[source]

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.plugin.frame_selection_payload(frame_selection)[source]

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.plugin.strict_json_payload(value, *, analysis_name)[source]

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