emerge 1.0.7__py3-none-any.whl → 1.1.1__py3-none-any.whl

emerge/_emerge/physics/microwave/microwave_bc.py

@@ -29,6 +29,7 @@ from ...bc import BoundaryCondition, BoundaryConditionSet, Periodic
 from ...periodic import PeriodicCell, HexCell, RectCell
 from ...material import Material
 from ...const import Z0, C0, EPS0, MU0
+from ...logsettings import DEBUG_COLLECTOR
 
 ############################################################
 #                     UTILITY FUNCTIONS                    #
@@ -59,6 +60,7 @@ class MWBoundaryConditionSet(BoundaryConditionSet):
         self.RectangularWaveguide: type[RectangularWaveguide] = self._construct_bc(RectangularWaveguide)
         self.Periodic: type[Periodic] = self._construct_bc(Periodic)
         self.FloquetPort: type[FloquetPort] = self._construct_bc(FloquetPort)
+        self.UserDefinedPort: type[UserDefinedPort] = self._construct_bc(UserDefinedPort)
 
         self._cell: PeriodicCell | None = None
 
@@ -341,7 +343,6 @@ class PortMode:
     norm_factor: float = 1
     freq: float = 0
     neff: float = 1
-    TEM: bool = True
     Z0: float = 50.0
     polarity: float = 1.0
     modetype: Literal['TEM','TE','TM'] = 'TEM'
@@ -459,7 +460,7 @@ class ModalPort(PortBC):
                  port_number: int, 
                  cs: CoordinateSystem | None = None,
                  power: float = 1,
-                 TEM: bool = False,
+                 modetype: Literal['TE','TM','TEM'] | None = None,
                  mixed_materials: bool = False):
         """Generes a ModalPort boundary condition for a port that requires eigenmode solutions for the mode.
 
@@ -476,7 +477,7 @@ class ModalPort(PortBC):
             port_number (int): The port number as an integer
             cs (CoordinateSystem, optional): The local coordinate system of the port face. Defaults to None.
             power (float, optional): The radiated power. Defaults to 1.
-            TEM (bool, optional): Wether the mode should be considered as a TEM mode. Defaults to False
+            modetype (str[TE, TM, TEM], optional): Wether the mode should be considered as a TEM mode. Defaults to False
             mixed_materials (bool, optional): Wether the port consists of multiple different dielectrics. This requires
                 A recalculation of the port mode at every frequency
         """
@@ -490,7 +491,7 @@ class ModalPort(PortBC):
         self.selected_mode: int = 0
         self.modes: dict[float, list[PortMode]] = defaultdict(list)
 
-        self.TEM: bool = TEM
+        self.forced_modetype: Literal['TE','TM','TEM'] | None = modetype
         self.mixed_materials: bool = mixed_materials
         self.initialized: bool = False
         self._first_k0: float | None = None
@@ -506,7 +507,25 @@ class ModalPort(PortBC):
             raise ValueError('No Coordinate System could be derived.')
         self._er: np.ndarray | None = None
         self._ur: np.ndarray | None = None
+        
+        self.vintline: list[Line] = []
+
+    def set_integration_line(self, c1: tuple[float, float, float], c2: tuple[float, float, float], N: int = 21) -> None:
+        """Define the integration line start and end point
+
+        Args:
+            c1 (tuple[float, float, float]): The start coordinate
+            c2 (tuple[float, float, float]): The end coordinate
+            N (int, optional): The number of integration points. Defaults to 21.
+        """
+        self.vintline.append(Line.from_points(c1, c2, N))
     
+    def reset(self) -> None:
+        self.modes: dict[float, list[PortMode]] = defaultdict(list)
+        self.initialized: bool = False
+        self.plus_terminal: list[tuple[int, int]] = []
+        self.minus_terminal: list[tuple[int, int]] = []
+        
     def portZ0(self, k0: float) -> complex | float | None:
         return self.get_mode(k0).Z0
     
@@ -524,6 +543,11 @@ class ModalPort(PortBC):
         """ 
         self.alignment_vectors = [_parse_axis(ax) for ax in axes]
     
+    def _get_alignment_vector(self, index: int) -> np.ndarray | None:
+        if len(self.alignment_vectors) > index:
+            return self.alignment_vectors[index].np
+        return None
+    
     def set_terminals(self, positive: Selection | GeoObject | None = None,
                       negative: Selection | GeoObject | None = None,
                       ground: Selection | GeoObject | None = None) -> None:
@@ -616,7 +640,7 @@ class ModalPort(PortBC):
                  beta: float,
                  k0: float,
                  residual: float,
-                 TEM: bool,
+                 number: int,
                  freq: float) -> PortMode | None:
         """Add a mode function to the ModalPort
 
@@ -627,16 +651,17 @@ class ModalPort(PortBC):
             beta (float): The out-of-plane propagation constant 
             k0 (float): The free space phase constant
             residual (float): The solution residual
-            TEM (bool): Whether its a TEM mode
             freq (float): The frequency of the port mode
 
         Returns:
             PortMode: The port mode object.
         """
-        mode = PortMode(field, E_function, H_function, k0, beta, residual, TEM=TEM, freq=freq)
+        mode = PortMode(field, E_function, H_function, k0, beta, residual, freq=freq)
+        
         if mode.energy < 1e-4:
             logger.debug(f'Ignoring mode due to a low mode energy: {mode.energy}')
             return None
+        
         self.modes[k0].append(mode)
         self.initialized = True
 
@@ -659,7 +684,7 @@ class ModalPort(PortBC):
     
     def get_beta(self, k0: float) -> float:
         mode = self.get_mode(k0)
-        if mode.TEM:
+        if self.forced_modetype=='TEM':
             beta = mode.beta/mode.k0 * k0
         else:
             freq = k0*299792458/(2*np.pi)
@@ -748,6 +773,7 @@ class RectangularWaveguide(PortBC):
             logger.info(' - Constructing coordinate system from normal port')
             self.cs = Axis(self.selection.normal).construct_cs()
             logger.debug(f' - Port CS: {self.cs}')
+    
     def get_basis(self) -> np.ndarray:
         return self.cs._basis
         
@@ -816,6 +842,125 @@ class RectangularWaveguide(PortBC):
         Exg, Eyg, Ezg = self.cs.in_global_basis(Ex, Ey, Ez)
         return np.array([Exg, Eyg, Ezg])
 
+def _f_zero(k0,x,y,z):
+    "Zero field function"
+    return np.zeros_like(x, dtype=np.complex128)
+
+class UserDefinedPort(PortBC):
+    
+    _include_stiff: bool = True
+    _include_mass: bool = False
+    _include_force: bool = True
+
+    def __init__(self, 
+                 face: FaceSelection | GeoSurface,
+                 port_number: int, 
+                 Ex: Callable | None = None,
+                 Ey: Callable | None = None,
+                 Ez: Callable | None = None,
+                 kz: Callable | None = None,
+                 power: float = 1.0,
+                 modetype: Literal['TEM','TE','TM'] = 'TEM',
+                 cs: CoordinateSystem | None = None):
+        """Creates a user defined port field
+        
+        The UserDefinedPort is defined based on user defined field callables. All undefined callables will default to 0 field or k0.
+        
+        All spatial field functions should be defined using the template:
+        >>> def Ec(k0: float, x: np.ndarray, y: np.ndarray, z: np.ndarray) -> np.ndarray
+        >>>     return #shape like x
+        
+        Args:
+            face (FaceSelection, GeoSurface): The port boundary face selection
+            port_number (int): The port number
+            Ex (Callable): The Ex(k0,x,y,z) field
+            Ey (Callable): The Ey(k0,x,y,z) field
+            Ez (Callable): The Ez(k0,x,y,z) field
+            kz (Callable): The out of plane propagation constant kz(k0)
+            power (float): The port output power
+        """
+        super().__init__(face)
+        if cs is None:
+            cs = GCS
+
+        self.cs = cs
+        self.port_number: int= port_number
+        self.active: bool = False
+        self.power: float = power
+        self.type: str = 'TE'
+        if Ex is None:
+            Ex = _f_zero
+        if Ey is None:
+            Ey = _f_zero
+        if Ez is None:
+            Ez = _f_zero
+        if kz is None:
+            kz = lambda k0: k0
+
+        self._fex: Callable = Ex
+        self._fey: Callable = Ey
+        self._fez: Callable = Ez
+        self._fkz: Callable = kz
+        self.type = modetype
+
+    def get_basis(self) -> np.ndarray:
+        return self.cs._basis
+        
+    def get_inv_basis(self) -> np.ndarray:
+        return self.cs._basis_inv
+    
+    def modetype(self, k0):
+        return self.type
+    
+    def get_amplitude(self, k0: float) -> float:
+        return np.sqrt(self.power)
+
+    def get_beta(self, k0: float) -> float:
+        ''' Return the out of plane propagation constant. βz.'''
+        return self._fkz(k0)
+    
+    def get_gamma(self, k0: float) -> complex:
+        """Computes the γ-constant for matrix assembly. This constant is required for the Robin boundary condition.
+
+        Args:
+            k0 (float): The free space propagation constant.
+
+        Returns:
+            complex: The γ-constant
+        """
+        return 1j*self.get_beta(k0)
+    
+    def get_Uinc(self, x_global: np.ndarray, y_global: np.ndarray, z_global: np.ndarray, k0: float) -> np.ndarray:
+        return -2*1j*self.get_beta(k0)*self.port_mode_3d_global(x_global, y_global, z_global, k0)
+    
+    def port_mode_3d(self, 
+                     x_local: np.ndarray,
+                     y_local: np.ndarray,
+                     k0: float,
+                     which: Literal['E','H'] = 'E') -> np.ndarray:
+        x_global, y_global, z_global = self.cs.in_global_cs(x_local, y_local, 0*x_local)
+
+        Egxyz = self.port_mode_3d_global(x_global,y_global,z_global,k0,which=which)
+        
+        Ex, Ey, Ez = self.cs.in_local_basis(Egxyz[0,:], Egxyz[1,:], Egxyz[2,:])
+
+        Exyz = np.array([Ex, Ey, Ez])
+        return Exyz
+
+    def port_mode_3d_global(self, 
+                            x_global: np.ndarray,
+                            y_global: np.ndarray,
+                            z_global: np.ndarray,
+                            k0: float,
+                            which: Literal['E','H'] = 'E') -> np.ndarray:
+        '''Compute the port mode field for global xyz coordinates.'''
+        xl, yl, _ = self.cs.in_local_cs(x_global, y_global, z_global)
+        Ex = self._fex(k0, x_global, y_global, z_global)
+        Ey = self._fey(k0, x_global, y_global, z_global)
+        Ez = self._fez(k0, x_global, y_global, z_global)
+        Exg, Eyg, Ezg = self.cs.in_global_basis(Ex, Ey, Ez)
+        return np.array([Exg, Eyg, Ezg])
+    
 class LumpedPort(PortBC):
     
     _include_stiff: bool = True
@@ -874,6 +1019,11 @@ class LumpedPort(PortBC):
         self.vintline: list[Line] = []
         self.v_integration = True
 
+        # Sanity checks
+        if self.width > 0.5 or self.height > 0.5:
+            DEBUG_COLLECTOR.add_report(f'{self}: A lumped port width/height larger than 0.5m has been detected: width={self.width:.3f}m. Height={self.height:.3f}.m. Perhaps you forgot a unit like mm, um, or mil')
+
+        
     @property
     def surfZ(self) -> float:
         """The surface sheet impedance for the lumped port

emerge/_emerge/physics/microwave/microwave_data.py

@@ -667,13 +667,51 @@ class MWField:
         return sum([self.excitation[mode.port_number]*self._fields[mode.port_number] for mode in self.port_modes]) # type: ignore
     
     def set_field_vector(self) -> None:
-        """Defines the default excitation coefficients for the current dataset"""
+        """Defines the default excitation coefficients for the current dataset as an excitation of only port 1."""
         self.excitation = {key: 0.0 for key in self._fields.keys()}
         self.excitation[self.port_modes[0].port_number] = 1.0 + 0j
 
-    def excite_port(self, number: int) -> None:
+    def excite_port(self, number: int, excitation: complex = 1.0 + 0.0j) -> None:
+        """Excite a single port provided by a given port number
+
+        Args:
+            number (int): The port number to excite
+            coefficient (complex): The port excitation. Defaults to 1.0 + 0.0j
+        """
+        self.excitation = {key: 0.0 for key in self._fields.keys()}
+        self.excitation[self.port_modes[number-1].port_number] = excitation
+    
+    def set_excitations(self, *excitations: complex) -> None:
+        """Set bulk port excitations by an ordered array of excitation coefficients.
+
+        Returns:
+            *complex: A sequence of complex numbers
+        """
         self.excitation = {key: 0.0 for key in self._fields.keys()}
-        self.excitation[self.port_modes[number].port_number] = 1.0 + 0j
+        for iport, coeff in enumerate(excitations):
+            self.excitation[self.port_modes[iport].port_number] = coeff
+    
+    def combine_ports(self, p1: int, p2: int) -> MWField:
+        """Combines ports p1 and p2 into a cifferential and common mode port respectively.
+        
+        The p1 index becomes the differential mode port
+        The p2 index becomes the common mode port
+
+        Args:
+            p1 (int): The first port number
+            p2 (int): The second port number
+
+        Returns:
+            MWField: _description_
+        """
+        
+        fp1 = self._fields[p1]
+        fp2 = self._fields[p2]
+        
+        self._fields[p1] = (fp1-fp2)/np.sqrt(2)
+        self._fields[p2] = (fp1+fp2)/np.sqrt(2)
+        
+        return self
         
     @property
     def EH(self) -> tuple[np.ndarray, np.ndarray]:
@@ -720,7 +758,9 @@ class MWField:
         xf = xs.flatten()
         yf = ys.flatten()
         zf = zs.flatten()
+        logger.debug(f'Interpolating {xf.shape[0]} field points')
         Ex, Ey, Ez = self.basis.interpolate(self._field, xf, yf, zf, usenan=usenan)
+        logger.debug('E Interpolation complete')
         self.Ex = Ex.reshape(shp)
         self.Ey = Ey.reshape(shp)
         self.Ez = Ez.reshape(shp)
@@ -728,6 +768,7 @@ class MWField:
         
         constants = 1/ (-1j*2*np.pi*self.freq*(self._dur*MU0) )
         Hx, Hy, Hz = self.basis.interpolate_curl(self._field, xf, yf, zf, constants, usenan=usenan)
+        logger.debug('H Interpolation complete')
         ids = self.basis.interpolate_index(xf, yf, zf)
         
         self.er = self._der[ids].reshape(shp)
@@ -743,10 +784,10 @@ class MWField:
         
         return field
     
-    def _solution_quality(self) -> tuple[np.ndarray, np.ndarray]:
+    def _solution_quality(self, solve_ids: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
         from .adaptive_mesh import compute_error_estimate
         
-        error_tet, max_elem_size = compute_error_estimate(self)
+        error_tet, max_elem_size = compute_error_estimate(self, solve_ids)
         return error_tet, max_elem_size
         
     def boundary(self,
@@ -1146,6 +1187,54 @@ class MWScalarNdim:
     def S(self, i1: int, i2: int) -> np.ndarray:
         return self.Sp[...,self._portmap[i1], self._portmap[i2]]
     
+    def combine_ports(self, p1: int, p2: int) -> MWScalarNdim:
+        """Combine ports p1 and p2 into a differential and common mode port respectively.
+
+        The p1 index becomes the differential mode port
+        The p2 index becomes the common mode port
+
+        Args:
+            p1 (int): The first port number
+            p2 (int): The second port number
+
+        Returns:
+            MWScalarNdim: _description_
+        """
+        if p1==p2:
+            raise ValueError('p1 and p2 must be different port numbers')
+        
+        F, N, _ = self.Sp.shape
+        p1 = p1-1
+        p2 = p2-1
+        
+        if not (0 <= p1 < N and 0 <= p2 < N):
+            raise IndexError(f'Ports {p1+1} or {p2+1} are out of range {N}')
+        
+        Sout = self.Sp.copy()
+        ii, jj = p1, p2
+        idx = np.ones(N, dtype=np.bool)
+        idx[[ii,jj]] = False
+        others = np.nonzero(idx)[0]
+        isqrt2 = 1.0 / np.sqrt(2.0)
+        
+        Sout[:, others, ii] = (self.Sp[:, others, ii] - self.Sp[:, others, jj]) * isqrt2
+        Sout[:, others, jj] = (self.Sp[:, others, ii] + self.Sp[:, others, jj]) * isqrt2
+        Sout[:, ii, others] = (self.Sp[:, ii, others] - self.Sp[:, jj, others]) * isqrt2
+        Sout[:, jj, others] = (self.Sp[:, ii, others] + self.Sp[:, jj, others]) * isqrt2
+        
+        Sii = self.Sp[:, ii, ii]
+        Sij = self.Sp[:, ii, jj]
+        Sji = self.Sp[:, jj, ii]
+        Sjj = self.Sp[:, jj, jj]
+        
+        Sout[:, ii, ii] = 0.5 *(Sii - Sij - Sji + Sjj)
+        Sout[:, ii, jj] = 0.5 *(Sii + Sij - Sji - Sjj)
+        Sout[:, jj, ii] = 0.5 *(Sii - Sij + Sji - Sjj)
+        Sout[:, jj, jj] = 0.5 *(Sii + Sij + Sji + Sjj)
+        
+        self.Sp = Sout
+        
+        return self
     @property
     def Smat(self) -> np.ndarray:
         """Returns the full S-matrix

emerge/_emerge/plot/pyvista/display.py

@@ -15,20 +15,21 @@
 # along with this program; if not, see
 # <https://www.gnu.org/licenses/>.
 from __future__ import annotations
-import time
 from ...mesh3d import Mesh3D
+from ...simstate import SimState
 from ...geometry import GeoObject
 from ...selection import FaceSelection, DomainSelection, EdgeSelection, Selection, encode_data
 from ...physics.microwave.microwave_bc import PortBC, ModalPort
-import numpy as np
-import pyvista as pv
-from typing import Iterable, Literal, Callable, Any
 from ..display import BaseDisplay
 from .display_settings import PVDisplaySettings
-from matplotlib.colors import ListedColormap
 from .cmap_maker import make_colormap
 
+import time
+import numpy as np
+import pyvista as pv
+from typing import Iterable, Literal, Callable, Any
 from itertools import cycle
+from loguru import logger
 ### Color scale
 
 # Define the colors we want to use
@@ -232,8 +233,8 @@ class _AnimObject:
 
 class PVDisplay(BaseDisplay):
 
-    def __init__(self, mesh: Mesh3D):
-        self._mesh: Mesh3D = mesh
+    def __init__(self, state: SimState):
+        self._state: SimState = state
         self.set: PVDisplaySettings = PVDisplaySettings()
         
         # Animation options
@@ -241,6 +242,7 @@ class PVDisplay(BaseDisplay):
         self._stop: bool = False
         self._objs: list[_AnimObject] = []
         self._do_animate: bool = False
+        self._animate_next: bool = False
         self._closed_via_x: bool = False
         self._Nsteps: int  = 0
         self._fps: int = 25
@@ -260,6 +262,9 @@ class PVDisplay(BaseDisplay):
         self._cbar_lim: tuple[float, float] | None = None
         self.camera_position = (1, -1, 1)     # +X, +Z, -Y
     
+    @property
+    def _mesh(self) -> Mesh3D:
+        return self._state.mesh
     
     def cbar(self, name: str, n_labels: int = 5, interactive: bool = False, clim: tuple[float, float] | None = None ) -> PVDisplay:
         self._cbar_args = dict(title=name, n_labels=n_labels, interactive=interactive)
@@ -302,8 +307,7 @@ class PVDisplay(BaseDisplay):
         self._ruler.min_length = max(1e-3, min(self._mesh.edge_lengths))
         self._update_camera()
         self._add_aux_items()
-        # self._plot.renderer.enable_depth_peeling(20, 0.8)
-        # self._plot.enable_anti_aliasing(self.set.anti_aliassing)
+        self._add_background()
         if self._do_animate:
             self._wire_close_events()
             self.add_text('Press Q to close!',color='red', position='upper_left')
@@ -313,14 +317,17 @@ class PVDisplay(BaseDisplay):
             self._plot.show()
         
         self._reset()
-    
-    def set_mesh(self, mesh: Mesh3D):
-        """Define the mesh to be used
 
-        Args:
-            mesh (Mesh3D): The mesh object
-        """
-        self._mesh = mesh
+    def _add_background(self):
+        from pyvista import examples
+        from requests.exceptions import ConnectionError
+        
+        try:
+            cubemap = examples.download_sky_box_cube_map()
+            self._plot.set_environment_texture(cubemap)
+        except ConnectionError:
+            logger.warning(f'No internet, no background texture will be used.')
+        
 
     def _reset(self):
         """ Resets key display parameters."""
@@ -328,6 +335,7 @@ class PVDisplay(BaseDisplay):
         self._plot = pv.Plotter()
         self._stop = False
         self._objs = []
+        self._animate_next = False
         C_CYCLE = _gen_c_cycle()
 
     def _close_callback(self, arg):
@@ -397,6 +405,7 @@ class PVDisplay(BaseDisplay):
         print('If you closed the animation without using (Q) press Ctrl+C to kill the process.')
         self._Nsteps = Nsteps
         self._fps = fps
+        self._animate_next = True
         self._do_animate = True
         return self
     
@@ -456,6 +465,10 @@ class PVDisplay(BaseDisplay):
     ## OBLIGATORY METHODS
     def add_object(self, obj: GeoObject | Selection, mesh: bool = False, volume_mesh: bool = True, label: bool = False, *args, **kwargs):
         
+        if isinstance(obj, GeoObject):
+            if obj._hidden:
+                return
+            
         show_edges = False
         opacity = obj.opacity
         line_width = 0.5
@@ -508,7 +521,7 @@ class PVDisplay(BaseDisplay):
         
         self._plot.add_mesh(self._volume_edges(_select(obj)), color='#000000', line_width=2, show_edges=True)
         
-        if isinstance(obj, GeoObject) and label:
+        if label:
             points = []
             labels = []
             for dt in obj.dimtags:
@@ -681,14 +694,14 @@ class PVDisplay(BaseDisplay):
         actor = self._plot.add_mesh(grid_no_nan, scalars=name, scalar_bar_args=self._cbar_args, **kwargs)
 
 
-        if self._do_animate:
+        if self._animate_next:
             def on_update(obj: _AnimObject, phi: complex):
                 field_anim = obj.T(np.real(obj.field * phi))
                 obj.grid[name] = field_anim
                 obj.fgrid[name] = obj.grid.threshold(scalars=name)[name]
                 #obj.fgrid replace with thresholded scalar data.
             self._objs.append(_AnimObject(field_flat, T, grid, grid_no_nan, actor, on_update))
-        
+            self._animate_next = False
         self._reset_cbar()
     
     def add_boundary_field(self, 
@@ -763,13 +776,13 @@ class PVDisplay(BaseDisplay):
         kwargs = setdefault(kwargs, cmap=cmap, clim=clim, opacity=opacity, pickable=False, multi_colors=True)
         actor = self._plot.add_mesh(grid, scalars=name, scalar_bar_args=self._cbar_args, **kwargs)
 
-        if self._do_animate:
+        if self._animate_next:
             def on_update(obj: _AnimObject, phi: complex):
                 field_anim = obj.T(np.real(obj.field * phi))
                 obj.grid[name] = field_anim
                 #obj.fgrid replace with thresholded scalar data.
             self._objs.append(_AnimObject(field_flat, T, grid, grid, actor, on_update))
-        
+            self._animate_next = False
         self._reset_cbar()
         
     def add_title(self, title: str) -> None:
@@ -911,7 +924,7 @@ class PVDisplay(BaseDisplay):
         
         actor = self._plot.add_mesh(contour, opacity=opacity, cmap=cmap, clim=clim, pickable=False, scalar_bar_args=self._cbar_args)
         
-        if self._do_animate:
+        if self._animate_next:
             def on_update(obj: _AnimObject, phi: complex):
                 new_vals = obj.T(np.real(obj.field * phi))
                 obj.grid['anim'] = new_vals
@@ -919,7 +932,7 @@ class PVDisplay(BaseDisplay):
                 obj.actor.GetMapper().SetInputData(new_contour) # type: ignore
                 
             self._objs.append(_AnimObject(field, T, grid, None, actor, on_update)) # type: ignore
-            
+            self._animate_next = False
         self._reset_cbar()
         
     def _add_aux_items(self) -> None:

emerge/_emerge/selection.py

@@ -21,6 +21,9 @@ import numpy as np
 from .cs import Axis, CoordinateSystem, _parse_vector, Plane
 from typing import Callable, TypeVar, Iterable, Any
 
+class SelectionError(Exception):
+    pass
+
 def align_rectangle_frame(pts3d: np.ndarray, normal: np.ndarray) -> dict[str, Any]:
     """Tries to find a rectangle as convex-hull of a set of points with a given normal vector.
 
@@ -174,7 +177,7 @@ class Selection:
     """
     dim: int = -1
     def __init__(self, tags: list[int] | set[int] | tuple[int] | None = None):
-
+        self.name: str = 'Selection'
         self._tags: set[int] = set()
 
         if tags is not None:
@@ -252,7 +255,19 @@ class Selection:
                 maxy = max(maxy, y1)
                 maxz = max(maxz, z1)
             return (minx, miny, minz), (maxx, maxy, maxz)
-        
+    
+    def _named(self, name: str) -> Selection:
+        """Sets the name of the selection and returns it
+
+        Args:
+            name (str): The name of the selection
+
+        Returns:
+            Selection: The same selection object
+        """
+        self.name = name
+        return self
+    
     def exclude(self, xyz_excl_function: Callable = lambda x,y,z: True, plane: Plane | None = None, axis: Axis | None = None) -> Selection:
         """Exclude points by evaluating a function(x,y,z)-> bool