SuPyMode 2.4.3__cp313-cp313-win_amd64.whl

SuPyMode/representation/field.py

@@ -0,0 +1,486 @@
+# #!/usr/bin/env python
+# # -*- coding: utf-8 -*-
+
+import numpy
+from MPSPlots import colormaps
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from matplotlib import colors
+
+from SuPyMode.utils import (
+    interpret_slice_number_and_itr,
+    slice_to_itr,
+    get_symmetrized_vector,
+)
+from SuPyMode.boundaries import BoundaryValue
+from SuPyMode.supermode import SUPERMODE
+
+
+class Field:
+    """
+    Represents a field derived from a supermode in a modal analysis framework.
+
+    This class extends functionality from a parent supermode class to manage field data operations,
+    including retrieving and processing field data for visualization and analysis.
+
+    Attributes
+    ----------
+    supermode : SUPERMODE
+        Reference to the parent supermode object that provides source data.
+    data : numpy.ndarray
+        The field data retrieved from the parent supermode binding.
+    """
+
+    def __init__(self, supermode: SUPERMODE):
+        """
+        Initialize the Field object with a reference to a parent supermode.
+
+        Parameters
+        ----------
+        supermode : SUPERMODE
+            The parent supermode from which this field is derived.
+        """
+        self.supermode = supermode
+        self.data = self.supermode.get_fields()
+
+    def _get_symmetrize_vector(self, *args, **kwargs):
+        """
+        Get the symmetrization vector from the parent supermode.
+
+        Returns
+        -------
+        Any
+            The symmetrization vector computed by the parent supermode.
+        """
+        return self.supermode._get_symmetrize_vector(*args, **kwargs)
+
+    def _get_axis_vector(self, supermode: object, add_symmetries: bool = True) -> tuple:
+        """
+        Computes the full axis vectors, optionally including symmetries.
+
+        Parameters
+        ----------
+        add_symmetries : bool, optional, default=True
+            Whether to include symmetries when computing the axis vectors.
+
+        Returns
+        -------
+        tuple
+            A tuple containing the full x-axis and y-axis vectors.
+        """
+        full_x_axis = self.supermode.model_parameters.x_vector
+        full_y_axis = self.supermode.model_parameters.y_vector
+
+        if not add_symmetries:
+            return full_x_axis, full_y_axis
+
+        if supermode.boundaries.right in [
+            BoundaryValue.Symmetric,
+            BoundaryValue.AntiSymmetric,
+        ]:
+            full_x_axis = get_symmetrized_vector(full_x_axis, symmetry_type="last")
+            full_x_axis.sort()
+
+        if supermode.boundaries.left in [
+            BoundaryValue.Symmetric,
+            BoundaryValue.AntiSymmetric,
+        ]:
+            full_x_axis = get_symmetrized_vector(full_x_axis, symmetry_type="first")
+            full_x_axis.sort()
+
+        if supermode.boundaries.top in [
+            BoundaryValue.Symmetric,
+            BoundaryValue.AntiSymmetric,
+        ]:
+            full_y_axis = get_symmetrized_vector(full_y_axis, symmetry_type="last")
+            full_y_axis.sort()
+
+        if supermode.boundaries.bottom in [
+            BoundaryValue.Symmetric,
+            BoundaryValue.AntiSymmetric,
+        ]:
+            full_y_axis = get_symmetrized_vector(full_y_axis, symmetry_type="first")
+            full_y_axis.sort()
+
+        return full_x_axis, full_y_axis
+
+    def get_axis(
+        self, supermode: object, slice_number: int, add_symmetries: bool = True
+    ) -> tuple:
+        """
+        Computes the scaled axis vectors for a specific slice, optionally including symmetries.
+
+        Parameters
+        ----------
+        slice_number : int
+            The slice index for which to compute the axis vectors.
+        add_symmetries : bool, optional, default=True
+            Whether to include symmetries in the computed axis vectors.
+
+        Returns
+        -------
+        tuple
+            A tuple containing the scaled x-axis and y-axis vectors for the given slice.
+        """
+        itr = supermode.model_parameters.itr_list[slice_number]
+        x_axis, y_axis = self._get_axis_vector(
+            supermode=supermode, add_symmetries=add_symmetries
+        )
+        return (x_axis * itr, y_axis * itr)
+
+    def get_norm(self, slice_number: int) -> float:
+        """
+        Calculate the norm of the field for a specific slice.
+
+        Parameters
+        ----------
+        slice_number : int
+            The slice number for which to calculate the norm.
+
+        Returns
+        -------
+        float
+            The norm of the field for the specified slice.
+        """
+        return self.supermode.get_norm(slice_number)
+
+    @property
+    def itr_list(self) -> numpy.ndarray:
+        """
+        Provides a list of iteration indices available for the fields.
+
+        Returns
+        -------
+        numpy.ndarray
+            An array of iteration indices.
+        """
+        return self.supermode.model_parameters.itr_list
+
+    @property
+    def parent_superset(self) -> object:
+        """
+        Access the parent set of the supermode.
+
+        Returns
+        -------
+        object
+            The parent set object.
+        """
+        return self.supermode.parent_set
+
+    def get_field(
+        self, slice_number: int = None, itr: float = None, add_symmetries: bool = True
+    ) -> numpy.ndarray:
+        """
+        Retrieve a specific field adjusted for boundary conditions and optionally add symmetries.
+
+        Parameters
+        ----------
+        slice_number : int, optional
+            The slice number to retrieve.
+        itr : float, optional
+            The iteration to use for retrieving the field.
+        add_symmetries : bool, optional, default=True
+            Whether to add boundary symmetries to the field.
+
+        Returns
+        -------
+        numpy.ndarray
+            The requested field as a numpy array.
+
+        Raises
+        ------
+        AssertionError
+            If neither or both of `slice_number` and `itr` are defined.
+        """
+        slice_list, itr_list = interpret_slice_number_and_itr(
+            itr_baseline=self.itr_list, itr_list=itr, slice_list=slice_number
+        )
+
+        fields = self.supermode.get_fields()
+
+        fields = numpy.take(fields, slice_list, axis=0)
+        if add_symmetries:
+            fields = self._get_symmetrized_field(fields)
+
+        return fields
+
+    def normalize_field(
+        self, field: numpy.ndarray, itr: float, norm_type: str = "L2"
+    ) -> numpy.ndarray:
+        """
+        Normalize a field array based on a specified normalization method.
+
+        Parameters
+        ----------
+        field : numpy.ndarray
+            The field to normalize.
+        itr : float
+            The iteration value for normalization scaling.
+        norm_type : str, optional, default='L2'
+            The type of normalization ('max', 'center', 'L2', 'cmt').
+
+        Returns
+        -------
+        numpy.ndarray
+            The normalized field.
+        """
+        match norm_type.lower():
+            case "max":
+                norm = abs(field).max()
+            case "center":
+                idx_x_center = numpy.argmin(
+                    abs(self.supermode.parent_set.coordinate_system.x_vector)
+                )
+                idx_y_center = numpy.argmin(
+                    abs(self.supermode.parent_set.coordinate_system.y_vector)
+                )
+                center_value = field[idx_x_center, idx_y_center]
+                norm = center_value
+            case "l2":
+                dx_scaled = self.supermode.parent_set.coordinate_system.dx * itr
+                dy_scaled = self.supermode.parent_set.coordinate_system.dy * itr
+                norm = numpy.sqrt(
+                    numpy.trapz(
+                        numpy.trapz(numpy.square(field), dx=dy_scaled, axis=0),
+                        dx=dx_scaled,
+                        axis=0,
+                    )
+                )
+            case "cmt":
+                dx_scaled = self.supermode.parent_set.coordinate_system.dx * itr
+                dy_scaled = self.supermode.parent_set.coordinate_system.dy * itr
+                norm = numpy.sqrt(
+                    numpy.trapz(
+                        numpy.trapz(numpy.square(field), dx=dx_scaled, axis=0),
+                        dx=dy_scaled,
+                        axis=0,
+                    )
+                )
+
+        return field / norm
+
+    def _get_symmetrized_field_and_axis(self, field: numpy.ndarray) -> tuple:
+        """
+        Generate a symmetrical version of the input field mesh according to defined boundary conditions.
+
+        Parameters
+        ----------
+        field : numpy.ndarray
+            The 2D field mesh to be symmetrized.
+
+        Returns
+        -------
+        tuple
+            A tuple containing the x-axis, y-axis, and the symmetrized field.
+
+        Raises
+        ------
+        AssertionError
+            If the input is not a 2D array.
+        """
+        x_axis, y_axis = self._get_axis_vector(add_symmetries=True)
+
+        field = self._get_symmetrized_field(field=field)
+
+        return x_axis, y_axis, field
+
+    def _get_symmetrized_field(self, field: numpy.ndarray) -> numpy.ndarray:
+        """
+        Retrieve the field and axis data adjusted for symmetry.
+
+        This method generates symmetrized versions of the field and its corresponding axis vectors.
+
+        Parameters
+        ----------
+        field : numpy.ndarray
+            The field data array to be symmetrized.
+
+        Returns
+        -------
+        numpy.ndarray
+            The symmetrized field data.
+
+        Raises
+        ------
+        AssertionError
+            If the input field is not a 2D array.
+        """
+        field = field.squeeze()
+        assert (
+            field.ndim == 2
+        ), f"Expected a 2-dimensional array, but got {field.ndim}-dimensional."
+
+        symmetric_field = field[:, -2::-1]
+        match self.supermode.boundaries.left:
+            case BoundaryValue.Symmetric:
+                field = numpy.c_[symmetric_field, field]
+
+            case BoundaryValue.AntiSymmetric:
+                field = numpy.c_[-symmetric_field, field]
+
+        match self.supermode.boundaries.right:
+            case BoundaryValue.Symmetric:
+                field = numpy.c_[field, symmetric_field]
+
+            case BoundaryValue.AntiSymmetric:
+                field = numpy.c_[field, -symmetric_field]
+
+        symmetric_field = field[-2::-1, :]
+        match self.supermode.boundaries.top:
+            case BoundaryValue.Symmetric:
+                field = numpy.r_[field, symmetric_field]
+
+            case BoundaryValue.AntiSymmetric:
+                field = numpy.r_[field, -symmetric_field]
+
+        match self.supermode.boundaries.bottom:
+            case BoundaryValue.Symmetric:
+                field = numpy.r_[symmetric_field, field]
+
+            case BoundaryValue.AntiSymmetric:
+                field = numpy.r_[-symmetric_field, field]
+
+        return field
+
+    def plot(
+        self,
+        itr_list: list[float] = [],
+        slice_list: list[int] = [0, -1],
+        add_symmetries: bool = True,
+        show_colorbar: bool = False,
+        show: bool = True,
+    ) -> None:
+        """
+        Plot the field for specified iterations or slice numbers.
+
+        Parameters
+        ----------
+        itr_list : list of float, optional
+            List of iterations to evaluate the field.
+        slice_list : list of int, optional, default=[0, -1]
+            List of slices to evaluate the field.
+        add_symmetries : bool, optional, default=True
+            Whether to include boundary symmetries in the plot.
+        show_mode_label : bool, optional, default=True
+            Whether to show the mode label.
+        show_itr : bool, optional, default=True
+            Whether to show the iteration value.
+        show_colorbar : bool, optional, default=False
+            Whether to show the colorbar.
+        show_slice : bool, optional, default=True
+            Whether to show the slice number.
+        """
+        slice_list, itr_list = interpret_slice_number_and_itr(
+            itr_baseline=self.itr_list, itr_list=itr_list, slice_list=slice_list
+        )
+
+        unit_size = numpy.array([len(slice_list), 1])
+        figure, axes = plt.subplots(*unit_size, figsize=3 * numpy.flip(unit_size))
+
+        for n, (itr, slice_number) in enumerate(zip(itr_list, slice_list)):
+            self.render_on_ax(
+                ax=axes[n],
+                slice_number=slice_number,
+                add_symmetries=add_symmetries,
+                show_colorbar=show_colorbar,
+            )
+
+        plt.tight_layout()
+
+        if show:
+            plt.show()
+
+    def render_on_ax(
+        self,
+        ax: plt.Axes,
+        slice_number: int,
+        show_mode_label: bool = True,
+        show_itr: bool = True,
+        show_slice: bool = True,
+        show_colorbar: bool = False,
+        add_symmetries: bool = True,
+    ) -> None:
+        """
+        Render the mode field at the given slice number into the input axis.
+
+        Args:
+            ax (plt.Axes): The matplotlib axis to render the field on.
+            slice_number (int): The slice number to render.
+            show_mode_label (bool): Whether to show the mode label.
+            show_itr (bool): Whether to show the iteration value.
+            show_slice (bool): Whether to show the slice number.
+            show_colorbar (bool): Whether to show the colorbar.
+            add_symmetries (bool): Whether to include boundary symmetries.
+        """
+        title = self.get_plot_mode_field_title(
+            slice_number=slice_number,
+            show_mode_label=show_mode_label,
+            show_itr=show_itr,
+            show_slice=show_slice,
+        )
+
+        ax.set_title(title)
+        ax.set_aspect("equal")
+
+        field = self.get_field(slice_number=slice_number, add_symmetries=add_symmetries)
+
+        x, y = self.get_axis(
+            supermode=self.supermode,
+            slice_number=slice_number,
+            add_symmetries=add_symmetries,
+        )
+
+        mappable = ax.pcolormesh(
+            x * 1e6,
+            y * 1e6,
+            field,
+            cmap=colormaps.blue_black_red,
+            norm=colors.CenteredNorm(),
+        )
+        plt.setp(ax.get_xticklabels(), visible=False)
+
+        if show_colorbar:
+            divider = make_axes_locatable(ax)
+            cax = divider.append_axes("right", size="5%", pad=0.05)
+
+            figure = ax.get_figure()
+            figure.colorbar(mappable, cax=cax, orientation="vertical")
+
+    def get_plot_mode_field_title(
+        self, slice_number: int, show_mode_label: bool, show_itr: bool, show_slice: bool
+    ) -> str:
+        """
+        Constructs a title for the field plot based on the mode, iteration, and slice number.
+
+        Args:
+            slice_number (int): The slice number for which the field is plotted.
+            show_mode_label (bool): Flag to include the mode label in the title.
+            show_itr (bool): Flag to include the iteration number in the title.
+            show_slice (bool): Flag to include the slice number in the title.
+
+        Returns:
+            str: The constructed title for the plot.
+        """
+        title = ""
+
+        if show_mode_label:
+            title += f"{self.supermode.stylized_label}"
+
+        if show_itr or show_slice:
+            itr = slice_to_itr(
+                itr_list=self.supermode.model_parameters.itr_list,
+                slice_number=slice_number,
+            )
+            title += "\n"
+
+        if show_slice:
+            title += f"slice: {slice_number}"
+
+        if show_itr:
+            title += f"  itr: {itr:.3f}"
+
+        return title
+
+
+# -

SuPyMode/representation/index.py

@@ -0,0 +1,80 @@
+# #!/usr/bin/env python
+# # -*- coding: utf-8 -*-
+import matplotlib.pyplot as plt
+from MPSPlots.helper import post_mpl_plot
+
+from SuPyMode.supermode import SUPERMODE
+
+
+class Index:
+    """
+    Represents the effective refractive index of a mode derived from a supermode in optical fiber simulations.
+
+    This class extends from `InheritFromSuperMode` for accessing supermode-related data and `BaseSingleModePlot`
+    for plotting functionalities tailored to visualize the effective refractive index.
+
+    Attributes
+    ----------
+    supermode : SUPERMODE
+        The supermode instance to which this Index object is linked.
+    data : numpy.ndarray
+        The effective refractive index data for the mode derived from the parent supermode.
+    """
+
+    def __init__(self, supermode: SUPERMODE):
+        """
+        Initialize an Index object with a reference to a parent supermode.
+
+        Parameters
+        ----------
+        supermode : SUPERMODE
+            The parent supermode object that provides the base mode data.
+        """
+        self.supermode = supermode
+        self.data = self.supermode.get_index()
+
+    @post_mpl_plot
+    def plot(self, ax: plt.Axes = None, show: bool = True) -> plt.Figure:
+        """
+        Plot the propagation constant for a single mode.
+
+        This method generates a plot of the propagation constants as a function of the inverse taper ratio (ITR),
+        formatted according to the predefined plot style.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes, optional
+            The axis on which to plot. If `None`, a new axis is created (default is `None`).
+        show : bool, optional
+            Whether to display the plot immediately (default is `True`).
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+            The figure object containing the generated plot.
+
+        """
+        if ax is None:
+            figure, ax = plt.subplots(1, 1)
+        else:
+            figure = ax.figure
+
+        ax.plot(
+            self.supermode.model_parameters.itr_list,
+            self.data,
+            label=f"{self.supermode.stylized_label}",
+            linewidth=2,
+        )
+
+        ax.legend()
+
+        ax.set(
+            xlabel="Inverse taper ratio",
+            ylabel="Effective refractive index",
+            ylim=[1.44, 1.455],
+        )
+
+        return figure
+
+
+# -

SuPyMode/representation/normalized_coupling.py

@@ -0,0 +1,98 @@
+# #!/usr/bin/env python
+# # -*- coding: utf-8 -*-
+import numpy
+import matplotlib.pyplot as plt
+from MPSPlots.helper import post_mpl_plot
+
+from SuPyMode.supermode import SUPERMODE
+
+
+class NormalizedCoupling:
+    """
+    Represents the normalized mode coupling between modes of different supermodes in optical fiber simulations.
+
+    This class extends from `InheritFromSuperMode` for accessing supermode-related data and provides plotting functionalities
+    tailored to visualize mode coupling comparisons.
+
+    Attributes
+    ----------
+    supermode : SUPERMODE
+        The supermode instance to which this NormalizedCoupling object is linked.
+
+    """
+
+    def __init__(self, supermode: SUPERMODE):
+        """
+        Initialize a NormalizedCoupling object with a reference to a parent supermode.
+
+        Parameters
+        ----------
+        supermode : SUPERMODE
+            The parent supermode object that provides the base mode data.
+        """
+        self.supermode = supermode
+
+    def get_values(self, other_supermode: SUPERMODE) -> numpy.ndarray:
+        """
+        Calculate the normalized mode coupling between the parent supermode and another specified supermode.
+
+        Parameters
+        ----------
+        other_supermode : SUPERMODE
+            The supermode with which to compare the parent supermode.
+
+        Returns
+        -------
+        numpy.ndarray
+            An array of normalized mode coupling values, adjusted for computational compatibility.
+        """
+        output = self.supermode.get_normalized_coupling_with_mode(other_supermode)
+
+        if not self.supermode.is_computation_compatible(other_supermode):
+            output *= 0
+
+        return output
+
+    @post_mpl_plot
+    def plot(self, other_supermode: SUPERMODE, ax: plt.Axes = None) -> plt.Figure:
+        """
+        Plot the normalized mode coupling between the parent supermode and another specified supermode.
+
+        This method generates a plot of the normalized coupling as a function of the inverse taper ratio (ITR),
+        formatted according to the predefined plot style.
+
+        Parameters
+        ----------
+        other_supermode : SUPERMODE
+            The supermode to compare against.
+        ax : matplotlib.axes.Axes
+            The axis on which to plot.
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+            The figure object containing the generated plot.
+        """
+        if ax is None:
+            figure, ax = plt.subplots(nrows=1, ncols=1)
+        else:
+            figure = ax.figure
+
+        ax.set_xlabel("Inverse taper ratio")
+        ax.set_ylabel("Mode coupling")
+
+        if not self.supermode.is_computation_compatible(other_supermode):
+            return
+
+        y = self.get_values(other_supermode=other_supermode)
+
+        label = f"{self.supermode.stylized_label} - {other_supermode.stylized_label}"
+
+        ax.plot(self.supermode.model_parameters.itr_list, abs(y), label=label)
+
+        ax.legend()
+
+        return figure
+
+
+# -