mc3d-source

Code for the MC3D source pipeline: the workflow that turns raw CIF dumps from external crystal structure databases (COD, ICSD, MPDS) into the unique, curated set of structures that seed all MC3D calculations.

For the scientific context, see the MC3D website and the accompanying paper in Digital Discovery (Huber et al., 2026).

What it does

The package provides a single CLI, mc3d-source, that drives the pipeline in stages:

1. import — fetch raw CIFs from a source database into AiiDA.
2. (Cleaning step.) The raw CifData are processed by CifCleanWorkChain runs, submitted in batch from the separate runner in pipeline/cif_clean/ (not part of the installed package).
3. curate — from a group of completed CifCleanWorkChain, attach source/spacegroup/formula extras to the parsed StructureData and collect the clean ones into a curated group.
4. update — when re-importing an updated version of a source database, reconcile the new curated set against the previous one (keep old structure when unchanged, take new when geometry differs, drop entries removed upstream).
5. analyse — produce the per-source deprecation report (id_removed, structure_updated, incorrect_formula) consumed by select.
6. uniq — deduplicate structures across sources via pymatgen's StructureMatcher, emit unique families as JSON.
7. select — pick the final MC3D structures from the unique families, taking the previous MC3D set and the deprecation report into account.

Install

Requires Python 3.9+ and a working AiiDA setup. Install from source:

git clone https://github.com/mbercx/mc3d-source.git
cd mc3d-source
pip install -e .

For development (docs, tests, pre-commit), use the dev dependency group or hatch. See the developer guide.

Usage

mc3d-source --help

Full documentation: https://mbercx.github.io/mc3d-source/.

License

MIT — see LICENSE.