Metadata-Version: 2.4
Name: molcrys-kit
Version: 0.8.0
Summary: Molecular Crystal Toolkit
Author-email: MolCrysKit Development Team <none@example.com>
License: MIT
Project-URL: Homepage, https://github.com/SchrodingersCattt/MolCrysKit
Project-URL: Repository, https://github.com/SchrodingersCattt/MolCrysKit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.18.0
Requires-Dist: scipy>=1.4.0
Requires-Dist: networkx>=2.5.0
Requires-Dist: ase>=3.26.0
Requires-Dist: pymatgen>=2022.0.3
Requires-Dist: click<9,>=8.0
Provides-Extra: vis
Requires-Dist: nglview; extra == "vis"
Requires-Dist: py3Dmol; extra == "vis"
Provides-Extra: test
Requires-Dist: pytest>=6.0.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest-timeout>=2.0; extra == "test"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "test"
Requires-Dist: build; extra == "test"
Provides-Extra: dev
Requires-Dist: molcrys-kit[test,vis]; extra == "dev"
Requires-Dist: ruff==0.15.14; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: nbstripout; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# MolCrysKit: Molecular Crystal Toolkit

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](#)
[![PyPI](https://img.shields.io/pypi/v/molcrys-kit.svg)](https://pypi.org/project/molcrys-kit/)
[![unit-tests](https://github.com/SchrodingersCattt/MolCrysKit/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/SchrodingersCattt/MolCrysKit/actions/workflows/unit-tests.yml)

## Overview

MolCrysKit is a Python toolkit designed for handling molecular crystals, providing utilities for parsing crystallographic data, identifying molecules within crystals, and performing various analyses on molecular crystals using graph theory and the Atomic Simulation Environment (ASE).

## Key Features

- Robust Molecule Identification: Identify individual molecules within a crystal structure using graph-based algorithms
- Disorder Handling: Process disordered structures with graph algorithms
- Topological Surface Generation: Create surface slabs while preserving molecular topology
- Hydrogen Completion: Add hydrogen atoms with heuristic geometric placement rules
- Cluster Carving: Disorder resolution → desolvation → coordination-shell cluster extraction
- Nanocluster Carving: Build arbitrary finite shapes while preserving complete molecular or unit-cell topology
- LLM-based AI agent Friendliness: Try on https://matmaster.bohrium.com/matmaster or build your own skill for your agent
- Bundled Agent Skills: use `mck skills list`, `show`, and `tree` for read-only progressive access to shipped workflows

<p align="center">
  <img src="https://github.com/SchrodingersCattt/MolCrysKit/releases/download/readme-assets-v1/01_molecule_identification.png" width="357"><br>
  <em>Molecule Identification</em>
</p>

<p align="center">
  <img src="https://github.com/SchrodingersCattt/MolCrysKit/releases/download/readme-assets-v1/02_disorder_handling.png" width="548"><br>
  <em>Disorder Handling</em>
</p>

<p align="center">
  <img src="https://github.com/SchrodingersCattt/MolCrysKit/releases/download/readme-assets-v1/03_topological_surface.png" width="496"><br>
  <em>Topological Surface Generation</em>
</p>

<p align="center">
  <img src="https://github.com/SchrodingersCattt/MolCrysKit/releases/download/readme-assets-v1/04_hydrogen_completion.png" width="305"><br>
  <em>Hydrogen Completion</em>
</p>

<p align="center">
  <img src="https://github.com/SchrodingersCattt/MolCrysKit/releases/download/readme-assets-v1/05_cluster_carving.png" width="700"><br>
  <em>Cluster Carving</em>
</p>

<p align="center">
  <img src="https://github.com/SchrodingersCattt/MolCrysKit/releases/download/readme-assets-v1/06_shape_operations.png" width="700"><br>
  <em>Shape Operations</em>
</p>

## Installation

### From PyPI (recommended)

```bash
pip install molcrys-kit
```

Pymatgen users who want the namespace import path
(`from pymatgen.analysis.molcrys import ...`) can also install the thin addon
package `pymatgen-analysis-molcrys` (see `addons/pymatgen-analysis-molcrys/`).

### From source (development)

```bash
git clone https://github.com/SchrodingersCattt/MolCrysKit.git
cd MolCrysKit
pip install -e ".[dev]"
# optional pymatgen namespace addon
pip install -e addons/pymatgen-analysis-molcrys
```

All dependencies are declared in `pyproject.toml` (there is no separate
`requirements.txt`). `requires-python = ">=3.10"`. The available extras are:

| Extra | Adds |
|---|---|
| `[test]` | `pytest`, `pytest-cov` |
| `[vis]` | `nglview`, `py3Dmol` for 3-D visualisation in notebooks |
| `[dev]` | `[test]` + `[vis]` + `build`, `ruff==0.15.14`, `pre-commit`, `nbstripout`, `twine` |

So a contributor environment is `pip install -e ".[dev]"` and a CI / minimal
test environment is `pip install -e ".[test]"`.

### Optional separate formatting commit

In an activated `[dev]` environment, run `pre-commit install --hook-type
pre-commit` and `python scripts/install_style_hook.py` from the repository
root. The first command installs the existing lint and file checks. The
second installs an optional Git post-commit hook (and refuses to overwrite an
existing one). After a commit, this hook runs Ruff format on Python files in
that commit. If formatting changes them, it creates a separate `style:
format Python from previous commit` commit. It skips formatting when tracked
files have uncommitted changes, so it never incorporates unrelated work.
Git worktrees of the same clone share the hooks directory; install this hook
only if you want it available to that clone's worktrees. The usual Ruff
format hook remains available manually with
`pre-commit run ruff-format --hook-stage manual --all-files`.

Ruff formats whitespace and layout, but it does not rewrite dense logic into
more readable steps. The follow-up commit only happens when formatting
actually changes a file; a commit that is already formatted gets no extra
commit.

## Quick Start

Here's a simple example of how to use MolCrysKit:

```python
import molcrys_kit as mck
from ase import Atoms

# 1. Create a toy system (e.g., 2 Water molecules in a unit cell)
# In practice, you would typically load this from a file: atoms = read('cif_file.cif')
atoms = Atoms(
    symbols=['O', 'H', 'H', 'O', 'H', 'H'],
    positions=[
        [1.0, 1.0, 1.0], [1.8, 1.0, 1.0], [0.7, 1.6, 1.0],  # Molecule 1
        [5.0, 5.0, 5.0], [5.8, 5.0, 5.0], [4.7, 5.6, 5.0]   # Molecule 2
    ],
    cell=[10.0, 10.0, 10.0],
    pbc=True
)

# 2. Initialize MolecularCrystal (Automatically identifies molecules via graph logic)
crystal = mck.MolecularCrystal.from_ase(atoms)

# 3. Access Crystal & Molecular Properties
print(f"Lattice Parameters: {crystal.get_lattice_parameters()}")
print(f"Identified Molecules: {len(crystal.molecules)}") 

mol = crystal.molecules[0]
print(f"Molecule 1 Formula: {mol.get_chemical_formula()}")
print(f"Molecule 1 Center of Mass: {mol.get_center_of_mass()}")
```

## Citation

If you use MolCrysKit in academic work, please cite:

> Guo, M.-Y.; Zhang, W.-X. MolCrysKit: A Topology-Aware Toolkit for Bridging Experimental Molecular-Crystal Structures and Simulation-Ready Modeling. *J. Chem. Inf. Model.* **2026**, *66* (9), 4999-5007. https://doi.org/10.1021/acs.jcim.6c00168

For exact reproduction of the published JCIM results, use the archived
`v0.1.0` release together with the versioned container image and the material
under `paper/`. The `main` branch may continue to evolve after publication.


## Docker / Cloud

See [Docker Guide](docs/docker.md) for local Docker, Bohrium cloud deployment, and GHCR image publication.

## Command Line Interface

Installing MolCrysKit also installs the `mck` command. The CLI is self-documenting;
use `--help` at any level to see the exact arguments for your installed version:

```bash
mck --help
mck io --help
mck operate --help
mck analyze --help
mck operate cluster --help
mck operate nanocluster --help
mck operate void --help
mck build chain --help
mck validate-periodic-bundle --help
mck skills --help
mck skills list --json
```

The command groups roughly mirror the Python package layout:

- `mck io ...` — inspect molecular-crystal contents, extract molecules, and convert structures (`info`, `molecules`, `extract-molecule`, `convert`).
- `mck operate ...` — generate modified structures (`disorder`, `disorder-supercell`, `add-h`, `slab`, `cluster`, `nanocluster`, `void`, `supercell`, `vacancy`, `desolvate`, `interpolate`, `reorient`).
- `mck analyze ...` — print analysis reports (`summary`, `bfdh`, `interactions`, `bond-orders`, `polyhedra`, `sanity-check`).
- `mck build chain ...` — construct a geometry-native periodic chain bundle.
- `mck validate-periodic-bundle ...` — validate a periodic bundle and its sidecar.

## Documentation

| You are… | Start here |
|---|---|
| **Using the library** | [API & Capabilities](docs/api.md) · [Tutorials](docs/tutorials.md) · [Periodic chains](docs/periodic-chains.md) |
| **AI agent (using the library)** | [API & Capabilities](docs/api.md) — read "Capability Map" then "Module Index" |
| **AI agent (modifying code)** | [AGENTS.md](AGENTS.md) · [Architecture](docs/architecture.md) |
| **Docker / cloud** | [Docker Guide](docs/docker.md) |

[`molcrys_kit/`](molcrys_kit/) — source code · [`scripts/`](scripts/) — diagnostic utilities · [`examples/`](examples/) — CIF structure files

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
