:py:mod:`FELiCS.Fields.ModeCollection` ====================================== .. py:module:: FELiCS.Fields.ModeCollection Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: FELiCS.Fields.ModeCollection.ModeCollection Attributes ~~~~~~~~~~ .. autoapisummary:: FELiCS.Fields.ModeCollection.logger .. py:data:: logger .. py:class:: ModeCollection(femSpace, mesh, isStateVector=True, analysisType='Modal') Container for managing a collection of Mode objects. This class provides methods to append, retrieve, and analyze modes, as well as to interface with legacy solution objects. It is designed to store and manage eigenmodes and their properties for further analysis. **Initialize the ModeCollection object** :param femSpace: The finite element space associated with the modes. :type femSpace: :py:class:`dolfinx.fem.FunctionSpace` :param mesh: The mesh associated with the modes. :type mesh: :py:class:`FELiCS.SpaceDisc.FELiCSMesh` :param isStateVector: If True, modes in this collection are treated as state vectors in a mixed space. Default is True. :type isStateVector: :py:class:`bool`, *optional* :param analysisType: Type of analysis this collection belongs to. The string is mapped (case-insensitively) to :class:`AnalysisType` (e.g. 'Modal', 'Resolvent', 'Input_Output'). Default is ``'Modal'``. :type analysisType: :py:class:`str`, *optional* :ivar modeList: List of Mode objects in the collection. :vartype modeList: :py:class:`list` :ivar femSpace: The finite element space associated with the modes. :vartype femSpace: :py:class:`dolfinx.fem.FunctionSpace` :ivar mesh: The mesh associated with the modes. :vartype mesh: :py:class:`FELiCS.SpaceDisc.FELiCSMesh` :ivar isStateVector: Indicates if modes are treated as state vectors. :vartype isStateVector: :py:class:`bool` :ivar analysisType: The specific analysis type enum associated with this collection. :vartype analysisType: :py:class:`AnalysisType` .. py:method:: describe() Print a description of the ModeCollection. .. py:method:: appendMode(mode) Append an existing Mode object to the collection. :param mode: The Mode object to append. :type mode: :py:class:`Mode` .. py:method:: appendModeFromVector(vector, gain=None, eigenValue=None, guess=None, waveNumber=None, frequency=None, modeType=None, m=0) Create a Mode from a coefficient vector and properties, and append it to the collection. :param vector: Coefficient vector for the mode. :type vector: :py:class:`array-like` :param gain: Gain associated with the mode (mainly for resolvent analysis). :type gain: :py:class:`float`, *optional* :param eigenValue: Eigenvalue associated with the mode (for modal analysis). :type eigenValue: :py:class:`complex`, *optional* :param guess: Initial guess or parameter used to obtain this mode. :type guess: :py:class:`any`, *optional* :param waveNumber: Wave number associated with the mode. :type waveNumber: :py:class:`float`, *optional* :param frequency: Frequency associated with the mode (for resolvent / input–output). :type frequency: :py:class:`float`, *optional* :param modeType: Mode role within the chosen analysis type, mapped to :class:`ModeType` (e.g. ``'direct'``, ``'adjoint'``, ``'response'``, ``'forcing'``). If ``None``, a default is chosen inside :class:`Mode` based on the analysis type. :type modeType: :py:class:`str` or :py:obj:`None`, *optional* :param m: Azimuthal wavenumber associated with the mode. Default is 0. :type m: :py:class:`int`, *optional* .. py:method:: appendSolutionOfEigenProblem(solution, guess, adjoint=False, name=None, m=0) Append all modes from an eigenproblem solution to the collection. This assumes that we are doing a 'Modal' analysis. :param solution: Tuple containing eigenvalues, eigenvectors, and errors. :type solution: :py:class:`tuple` :param guess: Initial guess or parameter for the modes. :type guess: :py:class:`any` :param adjoint: Whether the modes are adjoint modes (default is False). :type adjoint: :py:class:`bool`, *optional* :param name: A custom name for the mode. :type name: :py:class:`str`, *optional* :param m: Azimuthal wavenumber associated with the mode. Default is 0. :type m: :py:class:`int`, *optional* .. py:method:: appendSolutionOfSVDProblem(forcingArray, omega, gains, resolventOperator, name=None, m=0) Append all forcing modes from a SVD solution to the collection for one frequency. Then compute the corresponding response modes and append them as well. This assumes that we are doing a 'Resolvent' analysis. :param forcingArray: The forcing array. :type forcingArray: :py:class:`array-like` :param omega: The frequency. :type omega: :py:class:`float` :param gains: The gains from the SVD solution. :type gains: :py:class:`array-like` :param resolventOperator: The resolvent operator, instance of the ResolventOperator class. :type resolventOperator: :py:class:`FELiCS object` :param name: The name of the mode. :type name: :py:class:`str`, *optional* :param m: Azimuthal wavenumber associated with the mode. Default is 0. :type m: :py:class:`int`, *optional* .. py:method:: getMaximumError() Return the maximum error among all modes in the collection. :returns: The maximum error value. :rtype: :py:class:`float` .. py:method:: getDirectEigenValueSpectrum() Return the eigenvalue spectrum of direct (non-adjoint) modes. :returns: List of eigenvalues for direct modes. :rtype: :py:class:`list` .. py:method:: getSpectrum() Returns the spectrum for either `Modal` or `Resolvent` type of analysis. Returns: ------- spectrum: array-like Array of eigenvalues or gains at each omega and either (i) Direct/Adjoint for 'Modal' or (ii) GainNumber for `Resolvent`. header: list List of headers corresponding to the spectrum values. .. py:method:: exportSpectrumToCSV(writer) Export the spectrum to a CSV file. :param writer: :type writer: :py:class:`FELiCS.IO.Writer object` .. py:method:: getNearestMode(gain=None, eigenValue=None, guess=None, waveNumber=None, frequency=None) Find the nearest mode to the specified parameters. :param gain: Gain to match. :type gain: :py:class:`float`, *optional* :param eigenValue: Eigenvalue to match. :type eigenValue: :py:class:`complex`, *optional* :param guess: Guess to match. :type guess: :py:class:`any`, *optional* :param waveNumber: Wave number to match. :type waveNumber: :py:class:`float`, *optional* :param frequency: Frequency to match. :type frequency: :py:class:`float`, *optional* .. admonition:: Notes This method is not yet implemented and will be added in future releases. .. py:method:: getLeadingMode(adjoint=False) Return the leading mode based on the imaginary part of the eigenvalue. For direct modes, returns the mode with the largest imaginary part. For adjoint modes, returns the mode with the smallest imaginary part. :param adjoint: Whether to search among adjoint modes (default is False). :type adjoint: :py:class:`bool`, *optional* :returns: The leading Mode object, or None if not found. :rtype: :py:class:`Mode` or :py:obj:`None` .. py:method:: getOldSolutionObject(meanFlow, param, FEMSpaces) Create legacy fluctuation solution objects from the modes. This is a wrapper for the old solution class and should be removed at the end of restructuring. :param meanFlow: Mean flow object. :type meanFlow: :py:class:`object` :param param: Parameter object containing case information. :type param: :py:class:`object` :param FEMSpaces: Finite element spaces. :type FEMSpaces: :py:class:`object` :returns: List of fluctuationSolutions objects. :rtype: :py:class:`list` .. admonition:: Notes In future relases, this method will be deleted .. py:method:: getSize() Return the number of modes in the collection. :returns: Number of modes in the collection. :rtype: :py:class:`int` .. py:method:: popList() Remove and return the last mode in the collection. :returns: The last Mode object in the collection. :rtype: :py:class:`Mode` .. py:method:: exportModes(writer, onlyNewN=0) Export modes in the collection to HDF5 files. :param writer: Writer object providing ``exportFieldToH5``. :type writer: :py:class:`FELiCS.IO.Writer` :param onlyNewN: If 0 (default), export all modes in the collection. If positive, export only the last ``onlyNewN`` modes that were added. :type onlyNewN: :py:class:`int`, *optional* .. py:method:: importData(reader, importFolder, omegas=None, modeType=None, gainNumber=None) Import mode collection data from a specified folder using a reader. :param reader: The Reader object used to read the mode data. :type reader: :py:class:`Reader` :param importFolder: Path to the folder containing the mode files. :type importFolder: :py:class:`str` :param omegas: List of frequencies to import. If None, all frequencies found in the folder are considered (matching is done on rounded values). :type omegas: :py:class:`list` of :py:class:`float`, *optional* :param modeType: Type of mode to import (e.g. 'Direct', 'Adjoint', 'Response', 'Forcing'). If None, all detected types are imported. :type modeType: :py:class:`str`, *optional* :param gainNumber: Gain number to import (for Resolvent analysis). If None, all gain numbers are imported. :type gainNumber: :py:class:`int`, *optional*