Prerequisites

• Python ≥ 3.9
• pip

Setup

# Clone the repository
git clone <repo-url>
cd matcraft-kit

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\activate         # Windows

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Project Structure

mckit/
├── __init__.py              # Package root — exports public API
├── core/
│   ├── lattice.py           # Lattice dataclass (3×3 matrix, ASE Cell-backed)
│   └── tool.py              # Abstract base classes: Operation, Observation
├── operate/
│   ├── bulk.py              # BulkBuilder — standard crystal structures
│   └── surface.py           # SurfaceBuilder, TerminationAnalyzer, MoleculeDetector
├── observe/
│   ├── inspect.py              # StructureInspect — structural summary
│   └── fundamental.py       # FundamentalCheck — geometric validity checks
└── io/
    ├── reader.py            # read_structure() -> ASE Atoms
    └── writer.py            # write_structure() — ASE io.write

Architecture

The framework follows an Operation / Observation pattern:

• Operation (abstract) — tools that build or modify structures. Subclasses implement apply(...) and return ase.Atoms.
• Observation (abstract) — tools that inspect structures without modifying them. Subclasses implement observe(structure) → Any.

Both are single-method ABCs defined in mckit.core.tool, making it straightforward to add new operations or observations.

Core data flow:

File (CIF, VASP, ...) ──read_structure()──▶ ase.Atoms ──Operation──▶ ase.Atoms ──write_structure()──▶ File
                                                │
                                                └──Observation──▶ dict / CheckResult / ...

Running Tests

pytest

With coverage:

pytest --cov=mckit --cov-report=term-missing

Adding a New Operation

Create a file under mckit/operate/ and subclass Operation:

from ase import Atoms
from mckit.core.tool import Operation

class MyBuilder(Operation):
    """Build or modify a structure."""

    def apply(self, *, some_param: float, **kwargs) -> Atoms:
        # ... your logic here ...
        return new_structure

Then re-export it from mckit/operate/__init__.py.

Adding a New Observation

Create a file under mckit/observe/ and subclass Observation:

from ase import Atoms
from mckit.core.tool import Observation

class MyAnalysis(Observation):
    """Inspect a structure and return results."""

    def observe(self, structure: Atoms, **kwargs):
        # ... your logic here ...
        return result_dict

Then re-export it from mckit/observe/__init__.py.

Dependencies