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: qgs.params.params.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: qgs.params.params.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: qgs.params.params.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: qgs.params.params.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: qgs.params.params.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: qgs.params.params.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.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)[source]

Bases: qgs.params.params.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.

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

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

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

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

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

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)

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

Bases: qgs.params.params.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.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: qgs.basis.base.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: qgs.basis.base.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

property x_derivative

Basis functions differentiated with respect to \(x\) coordinate.

Type

SymbolicBasis

property y_derivative

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

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: qgs.basis.base.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: qgs.basis.base.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