emerge 0.4.7__py3-none-any.whl → 0.4.8__py3-none-any.whl

emerge/_emerge/physics/microwave/touchstone.py

@@ -0,0 +1,140 @@
+# EMerge is an open source Python based FEM EM simulation module.
+# Copyright (C) 2025  Andrés Martínez Mera.
+# Copyright (C) 2025  Robert Fennis.
+
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see
+# <https://www.gnu.org/licenses/>.
+
+import os
+from typing import Literal
+import numpy as np
+from datetime import datetime
+from loguru import logger
+
+_F_UNIT = {'HZ': 1,
+           'KHZ': 1e3,
+           'MHZ': 1e6,
+           'GHZ': 1e9,
+}
+def generate_touchstone(filename: str,
+                        freq: np.ndarray,
+                        Smat: np.ndarray,
+                        data_format: Literal['RI','MA','DB'],
+                        custom_comments: list[str] = None,
+                        funit: Literal['HZ','KHZ','MHZ','GHZ'] = 'GHZ') -> None:
+    """
+    Export S-parameter data to a Touchstone file
+
+    Parameters
+    ----------
+    filename : str
+        Base filename (may include path). If no extension is given, one
+        will be added of the form '.sNp' where N = number of ports.
+    freq : np.ndarray
+        1-D array of M frequency points, in Hz.
+    Smat : np.ndarray
+        3-D array of S-parameters with shape (M, N, N).
+    data_format : {'RI','MA','DB'}
+        RI = real&imag, MA = magnitude&angle (deg), DB = dB&angle (deg).
+    custom_comments : list[str], optional
+        List of custom comment strings to add to the touchstone file header.
+        Each string will be prefixed with "! " automatically.
+    """
+    # --- validations ---
+    if Smat.ndim != 3:
+        raise ValueError(f"Smat must be 3-D with shape (M,N,N), got ndim={Smat.ndim}")
+    M, Nports, N2 = Smat.shape
+    if Nports != N2:
+        raise ValueError(f"Smat must be square in its last two dims, got {Nports}×{N2}")
+    if freq.ndim != 1 or freq.size != M:
+        raise ValueError(f"freq must be 1-D of length {M}, got shape {freq.shape}")
+
+    # --- determine output filename & extension ---
+    base, ext = os.path.splitext(filename)
+    if ext == '':
+        ext = f".s{Nports}p"
+    filename_out = base + ext
+
+    # --- write the Touchstone file ---
+    with open(filename_out, 'w') as f:
+        # Write header
+        f.write(f"! Generated by EMerge - {Nports}-port S-parameters\n")
+        timestamp_str = datetime.now().strftime("%Y-%m-%d %H:%M %Z")
+        f.write(f"! File generated: {timestamp_str}\n")
+        
+        # Write custom comments if provided
+        if custom_comments:
+            for comment in custom_comments:
+                # Ensure comment starts with "! " if not already present
+                if not comment.startswith("! "):
+                    comment = "! " + comment
+                f.write(f"{comment}\n")
+
+        f.write(f"# {funit} S {data_format.upper()} R 50\n")
+
+        # Write data
+        for i in range(M):
+            freq_ghz = freq[i] / _F_UNIT[funit]  # Convert Hz to GHz
+            
+            # Build all S-parameter values for this frequency
+            s_values = []
+            for row in range(Nports):
+                for col in range(Nports):
+                    s_val = Smat[i, row, col]
+                    
+                    if data_format == 'RI':
+                        # Real and Imaginary
+                        val1 = s_val.real
+                        val2 = s_val.imag
+                    elif data_format == 'MA':
+                        # Magnitude and Angle (degrees)
+                        val1 = np.abs(s_val)
+                        val2 = np.angle(s_val) * 180.0 / np.pi
+                    elif data_format == 'DB':
+                        # dB and Angle (degrees)
+                        val1 = 20.0 * np.log10(np.abs(s_val)) if np.abs(s_val) > 0 else -300.0
+                        val2 = np.angle(s_val) * 180.0 / np.pi
+                    
+                    s_values.extend([val1, val2])
+            
+            # Write frequency and S-parameters according to touchstone format
+            if Nports == 1:
+                # s1p: freq S11_real S11_imag (3 values per line)
+                f.write(f"{freq_ghz:12.6e}  {s_values[0]:12.6e}  {s_values[1]:12.6e}\n")
+            
+            elif Nports == 2:
+                # s2p: freq S11_r S11_i S21_r S21_i S12_r S12_i S22_r S22_i (9 values per line)
+                f.write(f"{freq_ghz:12.6e}")
+                for val in s_values:
+                    f.write(f"  {val:12.6e}")
+                f.write("\n")
+            
+            else:
+                # s3p, s4p, etc: freq on first line, then S-parameters on subsequent lines
+                f.write(f"{freq_ghz:12.6e}")
+                
+                if (Nports == 3):
+                    values_per_line = 6  # 3-port S-parameter
+                else: 
+                    values_per_line = 8  # 4-port S-parameter pairs
+                for j in range(0, len(s_values), values_per_line):
+                    f.write("   ")  # Indent continuation lines
+                    if (j != 0):
+                        f.write(' ' * 12)  # Extra indentation
+                    end_idx = min(j + values_per_line, len(s_values))
+                    for val in s_values[j:end_idx]:
+                        f.write(f" {val:12.6e}")
+                    f.write("\n")
+    
+    logger.info(f"Touchstone file written to '{filename_out}'")

emerge/_emerge/plot/display.py

@@ -0,0 +1,394 @@
+from ..mesh3d import Mesh3D
+from ..geometry import GeoObject
+from ..selection import Selection
+from ..physics.microwave.microwave_bc import PortBC
+from typing import Iterable, Literal
+import numpy as np
+
+cmap_names = Literal['bgy','bgyw','kbc','blues','bmw','bmy','kgy','gray','dimgray','fire','kb','kg','kr',
+                     'bkr','bky','coolwarm','gwv','bjy','bwy','cwr','colorwheel','isolum','rainbow','fire',
+                     'cet_fire','gouldian','kbgyw','cwr','CET_CBL1','CET_CBL3','CET_D1A']
+
+
+class BaseDisplay:
+
+    def __init__(self, mesh: Mesh3D):
+        self._mesh: Mesh3D = mesh
+
+    def show(self):
+        raise NotImplementedError('This method is not implemented')
+        
+    def add_object(self, obj: GeoObject | Selection | Iterable,*args, **kwargs):
+        """ Adds an object to the display
+
+        Keyword arguments
+        ----------
+        color : ColorLike, optional
+            Use to make the entire mesh have a single solid color.
+            Either a string, RGB list, or hex color string.  For example:
+            ``color='white'``, ``color='w'``, ``color=[1.0, 1.0, 1.0]``, or
+            ``color='#FFFFFF'``. Color will be overridden if scalars are
+            specified.
+
+            Defaults to :attr:`pyvista.global_theme.color
+            <pyvista.plotting.themes.Theme.color>`.
+
+        style : str, optional
+            Visualization style of the mesh.  One of the following:
+            ``style='surface'``, ``style='wireframe'``, ``style='points'``,
+            ``style='points_gaussian'``. Defaults to ``'surface'``. Note that
+            ``'wireframe'`` only shows a wireframe of the outer geometry.
+            ``'points_gaussian'`` can be modified with the ``emissive``,
+            ``render_points_as_spheres`` options.
+
+        scalars : str | numpy.ndarray, optional
+            Scalars used to "color" the mesh.  Accepts a string name
+            of an array that is present on the mesh or an array equal
+            to the number of cells or the number of points in the
+            mesh.  Array should be sized as a single vector. If both
+            ``color`` and ``scalars`` are ``None``, then the active
+            scalars are used.
+
+        clim : sequence[float], optional
+            Two item color bar range for scalars.  Defaults to minimum and
+            maximum of scalars array.  Example: ``[-1, 2]``. ``rng`` is
+            also an accepted alias for this.
+
+        show_edges : bool, optional
+            Shows the edges of a mesh.  Does not apply to a wireframe
+            representation.
+
+        edge_color : ColorLike, optional
+            The solid color to give the edges when ``show_edges=True``.
+            Either a string, RGB list, or hex color string.
+
+            Defaults to :attr:`pyvista.global_theme.edge_color
+            <pyvista.plotting.themes.Theme.edge_color>`.
+
+        point_size : float, optional
+            Point size of any nodes in the dataset plotted. Also
+            applicable when style='points'. Default ``5.0``.
+
+        line_width : float, optional
+            Thickness of lines.  Only valid for wireframe and surface
+            representations.  Default ``None``.
+
+        opacity : float | str| array_like
+            Opacity of the mesh. If a single float value is given, it
+            will be the global opacity of the mesh and uniformly
+            applied everywhere - should be between 0 and 1. A string
+            can also be specified to map the scalars range to a
+            predefined opacity transfer function (options include:
+            ``'linear'``, ``'linear_r'``, ``'geom'``, ``'geom_r'``).
+            A string could also be used to map a scalars array from
+            the mesh to the opacity (must have same number of elements
+            as the ``scalars`` argument). Or you can pass a custom
+            made transfer function that is an array either
+            ``n_colors`` in length or shorter.
+
+        flip_scalars : bool, default: False
+            Flip direction of cmap. Most colormaps allow ``*_r``
+            suffix to do this as well.
+
+        lighting : bool, optional
+            Enable or disable view direction lighting. Default ``False``.
+
+        n_colors : int, optional
+            Number of colors to use when displaying scalars. Defaults to 256.
+            The scalar bar will also have this many colors.
+
+        interpolate_before_map : bool, optional
+            Enabling makes for a smoother scalars display.  Default is
+            ``True``.  When ``False``, OpenGL will interpolate the
+            mapped colors which can result is showing colors that are
+            not present in the color map.
+
+        cmap : str | list | pyvista.LookupTable, default: :attr:`pyvista.plotting.themes.Theme.cmap`
+            If a string, this is the name of the ``matplotlib`` colormap to use
+            when mapping the ``scalars``.  See available Matplotlib colormaps.
+            Only applicable for when displaying ``scalars``.
+            ``colormap`` is also an accepted alias
+            for this. If ``colorcet`` or ``cmocean`` are installed, their
+            colormaps can be specified by name.
+
+            You can also specify a list of colors to override an existing
+            colormap with a custom one.  For example, to create a three color
+            colormap you might specify ``['green', 'red', 'blue']``.
+
+            This parameter also accepts a :class:`pyvista.LookupTable`. If this
+            is set, all parameters controlling the color map like ``n_colors``
+            will be ignored.
+
+        label : str, optional
+            String label to use when adding a legend to the scene with
+            :func:`pyvista.Plotter.add_legend`.
+
+        reset_camera : bool, optional
+            Reset the camera after adding this mesh to the scene. The default
+            setting is ``None``, where the camera is only reset if this plotter
+            has already been shown. If ``False``, the camera is not reset
+            regardless of the state of the ``Plotter``. When ``True``, the
+            camera is always reset.
+
+        scalar_bar_args : dict, optional
+            Dictionary of keyword arguments to pass when adding the
+            scalar bar to the scene. For options, see
+            :func:`pyvista.Plotter.add_scalar_bar`.
+
+        show_scalar_bar : bool, optional
+            If ``False``, a scalar bar will not be added to the
+            scene.
+
+        multi_colors : bool | str | cycler.Cycler | sequence[ColorLike], default: False
+            If a :class:`pyvista.MultiBlock` dataset is given this will color
+            each block by a solid color using a custom cycler.
+
+            If ``True``, the default 'matplotlib' color cycler is used.
+
+            See :func:`set_color_cycler<Plotter.set_color_cycler>` for usage of
+            custom color cycles.
+
+        name : str, optional
+            The name for the added mesh/actor so that it can be easily
+            updated.  If an actor of this name already exists in the
+            rendering window, it will be replaced by the new actor.
+
+        texture : pyvista.Texture or np.ndarray, optional
+            A texture to apply if the input mesh has texture
+            coordinates.  This will not work with MultiBlock
+            datasets.
+
+        render_points_as_spheres : bool, optional
+            Render points as spheres rather than dots.
+
+        render_lines_as_tubes : bool, optional
+            Show lines as thick tubes rather than flat lines.  Control
+            the width with ``line_width``.
+
+        smooth_shading : bool, optional
+            Enable smooth shading when ``True`` using the Phong
+            shading algorithm.  When ``False``, use flat shading.
+            Automatically enabled when ``pbr=True``.  See
+            :ref:`shading_example`.
+
+        split_sharp_edges : bool, optional
+            Split sharp edges exceeding 30 degrees when plotting with smooth
+            shading.  Control the angle with the optional keyword argument
+            ``feature_angle``.  By default this is ``False`` unless overridden
+            by the global or plotter theme.  Note that enabling this will
+            create a copy of the input mesh within the plotter.  See
+            :ref:`shading_example`.
+
+        ambient : float, optional
+            When lighting is enabled, this is the amount of light in
+            the range of 0 to 1 (default 0.0) that reaches the actor
+            when not directed at the light source emitted from the
+            viewer.
+
+        diffuse : float, optional
+            The diffuse lighting coefficient. Default 1.0.
+
+        specular : float, optional
+            The specular lighting coefficient. Default 0.0.
+
+        specular_power : float, optional
+            The specular power. Between 0.0 and 128.0.
+
+        nan_color : ColorLike, optional
+            The color to use for all ``NaN`` values in the plotted
+            scalar array.
+
+        nan_opacity : float, optional
+            Opacity of ``NaN`` values.  Should be between 0 and 1.
+            Default 1.0.
+
+        culling : str, optional
+            Does not render faces that are culled. Options are
+            ``'front'`` or ``'back'``. This can be helpful for dense
+            surface meshes, especially when edges are visible, but can
+            cause flat meshes to be partially displayed.  Defaults to
+            ``False``.
+
+        rgb : bool, optional
+            If an 2 dimensional array is passed as the scalars, plot
+            those values as RGB(A) colors. ``rgba`` is also an
+            accepted alias for this.  Opacity (the A) is optional.  If
+            a scalars array ending with ``"_rgba"`` is passed, the default
+            becomes ``True``.  This can be overridden by setting this
+            parameter to ``False``.
+
+        categories : bool, optional
+            If set to ``True``, then the number of unique values in
+            the scalar array will be used as the ``n_colors``
+            argument.
+
+        silhouette : dict, bool, optional
+            If set to ``True``, plot a silhouette highlight for the
+            mesh. This feature is only available for a triangulated
+            ``PolyData``.  As a ``dict``, it contains the properties
+            of the silhouette to display:
+
+                * ``color``: ``ColorLike``, color of the silhouette
+                * ``line_width``: ``float``, edge width
+                * ``opacity``: ``float`` between 0 and 1, edge transparency
+                * ``feature_angle``: If a ``float``, display sharp edges
+                  exceeding that angle in degrees.
+                * ``decimate``: ``float`` between 0 and 1, level of decimation
+
+        use_transparency : bool, optional
+            Invert the opacity mappings and make the values correspond
+            to transparency.
+
+        below_color : ColorLike, optional
+            Solid color for values below the scalars range
+            (``clim``). This will automatically set the scalar bar
+            ``below_label`` to ``'below'``.
+
+        above_color : ColorLike, optional
+            Solid color for values below the scalars range
+            (``clim``). This will automatically set the scalar bar
+            ``above_label`` to ``'above'``.
+
+        annotations : dict, optional
+            Pass a dictionary of annotations. Keys are the float
+            values in the scalars range to annotate on the scalar bar
+            and the values are the string annotations.
+
+        pickable : bool, optional
+            Set whether this actor is pickable.
+
+        preference : str, default: "point"
+            When ``mesh.n_points == mesh.n_cells`` and setting
+            scalars, this parameter sets how the scalars will be
+            mapped to the mesh.  Default ``'point'``, causes the
+            scalars will be associated with the mesh points.  Can be
+            either ``'point'`` or ``'cell'``.
+
+        log_scale : bool, default: False
+            Use log scale when mapping data to colors. Scalars less
+            than zero are mapped to the smallest representable
+            positive float.
+
+        pbr : bool, optional
+            Enable physics based rendering (PBR) if the mesh is
+            ``PolyData``.  Use the ``color`` argument to set the base
+            color.
+
+        metallic : float, optional
+            Usually this value is either 0 or 1 for a real material
+            but any value in between is valid. This parameter is only
+            used by PBR interpolation.
+
+        roughness : float, optional
+            This value has to be between 0 (glossy) and 1 (rough). A
+            glossy material has reflections and a high specular
+            part. This parameter is only used by PBR
+            interpolation.
+
+        render : bool, default: True
+            Force a render when ``True``.
+
+        user_matrix : np.ndarray | vtk.vtkMatrix4x4, default: np.eye(4)
+            Matrix passed to the Actor class before rendering. This affects the
+            actor/rendering only, not the input volume itself. The user matrix is the
+            last transformation applied to the actor before rendering. Defaults to the
+            identity matrix.
+
+        component : int, optional
+            Set component of vector valued scalars to plot.  Must be
+            nonnegative, if supplied. If ``None``, the magnitude of
+            the vector is plotted.
+
+        emissive : bool, optional
+            Treat the points/splats as emissive light sources. Only valid for
+            ``style='points_gaussian'`` representation.
+
+        copy_mesh : bool, default: False
+            If ``True``, a copy of the mesh will be made before adding it to
+            the plotter.  This is useful if you would like to add the same
+            mesh to a plotter multiple times and display different
+            scalars. Setting ``copy_mesh`` to ``False`` is necessary if you
+            would like to update the mesh after adding it to the plotter and
+            have these updates rendered, e.g. by changing the active scalars or
+            through an interactive widget. This should only be set to ``True``
+            with caution. Defaults to ``False``. This is ignored if the input
+            is a ``vtkAlgorithm`` subclass.
+
+        backface_params : dict | pyvista.Property, optional
+            A :class:`pyvista.Property` or a dict of parameters to use for
+            backface rendering. This is useful for instance when the inside of
+            oriented surfaces has a different color than the outside. When a
+            :class:`pyvista.Property`, this is directly used for backface
+            rendering. When a dict, valid keys are :class:`pyvista.Property`
+            attributes, and values are corresponding values to use for the
+            given property. Omitted keys (or the default of
+            ``backface_params=None``) default to the corresponding frontface
+            properties.
+
+        show_vertices : bool, optional
+            When ``style`` is not ``'points'``, render the external surface
+            vertices. The following optional keyword arguments may be used to
+            control the style of the vertices:
+
+            * ``vertex_color`` - The color of the vertices
+            * ``vertex_style`` - Change style to ``'points_gaussian'``
+            * ``vertex_opacity`` - Control the opacity of the vertices
+
+        edge_opacity : float, optional
+            Edge opacity of the mesh. A single float value that will be applied globally
+            edge opacity of the mesh and uniformly applied everywhere - should be
+            between 0 and 1.
+
+            .. note::
+                `edge_opacity` uses ``SetEdgeOpacity`` as the underlying method which
+                requires VTK version 9.3 or higher. If ``SetEdgeOpacity`` is not
+                available, `edge_opacity` is set to 1.
+
+        **kwargs : dict, optional
+            Optional keyword arguments.
+        """
+        raise NotImplementedError('This method is not implemented')
+
+    def add_scatter(self, xs: np.ndarray, ys: np.ndarray, zs: np.ndarray):
+        raise NotImplementedError('This method is not implemented')
+
+    def add_portmode(self, port: PortBC, k0: float, Npoints: int = 10, dv=(0,0,0), XYZ=None,
+                      field: Literal['E','H'] = 'E'):
+        raise NotImplementedError('This method is not implemented')
+
+    def add_quiver(self, x: np.ndarray, y: np.ndarray, z: np.ndarray,
+              dx: np.ndarray, dy: np.ndarray, dz: np.ndarray,
+              scale: float = 1,
+              scalemode: Literal['lin','log'] = 'lin'):
+        
+        raise NotImplementedError('This method is not implemented')
+    
+    def add_surf(self, 
+                 x: np.ndarray,
+                 y: np.ndarray,
+                 z: np.ndarray,
+                 field: np.ndarray,
+                 scale: Literal['lin','log','symlog'] = 'lin',
+                 cmap: cmap_names = 'coolwarm',
+                 clim: tuple[float, float] = None,
+                 opacity: float = 1.0,
+                 symmetrize: bool = True,
+                 animate: bool = False,
+                 **kwargs,):
+        """Add a surface plot to the display
+        The X,Y,Z coordinates must be a 2D grid of data points. The field must be a real field with the same size.
+
+        Args:
+            x (np.ndarray): The X-grid array
+            y (np.ndarray): The Y-grid array
+            z (np.ndarray): The Z-grid array
+            field (np.ndarray): The scalar field to display
+            scale (Literal["lin","log","symlog"], optional): The colormap scaling¹. Defaults to 'lin'.
+            cmap (cmap_names, optional): The colormap. Defaults to 'coolwarm'.
+            clim (tuple[float, float], optional): Specific color limits (min, max). Defaults to None.
+            opacity (float, optional): The opacity of the surface. Defaults to 1.0.
+            symmetrize (bool, optional): Wether to force a symmetrical color limit (-A,A). Defaults to True.
+        
+        (¹): lin: f(x)=x, log: f(x)=log₁₀(|x|), symlog: f(x)=sgn(x)·log₁₀(1+|x·ln(10)|)
+        """
+        raise NotImplementedError('This method is not implemented')

emerge/_emerge/plot/grapher.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+import matplotlib.pyplot as plt
+import numpy as np
+from typing import Any
+from itertools import cycle
+
+class Style:
+
+    def __init__(self):
+        self.linecolors: list = ['k']
+        self.linestyles: list[str] = ['-']
+        self.markers: list[str] = [None]
+
+        self.color_cycler = cycle(self.linecolors)
+        self.style_cycler = cycle(self.linestyles)
+        self.marker_cycle = cycle(self.markers)
+
+    def get_line_properties(self, color: str, linestyle: str, marker: str) -> dict[str, Any]:
+        if color is None:
+            color = next(self.color_cycler)
+        if linestyle is None:
+            linestyle = next(self.style_cycler)
+        if marker is None:
+            marker = next(self.marker_cycle)
+        return dict(color=color, linestyle=linestyle, marker=marker)
+
+    def dress(self, axis):
+        axis.grid(True, axis='both', color='k')
+
+class Grapher:
+
+    def __init__(self):
+        self.axes: list = []
+        self.axes_grid: list[list] = []
+        self.fig = None
+        self.style: Style = Style()
+        self.nrows: int = 0
+        self.ncols: int = 0
+        self.current: int = 0
+
+        self.cur_axis = None
+    
+    @property
+    def ax(self) -> plt.axis:
+        if self.cur_axis is None:
+            return self.axes[0]
+        return self.cur_axis
+    
+    def reset(self):
+        self.cur_axis = None
+
+    def __call__(self, i: int = None, j: int = None) -> Grapher:
+        if i is None:
+            self.cur_axis = self.axes[0]
+        return self
+        if j is None and i is not None:
+            self.cur_axis = self.axes[i]
+        else:
+            self.cur_axis = self.axes[i,j]
+        return self
+    
+    def new(self, rows: int = 1, cols: int = 1) -> Grapher:
+        self.fig, self.axes = plt.subplots(rows, cols)
+        if rows==1 and cols==1:
+            self.axes = [self.axes]
+        self.nrows = rows
+        self.ncols = cols 
+        return self
+
+    def line(self,
+             xs: np.ndarray,
+             ys: np.ndarray,
+             color: str = None,
+             linestyle: str = None,
+             marker: str = None,
+             dB: bool = False) -> Grapher:
+        if dB:
+            ys = 20*np.log10(np.abs(ys))
+        self.ax.plot(xs, ys, **self.style.get_line_properties(color=color, linestyle=linestyle, marker=marker))
+        self.reset()
+        return self
+
+    def show(self):
+        for ax in self.axes:
+            self.style.dress(ax)
+        plt.show()
+
+gr = Grapher().new()
+
+xs = np.linspace(1e9, 2e9, 1001)
+ys = np.sin(xs/1e8)
+
+gr().line(xs, ys).show()