Skip to content

Manual

MolPy

Programmable Python toolkit for molecular simulation workflows.

MolPy

The pipeline

A molecular description in, a runnable system out

One molecule, every stage, no detours through disk. Chemistry, coordinates, and parameters live in separate layers — pause at any boundary, inspect what you have, keep going.

One representation · six stages The same Atomistic graph becomes a typed, packed Frame — export it or analyze it in place

The Quickstart narrates a full system end to end; the Example Gallery collects short, copy-paste workflows.

In practice

Every stage is a few lines of Python

The six cards below mirror the pipeline, stage for stage. Polymers appear as a demonstration domain — coupling, crosslinking, and polydispersity stress every part of the editing machinery — not as the limit of what MolPy models.

01 · Parse / build

Describe chemistry as text

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

from molpy.builder import polymer

mol = mp.parser.parse_molecule("CCO")   # one molecule from SMILES
peo = polymer("{[<]CCOCC[>]}|10|")      # or a whole chain, DP = 10
02 · Edit

Rewire the topology, atom by atom

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

chain = mon_a.merge(mon_b)                # combine two monomers
chain.def_bond(anchor_C, port_O)          # form the new C–O bond
chain.del_atom(o_leave, h1, h2)           # remove the leaving water
chain = chain.get_topo(gen_angle=True, gen_dihe=True)
03 · Typify

Assign types while it's still data

SMARTS matching maps every atom, bond, angle, and dihedral to force-field parameters — inspectable and checkable before anything is exported.

ff    = mp.io.read_xml_forcefield("oplsaa.xml")      # bundled OPLS-AA
typed = mp.typifier.OplsTypifier(ff).typify(chain)
04 · Pack

Fill a periodic box with Packmol

Clash-free placement at target density, driving the battle-tested Packmol executable from Python. Prefer pure Rust? Our own molpack packer is in beta — try it.

from molpy.pack import Packmol, Target, InsideBoxConstraint

target = Target(typed.to_frame(), 500, InsideBoxConstraint(length=30.0))
packed = Packmol()([target], seed=42)     # one clash-free Frame
05 · Export

Write files your engine actually runs

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

packed.box = mp.Box.cubic(30.0)
mp.io.write_lammps_data("system.data", packed, atom_style="full")
mp.io.write_lammps_forcefield("system.ff", ff)
06 · Analyze

Turn trajectories into observables

Feed the same Frame straight into the Rust-backed compute kernel — neighbor search and g® in two calls, thirty more analyses behind them.

from molpy.compute import NeighborList, RDF

neighbors = NeighborList(cutoff=8.0)(packed)
result    = RDF(n_bins=50, r_max=8.0)(packed, neighbors)   # g(r) over the box

By design

Engineered to build on

A library first, not a black box: one shared data model, a Rust core, and explicit seams throughout — take a single piece, swap another out, or extend any of it without forking.

One data structure, whole ecosystem
Every MolCrafts tool speaks the same molrs-backed abstract data structure — molpack, molvis, and molmcp read it directly. No converters, no glue code between libraries.
A Rust kernel under everything
Frame, Block, and every compute operator are backed by molrs — a Rust column store with zero-copy NumPy views and O(N) linked-cell neighbor search.
Built for LLM agents
The molmcp suite serves MolPy's symbols, docs, and live structures over MCP — an agent inspects your Frame and calls the real API, grounded in the source rather than guessed.
Use one piece or all of them
Parser, builder, typifier, packer, I/O, and compute talk only through explicit data — no hidden shared state. Import the single layer you need and ignore the rest.
Nothing is hardcoded
Register a new compute operator, I/O format, force-field style, or typifier from outside the core — the internal catalogs are open registries, not baked-in lists.
Typed end to end
Public APIs carry full type hints, checked in CI with Astral's ty. Your editor autocompletes real signatures instead of falling back to Any.

Ecosystem

One carefully designed abstract data structure — no glue code

The carefully designed abstract data structure you build here is the same object every MolCrafts tool reads. One shared data model, so nothing between them needs an adapter.

molvis — interactive 3D molecules

Render the core abstract data structure in the browser: a standalone JavaScript library, an embeddable viewer for Jupyter notebooks, and an editor — one GPU renderer everywhere. Drag the aspirin to rotate it.

Explore molvis →

molpack
Molecular packing engine — the same clash-free packer as a CLI, a Rust crate, and a Python package.
molmcp
MCP server for LLM agents — graph-based code discovery plus live ecosystem providers.
molrs
The shared Rust molecular kernel — the core abstract data structure, with Python, WASM, and C bindings.

Integrations

Plays with the tools you already run

External tools connect through explicit adapters and wrappers — every integration optional, every boundary visible.

RDKit
Bidirectional Atomistic ↔ Mol conversion for embedding, conformers, and SMILES export.
AmberTools
antechamber, parmchk2, and tleap driven programmatically for GAFF charges and topologies.
Packmol
Clash-free packing into periodic boxes through a typed constraint interface.
LAMMPS · CP2K · OpenMM
Complete, ready-to-run input decks generated from MolPy data objects.
molrs · MCP
A Rust column store and compute kernel underneath; the MCP suite exposes symbols and docs to LLM agents.

Find your page

The manual

The manual splits by intent. Tutorials teach: get running, then the data model, chapter by chapter — read them once. Guides do: end-to-end task recipes — reach for one whenever you have a task in hand.

Tutorials

Learn. Install, run your first system in fifteen minutes, then the data model chapter by chapter.

Guides

Do the work. End-to-end recipes — parse, build, typify, pack, export — that assume the tutorials.

Compute

Trajectory analysis: distributions, transport, order parameters, spectra, and analysis workflows.

API Reference

Every public module, from core data structures to engine adapters.

Developer Guide

Contributing workflow, architecture overview, and the extension points for new capabilities.