API reference

FastMDXplora’s public Python API is centered on two classes, both importable from the top-level package.

import fastmdxplora as fastmdx

study = fastmdx.FastMDXplora(config="study.yml")
results = study.explore()

FastMDXplora

The project-level orchestrator: the entry point for running a complete study (any subset of the four phases) from Python.

class fastmdxplora.FastMDXplora(system=None, *, config=None, config_data=None, output_dir=None, options=None, verbose=False, include=None, exclude=None)[source]

Bases: object

Project-level orchestrator for end-to-end MD studies.

Parameters:

  • system (str | os.PathLike) –

    Input for a single study. Accepted forms (auto-detected):

    • Path to a PDB / CIF file (e.g. "protein.pdb")

    • 4-character PDB ID (e.g. "1L2Y"), fetched from RCSB

    • One-letter amino-acid sequence, if structure prediction is available (future)

    Mutually exclusive with config.

  • config (str | os.PathLike | None) – Path to a YAML config file. Drives one system or many (with an optional parameter sweep and parallel execution); the interface is the same either way. Mutually exclusive with system.

  • output_dir (str | os.PathLike | None) – Where to write project outputs. Defaults to ./fastmdxplora_output_<timestamp>.

  • options (dict[str, dict] | None) – Per-phase keyword arguments, e.g. {"simulation": {"duration_ns": 100}}.

  • verbose (bool) – If True, log progress to stdout in addition to the project log file.

  • include (list[str] | None) – Default phase selection (explore() arguments still override).

  • exclude (list[str] | None) – Default phase selection (explore() arguments still override).

  • config_data (dict[str, Any] | None)

Examples

>>> fmdx = FastMDXplora(system="protein.pdb")
>>> fmdx.explore()

>>> fmdx = FastMDXplora(system="1L2Y")     # PDB ID, fetched from RCSB
>>> fmdx.explore(
...     include=["setup", "simulation"],
...     options={"simulation": {"duration_ns": 50}},
... )

>>> # A config file: one system or many, same interface:
>>> fmdx = FastMDXplora(config="study.yml")
>>> fmdx.explore()
analyze(**kwargs)[source]

Run only the analysis phase.

Parameters:

kwargs (Any)

Return type:

PhaseResult

compare(*, output_dir=None)[source]

(Re)build the cross-run comparison report for a multi-run study.

A multi-run explore() builds this automatically; call this to regenerate it — for example after re-running some of the runs, or to produce it for a batch that finished earlier.

Parameters:

output_dir (str | os.PathLike, optional) – The batch output directory to read (the one containing batch_manifest.json). Defaults to this object’s output_dir — i.e. the study it just ran.

Returns:

The comparison/ directory, or None if there was nothing to compare (fewer than two successful runs, or no analysis outputs were found).

Return type:

Path or None

explore(*, include=None, exclude=None, options=None, report=True, dry_run=False)[source]

Run the full pipeline, end to end.

Parameters:

  • include (list of str, optional) – Phases to run (subset of {“setup”, “simulation”, “analysis”, “report”}). If omitted, all phases run.

  • exclude (list of str, optional) – Phases to skip. Mutually exclusive with include.

  • options (dict, optional) – Per-phase option overrides applied on top of the orchestrator’s options attribute.

  • report (bool, default True) – Convenience flag. If False, skip the report phase even when include/exclude would otherwise enable it.

  • dry_run (bool, default False) – If True, print the plan — every run, its system, swept values, output directory, and the phases that would execute — and return without running anything.

Returns:

One RunResult per run, always. A single study is a list of one; a sweep is a list of many. Each RunResult carries its per-phase PhaseResult list in .phases.

Return type:

list[RunResult]

Notes

When include / exclude are omitted here but were set in a config file passed to the constructor, the config-file values are used. Explicit arguments to this method always win.

report(**kwargs)[source]

Run only the report phase.

Parameters:

kwargs (Any)

Return type:

PhaseResult

setup(**kwargs)[source]

Run only the setup phase.

Parameters:

kwargs (Any)

Return type:

PhaseResult

simulate(**kwargs)[source]

Run only the simulation phase.

Parameters:

kwargs (Any)

Return type:

PhaseResult

AnalysisOrchestrator

Coordinates the analysis phase: trajectory loading, the analysis plan (including auto-detected protein-ligand analyses), and writing results.

class fastmdxplora.AnalysisOrchestrator(trajectory, topology=None, *, output_dir=None, selection=None, scope='solute', ligand_resname=None, stride=None, first=None, last=None)[source]

Bases: object

Coordinate the execution of trajectory analysis modules.

The orchestrator loads the trajectory once at construction (matching the standard pattern) and holds it on self.traj. Subsequent calls to run() operate on that loaded trajectory.

Parameters:

  • trajectory (path, list of paths, or glob) – Trajectory file(s) to analyze. Passed verbatim to load_trajectory().

  • topology (path, optional) – Topology file. If omitted, auto-resolution is attempted (see load_trajectory()).

  • output_dir (path, optional) – Where to write per-analysis subdirectories. Defaults to ./fastmdx_analysis_<timestamp>.

  • selection (str, optional) – Default MDTraj selection string applied to every analysis that does not override it.

  • stride (int, optional) – Frame-selection parameters applied at load time.

  • first (int, optional) – Frame-selection parameters applied at load time.

  • last (int, optional) – Frame-selection parameters applied at load time.

  • scope (str)

  • ligand_resname (str | None)

Examples

Run all registered analyses with defaults:

from fastmdxplora.analysis import AnalysisOrchestrator

ao = AnalysisOrchestrator("traj.dcd", topology="top.pdb")
results = ao.run()

Selectively run RMSD and Rg with custom RMSD options:

results = ao.run(
    include=["rmsd", "rg"],
    options={"rmsd": {"ref": 0, "selection": "name CA"}},
)

Exclude expensive analyses on a quick first pass:

results = ao.run(exclude=["cluster", "dimred"])
analyze(*, include=None, exclude=None, options=None)[source]

Alias for run().

Parameters:
Return type:

dict[str, AnalysisResult]

run(*, include=None, exclude=None, options=None)[source]

Execute the planned analyses against self.traj.

Parameters:

  • include (list of str, optional) – Subset of analysis names to run. Mutually exclusive with exclude.

  • exclude (list of str, optional) – Subset of analysis names to skip.

  • options (dict, optional) – Per-analysis keyword arguments. Keys are analysis names (e.g. "rmsd"); values are dicts forwarded to the analysis constructor. Unrecognized kwargs are silently dropped so the orchestrator can be safely called with a superset of options.

Returns:

Mapping from analysis name to result, in execution order. Also stored on self.results.

Return type:

dict[str, AnalysisResult]

Package metadata

fastmdxplora.__version__ = '0.1.1.dev77+gaf8e25f18'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

fastmdxplora.__citation__ = 'Aina, A.; Kwan, D. FastMDAnalysis: Software for Automated Analysis of Molecular Dynamics Trajectories. J. Comput. Chem. 2026, 47, e70350. DOI: 10.1002/jcc.70350'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

fastmdxplora.__doi__ = '10.1002/jcc.70350'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.