`pycanha.parameters` — Parameters and Formulas#

The parameters subpackage provides the parametric study infrastructure: named parameters, entities (references to model scalars), and formulas (rules linking parameters to entities).

The following base classes are re-exported from pycanha_core.parameters — see the pycanha_core.parameters — Core Parameters Classes page for their full documentation:

Parameters#

class pycanha.parameters.Parameters[source]#

Bases: Parameters

add_parameter(self, name: str, value: object) → None#: Add a new named parameter with the given value.

contains(self, name: str) → bool#: Check whether a parameter with the given name exists.

property data#: Dictionary of all parameter name-value pairs.

get_idx(self, name: str) → int | None#: Get the internal index of a parameter by name, or None.

get_memory_address(self, name: str) → int#: Memory address (as int) of a parameter value for formula binding.

get_parameter(self, name: str) → object#: Get the current value of a parameter.

get_size_of_parameter(self, name: str) → int#: Get the byte size of a parameter’s stored value.

is_internal_parameter(self, name: str) → bool#: Check whether a parameter is marked as internal.

remove_parameter(self, name: str) → None#: Remove a parameter by name.

rename_parameter(self, current_name: str, new_name: str) → None#: Rename a parameter.

set_parameter(self, name: str, value: object) → None#: Update the value of an existing parameter.

size(self) → int#: Return the number of stored parameters.

Entities#

class pycanha.parameters.EntityType(*values)#

Bases: Enum

Type of thermal entity in the network.

T = 0#

C = 1#

QS = 2#

QA = 3#

QE = 4#

QI = 5#

QR = 6#

GL = 7#

GR = 8#

class pycanha.parameters.Entity#

Bases: object

Reference to a value in the thermal network.

An Entity points to a specific node attribute (T, C, QI, etc.) or coupling value (GL, GR) in a ThermalNetwork. Use the static factory methods (Entity.make, Entity.t, Entity.gl, etc.) or Entity.from_string to create instances.

albedo_heat = <nanobind.nb_func object>#

c = <nanobind.nb_func object>#

capacity = <nanobind.nb_func object>#

conductive = <nanobind.nb_func object>#

earth_ir = <nanobind.nb_func object>#

exists(self) → bool#: Check if the referenced node/coupling exists in the network.

from_internal_symbol = <nanobind.nb_func object>#

from_string = <nanobind.nb_func object>#

get_value(self) → float#: Get the current value (NaN if invalid).

get_value_pointer(self) → int#: Memory address of the referenced value for formula binding.

gl = <nanobind.nb_func object>#

gr = <nanobind.nb_func object>#

internal_heat = <nanobind.nb_func object>#

internal_symbol_name(self) → str#: Internal symbol name for formula preprocessing.

is_same_as(self, other: pycanha_core.pycanha_core.parameters.Entity) → bool#: Check if this entity references the same value as another.

make = <nanobind.nb_func object>#

property node_1#: First node number.

property node_2#: Second node number (-1 for single-node entities).

property node_count#: Number of nodes this entity type references (0, 1, or 2).

other_heat = <nanobind.nb_func object>#

qa = <nanobind.nb_func object>#

qe = <nanobind.nb_func object>#

qi = <nanobind.nb_func object>#

qr = <nanobind.nb_func object>#

qs = <nanobind.nb_func object>#

radiative = <nanobind.nb_func object>#

set_value(self, value: float) → bool#: Set the value. Returns True on success, False on failure.

solar_heat = <nanobind.nb_func object>#

string_representation(self) → str#: Human-readable string, e.g. ‘T1’, ‘GL(1,2)’.

t = <nanobind.nb_func object>#

temperature = <nanobind.nb_func object>#

property token#: Entity type token string (e.g. ‘T’, ‘GL’).

property type#: Entity type (EntityType enum value).

property writable#: Whether the entity’s value can be set.

Formulas#

class pycanha.parameters.ParameterFormula(*args, **kwargs)[source]#

Bases: ParameterFormula

apply_compiled_formula(self) → None#: Evaluate and write using pre-compiled pointers (faster).

apply_formula(self) → None#: Evaluate and write the parameter value to the entity.

calculate_derivatives(self) → None#: Calculate derivative values with respect to parameter dependencies.

clone(self) → pycanha_core.pycanha_core.parameters.Formula#: Create an independent copy of this formula.

compile_formula(self) → None#: Compile the formula (resolve pointers for fast evaluation).

property entity#: Reference to the target Entity.

property expression#: Original parameter expression string.

get_derivative_values(self) → object#: Get derivative values for sensitivity analysis, or None.

get_value(self) → float#: Get the current parameter value.

property parameter_dependencies#: List of parameter names this formula depends on.

class pycanha.parameters.ExpressionFormula(*args, **kwargs)[source]#

Bases: ExpressionFormula

apply_compiled_formula(self) → None#: Evaluate the compiled expression and write the result to the entity.

apply_formula(self) → None#: Evaluate the expression and write the result to the entity.

calculate_derivatives(self) → None#: Calculate derivative values with respect to parameter dependencies.

clone(self) → pycanha_core.pycanha_core.parameters.Formula#: Create an independent copy of this formula.

compile_formula(self) → None#: Compile the expression for fast repeated evaluation.

property entity#: Reference to the target Entity.

property expression#: Original expression string.

get_derivative_values(self) → object#: Get derivative values for sensitivity analysis, or None.

get_value(self) → float#: Get the current expression value.

property parameter_dependencies#: List of parameter names this formula depends on.

class pycanha.parameters.ValueFormula(*args, **kwargs)[source]#

Bases: ValueFormula

apply_compiled_formula(self) → None#: Write using pre-compiled pointers (faster).

apply_formula(self) → None#: Write the constant value to the entity.

calculate_derivatives(self) → None#: Calculate derivative values with respect to parameter dependencies.

clone(self) → pycanha_core.pycanha_core.parameters.Formula#: Create an independent copy of this formula.

compile_formula(self) → None#: Compile the formula (resolve pointers for fast evaluation).

property entity#: Reference to the target Entity.

get_derivative_values(self) → object#: Get derivative values for sensitivity analysis, or None.

get_value(self) → float#: Get the stored constant value.

property parameter_dependencies#: List of parameter names this formula depends on.

set_value(self, value: float) → None#: Set the constant value to assign.

Formulas collection#

class pycanha.parameters.Formulas(network=None, parameters=None)[source]#

Bases: Formulas

Parameters:

network (pcc.tmm.ThermalNetwork | None)
parameters (pcc.parameters.Parameters | None)

property general_formulas: list[GeneralFormula]#

add_general_formula(entity, *, update, initial_value=0.0, name=None)[source]#

Parameters:

entity (pcc.parameters.Entity | str)
update (Callable[[object], float])
initial_value (float)
name (str | None)

Return type:

GeneralFormula

remove_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity) → bool[source]#

remove_formula(self, entity: str) → bool

Overloaded function.

remove_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity) -> bool

Remove a formula by Entity target.

remove_formula(self, entity: str) -> bool

Remove a formula by entity string target.

Parameters:: entity (Entity | str)
Return type:: bool

apply_formulas(self) → None[source]#

Apply all formulas, propagating parameter values to the network.

Return type:: None

apply_compiled_formulas(self) → None[source]#

Apply using pre-compiled pointers (faster, requires compile_formulas()).

Return type:: None

add_expression_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, expression: str) → pycanha_core.pycanha_core.parameters.ExpressionFormula#

add_expression_formula(self, entity: str, expression: str) → pycanha_core.pycanha_core.parameters.ExpressionFormula

Overloaded function.

add_expression_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, expression: str) -> pycanha_core.pycanha_core.parameters.ExpressionFormula

Add an ExpressionFormula bound to an Entity target.

add_expression_formula(self, entity: str, expression: str) -> pycanha_core.pycanha_core.parameters.ExpressionFormula

Add an ExpressionFormula bound to an entity string target.

add_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, value: float) → pycanha_core.pycanha_core.parameters.Formula#

add_formula(self, entity: str, value: float) → pycanha_core.pycanha_core.parameters.Formula

add_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, formula_string: str) → pycanha_core.pycanha_core.parameters.Formula

add_formula(self, entity: str, formula_string: str) → pycanha_core.pycanha_core.parameters.Formula

add_formula(self, formula: pycanha_core.pycanha_core.parameters.Formula) → None

Overloaded function.

add_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, value: float) -> pycanha_core.pycanha_core.parameters.Formula

Add a formula for an Entity target from a numeric value.

add_formula(self, entity: str, value: float) -> pycanha_core.pycanha_core.parameters.Formula

Add a formula for an entity string target from a numeric value.

add_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, formula_string: str) -> pycanha_core.pycanha_core.parameters.Formula

Add a formula for an Entity target from a string expression.

add_formula(self, entity: str, formula_string: str) -> pycanha_core.pycanha_core.parameters.Formula

Add a formula for an entity string target from a string expression.

add_formula(self, formula: pycanha_core.pycanha_core.parameters.Formula) -> None

Add a formula (by copy) to the collection.

add_formula(self, formula: pycanha_core.pycanha_core.parameters.Formula) -> None

Add a formula (by shared pointer) to the collection.

add_parameter_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, expression: str) → pycanha_core.pycanha_core.parameters.ParameterFormula#

add_parameter_formula(self, entity: str, expression: str) → pycanha_core.pycanha_core.parameters.ParameterFormula

Overloaded function.

add_parameter_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, expression: str) -> pycanha_core.pycanha_core.parameters.ParameterFormula

Add a ParameterFormula bound to an Entity target.

add_parameter_formula(self, entity: str, expression: str) -> pycanha_core.pycanha_core.parameters.ParameterFormula

Add a ParameterFormula bound to an entity string target.

add_value_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, value: float) → pycanha_core.pycanha_core.parameters.ValueFormula#

add_value_formula(self, entity: str, value: float) → pycanha_core.pycanha_core.parameters.ValueFormula

Overloaded function.

add_value_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, value: float) -> pycanha_core.pycanha_core.parameters.ValueFormula

Add a ValueFormula bound to an Entity target.

add_value_formula(self, entity: str, value: float) -> pycanha_core.pycanha_core.parameters.ValueFormula

Add a ValueFormula bound to an entity string target.

associate(self, network: pycanha_core.pycanha_core.tmm.ThermalNetwork, parameters: pycanha_core.pycanha_core.parameters.Parameters) → None#: Associate this collection with a network and parameters store.

calculate_derivatives(self) → None#: Calculate derivatives for all stored formulas.

compile_formulas(self) → None#: Compile all formulas for fast application.

create_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, formula_string: str) → pycanha_core.pycanha_core.parameters.Formula#

Create a formula by auto-detecting its type from the string.

Returns a shared pointer to the created Formula.

create_parameter_formula(self, entity: pycanha_core.pycanha_core.parameters.Entity, parameter: str) → pycanha_core.pycanha_core.parameters.ParameterFormula#: Create and add a ParameterFormula for the entity and parameter name.

property debug_formulas#: Enable debug logging of formula application.

property formulas#: List of all stored Formula objects.

is_compiled_current(self) → bool#: Check whether the compiled state is up to date.

is_validation_current(self) → bool#: Check whether the current validation state is up to date.

lock_parameters_for_execution(self) → None#: Lock parameters to prevent structural changes during solve.

property parameter_dependencies#: Dict mapping parameter names to lists of dependent formulas.

property parameters_with_derivatives#: Ordered registry of derivative-parameter names.

unlock_parameters(self) → None#: Unlock parameters after solve completes.

validate_for_execution(self) → None#: Validate all formulas can be evaluated.

pycanha.parameters — Parameters and Formulas#

Parameters#

Entities#

Formulas#

Formulas collection#

`pycanha.parameters` — Parameters and Formulas#