Arithmetic module

This module is concerned with the definition and the operation on arithmetic tokens defining the partial differential equations.

A partial differential equation is mainly implemented with a Equation object.

Equation definition module

Main class to define partial differential equation. This class is the workhorse of LayerCake to define and specify partial differential equation.

class layercake.arithmetic.equation.Equation(field, lhs_terms=None, name='')[source]

Bases: object

Main class to define and specify partial differential equations.

Notes

The left-hand side is always expressed as a partial time derivative of something: \(\partial_t\) .

Parameters:

field (Field) – The spatial field over which the partial differential equation.
lhs_terms (ArithmeticTerms or list(ArithmeticTerms), optional) – Terms on the left-hand side of the equation. At least one must involve the field defined above.
name (str, optional) – Name for the equation.

field

The spatial field over which the partial differential equation.

Type:: Field

rhs_terms

List of additive terms in the right-hand side of the equation.

Type:: list(ArithmeticTerms)

lhs_terms

Term on the left-hand side of the equation.

Type:: ListOfArithmeticTerms(ArithmeticTerms)

name

Optional name for the equation.

Type:: str

add_lhs_term(term)[source]

Add a term to the left-hand side of the equation.

Parameters:: term (ArithmeticTerms) – Term to be added to the left-hand side of the equation.

add_lhs_terms(terms)[source]

Add multiple terms to the left-hand side of the equation.

Parameters:: terms (list(ArithmeticTerms)) – Terms to be added to the left-hand side of the equation.

add_rhs_term(term)[source]

Add a term to the right-hand side of the equation.

Parameters:: term (ArithmeticTerms) – Term to be added to the right-hand side of the equation.

add_rhs_terms(terms)[source]

Add multiple terms to the right-hand side of the equation.

Parameters:: terms (list(ArithmeticTerms)) – Terms to be added to the right-hand side of the equation.

compute_inner_products(basis, numerical=False, timeout=None, num_threads=None, permute=False)[source]

Compute the inner products tensor of the left-hand and right-hand side terms.

Parameters:

basis (SymbolicBasis) – Basis with which to compute the inner products.
numerical (bool, optional) – Whether the resulting computed inner products must be numerical or symbolic. Default to False, i.e. symbolic output.
num_threads (int or None, optional) – Number of threads to use to compute the inner products. If None use all the cpus available. Default to None.
timeout (int or float or bool or None, optional) –
Control the switch from symbolic to numerical integration. By default, parallel_integration workers will try to integrate Sympy expressions symbolically, but a fallback to numerical integration can be enforced. The options are:
- None: This is the “full-symbolic” mode. No timeout will be applied, and the switch to numerical integration will never happen. Can result in very long and improbable computation time.
- True: This is the “full-numerical” mode. Symbolic computations do not occur, and the workers try directly to integrate numerically.
- False: Same as None.
- An integer: defines a timeout after which, if a symbolic integration have not completed, the worker switch to the numerical integration.
permute (bool, optional) – If True, applies all the possible permutations to the tensor indices from 1 to the rank of the tensor. Default to False, i.e. no permutation is applied.

property lhs_inner_products

Inner products of each term of the left-hand side of the equation, if available.

Type:: list(ImmutableSparseMatrix or ImmutableSparseNDimArray) or list(sparse.COO(float))

property lhs_inner_products_addition

Added left-hand side inner products of the equation, if available. Might raise an error if not all terms are compatible.

Type:: ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

property maximum_rank

Maximum rank of the right-hand side terms tensors.

Type:: int

property numerical_expression

Expression of the equation with parameters replaced by their configured values.

Type:: Expr

property numerical_lhs

Expression of the left-hand side of the equation with parameters replaced by their configured values.

Type:: Expr

property numerical_rhs

Expression of the right-hand side of the equation with parameters replaced by their configured values.

Type:: Expr

property other_fields

List of additional fields present in the equation.

Type:: list(Field)

property other_fields_in_lhs

List of additional fields present in the LHS of the equation.

Type:: list(Field)

property parameter_fields

List of non-dynamical parameter fields present in the equation.

Type:: list(ParameterField)

property parameters

List of parameters present in the equation.

Type:: list(Parameter)

property parameters_symbols

List of parameter’s symbols present in the equation.

Type:: list(Symbol)

show_latex(enclose_lhs=True, drop_first_lhs_char=True, drop_first_rhs_char=False)[source]

Show the LaTeX string representing the equation mathematically rendered in a window.

Parameters:

enclose_lhs (bool, optional) – Whether to enclose the left-hand side term inside parenthesis. Default to True.
drop_first_lhs_char (bool, optional) – Whether to drop the first two character of the left-hand side latex string. Useful to drop the sign in front of it. Default to True.
drop_first_rhs_char (bool, optional) – Whether to drop the first two character of the right-hand side latex string. Useful to drop the sign in front of it. Default to False.

property symbolic_expression

Symbolic expression of the equation.

Type:: Expr

property symbolic_lhs

Symbolic expression of the left-hand side of the equation.

Type:: Expr

property symbolic_rhs

Symbolic expression of the right-hand side of the equation.

Type:: Expr

property terms: Alias for the list of RHS arithmetic terms.

to_latex(enclose_lhs=True, drop_first_lhs_char=True, drop_first_rhs_char=False)[source]

Generate a LaTeX string representing the equation mathematically.

Parameters:

enclose_lhs (bool, optional) – Whether to enclose the left-hand side term inside parenthesis. Default to True.
drop_first_lhs_char (bool, optional) – Whether to drop the first two character of the left-hand side latex string. Useful to drop the sign in front of it. Default to True.
drop_first_rhs_char (bool, optional) – Whether to drop the first two character of the right-hand side latex string. Useful to drop the sign in front of it. Default to False.

Returns:

The LaTeX string representing the equation.

Return type:

str

class layercake.arithmetic.equation.ListOfAdditiveArithmeticTerms(iterable=(), /)[source]

Bases: list

Class holding list of additive arithmetic terms in equations.

compute_inner_products(basis, numerical=False, timeout=None, num_threads=None, permute=False)[source]

Compute the inner products tensor of the all the terms of the list.

Parameters:

basis (SymbolicBasis) – Basis with which to compute the inner products.
numerical (bool, optional) – Whether the resulting computed inner products must be numerical or symbolic. Default to False, i.e. symbolic output.
num_threads (int or None, optional) – Number of threads to use to compute the inner products. If None use all the cpus available. Default to None.
timeout (int or float or bool or None, optional) –
Control the switch from symbolic to numerical integration. By default, parallel_integration workers will try to integrate Sympy expressions symbolically, but a fallback to numerical integration can be enforced. The options are:
- None: This is the “full-symbolic” mode. No timeout will be applied, and the switch to numerical integration will never happen. Can result in very long and improbable computation time.
- True: This is the “full-numerical” mode. Symbolic computations do not occur, and the workers try directly to integrate numerically.
- False: Same as None.
- An integer: defines a timeout after which, if a symbolic integration have not completed, the worker switch to the numerical integration.
permute (bool, optional) – If True, applies all the possible permutations to the tensor indices from 1 to the rank of the tensor. Default to False, i.e. no permutation is applied.

property maximum_rank

Maximum rank of the right-hand side terms tensors.

Type:: int

property numerical_expression

Expression of the collection of additive arithmetic terms with parameters replaced by their configured values.

Type:: Expr

property same_rank

Check if all terms have the same rank.

Type:: bool

property symbolic_expression

Symbolic expression of the collection of additive arithmetic terms.

Type:: Expr

Symbolic submodule

This submodule deals with the definition of high-level expressions, symbolic operations and operators.

Expressions definition module

This module defines mathematical expression to be inserted in the models equations.

class layercake.arithmetic.symbolic.expressions.Expression(symbolic_expression, expression_parameters=None, units='', latex=None)[source]

Bases: object

Class defining a general mathematical expression in the equations. Can be used for example as prefactor for arithmetic terms.

Parameters:

symbolic_expression (Expr) – A Sympy expression to represent the field mathematical expression in symbolic expressions.
expression_parameters (None or list(Parameter), optional) – List of parameters appearing in the symbolic expression. If None, assumes that no parameters are appearing there.
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.

symbolic_expression

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

Type:: Expr

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

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

property numerical_expression

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

Type:: Expr

property symbol

Synonym for the symbolic expression, to be accepted as prefactor.

Type:: Expr

Operators definition module

This module defines various symbolic operators (mainly differential ones) acting on the fields of the partial differential equations in Sympy expression.

class layercake.arithmetic.symbolic.operators.D(*variables, **kwargs)[source]

Bases: Expr

Symbolic differential operator acting on Sympy expression. Inspired by this post.

Parameters:: *variables (Symbol) – Variables with respect to which the operator differentiates. The number of variables indicate the order of the derivative.

variables

Variables with respect to which the operator differentiates. The number of variables indicate the order of the derivative.

Type:: list(Symbol)

evaluate

Whether the expression resulting from the action of the operator is evaluated. Default to False.

Type:: bool

latex

LaTeX representation of the operator.

Type:: str

layercake.arithmetic.symbolic.operators.Divergence(coordinate_system)[source]

Function returning the divergence (\(\nabla \cdot\)) operator associated with a given coordinate system.

Notes

The returned expression has an additional latex attribute.

Parameters:: coordinate_system (CoordinateSystem) – Coordinate system for which the divergence operator must be returned.
Returns:: The divergence operator associated with the coordinate system.
Return type:: Expr

layercake.arithmetic.symbolic.operators.Laplacian(coordinate_system)[source]

Function returning the Laplacian (\(\nabla^2\)) operator associated with a given coordinate system.

Notes

The returned expression has an additional latex attribute.

Parameters:: coordinate_system (CoordinateSystem) – Coordinate system for which the Laplacian operator must be returned.
Returns:: The Laplacian operator associated with the coordinate system.
Return type:: Expr

layercake.arithmetic.symbolic.operators.Nabla(coordinate_system)[source]

Function returning the Nabla (Del - \(\nabla\)) operator associated with a given coordinate system.

Notes

The returned expression has an additional latex attribute.

Parameters:: coordinate_system (CoordinateSystem) – Coordinate system for which the \(\nabla\) operator must be returned.
Returns:: The \(\nabla\) operator associated with the coordinate system.
Return type:: Expr

layercake.arithmetic.symbolic.operators.evaluate_expr(expr)[source]

Evaluate a given Sympy expression.

Parameters:: expr (Expr) – The expression to evaluate.
Returns:: The evaluated expression.
Return type:: Expr

Terms submodule

This module is a bestiary of the all the different kind of terms that can compose a partial differential equation.

Arithmetic terms definition module

This module defines base classes for partial differential equation arithmetic terms. The corresponding objects hold the symbolic representation of the terms and their decomposition on given function basis.

Description of the classes

ArithmeticTerms: General base class for partial differential equation arithmetic terms.
SingleArithmeticTerm: Base class for single arithmetic terms (singleton) involving the field over which the partial differential equation acts.
OperationOnTerms: Base class for operations on arithmetic terms. Perform the same operation on multiple terms.

class layercake.arithmetic.terms.base.ArithmeticTerms(name='', sign=1)[source]

Bases: ABC

General base class for partial differential equation arithmetic term(s). Holds the symbolic representation of (possibly multiple) term(s) and his(their) decomposition(s) on a given function basis.

More precisely, models a term \(\pm \, T(u_1, u_2)\) in the partial differential equation, where \(u_1, u_2\) are the coordinates of the model. Upon decomposition on function basis, it can be represented as a tensor \(\mathcal{T}_{i_1, \ldots, i_r}\) where \(r\) is the tensor (and term(s)) rank.

Parameters:

name (str, optional) – Name of the term(s). Must be defined in subclasses.
sign (int, optional) – Sign in front of the term(s). Either +1 or -1. Default to +1.

name

Name of the term(s). Must be defined in subclasses.

Type:: str, optional

sign

Sign in front of the term(s). Either +1 or -1.

Type:: int, optional

inner_products

The inner products tensor of the term(s). Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term(s) representation on a given function basis.

Type:: InnerProductDefinition

abstract compute_inner_products(basis, numerical=False, timeout=None, num_threads=None, permute=False)[source]

Compute the inner products tensor \(\mathcal{T}_{i_1, \ldots, i_r}\), either symbolic or numerical ones, representing the term(s) decomposed on a given function basis. Computations are parallelized on multiple CPUs. Results are stored in the inner_products attribute.

Parameters:

basis (SymbolicBasis or list(SymbolicBasis)) – Symbolic basis function or list of symbolic function basis on which each element of the term(s) inner products must be decomposed.
numerical (bool, optional) – Whether to compute numerical or symbolic inner products. Default to False (symbolic inner products as output).
timeout (int or bool or None, optional) –
Control the switch from symbolic to numerical integration. By default, parallel_integration workers will try to integrate Sympy expressions symbolically, but a fallback to numerical integration can be enforced. The options are:
- None: This is the “full-symbolic” mode. No timeout will be applied, and the switch to numerical integration will never happen. Can result in very long and improbable computation time.
- True: This is the “full-numerical” mode. Symbolic computations do not occur, and the workers try directly to integrate numerically.
- False: Same as None.
- An integer: defines a timeout after which, if a symbolic integration have not completed, the worker switch to the numerical integration.
num_threads (None or int, optional) – Number of CPUs to use in parallel for the computations. If None, use all the CPUs available. Default to None.
permute (bool, optional) – If True, applies all the possible permutations to the tensor indices from 1 to the rank of the tensor. Default to False, i.e. no permutation is applied.

copy()[source]: ArithmeticTerms: Return a copy of the term(s) object.

abstract property latex

Return a LaTeX representation of the term(s).

Type:: str

abstract property numerical_expression

The numeric expression of the term(s), with parameters replaced by their numerical value.

Type:: Expr

abstract property numerical_function

The numeric expression of the term(s), as a symbolic functional, but with parameters replaced by their numerical value.

Type:: Expr

property rank

Rank of the tensor storing the term(s) decomposition on the provided function basis.

Type:: int

abstract property symbolic_expression

The symbolic expression of the term(s). Only contains symbols.

Type:: Expr

abstract property symbolic_function

The symbolic expression of the term(s), but as a symbolic functional. Only contains symbols.

Type:: Expr

abstract property terms

List of the terms.

Type:: list(ArithmeticTerms)

class layercake.arithmetic.terms.base.OperationOnTerms(*terms, **kwargs)[source]

Bases: ArithmeticTerms

Base class for operations on arithmetic terms. Perform the same operation on multiple terms. Holds the symbolic representation of the result and his decomposition on a given function basis.

More precisely, models a term in the partial differential equation as a provided operation noted \(\wedge\), acting on multiple multilinear functional terms \(\pm \, T(u_1, u_2) = \bigwedge_{i=1}^k T_i[\psi^i_1, \ldots, \psi^i_{j_i}] (u_1, u_2)\), where the \(\psi^i_k\)’s are the \(j_i\) fields (possibly the same) on which the functional \(T_i\) are acting, and the \(u_1, u_2\) are the coordinates of the model. Upon decomposition on function basis, it can be represented as a tensor

\[\mathcal{T}_{j, k_{1,1}, \ldots, k_{1,j_1}, \ldots, k_{l,1}, \ldots, k_{l,{j_l}}} = \left\langle \phi_{j} , \pm \, \bigwedge_{i=1}^l T_i\left[\left(\eta^i_1\right)_{k_{i,1}}, \ldots, \left(\eta^i_{j_i}\right)_{k_{i,j_i}}\right] \right\rangle\]

where the \(\phi_j\)’s are basis functions provided by the user, and the \(\left(\eta^i_j\right)_k\)’s are basis functions on which the fields \(\psi^i_j\)’s are decomposed. \(\langle \, , \rangle\) is the inner provided by the user. The rank \(r\) of this kind of term (and its tensor rank) is thus \(1+\sum_{i=1}^l j_i\).

Parameters:

*terms (ArithmeticTerms) – The terms over which the operation is applied.
**continuation_kwargs – Additional arguments passed to the object, see list below:
inner_product_definition (InnerProductDefinition, optional) – Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis. If not provided, it will use the inner product definition found in the field object. Default to using the inner product definition found in the field object.
name (str, optional) – Name of the term(s). Must be defined in subclasses.
sign (int, optional) – Sign in front of the term(s). Either +1 or -1. Default to +1.
rank (int, optional) – Can be used to force the rank of the term, i.e. force the rank of the tensor storing the term(s) decomposition on the provided function basis. Compute the rank automatically if not provided.

name

Name of the term. Must be defined in subclasses.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

inner_products

The inner products tensor of the term. Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis.

Type:: InnerProductDefinition

compute_inner_products(basis, numerical=False, timeout=None, num_threads=None, permute=False)[source]

Compute the inner products tensor, either symbolic or numerical ones, representing the term(s) decomposed on a given function basis. Computations are parallelized on multiple CPUs. Results are stored in the inner_products attribute.

Parameters:

basis (list(SymbolicBasis)) – List of symbolic function basis on which each term of the operation on the terms must be decomposed.
numerical (bool, optional) – Whether to compute numerical or symbolic inner products. Default to False (symbolic inner products as output).
timeout (int or bool or None, optional) –
Control the switch from symbolic to numerical integration. By default, parallel_integration workers will try to integrate Sympy expressions symbolically, but a fallback to numerical integration can be enforced. The options are:
- None: This is the “full-symbolic” mode. No timeout will be applied, and the switch to numerical integration will never happen. Can result in very long and improbable computation time.
- True: This is the “full-numerical” mode. Symbolic computations do not occur, and the workers try directly to integrate numerically.
- False: Same as None.
- An integer: defines a timeout after which, if a symbolic integration have not completed, the worker switch to the numerical integration.
num_threads (None or int, optional) – Number of CPUs to use in parallel for the computations. If None, use all the CPUs available. Default to None.
permute (bool, optional) – If True, applies all the possible permutations to the tensor indices from 1 to the rank of the tensor. Default to False, i.e. no permutation is applied.

property number_of_terms

Number of the terms on which the operation acts.

Type:: int

property numerical_expression

The numerical expression of the result of the operation on the terms, with parameters replaced by their numerical value.

Type:: Expr

property numerical_function

The numerical expression of the result of the operation on the terms, as a symbolic functional, and with parameters replaced by their numerical value.

Type:: Expr

property numerical_function_dummy

The numerical expression of the result of the operation on the terms, as a symbolic functional with dummy symbols, and with parameters replaced by their numerical value.

Type:: Expr

abstract operation(*terms, evaluate=False)[source]

Operation acting on the terms. Must be defined in subclasses.

Parameters:

*terms (ArithmeticTerms) – Terms on which the operation must be applied.
evaluate (bool) – Whether to let Sympy evaluate the operation or not. Default to False.

Returns:

The result of the operation on the terms, as a Sympy symbolic expression.

Return type:

Expr

property parameters

List of parameters present in the terms.

Type:: list(Parameter)

property symbolic_expression

The symbolic expression of the result of the operation on the terms. Only contains symbols.

Type:: Expr

property symbolic_function

The symbolic expression of the result of the operation on the terms, but as a symbolic functional. Only contains symbols.

Type:: Expr

property symbolic_function_dummy

The symbolic expression of the result of the operation on the terms, but as a symbolic functional and with dummy symbols. Only contains symbols.

Type:: Expr

property terms

List of the terms on which the operation acts.

Type:: list(ArithmeticTerms)

class layercake.arithmetic.terms.base.SingleArithmeticTerm(field, inner_product_definition=None, prefactor=None, name='', sign=1)[source]

Bases: ArithmeticTerms

Base class for single arithmetic terms (singleton) involving the field over which the partial differential equation acts. Holds the symbolic representation of the term and his decomposition on given function basis.

More precisely, models a term in the partial differential equation as a linear functional \(\pm \, T[\psi](u_1, u_2)\), where \(\psi\) is the field solution of the equation, and the \(u_1, u_2\) are the coordinates of the model. Upon decomposition on function basis, it can be represented as a tensor

\[\mathcal{T}_{i_1, i_2} = \left\langle \phi_{i_1} , \pm \, T[\eta_{i_2}] \right\rangle\]

where the \(\phi_i\)’s are basis functions provided by the user, and the \(\eta_i\)’s are basis functions on which the field \(\psi\) is decomposed. \(\langle \, , \rangle\) is the inner provided by the user. The rank \(r\) of this kind of term (and its tensor rank) is thus always 2.

Parameters:

field (Field or ParameterField) – A field appearing in the partial differential equation.
inner_product_definition (InnerProductDefinition, optional) – Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis. If not provided, it will use the inner product definition found in the field object. Default to using the inner product definition found in the field object.
prefactor (Parameter or Expression, optional) – Prefactor in front of the single term. Must be specified as a model parameter or a symbolic expression.
name (str, optional) – Name of the term. Must be defined in subclasses.
sign (int, optional) – Sign in front of the term(s). Either +1 or -1. Default to +1.

field

The field appearing in the partial differential equation.

Type:: Field or ParameterField

name

Name of the term. Must be defined in subclasses.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

inner_products

The inner products tensor of the term. Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis.

Type:: InnerProductDefinition

prefactor

Prefactor in front of the single term.

Type:: Parameter or Expression

compute_inner_products(basis, numerical=False, timeout=None, num_threads=None, permute=False)[source]

Compute the inner products tensor, either symbolic or numerical ones, representing the term decomposed on a given function basis. Computations are parallelized on multiple CPUs. Results are stored in the inner_products attribute.

Parameters:

basis (SymbolicBasis) – Symbolic function basis on which the term must be decomposed, i.e integrated with the term’s field’s function basis.
numerical (bool, optional) – Whether to compute numerical or symbolic inner products. Default to False (symbolic inner products as output).
timeout (int or bool or None, optional) –
Control the switch from symbolic to numerical integration. By default, parallel_integration workers will try to integrate Sympy expressions symbolically, but a fallback to numerical integration can be enforced. The options are:
- None: This is the “full-symbolic” mode. No timeout will be applied, and the switch to numerical integration will never happen. Can result in very long and improbable computation time.
- True: This is the “full-numerical” mode. Symbolic computations do not occur, and the workers try directly to integrate numerically.
- False: Same as None.
- An integer: defines a timeout after which, if a symbolic integration have not completed, the worker switch to the numerical integration.
num_threads (None or int, optional) – Number of CPUs to use in parallel for the computations. If None, use all the CPUs available. Default to None.
permute (bool, optional) – If True, applies all the possible permutations to the tensor indices from 1 to the rank of the tensor. Default to False, i.e. no permutation is applied.

property numerical_function

The numeric expression of the term(s), as a symbolic functional, but with parameters replaced by their numerical value.

Type:: Expr

property parameters

List of parameters present in the term.

Type:: list(Parameter)

property symbolic_function

The symbolic expression of the term(s), but as a symbolic functional. Only contains symbols.

Type:: Expr

property terms

List of the terms. Here a single term is returned in the list.

Type:: list(ArithmeticTerms)

Constant arithmetic term definition module

This module defines a constant terms in partial differential equations, i.e. a time-invariant spatial pattern. The corresponding objects hold the symbolic representation of the terms and their decomposition on given function basis.

class layercake.arithmetic.terms.constant.ConstantTerm(parameter_field, name='', sign=1)[source]

Bases: ArithmeticTerms

Constant term in a partial differential equation, i.e. a time-invariant field \(C(u_1, u_2)\) where \(u_1, u_2\) are the coordinates of the model. Time-invariant here means \(\partial_t C = 0\). Allows to directly introduce constant terms into the ODEs.

Parameters:

parameter_field (ParameterField) – The field provided as a parameter field object which contains also the Galerkin expansion coefficients of the field on a given basis.
name (str, optional) – Name of the term(s).
sign (int, optional) – Sign in front of the term(s). Either +1 or -1. Default to +1.

field

The field over which the partial differential equation acts.

Type:: Field

name

Name of the term.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

compute_inner_products(basis, numerical=False, timeout=None, num_threads=None, permute=False)[source]: Return nor compute nothing. Not used by this class.

property latex

Return a LaTeX representation of the term.

Type:: str

property numerical_expression

The numeric expression of the term, with parameters replaced by their numerical value. Same as the symbolic expression for this term.

Type:: Expr

property numerical_function

The numeric expression of the term, as a symbolic functional, but with parameters replaced by their numerical value. Same as the symbolic function for this term.

Type:: Expr

property symbolic_expression

The symbolic expression of the term. Only contains symbols.

Type:: Expr

property symbolic_function

The symbolic expression of the term, but as a symbolic functional. Only contains symbols.

Type:: Expr

property terms

List of the terms.

Type:: list(ArithmeticTerms)

Linear arithmetic term definition module

This module defines linear terms in partial differential equations. The corresponding objects hold the symbolic representation of the terms and their decomposition on given function basis.

class layercake.arithmetic.terms.linear.LinearTerm(field, inner_product_definition=None, prefactor=None, name='', sign=1)[source]

Bases: SingleArithmeticTerm

Linear term in a partial differential equation, of the form \(\pm \, a \, \psi(u_1, u_2)\), where \(u_1, u_2\) are the coordinates of the model, \(a\) is a prefactor, and where \(\psi\) is a field of the equation.

Parameters:

field (Field or ParameterField) – A field appearing in the partial differential equation.
inner_product_definition (InnerProductDefinition, optional) – Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis. If not provided, it will use the inner product definition found in the field object. Default to using the inner product definition found in the field object.
prefactor (Parameter or Expression, optional) – Prefactor in front of the term. Must be specified as a model parameter or a symbolic expression.
name (str, optional) – Name of the term.
sign (int, optional) – Sign in front of the term. Either +1 or -1. Default to +1.

field

The field appearing in the partial differential equation.

Type:: Field or ParameterField

name

Name of the term.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

inner_products

The inner products tensor of the term. Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis.

Type:: InnerProductDefinition

prefactor

Prefactor in front of the term.

Type:: Parameter or Expression

property latex

Return a LaTeX representation of the term.

Type:: str

property numerical_expression

The numeric expression of the term, with parameters replaced by their numerical value.

Type:: Expr

property symbolic_expression

The symbolic expression of the term. Only contains symbols.

Type:: Expr

Arithmetic operations module

This module defines terms resulting from arithmetic operation being applied to arithmetic terms. The corresponding objects hold the symbolic representation of the terms and their decomposition on given function basis.

Description of the classes

ProductOfTerms: Product of a list of terms in a partial differential equation.
AdditionOfTerms: Addition of a list of terms in a partial differential equation.

class layercake.arithmetic.terms.operations.AdditionOfTerms(*terms, name='', rank=None, sign=1)[source]

Bases: OperationOnTerms

Term representing the addition of multiple arithmetic terms.

Warning

Provided terms must have the same rank, and involve the same field.

Parameters:

*terms (ArithmeticTerms) – Arithmetic terms to take the addition of.
name (str, optional) – Name of the term.
rank (int, optional) – Can be used to force the rank of the term, i.e. force the rank of the tensor storing the term(s) decomposition on the provided function basis. Compute the rank automatically if not provided.
sign (int, optional) – Sign in front of the term. Either +1 or -1. Default to +1.

name

Name of the term.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

inner_products

The inner products tensor of the term. Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis.

Type:: InnerProductDefinition

property latex

Return a LaTeX representation of the terms.

Type:: str

property numerical_expression

The numerical expression of the result of the operation on the terms, as a symbolic functional, and with parameters replaced by their numerical value.

Type:: Expr

operation(*terms, evaluate=False)[source]

Operation (here the addition) acting on the terms.

Parameters:

*terms (ArithmeticTerms) – Terms on which the operation must be applied.
evaluate (bool) – Whether to let Sympy evaluate the operation or not. Default to False.

Returns:

The result of the operation on the terms, as a Sympy symbolic expression.

Return type:

Expr

property symbolic_expression

The symbolic expression of the result of the operation on the terms, but as a symbolic functional. Only contains symbols.

Type:: Expr

class layercake.arithmetic.terms.operations.ProductOfTerms(*terms, name='', rank=None, sign=1)[source]

Bases: OperationOnTerms

Term representing the product of multiple arithmetic terms.

Parameters:

*terms (ArithmeticTerms) – Arithmetic terms to take the product of.
name (str, optional) – Name of the term.
rank (int, optional) – Can be used to force the rank of the term, i.e. force the rank of the tensor storing the term(s) decomposition on the provided function basis. Compute the rank automatically if not provided.
sign (int, optional) – Sign in front of the term. Either +1 or -1. Default to +1.

name

Name of the term.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

inner_products

The inner products tensor of the term. Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis.

Type:: InnerProductDefinition

property latex

Return a LaTeX representation of the terms.

Type:: str

operation(*terms, evaluate=False)[source]

Operation (here the product) acting on the terms.

Parameters:

*terms (ArithmeticTerms) – Terms on which the operation must be applied.
evaluate (bool) – Whether to let Sympy evaluate the operation or not. Default to False.

Returns:

The result of the operation on the terms, as a Sympy symbolic expression.

Return type:

Expr

Operator arithmetic term definition module

This module defines operator terms in partial differential equations. The corresponding objects hold the symbolic representation of the terms and their decomposition on given function basis.

Description of the classes

OperatorTerm: Operator term in a partial differential equation, acting on fields of the equation.
ComposedOperatorsTerm: Term representing the composition of multiple operators, acting on fields of the equation.

class layercake.arithmetic.terms.operators.ComposedOperatorsTerm(field, operators, operators_args, inner_product_definition=None, prefactor=None, name='', sign=1)[source]

Bases: SingleArithmeticTerm

Term representing the composition \(\circ\) of multiple operators \(H_i\) acting on fields of a partial differential equation, and of the form \(\pm \, a \, H_1 \circ H_2 \ldots \circ H_n \psi(u_1, u_2)\), where \(u_1, u_2\) are the coordinates of the model, \(a\) is a prefactor, and \(\psi\) is a field of the equation.

Parameters:

field (Field or ParameterField) – A field appearing in the partial differential equation, and on which the composed operators act.
operators (list(object)) – List of objects or functions returning the action of the operator on symbolic Sympy expressions. Each component of the list must also have a latex attribute.
operators_args (list(tuple)) – Tuples of arguments to pass to the operators objects or functions, one tuple per operator.
inner_product_definition (InnerProductDefinition, optional) – Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis. If not provided, it will use the inner product definition found in the field object. Default to using the inner product definition found in the field object.
prefactor (Parameter or Expression, optional) – Prefactor in front of the operator. Must be specified as a model parameter or a symbolic expression.
name (str, optional) – Name of the term.
sign (int, optional) – Sign in front of the term. Either +1 or -1. Default to +1.

field

The field appearing in the partial differential equation, and on which the operator acts.

Type:: Field or ParameterField

name

Name of the term.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

inner_products

The inner products tensor of the term. Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis.

Type:: InnerProductDefinition

prefactor

Prefactor in front of the operator.

Type:: Parameter or Expression

property latex

Return a LaTeX representation of the operators.

Type:: str

property numerical_expression

The numeric expression of the operators, with parameters replaced by their numerical value.

Type:: Expr

property symbolic_expression

The symbolic expression of the operators. Only contains symbols.

Type:: Expr

class layercake.arithmetic.terms.operators.OperatorTerm(field, operator, operator_args, inner_product_definition=None, prefactor=None, name='', sign=1)[source]

Bases: SingleArithmeticTerm

Operator term in a partial differential equation, acting on fields of the equation, and of the form \(\pm \, a \, H \psi(u_1, u_2)\), where \(H\) is the operator, \(u_1, u_2\) are the coordinates of the model, \(a\) is a prefactor, and \(\psi\) is a field of the equation.

Parameters:

field (Field or ParameterField) – A field appearing in the partial differential equation, and on which the operator acts.
operator (object) – Object or function returning the action of the operator on symbolic Sympy expressions. Must also have a latex attribute.
operator_args (tuple) – Tuple of arguments to pass to the operator object or function.
inner_product_definition (InnerProductDefinition, optional) – Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis. If not provided, it will use the inner product definition found in the field object. Default to using the inner product definition found in the field object.
prefactor (Parameter or Expression, optional) – Prefactor in front of the operator. Must be specified as a model parameter or a symbolic expression.
name (str, optional) – Name of the term.
sign (int, optional) – Sign in front of the term. Either +1 or -1. Default to +1.

field

The field appearing in the partial differential equation, and on which the operator acts.

Type:: Field or ParameterField

name

Name of the term.

Type:: str

sign

Sign in front of the term. Either +1 or -1.

Type:: int

inner_products

The inner products tensor of the term. Set initially to None (not computed).

Type:: None or ImmutableSparseMatrix or ImmutableSparseNDimArray or sparse.COO(float)

inner_product_definition

Object defining the integral representation of the inner product that is used to compute the term representation on a given function basis.

Type:: InnerProductDefinition

prefactor

Prefactor in front of the operator.

Type:: Parameter or Expression

property latex

Return a LaTeX representation of the operator.

Type:: str

property numerical_expression

The numeric expression of the operator, with parameters replaced by their numerical value.

Type:: Expr

property symbolic_expression

The symbolic expression of the operator. Only contains symbols.

Type:: Expr

Jacobian and vorticity module

This module defines a function to compute the terms for the Jacobian of fields in partial differential equations. A function to compute derived forms of the Jacobian like the vorticity advection is provided.

layercake.arithmetic.terms.jacobian.Jacobian(field1, field2, coordinate_system, sign=1, prefactors=(None, None))[source]

Function returning a list of ProductOfTerms components of the partial differential equation’s Jacobian:

\[J(\psi, \phi) = e_1 \, e_2 \, \left(\partial_{u_1} \psi \, \partial_{u_2} \phi - \partial_{u_1} \phi \, \partial_{u_2} \psi \right)\]

where \(\phi\) and \(\psi\) are two fields defined on the model’s domain, \(u_1, u_2\) are the coordinates of the model, and \(e_1, e_2\) are the inverse of the infinitesimal length of the coordinates (which can be functions of the \(u_1, u_2\) coordinates).

Parameters:

field1 (Field or ParameterField) – First field on which the Jacobian act (corresponds to the field \(\psi\) in the formula above).
field2 (Field or ParameterField) – Second field on which the Jacobian act (corresponds to the field \(\phi\) in the formula above).
coordinate_system (CoordinateSystem) – Coordinate system on which the model is defined.
sign (int, optional) – Sign in front of the Jacobian term. Either +1 or -1. Default to +1.
prefactors (tuple(Parameter or Expression), optional) – 2-tuple providing the prefactors in front of each of the two terms composing the Jacobian. This is added on top of the infinitesimal length prefactor. Must be specified as model parameters or symbolic expressions.

Returns:

2-tuple containing arithmetic terms representing each term of the Jacobian.

Return type:

tuple(ProductOfTerms)

layercake.arithmetic.terms.jacobian.vorticity_advection(field1, field2, coordinate_system, sign=1, prefactors=(None, None))[source]

Function returning a list of ProductOfTerms components of the vorticity advection in the partial differential equation, provided by the expression \(J(\psi, \nabla^2 \phi)\), where \(J\) is the partial differential equation’s Jacobian Jacobian():

\[J(\psi, \nabla^2 \phi) = e_1 \, e_2 \, \left(\partial_{u_1} \psi \, \partial_{u_2} \nabla^2 \phi - \partial_{u_1} \nabla^2 \phi \, \partial_{u_2} \psi \right)\]

where \(\phi\) and \(\psi\) are two fields defined on the model’s domain, \(u_1, u_2\) are the coordinates of the model, and \(e_1, e_2\) are the inverse of the infinitesimal length of the coordinates (which can be functions of the \(u_1, u_2\) coordinates).

Parameters:

field1 (Field or ParameterField) – First field, advected by the vorticity.
field2 (Field or ParameterField) – Second field with which the vorticity \(\nabla^2\) is computed.
coordinate_system (CoordinateSystem) – Coordinate system on which the model is defined.
sign (int, optional) – Sign in front of the vorticity advection term. Either +1 or -1. Default to +1.
prefactors (tuple(Parameter or Expression), optional) – 2-tuple providing the prefactors in front of each of the two terms composing the Jacobian. This is added on top of the infinitesimal length prefactor. Must be specified as model parameters or symbolic expressions.

Returns:

2-tuple containing arithmetic terms representing each term of the vorticity advection.

Return type:

tuple(ProductOfTerms)

Gradient module

This module defines a function to compute the terms for the scalar product of gradients of fields in partial differential equations. A function to compute derived forms of the gradient products involving the vorticity is also provided.

layercake.arithmetic.terms.gradient.gradients_product(field1, field2, coordinate_system, sign=1, prefactors=(None, None))[source]

Function returning a list of ProductOfTerms components of the partial differential equation’s scalar product of gradients:

\[P(\psi, \phi) = e_1^2 \, \partial_{u_1} \psi \, \partial_{u_1} \phi + e_2^2 \, \partial_{u_2} \psi \, \partial_{u_2} \phi\]

where \(\phi\) and \(\psi\) are two fields defined on the model’s domain, \(u_1, u_2\) are the coordinates of the model, and \(e_1, e_2\) are the inverse of the infinitesimal length of the coordinates (which can be functions of the \(u_1, u_2\) coordinates).

Parameters:

field1 (Field or ParameterField) – Field on which the first gradient of the scalar product act (corresponds to the field \(\psi\) in the formula above).
field2 (Field or ParameterField) – Field on which the second gradient of the scalar product act (corresponds to the field \(\phi\) in the formula above).
coordinate_system (CoordinateSystem) – Coordinate system on which the model is defined.
sign (int, optional) – Sign in front of the term. Either +1 or -1. Default to +1.
prefactors (tuple(Parameter or Expression), optional) – 2-tuple providing the prefactors in front of each of the two terms composing the scalar product of gradients. This is added on top of the infinitesimal length prefactor. Must be specified as model parameters or symbolic expressions.

Returns:

2-tuple containing arithmetic terms representing each term of the scalar product of gradients.

Return type:

tuple(ProductOfTerms)

layercake.arithmetic.terms.gradient.vorticity_gradients_product(field1, field2, coordinate_system, sign=1, prefactors=(None, None))[source]

Function returning a list of ProductOfTerms components of the vorticity advection in the partial differential equation, provided by the expression \(P(\psi, \nabla^2 \phi)\), where \(P\) is the partial differential equation’s scalar product of gradients gradients_product():

\[P(\psi, \nabla^2 \phi) = e_1^2 \, \partial_{u_1} \psi \, \partial_{u_1} \nabla^2 \phi + e_2^2 \, \partial_{u_2} \psi \, \partial_{u_2} \nabla^2 \phi\]

where \(\phi\) and \(\psi\) are two fields defined on the model’s domain, \(u_1, u_2\) are the coordinates of the model, and \(e_1, e_2\) are the inverse of the infinitesimal length of the coordinates (which can be functions of the \(u_1, u_2\) coordinates).

Parameters:

field1 (Field or ParameterField) – First field, advected by the vorticity.
field2 (Field or ParameterField) – Second field with which the vorticity \(\nabla^2\) is computed.
coordinate_system (CoordinateSystem) – Coordinate system on which the model is defined.
sign (int, optional) – Sign in front of the vorticity advection term. Either +1 or -1. Default to +1.
prefactors (tuple(Parameter or Expression), optional) – 2-tuple providing the prefactors in front of each of the two terms composing the Jacobian. This is added on top of the infinitesimal length prefactor. Must be specified as model parameters or symbolic expressions.

Returns:

2-tuple containing arithmetic terms representing each term of the vorticity advection.

Return type:

tuple(ProductOfTerms)