SENSITIVITY_MATRIX

Overview

The SENSITIVITY_MATRIX function computes how the outputs of a model change with respect to changes in parameters or initial conditions. It provides a sensitivity matrix or vector, enabling business users to assess the impact of parameter variations on model results directly in Excel. This function leverages the CasADi package for symbolic and algorithmic differentiation. For more information, see the CasADi documentation .

From a technical perspective, the function uses symbolic differentiation to compute the Jacobian matrix of the model output with respect to the specified parameters. Given a model $f(\mathbf{x}, \mathbf{a})$ where $\mathbf{x}$ are variables and $\mathbf{a}$ are parameters, the sensitivity matrix $S$ is defined as:

S = \frac{\partial f}{\partial \mathbf{a}}

This means each entry $S_{ij}$ represents the partial derivative of the $i$ -th output with respect to the $j$ -th parameter, evaluated at the provided values. The CasADi library constructs the symbolic computation graph and efficiently evaluates these derivatives using algorithmic differentiation, ensuring both accuracy and performance for complex models.

This example function is provided as-is without any representation of accuracy.

Usage

To use the function in Excel:


=SENSITIVITY_MATRIX(model, variables, parameters, [variable_names], [parameter_names])

model (string, required): Symbolic expression for the model output as a function of variables and parameters.
variables (2D list of float, required): Values for the model’s variables at which to compute sensitivities.
parameters (2D list of float, required): Values for the model’s parameters at which to compute sensitivities.
variable_names (2D list of string, optional): Names of the variables (if not inferred from the model).
parameter_names (2D list of string, optional): Names of the parameters (if not inferred from the model).

The function returns a sensitivity matrix or vector (list[list[float]]) showing how outputs change with respect to parameters, or a string error message if the calculation fails or input is invalid.

Examples

Example 1: Logistic Growth Model

A biologist wants to see how carrying capacity (K), growth rate (r), and midpoint (t0) affect population at time t.

In Excel:


=SENSITIVITY_MATRIX("K/(1+ca.exp(-r*(t - t0)))", {5}, {100, 0.1, 10}, {"t"}, {"K", "r", "t0"})

Expected output (approximate):

K	r	t0
0.38	-117.50	-2.35

Example 2: Oscillatory System

An engineer studies how amplitude parameters affect a sinusoidal response.

In Excel:


=SENSITIVITY_MATRIX("ca.sin(a*x) + ca.cos(b*y)", {0.5, 1.0}, {2.0, 3.0}, {"x", "y"}, {"a", "b"})

Expected output (approximate):

a	b
0.27	-0.14

Python Code


import casadi as ca
 
def sensitivity_matrix(model, variables, parameters, variable_names=None, parameter_names=None):
    """
    Computes the sensitivity matrix of a model output with respect to parameters using CasADi.
 
    Args:
        model (str): Symbolic expression for the model output (e.g., "x**2 + a*y").
        variables (list[list[float]]): Values for the model's variables (e.g., [[1.0, 2.0]]).
        parameters (list[list[float]]): Values for the model's parameters (e.g., [[0.5, 1.5]]).
        variable_names (list[list[str]], optional): Names of the variables (e.g., [["x", "y"]]).
        parameter_names (list[list[str]], optional): Names of the parameters (e.g., [["a"]]).
 
    Returns:
        list[list[float]]: Sensitivity matrix or vector, or error message string.
 
    This example function is provided as-is without any representation of accuracy.
    """
    try:
        if not isinstance(model, str):
            return "model must be a string."
        if not (isinstance(variables, list) and len(variables) > 0 and isinstance(variables[0], list)):
            return "variables must be a 2D list of floats."
        if not (isinstance(parameters, list) and len(parameters) > 0 and isinstance(parameters[0], list)):
            return "parameters must be a 2D list of floats."
        var_vals = variables[0]
        param_vals = parameters[0]
        if variable_names is not None:
            if not (isinstance(variable_names, list) and len(variable_names) > 0 and isinstance(variable_names[0], list)):
                return "variable_names must be a 2D list of strings."
            var_names = variable_names[0]
        else:
            var_names = [f"x{i+1}" for i in range(len(var_vals))]
        if parameter_names is not None:
            if not (isinstance(parameter_names, list) and len(parameter_names) > 0 and isinstance(parameter_names[0], list)):
                return "parameter_names must be a 2D list of strings."
            param_names = parameter_names[0]
        else:
            param_names = [f"a{i+1}" for i in range(len(param_vals))]
        if len(var_names) != len(var_vals):
            return "Number of variable names and values must match."
        if len(param_names) != len(param_vals):
            return "Number of parameter names and values must match."
        sym_vars = [ca.MX.sym(name) for name in var_names]
        sym_params = [ca.MX.sym(name) for name in param_names]
        vars_dict = {name: sym_vars[i] for i, name in enumerate(var_names)}
        params_dict = {name: sym_params[i] for i, name in enumerate(param_names)}
        try:
            expr = eval(model, {**vars_dict, **params_dict, 'ca': ca})
        except Exception as e:
            return f"Invalid model expression: {str(e)}"
        S = ca.jacobian(expr, ca.vertcat(*sym_params))
        sens_func = ca.Function('sens_func', sym_vars + sym_params, [S])
        result_matrix = sens_func(*(var_vals + param_vals))
        if isinstance(result_matrix, ca.DM):
            return result_matrix.full().tolist()
        else:
            return "Error during CasADi calculation: Unexpected result type."
    except ca.CasadiException as e:
        return f"Error during CasADi calculation: {e}"
    except Exception as e:
        return str(e)

Live Notebook

Edit this function in a live notebook .