:py:mod:`FELiCS.Misc.tensorUtils` ================================= .. py:module:: FELiCS.Misc.tensorUtils Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: FELiCS.Misc.tensorUtils.SpectralIndicator FELiCS.Misc.tensorUtils.CoordinateSystem FELiCS.Misc.tensorUtils.Tensor Functions ~~~~~~~~~ .. autoapisummary:: FELiCS.Misc.tensorUtils.iDot FELiCS.Misc.tensorUtils.iInner FELiCS.Misc.tensorUtils.iGrad FELiCS.Misc.tensorUtils.iDiv FELiCS.Misc.tensorUtils.iT FELiCS.Misc.tensorUtils.iTr FELiCS.Misc.tensorUtils.iIdentity FELiCS.Misc.tensorUtils.iConj FELiCS.Misc.tensorUtils.iOuter .. py:class:: SpectralIndicator(*args, **kwds) Bases: :py:obj:`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 :class:`Tensor` class to determine how derivatives and spectral terms should be handled. Members ------- SPECTRAL : int Marks a dimension as a spectral dimension. Derivatives along this axis are replaced by ``i * m / r`` terms. NOTSPECTRAL : int Marks a dimension as a regular geometric dimension. ZERO : int Marks a dimension that is neither geometric nor spectral (e.g. padding dimensions for tensors whose true dimension exceeds the geometric one). .. py:attribute:: SPECTRAL :value: 1 .. py:attribute:: NOTSPECTRAL :value: 2 .. py:attribute:: ZERO :value: 3 .. py:class:: CoordinateSystem(SpatialCoordinateObj, name: str, gdim: int, trueDim=None, m=0) The `CoordinateSystem` class supports two coordinate systems, 'cartesian' and 'cylindricalfelics'. :param SpatialCoordinateObj: Coordinate vector of the mesh. :type SpatialCoordinateObj: :py:class:`ufl.SpatialCoordinate` :param name: Name of the coordinate system ("cartesian", "cylindricalfelics"). :type name: :py:class:`str` :param gdim: Geometrical dimension of the mesh. :type gdim: :py:class:`int` :param trueDim: True dimension of the system, including a possible spectral dimension. :type trueDim: :py:class:`int`, *optional* :param m: Wave number for spectral direction. :type m: :py:class:`int`, *optional* :raises ValueError: When object is initialized: if the coordinate system name is not recognized. .. py:property:: m Returns the wave number `m`, used in the spectral dimension. :returns: The wave number. :rtype: :py:class:`int` .. py:method:: 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. :param dim: True dimension of the system, including a possible spectral dimension. :type dim: :py:class:`int` .. py:class:: 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. :ivar ufl_tens: The underlying UFL tensor expression. :vartype ufl_tens: :py:class:`ufl.Expr` :ivar CoordSys: Coordinate system in which this tensor is defined. :vartype CoordSys: :py:class:`CoordinateSystem` :ivar hasSpectralDimension: 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. :vartype hasSpectralDimension: :py:class:`bool` :ivar isSpectralDimension: Per-dimension indicator specifying whether each axis is spectral, geometric, or zero (non-geometric, non-spectral). :vartype isSpectralDimension: :py:class:`list` of :py:class:`SpectralIndicator` :ivar m: Wave number associated with the spectral dimension (if present). :vartype m: :py:class:`int` :ivar dim: Total dimension of the system (geometric + spectral). :vartype dim: :py:class:`int` :ivar order: Tensor order, inferred from ``ufl_tens.ufl_shape`` (0, 1, or 2). :vartype order: :py:class:`int` .. admonition:: Example >>> T = Tensor(u, CoordSys) >>> grad_T = iGrad(T) .. py:function:: iDot(tensorA: Tensor, tensorB: Tensor) Performs a single contraction between two tensors. The function supports dot products between tensors of order 1 or 2. :param tensorA: First tensor operand. :type tensorA: :py:class:`Tensor` :param tensorB: Second tensor operand. :type tensorB: :py:class:`Tensor` :returns: Result of the dot product, with updated metadata. :rtype: :py:class:`Tensor` .. py:function:: iInner(tensorA: Tensor, tensorB: Tensor) Computes the inner product between two second-order tensors. :param tensorA: First tensor operand of order 2. :type tensorA: :py:class:`Tensor` :param tensorB: Second tensor operand of order 2. :type tensorB: :py:class:`Tensor` :returns: Scalar-valued (order-0) tensor representing the inner product. :rtype: :py:class:`Tensor` :raises ValueError: If the tensors are not both of order 2. .. py:function:: iGrad(T: Tensor) Computes the gradient of a tensor. :param T: The tensor to differentiate. :type T: :py:class:`Tensor` :returns: Gradient of the input tensor. :rtype: :py:class:`Tensor` :raises ValueError: If the tensor is of order > 2 (not implemented). .. py:function:: iDiv(tensor: Tensor) Computes the divergence of a tensor. Computes the gradient and sums of the last two indices of a tensor. :param tensor: Tensor of order 1 or 2. :type tensor: :py:class:`Tensor` :returns: The divergence result as a tensor of order reduced by one reduced. :rtype: :py:class:`Tensor` :raises ValueError: If called on a scalar tensor (order 0). .. py:function:: iT(tensor: Tensor) Returns the transpose of a second-order tensor. :param tensor: A tensor of order 2. :type tensor: :py:class:`Tensor` :returns: Transposed tensor. :rtype: :py:class:`Tensor` :raises ValueError: If tensor order is not 2. .. py:function:: iTr(tensor: Tensor) Computes the trace of a second-order tensor. :param tensor: Tensor of order 2. :type tensor: :py:class:`Tensor` :returns: Scalar-valued tensor (trace result). :rtype: :py:class:`Tensor` :raises ValueError: If the input tensor is not of order 2. .. py:function:: iIdentity(tensor: Tensor) Returns the identity tensor corresponding to the tensor's dimension and coordinate system. :param tensor: Input tensor, used to infer dimensionality and coordinate system. :type tensor: :py:class:`Tensor` :returns: Identity tensor with the same coordinate system and dimension. :rtype: :py:class:`Tensor` .. py:function:: 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. :param tensor: Tensor to conjugate. :type tensor: :py:class:`Tensor` :returns: Conjugated tensor, with the same coordinate system and spectral flags but with ``m`` replaced by ``-m``. :rtype: :py:class:`Tensor` .. py:function:: iOuter(tensorA: Tensor, tensorB: Tensor) Computes the outer product of two tensors. :param tensorA: Left operand tensor. :type tensorA: :py:class:`Tensor` :param tensorB: Right operand tensor. :type tensorB: :py:class:`Tensor` :returns: Outer product tensor. :rtype: :py:class:`Tensor` :raises Exception: If scalar multiplication is attempted using this function.