Local Polarization Workflow
Command: get-hbn-reference-local-polarization
Calculate cell- and layer-resolved local dipole and polarization.
Each crystallographic cell is one Al2N2 reference cell. Each reference layer is one coplanar AlN pair, so both spatial resolutions are written on every run. --local-grouping selects the table used by plots and the generic local output. Equal volume shares the selected frame volume among groups; deformation uses normalized local affine-deformation weights. With the default hull volume, vacuum is excluded before either assignment.
Examples
reaxkit get-hbn-reference-local-polarization --replication 19 19 10 --periodic xy --charge-source reaxff --volume-method hull --write-extxyz
reaxkit get-hbn-reference-local-polarization --replication 19 19 10 --charge-source formal --formal-charge Al=3 N=-3 --local-volume-method deformation --plot-2d --plot-plane xz --plot-component c
Arguments
Scientific choices
| Flag | Required | Default | Help | Choices |
|---|---|---|---|---|
--reference |
No | PosixPath('/home/runner/work/reaxkit/reaxkit/src/reaxkit/analysis/ferroelectrics/hbn_reference/AlN_hbn.cif') | Select the nonpolar reference CIF. Default: bundled AlN_hbn.cif. | |
--replication |
Yes | Repeat the oriented reference explicitly. Example: --replication 19 19 10 repeats an orthogonalized AlN_hbn cell by those counts. | ||
--charge-source |
No | auto | Choose ReaxFF or formal charges. Example: --charge-source formal --formal-charge Al=3 N=-3, uses the configured species charges; auto uses fort.7 when available. | auto, reaxff, formal |
--formal-charge |
No | ['Al=3.0', 'N=-3.0'] | Assign species formal charges in e. Defaults: Al=3 N=-3; provide values for additional trajectory species. | |
--reference-species |
No | ['B=Al'] | Map substitutions onto reference sites. Default: B=Al. | |
--c-axis |
No | 0.0, 0.0, 1.0 | Set the Cartesian longitudinal direction. Default: 0 0 1. | |
--periodic |
No | xyz | Choose periodic directions used for matching and displacement. | none, x, y, z, xy, xz, yz, xyz |
--cell-lengths |
No | Override trajectory cell lengths in angstrom for every frame. | ||
--cell-angles |
No | 90.0, 90.0, 90.0 | Set angles for --cell-lengths in degrees. | |
--frames |
No | Select zero-based source frames, for example --frames 0:101:10. | ||
--every |
No | 1 | Stride selected frames. | |
--reference-frame |
No | 0 | Choose the frame used to size, assign, and write the reference lattice. | |
--orthogonalize-reference, --no-orthogonalize-reference |
No | Apply ReaxKit's hexagonal-to-orthogonal transform before replication. Use --no-orthogonalize-reference to retain the CIF cell. If omitted, the cell angles select the better representation automatically. | ||
--angle-tolerance |
No | 1.0 | Set the cell-angle comparison tolerance in degrees. | |
--max-reference-strain |
No | 0.15 | Scale a replicated reference axis to the trajectory box only when the relative length change is at most this value. Larger gaps are treated as vacuum. Default: 0.15. | |
--volume-method |
No | hull | Choose the polarization volume: occupied atomic convex hull (default), occupied bounding box, or full simulation cell. | hull, bbox, cell |
--max-alignment-candidates |
No | 8 | Limit periodic origin candidates considered during initial atom assignment. | |
--local-grouping |
No | cell | Use four-atom Al2N2 cells or two-atom AlN layers for plots and the generic local table. Both explicit tables are always written. Default: cell. | cell, layer |
--local-volume-method |
No | equal | Choose equal shares of the selected frame volume (default), or normalized local-deformation weights. | equal, deformation |
--deformation-neighbors |
No | 12 | Set the maximum neighboring reference cells used by local affine fits. Default: 12. | |
--local-charge-treatment |
No | auto | Choose raw atomic charges, per-cell charge neutralization, or auto neutralization only when a cell is charged. Default: auto. | auto, raw, neutralize |
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 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 |
|---|---|---|---|---|
--output-dir |
No | Choose the output directory for CSV and XYZ artifacts. | ||
--write-displacements |
No | False | Write the per-atom displacement table. Disabled by default because the table can be very large. | |
--plot-2d |
No | False | Write per-frame 2D maps after aggregating along the omitted coordinate. | |
--plot-3d |
No | False | Write per-frame 3D cell-center scatter plots. | |
--plot-plane |
No | xy | Choose the displayed plane for --plot-2d. Default: xy. | xy, xz, yz |
--plot-component |
No | c | Choose the dipole or polarization component used as plot color. Default: c. | x, y, z, c |
--plot-quantity |
No | polarization | Plot local polarization (default) or local dipole. | polarization, dipole |
--plot-bins |
No | 40, 40 | Set the two in-plane bin counts for --plot-2d. Default: 40 40. | |
--global-scaling, --no-global-scaling |
No | False | Use shared symmetric color limits across frames. | |
--figure-dpi |
No | 180 | Set PNG resolution. Default: 180. | |
--write-extxyz |
No | False | Write an OVITO-compatible trajectory with local vector properties. | |
--extxyz-precision |
No | 8 | Set significant digits in Extended XYZ output. Default: 8. | |
--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. |
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.