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
qgs.functions.sparse_mul.sparse_mul4(coo, value, vec_a, vec_b, vec_c)[source]

Sparse multiplication of a rank-5 tensor with three vectors: $$A_{i, j} = {\displaystyle \sum_{k,l,m=0}^{\mathrm{ndim}}} \, \mathcal{T}_{i,j,k,l, m} \, a_k \, b_l \, c_m$$

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, 5), 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,).

• vec_c (ndarray(float)) – The vector $$c_l$$ 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_mul5(coo, value, vec_a, vec_b, vec_c, vec_d)[source]

Sparse multiplication of a rank-5 tensor with four vectors: $$v_i = {\displaystyle \sum_{j,k,l,m=0}^{\mathrm{ndim}}} \, \mathcal{T}_{i,j,k,l,m} \, a_j \, b_k \, c_l \, d_m$$

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
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_atmo_thermo_tendencies(params, return_atmo_thermo_tensor=False)[source]

Returns a function which return a part of the atmospheric thermodynamic tendencies useful for computing the vertical wind.

Parameters
• params (QgParams) – The parameters fully specifying the model configuration.

• return_atmo_thermo_tensor (bool) – If True, return the tendencies tensor of these tencencies. Default to False.

Returns

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

• atmo_thermo_tensor (AtmoThermoTensor) – If return_atmo_thermo_tensor is True, the tendencies tensor of the system.

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