FELiCS.Misc.tensorUtils

Module Contents

Classes

SpectralIndicator	Enumeration describing the role of each dimension in a tensor or coordinate system.
CoordinateSystem	The CoordinateSystem class supports two coordinate systems,
Tensor	Tensor object that extends UFL tensors.

Functions

iDot(tensorA, tensorB)	Performs a single contraction between two tensors.
iInner(tensorA, tensorB)	Computes the inner product between two second-order tensors.
iGrad(T)	Computes the gradient of a tensor.
iDiv(tensor)	Computes the divergence of a tensor.
iT(tensor)	Returns the transpose of a second-order tensor.
iTr(tensor)	Computes the trace of a second-order tensor.
iIdentity(tensor)	Returns the identity tensor corresponding to the tensor's dimension and coordinate system.
iConj(tensor)	Computes the complex conjugate of a tensor.
iOuter(tensorA, tensorB)	Computes the outer product of two tensors.

class FELiCS.Misc.tensorUtils.SpectralIndicator(*args, **kwds)

Bases: enum.Enum

Enumeration describing the role of each dimension in a tensor or coordinate system.

This enum is used to mark whether a given axis corresponds to a geometric, spectral, or inactive (zero) dimension. It is primarily used internally by the Tensor class to determine how derivatives and spectral terms should be handled.

Members

SPECTRALint

Marks a dimension as a spectral dimension. Derivatives along this axis are replaced by i * m / r terms.

NOTSPECTRALint

Marks a dimension as a regular geometric dimension.

ZEROint

Marks a dimension that is neither geometric nor spectral (e.g. padding dimensions for tensors whose true dimension exceeds the geometric one).

SPECTRAL = 1

NOTSPECTRAL = 2

ZERO = 3

class FELiCS.Misc.tensorUtils.CoordinateSystem(SpatialCoordinateObj, name: str, gdim: int, trueDim=None, m=0)

The CoordinateSystem class supports two coordinate systems, ‘cartesian’ and ‘cylindricalfelics’.

Parameters:

• SpatialCoordinateObj (ufl.SpatialCoordinate) – Coordinate vector of the mesh.

• name (str) – Name of the coordinate system (“cartesian”, “cylindricalfelics”).

• gdim (int) – Geometrical dimension of the mesh.

• trueDim (int, optional) – True dimension of the system, including a possible spectral dimension.

• m (int, optional) – Wave number for spectral direction.

Raises:

ValueError – When object is initialized: if the coordinate system name is not recognized.

property m

Returns the wave number m, used in the spectral dimension.

Returns:

The wave number.

Return type:

int

setTrueDimension(dim)

Corrects the true dimension of the system. This has to be called if a spectral dimension is included, in which case the true dimension is higher than the geometrical dimension of the mesh.

Parameters:

dim (int) – True dimension of the system, including a possible spectral dimension.

class FELiCS.Misc.tensorUtils.Tensor(ufl_tens, CoordSys: CoordinateSystem, mayHaveSpectralDimension=False, m=None)

Tensor object that extends UFL tensors.

Supports scalar, vector, and matrix-valued tensors in both physical and spectral settings, including an optional spectral dimension.

Variables:

• ufl_tens (ufl.Expr) – The underlying UFL tensor expression.

• CoordSys (CoordinateSystem) – Coordinate system in which this tensor is defined.

• hasSpectralDimension (bool) – Whether this tensor actually carries a spectral dependence (i.e. a factor of exp(i * m * sdim)), as determined from mayHaveSpectralDimension and the coordinate system.

• isSpectralDimension (list of SpectralIndicator) – Per-dimension indicator specifying whether each axis is spectral, geometric, or zero (non-geometric, non-spectral).

• m (int) – Wave number associated with the spectral dimension (if present).

• dim (int) – Total dimension of the system (geometric + spectral).

• order (int) – Tensor order, inferred from ufl_tens.ufl_shape (0, 1, or 2).

Example

>>> T = Tensor(u, CoordSys)
>>> grad_T = iGrad(T)

FELiCS.Misc.tensorUtils.iDot(tensorA: Tensor, tensorB: Tensor)

Performs a single contraction between two tensors.

The function supports dot products between tensors of order 1 or 2.

Parameters:

• tensorA (Tensor) – First tensor operand.

• tensorB (Tensor) – Second tensor operand.

Returns:

Result of the dot product, with updated metadata.

Return type:

Tensor

FELiCS.Misc.tensorUtils.iInner(tensorA: Tensor, tensorB: Tensor)

Computes the inner product between two second-order tensors.

Parameters:

• tensorA (Tensor) – First tensor operand of order 2.

• tensorB (Tensor) – Second tensor operand of order 2.

Returns:

Scalar-valued (order-0) tensor representing the inner product.

Return type:

Tensor

Raises:

ValueError – If the tensors are not both of order 2.

FELiCS.Misc.tensorUtils.iGrad(T: Tensor)

Computes the gradient of a tensor.

Parameters:

T (Tensor) – The tensor to differentiate.

Returns:

Gradient of the input tensor.

Return type:

Tensor

Raises:

ValueError – If the tensor is of order > 2 (not implemented).

FELiCS.Misc.tensorUtils.iDiv(tensor: Tensor)

Computes the divergence of a tensor.

Computes the gradient and sums of the last two indices of a tensor.

Parameters:

tensor (Tensor) – Tensor of order 1 or 2.

Returns:

The divergence result as a tensor of order reduced by one reduced.

Return type:

Tensor

Raises:

ValueError – If called on a scalar tensor (order 0).

FELiCS.Misc.tensorUtils.iT(tensor: Tensor)

Returns the transpose of a second-order tensor.

Parameters:

tensor (Tensor) – A tensor of order 2.

Returns:

Transposed tensor.

Return type:

Tensor

Raises:

ValueError – If tensor order is not 2.

FELiCS.Misc.tensorUtils.iTr(tensor: Tensor)

Computes the trace of a second-order tensor.

Parameters:

tensor (Tensor) – Tensor of order 2.

Returns:

Scalar-valued tensor (trace result).

Return type:

Tensor

Raises:

ValueError – If the input tensor is not of order 2.

FELiCS.Misc.tensorUtils.iIdentity(tensor: Tensor)

Returns the identity tensor corresponding to the tensor’s dimension and coordinate system.

Parameters:

tensor (Tensor) – Input tensor, used to infer dimensionality and coordinate system.

Returns:

Identity tensor with the same coordinate system and dimension.

Return type:

Tensor

FELiCS.Misc.tensorUtils.iConj(tensor: Tensor)

Computes the complex conjugate of a tensor.

The underlying UFL expression is conjugated and the sign of the spectral wave number m is flipped.

Parameters:

tensor (Tensor) – Tensor to conjugate.

Returns:

Conjugated tensor, with the same coordinate system and spectral flags but with m replaced by -m.

Return type:

Tensor

FELiCS.Misc.tensorUtils.iOuter(tensorA: Tensor, tensorB: Tensor)

Computes the outer product of two tensors.

Parameters:

• tensorA (Tensor) – Left operand tensor.

• tensorB (Tensor) – Right operand tensor.

Returns:

Outer product tensor.

Return type:

Tensor

Raises:

Exception – If scalar multiplication is attempted using this function.