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

ndarray(float)

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

ndarray(float)

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