Learn the Python API¶
PQAnalysis exposes the same scientific kernels from Python that the command line uses. There are two layers:
File wrappers such as
rdf()read the same.infiles aspqanalysis rdfand write the same tables.Analysis objects such as
RDFtake a trajectory or reader and return NumPy arrays. Use them when the data are already in memory or when you want to post-process without writing a file.
Analysis objects (RDF, MSD, VACF, Momentum) are single-use:
call run() once, then construct a new object for another calculation.
File wrappers and analysis tables¶
The shortest Python path mirrors the command line. Filenames inside an input
file (traj_files, out_file, …) resolve against the directory of the
input file; export_files resolve against the working directory. With
Example data, from the repository root:
from PQAnalysis.analysis import rdf, read_analysis_table
rdf("examples/water/rdf.in", export_files=["rdf.csv"])
table = read_analysis_table("rdf.csv")
r = table.column("r_i")
g = table.column("g_r_i")
print(table.schema.fields)
print(r[:5], g[:5])
read_analysis_table() accepts native text,
CSV, TSV or XVG and reconstructs the scientific column schema. Field names
such as r_i, g_r_i, lag and normalized_correlation are listed
in Analysis Output Files.
The same pattern works for the other file-driven analyses:
from PQAnalysis.analysis import msd, vacf, vibrations, check_momentum
msd("examples/water/msd.in", export_files=["msd.csv"])
vacf("examples/water/vacf.in", export_files=["vacf.csv"])
vibrations("examples/water/vibrations.in", export_files=["wavenumbers.csv"])
norms = check_momentum(
"examples/water/trajectory.vel",
output="momentum.dat",
selection="all",
)
check_momentum is the exception: it takes trajectory paths directly and
returns the scaled momentum norms as a NumPy array.
Analysis objects¶
When frames are already loaded, construct the analysis class and call
run(). The example below builds a two-frame orthorhombic water-like cell
and computes a short RDF without an input file:
import numpy as np
from PQAnalysis.analysis import RDF
from PQAnalysis.atomic_system import AtomicSystem
from PQAnalysis.core import Atom, Cell
from PQAnalysis.traj import Trajectory
cell = Cell(10.0, 10.0, 10.0)
atoms = [Atom("O"), Atom("H"), Atom("H")]
frames = [
AtomicSystem(
atoms=atoms,
pos=np.array([
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
]),
cell=cell,
),
AtomicSystem(
atoms=atoms,
pos=np.array([
[0.1, 0.0, 0.0],
[1.1, 0.0, 0.0],
[0.0, 1.1, 0.0],
]),
cell=cell,
),
]
r, g, coordination, shell, residual = RDF(
Trajectory(frames),
reference_species="O",
target_species="H",
delta_r=0.1,
r_max=4.0,
).run()
Readers from read_trajectory() and
TrajectoryReader are valid
traj arguments as well. File-backed orthorhombic inputs still take the
legacy-compatible RDF path described on RDF: Theory and Validity.
Reading trajectories¶
from PQAnalysis.io import read_trajectory, TrajectoryReader
traj = read_trajectory("examples/water/trajectory.xyz") # loads all frames
reader = TrajectoryReader("examples/water/trajectory.xyz") # streams frames
Use read_trajectory for small systems and interactive work. Prefer
TrajectoryReader (or the analysis file wrappers) for long trajectories so
frames are not held in memory at once.
Atom strings such as "O", "0..2" and "*|H" are documented in
Atom selections. A continuous session from loading to a figure is on
From trajectory to figure.
Where each method is documented¶
Each method page has a Python recipe next to its CLI input:
Page |
Objects |
|---|---|
|
|
|
|
|
|
|
|
|
The full callable index is Function Index. Generated class pages live under Package Reference.