The caps command line

First steps

Run caps with no arguments to see every command and its main options on one screen. The workflow commands (coarse-graining and DFT surfaces) also take --help, which prints every option with its default and the reason for that default:

caps                      # the usage: every command
caps cgfit --help         # one command's options, defaults and reasons
caps info ps.data          # any structure: atoms, molecules, bonds, cell, frames

caps info is the quickest check that a file reads as you expect. Sample structures and recipes ship in the program's samples folder.

Conventions every command shares

Units

CAPS works in LAMMPS real units throughout: lengths in Å, time in fs (time steps) or ps (run lengths, where an option says so), temperature in K, pressure in atm, energy in kcal/mol, density in g/cm³, charge in e. Options name their unit in the usage when it is not one of these.

Files

The format follows the extension, both ways:

A trajectory carries no bonds, so commands that read one take --topology DATA (the data file of the same atoms). -o names the output; a folder for the commands that write several files.

Seeds and threads

Everything random takes --seed (default 1): the same command, input and seed give the same result on the same build. The commands that run in parallel (md, run, pack) take --threads N (default: all cores).

Provenance

The recipe runner and the coarse-graining and DFT commands write FILE.provenance.json beside what they make: the program's version, the inputs' SHA-256, every step with its parameters, seed and the methods it follows. caps provenance FILE --methods turns it into a methods paragraph with numbered references, --bibtex into BibTeX, and --compare OTHER lists what differs between two runs.

Output and exit codes

Commands print a short report and the files they wrote. --json (recipes, coarse-graining and DFT commands) prints the result as JSON for scripts. A command exits 0 on success and non-zero on an error. caps run distinguishes 2 (bad input), 3 (parameters missing from the force field) and 4 (a failed run); caps validate exits 1 when a slab fails a check, so it can stop a batch script.

Which command for what

Each command links to its full entry in the command reference, which is generated from the program itself.

Build structures

Molecules, chains, cells, crystals, surfaces and fillers.

Force fields

Types, charges and parameters; exports for LAMMPS, GROMACS and DL_POLY.

Relax and run

Minimisation, molecular dynamics, equilibration protocols, regrowth, crosslinking and recipes.

Properties

Mechanics, glass transition, elastic constants and interfaces.

Inspect and analyse

Files, structure, trajectories and figures.

Reproducibility

Provenance, bundles and the validation suite.

Coarse-graining

Chemistry-aware mapping, bonded and non-bonded potentials, melts, entanglements, backmapping.

Biomolecular coarse-graining

Secondary structure and Martini proteins.

DFT surfaces

2D sheets, terminations, adsorption complexes and VASP case folders.

Scripts CAPS writes for you to run

Long runs belong on a workstation or a cluster, not inside CAPS. For those, CAPS writes ready-to-run inputs and scripts, each with a comment block at the top saying how to run it and which variables it takes.

Putting commands together

A shell loop over seeds

Independent replicas differ only in the seed; the provenance records it, so caps provenance --compare shows exactly that difference.

for s in 1 2 3; do
  caps grow -o ps_$s.data --chains 4 --dp 10 --density 0.5 --units '*CC(*)c1ccccc1' --seed $s
  caps relax ps_$s.data -o ps_${s}_min.data --quiet
  caps md ps_${s}_min.data -o ps_${s}_md.data --steps 2000 --barostat berendsen --seed $s --quiet
done
caps analyze ps_1_md.data --props density

A recipe instead of a script

When the chain is fixed (build, type, grow, relax, equilibrate, run, analyse, export), write it once as a recipe and run it with caps run. The recipe's hash, every stage's parameters and the seed go into the provenance, so the whole study can be rebuilt; see Tutorial 03.

Pipelines over many trajectories

caps pipeline FILE --steps STEPS.yaml runs a chain of analysis steps (the Studio's pipeline, including Python steps) on one frame; caps run PIPELINE.yaml --input 'runs/*/traj.lammpstrj' --csv results.csv runs it over many inputs and writes one row per input.

Command line, Python or Studio?

All three call the same core, so results agree. Use the command line for batch work, shell scripts and clusters; Python (import caps) when a study needs loops, conditions or your own analysis, or features with no command yet (CAPS React's fix bond/react export, polymer sweeps, χ by MD); the Studio to look at structures, build interactively, and read plots and the methods report. The Studio's Coarse-grain and DFT pages show the equivalent command line for what you set up, ready to copy.