Z Binned Strain Workflow
CLI workflow for z-binned top/bottom and deformation-gradient strain.
This module maps command-line selections into typed stress/strain requests,
executes registered analyzers through the standard runtime, and hands tabular
or profile-plot output to the presentation layer. Scientific computation stays
in reaxkit.analysis.stress_strain.
Usage context
- Direct commands: Analyze trajectory files from the ReaxKit CLI.
- Output handling: Persist results, export CSV, and render z profiles.
Command: get_z_binned_top_bottom_strain
Compute robust normal strain from top/bottom coordinate spans in z bins.
Each span averages multiple coordinate extrema and is compared with frame zero.
Examples
1. Analyze an xy-periodic slab:
reaxkit get_z_binned_top_bottom_strain --xmolout xmolout --atom-types Al N --z-bins 20 --periodic xy --gen-plots --y-scale global
2. Plot selected frames with larger extreme sets:
reaxkit get_z_binned_top_bottom_strain --z-bins 10 --frames 0:101:10 --top-bottom-count 8 --component strain_xx --plot subplot
Arguments
Scientific choices
| Flag |
Required |
Default |
Help |
Choices |
--atom-types |
No |
Al, N |
Elements included in bin fits. Example: --atom-types Al N, which excludes all other elements. |
|
--z-bins |
Yes |
|
Number of equal-width z bins. Example: --z-bins 20, which creates twenty through-thickness regions. |
|
--bin-range |
No |
reference |
How z-bin edges are defined. Example: --bin-range reference, which fixes edges from frame zero. |
reference, current |
--frames |
No |
|
Frame selector syntax. Example: --frames 0:101:10, which reports frames 0 through 100 every ten frames. |
|
--every |
No |
1 |
Stride over the selected frame list. Example: --every 5, which keeps every fifth selected frame. |
|
--unwrap, --no-unwrap |
No |
True |
Cumulatively unwrap selected periodic axes. Example: --no-unwrap, which analyzes raw wrapped coordinates. |
|
--wrapped |
No |
True |
Standalone-compatible alias for --no-unwrap. |
|
--periodic |
No |
xyz |
Axes treated as periodic during unwrapping. Example: --periodic xy, which leaves slab-normal z unwrapped as-is. |
none, x, y, z, xy, xz, yz, xyz |
--top-bottom-count, --n-extreme-atoms |
No |
5 |
Atoms averaged at each coordinate extreme. Example: --top-bottom-count 8, which averages eight top and eight bottom atoms. |
|
--zero-tolerance |
No |
1e-12 |
Smallest usable frame-zero span. Example: --zero-tolerance 1e-10, which leaves strain blank for smaller baselines. |
|
--component |
No |
strain_zz |
Quantity plotted against z. Example: --component strain_xx, which plots x-normal strain profiles. |
strain_xx, strain_yy, strain_zz, span_change_x, span_change_y, span_change_z |
| Flag |
Required |
Default |
Help |
Choices |
--engine |
No |
|
Engine override. Example: --engine reaxff, which uses ReaxFF trajectory loading. |
reaxff, ams, lammps |
--run-dir, --dir |
No |
. |
Fallback directory for input detection. Example: --run-dir runs/slab, which searches that simulation directory. |
|
--xmolout, --file |
No |
|
Trajectory input path. Example: --xmolout runs/slab/xmolout, which reads that coordinate trajectory. |
|
Outputs and plots
| Flag |
Required |
Default |
Help |
Choices |
--plot |
No |
|
Render z profiles. Example: --plot subplot, which creates one panel per selected frame. |
single, subplot |
--show |
No |
False |
Show the generated plot interactively. Example: --show, which opens a plot window after analysis. |
|
--save |
No |
|
Save the generated plot. Example: --save strain.png, which writes a combined profile figure. |
|
--export |
No |
|
Export the result table to CSV. Example: --export strain.csv, which writes all frame/bin rows. |
|
--grid |
No |
|
Subplot grid dimensions. Example: --grid 2x3, which arranges six frame panels. |
|
--gen-plots |
No |
False |
Generate all four standalone-compatible frame/bin plot directories. |
|
--y-scale |
No |
global |
Batch-plot scaling. Global keeps axes consistent across each complete plot family. |
global, frame |
--plot-every |
No |
1 |
Generate every Nth frame plot; bin-history plots always include every bin. |
|
--dpi |
No |
180 |
Resolution of batch PNG plots. |
|
--output-dir |
No |
|
Batch plot root. Defaults to a method-specific directory beside xmolout. |
|
--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 |
Logging detail. Example: --log verbose, which prints additional runtime progress. |
verbose, quiet |
Fit affine deformation gradients and Green-Lagrange strain in z bins.
Frame-zero atom groups define material regions and fit diagnostics are retained.
Examples
1. Analyze an xy-periodic slab:
reaxkit get_z_binned_deformation_gradient_strain --xmolout xmolout --atom-types Al N --z-bins 20 --periodic xy --gen-plots --y-scale global
2. Plot engineering shear profiles:
reaxkit get_z_binned_deformation_gradient_strain --z-bins 10 --frames 0 20 40 --component gamma_xy --plot single
Arguments
Scientific choices
| Flag |
Required |
Default |
Help |
Choices |
--atom-types |
No |
Al, N |
Elements included in bin fits. Example: --atom-types Al N, which excludes all other elements. |
|
--z-bins |
Yes |
|
Number of equal-width z bins. Example: --z-bins 20, which creates twenty through-thickness regions. |
|
--bin-range |
No |
reference |
How z-bin edges are defined. Example: --bin-range reference, which fixes edges from frame zero. |
reference, current |
--frames |
No |
|
Frame selector syntax. Example: --frames 0:101:10, which reports frames 0 through 100 every ten frames. |
|
--every |
No |
1 |
Stride over the selected frame list. Example: --every 5, which keeps every fifth selected frame. |
|
--unwrap, --no-unwrap |
No |
True |
Cumulatively unwrap selected periodic axes. Example: --no-unwrap, which analyzes raw wrapped coordinates. |
|
--wrapped |
No |
True |
Standalone-compatible alias for --no-unwrap. |
|
--periodic |
No |
xyz |
Axes treated as periodic during unwrapping. Example: --periodic xy, which leaves slab-normal z unwrapped as-is. |
none, x, y, z, xy, xz, yz, xyz |
--minimum-atoms |
No |
4 |
Minimum atoms required for a 3D affine fit. Example: --minimum-atoms 8, which leaves smaller bins undefined. |
|
--max-condition-number |
No |
1000000000000.0 |
Largest accepted reference-fit condition number. Example: --max-condition-number 1e8, which rejects less stable bin geometries. |
|
--component |
No |
strain_zz |
Quantity plotted against z. Example: --component gamma_xy, which plots engineering xy shear. |
strain_xx, strain_yy, strain_zz, strain_xy, strain_xz, strain_yz, gamma_xy, gamma_xz, gamma_yz, principal_E_1, principal_E_2, principal_E_3, J, volumetric_change, fit_rmse |
| Flag |
Required |
Default |
Help |
Choices |
--engine |
No |
|
Engine override. Example: --engine reaxff, which uses ReaxFF trajectory loading. |
reaxff, ams, lammps |
--run-dir, --dir |
No |
. |
Fallback directory for input detection. Example: --run-dir runs/slab, which searches that simulation directory. |
|
--xmolout, --file |
No |
|
Trajectory input path. Example: --xmolout runs/slab/xmolout, which reads that coordinate trajectory. |
|
Outputs and plots
| Flag |
Required |
Default |
Help |
Choices |
--plot |
No |
|
Render z profiles. Example: --plot subplot, which creates one panel per selected frame. |
single, subplot |
--show |
No |
False |
Show the generated plot interactively. Example: --show, which opens a plot window after analysis. |
|
--save |
No |
|
Save the generated plot. Example: --save strain.png, which writes a combined profile figure. |
|
--export |
No |
|
Export the result table to CSV. Example: --export strain.csv, which writes all frame/bin rows. |
|
--grid |
No |
|
Subplot grid dimensions. Example: --grid 2x3, which arranges six frame panels. |
|
--gen-plots |
No |
False |
Generate all four standalone-compatible frame/bin plot directories. |
|
--y-scale |
No |
global |
Batch-plot scaling. Global keeps axes consistent across each complete plot family. |
global, frame |
--plot-every |
No |
1 |
Generate every Nth frame plot; bin-history plots always include every bin. |
|
--dpi |
No |
180 |
Resolution of batch PNG plots. |
|
--output-dir |
No |
|
Batch plot root. Defaults to a method-specific directory beside xmolout. |
|
--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 |
Logging detail. Example: --log verbose, which prints additional runtime progress. |
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.