matcraft-kit 0.1.0__tar.gz

matcraft_kit-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: matcraft-kit
+Version: 0.1.0
+Summary: MatCraft Toolkit
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Requires-Dist: ase>=3.22
+Requires-Dist: pymatgen>=2022.0.0
+Requires-Dist: pymatgen-analysis-defects>=2024.10.22
+Requires-Dist: rdkit>=2025.9.6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

matcraft_kit-0.1.0/README.md

@@ -0,0 +1,164 @@
+# mckit — MatCraft Toolkit
+
+A modular Python framework for building and analyzing atomic structures. Backed by [ASE](https://wiki.fysik.dtu.dk/ase/) and [pymatgen](https://pymatgen.org/) for materials modelling.
+
+## Features
+
+- **Operations** — modelling materials
+- **Observations** — inspect structures and run sanity checks
+
+---
+
+## 1. Usage
+
+### Installation
+
+```bash
+pip install -e .
+```
+
+Or install with dev dependencies (pytest, coverage):
+
+```bash
+pip install -e ".[dev]"
+```
+
+### CLI
+
+```bash
+# for observations:
+mckit observe -h
+# for operations:
+mckit operate -h
+```
+
+
+## 2. Development
+
+<details>
+    <summary>Click to expand development instructions</summary>
+
+### Prerequisites
+
+- Python ≥ 3.9
+- pip
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd mat-modelling-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)
+│   ├── structure.py         # Structure dataclass (lattice + species + positions)
+│   └── tool.py              # Abstract base classes: Operation, Observation
+├── operate/
+│   ├── bulk.py              # BulkBuilder — standard crystal structures
+│   └── surface.py           # SurfaceBuilder, TerminationAnalyzer, MoleculeDetector
+├── observe/
+│   ├── info.py              # StructureInfo — 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 a `Structure`.
+- **`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──▶ Structure/ase.Atoms ──write_structure()──▶ File
+                                                │
+                                                └──Observation──▶ dict / CheckResult / ...
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=mckit --cov-report=term-missing
+```
+
+### Adding a New Operation
+
+Create a file under `mckit/operate/` and subclass `Operation`:
+
+```python
+from mckit.core.structure import Structure
+from mckit.core.tool import Operation
+
+class MyBuilder(Operation):
+    """Build or modify a structure."""
+
+    def apply(self, *, some_param: float, **kwargs) -> Structure:
+        # ... 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`:
+
+```python
+from mckit.core.structure import Structure
+from mckit.core.tool import Observation
+
+class MyAnalysis(Observation):
+    """Inspect a structure and return results."""
+
+    def observe(self, structure: Structure, **kwargs):
+        # ... your logic here ...
+        return result_dict
+```
+
+Then re-export it from `mckit/observe/__init__.py`.
+
+### Building the Package
+
+```bash
+pip install build
+python -m build
+```
+
+This produces a wheel and sdist under `dist/`.
+
+### Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `numpy ≥ 1.21` | Numerical computing |
+| `ase ≥ 3.22` | Atomic Simulation Environment — crystal builders, I/O, coordinate transforms |
+| `pymatgen ≥ 2022.0.0` | Python Materials Genomics — CIF parsing, symmetry analysis |
+
+</details>

matcraft_kit-0.1.0/matcraft_kit.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: matcraft-kit
+Version: 0.1.0
+Summary: MatCraft Toolkit
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Requires-Dist: ase>=3.22
+Requires-Dist: pymatgen>=2022.0.0
+Requires-Dist: pymatgen-analysis-defects>=2024.10.22
+Requires-Dist: rdkit>=2025.9.6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

matcraft_kit-0.1.0/matcraft_kit.egg-info/SOURCES.txt

@@ -0,0 +1,28 @@
+README.md
+pyproject.toml
+matcraft_kit.egg-info/PKG-INFO
+matcraft_kit.egg-info/SOURCES.txt
+matcraft_kit.egg-info/dependency_links.txt
+matcraft_kit.egg-info/entry_points.txt
+matcraft_kit.egg-info/requires.txt
+matcraft_kit.egg-info/top_level.txt
+mckit/__init__.py
+mckit/cli.py
+mckit/core/__init__.py
+mckit/core/lattice.py
+mckit/core/structure.py
+mckit/core/tool.py
+mckit/io/__init__.py
+mckit/io/reader.py
+mckit/io/writer.py
+mckit/observe/__init__.py
+mckit/observe/fundamental.py
+mckit/observe/info.py
+mckit/operate/__init__.py
+mckit/operate/bulk.py
+mckit/operate/defect_creation.py
+mckit/operate/interface.py
+mckit/operate/molecule_creation.py
+mckit/operate/perturbation.py
+mckit/operate/supercell.py
+mckit/operate/surface.py

matcraft_kit-0.1.0/matcraft_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

matcraft_kit-0.1.0/matcraft_kit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mckit = mckit.cli:main

matcraft_kit-0.1.0/matcraft_kit.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy>=1.21
+ase>=3.22
+pymatgen>=2022.0.0
+pymatgen-analysis-defects>=2024.10.22
+rdkit>=2025.9.6
+
+[dev]
+pytest
+pytest-cov

matcraft_kit-0.1.0/matcraft_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+mckit

matcraft_kit-0.1.0/mckit/__init__.py

@@ -0,0 +1,25 @@
+"""
+matmod - Materials Modelling Toolkit
+
+A modular framework for building and analyzing atomic structures.
+Backed by ASE and pymatgen for crystallographic computations.
+
+Two main subsystems:
+  - operations : tools that BUILD or MODIFY structures (bulk, surface, defect, ...)
+  - observations: tools that INSPECT structures (info, checks, properties, ...)
+"""
+
+from mckit.core.lattice import Lattice
+from mckit.core.structure import Structure
+from mckit.core.tool import Operation, Observation
+from mckit.io import read_structure, write_structure
+
+__version__ = "0.2.0"
+__all__ = [
+    "Lattice",
+    "Structure",
+    "Operation",
+    "Observation",
+    "read_structure",
+    "write_structure",
+]

matcraft_kit-0.1.0/mckit/cli.py

@@ -0,0 +1,84 @@
+"""mckit CLI — auto-dispatching central entry point.
+
+Any module under ``mckit.operate`` or ``mckit.observe`` can hook into the CLI
+by defining a ``register_cli(subparsers)`` function.  This file discovers and
+calls them automatically, so adding a new tool never requires touching this file.
+
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import pkgutil
+import sys
+from pathlib import Path
+
+
+def _discover_modules():
+    """Yield modules with ``register_cli`` from mckit.operate and mckit.observe."""
+    import mckit.operate
+    import mckit.observe
+
+    for pkg in (mckit.operate, mckit.observe):
+        pkg_path = str(Path(pkg.__file__).parent)
+        for info in pkgutil.iter_modules([pkg_path]):
+            if info.name.startswith("_"):
+                continue
+            mod = importlib.import_module(f"{pkg.__name__}.{info.name}")
+            if hasattr(mod, "register_cli"):
+                yield mod
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="mckit",
+        description="MatCraft Kit",
+    )
+    top_sub = parser.add_subparsers(dest="category")
+
+    operate = top_sub.add_parser("operate", help="Build / modify structures")
+    observe = top_sub.add_parser("observe", help="Inspect structures")
+    # defect = top_sub.add_parser("defect", help="Quick defect workflows")
+
+    op_sub = operate.add_subparsers(dest="tool")
+    ob_sub = observe.add_subparsers(dest="tool")
+    # defect_sub = defect.add_subparsers(dest="tool")
+
+    for mod in _discover_modules():
+        package = mod.__name__.split(".")[-2]  # 'operate' or 'observe'
+        sub = op_sub if package == "operate" else ob_sub
+        mod.register_cli(sub)
+
+    # # Optional top-level shortcuts (currently defect workflows).
+    # try:
+    #     from mmkit.operate import defect_creation as defect_mod
+
+    #     if hasattr(defect_mod, "register_cli_root"):
+    #         defect_mod.register_cli_root(defect_sub)
+    # except Exception:
+    #     # Keep CLI resilient if optional shortcut wiring fails.
+    #     pass
+
+    return parser
+
+
+def main():
+    """Console entry point."""
+    parser = build_parser()
+    args = parser.parse_args()
+    if not getattr(args, "category", None):
+        parser.print_help()
+    elif hasattr(args, "handler"):
+        try:
+            args.handler(args)
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

matcraft_kit-0.1.0/mckit/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core data structures."""
+
+from mckit.core.lattice import Lattice
+from mckit.core.structure import Structure
+from mckit.core.tool import Operation, Observation

matcraft_kit-0.1.0/mckit/core/lattice.py

@@ -0,0 +1,117 @@
+"""Lattice (unit cell) — a thin wrapper around ``ase.cell.Cell``.
+
+All cell-parameter and reciprocal-lattice computations are delegated to ASE
+so we do not reinvent geometry that already exists upstream.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from ase.cell import Cell as ASECell
+
+
+@dataclass
+class Lattice:
+    """Crystal lattice defined by three row-vectors in a 3x3 matrix (Å)."""
+
+    matrix: np.ndarray
+
+    def __post_init__(self) -> None:
+        arr = self.matrix.array if isinstance(self.matrix, ASECell) else self.matrix
+        self.matrix = np.asarray(arr, dtype=np.float64).reshape(3, 3)
+
+    # ------------------------------------------------------------------
+    # Constructors
+    # ------------------------------------------------------------------
+    @classmethod
+    def from_parameters(
+        cls, a: float, b: float, c: float,
+        alpha: float, beta: float, gamma: float,
+    ) -> "Lattice":
+        return cls(matrix=ASECell.new([a, b, c, alpha, beta, gamma]))
+
+    @classmethod
+    def cubic(cls, a: float) -> "Lattice":
+        return cls.from_parameters(a, a, a, 90.0, 90.0, 90.0)
+
+    @classmethod
+    def hexagonal(cls, a: float, c: float) -> "Lattice":
+        return cls.from_parameters(a, a, c, 90.0, 90.0, 120.0)
+
+    @classmethod
+    def from_ase_cell(cls, cell) -> "Lattice":
+        return cls(matrix=np.asarray(cell, dtype=np.float64))
+
+    # ------------------------------------------------------------------
+    # ASE delegation
+    # ------------------------------------------------------------------
+    def to_ase_cell(self) -> ASECell:
+        return ASECell(self.matrix.copy())
+
+    @property
+    def _cellpar(self) -> np.ndarray:
+        return self.to_ase_cell().cellpar()
+
+    @property
+    def a_vec(self) -> np.ndarray:
+        return self.matrix[0]
+
+    @property
+    def b_vec(self) -> np.ndarray:
+        return self.matrix[1]
+
+    @property
+    def c_vec(self) -> np.ndarray:
+        return self.matrix[2]
+
+    @property
+    def a(self) -> float:
+        return float(self._cellpar[0])
+
+    @property
+    def b(self) -> float:
+        return float(self._cellpar[1])
+
+    @property
+    def c(self) -> float:
+        return float(self._cellpar[2])
+
+    @property
+    def alpha(self) -> float:
+        return float(self._cellpar[3])
+
+    @property
+    def beta(self) -> float:
+        return float(self._cellpar[4])
+
+    @property
+    def gamma(self) -> float:
+        return float(self._cellpar[5])
+
+    @property
+    def volume(self) -> float:
+        return float(self.to_ase_cell().volume)
+
+    @property
+    def reciprocal(self) -> "Lattice":
+        """Reciprocal lattice (2π convention)."""
+        rec = self.to_ase_cell().reciprocal().array * 2 * np.pi
+        return Lattice(matrix=rec)
+
+    # ------------------------------------------------------------------
+    # Coordinate transforms
+    # ------------------------------------------------------------------
+    def fractional_to_cartesian(self, frac_coords) -> np.ndarray:
+        return np.asarray(frac_coords, dtype=np.float64) @ self.matrix
+
+    def cartesian_to_fractional(self, cart_coords) -> np.ndarray:
+        return np.asarray(cart_coords, dtype=np.float64) @ np.linalg.inv(self.matrix)
+
+    def __repr__(self) -> str:
+        cp = self._cellpar
+        return (
+            f"Lattice(a={cp[0]:.4f}, b={cp[1]:.4f}, c={cp[2]:.4f}, "
+            f"alpha={cp[3]:.2f}, beta={cp[4]:.2f}, gamma={cp[5]:.2f})"
+        )

matcraft_kit-0.1.0/mckit/core/structure.py

@@ -0,0 +1,160 @@
+"""Atomic structure — a thin wrapper around ``ase.Atoms``.
+
+``Structure`` keeps a single ``ase.Atoms`` instance internally and forwards
+properties to it. Use ``structure.atoms`` to reach the full ASE API, or
+``structure.to_pymatgen()`` for pymatgen.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Dict, List, Optional, Sequence, Union
+
+import numpy as np
+from ase import Atom, Atoms
+
+from mckit.core.lattice import Lattice
+
+
+# 1 amu/ų in g/cm³
+_AMU_PER_A3_TO_G_PER_CM3 = 1.66053906660
+
+
+class Structure:
+    """A periodic atomic structure backed by ``ase.Atoms``.
+
+    Construct either from explicit ``lattice/species/positions`` (fractional
+    coords) or directly from an existing ``ase.Atoms`` via the ``atoms`` kwarg.
+    """
+
+    def __init__(
+        self,
+        lattice: Optional[Union[Lattice, np.ndarray]] = None,
+        species: Optional[Sequence[str]] = None,
+        positions: Optional[np.ndarray] = None,
+        *,
+        atoms: Optional[Atoms] = None,
+    ) -> None:
+        if atoms is not None:
+            self._atoms = atoms
+            return
+        if lattice is None:
+            raise ValueError("Provide either `atoms=` or `lattice=`.")
+        species = list(species) if species is not None else []
+        symbols = [str(s).strip().capitalize() for s in species]
+        if positions is None:
+            positions = np.empty((0, 3), dtype=np.float64)
+        positions = np.asarray(positions, dtype=np.float64).reshape(-1, 3)
+        if len(symbols) != positions.shape[0]:
+            raise ValueError(
+                f"species ({len(symbols)}) and positions ({positions.shape[0]}) "
+                "must have the same length."
+            )
+        cell = lattice.matrix if isinstance(lattice, Lattice) else lattice
+        self._atoms = Atoms(
+            symbols=symbols, scaled_positions=positions, cell=cell, pbc=True,
+        )
+
+    # ------------------------------------------------------------------
+    # Underlying ASE handle (escape hatch)
+    # ------------------------------------------------------------------
+    @property
+    def atoms(self) -> Atoms:
+        """The underlying ``ase.Atoms`` (mutating it mutates the Structure)."""
+        return self._atoms
+
+    # ------------------------------------------------------------------
+    # Derived views
+    # ------------------------------------------------------------------
+    @property
+    def lattice(self) -> Lattice:
+        return Lattice(matrix=np.asarray(self._atoms.cell.array))
+
+    @property
+    def species(self) -> List[str]:
+        return self.symbols
+
+    @property
+    def symbols(self) -> List[str]:
+        return list(self._atoms.get_chemical_symbols())
+
+    @property
+    def positions(self) -> np.ndarray:
+        """Fractional coordinates (no wrapping)."""
+        return self._atoms.get_scaled_positions(wrap=False)
+
+    @property
+    def cart_positions(self) -> np.ndarray:
+        return self._atoms.positions.copy()
+
+    @property
+    def num_atoms(self) -> int:
+        return len(self._atoms)
+
+    def __len__(self) -> int:
+        return len(self._atoms)
+
+    @property
+    def volume(self) -> float:
+        return float(self._atoms.cell.volume)
+
+    @property
+    def total_mass(self) -> float:
+        return float(self._atoms.get_masses().sum())
+
+    @property
+    def density(self) -> float:
+        """Mass density (g/cm³)."""
+        return self.total_mass * _AMU_PER_A3_TO_G_PER_CM3 / self.volume
+
+    @property
+    def composition(self) -> Dict[str, int]:
+        return dict(Counter(self._atoms.get_chemical_symbols()))
+
+    # ------------------------------------------------------------------
+    # Mutation
+    # ------------------------------------------------------------------
+    def add_atom(self, element: str, frac_position: Sequence[float]) -> None:
+        cart = np.asarray(frac_position, dtype=np.float64) @ self._atoms.cell.array
+        self._atoms.append(Atom(str(element).strip().capitalize(), position=cart))
+
+    def remove_atom(self, index: int) -> None:
+        del self._atoms[index]
+
+    def wrap_to_cell(self) -> None:
+        self._atoms.wrap()
+
+    def copy(self) -> "Structure":
+        return Structure(atoms=self._atoms.copy())
+
+    # ------------------------------------------------------------------
+    # Geometry / transforms (delegate to ASE)
+    # ------------------------------------------------------------------
+    def get_distance(self, i: int, j: int, mic: bool = True) -> float:
+        return float(self._atoms.get_distance(i, j, mic=mic))
+
+    def supercell(self, na: int, nb: int, nc: int) -> "Structure":
+        return Structure(atoms=self._atoms.repeat((na, nb, nc)))
+
+    # ------------------------------------------------------------------
+    # Interop
+    # ------------------------------------------------------------------
+    def to_ase_atoms(self) -> Atoms:
+        return self._atoms.copy()
+
+    @classmethod
+    def from_ase_atoms(cls, atoms: Atoms) -> "Structure":
+        return cls(atoms=atoms.copy())
+
+    def to_pymatgen(self):
+        from pymatgen.io.ase import AseAtomsAdaptor
+        return AseAtomsAdaptor().get_structure(self._atoms)
+
+    @classmethod
+    def from_pymatgen(cls, struct) -> "Structure":
+        from pymatgen.io.ase import AseAtomsAdaptor
+        return cls(atoms=AseAtomsAdaptor().get_atoms(struct))
+
+    def __repr__(self) -> str:
+        comp_str = " ".join(f"{s}{n}" for s, n in self.composition.items())
+        return f"Structure({comp_str}, natoms={self.num_atoms}, V={self.volume:.2f} A^3)"

matcraft_kit-0.1.0/mckit/core/tool.py

@@ -0,0 +1,48 @@
+"""Abstract base classes for matmod tools.
+
+Two families:
+
+* ``Operation``  — *builds* or *modifies* a ``Structure``. Subclasses define
+  ``apply(...)`` with whatever signature makes sense (no fixed contract on
+  arguments — the only requirement is that it returns a ``Structure``).
+* ``Observation`` — *inspects* a ``Structure`` and returns arbitrary data
+  without modifying it. Subclasses implement ``observe(structure, **kwargs)``.
+
+Adding a new tool is a one-class affair — see the examples in
+``matmod/operations/bulk.py`` and ``matmod/observations/info.py``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from mckit.core.structure import Structure
+
+
+class Operation(ABC):
+    """Base class for structure-building / modifying tools."""
+
+    @abstractmethod
+    def apply(self, *args, **kwargs) -> Structure:
+        """Run the operation and return the resulting ``Structure``."""
+
+    def __call__(self, *args, **kwargs) -> Structure:
+        return self.apply(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} Operation>"
+
+
+class Observation(ABC):
+    """Base class for structure-inspection tools."""
+
+    @abstractmethod
+    def observe(self, structure: Structure, **kwargs) -> Any:
+        """Inspect the structure and return arbitrary result data."""
+
+    def __call__(self, structure: Structure, **kwargs) -> Any:
+        return self.observe(structure, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} Observation>"

matcraft_kit-0.1.0/mckit/io/__init__.py

@@ -0,0 +1,10 @@
+"""I/O utilities (read/write structures) backed by ASE."""
+
+from mckit.io.reader import read_structure
+from mckit.io.writer import write_structure, write_atoms
+
+__all__ = [
+    "read_structure",
+    "write_structure",
+    "write_atoms",
+]