API overview

The core classes, at a glance. Import paths are stable; anything not listed here is internal and may change.

Engine

from mosaic_materials.engine import MCEngine

Member	Purpose
`MCEngine(cores=1, units="metal", seed=None)`	Start LAMMPS in-process on `cores` MPI ranks. Context manager (`with ... as engine:`).
`load_lammps_data(path)`	Read a LAMMPS data file (`.data`).
`load_ase_atoms(atoms)`	Load an ASE `Atoms` object; a `mol-id` array defines molecules.
`to_ase_atoms()`	Export the current configuration as ASE `Atoms`.
`add_force_field(style, coeffs)`	Issue `pair_style` / `pair_coeff`.
`add_constraint(c)` / `remove_constraint(label)` / `get_constraint(label)`	Manage constraints.
`engine.system`	The `System` view: `cell_lengths`, `composition`, `pick_random_atom(rng)`, `pick_random_molecule(rng)`, …
`engine.lmp`	The raw LAMMPS handle, for anything else (`engine.lmp.command(...)`).

Constraints

from mosaic_materials.constraints import ...

Class	Scores	Key arguments
`EnthalpyConstraint`	Potential energy \(U\) (raw, eV)	`temperature_Kelvin`
`RDFConstraint`	Computes \(g_{ij}(r)\) (cost 0; feeds the others)	`r_max`, `bin_width=0.02`
`NeutronStructureFactorConstraint`	\(F_N(Q)\) vs experiment	`sigma`, `deuteration_ratio`, `scattering_lengths`
`XrayStructureFactorConstraint`	\(F_X(Q)\) vs experiment	`sigma`, `minimise_differences=True`
`NeutronTotalRDFConstraint` / `XrayTotalRDFConstraint`	\(G(r)\) vs experiment	`sigma`, `is_dofr`

All scattering constraints offer from_scattering_data(name, data, weight=1.0, **kwargs) and require an installed RDFConstraint (added first). Labels (name) key the cached patterns in SimulationState.scattering and the per-constraint costs in state.costs.

Experimental data

from mosaic_materials.data import ScatteringData

Member	Purpose
`ScatteringData.from_file(path, sigmas=None)`	Read `x y [sigma]` columns.
`apply_finite_box_correction(r_max, inplace=False)`	Convolve with the simulation-box sinc window.
`restrict_x(xmin, xmax)`	Crop the fitting range.
`multiply_by_q()` / `divide_by_q()`	Toggle \(QF(Q)\) ↔ \(F(Q)\).
`rescale_weight(f)` / `scale_intensity(f)`	Adjust weights / intensities.
`plot(ax=...)`	Scatter plot in the house style.

Moves

from mosaic_materials.moves import ...

Class	Proposal	Tuned parameter(s)
`TranslateMove`	Random displacement of the selected atoms	`max_disp`
`RotateMove`	Rigid rotation about COM/centroid	`max_angle` (`pivot="com"`)
`TranslateRotateMove`	Rotation then translation	`max_disp`, `max_angle`
`VolumeMove`	Isotropic \(\delta\ln V\) box scaling	`max_dlnv` (`rigid_molecules`)

Monte Carlo

from mosaic_materials.monte_carlo.adapt import MoveSpec
from mosaic_materials.monte_carlo.driver import MCDriver
from mosaic_materials.monte_carlo.schedules import (
    ConstantSchedule, LinearSchedule, ExponentialDecaySchedule,
)
from mosaic_materials.monte_carlo.callbacks import (
    summary_logger, move_magnitude_tuning_logger,
)
from mosaic_materials.monte_carlo.trajectory import (
    MCTrajectory, make_hdf5_writer,
)

Member	Purpose
`MoveSpec(name, move_class, selector, kwargs, ...)`	A move type + selector + adaptive tuning (`target_acceptance`, `adjustment_factor`, `interval`, `min_values`, `max_values`).
`MCDriver(engine, move_specs, temperature_schedule, pressure_schedule=None, callbacks=())`	The Metropolis loop. Pressure schedules in GPa enable NPT.
`MCDriver.run(n_steps, start=0)`	Generator yielding `(step, move_name, accepted, chi2, U, V)` per step; `start` offsets steps and schedules for restarts.
`ConstantSchedule(v)`, `LinearSchedule(start, stop, n_steps)`, `ExponentialDecaySchedule(start, decay)`	Temperature/pressure vs step.
`summary_logger(path, interval=100)`	CSV log: thermodynamics, acceptance, per-constraint costs, timing.
`move_magnitude_tuning_logger(move_specs)`	Logs every amplitude adjustment.
`MCTrajectory(path, engine, every=100)` + `make_hdf5_writer(traj)`	Compressed HDF5 trajectory as a driver callback.

State

from mosaic_materials.state.state import SimulationState

The driver's driver.state holds the last accepted state: state.costs (per-constraint), state.rdf[name] (partials, one row per pair), state.scattering[name] (total patterns), and state.plot_scattering(name, x=..., y=...) for a quick fit plot.