matcraft-kit 0.1.0__py3-none-any.whl

matcraft_kit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,25 @@
+mckit/__init__.py,sha256=Wd87JxoIkVKrJakY5RoT3IvSfDoQ5q4w_8aM5stxYrU,697
+mckit/cli.py,sha256=6LVCspQzcXozltprvvCBMrybF0LGrlrjuRf_g-uS_n4,2627
+mckit/core/__init__.py,sha256=cP0Ru_YhC6ruHa6yjyauA8XR1ATmmT0VuscKsI0wJ30,162
+mckit/core/lattice.py,sha256=BT6G4KFxHZjyYWag68q0yThGrvMnsLUSI2yOPF8Oe8I,3504
+mckit/core/structure.py,sha256=h0mzSgd7oTJXXs8SA0zRgRrKeJd9upAVw9V6D26OoK8,5579
+mckit/core/tool.py,sha256=S9c24YGTNaaW5Q__RougE8Q4YeSuumy9Ugcm3YIpU8Y,1562
+mckit/io/__init__.py,sha256=OEUgXPIT1H1yA33ixVKYJyT7jbqoh6chZkjqKZA0rpg,239
+mckit/io/reader.py,sha256=enWiZk9UOsRyjtvA6rha3umvxKbvbSwpTD7nIdrLVv8,1389
+mckit/io/writer.py,sha256=nEmnEelKyjEvhi4rRIwc4vAQlk1mdcMd8_L5al0InuM,1196
+mckit/observe/__init__.py,sha256=Fl8izOl_oEBB_QzqE9emN3kW2-4dW5vQ7kUirVGuy-o,648
+mckit/observe/fundamental.py,sha256=vMHfB0KNAUDEbp2eQSS2yLZwlSW3e39mvDFUnOqlVT0,5568
+mckit/observe/info.py,sha256=CFIIQooF4xqPLcm-hVNIaGSNW04iUUBz9wfY12WqYtc,24997
+mckit/operate/__init__.py,sha256=xzSRRnqK3LNrZAPWvzfoFV6xOZ8AkWYsgWcPhzoN150,1532
+mckit/operate/bulk.py,sha256=hra4slQUpC-2gwt-A4a3mNDHJXo7jissaGbJu_dxSSM,5122
+mckit/operate/defect_creation.py,sha256=tBwtLX_SxJ3Hg78Z38xJijREHeJARjcKSA1oHrt9g7E,35316
+mckit/operate/interface.py,sha256=XSeY59NOAsLWooOlFm_SnhjyKLsN6AiZXZtTVpIHbiw,43924
+mckit/operate/molecule_creation.py,sha256=q82-y3fJBpe6-6dFH4gTuXMQfQ3xMZoYRlbXN1waeRg,8465
+mckit/operate/perturbation.py,sha256=YABOXSdQkB7_J-xIAvo0NaPIWyPY_8jXJr7dcNEuG3U,20415
+mckit/operate/supercell.py,sha256=yGISGZTeTcSMz2iVzG1ca5GPuRW8u0MMDHwmI0-kbIY,6609
+mckit/operate/surface.py,sha256=hn5zjBwhUQGdg8USeESXoeqObx26TTTKJQita4GXvfA,45151
+matcraft_kit-0.1.0.dist-info/METADATA,sha256=F1BW2iQDu22Zxji_aVjGIpxDPR6WkOOZWyJJFmq6ars,388
+matcraft_kit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+matcraft_kit-0.1.0.dist-info/entry_points.txt,sha256=sCf8fpBCkjx6M31fS9gLV-cPV8_M9QiDdDtn__oDgxw,41
+matcraft_kit-0.1.0.dist-info/top_level.txt,sha256=cNncfWCbWtrmRnK9O4jEneIGm149-ABESk2m9CSgTms,6
+matcraft_kit-0.1.0.dist-info/RECORD,,

matcraft_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

matcraft_kit-0.1.0.dist-info/entry_points.txt

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

matcraft_kit-0.1.0.dist-info/top_level.txt

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

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",
+]

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()

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

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})"
+        )

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)"

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>"

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",
+]

mckit/io/reader.py

@@ -0,0 +1,47 @@
+"""Read structures as ``ase.Atoms`` using ASE (and pymatgen for CIF)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from ase import Atoms
+from ase.io import read as ase_read
+
+
+def read_structure(path: str, format: Optional[str] = None, **kwargs) -> Atoms:
+    """Read a structure file as ``ase.Atoms``.
+
+    Supports all formats that ASE supports (extxyz, vasp, cif, xyz, poscar, ...)
+    plus CIF via pymatgen for better handling of symmetry.
+
+    Parameters
+    ----------
+    path : str
+        File path.
+    format : str, optional
+        ASE format hint (e.g. ``"vasp"``, ``"cif"``). Auto-detected if omitted.
+    **kwargs
+        Extra keyword arguments forwarded to ``ase.io.read``.
+
+    Returns
+    -------
+    ase.Atoms
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    # Use pymatgen for CIF (better symmetry handling)
+    if p.suffix.lower() == ".cif" and format is None:
+        from pymatgen.io.cif import CifParser
+
+        parser = CifParser(str(p))
+        structs = parser.parse_structures(primitive=False)
+        if not structs:
+            raise ValueError(f"No structures parsed from {path}")
+        from pymatgen.io.ase import AseAtomsAdaptor
+
+        return AseAtomsAdaptor().get_atoms(structs[0])
+
+    return ase_read(str(p), format=format, **kwargs)

mckit/io/writer.py

@@ -0,0 +1,41 @@
+"""Write atomic structures to files via ``ase.io.write``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Union
+
+from ase import Atoms
+from ase.io import write as ase_write
+
+from mckit.core.structure import Structure
+
+
+def write_structure(
+    path: str,
+    structure: Union[Structure, Atoms, "PmgStructure"],
+    format: Optional[str] = None,
+    **kwargs,
+) -> str:
+    """Write a ``Structure`` (or raw ``ase.Atoms`` / pymatgen ``Structure``) to a file.
+
+    The output format is auto-detected from the extension when ``format`` is
+    omitted; missing extensions default to ``.extxyz``.
+    """
+    if isinstance(structure, Structure):
+        atoms = structure.to_ase_atoms()
+    elif isinstance(structure, Atoms):
+        atoms = structure
+    else:
+        # Assume pymatgen Structure (or compatible)
+        from pymatgen.io.ase import AseAtomsAdaptor
+        atoms = AseAtomsAdaptor().get_atoms(structure)
+    p = Path(path)
+    if p.suffix == "":
+        p = p.with_suffix(".extxyz")
+    ase_write(str(p), atoms, format=format, **kwargs)
+    return str(p)
+
+
+# Back-compat alias used by ``operations.surface``.
+write_atoms = write_structure

mckit/observe/__init__.py

@@ -0,0 +1,21 @@
+"""Structure inspection tools."""
+
+__all__ = [
+    "BasicInfo",
+    "InfoSection",
+    "SlabCompositionInfo",
+    "StructureInfo",
+    "VacuumInfo",
+    "FundamentalCheck",
+]
+
+
+def __getattr__(name):
+    """Lazy import to avoid loading heavy dependencies at startup."""
+    if name in ("BasicInfo", "InfoSection", "SlabCompositionInfo", "StructureInfo", "VacuumInfo"):
+        from mckit.observe import info
+        return getattr(info, name)
+    if name == "FundamentalCheck":
+        from mckit.observe.fundamental import FundamentalCheck
+        return FundamentalCheck
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")