API reference¶

Core workflow¶

sammd.load_config(path: str | Path) → SAMMDConfig¶: Load and validate a SAMMD YAML configuration file.

sammd.load_config_dict(data: dict[str, Any]) → SAMMDConfig¶: Load and validate a SAMMD configuration from a mapping.

Compose a deterministic SAMMD inspection build plan.

Parameters:

config – Validated config, path to a YAML config, or parsed config mapping.
output_dir – Base directory for resolving planned output artifact paths.
seed – Optional override for deterministic SAM site and component choices.

Returns:

Validated artifact containing slab, SAM, solution, and output plans.

Return type:

SAMMDBuildPlan

class sammd.core.builders.SAMMDBuildPlan(config: SAMMDConfig, slab: SurfaceSlab, binding_sites: tuple[BindingSite, ...], sam_placements: SAMPlacementPlan, solution: SolutionPlan, output_paths: OutputPaths, box_plan: BoxPlan)¶

Validated system plan with slab, SAM, solution, box, and output paths.

build_summary() → dict[str, object]¶: Return a machine-readable summary of the planned system build.

write_build_summary(path: str | Path | None = None, *, overwrite: bool = False) → Path¶: Write the JSON build summary artifact.

write_planned_topology(*, overwrite: bool = False) → Path¶: Write the configured topology CIF for the deterministic build plan.

write_resolved_config(path: str | Path | None = None, *, overwrite: bool = False) → Path¶: Write the validated YAML config used for the build.

write_topology_cif(path: str | Path | None = None, *, overwrite: bool = False) → Path¶

Write the configured topology CIF for inspecting the built plan.

Parameters:

path – Optional destination path. Defaults to the configured sam_grafting_density.cif path.
overwrite – Whether an existing destination may be replaced.

Returns:

Written topology CIF path.

Return type:

Path

class sammd.core.builders.BoxPlan(lateral_size_nm: tuple[float, float], dimensions_nm: tuple[float, float, float], bounds_nm: tuple[tuple[float, float], tuple[float, float], tuple[float, float]], volume_nm3: float, solvent_padding_nm: float, solvent_padding_per_face_nm: float, solvent_packing_regions_nm: tuple[tuple[tuple[float, float], tuple[float, float], tuple[float, float]], ...], solvent_count_planning_volume_nm3: float, solvent_packing_warnings: tuple[str, ...], sam_extended_length_nm: float, slab_center_nm: tuple[float, float, float], sam_length_estimates: tuple[SAMLengthEstimate, ...])¶: Unified orthorhombic build box for counts and topology metadata.

Configuration model¶

class sammd.SAMMDConfig(*, experiment: ExperimentConfig = <factory>, surface: SurfaceConfig = <factory>, sam: SAMConfig = <factory>, reactants: list[ReactantConfig] = <factory>, solvent: SolventConfig = <factory>, salts: list[SaltConfig] = <factory>, packing: PackingConfig = <factory>, parameterization: ParameterizationConfig = <factory>, outputs: OutputsConfig = <factory>)¶

Top-level SAMMD system-building configuration model.

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Orientation analysis helper¶

This dependency-free analysis helper is available for tutorial inspection workflows. It is not part of the system build/export contract.

sammd.analysis.analyze_orientation(coordinates: Sequence[tuple[float, float, float]], *, atom_index: int | None = None, atom_indices: Sequence[int] | None = None, masses: Sequence[float] | None = None, side: Literal['top', 'bottom'] | None = 'top', normal: tuple[float, float, float] | None = None, frame_index: int | None = None, time: float | None = None, reactant_label: str | None = None) → OrientationResult¶

Analyze reactant orientation relative to a surface normal.

Parameters:

coordinates – Reactant atom coordinates using 0-based Python atom-index conventions.
atom_index – Single target atom index.
atom_indices – Target atom indices whose centroid defines the target point.
masses – Optional positive atom masses aligned with coordinates for COM calculation.
side – Surface side used when normal is not supplied.
normal – Optional explicit surface normal vector.
frame_index – Optional trajectory frame index to store with the result.
time – Optional trajectory time to store with the result.
reactant_label – Optional reactant label to store with the result.

Returns:

Orientation angle and intermediate geometry values.

Return type:

OrientationResult

class sammd.analysis.OrientationResult(angle_degrees: float, vector: tuple[float, float, float], normal: tuple[float, float, float], com: tuple[float, float, float], target_point: tuple[float, float, float], side: Literal['top', 'bottom'] | None, selected_atom_indices: tuple[int, ...], target_kind: Literal['atom', 'midpoint', 'centroid'], frame_index: int | None = None, time: float | None = None, reactant_label: str | None = None)¶

Result of a reactant orientation analysis calculation.

angle_degrees¶

Angle between the reactant orientation vector and surface normal in degrees.

Type:: float

vector¶

Unit vector pointing from the reactant center of mass to the target point.

Type:: tuple[float, float, float]

normal¶

Unit surface normal used for the angle calculation.

Type:: tuple[float, float, float]

com¶

Reactant center of mass in the same units as input coordinates.

Type:: tuple[float, float, float]

target_point¶

Selected target atom, midpoint, or centroid in the same units as input coordinates.

Type:: tuple[float, float, float]

side¶

Surface side used to choose the normal, or None when an explicit normal is supplied.

Type:: Literal[‘top’, ‘bottom’] | None

selected_atom_indices¶

0-based atom indices used to define the target point.

Type:: tuple[int, …]

target_kind¶

Selection kind used to define the target point.

Type:: Literal[‘atom’, ‘midpoint’, ‘centroid’]

frame_index¶

Optional trajectory frame index associated with this result.

Type:: int | None

time¶

Optional trajectory time associated with this result.

Type:: float | None

reactant_label¶

Optional reactant label associated with this result.

Type:: str | None