API

Calculator

Thermochemical properties calculator.

Computes Cp(T), H°(T), S°(T) from NASA polynomial coefficients stored in a SQLite database.

All values returned as floats in standard units:: Cp, S° → J/(mol·K) H° → J/mol

exception pyglenn.calculator.ThermoCalcError[source]

Bases: Exception

Base exception for thermochemical calculation errors.

exception pyglenn.calculator.DatabaseNotConnectedError[source]

Bases: ThermoCalcError

Raised when attempting calculation without a database connection.

exception pyglenn.calculator.SpeciesNotFoundError(species_id)[source]

Bases: ThermoCalcError

Raised when a species ID is not found in the database.

Parameters:: species_id (int)
Return type:: None

exception pyglenn.calculator.TemperatureOutOfRangeError(temperature, species_name=None, temp_bounds=None)[source]

Bases: ThermoCalcError

Raised when the requested temperature is outside valid intervals.

Carries the requested temperature, the species name, and the overall valid temperature bounds (when known).

Parameters:

temperature (float)
species_name (str | None)
temp_bounds (tuple[float, float] | None)

Return type:

None

class pyglenn.calculator.ThermochemicalCalculator(db_file=None)[source]

Bases: object

High-level interface for calculating thermochemical properties.

Uses the bundled thermo.db by default — no manual build step needed.

Supports context-manager protocol for automatic connection management:

with ThermochemicalCalculator() as calc:
    props = calc.calculate_properties(species_id, 1000.0)

Parameters:: db_file (str | None)

property connected: bool: Whether the calculator is connected to the database.

connect()[source]

Connect to the database.

Returns:: True if connection succeeded, False otherwise.
Return type:: bool

close()[source]

Close the database connection.

Return type:: None

get_available_species(search_pattern='', exact_match=False)[source]

Return a list of available species, optionally filtered by name.

Parameters:

search_pattern (str) – Optional substring to filter species names.
exact_match (bool) – If True, use case-insensitive exact match (e.g. 'N2' returns only N2, not Be3N2). Defaults to False (substring search) for backward compatibility.

Returns:

List of SpeciesInfo with id, name, phase, molecular_weight.

Return type:

list[SpeciesInfo]

calculate_properties(species_id, temperature)[source]

Calculate thermochemical properties at a given temperature.

Parameters:

species_id (int) – Database ID of the species.
temperature (float) – Temperature in Kelvin.

Returns:

ThermoProperties with temperature, cp, h_relative, s, temp_interval, species_name, and phase.

Raises:

DatabaseNotConnectedError – If not connected to database.
SpeciesNotFoundError – If species_id is not in the database.
TemperatureOutOfRangeError – If temperature is outside all valid intervals for the species.

Return type:

ThermoProperties

calculate_formation_enthalpy(species_id)[source]

Get enthalpy of formation at 298.15 K in J/mol.

Parameters:: species_id (int) – Database ID of the species.
Returns:: Enthalpy of formation in J/mol, or None if not available.
Return type:: float | None

calculate_enthalpy_change(species_id, T1, T2)[source]

Calculate ΔH°(T₂) − ΔH°(T₁) in J/mol.

Uses absolute H°(T) values (NASA-7 convention).

Parameters:

species_id (int) – Database ID of the species.
T1 (float) – Initial temperature in Kelvin.
T2 (float) – Final temperature in Kelvin.

Returns:

Enthalpy change in J/mol.

Raises:

DatabaseNotConnectedError – If not connected to database.
SpeciesNotFoundError – If species_id is not in the database.
TemperatureOutOfRangeError – If either T1 or T2 is outside valid intervals.

Return type:

float | None

get_properties_range(species_id, temps)[source]

Calculate properties at multiple temperatures.

Parameters:

species_id (int) – Database ID of the species.
temps (list[float]) – List of temperatures in Kelvin.

Returns:

Dict mapping temperature → ThermoProperties, or None if all fail.

Return type:

dict[float, ThermoProperties] | None

calculate_properties_range(species_id, temps, *, strict=False)[source]

Calculate properties for many temperatures, loading data once.

Unlike get_properties_range(), this loads the species intervals a single time and evaluates all temperatures in memory, preserving input order.

Parameters:

species_id (int) – Database ID of the species.
temps (Sequence[float]) – Sequence of temperatures in Kelvin.
strict (bool) – If True, raise on an out-of-range temperature. If False (default), out-of-range values are skipped.

Returns:

Ordered list of ThermoProperties.

Raises:

DatabaseNotConnectedError – If not connected to database.
SpeciesNotFoundError – If species_id is not in the database.
TemperatureOutOfRangeError – If strict and a temperature is outside the valid intervals.

Return type:

list[ThermoProperties]

Exceptions

class pyglenn.ThermoCalcError[source]

Bases: Exception

Base exception for thermochemical calculation errors.

class pyglenn.DatabaseNotConnectedError[source]

Bases: ThermoCalcError

Raised when attempting calculation without a database connection.

class pyglenn.SpeciesNotFoundError(species_id)[source]

Bases: ThermoCalcError

Raised when a species ID is not found in the database.

Parameters:: species_id (int)

class pyglenn.TemperatureOutOfRangeError(temperature, species_name=None, temp_bounds=None)[source]

Bases: ThermoCalcError

Raised when the requested temperature is outside valid intervals.

Carries the requested temperature, the species name, and the overall valid temperature bounds (when known).

Parameters:

temperature (float)
species_name (str | None)
temp_bounds (tuple[float, float] | None)

Database

Database query interface for thermochemical data. Provides SQLite access, species lookup, and NASA polynomial calculations.

class pyglenn.database.ThermoDBQuery(db_file='thermo.db')[source]

Bases: object

Class for querying thermochemical database.

Parameters:: db_file (str)

connect(*, auto_migrate=True)[source]

Connect to database.

Parameters:: auto_migrate (bool) – If True (default), add canonical dataset metadata to legacy databases automatically (see D3).
Returns:: True if connection succeeded, False otherwise.
Return type:: bool

close()[source]

Close connection.

Return type:: None

get_gas_constant_ref()[source]

Return the dataset gas constant, with a safe legacy fallback.

Legacy databases without valid metadata retain the historic universal constant. Database errors are deliberately allowed to propagate instead of being mistaken for a legacy-database condition.

Return type:: float

migrate_metadata()[source]

Add canonical dataset metadata to a connected legacy database.

This explicit, idempotent operation changes only the additive metadata table. It never rebuilds or alters thermochemical rows.

Return type:: None

validate_database()[source]

Run integrity and semantic checks and return a validation report.

Returns:: Dict with valid (bool), errors (list[str]), warnings (list[str]), and counts (dict[str, int]).
Return type:: dict[str, Any]

get_statistics()[source]

Get database statistics.

Returns:: DatabaseStats with totals, phase counts, and average molecular weight.
Return type:: DatabaseStats

find_species(name, exact_match=False)[source]

Find species by name.

Parameters:

name (str) – Search pattern.
exact_match (bool) – If True, use case-insensitive exact match. If False (default), use substring match (LIKE).

Returns:

List of matching SpeciesInfo (max 20).

Return type:

list[SpeciesInfo]

get_species_data(species_id)[source]

Get complete data for a species with all its intervals.

Parameters:: species_id (int) – Database ID of the species.
Returns:: SpeciesData with its intervals tuple, or None if not found.
Return type:: SpeciesData | None

get_species_info(species_id)[source]

Get lightweight species metadata without loading intervals.

Parameters:: species_id (int) – Database ID of the species.
Returns:: SpeciesInfo, or None if the species is not found.
Return type:: SpeciesInfo | None

get_temperature_bounds(species_id)[source]

Return the overall [temp_min, temp_max] covered by a species.

Parameters:: species_id (int) – Database ID of the species.
Returns:: Tuple of (min_temp, max_temp), or None if the species has no intervals.
Return type:: tuple[float, float] | None

get_species_for_temperature(species_id, temperature)[source]

Get the interval and coefficients valid at a specific temperature.

Parameters:

species_id (int) – Database ID of the species.
temperature (float) – Temperature in Kelvin.

Returns:

IntervalData, or None if the temperature is out of range.

Return type:

IntervalData | None

list_species_page(page=1, page_size=20)[source]

List species with pagination.

Parameters:

page (int) – Page number (1-based).
page_size (int) – Number of species per page.

Returns:

Tuple of (species_list, total_pages).

Return type:

tuple[list[SpeciesInfo], int]

list_all_species()[source]

List every species in a single ordered query.

Returns:: List of all SpeciesInfo ordered by name.
Return type:: list[SpeciesInfo]

static calculate_cp(coeffs, temperature)[source]

Calculate Cp(T)/R using NASA-7 polynomial coefficients.

Parameters:

coeffs (NASACoefficients | dict[str, float]) – Dict with keys a1-a7.
temperature (float) – Temperature in Kelvin.

Returns:

Dimensionless Cp/R.

Return type:

float

static calculate_h(coeffs, temperature)[source]

Calculate H°(T)/RT using NASA-7 polynomial coefficients.

Parameters:

coeffs (NASACoefficients | dict[str, float]) – Dict with keys a1-a7, b1.
temperature (float) – Temperature in Kelvin.

Returns:

Dimensionless H/(RT).

Return type:

float

static calculate_s(coeffs, temperature)[source]

Calculate S°(T)/R using NASA-7 polynomial coefficients.

Parameters:

coeffs (NASACoefficients | dict[str, float]) – Dict with keys a1-a7, b2.
temperature (float) – Temperature in Kelvin.

Returns:

Dimensionless S/R.

Return type:

float

Builder

Database builder: converts thermo.inp (NASA FORTRAN format) → SQLite3.

FORTRAN Record Structure (Appendix C):: RECORD 1 – Species identification RECORD 2 – General information RECORD 3 – Temperature interval definition RECORD 4 – First 5 polynomial coefficients RECORD 5 – Last 2 coefficients + integration constants

Records 3–5 repeat for each temperature interval.

class pyglenn.builder.ThermoDBBuilder(inp_file, db_file)[source]

Bases: object

Build a SQLite database from a thermo.inp file.

Parameters:

inp_file (str)
db_file (str)

connect()[source]

Connect to (or create) the SQLite database.

Return type:: None

close()[source]

Close the database connection.

Return type:: None

create_tables()[source]

Create the normalised table structure.

Return type:: None

write_metadata()[source]

Write canonical dataset metadata using idempotent upserts.

The method intentionally does not commit; callers can include metadata writes in the same transaction as a database build.

Return type:: None

static parse_float(value)[source]

Parse a FORTRAN-style float (‘D’ → ‘E’).

Parameters:: value (str) – String possibly in FORTRAN D notation.
Returns:: Float value or None if parsing fails.
Return type:: float | None

static parse_species_record(line)[source]

Extract species name (cols 1-16) and comments (cols 19-80).

Parameters:: line (str) – RECORD 1 line from thermo.inp.
Returns:: Tuple of (species_name, comments).
Return type:: tuple[str, str]

parse_general_info_record(line)[source]

Parse RECORD 2 – general information.

Parameters:: line (str) – RECORD 2 line from thermo.inp.
Returns:: Dict with num_intervals, ref_code, phase, molecular_weight, heat_of_formation.
Return type:: dict[str, Any]

static parse_temp_interval_record(line)[source]

Parse RECORD 3 – temperature interval.

Parameters:: line (str) – RECORD 3 line from thermo.inp.
Returns:: Dict with temp_min, temp_max, h_298_to_0.
Return type:: dict[str, Any]

static parse_coefficients_record(lines)[source]

Parse RECORDS 4-5 – polynomial coefficients.

Parameters:: lines (list[str]) – Two lines containing a1-a7 and b1-b2.
Returns:: Dict with keys a1-a7, b1, b2.
Return type:: dict[str, Any]

read_thermo_file()[source]

Read thermo.inp, stripping comments and blank lines.

Returns:: List of non-empty, non-comment lines.
Return type:: list[str]

static is_temperature_line(line)[source]

Detect RECORD 3 (temperature interval).

A temperature line has two valid floats in cols 0-11 and 11-22 where the first is strictly less than the second.

Parameters:: line (str) – A line from thermo.inp.
Returns:: True if the line appears to be a temperature interval record.
Return type:: bool

static is_coefficient_line(line)[source]

Detect coefficient lines containing FORTRAN D notation.

Uses regex to match the standard FORTRAN double-precision format (e.g. 1.23456789D+01), which is more robust than substring matching.

Parameters:: line (str) – A line from thermo.inp.
Returns:: True if the line contains at least one FORTRAN D-format number.
Return type:: bool

static is_species_header(line)[source]

Return whether a line can be a species-identification record.

A coefficient line can fit entirely inside the fixed-width species-name field. It must therefore be rejected explicitly, rather than relying on whitespace in the apparent name.

Parameters:: line (str)
Return type:: bool

parse_and_load()[source]

Parse the thermo.inp file and populate the database atomically.

A species is inserted only after every declared interval and its two coefficient records have been parsed and validated. Malformed blocks are skipped without leaving partial rows behind.

Return type:: None