Eregime Generator

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.

Generators in this module:

• write fully formatted eregime.in files
• do not parse simulation output
• do not run simulations or perform analysis

write_a_given_eregime(file_path, rows)

Write an eregime.in file from explicit row definitions.

Each row defines the electric-field magnitude and direction applied at a given iteration.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Output path (e.g. "eregime.in").	required
rows	iterable of (iteration, V_index, direction, magnitude)	Electric-field schedule entries, where: - iteration : int Simulation iteration number. - V_index : int Voltage index column expected by ReaxFF. - direction : {"x","y","z"} Field direction. - magnitude : float Field magnitude in V/Å.	required

Returns:

Type	Description
Path	The resolved path of the written eregime.in file.

Examples:

>>> rows = [(0, 1, "z", 0.01), (100, 1, "z", -0.01)]
>>> write_a_given_eregime("eregime.in", rows)
PosixPath('eregime.in')

write_eregime_from_function(file_path, *, func, t_end, dt, iteration_step, direction='z', voltage_idx=1, start_iter=0)

Generate an electric-field regime from an arbitrary function and write eregime.in.

The function func(t) is sampled uniformly in time and mapped to simulation iterations.

Parameters:

Name	Type	Description	Default
func	Callable[[float], float]	Function returning electric-field magnitude (V/Å) at time t.	required
t_end	float	End time for sampling.	required
dt	float	Time step for sampling.	required
iteration_step	int	Iteration increment per sample.	required
direction	('x', 'y', 'z')	Field direction.	"x","y","z"
voltage_idx	int	Voltage index column value.	1
start_iter	int	Starting iteration index.	0

Returns:

Type	Description
Path	The written eregime.in file path.

Examples:

>>> f = lambda t: 0.02 * t
>>> write_eregime_from_function(
...     "eregime.in",
...     func=f,
...     t_end=10.0,
...     dt=0.5,
...     iteration_step=5
... )

write_eregime_sinusoidal(file_path, *, max_magnitude, step_angle, iteration_step, num_cycles, direction='z', voltage_idx=1, phase=0.0, dc_offset=0.0, start_iter=0)

Generate a sinusoidal electric-field schedule and write eregime.in.

The generated field follows: E(t) = dc_offset + max_magnitude · sin(phase + k · step_angle)

sampled at fixed angular increments.

Parameters:

Name	Type	Description	Default
max_magnitude	float	Peak field amplitude in V/Å.	required
step_angle	float	Angular step size in radians.	required
iteration_step	int	Iteration increment between successive samples.	required
num_cycles	float	Total number of sinusoidal cycles.	required
direction	('x', 'y', 'z')	Field direction (default: "z").	"x","y","z"
voltage_idx	int	Voltage index column value (default: 1).	1
phase	float	Phase offset in radians.	0.0
dc_offset	float	Constant offset added to the field (V/Å).	0.0
start_iter	int	Starting iteration index.	0

Returns:

Type	Description
Path	The written eregime.in file path.

Examples:

>>> write_eregime_sinusoidal(
...     "eregime.in",
...     max_magnitude=0.05,
...     step_angle=0.1,
...     iteration_step=10,
...     num_cycles=2
... )

write_eregime_smooth_pulse(file_path, *, amplitude, width, period, slope, iteration_step, num_of_cycles, step_size=0.1, direction='z', voltage_idx=1, baseline=0.0, start_iter=0)

Generate smooth bipolar electric-field pulses and write eregime.in.

Each cycle consists of a positive half-cycle followed by a mirrored negative half-cycle, with linear ramps and flat plateaus.

Parameters:

Name	Type	Description	Default
amplitude	float	Peak field magnitude in V/Å (positive value).	required
width	float	Flat-top duration at peak amplitude.	required
period	float	Full cycle duration.	required
slope	float	Ramp-up and ramp-down duration.	required
iteration_step	int	Iteration increment per sample.	required
num_of_cycles	int | float	Number of cycles to generate.	required
step_size	float	Time resolution for sampling.	0.1
direction	('x', 'y', 'z')	Field direction.	"x","y","z"
voltage_idx	int	Voltage index column value.	1
baseline	float	Baseline field offset in V/Å.	0.0
start_iter	int	Starting iteration index.	0

Returns:

Type	Description
Path	The written eregime.in file path.

Examples:

>>> write_eregime_smooth_pulse(
...     "eregime.in",
...     amplitude=0.1,
...     width=5.0,
...     period=20.0,
...     slope=2.0,
...     iteration_step=10,
...     num_of_cycles=3
... )