mosaic-materials

Hybrid reverse Monte Carlo (HRMC) refinement of atomistic structural models against total-scattering data, with configurational energies from any LAMMPS force field. You give it a starting configuration, one or more experimental datasets — X-ray or neutron \(F(Q)\), neutron \(G(r)\) — and a potential; it evolves the structure with Metropolis Monte Carlo moves that balance fit-to-data against energy.

Start here

• Installation — the package, and the one external requirement (a LAMMPS build with Python bindings).
• Quickstart — a complete minimal refinement in ~40 lines: engine, constraints, moves, driver.
• Worked example — a realistic multi-dataset refinement: X-ray and neutron structure factors plus \(G(r)\), molecule-aware moves, volume moves, adaptive tuning, logging, and snapshots.
• Theory — the HRMC acceptance rule and the total-scattering equations (following Keen's conventions), as implemented here.
• API overview — the core classes at a glance.

The package in one line

from mosaic_materials.engine import MCEngine
from mosaic_materials.monte_carlo.driver import MCDriver

with MCEngine(cores=4) as engine:
    ...                                  # load structure, potential, data
    driver = MCDriver(engine, moves, temperature_schedule)
    for step, move, accepted, chi2, U, V in driver.run(100_000):
        ...                              # log, snapshot, plot

Everything is composed from four kinds of object: an engine wrapping LAMMPS, constraints that score the current structure (energy, RDF, scattering), moves that propose changes, and a driver that runs the Metropolis loop with temperature/pressure schedules and adaptive step-size tuning.