Status: PACKAGE OVERVIEW / WORKFLOW GUIDANCE UNVERIFIED. This README is not canonical installation or training guidance for the current tree. MXtalTools has no universal training configuration, and the quick-start, installation, and linked documentation below have not been verified in this milestone. Read AGENTS.md for current scope and authority, then verify any command against the current package metadata, implementation, and focused tests before relying on it.

MXtalTools: Toolbox for machine learning on molecular crystals

A Python library built on PyTorch and PyTorch Geometric for machine learning tasks on molecules and molecular crystals.

Features:

• Crystal building -- fast, differentiable molecular crystal construction from asymmetric unit parameters
• Crystal density prediction -- predict packing coefficients from molecular structure
• Molecule autoencoder -- equivariant molecular encodings via pre-trained Mo3ENet
• Crystal scoring -- evaluate crystal structures against CSD statistics
• Crystal structure search -- optimize crystal packing with ML potentials
• Dataset utilities -- build molecular/crystal datasets from CSD, .cif, and .xyz files

Documentation

See our detailed docs at readthedocs.

Quick Start

from mxtaltools.dataset_utils.data_classes import MolData
from mxtaltools.dataset_utils.utils import collate_data_list
from mxtaltools.common.training_utils import load_molecule_scalar_regressor

# Create molecule from SMILES
mol = MolData.from_smiles("c1ccccc1", protonate=True, minimize=True, partial_charges=True)
batch = collate_data_list([mol])

# Predict crystal packing coefficient
model = load_molecule_scalar_regressor("checkpoints/cp_regressor.pt")
prediction = model(batch.clone())

Installation for Users

1. Install PyTorch and PyTorch Geometric (including torch-scatter, torch-sparse, torch-cluster) for your CUDA version:

   • PyTorch installation guide
   • PyG installation guide

2. Install MXtalTools:

   pip install mxtaltools

Installation for Developers

1. Clone the repository:

   git clone git@github.com:InfluenceFunctional/MXtalTools.git
   cd MXtalTools

2. Create a Python environment (pip+virtualenv recommended).

3. Install PyTorch and PyG as described above.

4. Install remaining dependencies:

   poetry install

5. For model training, login to Weights & Biases:

   wandb login

6. Create a user config in configs/users/YOUR_USERNAME.yaml with your paths and W&B settings. Pass --user YOUR_USERNAME when running.

7. (Optional) For crystal dataset construction from .cif files, install the CSD Python API with a valid CCDC license.

Reference

If you use this code in a publication, please cite:

@article{kilgour2023geometric,
  title={Geometric deep learning for molecular crystal structure prediction},
  author={Kilgour, Michael and Rogal, Jutta and Tuckerman, Mark},
  journal={Journal of Chemical Theory and Computation},
  volume={19},
  number={14},
  pages={4743--4756},
  year={2023},
  publisher={American Chemical Society}
}