Simulation

Manages a single simulation directory and its analyses.

Provides interfaces for saving/loading per-simulation metadata, managing analysis results, and executing registered analyses.

Attributes

attributeMETADATA_FILENAME

= 'metadata.json'

attributeANALYSIS_DIR

= '.analysis'

attributepathPath

= Path(path).resolve()

Simulation directory path (absolute)

attributestructure_file

= self.path / Path(structure_file)

attribute_trajectory_file

= trajectory_file

attribute_completed_file

= Path(completed_file)

attribute_build_input

= build_input

attribute_registryAnalysisRegistry | None

= None

AnalysisRegistry instance (lazy-loaded)

attributetrajectory_filePath

Get trajectory file path, validating it exists.

attributestatusstr

Determine simulation status based on output files.

Status hierarchy (checked in order):

"completed": completed_file exists (default: prod.gro)
"production": trajectory_file exists (default: prod.xtc)
"equilibrated": min.gro, nvt.gro, npt.gro all exist
"build": system.pdb + valid BuildInput YAML exist

attributeuniversemda.Universe

MDAnalysis Universe for this simulation.

Requires trajectory file to exist.

attributebuild_inputBuildInput

BuildInput instance loaded from YAML

attributemetadatadict[str, Any]

Get metadata dict from BuildInput.

attributeanalysis_dirPath

Path to .analysis directory.

attributeartifact_dirPath

Path to .analysis/artifacts directory.

attributeregistryAnalysisRegistry

Lazy-load and return AnalysisRegistry instance.

Creates .analysis directory if needed.

Functions

func__init__(self, path, build_input=None, structure_file='system.pdb', trajectory_file='prod.xtc', completed_file='prod.gro') → None

Initialize Simulation instance.

paramself

parampathPath | str

Simulation directory path

parambuild_inputBuildInput | None

= None

Optional BuildInput (if None, will be loaded from YAML)

paramstructure_filePath | str

= 'system.pdb'

Structure filename (default: system.pdb)

paramtrajectory_filePath | str | None

= 'prod.xtc'

Trajectory filename (default: prod.xtc). Set to None for simulations without trajectory (e.g., build-only).

paramcompleted_filePath | str

= 'prod.gro'

File that indicates simulation completion (default: prod.gro). Used by the status property to determine if simulation is completed.

Returns

None

funcsave_metadata(self) → None

Save per-simulation metadata.json.

Generates metadata from BuildInput and writes to disk.

paramself

Returns

None

funcload_metadata(self) → dict[str, Any]

Load per-simulation metadata.json from disk.

paramself

Returns

dict

Metadata dict

funcsave_analysis(self, name, df, **metadata_extras) → None

Save analysis results to parquet and update registry.

Atomically updates both file and registry. If registry update fails, the parquet file is removed to maintain consistency.

paramself

paramnamestr

Analysis name (without .parquet extension)

paramdfpd.DataFrame

DataFrame to save

parammetadata_extras

= {}

Returns

None

funcload_analysis(self, name) → pd.DataFrame

Load analysis results from parquet.

paramself

paramnamestr

Analysis name

Returns

pandas.DataFrame

DataFrame with analysis results

funclist_analyses(self) → list[str]

List available analyses from registry.

paramself

Returns

list

Sorted list of analysis names (empty if registry doesn't exist yet)

funclist_artifacts(self) → list[str]

List available artifacts from registry.

paramself

Returns

list

Sorted list of artifact names (empty if registry doesn't exist yet)

funcrun_analysis(self, name, **kwargs) → pd.DataFrame

Run analysis for this simulation using registered analysis function.

Executes the analysis function from ANALYSIS_REGISTRY, saves the result, and returns the DataFrame.

paramself

paramnamestr

Analysis name (must be registered for simulation type)

paramkwargs

= {}

Returns

pandas.DataFrame

DataFrame with analysis results

funcsave_artifact(self, name, files, **metadata_extras) → list[Path]

Save artifact files and update registry.

paramself

paramnamestr

Artifact name

paramfilesPath | list[Path]

File path or list of file paths to move

parammetadata_extras

= {}

Returns

list

Paths to artifact files under .analysis

funcload_artifact(self, name) → list[Path]

Load artifact file paths from registry.

paramself

paramnamestr

Artifact name

Returns

list

Paths to artifact files

funcrun_artifact(self, name, **kwargs) → list[Path]

Run artifact producer for this simulation and save artifacts.

paramself

paramnamestr

Artifact name registered for the simulation type

paramkwargs

= {}

Returns

list

Paths to saved artifacts

funcremove_artifact(self, name) → None

Remove artifact files and registry entry.

paramself

paramnamestr

Artifact name to remove

Returns

None

funccheck_integrity(self) → dict[str, Any]

Check integrity of simulation directory.

Verifies that required files exist and registry is consistent.

paramself

Returns

dict

Dict with:

valid: bool - True if no issues found
missing_metadata: bool - Per-simulation metadata.json missing
missing_build_input: bool - BuildInput YAML missing
registry_issues: dict - Issues from AnalysisRegistry.check_integrity()

funcdiscover_build_input(sim_dir) → BuildInput

Load BuildInput from YAML file in simulation directory.

Reuses logic from discover_simulations() - looks for *.yaml files and validates them as BuildInput.

paramsim_dirPath

Simulation directory path

Returns

BuildInput

BuildInput instance

funcremove_analysis(self, name) → None

Remove analysis results and registry entry.

paramself

paramnamestr

Analysis name to remove

Returns

None

funcremove_all_analyses(self) → None

Remove all analysis results and clear registry.

paramself

Returns

None

funcremove_all_artifacts(self) → None

Remove all artifact files and clear registry.

paramself

Returns

None

Attributes

Functions

On this page