physioblocks 1.0.3__tar.gz → 1.1.0__tar.gz

{physioblocks-1.0.3 → physioblocks-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: physioblocks
-Version: 1.0.3
+Version: 1.1.0
 Dynamic: Author
 Dynamic: Author-email
 Dynamic: License

{physioblocks-1.0.3 → physioblocks-1.1.0}/doc/source/user_guide/level_3/block_definition.rst

@@ -185,10 +185,21 @@ Declare functions to compute the fluxes and the internal equations
 
 We define methods to compute the :class:`~physioblocks.computing.models.Block` relations as written above in the discretized form.
 
+To make the methods available to build the residual matrix the methods are decorated to identify:
+    
+    * **Fluxes** with :func:`~physioblocks.computing.models.declares_flux` decorator.
+      You will need to set the local node index where the flux is shared as well as the local name in the block of the dof at the node.
+      The default flux size is 1 but can be updated.
+    * **Internal equations** with :func:`~physioblocks.computing.models.declares_internal_equation` decorator.
+      You need to set at least the local name of the variable on which the equation provides a dynamic.
+      Default equation size is set to 1 and can be updated.
+
+
 .. code:: python
 
     # Flux definition
 
+    @declares_flux(1, "pressure_1")
     def flux_1(self):
         """
         Computes the flux at first node.
@@ -198,6 +209,7 @@ We define methods to compute the :class:`~physioblocks.computing.models.Block` r
         
         return (pressure_mid_discr - pressure_1_discr) / self.resistance_1.current
 
+    @declares_flux(2, "pressure_2")
     def flux_2(self):
         """
         Computes the flux at second node.
@@ -208,6 +220,7 @@ We define methods to compute the :class:`~physioblocks.computing.models.Block` r
         return (pressure_mid_discr - pressure_2_discr) / self.resistance_2.current
 
     # Internal Equation definition
+    @declares_internal_equation("pressure_mid")
     def residual_pressure_mid(self):
         """
         Computes the rcr block internal equation residual
@@ -222,7 +235,12 @@ We define methods to compute the :class:`~physioblocks.computing.models.Block` r
             - (pressure_2_discr - pressure_mid_discr) / self.resistance_2
         )
 
+To be able to add output values that are not variables, we identify the saved quantities with :func:`~physioblocks.computing.models.declares_saved_quantity` decorator.
+
+.. code:: python
+
     # Saved Quantity definition
+    @declares_saved_quantities("volume")
     def volume_stored(self):
         """
         Computes volume stored in the capacitance.
@@ -234,17 +252,21 @@ Declare all flux and internal equations partial derivatives
 
 We then have to declare functions to compute fluxes and internal equations partial derivatives.
 
-.. code:: python
+To make the methods available to build the gradient matrix, the methods are decorated to identify function partial derivative with :func:`~physioblocks.computing.models.ExpressionDecorator.partial_derivative` decorator.
+Each decorator associate the function with its the derivation variable local name.
 
-    # Flux 0 partial derivatives
+.. code:: python
 
+    # Flux 1 partial derivatives
+    @flux_1.partial_derivative("pressure_mid")
     def dflux_1_dpressure_mid(self):
         """
-        Computes flux_1 partial derivative for pressure_1.
+        Computes flux_1 partial derivative for pressure_mid.
         """
         
         return 0.5 / self.resistance_1.current
 
+    @flux_1.partial_derivative("pressure_1")
     def dflux_1_dpressure_1(self):
         """
         Computes flux_1 partial derivative for pressure_1.
@@ -252,15 +274,17 @@ We then have to declare functions to compute fluxes and internal equations parti
         
         return - 0.5 / self.resistance_1.current
         
-    # Flux 1 partial derivatives
+    # Flux 2 partial derivatives
 
+    @flux_2.partial_derivative("pressure_mid")
     def dflux_2_dpressure_mid(self):
         """
         Computes flux_2 partial derivative for pressure_mid.
         """
         
-        return 0.5 / self.resistance_1.current
+        return 0.5 / self.resistance_2.current
 
+    @flux_2.partial_derivative("pressure_2")
     def dflux_2_dpressure_2(self):
         """
         Computes flux_2 partial derivative for pressure_2.
@@ -270,6 +294,7 @@ We then have to declare functions to compute fluxes and internal equations parti
 
     # Internal equation partial derivatives:
 
+    @residual_pressure_mid.partial_derivative("pressure_mid")
     def dresidual_pressure_mid_dpressure_mid(self):
         """
         Computes internal equation partial derivative for pressure_mid.
@@ -281,6 +306,7 @@ We then have to declare functions to compute fluxes and internal equations parti
             + 0.5 / self.resistance_2
         )
 
+    @residual_pressure_mid.partial_derivative("pressure_1")
     def dresidual_pressure_mid_dpressure_1(self):
         """
         Computes internal equation partial derivative for pressure_1.
@@ -289,6 +315,7 @@ We then have to declare functions to compute fluxes and internal equations parti
             - 0.5 / self.resistance_1
         )
 
+    @residual_pressure_mid.partial_derivative("pressure_2")
     def dresidual_pressure_mid_dpressure_2(self):
         """
         Computes internal equation partial derivative for pressure_2.
@@ -297,107 +324,6 @@ We then have to declare functions to compute fluxes and internal equations parti
             - 0.5 / self.resistance_2
         )
 
-Define the Block Expressions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-We defined every method to compute our blocks relations along with the needed quantities.
-But these methods are not yet available for the assembling process that builds the global system.
-
-We will now declare **Flux**, **Internal Equations** and **Saved Quantities** :class:`~physioblocks.computing.models.Expression` objects to assemble a residual and gradient matrix.
-
-This is performed on the **block type** directly, calling the created :class:`~physioblocks.library.blocks.capacitances.RCRBlock` class methods.
-
-But first, we have to instantiate the :class:`~physioblocks.computing.models.Expression` objects.
-They are composed of :
-
-    1. the **size** of the expression value
-    2. the **function** computing the expression value
-    3. a dictionary holding the **partial derivatives** for the function matched with the variable name.
-
-Here are all the expressions needed for our :class:`~physioblocks.computing.models.Block`.
-
-.. code:: python
-
-    # Define the flux expression going in the input node for rcr block
-    _rcr_block_flux_1_expr = Expression(
-        1, # flux 0 is size 1
-        RCRBlock.flux_1, # the function to compute flux 0
-        {
-            # the partial derivative for pressure 0 for flux 0
-            "pressure_1": RCRBlock.dflux_1_dpressure_1, 
-            # the partial derivative for pressure mid for flux 0
-            "pressure_mid": RCRBlock.dflux_1_dpressure_mid,
-        }
-    )
-
-    # The next expressions are built similarly:
-    _rcr_block_flux_2_expr = Expression(
-        1,
-        RCRBlock.flux_2,
-        {
-            # the partial derivative for pressure 0 for flux 0
-            "pressure_2": RCRBlock.dflux_2_dpressure_2, 
-            # the partial derivative for pressure mid for flux 0
-            "pressure_mid": RCRBlock.dflux_2_dpressure_mid,
-        }
-    )
-
-    _rcr_block_residual_expr = Expression(
-        1,
-        RCRBlock.residual_pressure_mid,
-        {
-            "pressure_mid": RCRBlock.dresidual_pressure_mid_dpressure_mid,
-            "pressure_1": RCRBlock.dresidual_pressure_mid_dpressure_1,
-            "pressure_2": RCRBlock.dresidual_pressure_mid_dpressure_2,
-        },
-    )
-
-    # The volume stored do not need partial derivatives
-    _rcr_block_volume_stored_expr = Expression(1, RCRBlock.volume_stored)
-
-Now we use the :class:`~physioblocks.library.blocks.capacitances.RCRBlock` class methods to register the expressions.
-To declare a flux expression for the block, we need:
-
-    1. the **index** of the local node sharing the flux.
-    2. the **variable local name** in the :class:`~physioblocks.computing.models.Block`.
-    3. the expression object
-
-.. code:: python
-
-    RCRBlock.declares_flux_expression(
-        0,
-        "pressure_1",
-        _rcr_block_flux_1_expr
-    )
-    RCRBlock.declares_flux_expression(
-        1,
-        "pressure_2",
-        _rcr_block_flux_2_expr
-    )
-
-
-To declare an internal equation expression for the block, we need:
-
-    1. the **internal variable local name** in the :class:`~physioblocks.computing.models.Block`
-    2. the expression object
-
-.. code:: python
-
-    RCRBlock.declares_internal_expression(
-        "pressure_mid",
-        _rcr_block_residual_expr
-    )
-
-Finally, to declare a **Saved Quantity** expression for the block, we need:
-
-    1. the saved quantity **local name**
-    2. the expression object
-
-.. code:: python
-
-    RCRBlock.declares_saved_quantity_expression(
-        "volume_stored", _rcr_block_volume_stored_expr
-    )
 
 Now the :class:`~physioblocks.library.blocks.capacitances.RCRBlock` is completely defined and can be used in a net.
 

{physioblocks-1.0.3 → physioblocks-1.1.0}/physioblocks/__init__.py

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

{physioblocks-1.0.3 → physioblocks-1.1.0}/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