Description Module

Declares objects and functions to describe Nets.

Flux

Declares Flux and DOF related objects.

class FluxDofTypesRegister

Stores relations between Flux types and DOFs types

property flux_dof_couples: dict[str, str]

Get all Flux-DOF types couples.

Returns:: the Flux-DOF couples
Return type:: dict[str, str]

property dof_flux_couples: dict[str, str]

Get all DOF-Flux types couples.

Returns:: the DOF-Flux couples
Return type:: dict[str, str]

register_flux_dof_couple(flux_type: str, dof_type: str) → None

Register a matching Flux-DOF type couple.

Parameters:

flux_type (str) – The flux type to register
dof_type (str) – The matching DOF type

Raises:

ValueError – Raise a ValueError when either the Flux or the DOF type is already registered.

unregister_flux_dof_couple(type_id: str) → None

Unregister the flux or DOF type and its matching type.

Parameters:: type_id (str) – The flux or DOF type to unregister
Raises:: ValueError – Raises a ValueError when no flux or DOF type with the given name is registered

get_flux_dof_register() → FluxDofTypesRegister

Get the unique register storing the relation between flux types and DOF types.

Returns:: The register mapping flux types with DOF types
Return type:: FluxDofTypesRegister

class Dof(dof_id: str, dof_type: str)

Degrees of freedom description.

dof_id: str: The id of the dof

dof_type: str: The type of dof (ex: pressure, chemical, etc)

Blocks

Declares the Blocks and their Local Nodes

class ModelComponentDescription(unique_id: str, model_type: type[ModelComponent], global_ids: dict[str, str] | None = None, submodels: dict[str, ModelComponentDescription] | None = None)

Description of a ModelComponent object in a Net object.

Model Components have no fluxes and their description can not interact directly with the net.

To use a model component in a net, it has to be added has a sub-model of a BlockDescription object or of a another ModelComponentDescription object.

Parameters:

unique_id (str) – the model name in the net
model_type (type[ModelComponent]) – the described ModelComponent type
global_ids (dict[str, str]) – mapping of all the component local parameter name with their global names in the net
submodels (dict[str, ModelComponentDescription]) – mapping of all the model submodels with their name.

property name: str

Get the model component name.

Returns:: the model component name
Return type:: str

property global_ids: dict[str, str]

Get a mapping of all local name of the quantities matching their global name in the net.

Returns:: the global ids of the model
Return type:: dict[str, str]

property described_type: type[ModelComponent]

Get the described ModelComponent type.

Returns:: the model component type
Return type:: type[ModelComponent]

property submodels: dict[str, ModelComponentDescription]

Get the submodels descriptions.

Returns:: the submodel descriptions
Return type:: dict[str, ModelComponentDescription]

property internal_variables: list[tuple[str, int]]

Get the model Internal Variables global names recursively for the model and its submodels.

Returns:: the internal variables name and sizes
Return type:: list[tuple[str, int]]

property internal_expressions: list[ExpressionDefinition]

Get the ExpressionDefinition object representing model’s Internal equations.

Returns:: all the model internal equations
Return type:: list[ExpressionDefinition]

property saved_quantities: list[tuple[str, int]]

Get the model Saved Quantities global names and sizes recursivly for the model and its submodels.

Returns:: the saved quantities name and sizes
Return type:: list[tuple[str, int]]

property saved_quantities_expressions: list[ExpressionDefinition]

Get all saved quantities expressions definitions for model

Returns:: all the model saved quantities expression definitions
Return type:: list[ExpressionDefinition]

rename_global_id(old_id: str, new_id: str) → None

Rename the global name with the new name in the current model and all its submodels.

If no name is a match, then no name are changed.

Parameters:

old_id (str) – the global name to rename
new_id (str) – the new name to set

add_submodel(local_model_id: str, model_description: ModelComponentDescription) → ModelComponentDescription

Add a submodel to the model.

Create and return a copy of the input model description updated with correct ids.

Parameters:

model_id (str) – The submodel name
model_description – The model to add

Returns:

the submodel description in the current model description

Return type:

ModelComponentDescritpion

remove_submodel(model_id: str) → ModelComponentDescription

Remove the submodel.

Parameters:: model_id (str) – the id of the submodel to remove
Returns:: the removed submodel description
Return type:: ModelComponentDescritpion

class BlockDescription(block_id: str, block_type: type[Block], flux_type: str, global_ids: dict[str, str] | None = None, submodels: dict[str, ModelComponentDescription] | None = None)

Extend the ModelComponentDescription to describe Block object in the net.

Block descriptions connect their block’s flux to Node objects to share them across the net.

Note

Internal variables can be empty, but described Block type should at least define one Flux (otherwise, it can not interact with the others blocks in the net)

Parameters:

block_id (str) – the block name in the net
block_type (type[Block]) – the described block type
flux_type (str) – the type of flux exchanged by the block
global_ids (dict[str, str]) – mapping of all the block local parameter name with their global names in the net
submodels (dict[str, ModelComponentDescription]) – mapping of all the block submodels with their name.

Example

>>> block_description = BlockDescription(
        "rc_block_1", # block name
        RCBlock, # block type
        "flow", # block flux type
        {
            "resistance": "r1", # rename "rc_block_1.resistance" to "r1"
            "capacitance": "c1", # rename "rc_block_1.capacitance" to "c1"
        }
        # no submodels defined
    )

property described_type: type[Block]

Get the described Block type.

Returns:: the block type
Return type:: type[Block]

property fluxes: dict[int, Expression]

Get a mapping of flux ~physioblocks.computing.models.Expression associated with their Local Node index.

Returns:: the flux expression at each local node
Return type:: dict[int, Expression]

property flux_type: str

Get the type of the block’s flux.

Returns:: the flux type
Return type:: str

Nets

Define the Net object that organises BlockDescription and Node to describe the global system.

class BoundaryCondition(condition_type: str, condition_id: str)

Holds boundary condition description.

condition_type: str: The condition type id

condition_id: str: The name of the parameter

class Node(node_id: str)

Global Node in a Net object.

They hold a set of Dof and BoundaryCondition. They define one dof per Flux Type.

For every block sharing a flux at the node, it holds its name in the net matching the local node index of the flux.

Different Flux types can be shared at the same node, but they will not mix (.ie Flux are only summed with the other Flux of the same type). Consequently, each node adds one equation per Flux Type to the Global System.

Parameters:: node_id (str) – the name of the node in the net

property name: str

Get the name of the node in the net

Returns:: the node name
Return type:: str

has_flux_type(flux_type: str) → bool

Check if the flux type is defined at the node.

Returns:: True if the flux type is accepted, False otherwise
Return type:: bool

add_dof(dof_id: str, dof_type: str) → None

Create a Dof object of the given type at the node.

Parameters:

dof_id (str) – the dof id.
dof_type (str) – the DOF type.

Raises:

ValueError – raises a Value Error if the Dof type is not registered.

remove_dof(dof_type: str) → None

Remove the DOF of the given type.

Parameters:: dof_type (str) – the DOF type.

property dofs: list[Dof]

Get all DOFs at the node.

Returns:: all the DOFs at the node.
Return type:: list[Dof]

get_flux_dof(flux_type: str) → Dof

Get the DOF matching the flux type.

Parameters:: flux_type (str) – the flux type.
Returns:: the DOF
Return type:: Dof

get_dof(dof_id: str) → Dof

Get a DOF with the given id.

Parameters:: dof_id (str) – id of the DOF to get
Raises:: KeyError – Error raised when there are no DOFs with the given id at the node.
Returns:: the DOF if it exists
Return type:: Dof

property is_boundary: bool

Check if the node is defines a boundary of the net.

Returns:: True if the node is a boundary, False otherwise
Return type:: bool

property boundary_conditions: list[BoundaryCondition]

Get the boundary conditions at the node.

This is a list of string representing the boundary condition types add the node.

Returns:: a list the boundaries conditions
Return type:: list[str]

add_boundary_condition(condition_type: str, parameter_id: str) → BoundaryCondition

Add a boundary condition at the node.

A DOF or flux type matching the condition type should exist.

Parameters:

condition_type (str) – the flux or potential type
parameter_id – the condition parameter global name

Raises:

ValueError – Raises a ValueError when no DOF or flux type is matching the condition type or when a matching type already has a boundary condition

remove_boundary_condition(condition_type: str) → None

Remove a boundary condition of the matching type.

Parameters:: condition_type (str) – the flux or potential type

property local_nodes: list[tuple[str, int]]

Get all the local nodes.

Returns:: The list of local nodes
Return type:: list[tuple[str, int]]

add_node_local(block_id: str, block_node_index: int) → None

Add a block local node to the global node.

Parameters:

block_id (int) – the block id in the net.
block_node_index (int) – the local node index in the block

remove_node_local(block_id: str, block_node_index: int) → None

Remove a block local node from the global node.

Parameters:

block_id (str) – the block id in the net.
block_node_index (int) – the local node index in the block

has_node_local(block_id: str, block_node_index: int) → bool

Check if a local node is linked to this global node.

Parameters:

block_id (str) – the block id in the net.
block_node_index (int) – the local node index in the block

Returns:

True if the block local node is linked to this node, False otherwise

Return type:

bool

class Net

The Net stores the Blocks and linked them with nodes.

It allows to create the global system.

Internal Equations of the blocks and their submodels are concatenated to the residual.

The fluxes shared at each node are summed by flux type and concatenated to the global system.

property blocks: dict[str, BlockDescription]

Get the BlockDescription objects in the net.

Returns:: the blocks descriptions in the net.
Return type:: dict[str, BlockDescription]

property nodes: dict[str, Node]

Get the Node objects in the net.

Returns:: the nodes in the net.
Return type:: dict[str, Nodes]

property boundary_conditions: dict[str, list[BoundaryCondition]]

Get BoundaryCondition objects in the net with their matching node name.

Returns:: the net boundaries conditions
Return type:: dict[str, list[BoundaryCondition]]

add_node(node_id: str) → Node

Add a new node to the net.

Parameters:: node_id (str) – The node id.
Raises:: ValueError – Raise a ValueError if a node with the same id is already in the net.
Returns:: the added node
Return type:: Node

remove_node(node_id: str) → None

Remove a node from the net.

Note

It also removes all the blocks linked to the node because their dofs no longer exists.

Parameters:: node_id (str) – The node id.

add_block(block_local_id: str, block_description: BlockDescription, node_ids: dict[int, str]) → BlockDescription

Add a block description in the net.

The method returns a copy of the block updated with correct global and dofs ids in the net.

Parameters:

block_description (BlockDescription) – the block to add
node_ids (dict[int, str]) – a mapping of local node indexes in the block to global nodes names in the net.

Raises:

ValueError – Exception raised if the block is already in the net or if there is already a block with the given id.

Returns:

the added block description

Return type:

BlockDescription

Note

When adding a block to a net, every of its flux should be linked to a node.

remove_block(block_id: str) → None

Remove a block from the net.

Also removes the dofs at the global nodes that no longer exists when this block is deleted (the dofs that are not linked to any block when the block is removed).

Parameters:: block_id (str) – the block id to remove

local_to_global_node_id(block_id: str, index_block_node: int) → str

Get the id of the global node linked to the given local node.

Parameters:

block_id (str) – the id of the block in the net
index_block_node (int) – the index of the local node in the block

Raises:

ValueError – Raise a ValueError if no globla node is linked to the given local node.

Returns:

the global node name

Return type:

str

set_boundary(node_id: str, condition_type: str, parameter_id: str) → None

Set a BoundaryCondition object in the net.

Parameters:

node_id (str) – the index of the node where to set the boundary condition
condition_type (str) – the flux or dof type of the condition.
parameter_id – the condition matching parameter id

remove_boundary(node_id: str, condition_type: str) → None

Remove a boundary condition from the net.

Parameters:

node_id (str) – the node name where the condition is
condition_type (str) – the flux or dof type for the condition