Skip to content

Dielectric Constant Workflow

CLI workflow for Kubo--Green dielectric response from an Excel time series.

Command: get-dielectric-constant

Calculate static and complex dielectric response from a dipole time series using the Kubo--Green relation.

The Excel sheet must contain one uniformly sampled time column and one scalar dipole column. Volume is calculated from a trajectory with hull (default), bbox, or cell. Hull and bbox exclude empty cell vacuum; cell includes it. The mean frame volume is used in the Kubo--Green prefactor. The dipole mean is removed before the autocorrelation is formed. Use --dipole-kind total for the isotropic 1/3 relation shown in the supplied equation, or component for one signed Cartesian dipole component. A magnitude- only series cannot retain vector orientation, so its dynamic response is an isotropic scalar approximation.

Examples

  1. Dipole moment in Debye sampled every femtosecond:
     reaxkit get-dielectric-constant --input dipole.xlsx --trajectory xmolout --time-unit fs --dipole-unit debye --temperature 300

  2. A z-component series with a 5 ps correlation cutoff:
     reaxkit get-dielectric-constant --input dipole.xlsx --trajectory dump.lammpstrj --engine lammps --volume-method bbox --time-column t --dipole-column mu_z --time-unit ps --dipole-unit e-angstrom --dipole-kind component --temperature 500 --max-lag 5 --output dielectric.xlsx

Arguments

Scientific choices

Flag Required Default Help Choices
--time-column No t Select the time column. Example: --time-column t.
--dipole-column No dipole Select the scalar dipole column. Example: --dipole-column mu_z.
--time-unit Yes Declare the unit of the time column. Example: --time-unit fs. s, ms, us, ns, ps, fs
--dipole-unit Yes Declare the dipole unit (c-m, debye, or e-angstrom). Example: --dipole-unit debye. c-m, debye, e-angstrom
--temperature Yes Set the simulation temperature in kelvin. Example: --temperature 300.
--volume-method No hull Calculate volume from the atomic hull, occupied bounding box, or full cell. Example: --volume-method hull. hull, bbox, cell
--volume No Override trajectory-based volume calculation with a fixed value. Example: --volume 25000.
--volume-unit No angstrom3 Declare the unit of a manual --volume value. Example: --volume-unit angstrom3. m3, cm3, nm3, angstrom3
--dipole-kind No total Choose total for the isotropic factor 1/3 or component for factor 1. Example: --dipole-kind component. total, component
--frequency-unit No thz Choose the reported frequency unit. Example: --frequency-unit cm-1. hz, khz, mhz, ghz, thz, cm-1
--max-lag No Truncate the correlation integral at this lag, in --time-unit. Example: --max-lag 5.
--max-frequency No Keep frequencies at or below this value, in --frequency-unit. Example: --max-frequency 20.

Input and file selection

Flag Required Default Help Choices
--input Yes Read the dipole time series from this Excel workbook. Example: --input ./dipole.xlsx.
--trajectory, --xmolout No Read coordinates used to calculate volume from this trajectory. Example: --trajectory ./run/xmolout.
--engine No Override automatic trajectory-engine detection. Example: --engine lammps. reaxff, ams, lammps
--run-dir No PosixPath('.') Set the simulation directory used for trajectory discovery. Example: --run-dir ./run.

Outputs and plots

Flag Required Default Help Choices
--sheet No 0 Select a worksheet by zero-based index or name. Example: --sheet production.
--output No Write summary, spectrum, and autocorrelation sheets here. Example: --output dielectric.xlsx.
--plot-output No Write the spectrum plot here (default: _spectrum.png). Example: --plot-output dielectric_spectrum.png.
--plot-max-frequency No 1000.0 Set the plot's upper wavenumber in cm-1 (default: 1000). Example: --plot-max-frequency 1500.
--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
--output-profile No standard Artifact profile (default: standard). standard, minimal, 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.