Polarization Workflow
CLI for vector polarization relative to a hexagonal AlN reference.
Command: get-hbn-reference-polarization
Calculate polarization relative to replicated nonpolar hexagonal AlN.
The command optionally applies ReaxKit's hexagonal-to-orthogonal transform to
AlN_hbn.cif, repeats it by the explicitly supplied replication counts, maps it
into each instantaneous cell, preserves large vacuum gaps, and removes a
periodic rigid translation. It then matches atoms one-to-one and evaluates
mu = -q Delta u and P = e/Omega sum(mu). The output reports x, y, z, and
the selected c-axis projection. Omega is selected with --volume-method; hull
is the default and excludes slab vacuum.
Examples
reaxkit get-hbn-reference-polarization --orthogonalize-reference --replication 19 19 10
reaxkit get-hbn-reference-polarization --replication 4 4 3 --charge-source formal --formal-charge Al=3 N=-3 B=3 --reference-species B=Al
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. |
|
| 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. |
|
--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.