Pyrolysis Module

This subpackage contains tools for modeling pyrolysis behavior and computing kinetic parameters.

Kinetics Module

firescipy.pyrolysis.kinetics.KAS_Ea(temperature, heating_rate, B=1.92, C=1.0008)[source]

Kissinger–Akahira–Sunose method (KAS), with Starink improvement by default. Estimates the activation energy for a given level of conversion \(E_{\alpha}\). This estimation is based on a linear regression based on the isoconversional assumption. By default, the Starink improvement is used, i.e.: B = 1.92, C = 1.0008 (https://doi.org/10.1016/S0040-6031(03)00144-8). The baseline KAS parameters would be: B = 2.0, C = 1.0.

The KAS equation is presented below.

\[\ln\left( \frac{\beta_i}{T_{\alpha,i}^{B}} \right) = \text{Const} - C \left( \frac{E_{\alpha}}{R\, T_{\alpha,i}} \right)\]

Formula 3.10 in: Vyazovkin et al. (2011). ICTAC Kinetics Committee recommendations for performing kinetic computations on thermal analysis data Thermochimica Acta, 520(1–2), 1–19. https://doi.org/10.1016/j.tca.2011.03.034

Parameters
  • temperature (array-like) – Sample temperatures in Kelvin.

  • heating_rate (array-like) – Heating rates in Kelvin per second.

  • B (float) – Exponent for the temperature term. Default is 1.92 (Starink improvement).

  • C (float) – Coefficient for activation energy expression. Default is 1.0008 (Starink improvement).

Returns

A tuple containing:

  • slope (float): Slope of the linear fit.

  • intercept (float): Intercept of the linear fit.

  • Ea_i (float): Apparent activation energy in J/mol.

  • fit_points (tuple): Data points (x, y) used for the linear fit.

Return type

tuple

firescipy.pyrolysis.kinetics.add_constant_heating_rate_tga(database, condition, repetition, raw_data, data_type=None, set_value=None)[source]

Add raw data for a constant heating rate TGA experiment to the database.

This function ensures that the hierarchical structure needed to store constant heating rate TGA data exists in the database. If not, it is created automatically. The provided raw data for a specific experimental condition and repetition is then added to the database.

The database argument is expected to be a nested dictionary following the structure created by initialize_investigation_skeleton().

Parameters
  • database (dict) – The main dictionary where all experimental data is stored.

  • condition (str) – The experimental condition (e.g., “10_Kmin”) under which the constant heating rate TGA data was collected.

  • repetition (str) – Identifier for the specific repetition of the experiment (e.g., “Rep_1”, “Rep_2”).

  • raw_data (pd.DataFrame) – The raw data collected for the specific condition repetition.

  • data_type (str, optional) – Type of data: “differential” or “integral”. Defaults to None. If not provided, existing value in database is kept.

  • set_value (list of [float, str]) – The nominal temperature program, value and unit [float, str] (e.g. [2.5, “K/min”]). Defaults to None.

Returns

Updates the dictionary in place, adding the constant heating rate data under the specified condition.

Return type

None

firescipy.pyrolysis.kinetics.add_isothermal_tga(database, condition, repetition, raw_data, data_type=None, set_value=None)[source]

Add raw data for an isothermal TGA experiment to the database.

This function ensures that the hierarchical structure for storing isothermal TGA experiment data is present in the database. If the structure does not exist, it will be created. Then, the provided raw data for a specific experimental condition and repetition is added to the database.

The database argument is expected to be a nested dictionary following the structure created by initialize_investigation_skeleton().

Parameters
  • database (dict) – The main dictionary where all experimental data is stored.

  • condition (str) – The experimental condition (e.g., “300_C”) under which the isothermal TGA data was collected.

  • repetition (str) – Identifier for the specific repetition of the experiment (e.g., “Rep_1”, “Rep_2”).

  • raw_data (pd.DataFrame) – The raw data collected for the specific condition and repetition.

  • data_type (str, optional) – Type of data: “differential” or “integral”. Defaults to None. If not provided, existing value in database is kept.

  • set_value (list of [float, str]) – The nominal temperature program, value and unit [float, str] (e.g. [300, “°C”]). Defaults to None.

Returns

Updates the database in place, adding the isothermal data under the specified condition and repetition.

Return type

None

firescipy.pyrolysis.kinetics.combine_repetitions(database, condition, temp_program='constant_heating_rate', column_mapping=None)[source]

Combine raw data from multiple repetitions for a specific condition.

This function extracts and combines raw data for a given experimental condition (e.g., “300_C” or “10_Kmin”) under a specified temperature program (e.g., “isothermal” or “constant_heating_rate”).

The column_mapping parameter allows data files with non-standard column headers to be mapped into a unified format expected by downstream functions. For example, compute_conversion() expects columns labeled ‘Time’, ‘Temperature’, and the signal name defined in the investigation skeleton.

Parameters
  • database (dict) – The main data structure storing all experimental data. Should follow the format initialized by initialize_investigation_skeleton().

  • condition (str) – The condition to combine (e.g., “300_C” or “10_Kmin”).

  • temp_program (str) – The temperature program of the experiment (e.g. “isothermal” or “constant_heating_rate”).

  • column_mapping (dict, optional) –

    Mapping from custom column labels to standardised ones. Expected keys: ‘time’, ‘temp’, and ‘signal’. Here, ‘signal’ indicates the recorded quantity, like ‘mass’ in the TGA. Example:

    {
        'time': 'Time (s)',
        'temp': 'Temperature (deg C)',
        'signal': 'Mass (mg)'
    }
    

Returns

Updates the dictionary in place, adding the combined data under the specified condition and temperature program.

Return type

None

firescipy.pyrolysis.kinetics.compute_Ea_KAS(database, data_keys=['experiments', 'TGA', 'constant_heating_rate'], **kwargs)[source]

Wrapper function to easily compute activation energies using the Kissinger–Akahira–Sunose (KAS) method.

This function applies the KAS method to interpolated conversion data (as prepared by compute_conversion_levels()) and estimates the activation energy (\(E_a\)) at each conversion level. It computes linear regression statistics, including RMSE and R², and stores the results in a DataFrame.

The final DataFrame is stored in the database at the specified location defined by data_keys.

This function requires that compute_conversion_levels() has been called beforehand to prepare the input data.

Parameters
  • database (dict) – The main data structure storing all experimental data. Must follow the format initialized by initialize_investigation_skeleton().

  • data_keys (list) – Keys that define the path to the relevant dataset inside the database. For example: [“experiments”, “TGA”, “constant_heating_rate”].

  • **kwargs – Additional arguments passed to KAS_Ea(). For example, to override the default Starink constants (B, C).

Returns

Adds a DataFrame named Ea_results_KAS to the corresponding location in the database. The DataFrame contains:

  • Conversion: Conversion level α

  • Ea: Activation energy in J/mol

  • m_fit: Slope of the linear fit

  • b_fit: Intercept of the linear fit

  • R_squared: Coefficient of determination

  • RMSE: Root mean square error

  • fit_points: Data points used in the linear fit

Return type

None

firescipy.pyrolysis.kinetics.compute_conversion(database, condition='all', setup='constant_heating_rate')[source]

Compute conversion values from experimental or model data for one or more conditions.

This function processes combined experimental data in the given database and adds conversion values (alpha) under each specified condition.

Requires combined data to be present under each condition, typically created using combine_repetitions().

Parameters
  • database (dict) – The main data structure storing all experimental data.

  • condition (str or list, optional) – The specific experimental condition(s) to process. If a string is provided, it can be a single condition (e.g., “300_C”), or “all” to process all conditions. If a list is provided, it should contain multiple condition labels.

  • setup (str, optional) – The experimental setup to process, either “isothermal” or “constant_heating_rate”. Defaults to “constant_heating_rate”.

Returns

Updates the database in place by adding conversion data under each condition.

Return type

None

firescipy.pyrolysis.kinetics.compute_conversion_levels(database, desired_levels=None, setup='constant_heating_rate', condition='all')[source]

Interpolate conversion (alpha) data to desired conversion levels (fractions) for specified experimental conditions.

This function interpolates the conversion values across different conditions to align them with a common set of points. This ensures consistency in follow-up steps such as isoconversional analysis.

Parameters
  • database (dict) – The main data structure storing all experimental data. Must follow the format initialized by initialize_investigation_skeleton().

  • desired_levels (array-like, optional) – Desired conversion levels (fractions) for interpolation. Defaults to np.linspace(0.05, 0.95, 37).

  • setup (str, optional) – The temperature program to process, either “isothermal” or “constant_heating_rate”. Defaults to “constant_heating_rate”.

  • condition (str or list, optional) – The specific experimental condition(s) to process. If a string is provided, it can be a single condition (e.g., “300_C”), or “all” to process all conditions. If a list is provided, it should contain multiple condition names.

Returns

Updates the database in place by adding the interpolated conversion levels under each condition and setup.

Return type

None

firescipy.pyrolysis.kinetics.compute_optimal_shift(initial_guess, temp_x1, temp_x2, data_y1, data_y2, method='Powell')[source]

Find the optimal horizontal shift that aligns two data series by minimizing RMSE.

This function optimizes the x-axis shift applied to temp_x2 so that the interpolated data_y2 best matches data_y1, evaluated over temp_x1. The objective function is root mean square error (RMSE), minimized using scipy.optimize.minimize.

Parameters
  • initial_guess (float) – Initial guess for the x-axis shift.

  • temp_x1 (array-like) – x-values of the alignment target (evaluation grid).

  • temp_x2 (array-like) – x-values of the data series to be shifted.

  • data_y1 (array-like) – y-values corresponding to temp_x1.

  • data_y2 (array-like) – y-values corresponding to temp_x2.

  • method (str, optional) – Optimization method passed to scipy.optimize.minimize. Default is “Powell” for robustness against local minima.

Returns

The optimal shift that minimizes RMSE between the two series.

Return type

float

firescipy.pyrolysis.kinetics.differential_conversion(differential_data, m_0=None, m_f=None)[source]
firescipy.pyrolysis.kinetics.exp_difference(offset, temp_x1, temp_x2, data_y1, data_y2)[source]

Compute the RMSE between two data series after applying a shift to the second x-axis.

The function shifts temp_x2 by a given offset, interpolates the corresponding data_y2 onto the temp_x1 grid using linear interpolation, and computes the root mean square error (RMSE) between data_y1 and the interpolated data_y2.

This is useful for aligning two experimental or simulated curves when a shift in the x-dimension (e.g., time or temperature) is expected.

Linear interpolation is done via scipy.interpolate.interp1d with extrapolation enabled outside the original temp_x2 range.

Parameters
  • offset (float) – Horizontal shift applied to temp_x2 before interpolation.

  • temp_x1 (array-like) – x-values of the alignment target (evaluation grid).

  • temp_x2 (array-like) – x-values of the data series to be shifted.

  • data_y1 (array-like) – y-values corresponding to temp_x1.

  • data_y2 (array-like) – y-values corresponding to temp_x2.

Returns

Root mean square error (RMSE) between data_y1 and the interpolated, shifted version of data_y2.

Return type

float

firescipy.pyrolysis.kinetics.initialize_investigation_skeleton(material, investigator=None, instrument=None, date=None, notes=None, signal=None)[source]

Create a base dictionary representing a new investigation.

This function returns a standardized data structure for documenting experimental investigations (e.g., thermal analysis). Optional metadata like investigator name, instrument, and signal description can be included.

Parameters
  • material (str) – Material being investigated.

  • investigator (str, optional) – Name of the investigator.

  • instrument (str, optional) – Device label (e.g., “TGA” or “TGA/DSC 3+, Mettler Toledo”).

  • date (str, optional) – Date of the investigation.

  • notes (str, optional) – Free-form notes or comments about the investigation.

  • signal (dict, optional) – Dictionary describing the primary measurement signal. For example: {“name”: “Mass”, “unit”: “mg”}. Common alternatives include {“name”: “HeatFlow”} or {“name”: “Enthalpy”}. This field guides downstream analysis and unit handling.

Returns

A dictionary representing the initialized investigation skeleton.

Return type

dict

firescipy.pyrolysis.kinetics.integral_conversion(integral_data, m_0=None, m_f=None)[source]

Calculate the conversion (alpha) from integral experimental data.

This function computes the conversion (alpha) for a series of integral experimental data, such as mass or concentration, based on the formula:

\[\alpha = \frac{m_0 - m_i}{m_0 - m_f}\]
where:

m_0 = initial mass/concentration, m_i = instantaneous mass/concentration, m_f = final mass/concentration.

If m_0 and m_f are not provided, they default to the first and last values of the integral_data series, respectively.

Parameters
  • integral_data (pd.Series or np.ndarray) – Experimental data representing integral quantities (e.g., mass or concentration over time) to calculate the conversion.

  • m_0 (float, optional) – Initial mass/concentration. Defaults to the first value of integral_data.

  • m_f (float, optional) – Final mass/concentration. Defaults to the last value of integral_data.

Returns

Array of alpha values representing the conversion.

Return type

np.ndarray

Modeling Module

firescipy.pyrolysis.modeling.clip_alpha(alpha, clip_values)[source]

Ensure alpha remains within numerical stability range. Specifically, to deal with floating-point errors. They may slightly push numbers outside of the expected range of alpha=[0,1]. This can lead to numerical errors when computations involve logarithms or power laws.

firescipy.pyrolysis.modeling.create_linear_temp_program(start_temp=300, end_temp=700, beta=10.0, beta_unit='K/min', steps=400)[source]

Create a linear temperature-time program for pyrolysis modeling.

The function generates a temperature ramp from start_temp to end_temp at a constant heating rate (beta). The time values are calculated accordingly based on the unit of the heating rate.

Cooling programs (where end_temp < start_temp) are not supported.

Parameters
  • start_temp (float) – Starting temperature in Kelvin. Default is 300 K.

  • end_temp (float) – Ending temperature in Kelvin. Default is 700 K.

  • beta (float) – Heating rate in specified units (float). Default is 10.0.

  • beta_unit (str) – Unit of the heating rate, either “K/min” or “K/s”. Default is “K/min”.

  • steps (int) – Number of steps for the time-temperature array. Default is 400.

Returns

Dictionary containing: - “Time”: array of time values (in seconds) - “Temperature”: array of temperature values (in Kelvin).

Return type

dict

firescipy.pyrolysis.modeling.get_reaction_model(model_name)[source]

Retrieve a reaction model function by name.

This function looks up a callable corresponding to a known reaction model name. The models can be either parameter-free (named_models) or parameterized (f_models), such as nth-order or Avrami-Erofeev models.

Parameters

model_name (str) – Name of the reaction model to retrieve. Must be a key in either named_models or f_models.

Returns

A function f(alpha) or f(alpha, params) that computes the reaction model value for a given conversion alpha.

Return type

callable

Raises

ValueError – If the model name is not found in any registered model dictionaries.

firescipy.pyrolysis.modeling.reaction_rate(t, alpha, t_array, T_array, A, E, R=8.31446261815324, reaction_model='nth_order', model_params=None)[source]

Compute the reaction rate \(\frac{d\alpha}{dt}\) using Arrhenius kinetics and a reaction model.

The reaction rate is computed using the Arrhenius expression for the rate constant \(k(T) = A \exp(-E / RT)\) and a chosen reaction model \(f(\alpha)\). Temperature \(T(t)\) is obtained by interpolating T_array at the current time t.

\[\frac{d\alpha}{dt} = A \exp\left(-\frac{E}{RT(t)}\right) f(\alpha)\]

Formula 1.1 in: Vyazovkin et al. (2011). ICTAC Kinetics Committee recommendations for performing kinetic computations on thermal analysis data Thermochimica Acta, 520(1–2), 1–19. https://doi.org/10.1016/j.tca.2011.03.034

Parameters
  • t (float) – Current time (in seconds).

  • alpha (float) – Current conversion fraction (dimensionless, between 0 and 1).

  • t_array (array-like) – Time points corresponding to the known temperatures.

  • T_array (array-like) – Temperatures (in Kelvin) corresponding to t_array.

  • A (float) – Pre-exponential factor (in 1/s).

  • E (float) – Activation energy (in J/mol).

  • R (float) – Gas constant (in J/mol·K). Default is GAS_CONSTANT.

  • reaction_model (str) – Key identifying the reaction model to use (e.g., ‘nth_order’). Must correspond to a model in the internal f_models dictionary.

  • model_params (dict) – Additional parameters required by the reaction model (e.g., {‘n’: 2.0} for an nth-order reaction).

Returns

The reaction rate \(\frac{d\alpha}{dt}\) at the given time t.

Return type

float

firescipy.pyrolysis.modeling.solve_kinetics(t_array, T_array, A, E, alpha0=1e-12, R=8.31446261815324, reaction_model='nth_order', model_params=None)[source]

Numerically solve the conversion ODE \(\frac{d\alpha}{dt}\) for a given temperature program.

This function solves the reaction kinetics ODE using Arrhenius temperature dependence and a specified reaction model \(f(\alpha)\). The temperature is interpolated over the given t_array, and the solution is returned at the same time points.

The underlying ODE is defined as:

\[\frac{d\alpha}{dt} = A \exp\left(-\frac{E}{RT(t)}\right) f(\alpha)\]
Parameters
  • t_array (array-like) – Time values (in seconds) at which the temperature profile is defined and where the solution will be evaluated.

  • T_array (array-like) – Corresponding temperatures (in Kelvin) at each point in t_array.

  • A (float) – Pre-exponential factor (in 1/s).

  • E (float) – Activation energy (in J/mol).

  • alpha0 (float) – Initial conversion level. Defaults to 1e-12 to avoid numerical issues with reaction models that are undefined at \(\alpha = 0\), such as the nth-order model.

  • R (float) – Gas constant (in J/mol·K). Default is GAS_CONSTANT.

  • reaction_model (str) – Key identifying the reaction model to use (e.g., ‘nth_order’). Must correspond to a model in the internal f_models dictionary.

  • model_params (dict) – Additional parameters required by the reaction model (e.g., {‘n’: 2.0} for an nth-order reaction).

Returns

  • t (ndarray) – Time points (in seconds) at which the solution is evaluated.

  • alpha (ndarray) – Computed conversion values \(\alpha(t)\) at each time point.