`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#

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.

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.

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.

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#

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 result tables.

Each table is a 2D matrix (rows x cols) identified by a string name. Solvers write output data here.

__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.

create_new_table#: Create a new named table with the given dimensions.

create_reset_table#: Create a table or reset it if it already exists.

get_table#: Get a mutable reference to a table by name.

get_table_const#: Get a read-only reference to a table by name.

has_table#: Check whether a table with the given name exists.

property network#: Reference to the associated ThermalNetwork.

property network_ptr#: Shared pointer to the associated ThermalNetwork.

remove_table#: Remove a table by name.

property size#: Number of stored tables.

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.

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.

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.

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.

pycanha_core.tmm — Thermal Model Classes#

Enumerations#

Nodes#

Couplings#

Thermal data#

Network and model#

Helpers#

`pycanha_core.tmm` — Thermal Model Classes#