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.

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

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

Note that check_momentum parses velocities in single precision: reported momentum norms below roughly 1e-7 times the scaled sum of m_i |v_i| are parsing noise rather than physical center of mass drift (the legacy equipartition.jl tool parses in double precision and resolves smaller drift).