CLI Conventions

Conventions shared across all mlmm commands.

Boolean options

Every on/off CLI toggle accepts all four forms:

Form

Example

Positive flag

--tsopt

Negative flag

--no-tsopt

Positive value

--tsopt True, --tsopt yes, --tsopt 1, --tsopt on

Negative value

--tsopt False, --tsopt no, --tsopt 0, --tsopt off

 
--tsopt --thermo --no-dft                        # toggle form
--tsopt True --thermo yes --dft 0                # value form
--tsopt true --thermo on --dft off               # mix is fine

All four forms route through a single root-CLI bool_compat synthesizer; the toggle form (--tsopt / --no-tsopt) is canonical, and the value form (--tsopt True) is accepted as a legacy alias for backward compatibility. tests/test_bool_compat_cli.py walks every registered bool option against every form on every release, so a missing entry is caught by CI.

--detect-layer is different: layer detection is automatic and enabled by default, so it is a positive-only marker rather than an on/off toggle.

Common toggles: --tsopt / --thermo / --dft (post-processing stages) · --dump (write trajectory files) · --preopt / --endopt (pre/post optimization) · --climb (climbing-image MEP).

Contributing a new bool flag

Declare the canonical interface as @click.option("--foo/--no-foo", ...) (or a shared add_*_option() factory). Runtime parameter introspection detects ordinary Click toggles. Add a manual hint in mlmm/cli/app.py only when normalization must happen before a lazy command is imported or a parser wrapper prevents introspection. Extend tests/test_bool_compat_cli.py for either path.

Progressive help

mlmm <subcmd> --help                # core options
mlmm <subcmd> --help-advanced       # full option set

all, every calc subcommand (opt, sp, tsopt, freq, irc, dft, scan / scan2d / scan3d, path-opt, path-search), and the main utilities (mm-parm, define-layer, add-elem-info, trj2fig, energy-diagram, oniom-export, extract, fix-altloc) follow this pattern.

Verbosity levels

-v/--verbose LEVEL is an integer from 0 to 3 (default 2) that sets how much each command prints to the console. It is a per-command option, so write it with the subcommand, e.g. mlmm opt -v 1 .... The same four levels apply to every command; command pages describe only their command-specific payload (e.g. the opt cycle table or the freq thermochemistry summary).

Level

What you see

-v 0

Silent. Confirm success from the exit code and the output artifacts.

-v 1

Milestones only: version, input summary, key settings, output location, dry-run / final status. No banner, [command], [mode], or config dump.

-v 2

Default. Adds the banner, [command], [mode], stage progress, the main optimizer cycle table, terminal status, the one-line Hessian summary, thermo / DFT summaries, and elapsed time.

-v 3

Debug: resolved config / dry-run plan, backend DEBUG, raw optimizer and internal-coordinate chatter, [HessianTiming], and [HessianVRAM].

A semantic failure is a failure at any level: a Traceback that appears only at -v 3 still means the run failed.

ML/MM required options

ML/MM calculation stages (opt, sp, tsopt, freq, irc, dft, scans, and path workflows) need the full-system Amber topology:

--parm real.parm7              # Amber parm7 topology of the full (real) system

mlmm all generates the topology automatically when --parm is omitted. Utilities and structure/topology preparation commands do not require it. Per-stage ML membership resolves in this order:

  1. --model-pdb when supplied.

  2. --model-indices when --model-pdb is omitted.

  3. Input PDB B-factor ML atoms under the default --detect-layer, when no explicit membership is supplied.

With explicit ML membership, valid input B-factors still define the movable/frozen MM layers; they do not replace the explicit ML atom set. A B-factor partition must contain at least one ML atom and one MM atom; an all-zero PDB is not treated as a layer assignment.

mlmm path-search -i R.pdb P.pdb --parm real.parm7 --model-pdb model.pdb -q 0 -m 1

Inspect resolved config

mlmm opt -i input.pdb --parm real.parm7 -q -1 --show-config --dry-run

B-factor layer encoding

Layer

B-factor

Meaning

ML

0.0

MLIP energy / force / Hessian

Movable-MM

10.0

MM atoms free to move

Frozen

20.0

Coordinates fixed (non-bonded interactions still included)

Tolerance ±1.0 when reading B-factors. Inspect visually by coloring on B-factor. Four ways to assign layers:

# 1. define-layer subcommand (recommended)
mlmm define-layer -i system.pdb --model-pdb ml_region.pdb -o labeled.pdb

# 2. Distance cutoffs (YAML)
calc:
  hess_cutoff: 3.6        # Hessian-target MM
  movable_cutoff: 8.0     # Movable-MM (beyond → Frozen)

# 3. Read existing B-factors
calc:
  use_bfactor_layers: true

# 4. Explicit index lists
calc:
  hess_mm_atoms:    [100, 101, 102, ...]
  movable_mm_atoms: [200, 201, 202, ...]
  frozen_mm_atoms:  [300, 301, 302, ...]

Residue selectors

Form

Example

Notes

By residue name

-c 'SAM,GPP' / -c 'LIG'

If multiple residues share a name, all matches are included (warning logged).

By residue ID

-c '123,456' / -c 'A:123,B:456' / -c '123A' / -c 'A:123A'

Optional chain prefix; trailing letter = insertion code.

By PDB file

-c substrate.pdb

Use coordinates from a separate PDB to locate substrates.

Charge specification

For PDB inputs, --ligand-charge specifies charges for unknown/non-standard ligand residues such as substrates and cofactors. Recognized ions use the internal ION table and must not be repeated in -l; the net charge of the selected ML region/model system is derived by summing amino-acid, recognized-ion, and supplied ligand charges.

-l 'SAM:1,GPP:-3'              # per-residue mapping (use the ':' separator)
-l -3                           # single integer = total ligand charge
-q 0                            # explicit ML-region/model-system charge override

Residue-name matching is case-insensitive; unmapped non-standard residues default to charge 0.

Resolution order (highest priority first):

  1. -q/--charge explicit CLI override.

  2. ML-region determination summary (sum of amino acids, ions, --ligand-charge; only when -c is set and extraction runs).

  3. --ligand-charge fallback when extraction is skipped (PDB input or --ref-pdb required).

  4. .gjf charge / spin header (Gaussian-style); the header is read only by oniom-import (bond-summary also reads .gjf geometry, but the optimization/MEP pipeline takes PDB/XYZ).

  5. Default: abort if unresolved.

Tip

Always provide --ligand-charge for non-standard residues so charges propagate correctly.

Spin multiplicity

-m 1    # singlet (default)
-m 2    # doublet
-m 3    # triplet

mm-parm uses the separate --ligand-mult for per-residue multiplicity metadata.

Atom selectors

--scan-lists '[(1, 5, 2.0)]'                                          # 1-based integer indices
--scan-lists '[("TYR,285,CA", "MMT,309,C10", 2.20)]'                  # PDB-style selector strings
--scan-lists '[("A:TYR:285:CA", "B:MMT:309A:C10", 2.20)]'             # exact chain-qualified form

Selector field delimiters: space · comma · slash · backtick · backslash — e.g. 'TYR 285 CA', 'TYR,285,CA', 'TYR/285/CA', 'TYR`285`CA', 'TYR\285\CA'. The three tokens (residue name / residue number / atom name) may appear in any order — the parser falls back to a heuristic for non-standard orderings.

For repeated identifiers and mmCIF inputs, prefer the exact four-field form CHAIN:RESNAME:RESSEQ[ICODE]:ATOM; it avoids heuristic matching and supports multi-character chains and residue numbers above 9,999.

Input file requirements

  • PDB — must contain hydrogens (add via reduce / pdb2pqr / Open Babel / mlmm mm-parm --add-h) and element symbols in cols 77–78 (mlmm add-elem-info if missing). Multiple PDBs must share identical atoms in the same order.

  • XYZ — accepted when ML-region determination is skipped (omit -c/--center).

  • Amber --parm (parm7) — force-field parameters for the full system; atom ordering must match the input PDB exactly.

Backend selection

ML/MM calculator subcommands (opt, sp, tsopt, freq, irc, scan / scan2d / scan3d, path-opt, path-search, and all) accept:

Option

Description

Default

-b, --backend

MLIP backend: uma, orb, mace, aimnet2.

uma

Install alternatives: pip install "mlmm-toolkit[orb]" / "[aimnet]" / pip uninstall -y fairchem-core && pip install mace-torch (MACE in a dedicated env; its e3nn pin conflicts with UMA).

Precision, workers, and analytical Hessians

Leaving --precision unset selects the backend default: UMA and AIMNet2 use fp32; ORB and MACE use fp64. AIMNet2 rejects fp64. Use explicit fp32 for ORB/MACE only when screening speed is more important than low-noise curvature.

--workers controls the UMA parallel predictor (fairchem-core[extras]), not generic CPU threading. The default is one worker. --workers > 1 cannot expose the autograd model needed for an analytical Hessian, so combining it with an explicit --hessian-calc-mode Analytical is a hard error. Choose one of:

--workers 1 --hessian-calc-mode Analytical       # analytical Hessian
--workers 4 --hessian-calc-mode FiniteDifference # parallel UMA predictor + FD

ORB, MACE, and AIMNet2 do not use this UMA worker pool. All four MLIP backends support an analytical/native Hessian with compatible installed versions; an unavailable analytical API raises rather than silently falling back.

--opt-mode (subcommand-dependent)

Warning

Choices and defaults differ across subcommands.

Subcommand

Gradient-only alias

Hessian-based alias

Default

Engine

opt

grad (lbfgs)

hess (rfo)

grad

L-BFGS vs RFO (with optional --microiter).

tsopt

grad (dimer)

hess (rsprfo; RS-P-RFO default, with RS-I-RFO / TRIM choices)

hess

Dimer vs Hessian-based TS optimizers.

all

grad

hess

grad

Fallback for TSOPT and post-IRC endpoint optimization; --opt-mode-post takes precedence.

Scan and path-search stages use their fixed L-BFGS optimizers and do not accept --opt-mode.

YAML precedence

defaults < config < CLI options

Three tiers; --config is the only YAML layer (no separate “override YAML”). Full schema: YAML Reference.

Output directory

--out-dir ./my_results/ overrides. Defaults: all → ./result_all/, per-stage subcommand → ./result_<subcmd>/ (e.g. result_opt/, result_tsopt/, result_path_search/). extract / mm-parm / define-layer default to the current directory or the explicit -o / --out-prefix.

See Also

Getting Started · Concepts & Workflow · Common Error Recipes · Troubleshooting · YAML Reference.