Examples¶

Natural-language acceptance examples¶

cspilot "what is the SMILES string of caffeine?" --workdir runs/caffeine
cspilot "what is the Gibbs free energy of water at ORCA with r2scan-3c" --workdir runs/water
cspilot "Optimize water geometry and compute thermochemistry with ORCA r2scan-3c" --workdir runs/water-thermo

Use a molecule name, SMILES, or XYZ path for new calculations. Without one the agent requests input. New thermochemistry runs optimization and frequencies; it does not report a single-point electronic energy as Gibbs energy.

Display a stored property¶

cspilot run "print Gibbs free energy from runs/water/result.json on screen" \
  --profile analysis --workdir runs/query --max-steps 4

Returned values print in full and remain saved as JSON. Add --html to save an HTML report as well; use --quiet only when result details are unwanted.

Examples assume CSPilot is installed and .env.cspilot is configured for any external programs being used.

Inspect XYZ¶

cspilot inspect tests/examples/input.xyz

LangGraph equivalent:

cspilot graph-run "inspect examples/water.xyz" --workdir runs/water

If examples/water.xyz is not present, use tests/examples/input.xyz.

Molecule Name to XYZ¶

Direct agent:

cspilot agent "Create an XYZ file for water at runs/water_agent/water.xyz" \
  --workdir runs/water_agent --agent-profile chem

Python deterministic call:

python -c "from cspilot.tools.mol_tools import molecule_name_to_xyz; print(molecule_name_to_xyz('water', 'runs/water.xyz'))"

xTB Optimization¶

cspilot xtb-opt tests/examples/input.xyz --charge 0 --uhf 0

ORCA Single Point¶

cspilot orca-sp tests/examples/input.xyz \
  --method r2scan-3c --basis def2-SVP --charge 0 --mult 1

xTB to ORCA¶

cspilot workflow xtb-orca-sp tests/examples/input.xyz \
  --charge 0 --mult 1 --method r2scan-3c --basis def2-SVP

Frequency workflow:

cspilot workflow xtb-orca-freq tests/examples/input.xyz \
  --charge 0 --mult 1 --method r2scan-3c --basis def2-SVP

stk Build and xTB¶

cspilot stk-build-smiles "O" --workdir runs/stk_water

cspilot stk-xtb "O" --workdir runs/stk_xtb

Graph request:

cspilot graph-run "use stk to build water from SMILES O and optimize with xTB" \
  --workdir runs/stk_water

stk to xTB to ORCA¶

cspilot graph-run "use stk to build water from SMILES O then run xTB and ORCA single point" \
  --workdir runs/stk_orca

This is a planned/executed agent workflow path, not a fixed deterministic workflow subcommand.

Result JSON Property Extraction¶

cspilot run "extract Gibbs free energy from the latest result JSON in runs/water" \
  --workdir runs/query --profile analysis

NWPESSe¶

cspilot nwpesse-search "(h2o)4Mg" \
  --workdir runs/h2o4mg --max-calculations 10 --box-size 3.0

Quiet and HTML Reports¶

cspilot graph-run "inspect tests/examples/input.xyz" --workdir runs/water --quiet
cspilot graph-run "inspect tests/examples/input.xyz" --workdir runs/water-html --html