Usage

The main command-line entry point is pyar-cli.

Examples:

pyar-cli -r A.xyz B.xyz -N 8 -gmin 100 -gmax 1000 --software xtb

pyar-cli -a C H -as 1 4 -N 8

pyar-cli --aggregate --formula C5H4 -N 8

The repository README contains additional examples for clustering, aggregation, solvation, and reaction searches.

Energy tables

To print a relative-energy table from raw .xyz files, use:

pyar-energy-table *.xyz

The command prints absolute energies, relative energies in kcal/mol, and the global minimum directly to the terminal.

Reaction trace analysis

To summarize a recorded AFIR trace and optionally generate PNG plots:

pyar-reaction-trace .
pyar-reaction-trace . --plot
pyar-reaction-trace . --plot-only
pyar-cli trace . --plot

The command writes path_summary.csv and candidate_ts/ in the job directory unless --plot-only is used, and places plots in trace_plots/ unless --plot-directory is set.

The summary distinguishes the physical backend energy from the AFIR-biased optimization objective:

  • backend_energy_hartree: backend electronic, ML, or xTB energy without AFIR

  • afir_energy_hartree: artificial AFIR contribution

  • total_energy_hartree: optimization objective used by geomeTRIC

  • backend_relative_kcalmol: backend-energy change relative to the first recorded trace frame

The candidate file candidate_ts/highest_backend_energy.xyz is usually the first structure to inspect for future NEB, string, dimer, or TS workflows. It is not a confirmed transition state.

Utilities

Several smaller helper commands are available for inspection and benchmarking:

pyar-energy-table *.xyz
pyar-clustering *.xyz -a maxmin -n 8
pyar-similarity -f "*.xyz" -t 0.005
pyar-descriptor *.xyz
pyar-trial-generation -N 8 -i seed.xyz monomer.xyz --plot
pyar-optimiser structure.xyz -c 0 -m 1 --software xtb

pyar-energy-table prints relative energies, pyar-clustering selects a diverse subset, pyar-similarity reports near-duplicate structures, pyar-descriptor writes compact cluster descriptors, pyar-trial-generation builds candidate orientations, and pyar-optimiser runs the standalone geometry optimizer.