Job execution

MDAAnalysisJob represents one named MDAnalysis-compatible analysis run on one replicate. It forwards FrameSelection kwargs to the wrapped object’s run() method and returns an MDAJobResult with the completed analysis and its results.

MDAFunctionAdapter is the simple-function path used by the default scaffold. It calls a function once with a loaded universe and frame-selection kwargs; it does not implement a custom frame loop. Functions that need per-frame iteration should use MDAnalysis primitives internally or be replaced by an AnalysisBase subclass.

MDABackendPolicy controls optional MDAnalysis internal backends. The default policy forwards no backend kwargs so PolyzyMD-level parallelism remains the default. In comparison.yaml, the top-level mda_backend_policy section maps to this object and is intentionally opt-in:

mda_backend_policy:
  backend: "multiprocessing"
  n_workers: 2
  n_parts: 2

Leave the section empty or omit it to forward no backend kwargs. Function-adapter jobs reject non-default backend policies; use an AnalysisBase-compatible job when opting into MDAnalysis internal parallelism.

Job execution primitives for MDAnalysis-compatible analyses.

exception polyzymd.analyses.mda.job.MDAAnalysisJobError[source]

Bases: MDAnalysisExtensionError

Runtime failure raised when an MDAnalysis job violates its contract.

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

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

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

Return keyword arguments for AnalysisBase.run.

Returns:: Non-None backend, worker, progress, and verbosity settings.
Return type:: MDARunKwargs

is_default()[source]

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.job.MDAUniversePolicy(condition_label=None, replicate=None, provenance=None, metadata=<factory>)[source]

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

Freeze metadata to avoid accidental mutation after job execution.

as_dict()[source]

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.job.MDAJobResult(name, analysis, results, run_kwargs, frame_selection, backend_policy, universe_policy)[source]

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.job.MDAFunctionAdapter(function, universe, *, function_kwargs=None)[source]

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

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

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.job.MDAAnalysisJob(name, frame_selection=<factory>, analysis=None, analysis_factory=None, backend_policy=<factory>, universe_policy=<factory>)[source]

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

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

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

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

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>)