`pycanha_core.tmm` — Thermal Model Classes#

The tmm submodule provides the core classes used to build and inspect thermal mathematical models.

Enumerations#

class NodeType(*values)#

Bases: Enum

Thermal node type: DIFFUSIVE or BOUNDARY.

DIFFUSIVE = 68#

BOUNDARY = 66#

class InterpolationMethod(*values)#

Bases: Enum

Method used for interpolating between data points.

LINEAR = 0#

NEAREST_LOWER = 1#

NEAREST_UPPER = 2#

STEP = 3#

class ExtrapolationMethod(*values)#

Bases: Enum

Method used when querying outside the data range.

CONSTANT = 0#

LINEAR = 1#

THROW = 2#

Nodes#

class Node(*args, **kwargs)#

Bases: object

Thermal node representing a lumped thermal element.

A node stores temperature, thermal capacity, heat loads, optical properties, area, and position. It can be standalone or associated with a Nodes container.

property C#: Thermal capacity [J/K].

property T#: Node temperature [K].

__init__#

Overloaded function.

__init__(self, node_num: int) -> None

Create a standalone node with the given user node number.

__init__(self, other: pycanha_core.pycanha_core.tmm.Node) -> None

Copy constructor.

property a#: Node area [m^2].

property aph#: Solar absorptivity [-].

property capacity#: Alias for C (thermal capacity) [J/K].

property eps#: IR emissivity [-].

property fx#: Node X coordinate [m].

property fy#: Node Y coordinate [m].

property fz#: Node Z coordinate [m].

int_node_num#: Return the internal (solver) node index, or -1 if standalone.

property literal_C#: Literal (formula) representation of thermal capacity.

property node_num#: User-assigned node number.

parent_pointer#: Return the parent Nodes container, or None if standalone.

parent_pointer_address#: Memory address of the parent Nodes container.

property qa#: Albedo heat load [W].

property qe#: Earth IR heat load [W].

property qi#: Internal dissipation heat load [W].

property qr#: Other (residual) heat load [W].

property qs#: Solar heat load [W].

property type#: Node type (DIFFUSIVE or BOUNDARY).

class Nodes(*args, **kwargs)#

Bases: object

Collection of thermal nodes.

Stores nodes efficiently using dense vectors for temperature and capacity, and sparse vectors for heat loads and other attributes. Nodes are auto-sorted: diffusive nodes first, then boundary nodes.

__init__#: Create an empty Nodes container.

add_node#: Add a node to the container.

property estimated_number_of_nodes#: Hint for pre-allocating internal storage.

get_C#: Get thermal capacity [J/K] of a node.

get_C_value_pointer#: Memory address of the thermal capacity value for formula binding.

get_T#: Get temperature [K] of a node.

get_T_value_pointer#: Memory address of the temperature value for formula binding.

get_a#: Get area [m^2] of a node.

get_a_value_pointer#: Memory address of the area value for formula binding.

get_aph#: Get solar absorptivity [-] of a node.

get_aph_value_pointer#: Memory address of the solar absorptivity value for formula binding.

get_eps#: Get IR emissivity [-] of a node.

get_eps_value_pointer#: Memory address of the IR emissivity value for formula binding.

get_fx#: Get X coordinate [m] of a node.

get_fx_value_pointer#: Memory address of the X coordinate value for formula binding.

get_fy#: Get Y coordinate [m] of a node.

get_fy_value_pointer#: Memory address of the Y coordinate value for formula binding.

get_fz#: Get Z coordinate [m] of a node.

get_fz_value_pointer#: Memory address of the Z coordinate value for formula binding.

get_idx_from_node_num#: Get internal index from user node number, or None if not found.

get_literal_C#: Get literal (formula) representation of thermal capacity.

get_node_from_idx#: Get a Node object by internal index.

get_node_from_node_num#: Get a Node object by user node number.

get_node_num_from_idx#: Get user node number from internal index, or None if invalid.

get_qa#: Get albedo heat load [W] of a node.

get_qa_value_pointer#: Memory address of the albedo heat load value for formula binding.

get_qe#: Get Earth IR heat load [W] of a node.

get_qe_value_pointer#: Memory address of the Earth IR heat load value for formula binding.

get_qi#: Get internal dissipation heat load [W] of a node.

get_qi_value_pointer#: Memory address of the internal heat load value for formula binding.

get_qr#: Get other (residual) heat load [W] of a node.

get_qr_value_pointer#: Memory address of the residual heat load value for formula binding.

get_qs#: Get solar heat load [W] of a node.

get_qs_value_pointer#: Memory address of the solar heat load value for formula binding.

get_type#: Get the type of a node (DIFFUSIVE or BOUNDARY).

is_mapped#: Check whether the internal node-number map is up to date.

is_node#: Check whether a node with the given number exists.

property num_bound_nodes#: Number of boundary nodes.

property num_diff_nodes#: Number of diffusive nodes.

property num_nodes#: Total number of nodes.

remove_node#: Remove a node by its user node number.

set_C#: Set thermal capacity [J/K] of a node.

set_T#: Set temperature [K] of a node.

set_a#: Set area [m^2] of a node.

set_aph#: Set solar absorptivity [-] of a node.

set_eps#: Set IR emissivity [-] of a node.

set_fx#: Set X coordinate [m] of a node.

set_fy#: Set Y coordinate [m] of a node.

set_fz#: Set Z coordinate [m] of a node.

set_literal_C#: Set literal (formula) representation of thermal capacity.

set_qa#: Set albedo heat load [W] of a node.

set_qe#: Set Earth IR heat load [W] of a node.

set_qi#: Set internal dissipation heat load [W] of a node.

set_qr#: Set other (residual) heat load [W] of a node.

set_qs#: Set solar heat load [W] of a node.

set_type#: Set the type of a node (DIFFUSIVE or BOUNDARY).

Couplings#

class Coupling(*args, **kwargs)#

Bases: object

Thermal coupling (conductance) between two nodes.

__init__#: Create a coupling between two nodes with a conductance value.

property node_1#: First node number.

property node_2#: Second node number.

property value#: Conductance value [W/K] or radiative exchange factor [m^2].

class CouplingMatrices(*args, **kwargs)#

Bases: object

Sparse coupling matrices (dd, db, bb blocks).

Stores conductance values in three sparse matrices: diffusive-diffusive, diffusive-boundary, and boundary-boundary. Indexed by internal node indices.

__init__#: Create empty coupling matrices.

add_new_coupling_from_node_idxs#: Add a coupling only if it does not already exist.

add_ovw_coupling_from_node_idxs#: Add or overwrite a coupling value by internal indices.

add_ovw_coupling_from_node_idxs_verbose#: Add or overwrite a coupling value by internal indices (verbose).

add_sum_coupling_from_node_idxs#: Add a coupling value, summing with any existing value.

add_sum_coupling_from_node_idxs_verbose#: Add a coupling value, summing with any existing value (verbose).

coupling_exists_from_idxs#: Check whether a coupling exists between two internal indices.

get_conductor_value_address_from_idx#: Memory address (as int) of the conductance value.

get_conductor_value_from_idx#: Get conductance value by internal indices.

get_conductor_value_pointer_from_idx#: Memory address of the conductance value for formula binding.

get_idxs_and_coupling_value_from_coupling_idx#: Get (idx1, idx2, value) tuple from a flat coupling index.

property num_bound_bound_couplings#: Number of non-zero boundary-boundary couplings.

property num_bound_nodes#: Number of boundary nodes in the matrices.

property num_diff_bound_couplings#: Number of non-zero diffusive-boundary couplings.

property num_diff_diff_couplings#: Number of non-zero diffusive-diffusive couplings.

property num_diff_nodes#: Number of diffusive nodes in the matrices.

property num_nodes#: Total number of nodes in the matrices.

property num_total_couplings#: Total number of non-zero couplings.

print_sparse#: Print the sparse matrices to the logger (debug).

reserve#: Pre-allocate space for the given number of non-zeros.

set_conductor_value_from_idx#: Set conductance value by internal indices.

sparse_bb_copy#: Return a copy of the boundary-boundary coupling matrix.

sparse_db_copy#: Return a copy of the diffusive-boundary coupling matrix.

sparse_dd_copy#: Return a copy of the diffusive-diffusive coupling matrix.

class Couplings(*args, **kwargs)#

Bases: object

Generic coupling manager using user node numbers.

Wraps CouplingMatrices and translates between user node numbers and internal indices. Supports multiple add strategies: overwrite, sum, new-only.

__init__#: Create a Couplings manager linked to a Nodes container.

add_coupling#

Overloaded function.

add_coupling(self, node_num_1: int, node_num_2: int, value: float) -> None

Add a coupling between two nodes.

add_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a coupling from a Coupling object.

add_new_coupling#

Overloaded function.

add_new_coupling(self, node_num_1: int, node_num_2: int, value: float) -> None

Add a coupling only if it does not already exist.

add_new_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a coupling from a Coupling object only if new.

add_ovw_coupling#

Overloaded function.

add_ovw_coupling(self, node_num_1: int, node_num_2: int, value: float) -> None

Add or overwrite a coupling between two nodes.

add_ovw_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add or overwrite a coupling from a Coupling object.

add_ovw_coupling_verbose#

Overloaded function.

add_ovw_coupling_verbose(self, node_num_1: int, node_num_2: int, value: float) -> None

Add or overwrite a coupling (verbose logging).

add_ovw_coupling_verbose(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add or overwrite a coupling from a Coupling object (verbose).

add_sum_coupling#

Overloaded function.

add_sum_coupling(self, node_num_1: int, node_num_2: int, value: float) -> None

Add a coupling, summing with any existing value.

add_sum_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a coupling from a Coupling object, summing with existing.

add_sum_coupling_verbose#

Overloaded function.

add_sum_coupling_verbose(self, node_num_1: int, node_num_2: int, value: float) -> None

Add a coupling, summing with existing (verbose logging).

add_sum_coupling_verbose(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a coupling from a Coupling object, summing (verbose).

coupling_exists#: Check whether a coupling exists between two nodes.

get_coupling_from_coupling_idx#: Get a Coupling object from a flat coupling index.

get_coupling_matrices#: Return a reference to the underlying CouplingMatrices.

get_coupling_value#: Get the conductance value between two nodes.

get_coupling_value_address#: Memory address (as int) of the coupling value.

get_coupling_value_pointer#: Memory address of the coupling value for formula binding.

set_coupling_value#: Set the conductance value between two nodes.

class ConductiveCouplings(*args, **kwargs)#

Bases: object

Container for conductive (linear) couplings GL.

Heat flow: Q = GL * (T1 - T2).

__init__#: Create conductive couplings linked to a Nodes container.

add_coupling#

Overloaded function.

add_coupling(self, node_num_1: int, node_num_2: int, value: float) -> None

Add a conductive coupling [W/K] between two nodes.

add_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a conductive coupling from a Coupling object.

get_coupling_value#: Get the conductive coupling value [W/K] between two nodes.

set_coupling_value#: Set the conductive coupling value [W/K] between two nodes.

class RadiativeCouplings(*args, **kwargs)#

Bases: object

Container for radiative (T^4) couplings GR.

Heat flow: Q = GR * sigma * (T1^4 - T2^4).

__init__#: Create radiative couplings linked to a Nodes container.

add_coupling#

Overloaded function.

add_coupling(self, node_num_1: int, node_num_2: int, value: float) -> None

Add a radiative coupling [m^2] between two nodes.

add_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a radiative coupling from a Coupling object.

get_coupling_value#: Get the radiative coupling value [m^2] between two nodes.

set_coupling_value#: Set the radiative coupling value [m^2] between two nodes.

Thermal data#

class LookupTable1D(*args, **kwargs)#

Bases: object

1-D lookup table with configurable interpolation and extrapolation. Maps scalar x -> scalar y.

__init__#

Overloaded function.

__init__(self) -> None

Create an empty lookup table.

__init__(self, x: numpy.ndarray[dtype=float64, shape=(*), order='C'], y: numpy.ndarray[dtype=float64, shape=(*), order='C'], interpolation: pycanha_core.pycanha_core.tmm.InterpolationMethod = InterpolationMethod.LINEAR, extrapolation: pycanha_core.pycanha_core.tmm.ExtrapolationMethod = ExtrapolationMethod.CONSTANT) -> None

Create a lookup table from x and y arrays.

evaluate#

Overloaded function.

evaluate(self, x_value: float) -> float

Evaluate the table at a single x value.

evaluate(self, x_values: numpy.ndarray[dtype=float64, shape=(*), order='C']) -> numpy.ndarray[dtype=float64, shape=(*), order='C']

Evaluate the table at an array of x values.

property extrapolation_method#: Extrapolation method used outside the data range.

property interpolation_method#: Interpolation method used between data points.

set_data#: Replace the x and y data arrays.

property size#: Number of data points in the table.

property x#: Input x data points (read-only view).

property y#: Output y data points (read-only view).

class LookupTableVec1D(*args, **kwargs)#

Bases: object

1-D lookup table mapping scalar x -> vector y.

Each x value maps to a row of y values.

__init__#

Overloaded function.

__init__(self) -> None

Create an empty vector lookup table.

__init__(self, x: numpy.ndarray[dtype=float64, shape=(*), order='C'], y: numpy.ndarray[dtype=float64, shape=(*, *), order='C'], interpolation: pycanha_core.pycanha_core.tmm.InterpolationMethod = InterpolationMethod.LINEAR, extrapolation: pycanha_core.pycanha_core.tmm.ExtrapolationMethod = ExtrapolationMethod.CONSTANT) -> None

Create a vector lookup table from x and y (matrix) data.

evaluate#

Overloaded function.

evaluate(self, x_value: float) -> numpy.ndarray[dtype=float64, shape=(*), order='C']

Evaluate the table at a single x value, returning a 1-D array.

evaluate(self, x_values: numpy.ndarray[dtype=float64, shape=(*), order='C']) -> numpy.ndarray[dtype=float64, shape=(*, *), order='C']

Evaluate the table at an array of x values, returning a matrix.

property extrapolation_method#: Extrapolation method used outside the data range.

property interpolation_method#: Interpolation method used between data points.

property num_values#: Number of y values per x data point (columns).

set_data#: Replace the x and y data.

property size#: Number of x data points.

property x#: Input x data points.

property y#: Output y matrix.

class DenseTimeSeries(*args, **kwargs)#

Bases: object

Dense time series storing times (vector) and values (matrix).

Each row corresponds to a timestep; each column to a variable.

__init__#

Overloaded function.

__init__(self) -> None

Create an empty dense time series.

__init__(self, num_timesteps: int, num_columns: int) -> None

Create a dense time series with pre-allocated dimensions.

interpolate#: Interpolate values at an arbitrary time.

property num_columns#: Number of value columns in the series.

property num_timesteps#: Number of timesteps (rows) in the series.

reset#: Reset the time series to empty state.

resize#: Resize the time series to new dimensions.

set_row#: Set a single row of the time series (time + values).

property times#: Time values for each timestep (mutable numpy view).

property values#

rows = timesteps, columns = variables (mutable numpy view).

Type:: Data matrix

class SparseTimeSeries(*args, **kwargs)#

Bases: object

Sparse time series storing a sequence of sparse matrices at discrete time points.

__init__#: Create an empty sparse time series.

at#: Get the sparse matrix at timestep index i (copy).

property cols#: Number of columns in the sparse matrices.

interpolate#: Interpolate the sparse matrices at an arbitrary time.

property nnz#: Number of non-zeros in the reference structure.

property num_timesteps#: Number of stored timesteps.

push_back#: Append a sparse matrix at the given time.

reserve#: Reserve storage for n timesteps.

property rows#: Number of rows in the sparse matrices.

time_at#: Get the time value at timestep index i.

property times#: Time values for each stored matrix (copy).

class TimeVariable#

Bases: object

A parameter whose value is driven by a lookup table of time.

Created via ThermalMathematicalModel.add_time_variable().

property current_value#: Current interpolated value.

property lookup_table#: The underlying LookupTable1D.

property name#: Variable name.

class TemperatureVariable(*args, **kwargs)#

Bases: object

A variable evaluated as a function of temperature via a lookup table.

Created via ThermalMathematicalModel.add_temperature_variable().

__init__#: Create a temperature variable with the given lookup table.

evaluate#: Evaluate the variable at a given temperature.

property lookup_table#: The underlying LookupTable1D.

property name#: Variable name.

Network and model#

class ThermalNetwork(*args, **kwargs)#

Bases: object

Thermal network combining nodes, conductive couplings, and radiative couplings.

__init__#

Overloaded function.

__init__(self) -> None

Create an empty thermal network.

__init__(self, nodes: pycanha_core.pycanha_core.tmm.Nodes, conductive: pycanha_core.pycanha_core.tmm.ConductiveCouplings, radiative: pycanha_core.pycanha_core.tmm.RadiativeCouplings) -> None

Create a thermal network from existing components.

add_node#: Add a node to the network.

property conductive_couplings#: Reference to the ConductiveCouplings container.

flow_conductive#

Overloaded function.

flow_conductive(self, node_num_1: int, node_num_2: int) -> float

Compute conductive heat flow [W] between two nodes.

flow_conductive(self, node_nums_1: collections.abc.Sequence[int], node_nums_2: collections.abc.Sequence[int]) -> float

Compute total conductive heat flow [W] between two groups of nodes.

flow_radiative#

Overloaded function.

flow_radiative(self, node_num_1: int, node_num_2: int) -> float

Compute radiative heat flow [W] between two nodes.

flow_radiative(self, node_nums_1: collections.abc.Sequence[int], node_nums_2: collections.abc.Sequence[int]) -> float

Compute total radiative heat flow [W] between two groups of nodes.

property nodes#: Reference to the Nodes container.

property nodes_ptr#: Shared pointer to the Nodes container.

property radiative_couplings#: Reference to the RadiativeCouplings container.

remove_node#: Remove a node from the network by user node number.

class ThermalData(*args, **kwargs)#

Bases: object

Storage for simulation data models and auxiliary lookup tables.

__init__#

Overloaded function.

__init__(self) -> None

Create an empty ThermalData store.

__init__(self, network: pycanha_core.pycanha_core.tmm.ThermalNetwork) -> None

Create a ThermalData store associated with a network.

associate#: Associate this ThermalData with a ThermalNetwork.

property models#: Reference to the transient output model store.

property network#: Reference to the associated ThermalNetwork.

property network_ptr#: Shared pointer to the associated ThermalNetwork.

property size#: Total number of stored data objects.

property tables#: Reference to the lookup-table store.

class ThermalMathematicalModel(*args, **kwargs)#

Bases: object

Top-level thermal mathematical model.

Aggregates a thermal network (nodes and couplings), parameters, formulas, thermal data tables, and solver callbacks. Non-copyable.

__init__#

Overloaded function.

__init__(self, model_name: str) -> None

Create a model with an empty network.

__init__(self, model_name: str, nodes: pycanha_core.pycanha_core.tmm.Nodes, conductive: pycanha_core.pycanha_core.tmm.ConductiveCouplings, radiative: pycanha_core.pycanha_core.tmm.RadiativeCouplings) -> None

Create a model from existing network components.

__init__(self, model_name: str, nodes: pycanha_core.pycanha_core.tmm.Nodes, conductive: pycanha_core.pycanha_core.tmm.ConductiveCouplings, radiative: pycanha_core.pycanha_core.tmm.RadiativeCouplings, parameters: pycanha_core.pycanha_core.parameters.Parameters, formulas: pycanha_core.pycanha_core.parameters.Formulas, thermal_data: pycanha_core.pycanha_core.tmm.ThermalData) -> None

Create a model from all existing components.

add_conductive_coupling#

Overloaded function.

add_conductive_coupling(self, node_1: int, node_2: int, value: float) -> None

Add a conductive coupling [W/K] between two nodes.

add_conductive_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a conductive coupling from a Coupling object.

add_node#

Overloaded function.

add_node(self, node: pycanha_core.pycanha_core.tmm.Node) -> None

Add a Node object to the model.

add_node(self, node_num: int) -> None

Add a default node by user node number.

add_radiative_coupling#

Overloaded function.

add_radiative_coupling(self, node_1: int, node_2: int, value: float) -> None

Add a radiative coupling [m^2] between two nodes.

add_radiative_coupling(self, coupling: pycanha_core.pycanha_core.tmm.Coupling) -> None

Add a radiative coupling from a Coupling object.

add_temperature_variable#: Add a temperature-driven variable (evaluated from a lookup table of temperature).

add_time_variable#: Add a time-driven variable (parameter updated from a lookup table of time).

property c_callbacks_active#: Enable/disable C function-pointer callbacks.

callback_solver_loop#: Execute all registered solver-loop callbacks.

callback_transient_after_timestep#: Execute all registered after-timestep callbacks.

callback_transient_time_change#: Execute all registered time-change callbacks.

property callbacks_active#: Master switch to enable/disable all callbacks.

property conductive_couplings#: Reference to the ConductiveCouplings.

property formulas#: Reference to the Formulas collection.

get_temperature_variable#: Get a read-only reference to a temperature variable by name.

get_time_variable#: Get a read-only reference to a time variable by name.

has_temperature_variable#: Check whether a temperature variable with the given name exists.

has_time_variable#: Check whether a time variable with the given name exists.

property internal_callbacks_active#: Enable/disable internal (C++) callbacks.

property name#: Model name.

property network#: Reference to the ThermalNetwork.

property network_ptr#: Shared pointer to the ThermalNetwork.

property nodes#: Reference to the Nodes container.

property nodes_ptr#: Shared pointer to the Nodes container.

property parameters#: Reference to the Parameters store.

property python_apply_formulas#: Python callable invoked to apply formulas during callbacks.

property python_callbacks_active#: Enable/disable Python callbacks.

property python_extern_callback_solver_loop#: Python callable invoked each solver iteration.

property python_extern_callback_transient_after_timestep#: Python callable invoked after each transient timestep.

property python_extern_callback_transient_time_change#: Python callable invoked when simulation time changes.

property python_formulas_active#: Enable/disable Python formula evaluation during callbacks.

property radiative_couplings#: Reference to the RadiativeCouplings.

read_tmd#: Read an ESATAN TMD file into this model.

remove_temperature_variable#: Remove a temperature variable by name.

remove_time_variable#: Remove a time variable by name.

property thermal_data#: Reference to the ThermalData store.

property time#: Current simulation time [s].

class ESATANReader(*args, **kwargs)#

Bases: object

Reader for ESATAN TMD thermal model files.

__init__#: Create a reader bound to a ThermalMathematicalModel.

read_tmd#: Read an ESATAN TMD file into the associated model.

property verbose#: Enable verbose logging during file reading.

Helpers#

read_tmd_transient(filepath: str, thermal_data: pycanha_core.pycanha_core.tmm.ThermalData, model_name: str, overwrite: bool = False, attributes: collections.abc.Sequence[pycanha_core.pycanha_core.tmm.DataModelAttribute] = [DataModelAttribute.T, DataModelAttribute.C, DataModelAttribute.QA, DataModelAttribute.QE, DataModelAttribute.QI, DataModelAttribute.QR, DataModelAttribute.QS]) → list[int]#

Read ESATAN TMD transient results into a named DataModel.

Returns a list of node numbers found in the file.

pycanha_core.tmm — Thermal Model Classes#

Enumerations#

Nodes#

Couplings#

Thermal data#

Network and model#

Helpers#

`pycanha_core.tmm` — Thermal Model Classes#