MolPy

The Quickstart walks through one full system end to end. The Example Gallery collects shorter copy-paste recipes.

01 · Parse / build

Describe chemistry as text ¶

One line of SMILES or BigSMILES becomes an editable structure — a single molecule or a polymer chain.

import molpy as mp
from molpy.conformer import Conformer

mol = mp.io.read_smiles("CCO")  # one molecule from SMILES
mol, report = Conformer(seed=42).generate(mol)  # hydrogens + 3D coordinates

02 · Edit

Rewire the topology ¶

Merge structures, form and break bonds, drop leaving groups, then re-derive angles and dihedrals across the new junction.

dimer = mol.copy().merge(mol.copy())  # combine two copies
dimer.get_topo(gen_angle=True, gen_dihe=True)  # derive angles/dihedrals in place

03 · Typify

Assign force-field types ¶

SMARTS matching maps every atom, bond, angle, and dihedral to parameters you can inspect before anything is exported.

ff = mp.io.read_xml_forcefield("oplsaa.xml")  # bundled OPLS-AA
typed = mp.typifier.OPLSAATypifier().typify(mol)
system = typed.to_frame()  # the numeric Frame
system.box = mp.Box.cubic(30.0)

04 · Pack

Fill a periodic box ¶

Clash-free placement at a target density via molpack — Packmol-grade packing as a library, no external binary (pip install molcrafts-molpack).

# docs: skip — optional molcrafts-molpack; not a molpy runtime/doc dep
from molpack import InsideBoxRestraint, Molpack, Target

target = (
    Target(system, count=500)
    .with_restraint(InsideBoxRestraint([0.0, 0.0, 0.0], [30.0, 30.0, 30.0]))
)
system = Molpack().with_seed(42).pack([target], max_loops=200)

05 · Export

Write files your engine runs ¶

One call per file: LAMMPS data plus force-field coefficients. GROMACS, PDB, and Zarr (MolStore) writers share the same pattern.

import numpy as np

atoms = system["atoms"]
atoms["mol_id"] = np.ones(atoms.nrows, dtype=np.uint32)  # full atom style needs mol_id
mp.io.write_lammps_data("system.data", system, atom_style="full")
mp.io.write_lammps_forcefield("system.ff", ff)

06 · Analyze

Turn trajectories into observables ¶

Feed the same Frame into the compute layer — neighbor search and \(g(r)\) in two calls, with many more analyses behind them.

from molpy.compute import NeighborList, RDF

system.box = mp.Box.cubic(30.0)
neighbors = NeighborList(cutoff=8.0)(system)
result = RDF(n_bins=50, r_max=8.0)([system], [neighbors])  # g(r) over the box

One data structure across the ecosystem: molpack, molvis, and molmcp speak the same Frame / Block. No converters between libraries.
A high-performance kernel underneath: Storage and compute live in the high-performance backend. Python sees zero-copy NumPy views on the public facade.
Built for LLM agents: The molmcp suite exposes symbols and docs over MCP so an agent can call the real API instead of guessing from training data.
Use one piece or all of them: Parser, builder, typifier, packer, I/O, and compute talk only through explicit data. Import the layer you need and ignore the rest.
Registries, not hardcoded lists: Register a compute operator, I/O format, force-field style, or typifier from outside the core without patching the package itself.
Typed end to end: Public APIs carry full type hints, checked in CI with Astral’s ty. Your editor sees real signatures, not Any.

Figure 1. Aspirin (PubChem) in molvis, ball-and-stick, from inline XYZ.

molpack: Clash-free packing as a CLI, a library crate, and a Python package — same engine everywhere.
molmcp: MCP server for LLM agents: code discovery plus live ecosystem providers.
Native backend: The shared high-performance molecular kernel — Frame, Block, and compute, with Python and other bindings.

RDKit: Bidirectional Atomistic ↔ Mol for embedding, conformers, and SMILES export.
AmberTools: antechamber, parmchk2, and tleap driven from Python for GAFF charges and topologies.
molpack: Clash-free packing into periodic boxes through a typed restraint interface.
LAMMPS · CP2K · OpenMM: Ready-to-run input decks generated from MolPy data objects.
Native backend · MCP: High-performance column store and compute underneath; MCP exposes symbols and docs to agents.

MolPy

From a molecule description to a runnable system¶

Each stage is a few lines of Python¶

Describe chemistry as text ¶

Rewire the topology ¶

Assign force-field types ¶

Fill a periodic box ¶

Write files your engine runs ¶

Turn trajectories into observables ¶

Built to be composed, not locked in¶

The structure you build is the structure everything else reads¶

Optional tools, explicit boundaries¶

How the manual is split¶

Tutorials ¶

Guides ¶

Compute ¶

API Reference ¶

Developer Guide ¶