Model configuration

We describe here the modules used to configure the model. Please read the User guide to learn how to use them.

The model’s parameters module

This module defines the main classes containing the model configuration parameters. The parameters are typically specified as Parameter objects.

There are seven types of parameters arranged in classes:

These parameters classes are regrouped into a global structure QgParams which also contains

  • spectral modes definition of the model

  • physical constants

  • parameters derived from the ones provided by the user

  • helper functions to initialize and parameterize the model

This global parameters structure is used by the other modules to construct the model’s ordinary differential equations.

Warning

If a model’s parameter is set to None, it is assumed to be disabled.

Description of the classes

class qgs.params.params.AtmosphericParams(scale_params, dic=None)[source]

Bases: Params

Class containing the atmospheric parameters.

Parameters:

  • scale_params (ScaleParams) – The scale parameters object of the model.

  • dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

kd

Atmosphere bottom friction coefficient [\(s^{-1}\)].

Type:

Parameter

kdp

Atmosphere internal friction coefficient [\(s^{-1}\)].

Type:

Parameter

sigma

Static stability of the atmosphere [\([m^2 s^{-2} Pa^{-2}\)].

Type:

Parameter

property sig0

Static stability of the atmosphere divided by 2.

Type:

Parameter

class qgs.params.params.AtmosphericTemperatureParams(scale_params, dic=None)[source]

Bases: Params

Class containing the atmospheric temperature parameters.

Parameters:

  • scale_params (ScaleParams) – The scale parameters object of the model.

  • dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

hd

Newtonian cooling coefficient. Newtonian cooling is disabled if None.

Type:

None or Parameter

thetas

Coefficients of the Newtonian cooling spectral decomposition (non-dimensional). Newtonian cooling is disabled if None.

Type:

None or ndarray(float)

gamma

Specific heat capacity of the atmosphere [\(J m^{-2} K^{-1}\)]. Heat exchange scheme is disabled if None.

Type:

None or Parameter

C

Spectral decomposition of the constant short-wave radiation of the atmosphere [\(W m^{-2}\)]. Heat exchange scheme is disabled if None.

Type:

None or ndarray(Parameter)

eps

Emissivity coefficient for the grey-body atmosphere Heat exchange scheme is disabled if None.

Type:

None or Parameter

T0

Stationary solution for the 0-th order atmospheric temperature [\(K\)]. Heat exchange scheme is disabled if None.

Type:

None or Parameter

sc

Ratio of surface to atmosphere temperature Heat exchange scheme is disabled if None.

Type:

None or Parameter

hlambda

Sensible + turbulent heat exchange between ocean/ground and atmosphere [\(W m^{-2} K^{-1}\)]. Heat exchange scheme is disabled if None.

Type:

None or Parameter

set_insolation(value, pos=None, dynamic_T=False)[source]

Function to define the spectral decomposition of the constant short-wave radiation of the atmosphere (insolation) \(C_{{\rm a}, i}\) (C).

Parameters:

  • value (float, int or iterable) – Value to set. If a scalar is given, the pos parameter should be provided to indicate which component to set. If an iterable is provided, create a vector of spectral decomposition parameters corresponding to it.

  • pos (int, optional) – Indicate in which component to set the value.

  • dynamic_T (bool, optional) – Whether or not the dynamic temperature scheme is activated.

set_thetas(value, pos=None)[source]

Function to define the spectral decomposition of the Newtonian cooling \(\theta^\star\) (thetas).

Parameters:

  • value (float, int or iterable) – Value to set. If a scalar is given, the pos parameter should be provided to indicate which component to set. If an iterable is provided, create a vector of spectral decomposition parameters corresponding to it.

  • pos (int, optional) – Indicate in which component to set the value.

class qgs.params.params.GroundParams(scale_params, dic=None)[source]

Bases: Params

Class containing the ground parameters

Parameters:

  • scale_params (ScaleParams) – The scale parameters object of the model.

  • dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

hk

Orography spectral decomposition coefficients (non-dimensional), an array of shape (nmod [0],). Orography is disabled (flat) if None.

Type:

None or ndarray(float)

orographic_basis

String to select which component basis modes to use to develop the orography in series. Can be either ‘atmospheric’ or ‘ground’. Default to ‘atmospheric’.

Type:

str

set_orography(value, pos=None, basis='atmospheric')[source]

Function to define the spectral decomposition of the orography profile \(h_k\) (hk).

Parameters:

  • value (float, int or iterable) – Value to set. If a scalar is given, the pos parameter should be provided to indicate which component to set. If an iterable is provided, create a vector of spectral decomposition parameters corresponding to it.

  • pos (int, optional) – Indicate in which component to set the value.

  • basis (str, optional) – Indicate which basis should be used to decompose the orography. Can be either atmospheric, oceanic or ground. Default to atmospheric.

class qgs.params.params.GroundTemperatureParams(scale_params, dic=None)[source]

Bases: Params

Class containing the ground temperature parameters

Parameters:

  • scale_params (ScaleParams) – The scale parameters object of the model.

  • dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

gamma

Specific heat capacity of the ground [\(J m^{-2} K^{-1}\)]. Heat exchange scheme is disabled if None.

Type:

None or Parameter

C

Spectral decomposition of the constant short-wave radiation of the ground [\(W m^{-2}\)]. Heat exchange scheme is disabled if None.

Type:

None or ndarray(Parameter)

T0

Stationary solution for the 0-th order ground temperature [\(K\)]. Heat exchange scheme is disabled if None.

Type:

None or Parameter

set_insolation(value, pos=None, dynamic_T=False)[source]

Function to define the decomposition of the constant short-wave radiation of the ground (insolation) \(C_{{\rm g}, i}\) (C).

Parameters:

  • value (float, int or iterable) – Value to set. If a scalar is given, the pos parameter should be provided to indicate which component to set. If an iterable is provided, create a vector of spectral decomposition parameters corresponding to it.

  • pos (int, optional) – Indicate in which component to set the value.

  • dynamic_T (bool, optional) – Whether or not the dynamic temperature scheme is activated.

class qgs.params.params.OceanicParams(scale_params, dic=None)[source]

Bases: Params

Class containing the oceanic parameters

Parameters:

  • scale_params (ScaleParams) – The scale parameters object of the model.

  • dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

gp

Reduced gravity in [\(m \, s^{-2}\)].

Type:

Parameter

r

Friction coefficient at the bottom of the ocean in [\(s^{-1}\)].

Type:

Parameter

h

Depth of the water layer of the ocean, in meters [\(m\)].

Type:

Parameter

d

The strength of the ocean-atmosphere mechanical coupling in [\(s^{-1}\)].

Type:

Parameter

class qgs.params.params.OceanicTemperatureParams(scale_params, dic=None)[source]

Bases: Params

Class containing the oceanic temperature parameters

Parameters:

  • scale_params (ScaleParams) – The scale parameters object of the model.

  • dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

gamma

Specific heat capacity of the ocean [\(J m^{-2} K^{-1}\)]. Heat exchange scheme is disabled if None.

Type:

None or Parameter

C

Spectral Decomposition of the constant short-wave radiation of the ocean [\(W m^{-2}\)]. Heat exchange scheme is disabled if None.

Type:

None or ndarray(Parameter)

T0

Stationary solution for the 0-th order oceanic temperature [\(K\)]. Heat exchange scheme is disabled if None.

Type:

None or Parameter

set_insolation(value, pos=None, dynamic_T=False)[source]

Function to define the spectral decomposition of the constant short-wave radiation of the ocean (insolation) \(C_{{\rm o}, i}\) (C).

Parameters:

  • value (float, int or iterable) – Value to set. If a scalar is given, the pos parameter should be provided to indicate which component to set. If an iterable is provided, create a vector of spectral decomposition parameters corresponding to it.

  • pos (int, optional) – Indicate in which component to set the value.

  • dynamic_T (bool, optional) – Whether or not the dynamic temperature scheme is activated.

class qgs.params.params.Params(dic=None)[source]

Bases: ABC

Base class for a model’s parameters container.

Parameters:

dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

load_from_file(filename, **kwargs)[source]

Function to load previously saved Params object with the method save_to_file().

Parameters:

  • filename (str) – The file name where the Params object was saved.

  • kwargs (dict) – Keyword arguments to pass to the pickle module method.

print_params()[source]

Print the parameters contained in the container.

save_to_file(filename, **kwargs)[source]

Function to save the Params object to a file with the pickle module.

Parameters:

  • filename (str) – The file name where to save the Params object.

  • kwargs (dict) – Keyword arguments to pass to the pickle module method.

set_params(dic)[source]

Set the specified parameters values.

Parameters:

dic (dict(float or Parameter)) – A dictionary with the parameters names and values to be assigned.

class qgs.params.params.QgParams(dic=None, scale_params=None, atmospheric_params=True, atemperature_params=True, oceanic_params=None, otemperature_params=None, ground_params=True, gtemperature_params=None, dynamic_T=False, T4=False)[source]

Bases: Params

General qgs parameters container.

Parameters:

  • dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

  • scale_params (None or ScaleParams, optional) – Scale parameters instance. If None, create a new ScaleParams instance. Default to None. Default to None.

  • atmospheric_params (bool, None or AtmosphericParams, optional) – Atmospheric parameters instance. If ‘True`, create a new AtmosphericParams instance. If None, atmospheric parameters are disabled. Default to True.

  • atemperature_params (bool, None or AtmosphericTemperatureParams, optional) – Atmospheric temperature parameters instance. If ‘True`, create a new AtmosphericTemperatureParams instance. If None, atmospheric temperature parameters are disabled. Default to True.

  • oceanic_params (bool, None or OceanicParams, optional) – Oceanic parameters instance. If ‘True`, create a new OceanicParams instance. If None, oceanic parameters are disabled. Default to None.

  • otemperature_params (bool, None or OceanicTemperatureParams, optional) – Oceanic temperature parameters instance. If ‘True`, create a new OceanicTemperatureParams instance. If None, oceanic temperature parameters are disabled. Default to None.

  • ground_params (bool, None or GroundParams, optional) – Ground parameters instance. If ‘True`, create a new GroundParams instance. If None, ground parameters are disabled. Default to True.

  • gtemperature_params (bool, None or GroundTemperatureParams, optional) – Ground temperature parameters instance. If ‘True`, create a new GroundTemperatureParams instance. If None, ground temperature parameters are disabled. Default to None.

  • dynamic_T (bool, optional) – Whether to use a fixed or a dynamical reference temperature if the heat exchange scheme is activated. Default to False.

  • T4 (bool, optional) – Use or not the \(T^4\) forcing for the evolution of the temperature field if the heat exchange is activated. Activate also the dynamical 0-th temperature. Default to False.

scale_params

Scale parameters instance.

Type:

ScaleParams

atmospheric_params

Atmospheric parameters instance. If None, atmospheric parameters are disabled.

Type:

None or AtmosphericParams

atemperature_params

Atmospheric temperature parameters instance. If None, atmospheric temperature parameters are disabled.

Type:

None or AtmosphericTemperatureParams

oceanic_params

Oceanic parameters instance. If None, oceanic parameters are disabled.

Type:

None or OceanicParams

ground_params

Ground parameters instance If None, ground parameters are disabled.

Type:

None or GroundParams

gotemperature_params

Ground or Oceanic temperature parameters instance. If None, ground and oceanic temperature parameters are disabled.

Type:

None, OceanicTemperatureParams or GroundTemperatureParams

time_unit

Dimensional unit of time to be used to represent the data.

Type:

float

rr

Gas constant of dry air in [\(J \, kg^{-1} \, K^{-1}\)].

Type:

Parameter

sb

Stefan-Boltzmann constant in [\(J \, m^{-2} \, s^{-1} \, K^{-4}\)].

Type:

float

dynamic_T

Whether to use a fixed or a dynamical reference temperature if the heat exchange scheme is activated. The atmospheric and possibly oceanic (or ground) basis must be reset if this parameter is changed.

Type:

bool

T4

Use or not the \(T^4\) forcing for the evolution of the temperature field if the heat exchange is activated.

Type:

bool

property Cpa

The \(C'_{{\rm a},i} = R C_{{\rm a},i} / (2 \gamma_{\rm a} L^2 f_0^3)\) parameter.

Type:

float

property Cpgo

The \(C'_{{\rm g/\rm o},i} = R C_{{\rm g/\rm o},i} / (\gamma_{\rm g/\rm o} L^2 f_0^3)\) parameter.

Type:

float

property G

The \(G = - L^2/L_R^2\) parameter.

Type:

float

property LR

Reduced Rossby deformation radius \(L_\text{R} = \sqrt{g' \, h } / f_0\) .

Type:

float

property LSBpa

Long wave radiation lost by atmosphere to space & ground/ocean \(S_{B,{\rm a}} = 8\,\epsilon_{\rm a}\, \sigma_B \, T_{{\rm a},0}^3 / (\gamma_{\rm a} f_0)\) in the linearized temperature model equations.

Type:

float

property LSBpgo

Long wave radiation from ground/ocean absorbed by atmosphere \(S_{B,{\rm g/\rm o}} = 2\,\epsilon_{\rm a}\, \sigma_B \, T_{{\rm a},0}^3 / (\gamma_{\rm a} f_0)\) in the linearized temperature model equations.

Type:

float

property Lpa

The \(\lambda'_{\rm a} = \lambda / (\gamma_{\rm a} f_0)\) parameter.

Type:

float

property Lpgo

The \(\lambda'_{{\rm g/\rm o}} = \lambda/(\gamma_{\rm g/\rm o} f_0)\) parameter.

Type:

float

property T4LSBpa

Long wave radiation lost by atmosphere to space & ground/ocean \(S_{B,{\rm a}} = 16 \,\epsilon_{\rm a}\, \sigma_B \, L^6 \, f_0^5 / (\gamma_{\rm a} R^3)\) in the \(T^4\) model equations.

Type:

float

property T4LSBpgo

Long wave radiation from ground/ocean absorbed by atmosphere \(S_{B,{\rm g/\rm o}} = \frac{1}{2} \, \epsilon_{\rm a}\, \sigma_B \, L^6 \, f_0^5 / (\gamma_{\rm a} R^3)\) in the \(T^4\) model equations.

Type:

float

property T4sbpa

Long wave radiation from atmosphere absorbed by ground/ocean \(s_{B,{\rm a}} = 16 \,\epsilon_{\rm a}\, \sigma_B \, L^6 \, f_0^5 / (\gamma_{\rm g/\rm o} R^3)\) in the \(T^4\) model equations.

Type:

float

property T4sbpgo

Long wave radiation lost by ground/ocean to the atmosphere \(s_{B,{\rm g/\rm o}} = \sigma_B \, L^6 \, f_0^5 / (\gamma_{\rm g/\rm o} R^3)\) in the \(T^4\) model equations.

Type:

float

property ablocks

Spectral blocks detailing the model’s atmospheric modes \(x\)- and \(y\)-wavenumber. Array of shape (nmod [0], 2).

Type:

ndarray(int)

property atmospheric_basis

The atmospheric basis of functions used to project the PDEs onto.

Type:

Basis

property dimensional_time

Return the conversion factor between the non-dimensional time and the dimensional time unit specified in time_unit

Type:

float

property gblocks

Spectral blocks detailing the model’s ground modes \(x\)-and \(y\)-wavenumber. Array of shape (nmod [1], 2).

Type:

ndarray(int)

property geopotential_scaling

Dimensional scaling of the geopotential height.

Type:

float

get_variable_units(i)[source]

Return the units of a model’s variable as a string containing latex symbols.

Parameters:

i (int) – The number of the variable.

Returns:

The string with the units of the variable.

Return type:

str

property ground_basis

The ground basis of functions used to project the PDEs onto.

Type:

Basis

property latex_components_units

The units of every model’s components variables, as a list of latex strings.

Type:

list(str)

property latex_var_string

List of model’s variable names, ready for use in latex.

Type:

list(str)

property ndim

Total number of variables of the model.

Type:

int

property nmod

Atmospheric and ground/oceanic number of modes.

Type:

(int, int)

property number_of_variables

Number of variables per component.

Type:

list(int)

property oblocks

Spectral blocks detailing the model’s oceanic modes \(x\)-and \(y\)-wavenumber. Array of shape (nmod [1], 2).

Type:

ndarray(int)

property oceanic_basis

The oceanic basis of functions used to project the PDEs onto.

Type:

Basis

print_params()[source]

Print all the parameters in the container.

property sbpa

Long wave radiation from atmosphere absorbed by ground/ocean \(s_{B,{\rm a}} = 4\,\epsilon_{\rm a}\, \sigma_B \, T_{{\rm a},0}^3 / (\gamma_{\rm g/\rm o} f_0)\) in the linearized temperature model equations.

Type:

float

property sbpgo

Long wave radiation lost by ground/ocean to the atmosphere \(s_{B,{\rm g/\rm o}} = 4\,\sigma_B \, T_{{\rm a},0}^3 / (\gamma_{\rm g/\rm o} f_0)\) in the linearized temperature model equations.

Type:

float

set_atmospheric_channel_fourier_modes(nxmax, nymax, auto=False, mode='analytic')[source]

Function to configure and set the basis for contiguous spectral blocks of atmospheric modes on a channel.

Parameters:

  • nxmax (int) – Maximum x-wavenumber to fill the spectral block up to.

  • nymax (int) – Maximum \(y\)-wavenumber to fill the spectral block up to.

  • auto (bool, optional) – Automatically instantiate the parameters container needed to describe the atmospheric models parameters. Default is False.

  • mode (str, optional) – Mode to set the inner products: Either analytic or symbolic: analytic for inner products computed with formula or symbolic using Sympy. Default to analytic.

Examples

>>> from qgs.params.params import QgParams
>>> q = QgParams()
>>> q.set_atmospheric_channel_fourier_modes(2, 2)
>>> q.ablocks
array([[1, 1],
       [1, 2],
       [2, 1],
       [2, 2]])
set_atmospheric_modes(basis, auto=False)[source]

Function to configure the atmospheric modes (basis functions) used to project the PDEs onto.

Parameters:

  • basis (Basis) – Basis object containing the definition of the atmospheric modes.

  • auto (bool, optional) – Automatically instantiate the parameters container needed to describe the atmospheric models parameters. Default is False.

Examples

>>> from qgs.params.params import QgParams
>>> from qgs.basis.fourier import contiguous_channel_basis
>>> q = QgParams()
>>> atm_basis = contiguous_channel_basis(2, 2, 1.5)
>>> q.set_atmospheric_modes(atm_basis)
>>> q.atmospheric_basis
[sqrt(2)*cos(y), 2*sin(y)*cos(n*x), 2*sin(y)*sin(n*x), sqrt(2)*cos(2*y), 2*sin(2*y)*cos(n*x), 2*sin(2*y)*sin(n*x), 2*sin(y)*cos(2*n*x), 2*sin(y)*sin(2*n*x), 2*sin(2*y)*cos(2*n*x), 2*sin(2*y)*sin(2*n*x)]
set_ground_channel_fourier_modes(nxmax=None, nymax=None, auto=True, mode='analytic')[source]

Function to configure and set the basis for contiguous spectral blocks of ground modes on a channel.

Parameters:

  • nxmax (int, optional) – Maximum x-wavenumber to fill the spectral block up to. Default to None.

  • nymax (int, optional) – Maximum \(y\)-wavenumber to fill the spectral block up to. Default to None.

  • auto (bool, optional) – Automatically instantiate the parameters container needed to describe the atmospheric models parameters. Default is True.

  • mode (str, optional) – Mode to set the inner products: Either analytic or symbolic. analytic for inner products computed with formula or symbolic using Sympy. Default to analytic.

Notes

If both nxmax and nymax are None, default to the atmospheric basis configuration if available.

Examples

>>> from qgs.params.params import QgParams
>>> q = QgParams()
>>> q.set_atmospheric_channel_fourier_modes(2,4)
>>> q.set_ground_channel_fourier_modes()
>>> q.gblocks
array([[1, 1],
       [1, 2],
       [1, 3],
       [1, 4],
       [2, 1],
       [2, 2],
       [2, 3],
       [2, 4]])
set_ground_modes(basis=None, auto=True)[source]

Function to configure the ground modes (basis functions) used to project the PDEs onto.

Parameters:

  • basis (None or Basis, optional) – Basis object containing the definition of the ground modes. If None, use the basis of the atmosphere. Default to None.

  • auto (bool, optional) – Automatically instantiate or not the parameters container needed to describe the ground models parameters. Default is True.

Examples

>>> from qgs.params.params import QgParams
>>> from qgs.basis.fourier import contiguous_channel_basis, contiguous_basin_basis
>>> q = QgParams()
>>> atm_basis = contiguous_channel_basis(2, 2, 1.5)
>>> q.set_atmospheric_modes(atm_basis)
>>> q.set_ground_modes()
>>> q.ground_basis
[sqrt(2)*cos(y), 2*sin(y)*cos(n*x), 2*sin(y)*sin(n*x), sqrt(2)*cos(2*y), 2*sin(2*y)*cos(n*x), 2*sin(2*y)*sin(n*x), 2*sin(y)*cos(2*n*x), 2*sin(y)*sin(2*n*x), 2*sin(2*y)*cos(2*n*x), 2*sin(2*y)*sin(2*n*x)]
set_oceanic_basin_fourier_modes(nxmax, nymax, auto=True, mode='analytic')[source]

Function to configure and set the basis for contiguous spectral blocks of oceanic modes on a closed basin.

Parameters:

  • nxmax (int) – Maximum x-wavenumber to fill the spectral block up to.

  • nymax (int) – Maximum \(y\)-wavenumber to fill the spectral block up to.

  • auto (bool, optional) – Automatically instantiate the parameters container needed to describe the atmospheric models parameters. Default is True.

  • mode (str, optional) – Mode to set the inner products: Either analytic or symbolic. analytic for inner products computed with formula or symbolic using Sympy. Default to analytic.

Examples

>>> from qgs.params.params import QgParams
>>> q = QgParams()
>>> q.set_atmospheric_channel_fourier_modes(2, 2)
>>> q.set_oceanic_basin_fourier_modes(2, 4)
>>> q.oblocks
array([[1, 1],
       [1, 2],
       [1, 3],
       [1, 4],
       [2, 1],
       [2, 2],
       [2, 3],
       [2, 4]])
set_oceanic_modes(basis, auto=True)[source]

Function to configure the oceanic modes (basis functions) used to project the PDEs onto.

Parameters:

  • basis (Basis) – Basis object containing the definition of the oceanic modes.

  • auto (bool, optional) – Automatically instantiate or not the parameters container needed to describe the oceanic models parameters. Default is True.

Examples

>>> from qgs.params.params import QgParams
>>> from qgs.basis.fourier import contiguous_channel_basis, contiguous_basin_basis
>>> q = QgParams()
>>> atm_basis = contiguous_channel_basis(2, 2, 1.5)
>>> oc_basis = contiguous_basin_basis(2, 4, 1.5)
>>> q.set_atmospheric_modes(atm_basis)
>>> q.set_oceanic_modes(oc_basis)
>>> q.oceanic_basis
[2*sin(y)*sin(0.5*n*x), 2*sin(2*y)*sin(0.5*n*x), 2*sin(3*y)*sin(0.5*n*x), 2*sin(4*y)*sin(0.5*n*x), 2*sin(y)*sin(1.0*n*x), 2*sin(2*y)*sin(1.0*n*x), 2*sin(3*y)*sin(1.0*n*x), 2*sin(4*y)*sin(1.0*n*x)]
set_params(dic)[source]

Set the specified parameters values.

Parameters:

dic (dict(float or Parameter)) – A dictionary with the parameters names and values to be assigned.

property streamfunction_scaling

Dimensional scaling of the streamfunction fields.

Type:

float

property temperature_scaling

Dimensional scaling of the temperature fields.

Type:

float

property var_string

List of model’s variable names.

Type:

list(str)

property variables_range

List of the variables indices upper bound per component.

Type:

list(int)

class qgs.params.params.ScaleParams(dic=None)[source]

Bases: Params

Class containing the model scales parameters.

Parameters:

dic (dict(float or Parameter), optional) – A dictionary with the parameters names and values to be assigned.

scale

The characteristic meridional space scale, \(L_y = \pi \, L\), in meters [\(m\)].

Type:

Parameter

f0

Coriolis parameter, in [\(s^{-1}\)].

Type:

Parameter

n

Model domain aspect ratio, \(n = 2 L_y/L_x\) .

Type:

Parameter

rra

Earth radius, in meters [\(m\)].

Type:

Parameter

phi0_npi

Latitude expressed in fraction of \(\pi\) .

Type:

Parameter

deltap

Difference of pressure between the center of the two atmospheric layers, in [\(Pa\)].

Type:

Parameter

property L

Typical length scale \(L\) of the model, in meters [\(m\)].

Type:

Parameter

property L_x

The zonal extent \(L_x = 2 \pi \, L / n\) of the model’s domain, in meters [\(m\)].

Type:

Parameter

property L_y

The meridional extent \(L_y = \pi \, L\) of the model’s domain, in meters [\(m\)].

Type:

Parameter

property beta

The meridional gradient of the Coriolis parameter at \(\phi_0\), expressed in [\(m^{-1} s^{-1}\)].

Type:

Parameter

property phi0

The reference latitude \(\phi_0\) at the center of the domain, expressed in radians [\(rad\)].

Type:

Parameter

Basis definition module (base class)

Abstract base classes defining the functions (modes) of the basis of the model and used to configure it. (see Projecting the equations on a set of basis functions).

Description of the classes

Warning

These are abstract base class, they must be subclassed to create new basis!

class qgs.basis.base.Basis[source]

Bases: ABC

General base class for a basis of functions.

functions

List of functions of the basis.

Type:

list

class qgs.basis.base.NumericBasis[source]

Bases: Basis

General base class for a basis of numeric functions.

num_functions()[source]

Return the basis functions with as python callable.

Returns:

List of callable basis functions

Return type:

list(callable)

class qgs.basis.base.SymbolicBasis[source]

Bases: Basis

General base class for a basis of symbolic functions.

substitutions

List of 2-tuples containing the substitutions to be made with the functions. The 2-tuples contain first a Sympy expression and then the value to substitute.

Type:

list(tuple)

.. _Sympy
Type:

https://www.sympy.org/

derivative(symbol, order=1)[source]

Return the basis functions differentiated with respect to symbol as a new basis.

Parameters:

  • symbol (Sympy symbol) – The symbol with respect to which the basis is to be differentiated.

  • order (int, optional) – The order of the derivative. Default to first order.

Returns:

A new basis object with the differentiated basis function.

Return type:

SymbolicBasis

num_functions(extra_subs=None)[source]

Return the basis functions with as python callable.

Parameters:

extra_subs (list(tuple), optional) – List of 2-tuples containing extra substitutions to be made with the functions before transforming them into python callable. The 2-tuples contain first a Sympy expression and then the value to substitute.

Returns:

List of callable basis functions

Return type:

list(callable)

subs_functions(extra_subs=None)[source]

Return the basis functions with the substitutions stored in the object being applied.

Parameters:

extra_subs (list(tuple), optional) – List of 2-tuples containing extra substitutions to be made with the functions. The 2-tuples contain first a Sympy expression and then the value to substitute.

Returns:

List of the substituted basis functions

Return type:

list

x_derivative(order=1)[source]

Return the basis functions differentiated with respect to the \(x\) coordinate.

Parameters:

order (int, optional) – The order of the derivative. Default to first order.

Returns:

A new basis object with the differentiated basis function.

Return type:

SymbolicBasis

y_derivative(order=1)[source]

SymbolicBasis: Basis functions differentiated with respect to the \(y\) coordinate.

Parameters:

order (int, optional) – The order of the derivative. Default to first order.

Returns:

A new basis object with the differentiated basis function.

Return type:

SymbolicBasis

Fourier Basis definition module

Classes and functions defining Fourier basis of functions (Fourier modes) and used to configure the model. (see Projecting the equations on a set of basis functions).

Description of the classes

  • ChannelFourierBasis: Fourier basis defined on a zonally perdiodic channel, with no-flux boundary conditions in the meridional direction \(y\).

  • BasinFourierBasis: Fourier basis defined on a closed basin, with no-flux boundary conditions in both the zonal and meridional direction \(x\) and \(y\).

class qgs.basis.fourier.BasinFourierBasis(spectral_blocks, aspect_ratio)[source]

Bases: SymbolicBasis

Fourier basis defined on a closed basin, with no-flux boundary conditions in both the zonal and meridional direction \(x\) and \(y\).

Parameters:

  • spectral_blocks (ndarray(int)) – Spectral blocks detailing the modes \(x\)- and \(y\)-wavenumber. Array of shape (nblocks, 2), where nblocks is the number of spectral blocks.

  • aspect_ratio (float) – Spatial domain aspect ratio, \(n = 2 L_y/L_x\) .

class qgs.basis.fourier.ChannelFourierBasis(spectral_blocks, aspect_ratio)[source]

Bases: SymbolicBasis

Fourier basis defined on a zonally perdiodic channel, with no-flux boundary conditions in the meridional direction \(y\).

Parameters:

  • spectral_blocks (ndarray(int)) – Spectral blocks detailing the modes \(x\)- and \(y\)-wavenumber. Array of shape (nblocks, 2), where nblocks is the number of spectral blocks.

  • aspect_ratio (float) – Spatial domain aspect ratio, \(n = 2 L_y/L_x\) .

class qgs.basis.fourier.WaveNumber(function_type, P, M, H, nx, ny)[source]

Bases: object

Class to define model base functions wavenumber. The basis function available are:

  • ‘A’ for a function of the form \(F^A_{P} (x, y) = \sqrt{2}\, \cos(P y) = \sqrt{2}\, \cos(n_y\, y)\)

  • ‘K’ for a function of the form \(F^K_{M,P} (x, y) = 2\cos(M nx)\, \sin(P y) = 2\cos(n_x\, n\, x)\, \sin(n_y\, y)\)

  • ‘L’ for a function of the form \(F^L_{H,P} (x, y) = 2\sin(H nx)\, \sin(P y) = 2\sin(n_x\, n \,x)\, \sin(n_y\, y)\)

where \(x\) and \(y\) are the nondimensional model’s domain coordinates (see Projecting the equations on a set of basis functions).

Parameters:

  • function_type (str) – One character string to define the type of basis function. It can be ‘A’, ‘K’ or ‘L’.

  • P (int) – The \(y\) wavenumber integer.

  • M (int) – The \(x\) wavenumber integer.

  • H (int) – The \(x\) wavenumber integer.

  • nx (float) – The \(x\) wavenumber.

  • ny (float) – The \(y\) wavenumber.

type

One character string to define the type of basis function. It can be ‘A’, ‘K’ or ‘L’.

Type:

str

P

The \(y\) wavenumber integer.

Type:

int

M

The \(x\) wavenumber integer.

Type:

int

H

The \(x\) wavenumber integer.

Type:

int

nx

The \(x\) wavenumber.

Type:

float

ny

The \(y\) wavenumber.

Type:

float

qgs.basis.fourier.basin_wavenumbers(spectral_blocks)[source]

Functions that returns the WaveNumber objects corresponding to a given list of spectral blocks for a closed basin spatial domain.

Parameters:

spectral_blocks (ndarray(int)) – Spectral blocks detailing the modes \(x\)- and \(y\)-wavenumber. Array of shape (nblocks, 2), where nblocks is the number of spectral blocks.

Returns:

The array of wavenumber objects corresponding to the given spectral blocks.

Return type:

ndarray(WaveNumber)

qgs.basis.fourier.channel_wavenumbers(spectral_blocks)[source]

Functions that returns the WaveNumber objects corresponding to a given list of spectral blocks for a channel-like spatial domain.

Parameters:

spectral_blocks (ndarray(int)) – Spectral blocks detailing the modes \(x\)- and \(y\)-wavenumber. Array of shape (nblocks, 2), where nblocks is the number of spectral blocks.

Returns:

The array of wavenumber objects corresponding to the given spectral blocks.

Return type:

ndarray(WaveNumber)

qgs.basis.fourier.contiguous_basin_basis(nxmax, nymax, aspect_ratio)[source]

Function that returns the basis for contiguous spectral blocks of modes on a closed basin.

Parameters:

  • nxmax (int) – Maximum x-wavenumber to fill the spectral block up to.

  • nymax (int) – Maximum \(y\)-wavenumber to fill the spectral block up to.

  • aspect_ratio (float) – Spatial domain aspect ratio, \(n = 2 L_y/L_x\) .

Returns:

The closed basin contiguous basis up to the specified spectral truncation.

Return type:

BasinFourierBasis

qgs.basis.fourier.contiguous_channel_basis(nxmax, nymax, aspect_ratio)[source]

Function that returns the basis for contiguous spectral blocks of modes on a channel.

Parameters:

  • nxmax (int) – Maximum x-wavenumber to fill the spectral block up to.

  • nymax (int) – Maximum \(y\)-wavenumber to fill the spectral block up to.

  • aspect_ratio (float) – Spatial domain aspect ratio, \(n = 2 L_y/L_x\) .

Returns:

The channel contiguous basis up to the specified spectral truncation.

Return type:

ChannelFourierBasis

qgs.basis.fourier.fourier_functions(wave_number)[source]

Function that return Fourier modes expressions:

  • ‘A’ for a function of the form \(F^A_{P} (x, y) = \sqrt{2}\, \cos(P y) = \sqrt{2}\, \cos(n_y\, y)\)

  • ‘K’ for a function of the form \(F^K_{M,P} (x, y) = 2\cos(M nx)\, \sin(P y) = 2\cos(n_x\, n\, x)\, \sin(n_y\, y)\)

  • ‘L’ for a function of the form \(F^L_{H,P} (x, y) = 2\sin(H nx)\, \sin(P y) = 2\sin(n_x\, n \,x)\, \sin(n_y\, y)\)

Parameters:

wave_number (WaveNumber) – The wavenumber and type information of the mode to be returned.

Returns:

  • Sympy expression – Symbolic expression of the mode.

  • .. _Sympy (https://www.sympy.org/)

Parameter module

This module contains the basic parameter class to hold model’s parameters values. It allows to manipulate dimensional and nondimensional parameter easily.

Examples

>>> from qgs.params.params import ScaleParams
>>> from qgs.params.parameter import Parameter, ParametersArray
>>> import numpy as np
>>> # defining a scale object to help Parameter compute the nondimensionalization
>>> sc = ScaleParams()
>>> # creating a parameter initialized with a nondimensional value but returning a
>>> # dimensional one when called
>>> sigma = Parameter(0.2e0, input_dimensional=False, scale_object=sc,
...                   units='[m^2][s^-2][Pa^-2]',
...                   description="static stability of the atmosphere",
...                   return_dimensional=True)
>>> sigma
2.1581898457499433e-06
>>> sigma.nondimensional_value
0.2
>>> sigma.return_dimensional
True
>>> # creating a parameter initialized with a dimensional value but returning a
>>> # nondimensional one when called
>>> sigma = Parameter(2.1581898457499433e-06, input_dimensional=True, scale_object=sc,
...                   units='[m^2][s^-2][Pa^-2]',
...                   description="static stability of the atmosphere",
...                   return_dimensional=False)
>>> sigma
0.2
>>> sigma.dimensional_value
2.1581898457499433e-06
>>> sigma.return_dimensional
False
>>> # creating a parameters array initialized with a nondimensional values and returning
>>> # nondimensional ones when called
>>> s = ParametersArray(np.array([[0.1,0.2],[0.3,0.4]]), input_dimensional=False, scale_object=sc, units='[s^-1]',
...                     description="atmosphere bottom friction coefficient")
>>> s
ArrayParameters([[0.1, 0.2],
                 [0.3, 0.4]], dtype=object)
>>> # dimensional values can also be retrieved with
>>> s.dimensional_values
array([[1.0320000000000001e-05, 2.0640000000000002e-05],
       [3.096e-05, 4.1280000000000005e-05]], dtype=object)
>>> # you can also ask for the dimensional value of one particular value of the array
>>> s[0,0]
0.1
>>> s[0,0].dimensional_value
1.0320000000000001e-05

Main class

class qgs.params.parameter.Parameter(value, input_dimensional=True, units='', scale_object=None, description='', symbol=None, return_dimensional=False, symbolic_expression=None)[source]

Bases: float

Base class of model’s parameter.

Parameters:

  • value (float) – Value of the parameter.

  • input_dimensional (bool, optional) – Specify whether the value provided is dimensional or not. Default to True.

  • units (str, optional) – The units of the provided value. Used to compute the conversion between dimensional and nondimensional value. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’. Empty by default.

  • scale_object (ScaleParams, optional) – A scale parameters object to compute the conversion between dimensional and nondimensional value. None by default. If None, cannot transform between dimensional and nondimentional value.

  • description (str, optional) – String describing the parameter.

  • symbol (Symbol, optional) – A Sympy symbol to represent the parameter in symbolic expressions.

  • symbolic_expression (Expr, optional) – A Sympy expression to represent a relationship to other parameters.

  • return_dimensional (bool, optional) – Defined if the value returned by the parameter is dimensional or not. Default to False.

Notes

Parameter is immutable. Once instantiated, it cannot be altered. To create a new parameter, one must re-instantiate it.

Warning

If no scale_object argument is provided, cannot transform between the dimensional and nondimentional value !

property description

Description of the parameter.

Type:

str

property dimensional_value

Returns the dimensional value.

Type:

float

property input_dimensional

Indicate if the provided value is dimensional or not.

Type:

bool

property nondimensional_value

Returns the nondimensional value.

Type:

float

property return_dimensional

Indicate if the returned value is dimensional or not.

Type:

bool

property symbol

Returns the symbol of the parameter.

Type:

Symbol

property symbolic_expression

Returns the symbolic expression of the parameter.

Type:

Expr

property units

The units of the dimensional value.

Type:

str

class qgs.params.parameter.ParametersArray(values, input_dimensional=True, units='', scale_object=None, description='', symbols=None, symbolic_expressions=None, return_dimensional=False)[source]

Bases: ndarray

Base class of model’s array of parameters.

Parameters:

  • values (list(float) or ndarray(float) or list(Parameter) or ndarray(Parameter) or list(ScalingParameter) or ndarray(ScalingParameter)) – Values of the parameter array.

  • input_dimensional (bool, optional) – Specify whether the value provided is dimensional or not. Default to True.

  • units (str, optional) – The units of the provided value. Used to compute the conversion between dimensional and nondimensional value. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’. Empty by default.

  • scale_object (ScaleParams, optional) – A scale parameters object to compute the conversion between dimensional and nondimensional value. None by default. If None, cannot transform between dimensional and nondimentional value.

  • description (str or list(str) or array(str), optional) – String or an iterable of strings, describing the parameters. If an iterable, should have the same length or shape as values.

  • symbols (Symbol or list(Symbol) or ndarray(Symbol), optional) – A Sympy symbol or an iterable of symbols, to represent the parameters in symbolic expressions. If an iterable, should have the same length or shape as values.

  • symbolic_expressions (Expr or list(Expr) or ndarray(Expr), optional) – A Sympy expression or an iterable of expressions, to represent a relationship to other parameters. If an iterable, should have the same length or shape as values.

  • return_dimensional (bool, optional) – Defined if the value returned by the parameter is dimensional or not. Default to False.

Warning

If no scale_object argument is provided, cannot transform between the dimensional and nondimensional value !

property descriptions

Description of the parameters in the array.

Type:

ndarray(str)

property dimensional_values

Returns the dimensional value.

Type:

float

property input_dimensional

Indicate if the provided value is dimensional or not.

Type:

bool

property nondimensional_values

Returns the nondimensional value.

Type:

float

property return_dimensional

Indicate if the returned value is dimensional or not.

Type:

bool

property symbolic_expressions

Returns the symbolic expressions of the parameters in the array.

Type:

ndarray(Expr)

property symbols

Returns the symbol of the parameters in the array.

Type:

ndarray(Symbol)

property units

The units of the dimensional value.

Type:

str

class qgs.params.parameter.ScalingParameter(value, units='', description='', dimensional=False, symbol=None, symbolic_expression=None)[source]

Bases: float

Class of model’s dimension parameter.

Parameters:

  • value (float) – Value of the parameter.

  • units (str, optional) – The units of the provided value. Used to compute the conversion between dimensional and nondimensional value. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’. Empty by default.

  • description (str, optional) – String describing the parameter.

  • dimensional (bool, optional) – Indicate if the value of the parameter is dimensional or not. Default to True.

  • symbol (Symbol, optional) – A Sympy symbol to represent the parameter in symbolic expressions.

  • symbolic_expression (Expr, optional) – A Sympy expression to represent a relationship to other parameters.

Notes

Parameter is immutable. Once instantiated, it cannot be altered. To create a new parameter, one must re-instantiate it.

property description

Description of the parameter.

Type:

str

property dimensional

Indicate if the returned value is dimensional or not.

Type:

bool

property symbol

Returns the symbol of the parameter.

Type:

Symbol

property symbolic_expression

Returns the symbolic expression of the parameter.

Type:

Expr

property units

The units of the dimensional value.

Type:

str