Installation

The package

Install from source:

git clone https://github.com/tcnicholas/mosaic-materials.git
cd mosaic-materials
pip install -e .

or, with uv:

uv pip install -e .

Python ≥ 3.9. The Python dependencies (ase, numba, numpy, matplotlib, h5py, pylammpsmpi) are installed automatically.

Optional extras:

pip install -e ".[tests]"   # pytest, pytest-cov
pip install -e ".[docs]"    # mkdocs-material (for building these docs)

LAMMPS

The one requirement not handled by pip: a LAMMPS build with Python bindings (the lammps Python module must be importable), which pylammpsmpi uses to run LAMMPS in-process across MPI ranks. Build LAMMPS as a shared library with the packages your force field needs — e.g. ML-PACE for ACE potentials, MOLECULE for bonded systems — following the LAMMPS Python documentation.

Parallelism is requested per engine:

engine = MCEngine(cores=8)   # 8 MPI ranks under the hood

Units

The package works in LAMMPS metal units throughout: energies in eV, distances in Å, temperatures in K. Pressure schedules are supplied in GPa and converted internally. The driver will refuse to run with any other unit style.

Building the documentation

pip install -e ".[docs]"
mkdocs serve    # live-preview at http://127.0.0.1:8000
mkdocs build    # static site in site/