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 or numeric matrix \(P\) divided by blocks.

Parameters:

• P (ImmutableSparseMatrix or MutableSparseMatrix or ndarray) – 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. Only applies to symbolic matrices. Default to True.

Warning

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