Getting Started

Installation

Core package (ionization calculations, unit conversions, parameter store, NIST ionization potentials):

pip install gasfir

With fitting, retrieval pipeline, and uncertainty quantification:

pip install gasfir[retrieval]

With all development tools:

pip install gasfir[retrieval,dev,docs]

Using the conda environment shipped with the repository:

conda env create -f environment.yml
conda activate gasfir
pip install -e ".[retrieval,dev,docs]"

Package layout

Module	Requires	Contents
`gasfir`	core	Pulse classes, kernels, parameter store, unit conversions, NIST ionization potentials
`gasfir.fitting`	`[retrieval]`	Residual functions for parameter fitting
`gasfir.retrieval`	`[retrieval]`	Full CMA-ES → LS → emcee pipeline, output generation, post-processing

Basic Workflow

Every GASFIR calculation follows three steps:

Create a laser pulse with gasfir.create_pulse().
Load a parameter dict with gasfir.get_parameters().
Compute the ionization observable.

from gasfir import create_pulse, get_parameters, get_diabatic_ionization_probability

laser  = create_pulse(800, 8.8e13, 0, 6)
params = get_parameters("Hydrogen_SFA")
prob   = get_diabatic_ionization_probability(pulse=laser, param_dict=params)
print(f"P = {prob:.4e}")

Ionization Rate Models

GASFIR provides three ionization models. The GASFIR and exact-SFA models are both reached through gasfir.get_diabatic_ionization_probability() via its kernel_type argument; the quasi-static model has its own function.

GASFIR kernel (recommended for most uses — semi-analytic, accounts for non-adiabatic corrections; kernel_type="GASFIR" is the default):

from gasfir import get_diabatic_ionization_probability

prob = get_diabatic_ionization_probability(pulse=laser, param_dict=params)

Exact SFA (full numerical saddle-point integration) — same function, selected with kernel_type="exact_SFA". The exact SFA kernel is currently implemented for the hydrogen ground state only and should be used with the H_SFA parameters. For hydrogen the GASFIR kernel with H_SFA reproduces the exact SFA result (GASFIR was fit to it), so the two agree:

from gasfir import get_diabatic_ionization_probability, get_parameters

params = get_parameters("H_SFA")          # hydrogen
prob_sfa = get_diabatic_ionization_probability(
    pulse=laser, param_dict=params, kernel_type="exact_SFA"
)

Quasi-static (QS) (adiabatic / tunnelling limit; fastest to evaluate):

from gasfir import get_probability_quasi_static_limit

prob_qs = get_probability_quasi_static_limit(pulse=laser, param_dict=params)

All three return a scalar probability (float). For the time-resolved rate instead of the integrated probability, use gasfir.get_diabatic_ionization_rate() (GASFIR / exact SFA) or gasfir.get_rate_quasi_static_limit() (QS).

Available Parameter Sets

Calling gasfir.get_parameters() with no argument returns a list of all built-in medium names, including their aliases:

import gasfir
gasfir.get_parameters()  # returns a list of all available material names

The full table of built-in parameter sets is shown below. It is auto-generated at docs build time by a conf.py hook that writes docs/_static/parameter_table.txt:

Available GASFIR parameter sets
================================

Pass any of these strings to ``get_parameters('...')``::

    Ar_Hacc5_QS
    Ar_SAE
    CO_Hacc5_QS
    Cs_QS
    Diamond_TBmBJ
    Fr_QS
    H2_Hacc5_QS
    H_QS
    H_SFA
    H_diabatic
    He_Hacc5
    He_Hacc5_QS
    Hydrogen
    Hydrogen_QS
    Hydrogen_SFA
    Hydrogen_diabatic
    K_QS
    N2_Hacc5_QS
    Ne_Hacc4_QS
    Rb_QS
    SiO2_Ulmic
    Si_TBmBJ
    TestGas

Total: 23 parameter sets.

See Parameters for a full description of each set.

NIST Ionization Potentials

First ionization potentials for all 118 elements are built into GASFIR:

from gasfir import get_ionization_potential

get_ionization_potential("Ar")      # 0.5792 a.u. (argon)
get_ionization_potential("helium")  # 0.9036 a.u. (full name works)
get_ionization_potential("Kr")      # 0.5145 a.u.

These values are used automatically when fitting a medium not yet in the parameter store — you only need to provide E_g for crystals.

Batch Processing

Intensity scan — compute ionization probabilities over a range of intensities:

import numpy as np
from gasfir import create_pulse, get_diabatic_ionization_probability, get_parameters

params = get_parameters("H_SFA")
intensities = np.logspace(13, 15, 20)  # W/cm^2
probs = [
    get_diabatic_ionization_probability(
        pulse=create_pulse(800, I, 0, 6), param_dict=params
    )
    for I in intensities
]

Residual computation — evaluate fit residuals over a dataset (useful when implementing custom cost functions):

from gasfir import get_diabatic_ionization_probability
import numpy as np

def compute_residuals(params, data_df):
    """data_df has columns: pulses (Pulse objects), Y (measured probabilities)"""
    predicted = np.array([
        get_diabatic_ionization_probability(pulse=row.pulses, param_dict=params)
        for _, row in data_df.iterrows()
    ])
    return predicted - data_df["Y"].values

Parameter Fitting & Retrieval (`gasfir[retrieval]`)

The three-phase pipeline (CMA-ES → least-squares → emcee) is in gasfir.retrieval:

from gasfir.retrieval import RetrievalConfig, retrieve

# Known medium — parameters and bounds from stored reference
cfg = RetrievalConfig(medium_name="Hydrogen_SFA")
result = retrieve(data_NA=data, config=cfg)

# Atom cold start — E_g from NIST, no other guess needed
cfg = RetrievalConfig(medium_name="Kr", cma_maxiter=5000)

# Crystal cold start — E_g must be supplied
cfg = RetrievalConfig(
    medium_name="MyMaterial",
    initial_params={"E_g": 0.30},
    is_crystal=True,
    ret_electron_density=True,
)

See Parameter Fitting for complete examples.