:py:mod:`FELiCS.Fields.Mode` ============================ .. py:module:: FELiCS.Fields.Mode Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: FELiCS.Fields.Mode.ModeType FELiCS.Fields.Mode.AnalysisType FELiCS.Fields.Mode.Mode Attributes ~~~~~~~~~~ .. autoapisummary:: FELiCS.Fields.Mode.logger .. py:data:: logger .. py:class:: ModeType(*args, **kwds) Bases: :py:obj:`enum.Enum` Enumeration of mode roles in the analysis. Members ------- NONE : 0 No specific mode type. DIRECT : 1 Direct eigenmode. ADJOINT : 2 Adjoint eigenmode. RESPONSE : 3 Response mode in resolvent or input–output analysis. FORCING : 4 Forcing mode in resolvent or input–output analysis. .. py:attribute:: NONE :value: 0 .. py:attribute:: DIRECT :value: 1 .. py:attribute:: ADJOINT :value: 2 .. py:attribute:: RESPONSE :value: 3 .. py:attribute:: FORCING :value: 4 .. py:class:: AnalysisType(*args, **kwds) Bases: :py:obj:`enum.Enum` Enumeration of analysis types supported for modes. Members ------- NONE : 0 No analysis type. MODAL : 1 Modal (eigenvalue) analysis. RESOLVENT : 2 Resolvent analysis. INPUT_OUTPUT : 3 Input–output analysis. .. py:attribute:: NONE :value: 0 .. py:attribute:: MODAL :value: 1 .. py:attribute:: RESOLVENT :value: 2 .. py:attribute:: INPUT_OUTPUT :value: 3 .. py:class:: Mode(FEMSpace, mesh, name='q_hat', isStateVector=True, m=0, analysisType='Modal', modeType=None) Bases: :py:obj:`FELiCS.Fields.Field.Field` Field-based representation of a computational mode. This class extends :class:`Field` to represent modes in a FEM-based analysis, such as eigenmodes, forcing modes or response modes. It stores additional metadata such as gain, frequency, eigenvalue, wave number, and error metrics, together with an analysis type and a mode type. **Initialize the Mode object** :param FEMSpace: The finite element space defining the discretization. :type FEMSpace: :py:class:`dolfinx.fem.FunctionSpace` :param mesh: Mesh on which the FEM space is defined. :type mesh: :py:class:`FELiCS.SpaceDisc.FELiCSMesh` :param name: Name of the underlying field. Default is ``"q_hat"``. :type name: :py:class:`str`, *optional* :param isStateVector: If True, this mode is treated as a state vector in a mixed formulation. Default is True. :type isStateVector: :py:class:`bool`, *optional* :param m: Wave number associated with a spectral spatial dimension. Default is 0. :type m: :py:class:`int`, *optional* :param analysisType: Type of analysis for which this mode is defined. The string is mapped (case-insensitively) to :class:`AnalysisType` (e.g. ``'Modal'``, ``'Resolvent'``). Default is ``'Modal'``. :type analysisType: :py:class:`str`, *optional* :param modeType: Mode role within the chosen analysis type, mapped to :class:`ModeType` (e.g. ``'direct'``, ``'adjoint'``, ``'response'``, ``'forcing'``). If ``None``, a sensible default is chosen based on ``analysisType``. :type modeType: :py:class:`str` or :py:obj:`None`, *optional* :ivar analysisType: The specific analysis type enum associated with this mode. :vartype analysisType: :py:class:`AnalysisType` :ivar modeType: The specific role of the mode (e.g. DIRECT, ADJOINT, FORCING). :vartype modeType: :py:class:`ModeType` :ivar waveNumber: Wave number associated with the mode (initialized by `m`). :vartype waveNumber: :py:class:`int` :ivar namesOfSubFields: List of names of the subfields (variables) constituting the mode. :vartype namesOfSubFields: :py:class:`list` :ivar omega: Property returning the eigenvalue (Modal) or frequency (Resolvent/IO). :vartype omega: :py:class:`float` :ivar gain: Property returning the mode gain (returns -9999. if undefined). :vartype gain: :py:class:`float` :ivar error: Property returning the error associated with the mode (returns -9999. if undefined). :vartype error: :py:class:`float` .. py:property:: name Name of the mode. For state-vector modes (``isStateVector`` is True), this is always returned as ``"q_hat"``, irrespective of the underlying field name. Otherwise, the name from the base :class:`Field` class is used. .. py:property:: omega Angular frequency associated with the mode. For modal analysis, this is the eigenvalue. For resolvent and input–output analysis, this is the real frequency. :returns: Eigenvalue (modal) or frequency (resolvent / input–output). :rtype: :py:class:`float` .. py:property:: gain Gain associated with the mode. :returns: The mode gain. If undefined, returns ``-9999.`` and issues a warning. :rtype: :py:class:`float` .. py:property:: gainNumber Get the gain number of the mode. :returns: Gain number of the mode. Returns -1 if undefined. :rtype: :py:class:`int` .. py:property:: frequency Get the frequency of the mode. :returns: Frequency of the mode. Returns -9999. if undefined. :rtype: :py:class:`float` .. py:property:: eigenValue Get the eigenvalue of the mode. :returns: Eigenvalue of the mode. Returns -9999. if undefined. :rtype: :py:class:`float` .. py:property:: waveNumber Get the wave number of the mode. :returns: Wave number of the mode. Returns -9999. if undefined. :rtype: :py:class:`float` .. py:property:: guess Get the initial guess of the mode. :returns: Initial guess used. Returns -9999. if undefined. :rtype: :py:class:`float` .. py:property:: error Get the error associated with the mode. :returns: Error of the mode. Returns -9999. if undefined. :rtype: :py:class:`float` .. py:method:: describe() Log a summary of the mode's properties. Prints the mode type, and depending on the analysis type, logs relevant metrics such as guess and eigenvalue (Modal) or frequency, gain, and gain number (Resolvent/Input-Output). .. py:method:: exportToH5(writer, fileName=None) Export the mode to an HDF5 file. If no file name is provided, a default name is constructed from the analysis type, mode type, and frequency/eigenvalue (and gain number for resolvent modes). Mode metadata such as omega and, where applicable, gain and gain number are written as attributes. :param writer: Writer object providing an ``exportFieldToH5(field, fileName, attrList)`` method. :type writer: :py:class:`object` :param fileName: Base file name (without directory). If ``None``, a default is generated based on analysis type and mode properties. :type fileName: :py:class:`str`, *optional* .. py:method:: importData(reader, importDirPath, importFileName=None) Import mode data from an HDF5 file. If no explicit file name is provided, a default name is constructed from the analysis type, mode type, and frequency/eigenvalue (and gain number for resolvent modes). After importing the field coefficients via the parent :class:`Field` method, the eigenvalue, frequency, gain and gain number are read back from file attributes. :param reader: Reader object providing an ``importInField(field, filePath, groupName)`` method. :type reader: :py:class:`object` :param importDirPath: Directory from which the mode file is read. :type importDirPath: :py:class:`str` :param importFileName: Explicit file name to import from. If ``None``, a default name is constructed from the mode metadata. :type importFileName: :py:class:`str`, *optional* :returns: * :py:class:`Mode` -- The updated mode (self) with imported coefficients and metadata. * :py:class:`list` of :py:class:`str` -- List of variable names that were not found in the file. .. admonition:: Notes For Resolvent and Input-Output analyses, the mode frequency is populated from the 'omega' dataset in the HDF5 file.