MolCrysKit: Molecular Crystal Toolkit

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 Addition: Automatically add hydrogen atoms based on geometric rules

Installation

To install MolCrysKit, you can use pip:

pip install .

Or for development purposes, install in editable mode:

pip install -e .

Quick Start

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

from ase import Atoms
from molcrys_kit.structures.crystal import MolecularCrystal

# 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 = 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()}")

Documentation

For detailed architecture, tutorials, and API reference, please see the docs/ directory.

Project Structure

See the molcrys_kit/ directory for source code and the scripts/ directory for examples.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.