Variables module

Module to define all kind of variables in the models.

Variable definition module

Variables are objects with a name, a symbol and units. They represent any formal quantity in the models.

Description of the classes

  • Variable: Abstract base class to define variables in the models.

  • VariablesArray: Base class to define array of variables in the models.

class layercake.variables.variable.Variable(name, symbol, units=None, latex=None, dynamical=False)[source]

Bases: ABC

Abstract base class to define variable object in the models.

Parameters:

  • name (str) – Name of the variable.

  • symbol (Symbol) – A Sympy symbol to represent the variable in symbolic expressions.

  • units (str, optional) – The units of the variable. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’. Empty by default.

  • latex (str, optional) – Latex string representing the variable. Empty by default.

  • dynamical (bool, optional) – Whether the variable can vary over time. Default to False.

name

Name of the variable.

Type:

str

symbol

Symbol of the variable.

Type:

Symbol

units

The units of the variable specified as atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’.

Type:

str

latex

Latex string representing the variable.

Type:

str

property dynamical

Whether the variable can vary over time.

Type:

bool

class layercake.variables.variable.VariablesArray(values, name, symbol, units='', latex=None, dynamical=False)[source]

Bases: ndarray

Base class of model’s array of variables values.

Parameters:

  • values (list(float) or ndarray(float)) – Values of the variables array.

  • name (str) – General name of the variables.

  • symbol (str or Symbol) – A Sympy symbol to represent the variables in symbolic expressions.

  • 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.

  • latex (str, optional) – A latex string representing the variables. Used in plots. Empty by default.

  • dynamical (bool, optional) – Whether the variables are varying over time. Default to False.

property dynamical

Whether the variables can vary over time.

Type:

bool

property latex

Returns the general latex expression of the variables in the array.

Type:

str

property latexes

Returns the latex expressions of the variables in the array.

Type:

str

property name

Returns the general name of the variables in the array.

Type:

str

property names

Returns the names of the variables in the array.

Type:

str

property symbol

Returns the general symbol of the variables in the array.

Type:

Symbol

property symbols

Returns the symbols of the variables in the array.

Type:

ndarray(Symbol)

property units

The units of the dimensional values.

Type:

str

Coordinate definition module

A coordinate is a Variable used to define the models’ domains, i.e. as a part of a CoordinatesSystem, to uniquely determine and standardize the position of the points of the domain.

class layercake.variables.coordinate.Coordinate(name, symbol, extent, infinitesimal_length=1, infinitesimal_length_units=None, units=None, latex=None)[source]

Bases: Variable

Class to define a physical coordinate in the system.

Parameters:

  • name (str) – Name of the coordinate.

  • symbol (Symbol) – Sympy symbol of the coordinate

  • extent (tuple(float or Expr or Symbol)) – 2-tuple giving the natural extent of the coordinate, i.e. the lower and higher bounds of the coordinate’s interval.

  • units (str, optional) – The units of the coordinate. 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]’.

  • infinitesimal_length (float or Expr or Symbol, optional) – Infinitesimal length associated with the

  • infinitesimal_length_units (str, optional) – Infinitesimal length units. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’.

  • latex (str, optional) – Latex string representing the coordinate.

name

Name of the coordinate.

Type:

str

symbol

Sympy symbol of the coordinate

Type:

Symbol

extent

2-tuple giving the natural extent of the coordinate, i.e. the lower and higher bounds of the coordinate’s interval.

Type:

tuple(float or Expr or Symbol)

units

The units of the coordinate. Used to compute the conversion between dimensional and nondimensional value.

Type:

str

infinitesimal_length

Infinitesimal length associated with the

Type:

float or Expr or Symbol

infinitesimal_length_units

Infinitesimal length units

Type:

str

latex

Latex string representing the coordinate.

Type:

str

Warning

Coordinates with infinite extent are not currently supported.

Coordinate systems definition module

Coordinate systems defined on models’ domains.

Description of the classes

class layercake.variables.systems.CoordinateSystem(coordinates, name='', parameters=None)[source]

Bases: object

Base class to define a coordinate system.

Parameters:

  • coordinates (list(Coordinate)) – List of coordinates on which the basis is defined.

  • name (str, optional) – Optional name for the coordinate system.

  • parameters (list(Parameter) or tuple(Parameter), optional) – List of parameters used to define the coordinates infinitesimal length.

coordinates

List of coordinates on which the basis is defined.

Type:

list(Coordinate)

name

Optional name for the coordinate system.

Type:

str

parameters

List of parameters used to define the coordinates infinitesimal length.

Type:

list(Parameter)

property coordinates_name

List of the coordinates names.

Type:

list(str)

property coordinates_symbol

Symbols of the coordinates as a dictionary.

Type:

dict(Symbol)

property coordinates_symbol_as_list

Symbols of the coordinates as a list.

Type:

list(Symbol)

property extent

Dictionary of the coordinates extents.

Type:

dict(tuple(float or Expr or Symbol))

property infinitesimal_volume

Infinitesimal volume spanned by the coordinates.

Type:

Expr

class layercake.variables.systems.PlanarCartesianCoordinateSystem(extent)[source]

Bases: CoordinateSystem

Class to define a planar Cartesian coordinate system. Coordinates are \(x\) and \(y\).

Parameters:

extent (list(tuple(float or Expr or Symbol))) – Defines the extent of the plane.

coordinates

x and y coordinates.

Type:

list(Coordinate)

class layercake.variables.systems.SphericalCoordinateSystem(radius, extent=None)[source]

Bases: CoordinateSystem

Class to define a coordinate system on the sphere. Coordinates are the azimuth angle (longitude) \(\lambda\) and the elevation angle (latitude) \(\varphi\).

Parameters:

  • radius (Parameter) – The radius of the sphere.

  • extent (list(tuple(float or Expr or Symbol)), optional) – Defines the extent of the coordinates on the sphere. If not provided, the coordinate system covers the whole sphere.

coordinates

lambda and phi coordinates.

Type:

list(Coordinate)

parameters

List of parameters used to define the coordinate system.

Type:

list(Parameter)

Field definition module

This module defines spatial fields in the models.

Description of the classes

  • Field: Class defining the spatial fields.

  • ParameterField: Class defining static spatial field that can be viewed as models’ parameters.

class layercake.variables.field.Field(name, symbol, basis, inner_product_definition=None, units=None, latex=None, state=None, **state_kwargs)[source]

Bases: Variable

Class defining the spatial fields in the models.

Parameters:

  • name (str) – Name of the field.

  • symbol (Symbol) – A Sympy symbol to represent the field in symbolic expressions.

  • basis (SymbolicBasis) – A symbolic basis of functions on which the Galerkin expansion of the field is performed.

  • inner_product_definition (InnerProductDefinition) – Inner product definition object used to compute the inner products between the elements of the basis.

  • units (str, optional) – The units of the variable. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’. Empty by default.

  • latex (str, optional) – Latex string representing the variable. Empty by default.

  • state (VariablesArray) – Field state array: array containing the coefficient of the field’s Galerkin expansion.

  • state_kwargs (dict) – Used to create the field state array if state is not a VariableArray. Passed to the VariableArray constructor.

name

Name of the field.

Type:

str

symbol

The Sympy symbol representing the field in symbolic expressions.

Type:

Symbol

basis

The symbolic basis of functions on which the Galerkin expansion of the field is performed.

Type:

SymbolicBasis

inner_product_definition

The inner product definition object used to compute the inner products between the elements of the basis.

Type:

InnerProductDefinition

units

The units of the variable. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’.

Type:

str, optional

latex

Latex string representing the variable.

Type:

str, optional

state

Field state array: array containing the coefficient of the field’s Galerkin expansion.

Type:

VariablesArray

coordinate_system

Coordinate system on which the basis of functions and the inner product are defined.

Type:

CoordinateSystem

function

A Sympy symbolic representation of the field as a function of space and time.

Type:

Expr

class layercake.variables.field.FunctionField(name, symbol, symbolic_expression, basis, expression_parameters=None, inner_product_definition=None, units='', latex=None, extra_substitutions=None, force_substitution=False, force_symbolic_substitution=False, **parameters_array_kwargs)[source]

Bases: Variable

Class defining a static spatial fields in the models, specified as a function of the model’s coordinates.

Parameters:

  • name (str) – Name of the field.

  • symbol (Symbol) – Symbol representing the field.

  • symbolic_expression (Expr) – A Sympy expression to represent the field mathematical expression in symbolic expressions.

  • basis (SymbolicBasis) – A symbolic basis of functions on which the Galerkin expansion of the field is performed.

  • expression_parameters (None or list(Parameter), optional) – List of parameters appearing in the symbolic expression. If None, assumes that no parameters are appearing there.

  • inner_product_definition (InnerProductDefinition or None, optional) – Inner product definition object used to compute the inner products between the elements of the basis. If None, the Galerkin expansion will not be computed, and then this field can only be used in symbolic expressions.

  • units (str, optional) – The units of the variable. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’. Empty by default.

  • latex (str, optional) – Latex string representing the variable. Empty by default.

  • extra_substitutions (list(tuple), optional) – List of 2-tuples containing extra symbolic substitutions to be made at the end of the integral computation. The 2-tuples contain first a Sympy expression and then the value to substitute.

  • force_substitution (bool, optional) – Force the substitution by the numerical values of the parameters arrays, even in the symbolic case. Default to False.

  • force_symbolic_substitution (bool, optional) – Force the substitution by the symbolic expressions resulting from the projection of the function field onto the provided basis. Only relevant when working in the symbolic case. Is superseded by the force_substitution argument, i.e. the latter should be set to False for this parameter to work. Default to False.

  • **parameters_array_kwargs (dict, optional) – Used to create the field state ParametersArray object. Passed to the ParametersArray class constructor.

name

Name of the field.

Type:

str

symbol

Symbol representing the field.

Type:

Symbol

symbolic_expression

A Sympy expression to represent the field mathematical expression in symbolic expressions.

Type:

Expr

basis

The symbolic basis of functions on which the Galerkin expansion of the field is performed.

Type:

SymbolicBasis

inner_product_definition

The inner product definition object used to compute the inner products between the elements of the basis.

Type:

InnerProductDefinition

units

The units of the variable. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’.

Type:

str

latex

Latex string representing the variable.

Type:

str, optional

parameters

Array containing the coefficients of the field Galerkin expansion, computed from the specified basis.

Type:

ParametersArray

expression_parameters

List of parameters appearing in the symbolic expression. If None, assumes that no parameters are appearing there.

Type:

None or list(Parameter), optional

force_substitution

Force the substitution by the numerical values of the parameters arrays, even in the symbolic case.

Type:

bool, optional

force_symbolic_substitution

Force the substitution by the symbolic expressions resulting from the projection of the function field onto the provided basis.

Type:

bool, optional

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 numerical_expression

The numeric expression of the function, i.e. with parameters replaced by their numerical value.

Type:

Expr

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)

class layercake.variables.field.ParameterField(name, symbol, parameters_array, basis, inner_product_definition=None, units='', latex=None, **parameters_array_kwargs)[source]

Bases: Variable

Class defining a static spatial fields in the models. Can be viewed as a model parameter.

Parameters:

  • name (str) – Name of the field.

  • symbol (Symbol) – A Sympy symbol to represent the field in symbolic expressions.

  • parameters_array (ParametersArray or ndarray) – Array containing the coefficients of the field Galerkin expansion.

  • basis (SymbolicBasis) – A symbolic basis of functions on which the Galerkin expansion of the field is performed.

  • inner_product_definition (InnerProductDefinition) – Inner product definition object used to compute the inner products between the elements of the basis.

  • units (str, optional) – The units of the variable. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’. Empty by default.

  • latex (str, optional) – Latex string representing the variable. Empty by default.

  • parameters_array_kwargs (dict, optional) – Used to create the field state if parameters_array is not a ParametersArray object. Passed to the ParametersArray class constructor.

name

Name of the field.

Type:

str

symbol

The Sympy symbol representing the field in symbolic expressions.

Type:

Symbol

basis

The symbolic basis of functions on which the Galerkin expansion of the field is performed.

Type:

SymbolicBasis

inner_product_definition

The inner product definition object used to compute the inner products between the elements of the basis.

Type:

InnerProductDefinition

units

The units of the variable. Should be specified by joining atoms like ‘[unit^power]’, e.g ‘[m^2][s^-2][Pa^-2]’.

Type:

str

latex

Latex string representing the variable.

Type:

str, optional

parameters

Array containing the coefficients of the field Galerkin expansion.

Type:

ParametersArray

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)

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 layercake.variables.parameter import Parameter, ParametersArray
>>> import numpy as np
>>> # creating a parameter initialized with a nondimensional value
>>> sigma = Parameter(0.2e0,
...                   description="static stability of the atmosphere (nondimensional)")
>>> sigma
0.2
>>> # creating a parameter initialized with a dimensional value
>>> sigma = Parameter(2.1581898457499433e-06,
...                   units='[m^2][s^-2][Pa^-2]',
...                   description="static stability of the atmosphere")
>>> sigma
2.1581898457499433e-06
>>> # creating a parameters array initialized with a nondimensional values
>>> s = ParametersArray(np.array([[0.1,0.2],[0.3,0.4]]), units='',
...                     description="atmosphere bottom friction coefficient (nondimensional")
>>> s
ArrayParameters([[0.1, 0.2],
                 [0.3, 0.4]], dtype=object)
>>> # you can also ask for the value of one particular value of the array
>>> s[0,0]
0.1

Main classes

class layercake.variables.parameter.Parameter(value, units='', description='', symbol=None, latex=None, symbolic_expression=None)[source]

Bases: float

Base class of model’s parameter.

Parameters:

  • value (float) – Value of the parameter.

  • units (str, optional) – The units of the provided 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.

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

  • latex (str, optional) – A latex string to define the parameter in the latex equations.

  • 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 latex

A latex string defining the parameter in the latex equations.

Type:

str

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 layercake.variables.parameter.ParametersArray(values, units='', description='', symbols=None, symbolic_expressions=None)[source]

Bases: ndarray

Base class of model’s array of parameters.

Parameters:

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

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

  • 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.

  • ~numpy.ndarray(~sympy.core.symbol.Symbol) (symbols ~sympy.core.symbol.Symbol or list(Symbol) or) – 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.

  • 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.

property descriptions

Description of the parameters in the array.

Type:

ndarray(str)

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

Variables utility module

Defines useful functions.

layercake.variables.utils.combine_units(units1, units2, operation)[source]

Combine units strings together with a given operation on the exponents.

Parameters:

  • units1 (str) – First units string to combine.

  • units2 (str) – Second units string to combine.

  • operation (str) – Operation to perform on the units exponents. Presently can be ‘-’ or ‘+’.

Returns:

The resulting units string.

Return type:

str

layercake.variables.utils.power_units(units, power)[source]

Apply power to a units strings.

Parameters:

  • units (str) – Units to take power of.

  • power (int) – Power.

Returns:

The resulting units string.

Return type:

str