API Reference¶

Temperature Programs¶

class ta.temperature_program.TemperatureSegment(rate_C_per_min, T_target_C, hold_min=0.0)[source]¶

One segment of a temperature program.

Parameters:

rate_C_per_min (float) – Heating rate [deg C / min]. Positive = heating, negative = cooling, zero = isothermal hold.
T_target_C (float) – Target temperature [deg C] for ramp segments. For isothermal holds this should equal the current temperature (it is stored for documentation but not used to compute the profile).
hold_min (float) – Duration of an isothermal hold [min]. Only used when rate_C_per_min is zero.

class ta.temperature_program.TemperatureProgram(T_initial_C, segments)[source]¶

Piecewise-linear furnace temperature profile.

The program starts at T_initial_C and executes each segment in order. Ramp segments heat or cool at a constant rate until the target temperature is reached; hold segments keep the temperature constant for a specified duration.

Parameters:

T_initial_C (float) – Starting temperature [deg C].
segments (list[TemperatureSegment]) – Ordered list of program segments.

Examples

Ramp from 50 to 200 at 10 C/min, hold 30 min, ramp to 600 at 5 C/min:

>>> prog = TemperatureProgram(50.0, [
...     TemperatureSegment(10.0, 200.0),
...     TemperatureSegment(0.0, 200.0, hold_min=30.0),
...     TemperatureSegment(5.0, 600.0),
... ])

classmethod single_ramp(T_initial_C, T_final_C, rate_C_per_min)[source]¶

Create a program consisting of a single linear ramp.

This reproduces the legacy TASimulator behaviour.

Parameters:

T_initial_C (float)
T_final_C (float)
rate_C_per_min (float)

Return type:

TemperatureProgram

property T_initial_C: float¶: Starting temperature [deg C].

property T_final_C: float¶: Temperature at the end of the last segment [deg C].

property total_time_s: float¶: Total duration of the program [s].

property segments: list[TemperatureSegment]¶: Copy of the segment list.

property segment_boundaries: list[tuple[float, float]]¶

(time_s, temperature_C) at each segment boundary.

Includes the initial point and the end of every segment, so the length is len(segments) + 1.

T_furnace_K(t)[source]¶

Furnace temperature [K] at time t [s].

Parameters:: t (float)
Return type:: float

T_furnace_C(t)[source]¶

Furnace temperature [deg C] at time t [s].

Parameters:: t (float)
Return type:: float

Simulator¶

class ta.simulator.SimulationResult(time_s, furnace_temperature_C, reactor_temperature_C, reactor_mass, mass_fractions, mole_fractions, wall_heat_flux, density, species_names, condensed_species, sample_mass_mg, bath_gas, bath_gas_flow_sccm, pressure_Pa, temperature_program=None)[source]¶

Container for raw simulation output.

All arrays share the same length (number of recorded time steps).

Parameters:

time_s (ndarray)
furnace_temperature_C (ndarray)
reactor_temperature_C (ndarray)
reactor_mass (ndarray)
mass_fractions (dict[str, ndarray])
mole_fractions (dict[str, ndarray])
wall_heat_flux (ndarray)
density (ndarray)
species_names (list[str])
condensed_species (list[str])
sample_mass_mg (float)
bath_gas (str)
bath_gas_flow_sccm (float)
pressure_Pa (float)
temperature_program (TemperatureProgram | None)

time_s¶

Time in seconds.

Type:: np.ndarray

furnace_temperature_C¶

Prescribed furnace (reservoir) temperature in degree C.

Type:: np.ndarray

reactor_temperature_C¶

Actual sample (reactor) temperature in degree C.

Type:: np.ndarray

reactor_mass¶

Total gas mass inside the reactor [kg] at each step.

Type:: np.ndarray

mass_fractions¶

Per-species mass-fraction history Y_k(t).

Type:: dict[str, np.ndarray]

mole_fractions¶

Per-species mole-fraction history X_k(t).

Type:: dict[str, np.ndarray]

wall_heat_flux¶

Wall heat-transfer rate [W] (positive = into reactor).

Type:: np.ndarray

density¶

Gas density [kg/m^3].

Type:: np.ndarray

species_names¶

All species in the mechanism.

Type:: list[str]

condensed_species¶

Species classified as condensed (tracked for TGA).

Type:: list[str]

sample_mass_mg¶

User-specified initial sample mass [mg].

Type:: float

bath_gas¶

Bath gas species name.

Type:: str

bath_gas_flow_sccm¶

Bath gas volumetric flow rate [standard cm^3/min].

Type:: float

pressure_Pa¶

System pressure [Pa].

Type:: float

temperature_program¶

The temperature program used for this simulation, if available.

Type:: TemperatureProgram or None

class ta.simulator.TASimulator(mechanism='gri30.yaml', sample_composition='CH4:1', sample_mass_mg=10.0, bath_gas='AR', bath_gas_flow_sccm=50.0, T_initial_C=50.0, T_final_C=600.0, heating_rate_C_per_min=5.0, pressure_atm=1.0, condensed_species=None, dt=1.0, wall_area=0.0001, htc=100.0, temperature_program=None)[source]¶

Simulate simultaneous TGA/DTA/DTG/MS using Cantera.

The experiment consists of a sample crucible (ConstPressureReactor) inside a furnace (Reservoir) connected by a Wall with heat-transfer coefficient U and area A. The furnace follows a temperature program (one or more ramp / hold / cooling segments) while the sample heats through the wall, producing thermal lag.

Implementation¶

The furnace profile is realised as a time-dependent wall heat-flux Func1 so that the single ReactorNet.advance() loop handles both chemistry and heat transfer without re-creating the network.

At each recording time-step the simulator:

Advances the ReactorNet to the current time (Cantera solves the coupled energy + species ODEs internally).
Records the reactor state and wall heat-transfer rate.

The energy equation is enabled on the reactor so that the DTA signal (temperature difference driven by endo/exothermic reactions and wall heat transfer) emerges naturally.

param mechanism:: Path to a Cantera YAML mechanism file (or a built-in name such as "gri30.yaml").
type mechanism:: str
param sample_composition:: Initial composition, e.g. "C2H6:1.0" or {"C2H6": 1.0}.
type sample_composition:: str or dict
param sample_mass_mg:: Nominal sample mass [mg] (default 10). Used to set the reactor volume so that the simulated mass matches the physical sample.
type sample_mass_mg:: float
param bath_gas:: Bath-gas species name (default "AR").
type bath_gas:: str
param bath_gas_flow_sccm:: Bath-gas volumetric flow rate at STP [cm^3/min].
type bath_gas_flow_sccm:: float
param T_initial_C:: Starting temperature [deg C] (default 50). Ignored when temperature_program is provided.
type T_initial_C:: float
param T_final_C:: Target temperature [deg C] (default 600). Ignored when temperature_program is provided.
type T_final_C:: float
param heating_rate_C_per_min:: Linear heating rate [deg C / min] (default 5). Ignored when temperature_program is provided.
type heating_rate_C_per_min:: float
param pressure_atm:: System pressure [atm] (default 1).
type pressure_atm:: float
param condensed_species:: Species that remain in the crucible. If None, every species with a non-zero initial mass fraction (excluding the bath gas) is treated as condensed.
type condensed_species:: list[str] or None
param dt:: Recording time-step [s] (default 1).
type dt:: float
param wall_area:: Wall area between furnace and sample [m^2] (default 1e-4).
type wall_area:: float
param htc:: Wall heat-transfer coefficient [W/m^2/K] (default 100).
type htc:: float
param temperature_program:: Multi-segment temperature program. When provided, overrides T_initial_C, T_final_C, and heating_rate_C_per_min.
type temperature_program:: TemperatureProgram or None

run()[source]¶

Execute the thermal-analysis simulation.

Returns:: SimulationResult – Dataclass holding all recorded arrays.
Return type:: SimulationResult

Parameters:

mechanism (str)
sample_composition (str | dict[str, float])
sample_mass_mg (float)
bath_gas (str)
bath_gas_flow_sccm (float)
T_initial_C (float)
T_final_C (float)
heating_rate_C_per_min (float)
pressure_atm (float)
condensed_species (list[str] | None)
dt (float)
wall_area (float)
htc (float)
temperature_program (TemperatureProgram | None)

Signals¶

ta.signals.compute_tga(result, condensed_species=None)[source]¶

Mass remaining as a percentage of the condensed-species mass fraction.

\[\text{TGA}(t) = \left(\sum_{k \in \text{condensed}} Y_k(t)\right) \times 100\]

Parameters:

result (SimulationResult)
condensed_species (list[str] or None) – Override the condensed-species list stored in result.

Returns:

np.ndarray – TGA signal [%].

Return type:

np.ndarray

ta.signals.compute_dtg(tga, time_s)[source]¶

Time derivative of the TGA signal.

Uses numpy.gradient() with time converted to minutes so the result is in %/min.

Parameters:

tga (np.ndarray) – TGA signal [%].
time_s (np.ndarray) – Time array [s].

Returns:

np.ndarray – DTG signal [%/min].

Return type:

ndarray

ta.signals.compute_dta(result, condensed_species=None, sensitivity=1.0)[source]¶

Differential-thermal-analysis signal.

The DTA signal is the wall heat-transfer rate normalised by the current condensed mass:

\[\text{DTA}(t) = \frac{\dot{Q}_\text{wall}(t)} {m_\text{reactor}(t) \cdot \text{TGA}(t)/100} \times S\]

where S is an optional calibration sensitivity factor that converts W/kg to µV/mg (instrument output).

Sign convention: positive DTA = net heat flowing into the reactor (endothermic event or heating lag).

Parameters:

result (SimulationResult)
condensed_species (list[str] or None) – Override the condensed-species list stored in result.
sensitivity (float) – Calibration constant [µV·kg / (W·mg)] (default 1.0, i.e. the output is in W/kg).

Returns:

np.ndarray – DTA signal.

Return type:

np.ndarray

ta.signals.compute_ms(result, target_gases=None, top_n=None)[source]¶

Gas-phase mole fractions as a proxy for MS ion intensity.

Parameters:

result (SimulationResult)
target_gases (list[str] or None) – Explicit list of gas species to return. If None, all non-condensed, non-bath-gas species with any non-zero mole fraction are included.
top_n (int or None) – If set, keep only the top_n species ranked by their peak mole fraction over the simulation.

Returns:

dict[str, np.ndarray] – {species_name: mole_fraction_array}.

Return type:

dict[str, np.ndarray]

Plotting¶

ta.plotter.plot_ta_figure(temperature_C, tga, dtg, dta, ms_dict, *, figsize=(10, 8), dta_label='DTA ($\\mu$V/mg)', tga_label='TGA (mass %)', dtg_label='DTG (%/min)', ms_label='Ion intensity (a.u.)', title='Thermal Analysis')[source]¶

Create a two-panel thermal-analysis figure.

Parameters:

temperature_C (np.ndarray) – Temperature [deg C] (shared X-axis for both panels).
tga (np.ndarray) – Signals computed by ta.signals.
dtg (np.ndarray) – Signals computed by ta.signals.
dta (np.ndarray) – Signals computed by ta.signals.
ms_dict (dict[str, np.ndarray]) – Species name -> mole-fraction array for the MS panel.
figsize (tuple[float, float]) – Figure dimensions in inches.
dta_label (str) – Y-axis labels.
tga_label (str) – Y-axis labels.
dtg_label (str) – Y-axis labels.
ms_label (str) – Y-axis labels.
title (str) – Figure super-title.

Returns:

fig (matplotlib.figure.Figure)
axes (tuple[Axes, Axes, Axes, Axes]) – (ax_dta, ax_tga, ax_dtg, ax_ms)

Return type:

tuple[Figure, tuple[Axes, Axes, Axes, Axes]]