User Guide

Command Line Interface

The PQAnalysis package does not only provide an API but also a number of different command line tools. These tools can be categorized into two groups primary groups: pure command line tools and tools that are based on an input file.

Input file based tools

For more details on the grammar and syntax of the input file see Input File. For the columns, units and normalization conventions of analysis output files, see Analysis Output Files.

RDF input files

Basic RDF calculations only need a trajectory, selections, bin settings, and an output file. A restart file is not required for this case:

reference_selection = H
target_selection = O
delta_r = 0.05
out_file = rdf.out
traj_files = trajectory.xyz

For a file-backed periodic orthorhombic trajectory, this minimal form with delta_r alone and the default r_min = 0 uses the legacy-compatible RDF path. Coordinates are parsed directly as float64, while delta_r is represented as float32 as it was by the legacy C input reader. Histogram binning and all five output columns preserve the legacy arithmetic order. Explicit r_max or n_bins values, triclinic cells, vacuum trajectories and intra-molecular exclusion use the general PQAnalysis RDF definition.

Restart files and moldescriptor files are only needed when the calculation requires molecular topology information. For example, no_intra_molecular = True excludes pairs from the same molecule. If the files are not given explicitly, PQAnalysis tries to infer trajectory.rst from trajectory.xyz and moldescriptor.dat from the trajectory directory:

reference_selection = H
target_selection = O
delta_r = 0.05
out_file = rdf_inter.out
traj_files = trajectory.xyz
no_intra_molecular = True

Explicit restart_file and moldescriptor_file values are used as-is. If both files are given and no_intra_molecular is omitted, no_intra_molecular defaults to True. If no_intra_molecular is set to False, intra molecular pairs are included. Inferred and defaulted values are written to the normal PQAnalysis log output.

Vibrational analysis input files

Vibrational analyses use a structure file and a Cartesian Hessian matrix. The Hessian can be generated by a PQ mm-hessian run.

structure_file = structure.rst
hessian_file = hessian.dat
moldescriptor_file = moldescriptor.dat
out_file = wavenumbers.dat
normal_modes_file = normal_modes.dat
modes_prefix = mode
modes_file = modes.xyz
modes = positive
modes_frames = 30
modes_amplitude = 0.25
modes_threshold = 1.0e-6
unit = kcal
hessian_sign = auto

The moldescriptor_file key is optional, but IR intensities require partial charges. unit accepts kcal, hartree and ev. hessian_sign = auto lets PQAnalysis choose the sign convention that gives the larger number of non-negative vibrational modes.

Mode visualization is optional. modes_prefix writes one sinusoidal multi-frame XYZ animation per selected mode, for example mode-6.xyz. modes_file writes one extended XYZ file with mode vectors and metadata, similar to ASE/Jmol vibration output. modes accepts all, nonzero, positive, one mode number, a list of mode numbers or a range. Explicit mode numbers are one-based. modes_frames controls animation frames, modes_amplitude controls fixed-amplitude displacement in Angstrom, and modes_threshold filters named mode selections in cm-1. modes_temperature can be used instead for ASE-style energy-scaled animations.

MSD input files

Mean square displacement analyses compute the multiple-time-origin MSD of a selected atom set with periodic-image unwrapping. If time_step (in ps) is given, the self-diffusion coefficient is obtained from an Einstein-relation fit over the trailing fit_window points and reported in the log output in m²/s:

traj_files = trajectory.xyz
target_selection = O
out_file = msd.dat
window = 1000
gap = 10
time_step = 0.001
fit_window = 200

The output file contains the frame lag and the per-axis MSD in Angstrom squared, matching the format of the legacy Diffcalc tool. window must be divisible by gap.

VACF input files

Velocity autocorrelation analyses read a velocity trajectory (.vel) and compute the normalized VACF; with spectrum_file set, the windowed cosine transform yields a vibrational power spectrum in cm^-1:

traj_files = trajectory.vel
target_selection = all
out_file = vacf.dat
time_step = 0.001
window = 2500
gap = 5
spectrum_file = spectrum.dat
ftsize = 5000
window_function = exponential
window_param = 4.0
window_start = 0.0
window_stop = 1.0

Setting charge_file (static charges) or charge_files (a charge trajectory read in lockstep) switches to the charge-flux autocorrelation q_iv_i, whose spectrum approximates an infrared spectrum. window_function accepts exponential, hann and blackman; method = fft selects a faster dense-origin estimator instead of the legacy-exact sliding-origin one.

Pure command line tools

check_momentum parses file-backed velocity trajectories directly in float64 and preserves the atom-order arithmetic of the legacy equipartition.jl tool. This resolves conserved-momentum residuals at the float64 noise floor instead of the former float32 parsing floor.