LigParGen 3.0 User Guide

Installing
Giving a molecule
Charges
The files for each program
Limits
Messages, and what to do
From the command line
Getting help
Citing LigParGen

What LigParGen does

You give LigParGen a molecule. BOSS, the Jorgensen group's simulation program, assigns each atom its OPLS-AA atom type and computes the partial charges with the CM1A model. LigParGen then writes the complete parameter set — charges, Lennard-Jones terms, bonds, angles, dihedrals and impropers — in the files of eleven simulation programs, so the same molecule has the same energy in each.

Everything runs on this computer. Nothing is sent anywhere, except a message you choose to send with Help.

1 · Installing

Mac (Apple Silicon: M1 and later)

Open LigParGen-3.0.0-arm64.dmg and drag LigParGen to Applications.
Open it from Applications. The first time, macOS may say it cannot check the developer: open System Settings → Privacy & Security and choose Open Anyway.

Windows (10 and 11, 64-bit)

Run LigParGen Setup 3.0.0.exe and follow the steps. It installs for you only, so no administrator rights are needed.
If Windows SmartScreen says it protected your PC, choose More info → Run anyway.

Linux (x86-64)

Make the file runnable and start it: chmod +x LigParGen-3.0.0.AppImage, then ./LigParGen-3.0.0.AppImage.
Some distributions need the FUSE 2 library to open AppImages (on Ubuntu: sudo apt install libfuse2).

Nothing else is needed: BOSS, Python and RDKit are inside the program.

2 · Giving a molecule

Draw

Draw the molecule in the editor (Ketcher, the same as on jorgensenresearch.com). Hydrogens are added for you.

SMILES

Paste a SMILES string, such as CC(=O)Oc1ccccc1C(=O)O for aspirin. Hydrogens are added for you; write charges in the SMILES (CC(=O)[O-]).

File

Drop a MOL, MOL2 or PDB file on the window, or choose one. A file must contain every hydrogen, at the protonation state you want. LigParGen keeps your file's atom order and atom names in every output file.

Name, residue and charge

Name is only a label: it names the files (aspirin.gmx.itp…) and their folder.
Residue is the three-letter residue name written inside the files.
Charge is the molecule's net charge. For a SMILES, drawing or MOL file it follows the structure by itself; for a PDB file, set it yourself.

Before you run, LigParGen checks the molecule and says Ready, or what needs fixing.

3 · Charges

1.14*CM1A-LBCC — for neutral molecules (the default). CM1A charges scaled by 1.14, with localized bond-charge corrections.
1.14*CM1A — for charged molecules. For an ion the 1.14 scale is not applied, as in the method.

The charges come from BOSS's own charge cycle: charges, then an OPLS-AA optimization with them, three times. Your structure keeps its own coordinates in the output files.

Single atoms and ions

A single atom or ion runs with BOSS's own OPLS-AA parameters for it: He, Ne, Ar, Kr, Xe; F⁻, Cl⁻, Br⁻, I⁻; Li⁺, Na⁺, K⁺, Rb⁺, Cs⁺; Mg²⁺, Ca²⁺, Sr²⁺, Ba²⁺; La³⁺, Nd³⁺, Eu³⁺, Gd³⁺. Other ions are not supported: use your force field's ion parameters.

4 · The files for each program

Results are saved in Documents › LigParGen › name (or the folder you chose), with CITE.txt and a log. In the Files tab you can drag any file, or a program's title for all its files, out of the window: onto the Desktop, into a folder, or into another program.

OpenMM — .openmm.xml, .openmm.pdb, .openmm.py. Build the system with from NAME.openmm import build; pdb, system = build(). The loader keeps OPLS's geometric combining rule and BOSS's impropers, which the XML alone cannot express.

GROMACS — .gmx.itp, .gmx.gro. Put #include "NAME.gmx.itp" in your topol.top.

AMBER — .amber.prmtop, .amber.inpcrd. Use with sander, pmemd or ParmEd. sander reports about 0.3 kcal/mol more per straight (180°) angle, as it cannot measure an angle that close to 180°.

CHARMM / NAMD — .charmm.rtf, .charmm.prm, .charmm.pdb. For NAMD, build the PSF with psfgen from the .rtf; the .prm carries NBFIX lines so NAMD mixes Lennard-Jones as OPLS does.

LAMMPS — .lammps.lmp (data), .lammps.in (settings): include NAME.lammps.in.

TINKER — .tinker.key, .tinker.xyz.

X-PLOR / CNS — .xplor.top, .xplor.param, .xplor.pdb (atom names in capitals, as X-PLOR reads them).

Q — .q.lib, .q.prm, .q.pdb. Desmond — .desmond.cms. PQR — .pqr.

BOSS / MCPRO — .z, the Z-matrix with its parameters, ready for BOSS and MCPRO.

LigParGen writes the molecule's parameters only: no water, no box and no run settings. Build those in your program as usual.

5 · Limits

Elements: H, C, N, O, F, Cl, Br, I, P, S, B, Si, Al.
Size: about 110 non-hydrogen atoms (250 atoms with hydrogens) for BOSS's charge calculation.
Optimization: molecules over about 150 atoms are past BOSS's optimizer, so their charges are computed once, on the shape given.
One molecule at a time: no salts, counter-ions or mixtures; remove counter-ions first.
Not supported: two-atom molecules (N₂, O₂, CO, HCl…: OPLS-AA types are for atoms in larger molecules — use a model made for small gases), proteins, boranes and carboranes, perchlorate-type halogens, polymer repeat units with open attachment points (*).

6 · Messages, and what to do

The file is missing hydrogen atoms.: Add hydrogens at the right protonation state (PyMOL: h_add; Open Babel: obabel in.pdb -O out.pdb -h), or give the molecule as SMILES.
The structure has a net formal charge of +1, but the net charge is set to 0.: Set the Charge to the structure's charge, or fix the structure.
1.14*CM1A-LBCC is for neutral molecules only.: Choose 1.14*CM1A for ions.
Some atoms are missing a bonded partner / an odd number of electrons / unpaired electrons.: Usually a missing hydrogen or a missing formal charge. Check the atoms named in the message.
Unbonded atoms closer than a bond length, as in a 2D drawing.: The file has flat or overlapping coordinates. Give it as SMILES, or save a 3D structure.
This structure contains several separate molecules / counter-ions / only ions.: Keep the one molecule you want parameters for.
Too large for BOSS.: See the limits above; parameterize a smaller fragment.
RDKit cannot read this SMILES or file.: Check the SMILES, or export the file again from your drawing program.
LigParGen stopped unexpectedly.: Use Help and attach the run: we will look at it.

7 · From the command line

For scripts and long lists, the same LigParGen runs in a terminal. Set it up once: About → Set up the ligpargen command, then open a new terminal. (On Linux you can also run ./LigParGen-3.0.0.AppImage ligpargen … directly.)

One molecule — LigParGen 2.1's own options

ligpargen -s "CC(=O)Oc1ccccc1C(=O)O" -n ASP -r ASP -c 0 -cgen CM1A-LBCC -p aspirin
ligpargen -i mymolecule.mol -n LIG -r LIG -p results/lig

Every option of LigParGen 2.1 works as before (-s, -i, -n, -r, -c, -cgen, -o, -p, -f, and the alchemical -sb, -ib…), so existing scripts keep running. Before a run the molecule gets the same check as in the window; --no-check skips it and --json prints a result a script can read.

A whole list

ligpargen batch molecules.csv -o results -j 4 — a CSV with the columns name, smiles or file, and optionally charge and cgen; or a folder: ligpargen batch my_mol_files/ -o results. One folder per molecule, and summary.csv with what ran and why anything did not.

Only the check

ligpargen check -s "[Na+]" -c 1 says Ready or what to fix. ligpargen --help lists everything.

8 · Getting help

Press Help, give your name and email and say what happened. Leave Attach the last run ticked so we can see the molecule, the settings and the log. We answer by email from support@jorgensenresearch.com. If this computer is offline, your email program opens with the message instead.

9 · Citing LigParGen

If LigParGen helped your work, please cite (the program also saves these in CITE.txt with every run):

Dodda, L. S.; Cabeza de Vaca, I.; Tirado-Rives, J.; Jorgensen, W. L. LigParGen Web Server: An Automatic OPLS-AA Parameter Generator for Organic Ligands. Nucleic Acids Res. 2017, 45, W331–W336.
Dodda, L. S.; Vilseck, J. Z.; Tirado-Rives, J.; Jorgensen, W. L. 1.14*CM1A-LBCC: Localized Bond-Charge Corrected CM1A Charges for Condensed-Phase Simulations. J. Phys. Chem. B 2017, 121, 3864–3870. (for 1.14*CM1A-LBCC charges)
Jorgensen, W. L.; Tirado-Rives, J. Molecular Modeling of Organic and Biomolecular Systems Using BOSS and MCPRO. J. Comput. Chem. 2005, 26, 1689–1700.