molito 0.1.0__tar.gz

molito-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ross Irwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

molito-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: molito
+Version: 0.1.0
+Summary: Molecular representation and processing toolkit for storing and processing small molecules into a training-ready format
+Author-email: Ross Irwin <rssrwn@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rssrwn/molito
+Project-URL: Documentation, https://rssrwn.github.io/molito
+Project-URL: Repository, https://github.com/rssrwn/molito
+Project-URL: Issues, https://github.com/rssrwn/molito/issues
+Keywords: cheminformatics,molecules,machine-learning,rdkit,hdf5,conformers,drug-discovery
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.12
+Requires-Dist: rdkit>=2024.3
+Requires-Dist: h5py>=3.10
+Requires-Dist: biotite>=1.0
+Requires-Dist: more-itertools>=10.0
+Provides-Extra: interactions
+Requires-Dist: prolif>=2.0; extra == "interactions"
+Requires-Dist: MDAnalysis; extra == "interactions"
+Provides-Extra: dev
+Requires-Dist: matplotlib; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: py3Dmol; extra == "dev"
+Requires-Dist: ruff==0.16.0; extra == "dev"
+Requires-Dist: mypy==2.3.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Requires-Dist: ruff==0.16.0; extra == "docs"
+Dynamic: license-file
+
+# *Molito* - Small Molecule Data Processing Utility
+
+A Python toolkit for processing and storing small molecule and protein data into a training-ready format.
+
+Molito provides compact, serialisable representations for molecular graphs with atoms, bonds, and 3D conformer ensembles. It's designed for machine learning workflows where you need to go from RDKit molecules to structured arrays efficiently, with full support for stereochemistry (E/Z bond directions, tetrahedral chirality) preserved through round-trips. It also supports protein structures and protein-ligand complexes for binding data preprocessing, and integrates directly with RDKit, biotite and numpy.
+
+## Features
+
+- **Compact storage** — atomic numbers (uint8), charges (int8), chirality (int8), bonds (int16)
+- **Stereochemistry** — E/Z bond directions and chirality preserved through canonicalisation and atom reordering
+- **HDF5 persistence** — sharded save/load, with array data read on demand rather than up front
+- **Conformer ensembles** — multiple 3D conformers per molecule with optional Boltzmann weights
+- **Protein support** — residue annotations, biotite integration, prolif interaction detection
+- **Configurable vocabularies** — toggle chirality and E/Z directions without rewriting your dataset
+- **Lightweight** — core package needs only numpy, rdkit, scipy, h5py, biotite
+
+## Installation
+
+> Not yet on PyPI. For now, install editable from a local clone (see [Development](#development)).
+> Once published the install will be `pip install molito`.
+
+Requires Python >= 3.11.
+
+Optional extras:
+
+| extra | adds | enables |
+|---|---|---|
+| `interactions` | prolif, MDAnalysis | `Protein.to_prolif()`, `InteractionSet.from_system()` |
+| `dev`          | matplotlib, jupyter, ruff, mypy | development tooling |
+| `docs`         | mkdocs-material, mkdocstrings | building the documentation site |
+
+`optimise_mol_xtb()` additionally requires `xtb-python`, which only installs reliably from
+conda-forge:
+
+```bash
+mamba install -c conda-forge xtb-python
+```
+
+## Quick Start
+
+### Reading molecules
+
+```python
+from molito.mol import GraphBatch, GraphMol
+
+mol = GraphMol.from_smiles("C/C=C/C")
+
+# A whole SDF at once. Tags on each record become mol.meta, and 3D coordinates
+# are kept. Records holding only 2D depiction coordinates load without conformers.
+batch = GraphBatch.from_sdf("ligands.sdf", remove_hs=True)
+```
+
+RDKit molecules go in directly, which is also where the atom-ordering choice lives:
+
+```python
+from rdkit import Chem
+
+mol = GraphMol.from_rdkit(Chem.MolFromSmiles("C/C=C/C"))
+
+# Opt in to canonical atom ordering when ingesting the same compounds from
+# different formats, so the stored representation matches. Off by default.
+mol = GraphMol.from_rdkit(rdkit_mol, canonicalise=True)
+```
+
+### Accessing properties
+
+```python
+mol.atomics          # uint8 array of atomic numbers
+mol.charges          # int8 array of formal charges
+mol.tokens           # ['C_0', 'C_0', 'C_0', 'C_0'] — includes chirality if present
+mol.charged_symbols  # ['C_0', 'C_0', 'C_0', 'C_0'] — without chirality
+mol.bond_indices     # [n_bonds, 2] array
+mol.bond_types       # bond encoding indices
+mol.coords           # [n_confs, n_atoms, 3] float32, or None
+```
+
+### Writing molecules back out
+
+```python
+mol.to_smiles()                 # stereochemistry preserved
+rdkit_mol = mol.to_rdkit()      # None if the graph cannot be sanitised
+batch.to_sdf("out.sdf")         # meta entries are written as SDF tags
+```
+
+### Saving and loading datasets
+
+```python
+batch = GraphBatch([mol1, mol2, mol3])
+batch.save("my_dataset/", shard_size=1000, columnar_meta=True)
+
+loaded = GraphBatch.load("my_dataset/")
+mol = loaded[0]
+mol.atomics               # array data is read from HDF5 here, not at load time
+loaded.close_hdf5()       # loaded mols stop working after this - see below
+```
+
+For datasets beyond a million or so molecules, `materialise=False` skips building the
+Python objects until each molecule is asked for, and `meta_column` scans a metadata key
+without building any at all:
+
+```python
+import numpy as np
+
+loaded = GraphBatch.load("my_dataset/", materialise=False)
+
+ids = loaded.meta_column("mol_id")                 # one HDF5 column read
+train = loaded.subset(np.where(ids != "")[0])      # builds only the selection
+```
+
+Molecules from a loaded batch read their arrays from the open file, so they stop working
+once you call `close_hdf5()`. Call `mol.read()` to detach the ones you want to keep.
+
+### Vocabularies for model training
+
+```python
+from molito.core import VocabConfig
+
+# Defaults: chirality and E/Z directions enabled
+n_atom_types = len(VocabConfig.atoms)   # includes PAD, MASK, CW/CCW variants
+n_bond_types = len(VocabConfig.bonds)
+
+# Convert tokens to model indices (with chirality fallback)
+indices = VocabConfig.atoms.resolve_tokens(mol.tokens)
+
+# Disable features you don't need. This changes the model index space only —
+# the stored dataset is untouched.
+VocabConfig.set_chirality(False)
+VocabConfig.set_directions(False)
+```
+
+### Conformer generation and geometry
+
+These take RDKit molecules that already have hydrogens and a conformer; they return `None`
+rather than raising when the underlying force field cannot run.
+
+```python
+from rdkit import Chem
+from rdkit.Chem import AllChem
+from molito.geometry import calc_energy_mmff, optimise_mol_mmff, sample_ensemble
+
+rdkit_mol = Chem.AddHs(Chem.MolFromSmiles("CCO"))
+AllChem.EmbedMolecule(rdkit_mol)
+
+energy = calc_energy_mmff(rdkit_mol)
+opt_mol = optimise_mol_mmff(rdkit_mol, max_iters=500)
+
+# A Boltzmann-weighted ensemble: deduplicated, strain-filtered conformers plus weights
+final_mol, weights, e_min = sample_ensemble(rdkit_mol, max_confs=128)
+```
+
+### Proteins and complexes
+
+```python
+import biotite.structure.io as strucio
+from molito.mol import BindingComplex, Protein
+
+atom_array = strucio.load_structure("protein.pdb")
+protein = Protein.from_biotite(atom_array)
+
+system = BindingComplex(protein, ligand_mol)
+system.atomics      # ligand atoms first, then protein
+system.coords       # [n_complex_atoms, 3]
+```
+
+## Documentation
+
+- [Tutorial](docs/tutorial.md) — an SDF through to a padded training batch
+- [Concepts](docs/concepts.md) — bond encodings vs vocabulary indices, atom ordering, deferred loading, metadata
+- [Stereochemistry](docs/stereochemistry.md) — how stereo survives reordering, and what would break it
+- [Getting Started](docs/getting-started.md) — installation and the core classes
+
+Build the site locally with `mkdocs serve` after installing the `docs` extra.
+
+## Package Structure
+
+```
+molito/
+    core/           # AtomSet, BondSet, ConfSet, vocab, metadata, on-disk format
+    mol/            # GraphMol, Protein, BindingComplex, InteractionSet
+    geometry/       # conformer sampling, alignment, MMFF, xTB
+    convert.py      # RDKit <-> molito conversion
+    arrays.py       # numpy array ops (padding, one-hot, adjacency)
+```
+
+## Development
+
+Clone and install editable:
+
+```bash
+git clone https://github.com/rssrwn/molito
+cd molito
+pip install -e ".[interactions,dev]"
+```
+
+Run the tests:
+
+```bash
+python -m unittest discover tests/ -v
+```
+
+CI enforces lint, formatting and type checking, so run these before opening a PR:
+
+```bash
+ruff format . && ruff check . && mypy
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

molito-0.1.0/README.md

@@ -0,0 +1,209 @@
+# *Molito* - Small Molecule Data Processing Utility
+
+A Python toolkit for processing and storing small molecule and protein data into a training-ready format.
+
+Molito provides compact, serialisable representations for molecular graphs with atoms, bonds, and 3D conformer ensembles. It's designed for machine learning workflows where you need to go from RDKit molecules to structured arrays efficiently, with full support for stereochemistry (E/Z bond directions, tetrahedral chirality) preserved through round-trips. It also supports protein structures and protein-ligand complexes for binding data preprocessing, and integrates directly with RDKit, biotite and numpy.
+
+## Features
+
+- **Compact storage** — atomic numbers (uint8), charges (int8), chirality (int8), bonds (int16)
+- **Stereochemistry** — E/Z bond directions and chirality preserved through canonicalisation and atom reordering
+- **HDF5 persistence** — sharded save/load, with array data read on demand rather than up front
+- **Conformer ensembles** — multiple 3D conformers per molecule with optional Boltzmann weights
+- **Protein support** — residue annotations, biotite integration, prolif interaction detection
+- **Configurable vocabularies** — toggle chirality and E/Z directions without rewriting your dataset
+- **Lightweight** — core package needs only numpy, rdkit, scipy, h5py, biotite
+
+## Installation
+
+> Not yet on PyPI. For now, install editable from a local clone (see [Development](#development)).
+> Once published the install will be `pip install molito`.
+
+Requires Python >= 3.11.
+
+Optional extras:
+
+| extra | adds | enables |
+|---|---|---|
+| `interactions` | prolif, MDAnalysis | `Protein.to_prolif()`, `InteractionSet.from_system()` |
+| `dev`          | matplotlib, jupyter, ruff, mypy | development tooling |
+| `docs`         | mkdocs-material, mkdocstrings | building the documentation site |
+
+`optimise_mol_xtb()` additionally requires `xtb-python`, which only installs reliably from
+conda-forge:
+
+```bash
+mamba install -c conda-forge xtb-python
+```
+
+## Quick Start
+
+### Reading molecules
+
+```python
+from molito.mol import GraphBatch, GraphMol
+
+mol = GraphMol.from_smiles("C/C=C/C")
+
+# A whole SDF at once. Tags on each record become mol.meta, and 3D coordinates
+# are kept. Records holding only 2D depiction coordinates load without conformers.
+batch = GraphBatch.from_sdf("ligands.sdf", remove_hs=True)
+```
+
+RDKit molecules go in directly, which is also where the atom-ordering choice lives:
+
+```python
+from rdkit import Chem
+
+mol = GraphMol.from_rdkit(Chem.MolFromSmiles("C/C=C/C"))
+
+# Opt in to canonical atom ordering when ingesting the same compounds from
+# different formats, so the stored representation matches. Off by default.
+mol = GraphMol.from_rdkit(rdkit_mol, canonicalise=True)
+```
+
+### Accessing properties
+
+```python
+mol.atomics          # uint8 array of atomic numbers
+mol.charges          # int8 array of formal charges
+mol.tokens           # ['C_0', 'C_0', 'C_0', 'C_0'] — includes chirality if present
+mol.charged_symbols  # ['C_0', 'C_0', 'C_0', 'C_0'] — without chirality
+mol.bond_indices     # [n_bonds, 2] array
+mol.bond_types       # bond encoding indices
+mol.coords           # [n_confs, n_atoms, 3] float32, or None
+```
+
+### Writing molecules back out
+
+```python
+mol.to_smiles()                 # stereochemistry preserved
+rdkit_mol = mol.to_rdkit()      # None if the graph cannot be sanitised
+batch.to_sdf("out.sdf")         # meta entries are written as SDF tags
+```
+
+### Saving and loading datasets
+
+```python
+batch = GraphBatch([mol1, mol2, mol3])
+batch.save("my_dataset/", shard_size=1000, columnar_meta=True)
+
+loaded = GraphBatch.load("my_dataset/")
+mol = loaded[0]
+mol.atomics               # array data is read from HDF5 here, not at load time
+loaded.close_hdf5()       # loaded mols stop working after this - see below
+```
+
+For datasets beyond a million or so molecules, `materialise=False` skips building the
+Python objects until each molecule is asked for, and `meta_column` scans a metadata key
+without building any at all:
+
+```python
+import numpy as np
+
+loaded = GraphBatch.load("my_dataset/", materialise=False)
+
+ids = loaded.meta_column("mol_id")                 # one HDF5 column read
+train = loaded.subset(np.where(ids != "")[0])      # builds only the selection
+```
+
+Molecules from a loaded batch read their arrays from the open file, so they stop working
+once you call `close_hdf5()`. Call `mol.read()` to detach the ones you want to keep.
+
+### Vocabularies for model training
+
+```python
+from molito.core import VocabConfig
+
+# Defaults: chirality and E/Z directions enabled
+n_atom_types = len(VocabConfig.atoms)   # includes PAD, MASK, CW/CCW variants
+n_bond_types = len(VocabConfig.bonds)
+
+# Convert tokens to model indices (with chirality fallback)
+indices = VocabConfig.atoms.resolve_tokens(mol.tokens)
+
+# Disable features you don't need. This changes the model index space only —
+# the stored dataset is untouched.
+VocabConfig.set_chirality(False)
+VocabConfig.set_directions(False)
+```
+
+### Conformer generation and geometry
+
+These take RDKit molecules that already have hydrogens and a conformer; they return `None`
+rather than raising when the underlying force field cannot run.
+
+```python
+from rdkit import Chem
+from rdkit.Chem import AllChem
+from molito.geometry import calc_energy_mmff, optimise_mol_mmff, sample_ensemble
+
+rdkit_mol = Chem.AddHs(Chem.MolFromSmiles("CCO"))
+AllChem.EmbedMolecule(rdkit_mol)
+
+energy = calc_energy_mmff(rdkit_mol)
+opt_mol = optimise_mol_mmff(rdkit_mol, max_iters=500)
+
+# A Boltzmann-weighted ensemble: deduplicated, strain-filtered conformers plus weights
+final_mol, weights, e_min = sample_ensemble(rdkit_mol, max_confs=128)
+```
+
+### Proteins and complexes
+
+```python
+import biotite.structure.io as strucio
+from molito.mol import BindingComplex, Protein
+
+atom_array = strucio.load_structure("protein.pdb")
+protein = Protein.from_biotite(atom_array)
+
+system = BindingComplex(protein, ligand_mol)
+system.atomics      # ligand atoms first, then protein
+system.coords       # [n_complex_atoms, 3]
+```
+
+## Documentation
+
+- [Tutorial](docs/tutorial.md) — an SDF through to a padded training batch
+- [Concepts](docs/concepts.md) — bond encodings vs vocabulary indices, atom ordering, deferred loading, metadata
+- [Stereochemistry](docs/stereochemistry.md) — how stereo survives reordering, and what would break it
+- [Getting Started](docs/getting-started.md) — installation and the core classes
+
+Build the site locally with `mkdocs serve` after installing the `docs` extra.
+
+## Package Structure
+
+```
+molito/
+    core/           # AtomSet, BondSet, ConfSet, vocab, metadata, on-disk format
+    mol/            # GraphMol, Protein, BindingComplex, InteractionSet
+    geometry/       # conformer sampling, alignment, MMFF, xTB
+    convert.py      # RDKit <-> molito conversion
+    arrays.py       # numpy array ops (padding, one-hot, adjacency)
+```
+
+## Development
+
+Clone and install editable:
+
+```bash
+git clone https://github.com/rssrwn/molito
+cd molito
+pip install -e ".[interactions,dev]"
+```
+
+Run the tests:
+
+```bash
+python -m unittest discover tests/ -v
+```
+
+CI enforces lint, formatting and type checking, so run these before opening a PR:
+
+```bash
+ruff format . && ruff check . && mypy
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

molito-0.1.0/molito/__init__.py

@@ -0,0 +1,33 @@
+"""molito: Molecular representation and processing toolkit.
+
+Provides data structures for representing molecules as graphs with atoms, bonds, and 3D conformers,
+with efficient HDF5 serialization. Supports chirality, E/Z stereo, protein structures, and
+protein-ligand complexes.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from molito.core import PT, AtomSet, BondEncoding, BondSet, ConfSet, VocabConfig
+from molito.mol import BindingComplex, ComplexBatch, GraphBatch, GraphMol, Protein, ProteinBatch
+
+try:
+    __version__ = version("molito")
+except PackageNotFoundError:
+    # Package isn't installed (e.g. running from a source checkout without `pip install -e .`)
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "PT",
+    "AtomSet",
+    "BindingComplex",
+    "BondEncoding",
+    "BondSet",
+    "ComplexBatch",
+    "ConfSet",
+    "GraphBatch",
+    "GraphMol",
+    "Protein",
+    "ProteinBatch",
+    "VocabConfig",
+    "__version__",
+]

molito-0.1.0/molito/arrays.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import numpy as np
+
+TArr = np.ndarray
+
+
+def pad_arrays(arrays: list[TArr]) -> TArr:
+    """Pad a list of arrays with zeros along the first dimension.
+
+    All dimensions other than the first must have the same shape across arrays.
+
+    Args:
+        arrays: List of numpy arrays to pad.
+
+    Returns:
+        np.ndarray: Batched, padded array, shape [B, L, *] where L is length of longest array.
+    """
+
+    if len(arrays) == 0:
+        return np.array([])
+
+    max_len = max(arr.shape[0] for arr in arrays)
+    batch_shape = (len(arrays), max_len, *arrays[0].shape[1:])
+    padded = np.zeros(batch_shape, dtype=arrays[0].dtype)
+
+    for i, arr in enumerate(arrays):
+        padded[i, : arr.shape[0]] = arr
+
+    return padded
+
+
+def one_hot_encode(indices: TArr, vocab_size: int) -> TArr:
+    """Create one-hot encodings from indices.
+
+    Args:
+        indices: Indices into one-hot vectors, shape [*].
+        vocab_size: Length of returned vectors.
+
+    Returns:
+        np.ndarray: One-hot encoded vectors, shape [*, vocab_size].
+    """
+
+    one_hots = np.zeros((*indices.shape, vocab_size), dtype=np.long)
+    np.put_along_axis(one_hots, np.expand_dims(indices, -1), 1.0, axis=-1)
+    return one_hots
+
+
+def adj_from_edges(edge_indices: TArr, edge_types: TArr, n_nodes: int, symmetric: bool = False) -> TArr:
+    """Create adjacency matrix from edge indices and types.
+
+    Args:
+        edge_indices: Edge list, shape [n_edges, 2]. Pairs of (from_idx, to_idx).
+        edge_types: Edge types, shape [n_edges].
+        n_nodes: Number of nodes in the adjacency matrix.
+        symmetric: If True, fill both (i,j) and (j,i) for each edge.
+
+    Returns:
+        np.ndarray: Adjacency matrix, shape [n_nodes, n_nodes].
+    """
+
+    adj = np.zeros((n_nodes, n_nodes), dtype=edge_types.dtype)
+
+    if len(edge_indices) == 0:
+        return adj
+
+    adj[edge_indices[:, 0], edge_indices[:, 1]] = edge_types
+
+    if symmetric:
+        adj[edge_indices[:, 1], edge_indices[:, 0]] = edge_types
+
+    return adj