Trajectory Workflow
Documented CLI workflow for local ReaxFF electrostatics Extended XYZ export.
Command: write-trajectory-with-potential-and-electric-field
Write an Extended XYZ trajectory with internal, external, and total local electrostatic properties.
Use this command when local electrostatic values must remain aligned with atom species,
coordinates, charges, frame indices, and iterations for OVITO or another trajectory tool.
Each frame includes internal, external, and total local values, plus separate internal
and total values for every selected +1e probe species. Applied fields come from fort.78.
The command calculates and exports data; it does not run ReaxFF.
Examples
1. Write every twentieth frame with automatically detected probe species:
reaxkit write-trajectory-with-potential-and-electric-field --run-dir ./run --frames ::20 --periodic xyz
2. Write Al- and N-probe properties to a named trajectory copy:
reaxkit write-trajectory-with-potential-and-electric-field --run-dir ./run --probe-elements Al N --output ./results/local_electrostatics.extxyz
Arguments
Scientific choices
| Flag |
Required |
Default |
Help |
Choices |
--periodic |
No |
xyz |
Choose periodic lattice directions. Example: --periodic xy, includes periodic images along x and y while treating z as nonperiodic. |
none, x, y, z, xy, xz, yz, xyz |
--cell-lengths |
No |
|
Override cell lengths in angstrom. Example: --cell-lengths 30 30 60, uses those lengths for every selected frame. |
|
--cell-angles |
No |
90.0, 90.0, 90.0 |
Set cell angles in degrees for --cell-lengths. Example: --cell-angles 90 90 120, defines a hexagonal cell geometry. |
|
--frames |
No |
|
Select zero-based source frames or slices. Example: --frames ::20, evaluates every twentieth saved frame through the end of the trajectory. |
|
--every |
No |
1 |
Stride the selected frames again after --frames is applied. Example: --every 5, keeps every fifth frame from the current selection. |
|
--probe-elements |
No |
|
Choose the hypothetical +1e probe species that supply gamma_i. Example: --probe-elements Al N, writes Al-probe, N-probe, and equal-average results. |
|
--field-method |
No |
analytic |
Choose how the potential gradient is evaluated. Example: --field-method analytic, uses the exact derivative of the shielded tapered kernel. |
analytic, numerical |
--field-step |
No |
0.001 |
Set the Cartesian displacement in angstrom for numerical gradients. Example: --field-method numerical --field-step 0.0005, uses a centered difference with h=0.0005 angstrom. |
|
--disable-taper |
No |
False |
Disable tapering and cutoff filtering. Example: --disable-taper, uses Tap(r)=1 and every listed atom once with minimum-image periodic displacements. |
|
--potential-reference-mode |
No |
frame-midpoint |
Choose the zero of external potential. Example: --potential-reference-mode fixed-midpoint, reuses the first selected frame's material midpoint as the zero. |
frame-midpoint, fixed-midpoint |
--potential-reference-position |
No |
|
Set a fixed Cartesian potential-reference point in angstrom. Example: --potential-reference-position 0 0 25, uses that point instead of a calculated midpoint. |
|
| Flag |
Required |
Default |
Help |
Choices |
--engine |
No |
reaxff |
Select the simulation-data adapter. Example: --engine reaxff, reads standalone ReaxFF trajectory and charge files. |
reaxff |
--input |
No |
. |
Set the path used for ReaxFF input discovery. Example: --input ./run, discovers simulation files under ./run. |
|
--run-dir |
No |
. |
Set the directory used to resolve relative input filenames. Example: --run-dir ./run, resolves ffield and energylog under ./run. |
|
--fort7 |
No |
fort.7 |
Select the file containing frame-aligned atomic charges. Example: --fort7 ./run/fort.7, reads charges from that file. |
|
--fort78 |
No |
fort.78 |
Select the file containing the iteration-aligned applied electric field. Example: --fort78 ./run/fort.78, adds that external field to the reconstructed internal field. |
|
--xmolout |
No |
xmolout |
Select the coordinate and atom-label trajectory. Example: --xmolout ./run/xmolout, evaluates fields at coordinates in that trajectory. |
|
--summary |
No |
|
Select optional simulation and cell metadata. Example: --summary ./run/summary.txt, reads available iteration and cell information from that file. |
|
--ffield |
No |
ffield |
Select the force field containing taper radii and gammaEEM values. Example: --ffield ./run/ffield, uses electrostatic parameters from that file. |
|
--energylog |
No |
|
Select the partial-energy log used to compare Ecoul values. Example: --energylog ./run/energylog, matches each selected iteration to its logged Ecoul value. |
|
Outputs and plots
| Flag |
Required |
Default |
Help |
Choices |
--precision |
No |
8 |
Set significant digits for coordinates and real-valued properties. Example: --precision 12, writes twelve significant digits to the Extended XYZ file. |
|
--output |
No |
|
Choose an additional Extended XYZ destination. Example: --output ./results/local_field.extxyz, copies the workspace trajectory to that file. |
|
--output-dir |
No |
|
Choose the artifact directory and default trajectory-copy location. Example: --output-dir ./results, writes trajectory_with_local_electrostatics.extxyz and CSV files there. |
|
--detail-format |
No |
|
Optional detail format (default: Parquet; legacy: CSV). |
parquet, csv |
Execution
| Flag |
Required |
Default |
Help |
Choices |
--execution |
No |
auto |
Execution backend; unsupported backends fall back to serial with a logged reason. |
auto, serial, threads, processes |
--workers |
No |
0 |
Frame workers: auto or N (default: auto). |
|
--chunk-size |
No |
0 |
Maximum in-flight frames: auto or N. |
|
Storage and cache
| Flag |
Required |
Default |
Help |
Choices |
--run-id |
No |
|
Select an existing run identifier for workspace organization. Example: --run-id run_91ac0e, stores artifacts under that run identity. |
|
--project-root |
No |
reaxkit_workspace |
Set the ReaxKit workspace root containing data and analysis directories. Example: --project-root ./reaxkit_workspace, writes canonical artifacts under that workspace. |
|
--analysis-id |
No |
|
Set the analysis artifact identifier instead of deriving it from the run. Example: --analysis-id field_profile_01, stores results under that analysis name. |
|
--input-cache, --no-input-cache |
No |
True |
Reuse parsed input frames across commands (default: enabled; use --no-input-cache to force source reads for reproducibility checks or benchmarks). Example: --no-input-cache, which reloads frames from their source files. |
|
--frame-cache-max-gb |
No |
10.0 |
Maximum workspace frame-cache size in GiB (default: 10; use 0 for unlimited). Example: --frame-cache-max-gb 20, which caps cached frames at 20 GiB. |
|
--output-profile |
No |
standard |
Select the shared artifact policy. Standard writes declared default outputs; minimal keeps core tables; full and legacy include optional details. Default: standard. Example: --output-profile full, which includes declared optional detail tables. |
minimal, standard, full, legacy |
Diagnostics and compatibility
| Flag |
Required |
Default |
Help |
Choices |
-h, --help |
No |
|
show this help message and exit |
|
--help-all, --all-flags |
No |
|
Show every option, grouped by purpose. |
|
--log |
No |
quiet |
Choose console logging detail. Example: --log verbose, prints detailed loading and calculation progress. |
verbose, quiet |
Common Runtime and Presentation Arguments
These are shared workflow-level CLI flags added before command-specific options, covering runtime context (engine/input/storage) and output presentation/export behavior.
Each command table above includes its shared and inherited options.