API reference

Main module

Core tools for transient grating (TG) analysis.

This module provides the TGAnalysis class to load scan metadata from JSON files, extract TG traces from MATLAB .mat files, fit different model functions, and generate diagnostic plots.

class tg_analysis.TGAnalysis(json_path)

Bases: object

Transient grating analysis pipeline.

Parameters:

json_path (str) – Path to the metadata JSON file. The file must contain a main_path entry with the folder of .mat scans and multiple ScanXXX items.

filter_time(x, y)

Trim arrays before the first detected time-axis reset.

Parameters:

• x (numpy.ndarray) – Time axis.

• y (numpy.ndarray) – TG signal values associated with x.

Returns:

Filtered time and signal arrays up to the first negative time step.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

get_data_E_const(energy_eV)

Select scans at fixed energy and variable intensity.

Parameters:

energy_eV (float) – Target energy in eV.

Returns:

Scan labels, energies, intensities, and per-scan filter flags.

Return type:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

get_data_I_const(intensity_uJ)

Select scans at fixed intensity and variable energy.

Parameters:

intensity_uJ (float) – Target XUV intensity in microjoules.

Returns:

Scan labels, energies, intensities, and per-scan filter flags.

Return type:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

get_data_scan(params_scan)

Load and preprocess TG traces for a scan selection.

Parameters:

params_scan (dict) – Scan-selection configuration. Supported patterns are: {"E": "all", "I": value} or {"E": value, "I": "all"}.

Raises:

ValueError – If both E and I are fixed (or both are "all").

get_fit_parameters(model_idxs, initial_guess_bool=False, bounds=False)

Fit selected model(s) to every loaded scan.

Parameters:

• model_idxs (int or list[int]) – Model index (1, 2, or 3) for all scans, or one index per scan.

• initial_guess_bool (bool, optional) – If True, pass predefined initial guesses to curve_fit.

• bounds (bool, optional) – If True, use predefined lower/upper bounds in the optimization.

Notes

Results are appended scan-wise to params_fit. Optimizer vectors are stored in popts. Reported sigma values in params_fit are in femtoseconds (internally fitted in ps and scaled by 1000).

load_data()

Read metadata JSON and build the scans dataframe.

model1(t, amp1, t0, k_tau, sigma, amp_offset)

Model 1: mono-exponential decay convolved with Gaussian response.

model2(t, amp1, t0, k1, sigma, amp_offset, amp2, k2, t02)

Model 2: two Gaussian-convolved exponential channels plus an offset.

The second decay uses an independent time origin t02 (ps) for the exponential and error-function terms, while the offset still uses t0.

model3(t, amp1, amp2, amp3, t0, k1, k2, k3, sigma, t02, t03)

Model 3: three Gaussian-convolved exponential channels.

Each channel uses its own time zero in ps: t0 for the first decay, t02 for the second, and t03 for the third.

plot_fits(save_path=None, components_bool=False)

Plot data vs fitted curves and relative error per scan.

Parameters:

• save_path (str or None, optional) – If set, save the multi-panel figure to this path.

• components_bool (bool, optional) – If True, overlay analytic fit components (per model) as dashed curves using popts from the last get_fit_parameters run.

plot_params_all_models(models_config, param_name, mode, errors_bool=False, y_limits=None, save_path=None)

Compare one fitted parameter across multiple model configurations.

Parameters:

• models_config (list[dict]) – Each dict must include keys model_idxs, initial_guess_bool, bounds, label_model, and color, passed to get_fit_parameters() in order.

• param_name (str) – Name of the parameter in params_fit (e.g. "tau", "sigma").

• mode ({"constant_E", "constant_I"}) – Same scan-selection mode used with get_data_scan(): constant energy (abscissa = intensity) or constant intensity (abscissa = energy).

• errors_bool (bool, optional) – If True, include error bars for the selected parameter.

• y_limits (tuple[float, float] or None, optional) – Optional y-axis limits.

• save_path (str or None, optional) – If set, save the figure to this path.

plot_params_vs_energy(param_name, errors_bool=False, save_path=None)

Plot a fitted parameter vs scan energy with absorbance references.

plot_params_vs_intensity(param_name, errors_bool=False, save_path=None)

Plot a fitted parameter vs scan intensity.

plot_phase_space(plot_names=False, errors_bool=False, save_path=None)

Plot the phase-space coverage of secure, non-repeated scans.

plot_stacked_signals(limits_time=None, limits_signal=None, ylog_scale=False, plot_ind=None, data_over_fit=False, save_path=None)

Plot stacked TG signals and optionally stacked fits.

Parameters:

• limits_time (tuple[float, float] or None, optional) – Time-axis limits in ps.

• limits_signal (tuple[float, float] or None, optional) – Signal-axis limits.

• ylog_scale (bool, optional) – If True, display y-axis in logarithmic scale.

• plot_ind (list[int] or str or None, optional) – Subset of scan indices to plot, or "all" for every scan.

• data_over_fit (bool, optional) – If True, overlay sampled data in the fit panel.

• save_path (str or None, optional) – If set, save the figure using tight bounding box padding for legends.

Notes

Traces are divided by their peak amplitude so stacked scans are comparable.