Skip to content

Polarity Workflow

CLI workflow for site-resolved four-fold wurtzite polarity.

Command: get-wurtzite-polarity

Calculate site-resolved polar order for four-fold wurtzite environments.

The command assigns four distance-defined neighbors through the neighbor module, then calculates geometric UP/DOWN polarity, apical and basal bond projections, delta, charge-weighted local dipoles, eta_c, proton-proximity groups, and frame-zero basal changes. Separate CSV files preserve center, neighbor, apical, basal, site, and summary data. Optional plots show the selected property in 3D or as an XY/XZ/YZ projection.

Examples

  1. Analyze AlN using automatically detected ReaxFF charges:
     reaxkit get-wurtzite-polarity --center Al --neighbor N --charge-source formal --formal-charge Al=3 N=-3 H=1

  2. Analyze AlN using formal charges:
     reaxkit get-wurtzite-polarity --center Al --neighbor N --charge-source formal --formal-charge Al=3 N=-3 H=1

  3. Generate an XZ plot of frame-zero basal changes for a Y slice:
     reaxkit get-wurtzite-polarity --gen-plots --plane xz --slice-range 0 3.2 --plot-value basal-difference

  4. Generate 3D eta_c plots with one color scale per frame:
     reaxkit get-wurtzite-polarity --gen-plots --plot-value eta --color-scale frame

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.
--complete-only No False Exclude incomplete sites from polarity.csv. Example: --complete-only, writes only centers with four neighbors.
--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 only 0 <= y <= 3.2 angstrom.

Input and file selection

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.

Outputs and plots

Flag Required Default Help Choices
--gen-plots No False Generate one site plot per frame. Example: --gen-plots, writes plots/ alongside the CSV files.
--plot-value No polarity Choose the plotted site property. Example: --plot-value eta, colors sites by eta_c in e*angstrom. polarity, eta, delta, basal, basal-difference
--plot-real-values No False Plot continuous geometric delta values. Example: --plot-real-values, is equivalent to --plot-value delta.
--color-scale No global Choose continuous color normalization. Example: --color-scale frame, rescales colors independently in every frame. global, frame
--view-elevation No 18.0 Set the 3D camera elevation in degrees. Example: --view-elevation 25, raises the camera above the xy plane.
--view-azimuth No -60.0 Set the 3D camera azimuth in degrees. Example: --view-azimuth 45, rotates the view around z.
--marker-size No 12.0 Set plotted site-marker area. Example: --marker-size 20, draws larger site markers.
--figure-dpi No 180 Set output plot resolution. Example: --figure-dpi 300, writes publication-resolution PNG files.
--output-dir No Choose the CSV and plot output directory. Example: --output-dir ./polarity, writes all 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.