Polarity Workflow
CLI workflow for basal-only three-folded wurtzite polarity.
Command: get-three-folded-wurtzite-polarity
Calculate site polarity from three basal bonds before assigning an apical neighbor.
The three smallest absolute c-axis projections define the basal set and the negative
of their signed mean defines delta. Three basal neighbors are sufficient for a complete polarity
site. An apical candidate is selected afterward only when it lies on the side
required by UP or DOWN polarity. CSV outputs preserve selected and ignored candidates.
Examples
1. Analyze an AlN slab using formal charges and open z boundaries:
reaxkit get-three-folded-wurtzite-polarity --center Al --neighbor N --periodic xy --charge-source formal --formal-charge Al=3 N=-3
2. Plot basal-only delta on an XZ slice:
reaxkit get-three-folded-wurtzite-polarity --gen-plots --plane xz --slice-range 0 3.2 --plot-value delta
Arguments
Scientific choices
| Flag |
Required |
Default |
Help |
Choices |
--center, --cation |
No |
Al |
Choose center species. Example: --center Al Ga, analyzes Al- and Ga-centered sites. |
|
--neighbor, --anion |
No |
N |
Choose neighbor species. Example: --neighbor N, searches nitrogen atoms for basal and apical roles. |
|
--proton |
No |
H |
Choose proton-like species. Example: --proton H, groups sites by nearby hydrogen atoms. |
|
--charge-source |
No |
auto |
Choose dynamic or formal charges. Example: --charge-source formal --formal-charge Al=3 N=-3, calculates charge-weighted values with those charges. |
auto, reaxff, formal |
--formal-charge |
No |
|
Assign species formal charges. Example: --formal-charge Al=3 N=-3 H=1, uses charges in elementary-charge units. |
|
--neighbor-cutoff |
No |
3.0 |
Set the candidate radius in angstrom. Example: --neighbor-cutoff 2.5, excludes neighbors farther than 2.5 angstrom. |
|
--proton-cutoff |
No |
2.0 |
Set the proton-proximity radius in angstrom. Example: --proton-cutoff 1.8, marks sites 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, interprets positive z as UP. |
|
--periodic |
No |
xyz |
Choose periodic directions. Example: --periodic xy, wraps candidates across a and b while leaving the surface normal open. |
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 basal means as zero. |
|
--complete-only |
No |
False |
Exclude sites with fewer than three basal neighbors from polarity.csv. Example: --complete-only, retains all valid three-coordinate surface sites. |
|
--plane |
No |
|
Project plots onto a plane; omission gives 3D. Example: --plane xz, plots x horizontally and z vertically. |
xy, xz, yz |
--slice-range |
No |
|
Limit the coordinate omitted by --plane. Example: --plane xz --slice-range 0 3.2, includes sites with y from 0 to 3.2 angstrom. |
|
| 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 trajectory. Example: --xmolout ./run/xmolout, reads atom names and positions there. |
|
--summary |
No |
|
Select optional simulation metadata. Example: --summary ./run/summary.txt, reads timing and cell metadata there. |
|
Outputs and plots
| Flag |
Required |
Default |
Help |
Choices |
--gen-plots |
No |
False |
Generate one site plot per frame. Example: --gen-plots, writes PNG files under the plots directory. |
|
--plot-value |
No |
polarity |
Choose the plotted site property. Example: --plot-value delta, colors sites by the signed basal-only displacement. |
polarity, eta, delta, basal, basal-difference |
--plot-real-values |
No |
False |
Plot continuous delta values. Example: --plot-real-values, selects the same values as --plot-value delta. |
|
--color-scale |
No |
global |
Choose continuous color normalization. Example: --color-scale frame, rescales colors independently for each frame. |
global, frame |
--view-elevation |
No |
18.0 |
Set 3D camera elevation in degrees. Example: --view-elevation 25, raises the camera above the xy plane. |
|
--view-azimuth |
No |
-60.0 |
Set 3D camera azimuth in degrees. Example: --view-azimuth 45, rotates the view around z. |
|
--marker-size |
No |
12.0 |
Set site-marker area. Example: --marker-size 20, draws larger site markers. |
|
--figure-dpi |
No |
180 |
Set plot resolution. Example: --figure-dpi 300, writes 300-DPI PNG files. |
|
--output-dir |
No |
|
Choose the CSV and plot directory. Example: --output-dir ./three_folded_polarity, writes all analysis artifacts 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 |
|
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.