Utils Module

Defines utils modules for Physioblocks

Exceptions Utils

Declares a functions to log exceptions and to caught unhandled exceptions

ExceptionHandlerFunction

Type alias for exception handler signature

create_uncaught_exception_logger_handler(logger: Logger) → ExceptionHandlerFunction

Create an handler that log an uncaught exception.

Parameters:

logger (Logger) – the logger to use to log the exception

Returns:

the exception handler

Return type:

Callable

Example

# get a logger
SIMULATION_LOG_FORMATER = logging.Formatter(logging.BASIC_FORMAT)
_root_logger = logging.getLogger()
_root_logger.setLevel(logging.DEBUG)

# register a hook to log uncaught exceptions to the logger
sys.excepthook = create_uncaught_exception_logger_handler(_root_logger)
log_exception(logger: Logger, exc_type: type[BaseException], exception: BaseException, tb: TracebackType | None, loglevel: int = 40) → None

Log the provided exception.

Note

Type and message of the exception are logged with the provided loglevel, while the traceback informations are logged as DEBUG.

Parameters:

  • logger (Logger) – the logger used to log

  • exc_type – the exception type

  • exception (TracebackType) – the exception to log

  • tb – the traceback

  • loglevel (int) – The loglevel, default is error

Dynamic Import Utils

Defines methods to dynamically import modules while in a script or python application.

import_libraries(libraries_folder_paths: list[Path]) → None

Dynamically import all the modules at the given paths.

Note

The libraries folders must be in a site to be able to load theirs modules.

Parameters:

libraries_folder_path (list[Path]) – the paths

Example

# Add site for the library to load
site.addsitedir(ABSOLUTE_PATH_TO_LIBRARY)

lib_path = Path(ABSOLUTE_PATH_TO_LIBRARY)
import_libraries([lib_path]) # dynamically import the library

Math Utils

Defines some math functions to help compute quantities

exp_diff(a: float, b: float, diff: float) → Any

Computes exponential differences with more numerical accuracy when a and b are close using the relationship:

\[e^a - e^b = 2\ e^{\frac{a + b}{2}}\ \text{sinh}(\frac{a + b}{2})\]
Parameters:

  • a (np.float64) – value of a

  • b (np.float64) – value of b

  • diff (np.float64) – value of a - b

Returns:

exponential difference value

Return type:

np.float64

power_diff(a: float, b: float, diff: float, n: int) → Any

Computes the a and b power n difference with more numerical accuracy when a and b are close by using the following relationship:

\[a^n - b^n = (a-b) * \sum_{i = 0}^{n -1}{a^i b^{n-1-i}}\]

When n is negative, the following transformation is used:

\[\frac{1}{a^n} - \frac{1}{b^n} = -\frac{a^n-b^n}{{ab}^n}\]
Parameters:

  • a (np.float64) – value of a

  • b (np.float64) – value of b

  • diff (np.float64) – value of a - b

Returns:

the a and b power n difference value

Return type:

np.float64

Gradient Test Utils

Define functions to perform gradient tests to check the coherence between an function and its gradient.

The gradient test principle is to compare the result of a computed and estimated gradient from a EqSystem object.

gradient_test_from_file(config_file_path: str) → bool

Read the given configuration file and perform a gradient test on the full Net with the provided parameters and variables.

Warning

Every type (especially Blocks, ModelComponents and Functions) and alias used in the configuration file have to be loaded. Follow this user guide section to import libraries and aliases dynamically.

Parameters:

config_file_path (str) – the file path to the simulation configuration file.

Returns:

True if the gradient test is successfull, false otherwise.

gradient_test_from_model(model: ModelComponent, state: State, state_magnitude: NDArray[np.float64]) → bool

Create an equation system for the given block only and perform a gradient test.

Note

It does not test the submodels of the model.

Parameters:

  • model (str) – the model to test.

  • state (str) – the state used to determine the variables in the model.

  • state_magnitude (str) – the state variables magnitudes

Returns:

True if the gradient test is successfull, false otherwise.

gradient_test_from_expression(expr: Expression, expr_params: Any, state: State, state_magnitude: NDArray[np.float64]) → bool

Create an equation system for the given expression only and perform a gradient test.

Parameters:

  • expr (Expression) – the expression to test.

  • expr_params (Any) – the parameters to pass to the expression

  • state (str) – the state used to determine the variables in the expression.

  • state_magnitude (str) – the state variables magnitudes

Returns:

True if the gradient test is successfull, false otherwise.

Return type:

bool

gradient_test(eq_system: EqSystem, state: State, state_magnitude: NDArray[np.float64]) → bool

Test the computed gradient for the equation system by comparing it to a gradient estimated with finite differences.

Parameters:

  • eq_system (EqSystem) – the equation system providing method to compute a residual and a gradient

  • state (State) – system state

  • state_magnitude (str) – the state variables magnitudes

Returns:

True if the estimated and computed gradient meet tolerance, False otherwise.

get_errors_gradient(computed: NDArray[np.float64], estimated_1: NDArray[np.float64], estimated_2: NDArray[np.float64]) → list[tuple[int, int]]

Get the (line, column) positions of the errors in the gradient matrix.

Parameters:

  • computed (NDArray[np.float64]) – computed gradient

  • estimated_1 (NDArray[np.float64]) – first gradient estimate

  • estimated_2 (NDArray[np.float64]) – second gradient estimate

Returns:

the position of the errors in the gradient matrix

Return type:

list[tuple[int, int]]

exception GradientError

Error raised when the estimated and computed gradients do not match.