Example Gallery¶

Short, runnable workflows that each take a molecular description to a simulation-ready object in a handful of lines. The examples span the capability spectrum — a single small molecule, a packed solvent box, virtual-site models, and polymer systems (the stress test for MolPy's editing machinery). Every example links to the in-depth guide that explains the steps behind it.

For a fully narrated, step-by-step walkthrough — including the full LAMMPS export — start with the Quickstart.

Small molecule — parse, type, export¶

Parse a SMILES string, add hydrogens and coordinates, and assign OPLS-AA types.

import molpy as mp

mol   = mp.parser.parse_molecule("CCO")                  # ethanol from SMILES (heavy atoms)
mol   = mp.adapter.RDKitAdapter(mol).generate_3d(add_hydrogens=True)  # add hydrogens + 3D coordinates
ff    = mp.io.read_xml_forcefield("oplsaa.xml")          # bundled OPLS-AA
typed = mp.typifier.OplsTypifier(ff).typify(mol)         # assign force-field types

frame = typed.to_frame()   # simulation-ready columnar arrays
# mp.io.write_lammps_system("output/", frame, ff) writes system.data + system.ff
# (set frame.box and a per-atom mol_id first — see the Quickstart).

Solvent box — pack 500 waters¶

Build one molecule, then fill a periodic cube with clash-free copies through the Packmol backend.

Requires the packmol executable

Packing shells out to Packmol. Install it and make sure packmol is on your PATH.

import molpy as mp
from molpy.pack import Packmol, InsideBoxConstraint

water = mp.Atomistic(name="water")
o  = water.def_atom(element="O", x=0.000, y=0.000, z=0.000)
h1 = water.def_atom(element="H", x=0.957, y=0.000, z=0.000)
h2 = water.def_atom(element="H", x=-0.239, y=0.927, z=0.000)
water.def_bond(o, h1)
water.def_bond(o, h2)

p = Packmol(workdir="pack_out")
p.def_target(
    water.to_frame(),
    number=500,
    constraint=InsideBoxConstraint(length=30.0),  # a 30 Å cube
)
packed = p(max_steps=1000, seed=42)       # → one packed Frame (1500 atoms)

Virtual sites — TIP4P water¶

Augment a water molecule with an off-atom M-site on the HOH bisector. The builder copies the input, places the site, and redistributes charge.

import molpy as mp
from molpy.builder.virtualsite import Tip4pBuilder

water = mp.Atomistic(name="water")
o  = water.def_atom(element="O", x=0.000, y=0.000, z=0.000)
h1 = water.def_atom(element="H", x=0.957, y=0.000, z=0.000)
h2 = water.def_atom(element="H", x=-0.239, y=0.927, z=0.000)
water.def_bond(o, h1)
water.def_bond(o, h2)

water4p = Tip4pBuilder(d_om=0.1546).apply(water)   # d_om: O–M distance in nm; input unchanged

Polymer topologies — one monomer, eleven architectures¶

Guides and scripts share names under parallel trees:

Docs	Examples
`user-guide/topology/`	`examples/topology/`
`01_linear.md` … `11_prepolymer_agent.md`	`01_linear.py` … `11_prepolymer_agent.py`

cd examples
python topology/01_linear.py

Minimal linear chain (build_linear ≡ build("{[#EO]|10}")):

# run from examples/topology/ or put that dir on PYTHONPATH
from eo_kit import eo_builder

chain = eo_builder().build_linear("EO", 10)

See also: Polymer Topologies · Assembly.

Carbon nanotubes — topology from chirality¶

Build open or axially periodic zigzag, armchair, and chiral tubes without a public planning object:

from molpy.builder import CarbonTubeBuilder

builder = CarbonTubeBuilder()
zigzag = builder.build(8, 0, length=30.0)
armchair = builder.build(6, 6, cells=4, periodic=True)
chiral = builder.build(6, 3, cells=2, finalize="topology")

Polydisperse melt — Schulz-Zimm distribution¶

Sample a reproducible chain population from a molecular-weight distribution.

import molpy as mp
from molpy.builder import polymer_system

# Mn = 1500 Da, Mw = 3000 Da, total mass ≈ 500 kDa
chains = polymer_system(
    "{[<]CCOCC[>]}|schulz_zimm(1500,3000)||5e5|",
    random_seed=42,
)
print(f"Built {len(chains)} chains")   # reproducible chain population
frames = [c.to_frame() for c in chains]

AmberTools pipeline — GAFF2 parameters¶

Run a monomer through antechamber, parmchk2, and tleap to produce an AMBER topology with GAFF2 parameters and partial charges.

Requires AmberTools

This workflow shells out to antechamber, parmchk2, and tleap. Install AmberTools and activate its environment first.

import molpy as mp
from molpy.builder import polymer, prepare_monomer

eo = prepare_monomer("{[<]CCOCC[>]}")  # BigSMILES → 3D + ports

result = polymer(
    "{[#EO]|20}",
    library={"EO": eo},
    backend="amber",   # runs antechamber + parmchk2 + tleap
)
# result.prmtop_path, result.inpcrd_path, result.pdb_path