mchem-tools 0.1.2

M-Chem front-end: convert PDB to SQLite-DB formatted force-field parameters

---

M-Chem Setup Tools

---

Example: Solvate and Parameterize

This page walks through command-line usage: solvating a solute PDB, then parameterizing the solvated system and saving it to a SQLite database. The example uses the provided peptide structure examples/ace_ala_nme.pdb.

Prerequisites

The CLI is installed as mchem-tools (see the project’s installation instructions). Run mchem-tools --help to see available commands.

For the solvate command, Packmol must be installed and on your PATH. The convert command does not require external binaries.

Input PDB requirements

Warning: The input PDB must be prepared/fixed before use with mchem. mchem does not add hydrogens, missing atoms, missing residues, or terminal (capping) oxygens.

PDB files are read as-is: mchem.fileformats.pdb.load_pdb() parses ATOM/HETATM records and the topology is matched to residue templates via mchem.topology.Topology.matchTemplates(). Incomplete structures will fail template matching or yield incorrect parameters. Use an external tool (e.g. OpenMM Modeller, PDB2PQR, or a molecular builder) to add hydrogens, cap termini, and fill missing atoms or residues before running solvate or convert.

Example: Solvate then parameterize

Two-step workflow using the command line.

Step 1 — Solvate

• Input: A solute-only PDB (e.g. examples/ace_ala_nme.pdb). • Output: A solvated PDB with water, optional ions, and a CRYST1 periodic box record.

mchem-tools solvate -i examples/ace_ala_nme.pdb -o solvated.pdb

Optional flags: --box-shape (cube, dodecahedron, octahedron), --buffer (minimum padding in Å), --no-neutralize, --ionic-strength, --positive-ion, --negative-ion. Run mchem-tools solvate --help for details.

Step 2 — Parameterize (convert) to DB

• Input: The solvated PDB from step 1.

• Output: A SQLite database (e.g. system.db) containing force-field terms.

mchem-tools convert -i solvated.pdb -o system.db -f amoebabio18.xml

What the solvate command does

The solvate command (implemented in mchem.solvate and invoked from mchem.main) performs the following:

1. Load solute: The input PDB is loaded into a mchem.topology.Topology; atom positions are taken from the topology.
2. Charge: The net charge is computed by temporarily building a system with ForceField("amoebabio18_solvate.xml") and summing multipole monopoles. This value determines how many counterions to add when neutralization is requested.
3. Box: A periodic box shape is chosen (cube, dodecahedron, or octahedron). The box size is determined from the solute’s bounding sphere and the --buffer (minimum padding between solute and box edge). Box vectors are computed in reduced form (e.g. orthorhombic or triclinic).
4. Solute placement: The solute is shifted so its center lies at the box center in the orthorhombic frame used for packing.
5. Water and ions: The number of water molecules is estimated from (box volume approximate solute volume) × bulk water number density. Ion counts come from neutralization and, optionally, the requested ionic strength. Supported ion types are defined in mchem.solvate (e.g. Na+, K+, Cl-).
6. Packmol: The external Packmol program is run to place one fixed solute, N waters, and ions inside the box (default tolerance 2.0 Å).
7. Output: The combined solvated structure is read from Packmol’s output PDB; the CLI writes it to your output path with mchem.fileformats.pdb.write_pdb(), including box vectors as a CRYST1 record. Packmol must be installed and on your PATH for solvate to succeed. 1.5 What the convert command does The convert command (implemented in mchem.main) does the following:
8. Load topology: mchem.fileformats.pdb.load_pdb() reads the PDB, builds a mchem.topology. Topology with residues and atoms, and runs mchem.topology.Topology.matchTemplates() to assign residue templates (bonds and standard atom names).
9. Box (optional): mchem.fileformats.pdb.read_pdb_box() reads the CRYST1 record from the PDB if present. If present, a mchem.system.Box term is added to the system so the DB stores periodic boundary conditions.
10. Parameterize: mchem.forcefield.base.ForceField.createSystem() (i) assigns atom types from the force field XML, (ii) builds a mchem.system.System with a mchem.terms.nonbonded.Particle list (one per atom: index, name, symbol, mass, residue id, residue name, x, y, z), (iii) runs each force generator to create terms (bonds, angles, torsions, multipoles, vdW, polarization, etc.).
11. Save: mchem.system.System.save() writes the system to a SQLite file: a metadata table, a class map, and one table per term type (e.g. Particle, AmoebaBond, Multipole). No external binaries are required for convert; only the chosen force field XML (and its referenced templates) must be available.