Polarity Trajectory Workflow
CLI workflow for species-preserving polarity Extended XYZ trajectories.
Command: write-trajectory-with-polarity
Write a species-preserving Extended XYZ trajectory with local polarity properties.
Unlike the original relabeling script, this command keeps every atom name unchanged.
It adds atom_number, charge, polarity, eta_c, delta_eff, is_polarity_site,
has_four_neighbors, and has_proton_within_cutoff columns. Each frame header includes
frame and iter, plus lattice/PBC metadata and an iteration-matched electric field when
requested. ReaxFF charges are streamed through the lightweight charge-only reader.
The canonical trajectory and the neighbor/polarity CSV tables are always written under
reaxkit_workspace. --output optionally creates a second copy at another destination.
Examples
1. Write an AlN polarity trajectory with automatically assigned charges and electric field profile:
reaxkit write-trajectory-with-polarity --include-electric-field --field-direction z --charge-source formal --formal-charge Al=3 N=-3 H=1
Arguments
Scientific choices
| Flag |
Required |
Default |
Help |
Choices |
--center, --cation |
No |
Al |
Choose center species. Example: --center Zn Mg, analyzes both Zn- and Mg-centered sites. |
|
--neighbor, --anion |
No |
N |
Choose neighbor species. Example: --neighbor O, assigns the four nearest oxygen atoms. |
|
--proton |
No |
H |
Choose proton-like species for proximity grouping. Example: --proton H, tests nearby hydrogen atoms. |
|
--charge-source |
No |
auto |
Choose dynamic or formal charges. Formal mode has no implicit species fallback and requires --formal-charge for every center and neighbor. Example: --charge-source formal --formal-charge Al=3 N=-3 H=1. |
auto, reaxff, formal |
--formal-charge |
No |
|
Assign species-specific formal charges. Example: --formal-charge Al=3 N=-3 H=1, uses +3, -3, and +1 elementary charges. |
|
--neighbor-cutoff |
No |
3.0 |
Set the maximum center-neighbor distance in angstrom. Example: --neighbor-cutoff 2.5, excludes candidates farther than 2.5 angstrom. |
|
--proton-cutoff |
No |
2.0 |
Set the proton-proximity radius in angstrom. Example: --proton-cutoff 1.8, marks centers within 1.8 angstrom of H. |
|
--c-axis |
No |
0.0, 0.0, 1.0 |
Set the Cartesian polar-axis direction. Example: --c-axis 0 0 1, projects bonds along z. |
|
--periodic |
No |
xyz |
Choose periodic lattice directions. Example: --periodic xy, wraps neighbors across a and b only. |
none, x, y, z, xy, xz, yz, xyz |
--cell-lengths |
No |
|
Override cell lengths in angstrom. Example: --cell-lengths 10 10 16, uses that cell for every frame. |
|
--cell-angles |
No |
90.0, 90.0, 90.0 |
Set angles for --cell-lengths in degrees. Example: --cell-angles 90 90 120, defines a hexagonal cell. |
|
--frames |
No |
|
Select zero-based source frames. Example: --frames 0:101:10, includes frames 0 through 100 every 10 frames. |
|
--every |
No |
1 |
Stride the selected frames. Example: --every 5, keeps every fifth selected frame. |
|
--polarity-tolerance |
No |
1e-10 |
Set the zero-polarity tolerance in angstrom. Example: --polarity-tolerance 1e-6, treats smaller delta values as zero. |
|
--field-direction |
No |
z |
Choose the field component written to headers. Example: --field-direction z, writes the z component in MV/cm. |
x, y, z |
| Flag |
Required |
Default |
Help |
Choices |
--engine |
No |
|
Select the input adapter. Example: --engine reaxff, bypasses engine auto-detection. |
reaxff, ams, lammps |
--input |
No |
. |
Set the path used for engine detection. Example: --input ./run, inspects ./run. |
|
--run-dir |
No |
. |
Set the fallback simulation directory. Example: --run-dir ./run, resolves default files there. |
|
--fort7 |
No |
fort.7 |
Select the ReaxFF charge file. Example: --fort7 ./run/fort.7, streams charges from that file. |
|
--fort78 |
No |
fort.78 |
Select the applied-field file. Example: --fort78 ./run/fort.78, reads field samples from that file. |
|
--xmolout |
No |
xmolout |
Select the coordinate and atom-name trajectory. Example: --xmolout ./run/xmolout, reads that trajectory. |
|
--summary |
No |
|
Select optional simulation metadata. Example: --summary ./run/summary.txt, reads metadata from that file. |
|
--control |
No |
control |
Select the control file used for frame-count progress. Example: --control ./run/control, reads progress metadata there. |
|
Outputs and plots
| Flag |
Required |
Default |
Help |
Choices |
--include-electric-field |
No |
False |
Add an iteration-matched field to frame headers. Example: --include-electric-field, reads fort.78 and writes field metadata. |
|
--precision |
No |
8 |
Set significant digits for real values. Example: --precision 12, writes coordinates and properties with 12 digits. |
|
--output |
No |
|
Create an additional Extended XYZ copy outside the workspace. Example: --output ./polarity.extxyz, writes both the workspace artifact and that file. |
|
--output-dir |
No |
|
Create an additional trajectory copy in a directory. Example: --output-dir ./results, also writes ./results/trajectory_with_polarity.extxyz. Prefer --output for a custom name. |
|
--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 |
|
Run identifier for run-scoped layout. Example: --run-id run_91ac0e, which reuses that run identifier. |
|
--project-root |
No |
reaxkit_workspace |
Project root that contains inputs/, data/, analysis/, etc. Example: --project-root ./workspace, which stores run artifacts there. |
|
--analysis-id |
No |
|
Optional analysis artifact id; defaults to run id. Example: --analysis-id comparison-a, which names the analysis artifact explicitly. |
|
--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 diagnostic progress information. |
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.