General utility module

Module with various submodules with useful functions used throughout the code.

Sparse tensor utility module

Defines useful functions to deal with sparse tensors, defined by a coordinates-values list provided as a Numpy array.

layercake.utils.tensor.jsparse_mul(vec, coo, value)

Sparse multiplication of a tensor with a vector, resulting in a matrix.

Warning

It is a Numba-jitted function, so it cannot take a sparse.COO sparse tensor directly. The tensor coordinates list and values must be provided separately by the user.

Parameters:

• vec (ndarray(float)) – The vector to contract the tensor with. Must be of shape (ndim,) where ndim is the second dimension of the tensor.

• coo (ndarray(int)) – A 2D array of shape (n_elems, rank), a list of n_elems tensor coordinates corresponding to each value provided, and rank the rank of the tensor.

• value (ndarray(float)) – A 1D array of shape (n_elems,), a list of value in the tensor.

Returns:

The resulting tensor.

Return type:

ndarray(float)

layercake.utils.tensor.sparse_mul(vec, coo, value)

Sparse multiplication of a tensor with a vector, resulting into a vector.

Warning

It is a Numba-jitted function, so it cannot take a sparse.COO sparse tensor directly. The tensor coordinates list and values must be provided separately by the user.

Parameters:

• vec (ndarray(float)) – The vector to contract the tensor with. Must be of shape (ndim,) where ndim is the second dimension of the tensor.

• coo (ndarray(int)) – A 2D array of shape (n_elems, rank), a list of n_elems tensor coordinates corresponding to each value provided, and rank the rank of the tensor.

• value (ndarray(float)) – A 1D array of shape (n_elems,), a list of value in the tensor

Returns:

The result vector of shape (ndim,).

Return type:

ndarray(float)

Symbolic tensor utility module

Defines useful functions to deal with Sympy symbolic tensors.

layercake.utils.symbolic_tensor.compute_jacobian_permutations(shape)

Return the axes permutations needed to compute the Jacobian tensor associated to the symbolic models tendencies’ tensor.

Parameters:

shape (tuple) – The shape of the tendencies’ tensor.

Returns:

The list of permutations of the axes needed to compute the models Jacobian matrix.

Return type:

list(list(int))

layercake.utils.symbolic_tensor.get_coords_and_values_from_tensor(tensor, output='tuple')

Get the coordinates and values of a Sympy sparse tensor, as a coordinates-values list.

Warning

This a function implemented to compensate for the lack of such feature in Sympy, and which might need to be reimplemented or replaced in the future.

Parameters:

• tensor (ImmutableSparseNDimArray or MutableSparseNDimArray) – The tensor from which to return the coordinates and values list.

• output (str) –

  The kind of output. Can be:

  • numpy: return the list as a Numpy array.

  • list: return the list as nested Python lists.

  • tuple: return the list as a list of tuples.

  Default to tuple.

Returns:

The coordinates-values list.

Return type:

list(list) or list(tuple) or ndarray

layercake.utils.symbolic_tensor.get_coords_from_index(dic_index, ndim, shape_len)

Get the coordinates of a Sympy sparse tensor entry along each axis, given its private dictionary index.

Notes

Assumes that every axis has the same length ndim.

Warning

Assumes that the private dictionary has a certain indexing rationale, which may change over time in Sympy

Parameters:

• dic_index (int) – Index of the sought entry in the sparse tensor private dictionary.

• ndim (int) – The length of the axes.

• shape_len (int) – Rank of the tensor.

layercake.utils.symbolic_tensor.remove_dic_zeros(dic)

Removes zero values from dictionary

Parameters:

dic (dict) – Dictionary which could include zeroes in values to remove.

Returns:

Dictionary with same keys and values as input, but keys with zero value are removed.

Return type:

dict

layercake.utils.symbolic_tensor.symbolic_tensordot(a, b, axes=2)

Compute tensor dot product along specified axes of two sympy symbolic arrays

This is based on Numpy tensordot() .

Parameters:

• a (ImmutableDenseNDimArray or MutableDenseNDimArray or ImmutableSparseNDimArray or MutableSparseNDimArray) – Arrays to take the dot product of.

• b (ImmutableDenseNDimArray or MutableDenseNDimArray or ImmutableSparseNDimArray or MutableSparseNDimArray) – Arrays to take the dot product of.

• axes (int or 2-tuple) – If an integer is provided, sum over the last axes axes of a and the first axes axes of b in order. Else, specify the axes to be summed by a 2-tuple of tuples containing the axes. The sizes of the corresponding axes must match.

Returns:

The tensor dot product of the input.

Return type:

ImmutableDenseNDimArray or MutableDenseNDimArray or ImmutableSparseNDimArray or MutableSparseNDimArray

Commutativity utility module

Defines useful functions to deal with enabling or disabling commutativity in Sympy expressions.

layercake.utils.commutativity.disable_commutativity(expr)

Disable commutativity of a given Sympy expression.

Parameters:

expr (Expr) – The expression on which to disable commutativity.

Returns:

The expression with the commutativity disabled.

Return type:

Expr

layercake.utils.commutativity.enable_commutativity(expr)

Enable commutativity of a given Sympy expression.

Parameters:

expr (Expr) – The expression on which to enable commutativity.

Returns:

The expression with the commutativity enabled.

Return type:

Expr

Parallel computations utility module

Defines low-level functions to deal with parallel computation tasks.

Warning

Those are low-level computation routines which are not user-friendly. Usage must be thoroughly tested.

layercake.utils.parallel.exit_after(s)

use as decorator to exit process if function takes longer than s seconds

layercake.utils.parallel.parallel_integration(pool, args_list, substitutions, destination, timeout, permute=False, symbolic_int=False)

Functions to integrate Sympy expressions, either symbolically or numerically, in parallel.

Parameters:

• pool (pebble.ProcessPool) – A Pebble pool of workers.

• args_list (list(tuple)) –

  A list of tuples with the following arguments for the integration subfunctions:

  • indices: Tuple of integers labelling the integrations in the integration queue. Will be returned by the worker.

  • integrals_definition: A callable returning the integral(s) as a Sympy expression.

  • integrals_arguments: A tuple with the arguments to be provided to the integrals_definition callable.

• substitutions (list(tuple)) – 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.

• destination (None or sparse.DOK or ndarray) – Place where to store the output. If an array is provided, it will append the output of the integrations to it. If None, it will create a new dictionary and return it. If symbolic_int is True, then destination should be None.

• timeout (None or bool or int) –

  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) – Permute the indices provided, except the first one, and return the result for all these indices. Default to False.

• symbolic_int (bool, optional) – Force symbolic integration and do not substitute the substitutions at the end, making the output a list of Sympy expressions. Default to False.

Returns:

A list with the results, as 2-tuple with the labelling indices and the output of the integration, either as a float or as a Sympy integration.

Return type:

tuple(2-tuple)

layercake.utils.parallel.parallel_symbolic_evaluation(pool, indices_list, inner_product, basis, numerical, term)

Functions to evaluate Sympy inner products expressions inside tensors in parallel.

Parameters:

• pool (concurrent.futures.ThreadPoolExecutor or concurrent.futures.ProcessPoolExecutor) – A pool of workers.

• indices_list (list(tuple)) – A list of tuples with the indices of the tensor entries.

• inner_product (callable) – A callable defining the inner products.

• basis (list(SymbolicBasis)) – List of symbolic function basis on which each element of the term(s) inner products must be decomposed.

• numerical (bool) – Whether to compute numerical or symbolic inner products.

• term (ArithmeticTerms) – Arithmetic term(s) from which the inner products will be computed.

Returns:

A list with the results, as 2-tuple with the labelling indices and the output of the evaluation.

Return type:

tuple(2-tuple)

Integration module

Defines low-level functions to deal with integrations.

Warning

Those are low-level computation routines which are not user-friendly. Usage must be thoroughly tested.

layercake.utils.integration.integration(args_list, substitutions, destination, permute=False, symbolic_int=False)

Functions to integrate Sympy expressions, either symbolically or numerically.

Parameters:

• args_list (list(tuple)) –

  A list of tuples with the following arguments for the integration subfunctions:

  • indices: Tuple of integers labelling the integrations in the integration queue. Will be returned by the worker.

  • integrals_definition: A callable returning the integral(s) as a Sympy expression.

  • integrals_arguments: A tuple with the arguments to be provided to the integrals_definition callable.

• substitutions (list(tuple)) – 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.

• destination (None or sparse.DOK or ndarray) – Place where to store the output. If an array is provided, it will append the output of the integrations to it. If None, it will create a new dictionary and return it. If symbolic_int is True, then destination should be None.

• permute (bool, optional) – Permute the indices provided, except the first one, and return the result for all these indices. Default to False.

• symbolic_int (bool, optional) – Force symbolic integration and do not substitute the substitutions at the end, making the output a list of Sympy expressions. Default to False.

Returns:

A list with the results, as 2-tuple with the labelling indices and the output of the integration, either as a float or as a Sympy integration.

Return type:

tuple(2-tuple)

layercake.utils.integration.numerical_integration(ls)

Return the result of a numerical integration.

Parameters:

ls (list or tuple) –

A list or a tuple with the following arguments for the integration:

• indices: Tuple of integers labelling the integration. Will be returned by the worker.

• integrals_definition: A callable returning the integral(s) as a Sympy expression.

• integrals_arguments: A tuple with the arguments to be provided to the integrals_definition callable.

• substitutions: List of 2-tuples containing symbolic substitutions to be made before numerically integrating. The 2-tuples contain first a Sympy expression and then the value to substitute.

Returns:

• tuple(int) – The integers labelling the integration.

• float – The outcome of the numerical integration.

layercake.utils.integration.symbolic_integration(ls)

Return the result of a symbolic integration.

Parameters:

ls (list or tuple) –

A list or a tuple with the following arguments for the integration:

• indices: Tuple of integers labelling the integration. Will be returned by the worker.

• integrals_definition: A callable returning the integral(s) as a Sympy expression.

• integrals_arguments: A tuple with the arguments to be provided to the integrals_definition callable.

• substitutions: List of 2-tuples containing symbolic substitutions to be made before numerically integrating. The 2-tuples contain first a Sympy expression and then the value to substitute. This is used to check and bypass integrations that are giving zero values.

Returns:

• tuple(int) – The integers labelling the integration.

• ~sympy.core.expr.Expr – The outcome of the symbolic integration.

Matrix module

Defines useful functions to deal with symbolic matrices.

layercake.utils.matrix.block_matrix_inverse(P, blocks_extent, simplify=True)

Function to invert a symbolic matrix \(P\) divided by blocks.

Parameters:

• P (ImmutableSparseMatrix or MutableSparseMatrix) – The block matrix to invert.

• blocks_extent (list(tuple)) – The extent of each block, as a list of 2-tuple.

• simplify (bool, optional) – Try to simplify the inverse. Default to True.

Warning

If the simplify argument is set to False, this function will not check if the matrix \(P\) is invertible !