Eregime Generator Engine Utility

ReaxFF electric-field regime (eregime.in) generators.

This module provides deterministic utilities for generating ReaxFF eregime.in files, which define time-dependent external electric field schedules applied during MD simulations.

Usage context

Template generation: Produce canonical text payloads for ReaxFF artifacts.
File writing: Persist generated outputs to disk with stable formatting.
Workflow integration: Support higher-level ReaxKit workflow commands.

Class: `ExplicitERegimeSpec`

Represent ExplicitERegimeSpec.

Public class used by ReaxFF generator components.

Fields

rows : tuple[tuple[int, int, str, float], ...] Ordered explicit schedule rows in (iteration, voltage_idx, direction, magnitude) form used verbatim when writing eregime.in.

Examples:

spec = ExplicitERegimeSpec(
    rows=(
        (0, 1, "z", 0.0),
        (500, 1, "z", 0.25),
        (1000, 1, "z", -0.25),
    )
)

This means you provide every row yourself: at iteration 0 the field is 0.0 V/A, at 500 it is +0.25 V/A, and at 1000 it is -0.25 V/A, all on voltage index 1 and along the z direction.

Class: `SinusoidalERegimeSpec`

Represent SinusoidalERegimeSpec.

Public class used by ReaxFF generator components.

Fields

max_magnitude : float Peak sinusoidal amplitude (V/A) around dc_offset. step_angle : float Angular increment (radians) between consecutive samples. iteration_step : int MD-iteration increment between consecutive output rows. num_cycles : float Number of sinusoidal cycles to generate. direction : str Field axis label ("x", "y", or "z"). voltage_idx : int ReaxFF voltage slot index written to the second eregime.in column. phase : float Initial phase offset in radians applied to the sine argument. dc_offset : float Constant baseline value (V/A) added to the sinusoid. start_iter : int Iteration number for the first generated row.

Examples:

spec = SinusoidalERegimeSpec(
    max_magnitude=0.4,
    step_angle=0.05,
    iteration_step=100,
    num_cycles=2.0,
    direction="z",
    voltage_idx=1,
    phase=0.0,
    dc_offset=0.0,
    start_iter=0,
)

Plain-language meaning of each value: max_magnitude=0.4 means the signal gets as high or as low as about 0.4 V/A around the offset. step_angle=0.05 sets how finely the sine wave is sampled. iteration_step=100 means each sampled point is 100 MD steps apart. num_cycles=2.0 means generate two full sine cycles. direction="z" applies the field along z. voltage_idx=1 writes to voltage column/index 1 in ReaxFF. phase=0.0 starts the sine at zero phase shift. dc_offset=0.0 adds no constant bias. start_iter=0 starts writing rows at MD iteration 0.

Class: `SmoothPulseERegimeSpec`

Represent SmoothPulseERegimeSpec.

Public class used by ReaxFF generator components.

Fields

amplitude : float Pulse height above baseline (V/A) during the positive half-cycle. width : float Duration of the flat pulse plateau within each half-cycle. period : float Full pulse period in the profile time domain. slope : float Rise/fall ramp duration used to smooth pulse edges. iteration_step : int MD-iteration increment between consecutive sampled rows. num_of_cycles : int | float Number of full pulse periods to generate. step_size : float Sampling interval in profile time units. direction : str Field axis label ("x", "y", or "z"). voltage_idx : int ReaxFF voltage slot index written to the second eregime.in column. baseline : float Base field value around which bipolar pulses oscillate. start_iter : int Iteration number for the first generated row.

Examples:

spec = SmoothPulseERegimeSpec(
    amplitude=0.6,
    width=1.0,
    period=6.0,
    slope=0.5,
    iteration_step=50,
    num_of_cycles=3,
    step_size=0.1,
    direction="z",
    voltage_idx=1,
    baseline=0.0,
    start_iter=0,
)

Plain-language meaning of each value: amplitude=0.6 sets the pulse height above baseline. width=1.0 is how long the flat top lasts. period=6.0 is the full positive+negative cycle length. slope=0.5 smooths edges by ramping up/down over 0.5 time units. iteration_step=50 means output points are 50 MD steps apart. num_of_cycles=3 generates three full pulse cycles. step_size=0.1 controls time-resolution of sampling. direction="z" applies the field along z. voltage_idx=1 writes to voltage column/index 1. baseline=0.0 centers pulses around zero field. start_iter=0 starts writing from iteration 0.

Class: `FunctionalERegimeSpec`

Represent FunctionalERegimeSpec.

Public class used by ReaxFF generator components.

Fields

func : Callable[[float], float] Callable mapping sample time to field magnitude (V/A). t_end : float Final sample time (inclusive) in the function time domain. dt : float Sampling interval passed to func. iteration_step : int MD-iteration increment between consecutive sampled rows. direction : str Field axis label ("x", "y", or "z"). voltage_idx : int ReaxFF voltage slot index written to the second eregime.in column. start_iter : int Iteration number for the first generated row.

Examples:

spec = FunctionalERegimeSpec(
    func=lambda t: 0.2 * math.sin(t),
    t_end=10.0,
    dt=0.1,
    iteration_step=20,
    direction="z",
    voltage_idx=1,
    start_iter=0,
)

Plain-language meaning of each value: func is the rule used to compute field magnitude at each sampled time. Here it is a sine with amplitude 0.2 V/A. t_end=10.0 means sample up to time 10.0. dt=0.1 means sample every 0.1 time units. iteration_step=20 maps consecutive samples to rows 20 MD steps apart. direction="z" applies the field along z. voltage_idx=1 writes to voltage column/index 1. start_iter=0 starts row indexing at iteration 0.

Function: `gen_eregime`

Gen eregime.

Parameters:

Name	Type	Description	Default
`out_path`	`str \| Path`	Destination file path for the generated `eregime.in` payload.	`'eregime.in'`
`profile_type`	`str`	Profile selector: `"sin"`, `"pulse"`, or `"func"`.	required
`iteration_step`	`int`	MD-iteration spacing between successive rows in the schedule.	required
`direction`	`str`	Field direction written to the regime file (`"x"`, `"y"`, `"z"`).	`'z'`
`voltage_idx`	`int`	ReaxFF voltage slot index written in column two.	`1`
`start_iter`	`int`	Iteration index assigned to the first row.	`0`
`max_magnitude`	`float \| None`	Sinusoidal amplitude (required when `profile_type="sin"`).	`None`
`step_angle`	`float \| None`	Angular sample spacing in radians (required for `"sin"`).	`None`
`num_cycles`	`float \| None`	Number of cycles for `"sin"`/`"pulse"` profiles.	`None`
`phase`	`float`	Initial phase shift in radians for the sinusoidal profile.	`0.0`
`dc_offset`	`float`	Constant offset added to the sinusoidal profile.	`0.0`
`amplitude`	`float \| None`	Pulse amplitude above baseline (required for `"pulse"`).	`None`
`width`	`float \| None`	Flat-top duration for each pulse (required for `"pulse"`).	`None`
`period`	`float \| None`	Pulse period in profile time units (required for `"pulse"`).	`None`
`slope`	`float \| None`	Ramp duration for pulse rise/fall (required for `"pulse"`).	`None`
`step_size`	`float`	Time increment used to sample pulse profiles.	`0.1`
`baseline`	`float`	Baseline field level for pulse profiles.	`0.0`
`func`	`Callable[[float], float] \| None`	Magnitude function `f(t)` (required when `profile_type="func"`).	`None`
`t_end`	`float \| None`	Final sample time for function-based profiles.	`None`
`dt`	`float \| None`	Sampling interval for function-based profiles.	`None`

Returns:

Type	Description
`Path`	Path to the written `eregime.in` file.

Examples:

# Example
gen_eregime(...)

Eregime Generator Engine Utility

Class: ExplicitERegimeSpec

Class: SinusoidalERegimeSpec

Class: SmoothPulseERegimeSpec

Class: FunctionalERegimeSpec

Function: gen_eregime

Class: `ExplicitERegimeSpec`

Class: `SinusoidalERegimeSpec`

Class: `SmoothPulseERegimeSpec`

Class: `FunctionalERegimeSpec`

Function: `gen_eregime`