:py:mod:`pylbo.data_containers` =============================== .. py:module:: pylbo.data_containers Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pylbo.data_containers.LegolasDataContainer pylbo.data_containers.LegolasDataSet pylbo.data_containers.LegolasDataSeries Functions ~~~~~~~~~ .. autoapisummary:: pylbo.data_containers.ensure_dataset pylbo.data_containers.ensure_dataseries .. py:function:: ensure_dataset(data: any) -> None Ensures that the given data is a :class:`LegolasDataSet`. .. !! processed by numpydoc !! .. py:function:: ensure_dataseries(data: any) -> None Ensures that the given data is a :class:`LegolasDataSeries`. .. !! processed by numpydoc !! .. py:class:: LegolasDataContainer Bases: :py:obj:`abc.ABC` Baseclass for a Legolas data container. .. !! processed by numpydoc !! .. py:method:: continua() :abstractmethod: .. py:method:: parameters() :abstractmethod: .. py:method:: has_efs() :abstractmethod: .. py:method:: ef_grid() :abstractmethod: .. py:method:: ef_names() :abstractmethod: .. py:method:: has_background() :abstractmethod: .. py:method:: has_derived_efs() :abstractmethod: .. py:method:: derived_ef_names() :abstractmethod: .. py:method:: has_ef_subset() :abstractmethod: .. py:method:: has_matrices() :abstractmethod: .. py:method:: has_eigenvectors() :abstractmethod: .. py:method:: has_residuals() :abstractmethod: .. py:method:: get_sound_speed(which_values=None) :abstractmethod: .. py:method:: get_alfven_speed(which_values=None) :abstractmethod: .. py:method:: get_tube_speed(which_values=None) :abstractmethod: .. py:method:: get_reynolds_nb(which_values=None) :abstractmethod: .. py:method:: get_magnetic_reynolds_nb(which_values=None) :abstractmethod: .. py:method:: get_k0_squared() :abstractmethod: .. py:class:: LegolasDataSet(datfile) Bases: :py:obj:`LegolasDataContainer` Main container for a single Legolas dataset. :param datfile: Path to the datfile. :type datfile: str, ~os.PathLike .. attribute:: header The datfile header. :type: dict .. attribute:: grid The base grid. :type: numpy.ndarray .. attribute:: grid_gauss The Gaussian grid. :type: numpy.ndarray .. attribute:: equilibria Dictionary containing the equilibrium arrays. :type: dict .. attribute:: eigenvalues Array containing the complex eigenvalues. :type: numpy.ndarray .. attribute:: geometry The geometry. :type: str .. attribute:: scale_factor Array with the scale factor. One for Cartesian geometries, r for cylindrical. :type: numpy.ndarray .. attribute:: x_start Start of the grid. :type: float .. attribute:: x_end End of the grid :type: float .. attribute:: gridpoints The number of base gridpoints. :type: int .. attribute:: gauss_gridpoints The number of Gaussian gridpoints. :type: int .. attribute:: matrix_gridpoints The dimension of the matrix. :type: int .. attribute:: ef_gridpoints The number of eigenfunction gridpoints. :type: int .. attribute:: gamma The ratio of specific heats. :type: float .. attribute:: eq_type The type of equilibrium selected. :type: str .. attribute:: cgs If `True`, all units are in cgs. :type: bool .. attribute:: units Dictionary containing the unit normalisations. :type: dict .. attribute:: eq_names Array containing the names of the equilibrium arrays. :type: numpy.ndarray .. !! processed by numpydoc !! .. py:property:: legolas_version :type: pylbo._version.VersionHandler .. py:property:: k2_str :type: str Returns the :math:`k_2` string. .. !! processed by numpydoc !! .. py:property:: k3_str :type: str Returns the :math:`k_3` string. .. !! processed by numpydoc !! .. py:property:: u1_str :type: str Returns the :math:`u_1` string. .. !! processed by numpydoc !! .. py:property:: u2_str :type: str Returns the :math:`u_2` string. .. !! processed by numpydoc !! .. py:property:: u3_str :type: str Returns the :math:`u_3` string. .. !! processed by numpydoc !! .. py:property:: continua :type: dict Returns the continua in a dict with the continua names as keys. .. !! processed by numpydoc !! .. py:property:: parameters :type: dict Returns the parameters in a dict with the parameter names as keys .. !! processed by numpydoc !! .. py:property:: has_background :type: bool Returns `True` if background is present. .. !! processed by numpydoc !! .. py:property:: has_efs :type: bool Returns `True` if eigenfunctions are present. .. !! processed by numpydoc !! .. py:property:: ef_grid :type: numpy.ndarray Returns the eigenfunction grid, None if eigenfunctions are not present. .. !! processed by numpydoc !! .. py:property:: ef_names :type: numpy.ndarray Retrieves the eigenfunction names, None if eigenfunctions are not present. .. !! processed by numpydoc !! .. py:property:: has_derived_efs :type: bool Returns `True` if derived eigenfunctions are present. .. !! processed by numpydoc !! .. py:property:: derived_ef_names :type: numpy.ndarray Retrieves the derived eigenfunction names, None if not present. .. !! processed by numpydoc !! .. py:property:: has_ef_subset :type: bool Returns `True` if the dataset contains a subset of the eigenfunctions. .. !! processed by numpydoc !! .. py:property:: has_matrices :type: bool Checks if matrices are present. .. !! processed by numpydoc !! .. py:property:: has_eigenvectors :type: bool Checks if eigenvectors are present. .. !! processed by numpydoc !! .. py:property:: has_residuals :type: bool Checks if residuals are present. .. !! processed by numpydoc !! .. py:property:: is_mhd :type: bool Checks if the dataset is MHD. .. !! processed by numpydoc !! .. py:method:: _ensure_compatibility() -> None Makes sure that the dataset is backwards compatible with new changes. Mainly used for older (<2.0.0) datasets. .. !! processed by numpydoc !! .. py:method:: get_sound_speed(which_values=None) -> Union[float, numpy.ndarray] Calculates the sound speed based on the equilibrium arrays, given by :math:`c_s = \sqrt{\frac{\gamma p_0}{\rho_0}}`. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: Array with the sound speed at every grid point, or a float corresponding to the value of `which_values` if provided. :rtype: float or numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_alfven_speed(which_values=None) -> Union[float, numpy.ndarray] Calculates the Alfvén speed based on the equilibrium arrays, given by :math:`c_A = \sqrt{\frac{B_0^2}{\rho_0}}`. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: Array with the Alfvén speed at every grid point, or a float corresponding to the value of `which_values` if provided. :rtype: float or numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_tube_speed(which_values=None) -> Union[float, numpy.ndarray] Calculates the tube speed for a cylinder, given by :math:`c_t = \frac{c_s c_A}{\sqrt{c_s^2 + c_A^2}}`. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: Array with the tube speed at every grid point, or a float corresponding to the value of `which_values` if provided. Returns `None` if the geometry is not cylindrical. :rtype: float or numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_reynolds_nb(which_values=None) -> Union[float, numpy.ndarray] Calculates the Reynolds number, defined as :math:`R_e = \frac{ac_s}{\eta}` where the slabsize is given by :math:`a = x_{end} - x_{start}`. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: Array with the Reynolds number at every grid point, or a float corresponding to the value of `which_values` if provided. Returns `None` if the resistivity is zero somewhere on the domain. :rtype: float or numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_magnetic_reynolds_nb(which_values=None) -> Union[float, numpy.ndarray] Calculates the magnetic Reynolds number, defined as :math:`R_m = \frac{ac_A}{\eta}` where the slabsize is given by :math:`a = x_{end} - x_{start}`. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: Array with the magnetic Reynolds number at every grid point, or a float corresponding to the value of `which_values` if provided. Returns `None` if the resistivity is zero somewhere on the domain. :rtype: float or numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_k0_squared() -> float Calculates the squared wave number, defined as :math:`k_0^2 = k_2^2 + k_3^2`. .. !! processed by numpydoc !! .. py:method:: get_matrix_B() -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray] Retrieves the matrix B from the datfile. :returns: **Tuple(rows** -- Tuple containing the rows, columns and values of the non-zero B-matrix elements. Rows and columns are integers, values are real. :rtype: numpy.ndarray, cols: numpy.ndarray, vals: numpy.ndarray) :raises MatricesNotPresent: If the matrices were not saved to the datfile. .. !! processed by numpydoc !! .. py:method:: get_matrix_A() -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray] Retrieves the matrix A from the datfile. :returns: **Tuple(rows** -- Tuple containing the rows, columns and values of the non-zero A-matrix elements. Rows and columns are integers, values are complex. :rtype: numpy.ndarray, cols: numpy.ndarray, vals: numpy.ndarray) :raises MatricesNotPresent: If the matrices were not saved to the datfile. .. !! processed by numpydoc !! .. py:method:: get_eigenvectors() -> numpy.ndarray Retrieves the eigenvectors from the datfile. :returns: Array containing the eigenvectors. One eigenvector in each column. :rtype: numpy.ndarray :raises EigenvectorsNotPresent: If the eigenvectors were not saved to the datfile. .. !! processed by numpydoc !! .. py:method:: get_residuals() -> numpy.ndarray Retrieves the residuals from the datfile. :returns: Array containing the residuals. :rtype: numpy.ndarray :raises ResidualsNotPresent: If the residuals were not saved to the datfile. .. !! processed by numpydoc !! .. py:method:: _get_eigenfunction_like(ev_guesses: numpy.ndarray, ev_idxs: numpy.ndarray, getter_func: Callable) -> numpy.ndarray Returns the eigenfunctions based on the supplied getter function. :param ev_guesses: Eigenvalue guesses. :type ev_guesses: complex, numpy.ndarray :param ev_idxs: Indices of the eigenvalues to retrieve. :type ev_idxs: int, numpy.ndarray :param getter_func: Function to retrieve the eigenfunctions. :type getter_func: function :returns: Array containing the eigenfunctions, items are dictionaries. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_eigenfunctions(ev_guesses=None, ev_idxs=None) -> numpy.ndarray Returns the eigenfunctions based on given eigenvalue guesses or their indices. An array will be returned where every item is a dictionary, containing both the eigenvalue and its eigenfunctions. Either eigenvalue guesses or indices can be supplied, but not both. :param ev_guesses: Eigenvalue guesses. :type ev_guesses: complex, numpy.ndarray :param ev_idxs: Indices corresponding to the eigenvalues that need to be retrieved. :type ev_idxs: int, numpy.ndarray :returns: Array containing the eigenfunctions and eigenvalues corresponding to the supplied indices. Every index in this array contains a dictionary with the eigenfunctions and corresponding eigenvalue. The keys of each dictionary are the eigenfunction names. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_derived_eigenfunctions(ev_guesses=None, ev_idxs=None) -> numpy.ndarray Returns the derived eigenfunctions based on given eigenvalue guesses or their indices. An array will be returned where every item is a dictionary, containing both the eigenvalue and its quantities. Either eigenvalue guesses or indices can be supplied, but not both. :param ev_guesses: Eigenvalue guesses. :type ev_guesses: complex, numpy.ndarray :param ev_idxs: Indices corresponding to the eigenvalues that need to be retrieved. :type ev_idxs: int, numpy.ndarray :returns: Array containing the derived eigenfunctions and eigenvalues corresponding to the supplied indices. Every index in this array contains a dictionary with the derived eigenfunctions and corresponding eigenvalue. The keys of each dictionary are the corresponding eigenfunction names. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_nearest_eigenvalues(ev_guesses) -> tuple(np.ndarray, np.ndarray) Calculates the eigenvalues nearest to a given guess based on the distance between two points. :param ev_guesses: The guesses for the eigenvalues. These can be a single float/complex value, or a list/Numpy array of floats/complex values. :type ev_guesses: float, complex, list of float, list of complex :returns: The indices of the nearest eigenvalues in the :attr:`eigenvalues` array. The nearest eigenvalues to the provided guesses, corresponding with the indices `idxs`. :rtype: Tuple(numpy.ndarray, numpy.ndarray) .. !! processed by numpydoc !! .. py:method:: get_eigenvalues_at_distance(ev_guesses, min_distance=0.0) -> tuple(np.ndarray, np.ndarray) Calculates the nearest eigenvalues nearest to a given guess but at a minimum distance away. :param ev_guesses: The guesses for the eigenvalues. These can be a single float/complex value, or a list/Numpy array of floats/complex values. :type ev_guesses: float, complex, list of float, list of complex :param min_distance: Minimum distance from the guess the eigenvalue should have. :type min_distance: float :returns: The indices of the nearest eigenvalues at the minimum distance in the :attr:`eigenvalues` array. The nearest eigenvalues at a minimum distance to the provided guesses, corresponding with the indices `idxs`. :rtype: Tuple(numpy.ndarray, numpy.ndarray) .. !! processed by numpydoc !! .. py:method:: get_omega_max(real=True, strip=False, range_omega=(0.0, 1e+24)) Calculates the maximum of the real or imaginary part of a spectrum. :param real: Returns the largest real part if True (default option), returns the largest imaginary part if False. :type real: bool :param strip: Look for maximum in a horizontal half-plane if True. Default False. :type strip: bool :param range_omega: The horizontal range of the strip if strip=True. :type range_omega: tuple of floats :returns: **omega_max** -- The eigenvalue that has the largest real or imaginary part in the chosen strip. Default: in the whole complex plane. :rtype: complex .. !! processed by numpydoc !! .. py:class:: LegolasDataSeries(datfiles) Bases: :py:obj:`LegolasDataContainer` Baseclass for a Legolas data container. .. !! processed by numpydoc !! .. py:property:: continua :type: dict Returns the continua. Each key corresponds to a multiple Numpy arrays, one for each dataset. .. !! processed by numpydoc !! .. py:property:: parameters :type: dict Returns the parameters. Each key corresponds to multiple Numpy arrays, one for each dataset. .. !! processed by numpydoc !! .. py:property:: has_background :type: numpy.ndarray Returns `True` if background is present. .. !! processed by numpydoc !! .. py:property:: has_efs :type: numpy.ndarray Returns `True` if eigenfunctions are present. .. !! processed by numpydoc !! .. py:property:: ef_names :type: numpy.ndarray Returns the eigenfunction names. .. !! processed by numpydoc !! .. py:property:: ef_grid :type: numpy.ndarray Returns the eigenfunction grid. .. !! processed by numpydoc !! .. py:property:: has_derived_efs :type: numpy.ndarray Returns `True` at index `i` if eigenfunctions are present in dataset `i`. .. !! processed by numpydoc !! .. py:property:: derived_ef_names :type: numpy.ndarray Returns the derived eigenfunction names. .. !! processed by numpydoc !! .. py:property:: has_ef_subset :type: numpy.ndarray Returns `True` at index `i` if the `i`-th dataset contains a subset. .. !! processed by numpydoc !! .. py:property:: has_matrices :type: numpy.ndarray Returns `True` at index `i` if the `i`-th dataset contains matrices. .. !! processed by numpydoc !! .. py:property:: has_eigenvectors :type: numpy.ndarray Returns `True` at index `i` if the `i`-th dataset contains eigenvectorst. .. !! processed by numpydoc !! .. py:property:: has_residuals :type: numpy.ndarray Returns `True` at index `i` if the `i`-th dataset contains residuals. .. !! processed by numpydoc !! .. py:method:: get_sound_speed(which_values=None) -> numpy.ndarray Calculates the sound speed for the various datasets. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: A Numpy array of same length as the number of datasets, containing the sound speeds. Elements are either arrays themselves or floats, depending on the value of `which_values`. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_alfven_speed(which_values=None) -> numpy.ndarray Calculates the Alfvén speed for the various datasets. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: A Numpy array of same length as the number of datasets, containing the Alfvén speeds. Elements are either arrays themselves or floats, depending on the value of `which_values`. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_tube_speed(which_values=None) -> numpy.ndarray Calculates the tube speed for the various datasets. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: A Numpy array of same length as the number of datasets, containing the tube speeds. Elements are either arrays themselves or floats, depending on the value of `which_values`. Elements are None if the geometry is not cylindrical. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_reynolds_nb(which_values=None) -> numpy.ndarray Calculates the Reynolds number for the various datasets. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: A Numpy array of same length as the number of datasets, containing the Reynolds number. Elements are either arrays themselves or floats, depending on the value of `which_values`. Elements are None if the resistivity is zero. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_magnetic_reynolds_nb(which_values=None) -> numpy.ndarray Calculates the magnetic Reynolds number for the various datasets. :param which_values: Callback to :meth:`get_values`, either "average"/"minimum"/"maximum". :type which_values: str :returns: A Numpy array of same length as the number of datasets, containing the magnetic Reynolds number. Elements are either arrays themselves or floats, depending on the value of `which_values`. Elements are None if the resistivity is zero. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_k0_squared() -> numpy.ndarray Calculates the squared wave number for the various datasets. :returns: A Numpy array of same length as the number of datasets, containing the squared wavenumber for each. :rtype: numpy.ndarray .. !! processed by numpydoc !! .. py:method:: get_omega_max(real=True) Calculates the maximum of the real or imaginary part of the spectrum for the various datasets. :param real: Returns the largest real part if True (default option), returns the largest imaginary part if False. :type real: bool :returns: **omega_max** -- A Numpy array of same length as the number of datasets, containing tuples of the eigenvalue that has the largest real or imaginary part. :rtype: numpy.ndarray .. !! processed by numpydoc !!