Basis module

This module contains the code related to the definition of basis of functions in the models.

Basis definition module (base class)

Abstract base classes defining the functions (modes) of the basis of the model and used to configure it.

Description of the classes

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

class layercake.basis.base.Basis(coordinate_system)[source]

Bases: ABC

General base class for a basis of functions.

Parameters:: coordinate_system (CoordinateSystem) – Coordinate system on which the basis is defined.

functions

List of functions of the basis.

Type:: list

coordinate_system

Coordinate system on which the basis is defined.

Type:: CoordinateSystem

class layercake.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 layercake.basis.base.SymbolicBasis(coordinate_system, parameters)[source]

Bases: Basis

General base class for a basis of symbolic functions.

Parameters:

coordinate_system (CoordinateSystem) – Coordinate system on which the basis is defined.
parameters (dict(Parameter)) – Dictionary holding the parameters appearing in the equations defining the basis.

substitutions

List of 2-tuples containing the substitutions to be made with the functions. The 2-tuples contain first a Sympy symbol or expression and then the value to substitute. Parameters of the basis are automatically added to this list.

Type:: list(tuple)

coordinate_system

Coordinate system on which the basis is defined.

Type:: CoordinateSystem

parameters

Dictionary holding the parameters appearing in the equations defining the basis.

Type:: list(Parameter)

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

directional_derivative(order=1)[source]

Return the basis functions differentiated with respect to the coordinates.

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

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)

set_parameters(parameters)[source]

Setter for the parameters attributes. Must be redefined for subclasses.

Parameters:: parameters (dict(Parameter)) – Dictionary holding the parameters appearing in the equations defining the basis.

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

Fourier Basis definition module

Classes and functions defining Fourier basis of functions (Fourier modes) on a plane.

Description of the classes

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

class layercake.basis.planar_fourier.PlanarBasinFourierBasis(parameters, spectral_blocks, length=None)[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:

parameters (list(Parameter)) – List holding the parameters appearing in the equations defining the basis.
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.
length (float or Parameter, optional) – Length of the domain along the \(x\) coordinate: \(L_x\) . Default to None for the default length of \(2 \pi / n\).

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)

coordinate_system

Coordinate system on which the basis is defined.

Type:: CoordinateSystem

parameters

Dictionary holding the parameters appearing in the equations defining the basis.

Type:: list(Parameter)

length

Length of the domain along the \(x\) coordinate: \(L_x\) . None for the default length of \(2 \pi / n\).

Type:: float or None

set_parameters(parameters)[source]

Setter for the parameters’ dictionary.

parameters

List holding the parameters appearing in the equations defining the basis.

Type:: list(Parameter)

class layercake.basis.planar_fourier.PlanarChannelFourierBasis(parameters, spectral_blocks, length=None)[source]

Bases: SymbolicBasis

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

Parameters:

parameters (list(Parameter)) – List holding the parameters appearing in the equations defining the basis.
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.
length (float or Parameter, optional) – Length of the domain along the \(x\) coordinate: \(L_x\) . Default to None for the default length of \(2 \pi / n\).

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)

coordinate_system

Coordinate system on which the basis is defined.

Type:: CoordinateSystem

parameters

Dictionary holding the parameters appearing in the equations defining the basis.

Type:: list(Parameter)

length

Length of the domain along the \(x\) coordinate: \(L_x\) . None for the default length of \(2 \pi / n\).

Type:: float or Parameter or None

set_parameters(parameters)[source]

Setter for the parameters’ dictionary.

parameters

List holding the parameters appearing in the equations defining the basis.

Type:: list(Parameter)

class layercake.basis.planar_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.

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

layercake.basis.planar_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)

layercake.basis.planar_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)

layercake.basis.planar_fourier.contiguous_basin_basis(nxmax, nymax, parameters, length=None)[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.
parameters (list(Parameter)) – List holding the parameters appearing in the equations defining the basis.
length (float or Parameter, optional) – Length of the domain along the \(x\) coordinate: \(L_x\) . Default to None for the default length of \(2 \pi / n\).

Returns:

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

Return type:

PlanarBasinFourierBasis

layercake.basis.planar_fourier.contiguous_channel_basis(nxmax, nymax, parameters, length=None)[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.
parameters (list(Parameter)) – List holding the parameters appearing in the equations defining the basis.
length (float or Parameter, optional) – Length of the domain along the \(x\) coordinate: \(L_x\) . Default to None for the default length of \(2 \pi / n\).

Returns:

The channel contiguous basis up to the specified spectral truncation.

Return type:

ChannelFourierBasis

layercake.basis.planar_fourier.fourier_functions(wave_number, n, coordinate_system)[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.
n (Symbol) – The aspect ratio symbol.
coordinate_system (CoordinateSystem) – Coordinate system on which the basis is defined.

Returns:

Symbolic expression of the mode.

Return type:

Expr

Spherical Harmonics Basis definition module

Classes defining Spherical Harmonics basis of functions on a plane.

class layercake.basis.spherical_harmonics.SphericalHarmonicsBasis(parameters, truncation_parameters, complex=False, truncation='T', exclude_constant_term=True, use_num_factorial=False)[source]

Bases: SymbolicBasis

Complex or real spherical harmonics basis defined on a sphere with a given radius \(R\).

Parameters:

parameters (list(Parameter)) – List holding the parameters appearing in the equations defining the basis.
truncation_parameters (dict) – Dictionary of parameter associated with the specified truncature. For example, for the default triangular truncation, it expects an entry ‘M’ in the dictionary, determining the level of truncation TM.
complex (bool, optional) – Whether the spherical harmonics are defined using complex functions. Default to False.
truncation (str, optional) – Type of truncation to use. Default to “T” for a triangular truncature.
exclude_constant_term (bool, optional) – Whether the spherical harmonics corresponding to a constant should be discarded. Default to True.
use_num_factorial (bool, optional) – Use a numerical factorial instead of a symbolic one. Might speed up computations in certain cases. Default to False.

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.