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:

ScaleParams contains the model scale parameters. These parameters are used to scale and nondimentionalize the Parameter of the other parameters classes according to their units attribute.
AtmosphericParams contains the atmospheric dynamical parameters.
AtmosphericTemperatureParams containing the atmosphere’s temperature and heat-exchange parameters.
OceanicParams contains the oceanic dynamical parameters.
OceanicTemperatureParams contains the ocean’s temperature and heat-exchange parameters.
GroundParams contains the ground dynamical parameters (e.g. orography).
GroundTemperatureParams contains the ground’s temperature and heat-exchange parameters.

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 and atmosphere [\(W m^{-2} K^{-1}\)]. Heat exchange scheme is disabled if None.

Type: None or Parameter

set_insolation(value, pos=None)[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.

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)[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.

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)[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.

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) – 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,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

Basis: General base class.
SymbolicBasis: Base class for symbolic functions basis.

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
>>> # 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

Main class

class qgs.params.parameter.Parameter(value, input_dimensional=True, units='', scale_object=None, description='', return_dimensional=False)[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.
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 units

The units of the dimensional value.

Type: str