# Functions module

The functions module contains utility functions used by the model, as well as some high-level functions to handle it.

## Sparse matrix operation module

This module supports operations and functions on the sparse tensors defined in the QgsTensor objects.

qgs.functions.sparse_mul.sparse_mul2(coo, value, vec)[source]

Sparse multiplication of a tensor with one vector: $$A_{i,j} = {\displaystyle \sum_{k=0}^{\mathrm{ndim}}} \, \mathcal{T}_{i,j,k} \, a_k$$

Warning

It is a Numba-jitted function, so it cannot take a sparse.COO sparse tensor directly. The tensor coordinates list and values must be provided separately by the user.

In principle, this will be solved later in sparse, see https://github.com/pydata/sparse/issues/378.

Parameters
• coo (ndarray(int)) – A 2D array of shape (n_elems, 3), a list of n_elems tensor coordinates corresponding to each value provided.

• value (ndarray(float)) – A 1D array of shape (n_elems,), a list of value in the tensor

• vec (ndarray(float)) – The vector $$a_k$$ to contract the tensor with. Must be of shape (ndim + 1,).

Returns

The matrix $$A_{i,j}$$, of shape (ndim + 1, ndim + 1).

Return type
qgs.functions.sparse_mul.sparse_mul3(coo, value, vec_a, vec_b)[source]

Sparse multiplication of a tensor with two vectors: $$v_i = {\displaystyle \sum_{j,k=0}^{\mathrm{ndim}}} \, \mathcal{T}_{i,j,k} \, a_j \, b_k$$

Warning

It is a Numba-jitted function, so it cannot take a sparse.COO sparse tensor directly. The tensor coordinates list and values must be provided separately by the user.

In principle, this will be solved later in sparse, see https://github.com/pydata/sparse/issues/378.

Parameters
• coo (ndarray(int)) – A 2D array of shape (n_elems, 3), a list of n_elems tensor coordinates corresponding to each value provided.

• value (ndarray(float)) – A 1D array of shape (n_elems,), a list of value in the tensor

• vec_a (ndarray(float)) – The vector $$a_j$$ to contract the tensor with. Must be of shape (ndim + 1,).

• vec_b (ndarray(float)) – The vector $$b_k$$ to contract the tensor with. Must be of shape (ndim + 1,).

Returns

The vector $$v_i$$, of shape (ndim + 1,).

Return type

## Tendencies definition module

This module provides functions to create the tendencies functions of the model, based on its parameters.

qgs.functions.tendencies.create_tendencies(params, return_inner_products=False, return_qgtensor=False)[source]

Function to handle the inner products and tendencies tensors construction. Returns the tendencies function $$\boldsymbol{f}$$ determining the model’s ordinary differential equations:

$\dot{\boldsymbol{x}} = \boldsymbol{f}(\boldsymbol{x})$

which is for the model’s integration.

It returns also the linearized tendencies $$\boldsymbol{\mathrm{J}} \equiv \boldsymbol{\mathrm{D}f} = \frac{\partial \boldsymbol{f}}{\partial \boldsymbol{x}}$$ (Jacobian matrix) which are used by the tangent linear model:

$\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(\boldsymbol{x}) \cdot \boldsymbol{\delta x}$
Parameters
• params (QgParams) – The parameters fully specifying the model configuration.

• return_inner_products (bool) – If True, return the inner products of the model. Default to False.

• return_qgtensor (bool) – If True, return the tendencies tensor of the model. Default to False.

Returns

• f (callable) – The numba-jitted tendencies function.

• Df (callable) – The numba-jitted linearized tendencies function.

• inner_products ((AtmosphericInnerProducts, OceanicInnerProducts)) – If return_inner_products is True, the inner products of the system.

• qgtensor (QgsTensor) – If return_qgtensor is True, the tendencies tensor of the system.

## Utility functions module

This module has some useful functions for the model.

qgs.functions.util.normalize_matrix_columns(a)[source]

Numba-jitted function to normalize the columns of a 2D array to one.

Parameters

a (ndarray) – The 2D array to column-normalize.

Returns

The normalized array.

Return type

ndarray

qgs.functions.util.reverse(a)[source]

Numba-jitted function to reverse a 1D array.

Parameters

a (ndarray) – The 1D array to reverse.

Returns

The reversed array.

Return type

ndarray

qgs.functions.util.solve_triangular_matrix(a, b)[source]

Solve a triangular linear matrix equation $$ax = b$$.

Parameters
• a (ndarray) – The 2D array $$a$$.

• b (ndarray) – The 2D array $$b$$.

Returns

The 2D array of solution $$x$$.

Return type

ndarray