:py:mod:`FELiCS.Equation.Equations.SpeciesEquation`
===================================================

.. py:module:: FELiCS.Equation.Equations.SpeciesEquation


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   FELiCS.Equation.Equations.SpeciesEquation.SpeciesEquation




Attributes
~~~~~~~~~~

.. autoapisummary::

   FELiCS.Equation.Equations.SpeciesEquation.logger


.. py:data:: logger

   

.. py:class:: SpeciesEquation(index, eqColl, fluc, X, species, param)


   Bases: :py:obj:`FELiCS.Equation.Equations.EquationTemplate.EquationTemplate`

   Class representing the species transport equation.

   This class formulates the species transport equation in a tensorial framework,
   capturing the effects of advection, diffusion, and chemical reactions. It supports
   boundary forcing and input-output analysis, while enforcing integration by parts
   to enable more robust numerical handling of fluxes and boundary conditions.

   **Initialize the SpeciesEquation object**

   :param eqColl: The equation collection object.
   :type eqColl: :py:class:`EquationCollection`
   :param fluc: The fluctuations object.
   :type fluc: :py:class:`Fluctuations`
   :param X: The trial/test function in the weak formulation.
   :type X: :py:class:`Function`
   :param species: The species name being transported.
   :type species: :py:class:`str`
   :param param: The configuration and simulation parameters.
   :type param: :py:class:`Parameters`

   :ivar species: Name of the species for which the equation is formulated.
   :vartype species: :py:class:`str`
   :ivar fluc: Fluctuating quantities used in the formulation.
   :vartype fluc: :py:class:`Fluctuations`
   :ivar X: Trial/test function in the variational formulation.
   :vartype X: :py:class:`Function`
   :ivar param: Configuration and problem parameters.
   :vartype param: :py:class:`Parameters`
   :ivar J_hat: Jacobian determinant for integration.
   :vartype J_hat: :py:class:`Expression`
   :ivar all_ds: Boundary integration measure.
   :vartype all_ds: :py:class:`Measure`
   :ivar n: Unit normal vector on boundaries.

   :vartype n: :py:class:`FacetNormal`

   .. admonition:: Notes

      Discontinuous Galerkin schemes are not supported in this tensorial framework.

   .. py:method:: addWeightMatrixExpression(weakForm, mean)

      Add the weight matrix expression to the weak form.

      :param weakForm: The weak form object.
      :type weakForm: :py:class:`Form`
      :param mean: The mean flow object.
      :type mean: :py:class:`MeanFlow`

      .. admonition:: Notes

         Adds the time derivative term to the weak form for the species equation.
         This term incorporates fluctuations weighted by the mean density.


   .. py:method:: addNonlinearExpression()

      Add the nonlinear expression to the weak form.

      .. warning:: This method is currently a placeholder and not implemented.


   .. py:method:: addLinearExpression(weakForm, mean)

      Construct the weak form of the linearized species transport equation.

      :param weakForm: The weak form object.
      :type weakForm: :py:class:`Form`
      :param mean: The mean flow object.
      :type mean: :py:class:`MeanFlow`

      .. admonition:: Notes

         Constructs the weak form using a tensorial formulation. The method
         includes:
         - Integration by parts for advection terms to capture boundary contributions.
         - Volume-only integration of diffusion terms, effectively imposing Neumann boundary conditions.
         - Reaction terms based on a KaiserCnF2023 mechanism if specified.
         - Forcing terms for input-output analysis, including both body and boundary forcing.
         A warning is issued if the case parameter `m > 0`, as it has not been validated.