The Bakery

The bakery is where the cake’s layers and the cake itself get baked, to produce models from the partial differential equations.

Layer definition module

This module defines the layer object, i.e. the collection of partial differential equations (represented by Equation objects) which governs the time evolution of a given fluid/media layer of the system at hand. It also computes and includes the ordinary differential equations representation of the partial differential equations, when projected on a given basis (Galerkin procedure).

class layercake.bakery.layers.Layer(name='')

Bases: object

Class to gather partial differential equations modelling a given fluid/media layer of the system at hand.

Parameters:

name (str, optional) – Name for the layer.

equations

A list of the equation objects included in the layer.

Type:

list(Equation)

tensor

The tensor representing the ordinary differential equations tendencies. Can be either a numerical or a symbolic representation, depending on the user’s choice.

Type:

sparse.COO or ImmutableSparseNDimArray

name

Optional name for the layer.

Type:

str

add_equation(equation)

Add an equation object to the layer.

Parameters:

equation (Equation) – Equation object to add to the layer.

compute_inner_products(numerical=True, timeout=None, num_threads=None)

Compute the inner products tensors, either symbolic or numerical ones, of all the terms of the layer equations, including the left-hand side terms. Computations are parallelized on multiple CPUs.

Parameters:

• numerical (bool, optional) – Whether to compute numerical or symbolic inner products. Default to True (numerical 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.

compute_tensor(numerical=True, compute_inner_products=False, compute_inner_products_kwargs=None, substitutions=None, basis_subs=False, parameters_subs=None, lhs_inversion_in_layer=True)

Compute the tensor of the symbolic or numerical representation of the ordinary differential equations tendencies of the layer. Results are stored in the tensor attribute.

Parameters:

• numerical (bool, optional) – Whether to compute the numerical or the symbolic tensor. Default to True (numerical tensor as output).

• compute_inner_products (bool, optional) – Whether the inner products tensors of the layer equations’ terms must be computed first. Default to False. Please note that if the inner products are not computed firsthand, the tensor computation will fail.

• compute_inner_products_kwargs (dict, optional) – Arguments to pass to the computation of the inner products.

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

• basis_subs (bool, optional) – Whether to substitute the parameters appearing in the definition of the basis of functions by their numerical value. Only applies for the symbolic tendencies. Default to False.

• parameters_subs (list(Parameter), optional) – List of model’s parameters to substitute in the symbolic tendencies’ tensor. Only applies for the symbolic tendencies.

• lhs_inversion_in_layer (bool, optional) – Try to inverse the LHS matrix and take the matricial product with the RHS. Default to True.

property fields

Returns the list of dynamical fields of the layer, i.e. the fields whose time evolution is provided by the partial differential equations of the layer.

Type:

list(Field)

property maximum_rank

Maximum over the ranks of the equations in the layer.

Type:

int

property ndim

Dimension of the full ordinary differential equations system of the layer, resulting from the Galerkin expansion.

Type:

int

property number_of_equations

Number of partial differential equations in the layer.

Type:

int

property other_fields

Returns the list of dynamical fields of other layers, i.e. the fields whose time evolution is provided by the partial differential equations of other layers.

Type:

list(Field)

property other_fields_in_lhs

Returns the list of dynamical fields of other layers present in the LHS of the layer’s equations, i.e. the fields whose time evolution is provided by the partial differential equations of other layers.

Type:

list(Field)

property parameters

Returns the list of parameters of the layer, i.e. the explicit parameters appearing in the partial differential equations of the layer.

Type:

list(Parameter)

property parameters_symbols

List of parameter’s symbols present in the layer partial differential equations.

Type:

list(Symbol)

show_latex(enclose_lhs=True, drop_first_lhs_char=True, drop_first_rhs_char=False)

Show the LaTeX string representing the layer’s equations mathematically rendered in a window.

Parameters:

• enclose_lhs (bool, optional) – Whether to enclose the left-hand side term of the equations 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 of the equations. 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 of the equations. Useful to drop the sign in front of it. Default to False.

to_latex(enclose_lhs=True, drop_first_lhs_char=True, drop_first_rhs_char=False)

Generate the LaTeX strings representing the layer’s equations mathematically.

Parameters:

• enclose_lhs (bool, optional) – Whether to enclose the left-hand side term of the equations 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 of the equations. 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 of the equations. Useful to drop the sign in front of it. Default to False.

Returns:

The LaTeX strings representing the layer’s equations.

Return type:

list(str)

Cake definition module

This module defines the cake object, i.e. the collection of stacked layers (represented by Layer objects) of a given fluid/media of the system at hand. A cake is thus a representation of a layered system defined by the user. It also computes and includes the ordinary differential equations representation of the partial differential equations contained in the layers, when projected on a given basis (Galerkin procedure).

class layercake.bakery.cake.Cake

Bases: object

Class to gather layers of a given fluid/media of the system at hand.

layers

A list of the layer objects included in the cake.

Type:

list(Layer)

add_layer(layer)

Add a layer object to the cake.

Parameters:

layer (Layer) – Layer object to add to the cake.

compute_tendencies(language='python', lang_translation=None, force_symbolic_output=False)

Function handling the tendencies tensor to create a tendencies function for the whole cake. Returns the tendencies function \(\boldsymbol{f}\) determining the model’s ordinary differential equations:

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(\boldsymbol{x})\]

It returns also the linearized tendencies \(\boldsymbol{\mathrm{J}} \equiv \boldsymbol{\mathrm{D}f} = \frac{\partial \boldsymbol{f}}{\partial \boldsymbol{x}}\) (Jacobian matrix).

Depending on whether the tendencies tensor is symbolic or numerical, it will return either Numbafied callable for the functions \(\boldsymbol{f}\) and \(J\), or list of strings defining each tendency in a computing language selected by the user.

Parameters:

• language (str, optional) – String defining in which computing language the tendencies lists must be returned. Currently, it can be ‘python’, ‘fortran’ or ‘julia’. Default to ‘python’.

• lang_translation (dict(str), optional) – Additional language translation mapping provided by the user, mapping replacements for converting Sympy symbolic output strings to the target language.

• force_symbolic_output (bool, optional) – Force the return of symbolic tendencies, even if the tensor is numerical. Useful to use the results with another language, or to save it in plain text. Default to False.

Returns:

• f (callable or list(str), list(Symbol)) – If the tendencies tensor is numerical, the numba-jitted tendencies function. If the tendencies tensor is symbolic, or if force_symbolic is True, the list of tendencies string in the selected target language, along with the list of parameters appearing in them.

• Df (callable or list(str), list(Symbol)) – If the tendencies tensor is numerical, the numba-jitted linearized tendencies function. If the tendencies tensor is symbolic, or if force_symbolic is True, the list of linearized tendencies string in the selected target language, along with the list of parameters appearing in them.

compute_tensor(numerical=True, compute_inner_products=False, compute_inner_products_kwargs=None, substitutions=None, basis_subs=False, parameters_subs=None, lhs_inversion_in_layer=True)

Compute the tensor of the symbolic or numerical representation of the ordinary differential equations tendencies of all the layers. Arguments are passed to the layer compute_tensor() method.

Parameters:

• numerical (bool, optional) – Whether to compute the numerical or the symbolic tensor. Default to True (numerical tensor as output).

• compute_inner_products (bool, optional) – Whether the inner products tensors of the layer equations’ terms must be computed first. Default to False. Please note that if the inner products are not computed firsthand, the tensor computation will fail.

• compute_inner_products_kwargs (dict, optional) – Arguments to pass to the computation of the inner products.

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

• basis_subs (bool, optional) – Whether to substitute the parameters appearing in the definition of the basis of functions by their numerical value. Only applies for the symbolic tendencies. Default to False.

• parameters_subs (list(Parameter), optional) – List of model’s parameters to substitute in the symbolic tendencies’ tensor. Only applies for the symbolic tendencies.

• lhs_inversion_in_layer (bool, optional) – Try to inverse the LHS matrix and take the matricial product with the RHS in each layer if possible. Default to True. If False, it forces the inversion of the LHS at the cake level.

property fields

Returns the list of dynamical fields of the cake, i.e. the fields whose time evolution is provided by the partial differential equations of all the layers.

Type:

list(Field)

property fields_tensor_extent

A dictionary of 2-tuples giving for each dynamical field of the model its entries range in the tensor of tendencies.

Type:

dict(tuple(int))

property jacobian_tensor

Return the tensor representing the Jacobian matrix of the ordinary differential equations tendencies of the whole cake. Can be either a numerical or a symbolic representation, depending on the user’s choice for the inner products.

Type:

sparse.COO or ImmutableSparseNDimArray

property maximum_rank

Maximum over the ranks of the equations over all the layers.

Type:

int

property ndim

Dimension of the full ordinary differential equations system of the cake, resulting from the Galerkin expansions of the layers.

Type:

int

property number_of_equations

Total number of equations composing the cake.

Type:

int

property number_of_layers

Number of layers in the cake.

Type:

int

property parameters

Returns the list of parameters of the cake, i.e. the explicit parameters appearing in the partial differential equations of all the layers.

Type:

list(Parameter)

property parameters_symbols

List of parameter’s symbols present in all the layers’ partial differential equations.

Type:

list(Symbol)

print_jacobian_tensor(tensor_name='', to_numerics=False)

Routine to print the Jacobian tensor.

Parameters:

• tensor_name (str, optional) – Specify the name to print beside the values of the tensor. Default to TensorJacobian.

• to_numerics (bool) – Try to output a numerical value for the tensor entries, even if the tensor is a symbolic one.

print_jacobian_tensor_to_file(filename, tensor_name='', to_numerics=False)

Routine to print the Jacobian tensor to a file.

Parameters:

• filename (str) – The filename where to print the tensor.

• tensor_name (str, optional) – Specify the name to print beside the values of the tensor. Default to TensorJacobian.

• to_numerics (bool) – Try to output a numerical value for the tensor entries, even if the tensor is a symbolic one.

print_tensor(tensor_name='', to_numerics=False)

Routine to print the tensor.

Parameters:

• tensor_name (str, optional) – Specify the name to print beside the values of the tensor. Default to Tensor.

• to_numerics (bool) – Try to output a numerical value for the tensor entries, even if the tensor is a symbolic one.

print_tensor_to_file(filename, tensor_name='', to_numerics=False)

Routine to print the tensor to a file.

Parameters:

• filename (str) – The filename where to print the tensor.

• tensor_name (str, optional) – Specify the name to print beside the values of the tensor. Default to Tensor.

• to_numerics (bool) – Try to output a numerical value for the tensor entries, even if the tensor is a symbolic one.

show_latex(enclose_lhs=True, drop_first_lhs_char=True, drop_first_rhs_char=False)

Show the LaTeX string representing the cake’s equations mathematically rendered in a window.

Parameters:

• enclose_lhs (bool, optional) – Whether to enclose the left-hand side term of the equations 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 of the equations. 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 of the equations. Useful to drop the sign in front of it. Default to False.

static simplify_tensor(tensor, threshold=None)

Routine that simplifies the component of a tensor \(\mathcal{T}\). For each index \(i\), it upper-triangularizes the tensor \(\mathcal{T}_{i,\ldots}\) for all the subsequent indices.

Parameters:

• tensor (sparse.COO or ImmutableSparseNDimArray) – The tensor to simplify.

• threshold (float, optional) – If the absolute value of a tensor entry is lower than this threshold value, then this value is removed from the tensor. No threshold is applied if not set. Only applies to numerical tensors. Useful to filter small spurious results of numerical integrations.

Returns:

The upper-triangularized tensor.

Return type:

sparse.COO or ImmutableSparseNDimArray

property tensor

Return the tensor representing the ordinary differential equations tendencies of the whole cake. Can be either a numerical or a symbolic representation, depending on the user’s choice for the inner products.

Type:

sparse.COO or ImmutableSparseNDimArray

to_latex(enclose_lhs=True, drop_first_lhs_char=True, drop_first_rhs_char=False)

Generate the LaTeX strings representing the cake’s equations mathematically.

Parameters:

• enclose_lhs (bool, optional) – Whether to enclose the left-hand side term of the equations 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 of the equations. 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 of the equations. Useful to drop the sign in front of it. Default to False.

Returns:

The LaTeX strings representing the cake’s equations. It is a dictionary with one entry per cake’s layer.

Return type:

dict(list(str))