What it does

Build. Every builder is a blueprint you configure once and reuse:

• CSHBuilder — C-S-H and C-A-S-H from tobermorite, at a target Ca/Si and H2O/Si ratio

• AFBuilder — AFm/AFt phases

• SurfaceBuilder — surface slabs from Miller indices, ranked by how many bonds each termination breaks

• SolutionBuilder — electrolytes from molarities or explicit counts, packed to a target density

• GlassBuilder — amorphous oxide melts

• Splitter — cut a system open along an axis and fill the gap with a solution

Type and parameterize. set_topology() applies force-field typing rules (ClayFF, CSHFF and your own), set_ff_from_database() resolves the parameters. The bundled database holds ClayFF, CSHFF2014, IFF (CHARMM and CVFF flavours), GROMOS 54A7/ATB, Raiteri 2015, Guillot & Sator 2007, and the usual water models (SPC, SPC/E, SPC/Fw, TIP3P, TIP4P-2005, TIP4P-EW).

Analyse. Silicate network statistics (Ca/Si, H2O/Si, Qⁿ distribution, mean chain length), radial distribution functions, density and diffusion profiles, mean-squared displacement, electrostatic potential.

Read and write. Reads LAMMPS data files (.data, .lmp), PDB, CIF, moltemplate (.lt) and SDF; writes LAMMPS data files and PDB. It also fetches structures directly from PubChem and the COD, builds them from SMILES, and converts to and from MDAnalysis and pymatgen objects.

Inspect. An optional PySide6/PyVista interface for viewing and editing structures interactively.

Two examples

A mineral surface in contact with an electrolyte – the archetypal interface problem:

from cemd import AtomicSystem
from cemd.build import SolutionBuilder, SurfaceBuilder

calcite = AtomicSystem.from_file("calcite.cif")
slabs, *_ = SurfaceBuilder(calcite).build((1, 0, 4), min_slab_size=12.0)

brine = SolutionBuilder(density=1.0, molarities={"Na": 0.5, "Cl": 0.5})
system = slabs[0].add_liquid_layer(brine, thickness=20.0)

system.set_topology("clayff")
system.write("calcite_brine.data")

And a cement hydrate, where cemd does what nothing else does – build the C-S-H at a target Ca/Si, then measure where it can be cut before opening a pore, since under CSHFF the silicate framework carries no explicit bond to guide you:

from cemd.build import CSHBuilder, SolutionBuilder, Splitter

csh = CSHBuilder(cs_ratio=1.5, ws_ratio=1.0).build(model="tob11a_merlino.cif")
csh.set_types_from_elements()
csh.set_topology("cshff")

pore = SolutionBuilder(density=1.0, counts={"Na": 8, "HO": 8})
system = Splitter(csh, coordinate=17.0, axis="z", gap_size=25.0) \
    .add_solution(pore, padding=2.0) \
    .split()

system.write("csh_nanopore.data")

Installation

Python 3.11 or later. Install into an environment of its own: cemd pulls in pymatgen, MDAnalysis and RDKit, which pin versions of their own, and keeping them apart from your other work avoids resolving one project’s constraints against another’s.

conda create -n cemd python=3.11
conda activate cemd

pip install cemd

A plain virtual environment works just as well if you do not use conda:

python -m venv cemd
source cemd/bin/activate              # cemd\Scripts\activate on Windows

pip install cemd

For the graphical interface, which then opens with cemd-gui:

pip install "cemd[gui]"
cemd-gui

To work on cemd itself, clone it and install editable, which points the environment at your working copy rather than copying the code:

git clone https://github.com/cemd-dev/cemd.git
cd cemd
pip install -e ".[dev,gui,docs]"

The installation guide covers conda environments and the prerequisites in more detail.

Everything comes with it, including Packmol – every builder that packs molecules into a volume shells out to that binary, and pip puts it in the environment alongside the Python dependencies (MDAnalysis, pymatgen, RDKit, NumPy, SciPy, pandas, matplotlib, Dask). Should no wheel match your platform, install Packmol yourself and put it on your $PATH.

Citing cemd

If cemd contributes to work you publish, please cite it. The archive is on Zenodo:

Claverie, J. cemd. Zenodo. https://doi.org/10.5281/zenodo.22675363

That DOI is the concept DOI: it always resolves to the most recent release, so the citation stays valid as cemd evolves. To cite the exact version you ran, take the version DOI from the Zenodo page for that release.

CITATION.cff in the repository carries the same metadata, which is what GitHub’s “Cite this repository” button reads.

Documentation

https://cemd-dev.github.io/cemd/

The user guide covers building, analysis and the force-field database, and four worked tutorials go from a calcite surface to a C-S-H nanopore filled with an alkaline pore solution. Every output shown in them was captured from a real run.

To build the documentation locally:

sphinx-build -b html docs docs/_build/html

Tests

pytest

The suite runs against the real bundled data and force fields rather than mocks. Tests that shell out to Packmol are skipped when it is not installed.

Citing

See CITATION.cff.

License

GPL-3.0-only. See LICENCE.