gasfir — public API

All symbols below are importable directly from gasfir:

from gasfir import create_pulse, get_diabatic_ionization_probability, get_parameters

Ionization calculations

gasfir.get_diabatic_ionization_probability(pulse, param_dict, dt=2.0, dT=0.25, filterTreshold=0.0, kernel_type='GASFIR', ret_Rate=False, ret_electron_density=False)[source]

Compute ionization probability for a defined pulse.

Parameters:

pulse (Pulse) – Pulse object defining the pulse
param_dict (Dict[str, float]) – Dictionary containing kernel parameters
dt (float) – Time step for rate calculation (default: 2.0)
dT (float) – Time step for kernel integration (default: 0.25)
filterTreshold (float) – Threshold for filtering rates (default: 0.0)
kernel_type (str) – Type of kernel to use (“GASFIR” or “exact_SFA”)
ret_Rate (bool) – Whether to return rates array (default: False)

Return type:

Union[float, Tuple[float, ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]]

Returns:

If ret_Rate is False, the total ionization probability (float). If ret_Rate is True, a tuple (probability, t_grid, rates).

gasfir.get_diabatic_ionization_rate(t_grid, pulse, param_dict, dT=0.25, kernel_type='GASFIR', ret_tgrid=False)[source]

Compute ionization rates for a defined pulse.

Parameters:

t_grid (ndarray[tuple[Any, ...], dtype[float64]]) – Time grid for ionization moments
pulse (Pulse) – Pulse object defining the laser field
param_dict (Dict[str, float]) – Dictionary containing kernel parameters
dT (float) – Time step for integration (default: 0.25)
kernel_type (str) – Type of kernel to use (“GASFIR” or “exact_SFA”)
ret_tgrid (bool) – Whether to return the time grid (default: False)

Return type:

Union[ndarray[tuple[Any, ...], dtype[float64]], Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]]

Returns:

If ret_tgrid is False, an array of ionization rates at each time point. If ret_tgrid is True, a tuple (time_grid, rates).

Notes

The function handles various input formats for t_grid:

None: Uses laser field’s default time grid
pandas Series: Converts to numpy array
list: Converts to numpy array
numpy array: Used as is

gasfir.get_diabatic_ionization_probability_vec(pulses, param_dict, dt=2.0, dT=0.25, kernel_type='GASFIR', ret_electron_density=False)[source]

Return type:: List[Union[float, Tuple[float, ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]]]

gasfir.get_probability_quasi_static_limit(pulse, param_dict, dt=2.0)[source]

Calculate the quasi-static ionization probability.

Parameters:

pulse (Pulse) – Pulse object defining the laser field
param_dict (Dict[str, float]) – Dictionary containing the parameters
dt (float) – Time step for integration

Return type:

float

Returns:

Ionization probability as a float

gasfir.get_rate_quasi_static_limit(t_grid, pulse, param_dict, type='GASFIR', Z=1, l=0, m=None)[source]

Calculate the quasi-static ionization rate.

Parameters:

t_grid (ndarray[tuple[Any, ...], dtype[float64]]) – Time grid for the calculation
pulse (Pulse) – Pulse object defining the laser field
param_dict (Dict[str, float]) – Dictionary containing the parameters
type – Type of rate to compute (“GASFIR” or “ADK” or “Tong-Lin”) default is “GASFIR”
Z – Charge of the residual ion (default: 1 for neutral atoms, relevant for ADK)
l – Orbital angular momentum quantum number (default: 0, relevant for ADK)
m – Magnetic quantum number (default: None, if None, sums over all m for given l, relevant for ADK)

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

Array of ionization rates at each time point

gasfir.get_quasi_static_rate_for_field(field, param_dict, type='GASFIR', Z=1, l=0, m=None)[source]

return the ionization rate for a define pulse computed with provided parameters :type field: float | ndarray[tuple[Any, ...], dtype[float64]] :param field: the grid of electric field strengths :type field: float64/np.ndarray :type param_dict: Dict[str, float] :param param_dict: dictionary defining the medium’s parameters :type type: :param type: GASFIR or ADK or Tong-Lin (default: GASFIR) :type Z: :param Z: charge of the residual ion (default: 1 for neutral atoms) :type l: :param l: orbital angular momentum quantum number (default: 0) :type m: :param m: magnetic quantum number (default: None, if None, sums over all m for given l)

Returns:: the ionization rates for given array of electric field strengths
Return type:: np.ndarray, shape=(field.size)

gasfir.precompute_pulse_batch(pulse_list, dt_val=4.0, dT_val=0.25)[source]: Strips the raw NumPy arrays out of Python Pulse objects and packs them into Numba-compatible typed Lists for zero-overhead C-level processing.

Pulse creation

gasfir.create_pulse(wavel, intens, cep, fwhmCyc, N=8, t0=0.0)[source]

Create a cos8 pulse with specified parameters.

Parameters:

wavel – Central wavelength in nm
intens – Peak intensity in W/cm^2
cep – Carrier-envelope phase in radians
fwhmCyc – Full-width at half-maximum in optical cycles
N – Envelope parameter for CosNPulse

Returns:

An instance of the CosNPulse class with the specified parameters.

Return type:

Pulse

gasfir.OptCyc_au(fwhmOC, wavel)[source]

Convert a duration in optical cycles to atomic units.

Parameters:

fwhmOC (float) – Duration in optical cycles.
wavel (float) – Central wavelength in nm.

Return type:

float

Returns:

Duration in atomic units of time.

gasfir.ret_pulse_from_pandas_table(data, N=8, pulse_type='CosN', ellip_frac=100)[source]: Create a list of Pulse objects from a pandas dataframe.

Parameters

gasfir.get_parameters(medium_name=None)[source]

Return parameters for a medium, or list all available medium names.

Parameters:: medium_name (Optional[str]) – Case-insensitive name of the medium (e.g. "Hydrogen_SFA"). Pass None to get a list of all available medium names.
Return type:: Union[Dict[str, float], List[str]]
Returns:: A copy of the parameter dict when medium_name is given, or a list of all known medium name strings when medium_name is None.
Raises:: ValueError – If medium_name is not found in the parameter store.

Example

>>> params = get_parameters("Hydrogen_SFA")
>>> names = get_parameters()  # list all available media

gasfir.get_ionization_potential(element)[source]

Return the first ionization potential of an element in atomic units.

Parameters:: element (str) – Element symbol (e.g. "Ar", "He") or full name (e.g. "argon", "helium"). Case-insensitive.
Return type:: Optional[float]
Returns:: Ionization potential in atomic units (Hartree), or None if the element is not recognised.

Example

>>> get_ionization_potential("Ar")   # argon
0.5791...
>>> get_ionization_potential("helium")
0.9035...

Classes

class gasfir.Pulse[source]

Bases: ABC

get_average_initial_KE_energy(Ip)[source]

Calculate initial kinetic energy.

Parameters:: Ip (float) – Ionization potential in atomic units
Return type:: float
Returns:: Initial kinetic energy in atomic units

get_central_wavelength()[source]

Get the central wavelength of the pulse.

Return type:: float
Returns:: Central wavelength in nm

get_cummulative_electric_field_squared(t)[source]

Return type:: float | ndarray[tuple[Any, ...], dtype[float64]]

get_cummulative_vector_potential(t)[source]

Return type:: float | ndarray[tuple[Any, ...], dtype[float64]]

get_cummulative_vector_potential_squared(t)[source]

Return type:: float | ndarray[tuple[Any, ...], dtype[float64]]

get_electric_field(t)[source]

Return type:: float | ndarray[tuple[Any, ...], dtype[float64]]

get_fft(omega=None, center_of_pulse=None)[source]

Get the Fourier transform of the pulse.

Return type:: Union[ndarray[tuple[Any, ...], dtype[float64]], Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]]
Returns:: If omega is None, a tuple (frequencies, amplitudes) in atomic units. If omega is an array, the amplitude at the given frequency(ies) in atomic units.

get_intensity()[source]

Calculate the peak intensity of the pulse.

Return type:: float
Returns:: Peak intensity in W/cm^2

get_keldysh_parameter(Ip)[source]

Calculate the Keldysh parameter γ for this pulse and ionization potential.

The Keldysh parameter separates the tunnel (γ ≪ 1) and multiphoton (γ ≫ 1) ionization regimes:

\[\gamma = \sqrt{\frac{I_p}{2 U_p}} = \frac{\omega_0 \sqrt{2 I_p}}{E_0}\]

where \(U_p = E_0^2 / (4\omega_0^2)\) is the ponderomotive energy.

Parameters:: Ip (float) – Ionization potential in atomic units.
Return type:: float
Returns:: Dimensionless Keldysh parameter. γ < 1 → tunnel ionization regime. γ > 1 → multiphoton ionization regime. γ ≈ 1 → intermediate regime.

Example

>>> laser = create_pulse(800, 1e14, 0, 30)
>>> laser.get_keldysh_parameter(0.5)   # hydrogen, ~0.5 a.u. IP
1.0...

get_max_field_strength()[source]

Get the maximum electric field strength of the pulse.

Return type:: float
Returns:: Maximum electric field strength in atomic units

get_max_initial_KE_energy(Ip)[source]

Calculate maximum initial kinetic energy.

Parameters:: Ip (float) – Ionization potential in atomic units
Return type:: float
Returns:: Maximum initial kinetic energy in atomic units

get_ponderomotive_energy()[source]

Calculate ponderomotive energy.

Return type:: float
Returns:: Ponderomotive energy in atomic units

get_tgrid(dt=0.25)[source]

Get time grid for the pulse.

Parameters:: dt (float) – Time step in atomic units
Return type:: ndarray[tuple[Any, ...], dtype[float64]]
Returns:: Time grid as a numpy array

abstractmethod get_time_interval()[source]

Get time interval containing the pulse.

Return type:: Tuple[float, float]
Returns:: Tuple of (start_time, end_time) in atomic units

get_total_energy(Ip)[source]

Calculate total energy.

Parameters:: Ip (float) – Ionization potential in atomic units
Return type:: float
Returns:: Total energy in atomic units

get_vector_potential(t)[source]

Return type:: float | ndarray[tuple[Any, ...], dtype[float64]]

abstractmethod get_w0()[source]

Get the central wavelength of the pulse.

Return type:: float
Returns:: Central wavelength in nm

get_w_max(center_of_pulse=None)[source]

Get the maximum angular frequency of the pulse.

Returns:: angular frequency in atomic units This corresponds to the maximum photon energy.
Return type:: float

class gasfir.CosNPulse(central_wavelength, peak_intensity, cep, FWHM, envelope_N=8, t0=0.0)[source]

Bases: Pulse

get_time_interval()[source]

Get time interval containing the pulse.

Return type:: Tuple[float, float]
Returns:: Tuple of (start_time, end_time) in atomic units

get_w0()[source]

Get the central wavelength of the pulse.

Return type:: float
Returns:: Central wavelength in nm

class gasfir.DataPulse(t, *, E=None, A=None, t0=0.0)[source]

Bases: Pulse

Pulse constructed from a user-supplied numerical field on a time grid.

Accepts either the electric field E(t) or the vector potential A(t) sampled on a uniform (or non-uniform) time grid in atomic units.

Physical requirement:: A(t) must vanish at both ends of the time window (no net momentum kick). When E(t) is supplied, A is derived by integration A(t) = −∫ E(t') dt'; the integration constant is chosen so that A = 0 at t = t[0], and the field should be essentially zero at both boundaries for this to be accurate.

All four cumulative-integral splines (∫A, ∫A², ∫E²) are precomputed once at construction time from the supplied data grid.

Parameters:

t (ndarray[tuple[Any, ...], dtype[float64]]) – 1-D time array in atomic units, must be strictly increasing.
E (ndarray[tuple[Any, ...], dtype[float64]] | None) – Electric field array E(t) in atomic units. Mutually exclusive with A.
A (ndarray[tuple[Any, ...], dtype[float64]] | None) – Vector potential array A(t) in atomic units. E is derived as E(t) = −dA/dt via the cubic-spline derivative. Mutually exclusive with E.
t0 (float) – Time offset (default 0). get_electric_field(t) evaluates at t − t0.

Raises:

ValueError – If neither or both of E and A are given.

Example — from A(t):

t = np.linspace(-200, 200, 3200)
A = sum_pulse.get_vector_potential(t)
dp = DataPulse(t, A=A)
prob = get_diabatic_ionization_probability(pulse=dp, param_dict=params)

Example — from E(t):

E = sum_pulse.get_electric_field(t)
dp = DataPulse(t, E=E)

get_time_interval()[source]

Get time interval containing the pulse.

Return type:: Tuple[float, float]
Returns:: Tuple of (start_time, end_time) in atomic units

get_w0()[source]

Get the central wavelength of the pulse.

Return type:: float
Returns:: Central wavelength in nm

class gasfir.TIPTOE(pump, probe)[source]

Bases: object

Two-pulse delay scanner for pump–probe TIPTOE spectroscopy.

Generates SumOfPulses objects at arbitrary pump–probe delays and provides a Nyquist-sampled delay grid for scanning experiments.

The pump pulse is held fixed; the probe is shifted in time by the requested delay using a lightweight _DelayedPulse wrapper that adds no computational overhead beyond the underlying pulse’s own caching.

Parameters:

pump (Pulse) – Fixed pump pulse (any Pulse subclass).
probe (Pulse) – Probe pulse to be delayed. The zero-delay configuration corresponds to the probe at its original position (t0).

Example:

from gasfir import create_pulse
from gasfir.pulse import TIPTOE

pump  = create_pulse(800, 3e14, 0, 6)
probe = create_pulse(800, 1e13, 0, 2)   # weak probe

scanner = TIPTOE(pump, probe)

# Scan over the Nyquist-sampled delay grid
delays = scanner.return_delay_array()
for tau in delays:
    field = scanner.at_delay(tau)
    prob  = get_diabatic_ionization_probability(pulse=field, param_dict=params)

at_delay(delay)[source]

Return a SumOfPulses with the probe delayed by delay a.u.

Parameters:: delay (float) – Pump–probe delay in atomic units. Positive values place the probe after the pump; negative values place it before.
Return type:: SumOfPulses
Returns:: SumOfPulses of the fixed pump and the shifted probe.

return_delay_array(delay_min=None, delay_max=None, oversample=4)[source]

Nyquist-sampled delay grid covering the full pump–probe overlap region.

The sampling theorem requires at least 2 delay points per oscillation period of the highest-frequency field component. This method uses the maximum of the pump and probe carrier frequencies to set the step size:

Δτ = T₀ / oversample   where T₀ = 2π / max(ω_pump, ω_probe)

The default range extends 1.5× beyond the point where the two pulses just touch (positive and negative), ensuring both fully-separated and fully-overlapping configurations are included.

Parameters:

delay_min (float | None) – Start of the delay range in atomic units. None (default) sets it to −1.5 × (pump_half_duration + probe_half_duration).
delay_max (float | None) – End of the delay range in atomic units. None (default) mirrors delay_min.
oversample (int) – Number of delay samples per optical cycle of the highest-frequency component (default 4 — 2× Nyquist margin). Use 8 or more for carrier-envelope resolved scans.

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

1-D NumPy array of delay values in atomic units.

Example:

delays = scanner.return_delay_array()          # auto range
delays = scanner.return_delay_array(-500, 500, oversample=8)

class gasfir.EllipticalCosNPulse(central_wavelength, peak_intensity, FWHM, cep, peak_intensity2=0.0, envelope_N=8, t0=0.0)[source]

Bases: CosNPulse

get_cummulative_vector_potential_tuple(t)[source]

get_electric_field_tuple(t)[source]

get_vector_potential_tuple(t)[source]

The gasfir.AtomicUnits unit-conversion helper is documented on the gasfir.utils — unit conversion page.