physioblocks 1.0.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

physioblocks/__init__.py

@@ -26,7 +26,7 @@
 
 """Physioblocks package definition"""
 
-__version__ = "1.0.2"
+__version__ = "1.1.0"
 __copyright__ = "INRIA"
 __license__ = "LGPL-3.0-only"
 __authors__ = [

physioblocks/computing/models.py

@@ -32,6 +32,7 @@ functions.
 
 from __future__ import annotations
 
+import functools
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from inspect import get_annotations
@@ -46,7 +47,7 @@ SystemFunction: TypeAlias = Callable[..., np.float64 | NDArray[np.float64]]
 """Type alias for functions composing the system"""
 
 
-@dataclass(frozen=True)
+@dataclass
 class Expression:
     """Expression(size:int, expr_func: SystemFunction, expr_gradients: Mapping[str, SystemFunction] = {})
     Store function computing numerical values for terms in the models with the function
@@ -102,6 +103,223 @@ class Expression:
         )
 
 
+class ExpressionDecorator:
+    """
+    Base class for expression decorators.
+
+    This is a helper that defines expressions decorating methods in a model or block
+    class.
+    """
+
+    expression: Expression
+    """The expression resulting from decorators declarations"""
+
+    def __init__(
+        self,
+        wrapped_function: Callable[..., Any],
+    ):
+        """
+        :param wrapped_function: The decorated expression function
+        :type wrapped_function: Callable
+        """
+        self.expression = Expression(0, wrapped_function)
+        self._terms: list[tuple[str, int, int]] = []
+        functools.update_wrapper(self, wrapped_function)
+
+    def register_term(
+        self,
+        term_name: str,
+        term_size: int,
+        term_index: int,
+    ) -> None:
+        """
+        Register a new term to the expression decorator
+
+        :param term_name: the term local name.
+        :type term_name: str
+
+        :param term_size: The size of the term
+        :type term_size: int
+
+        :param term_index: The start index of the term in the expression
+        :type term_index: int
+        """
+        self.expression.size += term_size
+        self._terms.append((term_name, term_size, term_index))
+
+    @property
+    def terms(self) -> list[tuple[str, int, int]]:
+        """
+        Get the terms described by the expression.
+
+        :return: list of terms description
+        :rtype: list[[tuple[str, int, int]]]
+        """
+        return self._terms.copy()
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.expression.expr_func(*args, **kwargs)
+
+    def partial_derivative(
+        self, variable_name: str
+    ) -> Callable[..., Callable[..., Any]]:
+        """
+        Declares a flux partial derivative.
+
+        :param variable_name: the variable local name.
+        :type variable_name: str
+        """
+
+        def _register(wrapped: Callable[..., Any]) -> Callable[..., Any]:
+            self.expression.expr_gradients[variable_name] = wrapped
+            return wrapped
+
+        return _register
+
+
+def _check_expression_decorator_type(
+    wrapped_function: Any, new_decorator_type: type[ExpressionDecorator]
+) -> None:
+    if (
+        isinstance(wrapped_function, ExpressionDecorator) is True
+        and isinstance(wrapped_function, new_decorator_type) is False
+    ):
+        raise ValueError(
+            str.format(
+                "Can not decorate a function of an other type. "
+                "Current type is {0}, new type is {1}.",
+                type(wrapped_function),
+                new_decorator_type,
+            )
+        )
+
+
+class InternalEquationDecorator(ExpressionDecorator):
+    """
+    Define a decorator that identifies internal equation expressions.
+    """
+
+    pass
+
+
+def declares_internal_equation(
+    variable_name: str, size: int = 1, starting_index: int = 0
+) -> Callable[..., InternalEquationDecorator]:
+    """
+    Declares a internal equation expression.
+
+    Once the internal equation function is declared, partial derivatives can be added
+    using the function name and the local variable name for the partial derivative.
+
+    :param variable_name: the variable name on which the expression provides a dynamic.
+    :type variable_name: str
+
+    :param size: the size of the equation. Default is 1
+    :type size: int
+
+    :param starting_index: the starting index of the equation line matching the
+      variable. Default is 0
+    :type starting_index: int
+
+    :raises ValueError: Raises a ValueError if the function is already decorated with
+      an expression decorator of an other type.
+
+    Example
+    ^^^^^^^
+
+    .. code:: python
+
+        @dataclass
+        class SimpleModel(ModelComponent):
+
+            x: Quantity
+            a: Quantity
+
+            @declares_internal_equation("x")
+            def residual(self):
+                return x.new**2 - a.current
+
+            @flux_1.partial_derivative("x")
+            def dresidual_dx(self):
+                return 2.0 * x.new
+    """
+
+    def _create_internal_equation_decorator(
+        wrapped: Callable[..., Any],
+    ) -> InternalEquationDecorator:
+        _check_expression_decorator_type(wrapped, InternalEquationDecorator)
+
+        decorated = (
+            wrapped
+            if isinstance(wrapped, InternalEquationDecorator)
+            else InternalEquationDecorator(wrapped)
+        )
+        decorated.register_term(variable_name, size, starting_index)
+        return decorated
+
+    return _create_internal_equation_decorator
+
+
+class SavedQuantityDecorator(ExpressionDecorator):
+    """
+    Define a decorator that identifies saved quantities expressions.
+    """
+
+    pass
+
+
+def declares_saved_quantity(
+    quantity_name: str, size: int = 1, starting_index: int = 0
+) -> Callable[..., SavedQuantityDecorator]:
+    """
+    Declares a saved quantity expression.
+
+    :param quantity_name: the local quantity name.
+    :type quantity_name: str
+
+    :param size: the size of the expression. Default is 1
+    :type size: int
+
+    :param starting_index: the starting index of the expression in the function.
+      Default is 0
+    :type starting_index: int
+
+    :raises ValueError: Raises a ValueError if the function is already decorated with
+      an expression decorator of an other type.
+
+    Example
+    ^^^^^^^
+
+    .. code:: python
+
+        @dataclass
+        class SimpleModel(ModelComponent):
+
+            a: Quantity
+            b: Quantity
+
+            @declares_saved_quantity("a + b")
+            def sum(self):
+                return a.current + b.current
+    """
+
+    def _create_saved_quantity_decorator(
+        wrapped: Callable[..., Any],
+    ) -> SavedQuantityDecorator:
+        _check_expression_decorator_type(wrapped, SavedQuantityDecorator)
+
+        decorator = (
+            wrapped
+            if isinstance(wrapped, SavedQuantityDecorator)
+            else SavedQuantityDecorator(wrapped)
+        )
+        decorator.register_term(quantity_name, size, starting_index)
+
+        return decorator
+
+    return _create_saved_quantity_decorator
+
+
 @dataclass(frozen=True)
 class TermDefinition:
     """Describe Terms defined in an :class:`~physioblocks.computing.models.Expression`.
@@ -303,6 +521,23 @@ class ModelComponentMetaClass(type):
             cls.__INTERNAL_EXPRESSION_KEY: [],
             cls.__SAVED_QUANTITIES_EXPRESSION_KEY: [],
         }
+        for attr in cls.__dict__.values():
+            if isinstance(attr, InternalEquationDecorator):
+                for term_name, term_size, term_index in attr.terms:
+                    cls.declares_internal_expression(
+                        term_name,
+                        attr.expression,
+                        term_size,
+                        term_index,
+                    )
+            elif isinstance(attr, SavedQuantityDecorator):
+                for term_name, term_size, term_index in attr.terms:
+                    cls.declares_saved_quantity_expression(
+                        term_name,
+                        attr.expression,
+                        term_size,
+                        term_index,
+                    )
 
     @staticmethod
     def __is_quantity_type(type_to_test: Any) -> bool:
@@ -481,6 +716,7 @@ class ModelComponentMetaClass(type):
 
         # Add the term definition to the expression definition
         expression_def.terms.append(TermDefinition(term_id, size, index))
+        expression_def.terms.sort(key=lambda term: term.index)
 
     def declares_internal_expression(
         cls,
@@ -690,6 +926,78 @@ class ModelComponent(metaclass=ModelComponentMetaClass):
         """Override this method to define specific for model initialization."""
 
 
+class FluxDecorator(ExpressionDecorator):
+    """
+    Define a decorator that identifies flux functions
+    """
+
+    pass
+
+
+def declares_flux(
+    index: int, dof_name: str, size: int = 1
+) -> Callable[..., FluxDecorator]:
+    """
+    Declares a flux function.
+
+    Once the flux expression is declared, partial derivatives can be added using the
+    flux function name and the local variable name for the partial derivative.
+
+    :param index: the index of the flux in the block.
+    :type index: int
+
+    :param dof_name: the matching dof local name
+    :type dof_name: str
+
+    :param size: the size of the flux returned by the function
+    :type size: int
+
+    :raises ValueError: Raises a ValueError if the function is already decorated with
+      an expression decorator of an other type.
+
+
+    Example
+    ^^^^^^^
+
+    .. code:: python
+
+        @dataclass
+        class SimpleBlock(Block):
+
+            q_1: Quantity
+
+            # declares a flux shared at local node 1, where the associated dof has the
+            # local name "potential_1"
+            @declares_flux(1, "potential_1")
+            def flux_1(self):
+                return q_1.new
+
+            # associate the following function as the partial derivative of "flux_1" for
+            # variable "q_1"
+            @flux_1.partial_derivative("q_1")
+            def dflux_1_dq_1(self):
+                return 1.0
+
+    """
+
+    def _create_flux_decorator(wrapped: Callable[..., Any]) -> FluxDecorator:
+        if isinstance(wrapped, ExpressionDecorator) is True:
+            raise ValueError(
+                str.format(
+                    "Function already declares an expression, it can not be a flux."
+                )
+            )
+
+        decorator = (
+            wrapped if isinstance(wrapped, FluxDecorator) else FluxDecorator(wrapped)
+        )
+        decorator.register_term(dof_name, size, index)
+
+        return decorator
+
+    return _create_flux_decorator
+
+
 class BlockMetaClass(ModelComponentMetaClass):
     """Meta-class for :class:`~physioblocks.computing.models.Block`.
 
@@ -711,6 +1019,10 @@ class BlockMetaClass(ModelComponentMetaClass):
     def __init__(cls, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         cls._fluxes = {}
+        for attr in cls.__dict__.values():
+            if isinstance(attr, FluxDecorator):
+                for term_name, _term_size, term_index in attr.terms:
+                    cls.declares_flux_expression(term_index, term_name, attr.expression)
 
     def declares_flux_expression(
         cls, node_index: int, variable_id: str, expr: Expression

physioblocks/configuration/constants.py

@@ -38,11 +38,8 @@ PARAMETERS_ID = "parameters"
 # Definition of the flux-dof types couples
 FLUX_DOF_DEFINITION_ID = "flux_dof_definitions"
 
-
-# Magnitudes
-
-# The variable magnitude item label in the configuration
-MAGNITUDES = "magnitudes"
+# Options label for specific simulation types
+SIMULATION_OPTIONS = "simulation_options"
 
 # The variable magnitude item label in the configuration
 VARIABLES_MAGNITUDES = "variables_magnitudes"

physioblocks/configuration/simulation/simulations.py

@@ -35,10 +35,10 @@ from typing import Any
 from physioblocks.configuration.base import Configuration, ConfigurationError
 from physioblocks.configuration.constants import (
     INIT_VARIABLES_ID,
-    MAGNITUDES,
     NET_ID,
     OUTPUTS_FUNCTIONS_ID,
     PARAMETERS_ID,
+    SIMULATION_OPTIONS,
     SOLVER_ID,
     TIME_MANAGER_ID,
     VARIABLES_MAGNITUDES,
@@ -86,16 +86,15 @@ def load_simulation_config(
         if SOLVER_ID in config:
             solver = load(config[SOLVER_ID])
 
-        # magnitudes
-        magnitudes = None
-        if VARIABLES_MAGNITUDES in config:
-            magnitudes = load(config[VARIABLES_MAGNITUDES])
+        simulation_options = None
+        if SIMULATION_OPTIONS in config:
+            simulation_options = load(config[SIMULATION_OPTIONS])
 
         sim_factory = SimulationFactory(
             configuration_type,
             solver,
             net,
-            simulation_options={MAGNITUDES: magnitudes},
+            simulation_options=simulation_options,
         )
 
         configuration_object = sim_factory.create_simulation()
@@ -147,7 +146,7 @@ def save_simulation_config(
                 type(variable_init_values).__name__,
             )
         )
-    sim_config[VARIABLES_MAGNITUDES] = save(simulation.magnitudes)
+    sim_config[VARIABLES_MAGNITUDES] = save(simulation.state.magnitudes)
 
     # Parameters
     # Get quantities
@@ -226,6 +225,11 @@ def _configure_simulation(
         configuration_references=simulation.quantities,
     )
 
+    # magnitudes
+    if VARIABLES_MAGNITUDES in config:
+        magnitudes = load(config[VARIABLES_MAGNITUDES])
+        simulation.state.set_variables_magnitudes(magnitudes)
+
     references.update(simulation.quantities)
     references.update(simulation.models)
 

physioblocks/library/blocks/capacitances.py

@@ -31,7 +31,12 @@ from typing import Any
 
 import numpy as np
 
-from physioblocks.computing import Block, Expression, Quantity, diff, mid_point
+from physioblocks.computing import Block, Quantity, diff, mid_point
+from physioblocks.computing.models import (
+    declares_flux,
+    declares_internal_equation,
+    declares_saved_quantity,
+)
 from physioblocks.registers import register_type
 from physioblocks.simulation import Time
 
@@ -41,8 +46,8 @@ from physioblocks.simulation import Time
 # Constant for the c block type id
 C_BLOCK_TYPE_ID = "c_block"
 
-# Constant for the c block dof id
-C_BLOCK_PRESSURE_DOF_ID = "pressure"
+# Constant for the c block pressure local id
+C_BLOCK_PRESSURE_ID = "pressure"
 
 
 @register_type(C_BLOCK_TYPE_ID)
@@ -77,6 +82,7 @@ class CBlock(Block):
     time: Time
     """Simulation time"""
 
+    @declares_flux(1, C_BLOCK_PRESSURE_ID)
     def flux(self) -> Any:
         """
         Compute the flux at local node 1
@@ -86,6 +92,7 @@ class CBlock(Block):
         """
         return -self.capacitance.current * diff(self.pressure) * self.time.inv_dt
 
+    @flux.partial_derivative(C_BLOCK_PRESSURE_ID)
     def dflux_dpressure(self) -> Any:
         """
         Compute the flux at local node 1 partial derivative for pressure
@@ -96,12 +103,6 @@ class CBlock(Block):
         return -self.capacitance.current * self.time.inv_dt
 
 
-_c_block_flux_expression = Expression(
-    1, CBlock.flux, {C_BLOCK_PRESSURE_DOF_ID: CBlock.dflux_dpressure}
-)
-CBlock.declares_flux_expression(1, C_BLOCK_PRESSURE_DOF_ID, _c_block_flux_expression)
-
-
 # RC BLOCK Definition
 
 # Constant for the rc block type id
@@ -164,6 +165,7 @@ class RCBlock(Block):
     time: Time
     """The simulation time"""
 
+    @declares_flux(1, RC_BLOCK_PRESSURE_1_DOF_ID)
     def flux_1(self) -> Any:
         """
         Computes the outlet flux at local node 1.
@@ -175,6 +177,7 @@ class RCBlock(Block):
         pressure_2 = mid_point(self.pressure_2)
         return (pressure_2 - pressure_1) / self.resistance.current
 
+    @flux_1.partial_derivative(RC_BLOCK_PRESSURE_1_DOF_ID)
     def dflux_1_dpressure_1(self) -> Any:
         """
         Computes the outlet flux at node 1 derivative for pressure_1.
@@ -184,6 +187,7 @@ class RCBlock(Block):
         """
         return -0.5 / self.resistance.current
 
+    @flux_1.partial_derivative(RC_BLOCK_PRESSURE_2_DOF_ID)
     def dflux_1_dpressure_2(self) -> Any:
         """
         Computes the outlet flux at node 1 derivative for pressure_2.
@@ -193,6 +197,7 @@ class RCBlock(Block):
         """
         return 0.5 / self.resistance.current
 
+    @declares_flux(2, RC_BLOCK_PRESSURE_2_DOF_ID)
     def flux_2(self) -> Any:
         """
         Computes the outlet flux at node 2.
@@ -208,6 +213,7 @@ class RCBlock(Block):
             - self.capacitance.current * self.time.inv_dt * dpressure_2
         )
 
+    @flux_2.partial_derivative(RC_BLOCK_PRESSURE_1_DOF_ID)
     def dflux_2_dpressure_1(self) -> Any:
         """
         Computes the outlet flux at node 2 derivative for pressure_1.
@@ -217,6 +223,7 @@ class RCBlock(Block):
         """
         return 0.5 / self.resistance.current
 
+    @flux_2.partial_derivative(RC_BLOCK_PRESSURE_2_DOF_ID)
     def dflux_2_dpressure_2(self) -> Any:
         """
         Computes the outlet flux at node 2 derivative for pressure_2.
@@ -229,29 +236,6 @@ class RCBlock(Block):
         )
 
 
-# Define the flux expression going in the input node for rc_block
-_rc_block_flux_1_expr = Expression(
-    1,
-    RCBlock.flux_1,
-    {
-        RC_BLOCK_PRESSURE_1_DOF_ID: RCBlock.dflux_1_dpressure_1,
-        RC_BLOCK_PRESSURE_2_DOF_ID: RCBlock.dflux_1_dpressure_2,
-    },
-)
-
-# Define the flux expression going in the output node for rc_block
-_rc_block_flux_2_expr = Expression(
-    1,
-    RCBlock.flux_2,
-    {
-        RC_BLOCK_PRESSURE_1_DOF_ID: RCBlock.dflux_2_dpressure_1,
-        RC_BLOCK_PRESSURE_2_DOF_ID: RCBlock.dflux_2_dpressure_2,
-    },
-)
-
-RCBlock.declares_flux_expression(1, RC_BLOCK_PRESSURE_1_DOF_ID, _rc_block_flux_1_expr)
-RCBlock.declares_flux_expression(2, RC_BLOCK_PRESSURE_2_DOF_ID, _rc_block_flux_2_expr)
-
 # RCR BLOCK Definition
 
 # Constant for the rcr block type id
@@ -300,7 +284,7 @@ class RCRBlock(Block):
 
             \frac{P_1 - P_{mid}}{R_1} + \frac{P_2 - P_{mid}}{R_2} - C\dot{P}_{mid} = 0
 
-    **Discretisation:**
+    **Discretization:**
 
         .. math::
 
@@ -341,6 +325,7 @@ class RCRBlock(Block):
     time: Time
     """The simulation time"""
 
+    @declares_flux(1, RCR_BLOCK_PRESSURE_1_ID)
     def flux_1(self) -> Any:
         """
         Computes the outlet flux at node 1.
@@ -354,6 +339,7 @@ class RCRBlock(Block):
 
         return (pressure_mid_discr - pressure_1_discr) / self.resistance_1.current
 
+    @flux_1.partial_derivative(RCR_BLOCK_PRESSURE_1_ID)
     def dflux_1_dp_1(self) -> Any:
         """
         Computes the outlet flux at node 1 derivative for pressure_1.
@@ -364,6 +350,7 @@ class RCRBlock(Block):
 
         return -0.5 / self.resistance_1.current
 
+    @flux_1.partial_derivative(RCR_BLOCK_PRESSURE_MID_ID)
     def dflux_1_dp_mid(self) -> Any:
         """
         Computes the outlet flux at node 1 derivative for pressure_mid.
@@ -374,6 +361,7 @@ class RCRBlock(Block):
 
         return 0.5 / self.resistance_1.current
 
+    @declares_flux(2, RCR_BLOCK_PRESSURE_2_ID)
     def flux_2(self) -> Any:
         """
         Computes the flux at node 2.
@@ -386,6 +374,7 @@ class RCRBlock(Block):
 
         return (pressure_mid_discr - pressure_2_discr) / self.resistance_2.current
 
+    @flux_2.partial_derivative(RCR_BLOCK_PRESSURE_MID_ID)
     def dflux_2_dp_mid(self) -> Any:
         """
         Computes the outlet flux at node 2 derivative for pressure_mid.
@@ -396,6 +385,7 @@ class RCRBlock(Block):
 
         return 0.5 / self.resistance_2.current
 
+    @flux_2.partial_derivative(RCR_BLOCK_PRESSURE_2_ID)
     def dflux_2_dp_2(self) -> Any:
         """
         Computes the outlet flux at node 2 derivative for pressure_2.
@@ -406,6 +396,7 @@ class RCRBlock(Block):
 
         return -0.5 / self.resistance_2.current
 
+    @declares_internal_equation(RCR_BLOCK_PRESSURE_MID_ID)
     def pressure_mid_residual(self) -> Any:
         """
         Compute the residual representing dynamics of the mid node pressure.
@@ -424,6 +415,7 @@ class RCRBlock(Block):
             - self.capacitance.current * self.time.inv_dt * diff(self.pressure_mid)
         )
 
+    @pressure_mid_residual.partial_derivative(RCR_BLOCK_PRESSURE_1_ID)
     def pressure_mid_residual_dp_1(self) -> Any:
         """
         Compute the residual derivative for pressure_1
@@ -434,6 +426,7 @@ class RCRBlock(Block):
 
         return 0.5 / self.resistance_1.current
 
+    @pressure_mid_residual.partial_derivative(RCR_BLOCK_PRESSURE_2_ID)
     def pressure_mid_residual_dp_2(self) -> Any:
         """
         Compute the residual derivative for pressure_2
@@ -444,6 +437,7 @@ class RCRBlock(Block):
 
         return 0.5 / self.resistance_2.current
 
+    @pressure_mid_residual.partial_derivative(RCR_BLOCK_PRESSURE_MID_ID)
     def pressure_mid_residual_dp_mid(self) -> Any:
         """
         Compute the residual derivative for pressure_mid
@@ -458,6 +452,7 @@ class RCRBlock(Block):
             - 0.5 / self.resistance_2.current
         )
 
+    @declares_saved_quantity("volume")
     def compute_volume_stored(self) -> Any:
         """
         Computes volume stored in the capacitance.
@@ -467,50 +462,3 @@ class RCRBlock(Block):
         """
 
         return self.capacitance.current * self.pressure_mid.current
-
-
-# Define the flux expression going in node 1 for rcr block
-_rcr_block_flux_1_expr = Expression(
-    1,
-    RCRBlock.flux_1,
-    {
-        RCR_BLOCK_PRESSURE_1_ID: RCRBlock.dflux_1_dp_1,
-        RCR_BLOCK_PRESSURE_MID_ID: RCRBlock.dflux_1_dp_mid,
-    },
-)
-
-
-# Define the flux expression going in node 2 for rcr block
-_rcr_block_flux_2_expr = Expression(
-    1,
-    RCRBlock.flux_2,
-    {
-        RCR_BLOCK_PRESSURE_MID_ID: RCRBlock.dflux_2_dp_mid,
-        RCR_BLOCK_PRESSURE_2_ID: RCRBlock.dflux_2_dp_2,
-    },
-)
-
-# Define the residual expression giving the pressure at the mid node
-_rcr_block_pressure_mid_residual_expr = Expression(
-    1,
-    RCRBlock.pressure_mid_residual,
-    {
-        RCR_BLOCK_PRESSURE_1_ID: RCRBlock.pressure_mid_residual_dp_1,
-        RCR_BLOCK_PRESSURE_MID_ID: RCRBlock.pressure_mid_residual_dp_mid,
-        RCR_BLOCK_PRESSURE_2_ID: RCRBlock.pressure_mid_residual_dp_2,
-    },
-)
-
-# Derfine the stored volume saved quantity expression.
-_rcr_volume_stored_expr = Expression(1, RCRBlock.compute_volume_stored)
-
-
-RCRBlock.declares_internal_expression(
-    RCR_BLOCK_PRESSURE_MID_ID, _rcr_block_pressure_mid_residual_expr
-)
-
-RCRBlock.declares_flux_expression(1, RCR_BLOCK_PRESSURE_1_ID, _rcr_block_flux_1_expr)
-RCRBlock.declares_flux_expression(2, RCR_BLOCK_PRESSURE_2_ID, _rcr_block_flux_2_expr)
-RCRBlock.declares_saved_quantity_expression(
-    RCR_BLOCK_VOLUME_OUTPUT_ID, _rcr_volume_stored_expr
-)