Skip to content

Projected Polarity Workflow

CLI for projected h-BN-reference local-cell polarity maps.

Command: get-hbn-reference-projected-polarity

Average h-BN-reference local-cell polarity in fixed spatial bins.

Each neutral reference cell contributes -1, 0, or +1 from the selected local dipole component. Zero dipoles remain in the average. Spatial assignments are made once from --reference-frame and remain fixed as atoms move. --plot-2d writes one TEM-like projection per frame; --plot-kymograph writes the complete frame-versus-position evolution map. Detailed per-group centers are omitted by default; --write-centers writes them as Parquet unless CSV is requested.

Examples

  reaxkit get-hbn-reference-projected-polarity --replication 19 19 10 --periodic xy --charge-source auto --component c --projection-plane xz --projection-bins 1 40 --profile-axis z --plot-2d --plot-kymograph

AMS KF input:
  reaxkit get-hbn-reference-projected-polarity --engine ams --input reaxout.kf --replication 19 19 10 --charge-source auto --frames 0:4000:5 --plot-kymograph

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 Use charges from the selected/detected engine, or use the values provided by --formal-charge. Default: auto. auto, 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 Project four-atom crystallographic cells or two-atom AlN layers. Default: cell. cell, layer
--local-volume-method No equal Set the local-volume convention retained in the cell table. Default: equal. equal, deformation
--deformation-neighbors No 12 Set 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 for charged cells. Default: auto. auto, raw, neutralize
--component No c Choose the local dipole component whose sign defines polarity. Default: c. x, y, z, c
--projection-plane No xz Choose the two coordinates shown in each per-frame map. Default: xz. xy, xz, yz
--projection-bins No 40, 40 Set bin counts along the projection-plane axes. Default: 40 40.
--profile-axis No Choose the projection-plane axis on the kymograph vertical axis. Its --projection-bins count is reused. Default: the second axis. x, y, z
--dipole-zero-tolerance No 0.0 Map local dipole magnitudes at or below this value to polarity 0; zero remains included in bin means. Default: 0.

Input and file selection

Flag Required Default Help Choices
--engine No Select AMS/KF or ReaxFF text input. If omitted, ReaxKit detects the engine from the input path. ams, reaxff
--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.
--write-centers No False Write the optional detailed per-cell/per-layer polarity table.
--centers-format No parquet Choose the detailed centers-table format. Default: parquet. parquet, csv
--plot-2d No False Write one projection-plane mean-polarity heatmap per selected frame.
--plot-kymograph, --plot-evolution No False Write a frame-versus-position polarity heatmap. --plot-evolution is an alias.
--figure-dpi No 180 Set PNG resolution. Default: 180.
--detail-format No Optional detail format (default: Parquet; legacy: CSV). parquet, csv

Execution

Flag Required Default Help Choices
--workers No 0 Override the automatically selected frame-worker count. Use 0 for automatic selection. Default: 0.
--chunk-size No 0 Override the maximum number of in-flight frames. Use 0 for the memory-aware automatic limit. Default: 0.
--execution No auto Execution backend; unsupported backends fall back to serial with a logged reason. auto, serial, threads, processes

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.