emerge 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

emerge/_emerge/mesher.py

@@ -210,9 +210,41 @@ class Mesher:
         gmsh.model.mesh.field.set_numbers(ctag, "SurfacesList", tags)
         gmsh.model.mesh.field.set_number(ctag, "VIn", max_size)
         self.mesh_fields.append(ctag)
+        
+    def _set_size_on_edge(self, tags: list[int], max_size: float) -> None:
+        """Define the size of the mesh on an edge
 
-    def set_mesh_size(self, discretizer: Callable, resolution: float):
+        Args:
+            tags (list[int]): The tags of the geometry
+            max_size (float): The maximum size (in meters)
+        """
+        ctag = gmsh.model.mesh.field.add("Constant")
+        gmsh.model.mesh.field.set_numbers(ctag, "CurvesList", tags)
+        gmsh.model.mesh.field.set_number(ctag, "VIn", max_size)
+        self.mesh_fields.append(ctag)
         
+    def _set_size_on_point(self, tags: list[int], max_size: float) -> None:
+        """Define the size of the mesh on a point
+
+        Args:
+            tags (list[int]): The tags of the geometry
+            max_size (float): The maximum size (in meters)
+        """
+        ctag = gmsh.model.mesh.field.add("Constant")
+        gmsh.model.mesh.field.set_numbers(ctag, "PointsList", tags)
+        gmsh.model.mesh.field.set_number(ctag, "VIn", max_size)
+        self.mesh_fields.append(ctag)
+
+    def _configure_mesh_size(self, discretizer: Callable, resolution: float):
+        """Defines the mesh sizes based on a discretization callable.
+        The discretizer must take a material and return a maximum
+        size for that material.
+
+        Args:
+            discretizer (Callable): The discretization function
+            resolution (float): The resolution
+        """
+        logger.debug('Starting initial mesh size computation.')
         dimtags = gmsh.model.occ.get_entities(2)
 
         for dim, tag in dimtags:
@@ -227,21 +259,24 @@ class Mesher:
 
             size = discretizer(obj.material)*resolution*obj.mesh_multiplier
             size = min(size, obj.max_meshsize)
-            logger.info(f'Setting mesh size for {_DOM_TO_STR[obj.dim]} domain with tags {obj.tags} to {1000*size:.3f}mm')
+            
             for tag in obj.tags:
                 size_mapping[tag] = size
         
         for tag, size in size_mapping.items():
+            logger.debug(f'Setting mesh size:{1000*size:.3f}mm in domains: {tag}')
             self._set_size_in_domain([tag,], size)
 
         gmsh.model.mesh.field.setNumbers(mintag, "FieldsList", self.mesh_fields)
         gmsh.model.mesh.field.setAsBackgroundMesh(mintag)
 
         for tag, size in self.size_definitions:
+            logger.debug(f'Setting aux size definition: {1000*size:.3f}mm in domain {tag}.')
             gmsh.model.mesh.setSize([tag,], size)
 
     def unset_constraints(self, dimtags: list[tuple[int,int]]):
         '''Unset the mesh constraints for the given dimension tags.'''
+        logger.trace(f'Unsetting mesh size constraint for domains: {dimtags}')
         for dimtag in dimtags:
             gmsh.model.mesh.setSizeFromBoundary(dimtag[0], dimtag[1], 0)
             
@@ -263,13 +298,16 @@ class Mesher:
             return
         
         dimtags = boundary.dimtags
-
+        
+        
         if max_size is None:
             self._check_ready()
             max_size = self.max_size
         
         growth_distance = np.log10(max_size/size)/np.log10(growth_rate)
         
+        logger.debug(f'Setting boundary size for region {dimtags} to {size*1000:.3f}mm, GR={growth_rate:.3f}, dist={growth_distance*1000:.2f}mm, Max={max_size*1000:.3f}mm')
+        
         nodes = gmsh.model.getBoundary(dimtags, combined=False, oriented=False, recursive=False)
 
         disttag = gmsh.model.mesh.field.add("Distance")
@@ -295,6 +333,12 @@ class Mesher:
             obj (GeoVolume | Selection): The volumetric domain
             size (float): The maximum mesh size
         """
+        if obj.dim != 3:
+            logger.warning('Provided object is not a volume.')
+            if obj.dim==2:
+                logger.warning('Forwarding to set_face_size')
+                self.set_face_size(obj, size)
+        logger.debug(f'Setting size {size*1000:.3f}ff for object {obj}')
         self._set_size_in_domain(obj.tags, size)
 
     def set_face_size(self, obj: GeoSurface | Selection, size: float):
@@ -304,7 +348,30 @@ class Mesher:
             obj (GeoSurface | Selection): The surface domain
             size (float): The maximum size
         """
+        if obj.dim != 2:
+            logger.warning('Provided object is not a surface.')
+            if obj.dim==3:
+                logger.warning('Forwarding to set_domain_size')
+                self.set_face_size(obj, size)
+        
+        logger.debug(f'Setting size {size*1000:.3f}ff for face {obj}')
         self._set_size_on_face(obj.tags, size)
+    
+    def set_size(self, obj: GeoObject, size: float) -> None:
+        """Manually set the size in or on an object
+
+        Args:
+            obj (GeoObject): _description_
+            size (float): _description_
+        """
+        if obj.dim == 2:
+            self._set_size_on_face(obj.tags, size)
+        elif obj.dim == 3:
+            self._set_size_in_domain(obj.tags, size)
+        elif obj.dim == 1:
+            self._set_size_on_edge(obj.tags, size)
+        elif obj.dim == 0:
+            self._set_size_on_point(obj.tags, size)
         
     def refine_conductor_edge(self, dimtags: list[tuple[int,int]], size):
         nodes = gmsh.model.getBoundary(dimtags, combined=False, recursive=False)

emerge/_emerge/physics/microwave/assembly/assembler.py

@@ -27,6 +27,7 @@ from ..simjob import SimJob
 
 from ....const import MU0, EPS0, C0
 
+_PBC_DSMAX = 1e-15
 
 ############################################################
 #                         FUNCTIONS                        #
@@ -361,8 +362,8 @@ class Assembler:
             edge_ids_2 = mesh.get_edges(pbc.face2.tags)
             dv = np.array(pbc.dv)
             logger.trace(f'..displacement vector {dv}')
-            linked_tris = pair_coordinates(mesh.tri_centers, tri_ids_1, tri_ids_2, dv, 1e-9)
-            linked_edges = pair_coordinates(mesh.edge_centers, edge_ids_1, edge_ids_2, dv, 1e-9)
+            linked_tris = pair_coordinates(mesh.tri_centers, tri_ids_1, tri_ids_2, dv, _PBC_DSMAX)
+            linked_edges = pair_coordinates(mesh.edge_centers, edge_ids_1, edge_ids_2, dv, _PBC_DSMAX)
             dv = np.array(pbc.dv)
             phi = pbc.phi(K0)
             logger.trace(f'..ϕ={phi} rad/m')
@@ -547,8 +548,8 @@ class Assembler:
             tri_ids_2 = mesh.get_triangles(bcp.face2.tags)
             edge_ids_2 = mesh.get_edges(bcp.face2.tags)
             dv = np.array(bcp.dv)
-            linked_tris = pair_coordinates(mesh.tri_centers, tri_ids_1, tri_ids_2, dv, 1e-9)
-            linked_edges = pair_coordinates(mesh.edge_centers, edge_ids_1, edge_ids_2, dv, 1e-9)
+            linked_tris = pair_coordinates(mesh.tri_centers, tri_ids_1, tri_ids_2, dv, _PBC_DSMAX)
+            linked_edges = pair_coordinates(mesh.edge_centers, edge_ids_1, edge_ids_2, dv, _PBC_DSMAX)
             dv = np.array(bcp.dv)
             phi = bcp.phi(k0)
             

emerge/_emerge/physics/microwave/assembly/curlcurl.py

@@ -160,7 +160,6 @@ def tet_mass_stiffness_matrices(field: Nedelec2,
     edges = field.mesh.edges
     nodes = field.mesh.nodes
 
-    nT = tets.shape[1]
     tet_to_field = field.tet_to_field
     tet_to_edge = field.mesh.tet_to_edge
     nE = edges.shape[1]

emerge/_emerge/physics/microwave/assembly/generalized_eigen.py

@@ -18,7 +18,7 @@
 import numpy as np
 from ....elements.nedleg2 import NedelecLegrange2
 from scipy.sparse import csr_matrix
-from ....mth.optimized import local_mapping, matinv, compute_distances, gaus_quad_tri
+from ....mth.optimized import local_mapping, matinv, compute_distances
 from numba import c16, types, f8, i8, njit, prange
 
 
@@ -48,7 +48,6 @@ def generelized_eigenvalue_matrix(field: NedelecLegrange2,
     edges = field.mesh.edges
     nodes = field.mesh.nodes
     
-    nT = tris.shape[1]
     tri_to_field = field.tri_to_field
 
     nodes = field.local_nodes

emerge/_emerge/physics/microwave/assembly/generalized_eigen_hb.py

@@ -18,7 +18,7 @@
 import numpy as np
 from ....elements.nedleg2 import NedelecLegrange2
 from scipy.sparse import csr_matrix
-from ....mth.optimized import local_mapping, matinv, compute_distances, gaus_quad_tri
+from ....mth.optimized import local_mapping, matinv, compute_distances
 from numba import c16, types, f8, i8, njit, prange
 
 

emerge/_emerge/physics/microwave/assembly/robin_abc_order2.py

@@ -18,7 +18,6 @@
 
 import numpy as np
 from ....elements import Nedelec2
-from scipy.sparse import csr_matrix
 from ....mth.optimized import local_mapping, compute_distances
 from numba import c16, types, f8, i8, njit, prange
 

emerge/_emerge/physics/microwave/microwave_3d.py

@@ -262,6 +262,7 @@ class Microwave3D:
             logger.warning('A resolution greater than 0.33 may cause accuracy issues.')
         
         self.resolution = resolution
+        logger.trace(f'Resolution set to {self.resolution}')
 
     def set_conductivity_limit(self, condutivity: float) -> None:
         """Sets the limit of a material conductivity value beyond which
@@ -274,7 +275,9 @@ class Microwave3D:
         if condutivity < 0:
             raise ValueError('Conductivity values must be above 0. Ignoring assignment')
 
-        self.assembler.conductivity_limit = condutivity
+        self.assembler.settings.mw_2dbc_peclim = condutivity
+        self.assembler.settings.mw_3d_peclim = condutivity
+        logger.trace(f'Set conductivity limit to {condutivity} S/m')
     
     def get_discretizer(self) -> Callable:
         """Returns a discretizer function that defines the maximum mesh size.
@@ -295,7 +298,7 @@ class Microwave3D:
         if self.basis is not None:
             return
         if self.order == 1:
-            raise NotImplementedError('Nedelec 1 is temporarily not supported')
+            raise NotImplementedError('Nedelec 1 is currently not supported')
             from ...elements import Nedelec1
             self.basis = Nedelec1(self.mesh)
         elif self.order == 2:
@@ -310,6 +313,11 @@ class Microwave3D:
         for port in self.bc.oftype(LumpedPort):
             self.define_lumped_port_integration_points(port)
     
+    def _check_physics(self) -> None:
+        """ Executes a physics check before a simulation can be run."""
+        if not self.bc._is_excited():
+            raise SimulationError('The simulation has no boundary conditions that insert energy. Make sure to include at least one Port into your simulation.')
+    
     def define_lumped_port_integration_points(self, port: LumpedPort) -> None:
         """Sets the integration points on Lumped Port objects for voltage integration
 
@@ -319,7 +327,9 @@ class Microwave3D:
         Raises:
             SimulationError: An error if there are no nodes associated with the port.
         """
-        logger.debug('Finding Lumped Port integration points')
+        if len(port.vintline) > 0:
+            return
+        logger.debug(' - Finding Lumped Port integration points')
         field_axis = port.Vdirection.np
 
         points = self.mesh.get_nodes(port.tags)
@@ -344,7 +354,7 @@ class Microwave3D:
             start = np.array([x,y,z])
             end = start + port.Vdirection.np*port.height
             port.vintline.append(Line.from_points(start, end, 21))
-            logger.trace(f'Port[{port.port_number}] integration line {start} -> {end}.')
+            logger.trace(f' - Port[{port.port_number}] integration line {start} -> {end}.')
         
         port.v_integration = True
     
@@ -388,7 +398,7 @@ class Microwave3D:
         if self.basis is None:
             raise ValueError('The field basis is not yet defined.')
 
-        logger.debug('Finding PEC TEM conductors')
+        logger.debug(' - Finding PEC TEM conductors')
         pecs: list[PEC] = self.bc.get_conductors() # type: ignore
         mesh = self.mesh
 
@@ -415,10 +425,10 @@ class Microwave3D:
         
         pec_islands = mesh.find_edge_groups(pec_port)
 
-        logger.debug(f'Found {len(pec_islands)} PEC islands.')
+        logger.debug(f' - Found {len(pec_islands)} PEC islands.')
 
         if len(pec_islands) != 2:
-            raise ValueError(f'Found {len(pec_islands)} PEC islands. Expected 2.')
+            raise ValueError(f' - Found {len(pec_islands)} PEC islands. Expected 2.')
         
         groups = []
         for island in pec_islands:
@@ -475,6 +485,8 @@ class Microwave3D:
                 The desired frequency at which the mode is solved. If None then it uses the lowest frequency of the provided range.
         '''
         T0 = time.time()
+        logger.info(f'Starting Mode Analysis for port {port}.')
+        
         if self.bc._initialized is False:
             raise SimulationError('Cannot run a modal analysis because no boundary conditions have been assigned.')
         
@@ -484,7 +496,7 @@ class Microwave3D:
         if self.basis is None:
             raise SimulationError('Cannot proceed, the current basis class is undefined.')
 
-        logger.debug('Retreiving material properties.')
+        logger.debug(' - retreiving material properties.')
         
         if freq is None:
             freq = self.frequencies[0]
@@ -523,6 +535,8 @@ class Microwave3D:
 
         k0 = 2*np.pi*freq/299792458
         
+        logger.debug(f' - mean(max): εr = {ermean:.2f}({ermax:.2f}), μr = {urmean:.2f}({urmax:.2f})')
+        
         Amatrix, Bmatrix, solve_ids, nlf = self.assembler.assemble_bma_matrices(self.basis, er, ur, cond, k0, port, self.bc)
         
         logger.debug(f'Total of {Amatrix.shape[0]} Degrees of freedom.')
@@ -643,6 +657,7 @@ class Microwave3D:
         
         self._initialize_field()
         self._initialize_bc_data()
+        self._check_physics()
         
         if self.basis is None:
             raise SimulationError('Cannot proceed, the simulation basis class is undefined.')
@@ -664,8 +679,10 @@ class Microwave3D:
 
         logger.info(f'Pre-assembling matrices of {len(self.frequencies)} frequency points.')
 
-        # Thread-local storage for per-thread resources
-        thread_local = threading.local()
+        thread_local = None
+        if parallel:
+            # Thread-local storage for per-thread resources
+            thread_local = threading.local()
 
         ## DEFINE SOLVE FUNCTIONS
         def get_routine():
@@ -700,6 +717,7 @@ class Microwave3D:
         results: list[SimJob] = []
         matset: list[tuple[np.ndarray, np.ndarray, np.ndarray]] = []
         
+        logger.trace(f'Frequency groups: {freq_groups}')
         ## Single threaded
         job_id = 1
 
@@ -797,8 +815,8 @@ class Microwave3D:
                     # Distribute taks
                     group_results = pool.map(run_job_multi, jobs)
                     results.extend(group_results)
-
-        thread_local.__dict__.clear()
+        if parallel:
+            thread_local.__dict__.clear()
         logger.info('Solving complete')
 
         for freq, job in zip(self.frequencies, results):
@@ -807,7 +825,7 @@ class Microwave3D:
         for variables, data in self.data.sim.iterate():
             logger.trace(f'Sim variable: {variables}')
             for item in data['report']:
-                item.pretty_print(logger.trace)
+                item.logprint(logger.trace)
 
         self.solveroutine.reset()
         ### Compute S-parameters and return
@@ -914,8 +932,7 @@ class Microwave3D:
         mesh = self.mesh
         all_ports = self.bc.oftype(PortBC)
         port_numbers = [port.port_number for port in all_ports]
-        all_port_tets = self.mesh.get_face_tets(*[port.tags for port in all_ports])
-
+        
         logger.info('Computing S-parameters')
         
 
@@ -947,6 +964,8 @@ class Microwave3D:
 
             # Recording port information
             for active_port in all_ports:
+                port_tets = self.mesh.get_face_tets(active_port.tags)
+                
                 fielddata.add_port_properties(active_port.port_number,
                                          mode_number=active_port.mode_number,
                                          k0 = k0,
@@ -969,7 +988,7 @@ class Microwave3D:
                 fielddata.basis = self.basis
                 # Compute the S-parameters
                 # Define the field interpolation function
-                fieldf = self.basis.interpolate_Ef(solution, tetids=all_port_tets)
+                fieldf = self.basis.interpolate_Ef(solution, tetids=port_tets)
                 Pout = 0.0 + 0j
 
                 # Active port power
@@ -981,6 +1000,8 @@ class Microwave3D:
                 
                 #Passive ports
                 for bc in all_ports:
+                    port_tets = self.mesh.get_face_tets(bc.tags)
+                    fieldf = self.basis.interpolate_Ef(solution, tetids=port_tets)
                     tris = mesh.get_triangles(bc.tags)
                     tri_vertices = mesh.tris[:,tris]
                     pfield, pmode = self._compute_s_data(bc, fieldf,tri_vertices, k0, ertri[:,:,tris], urtri[:,:,tris])

emerge/_emerge/physics/microwave/microwave_bc.py

@@ -96,6 +96,15 @@ class MWBoundaryConditionSet(BoundaryConditionSet):
         self._cell._ports.append(port)
         return port
 
+    # Checks
+    def _is_excited(self) -> bool:
+        for bc in self.boundary_conditions:
+            if not isinstance(bc, RobinBC):
+                continue
+            if bc._include_force:
+                return True
+            
+        return False
 
 ############################################################
 #                    BOUNDARY CONDITIONS                   #
@@ -703,18 +712,20 @@ class RectangularWaveguide(PortBC):
         self.mode: tuple[int,int] = mode
 
         if dims is None:
-            logger.info("Determining port face based on selection")
+            logger.debug(f" - Establishing RectangularWaveguide port face based on selection {self.selection}")
             cs, (width, height) = self.selection.rect_basis() # type: ignore
             self.cs = cs # type: ignore
             self.dims = (width, height)
-            logger.debug(f'Port CS: {self.cs}')
-            logger.debug(f'Detected port {self.port_number} size = {width*1000:.1f} mm x {height*1000:.1f} mm')
+            logger.debug(f' - Port CS: {self.cs}')
+            logger.debug(f' - Detected port {self.port_number} size = {width*1000:.1f} mm x {height*1000:.1f} mm')
         else:
             self.dims = dims
             self.cs = cs
+            
         if self.cs is None:
-            logger.info('Constructing coordinate system from normal port')
+            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
         

emerge/_emerge/physics/microwave/microwave_data.py

@@ -20,7 +20,7 @@ from ...simulation_data import BaseDataset, DataContainer
 from ...elements.femdata import FEMBasis
 from dataclasses import dataclass
 import numpy as np
-from typing import Literal, Callable
+from typing import Literal
 from loguru import logger
 from .adaptive_freq import SparamModel
 from ...cs import Axis, _parse_axis
@@ -344,7 +344,7 @@ class FarFieldData:
         }
         mapping = fmap.get(quantity.lower(),np.abs)
         
-        F = mapping(self.__dict__.get(polarization, self.normE))
+        F = mapping(getattr(self, polarization))
         
         if isotropic:
             F = F/np.sqrt(Z0/(2*np.pi))
@@ -700,7 +700,7 @@ class MWField:
         ''' Return the magnetic field as a tuple of numpy arrays '''
         return self.Hx, self.Hy, self.Hz
     
-    def interpolate(self, xs: np.ndarray, ys: np.ndarray, zs: np.ndarray) -> EHField:
+    def interpolate(self, xs: np.ndarray, ys: np.ndarray, zs: np.ndarray, usenan: bool = True) -> EHField:
         ''' Interpolate the dataset in the provided xs, ys, zs values'''
         if isinstance(xs, (float, int, complex)):
             xs = np.array([xs,])
@@ -711,15 +711,16 @@ class MWField:
         xf = xs.flatten()
         yf = ys.flatten()
         zf = zs.flatten()
-        Ex, Ey, Ez = self.basis.interpolate(self._field, xf, yf, zf)
+        Ex, Ey, Ez = self.basis.interpolate(self._field, xf, yf, zf, usenan=usenan)
         self.Ex = Ex.reshape(shp)
         self.Ey = Ey.reshape(shp)
         self.Ez = Ez.reshape(shp)
 
         
         constants = 1/ (-1j*2*np.pi*self.freq*(self._dur*MU0) )
-        Hx, Hy, Hz = self.basis.interpolate_curl(self._field, xf, yf, zf, constants)
+        Hx, Hy, Hz = self.basis.interpolate_curl(self._field, xf, yf, zf, constants, usenan=usenan)
         ids = self.basis.interpolate_index(xf, yf, zf)
+        
         self.er = self._der[ids].reshape(shp)
         self.ur = self._dur[ids].reshape(shp)
         self.Hx = Hx.reshape(shp)
@@ -735,7 +736,8 @@ class MWField:
                      ds: float,
                      x: float | None = None,
                      y: float | None = None,
-                     z: float | None = None) -> EHField:
+                     z: float | None = None,
+                     usenan: bool = True) -> EHField:
         """Create a cartesian cut plane (XY, YZ or XZ) and compute the E and H-fields there
 
         Only one coordiante and thus cutplane may be defined. If multiple are defined only the last (x->y->z) is used.
@@ -763,12 +765,13 @@ class MWField:
         if z is not None:
             X,Y = np.meshgrid(xs, ys)
             Z = z*np.ones_like(Y)
-        return self.interpolate(X,Y,Z)
+        return self.interpolate(X,Y,Z, usenan=usenan)
     
     def cutplane_normal(self,
              point=(0,0,0),
              normal=(0,0,1),
-             npoints: int = 300) -> EHField:
+             npoints: int = 300,
+             usenan: bool = True) -> EHField:
         """
         Take a 2D slice of the field along an arbitrary plane.
         Args:
@@ -812,10 +815,10 @@ class MWField:
         Y = point[1] + S_mesh*u[1] + T_mesh*v[1]
         Z = point[2] + S_mesh*u[2] + T_mesh*v[2]
 
-        return self.interpolate(X, Y, Z)
+        return self.interpolate(X, Y, Z, usenan=usenan)
     
     
-    def grid(self, ds: float) -> EHField:
+    def grid(self, ds: float, usenan: bool = True) -> EHField:
         """Interpolate a uniform grid sampled at ds
 
         Args:
@@ -829,7 +832,7 @@ class MWField:
         ys = np.linspace(yb[0], yb[1], int((yb[1]-yb[0])/ds))
         zs = np.linspace(zb[0], zb[1], int((zb[1]-zb[0])/ds))
         X, Y, Z = np.meshgrid(xs, ys, zs)
-        return self.interpolate(X,Y,Z)
+        return self.interpolate(X,Y,Z, usenan=usenan)
     
     def vector(self, field: Literal['E','H'], metric: Literal['real','imag','complex'] = 'real') -> tuple[np.ndarray, np.ndarray,np.ndarray,np.ndarray,np.ndarray,np.ndarray]:
         """Returns the X,Y,Z,Fx,Fy,Fz data to be directly cast into plot functions.

emerge/_emerge/plot/pyvista/cmap_maker.py

@@ -0,0 +1,70 @@
+from typing import Iterable, Sequence, Optional
+import numpy as np
+from matplotlib.colors import LinearSegmentedColormap, to_rgba
+
+def make_colormap(
+    hex_colors: Sequence[str],
+    positions: Optional[Iterable[float]] = None,
+    name: str = "custom",
+    N: int = 256,
+) -> LinearSegmentedColormap:
+    """
+    Create a Matplotlib colormap from hex colors with optional positions.
+
+    Parameters
+    ----------
+    hex_colors : sequence of str
+        Hex color strings like '#RRGGBB' (or 'RRGGBB'). At least 2 required.
+    positions : iterable of float in [0, 1], optional
+        Locations of each color along the gradient. If not provided,
+        they are evenly spaced via linspace(0, 1, len(hex_colors)).
+        If provided, they do not have to be sorted; they will be sorted
+        together with the colors. If the first/last position do not
+        hit 0 or 1, they’ll be extended by duplicating the end colors.
+    name : str
+        Name for the colormap.
+    N : int
+        Resolution (number of lookup entries) of the colormap.
+
+    Returns
+    -------
+    matplotlib.colors.LinearSegmentedColormap
+    """
+    # Normalize hex strings and basic validation
+    colors = []
+    for c in hex_colors:
+        if not isinstance(c, str):
+            raise TypeError("All colors must be hex strings.")
+        colors.append(c if c.startswith("#") else f"#{c}")
+
+    if len(colors) < 2:
+        raise ValueError("Provide at least two hex colors.")
+
+    # Build/validate positions
+    if positions is None:
+        pos = np.linspace(0.0, 1.0, len(colors), dtype=float)
+    else:
+        pos = np.asarray(list(positions), dtype=float)
+        if pos.size != len(colors):
+            raise ValueError("`positions` must have the same length as `hex_colors`.")
+        if np.any((pos < 0.0) | (pos > 1.0)):
+            raise ValueError("All positions must be within [0, 1].")
+
+        # Sort positions and carry colors along
+        order = np.argsort(pos)
+        pos = pos[order]
+        colors = [colors[i] for i in order]
+
+        # Ensure coverage of [0, 1] by extending ends if needed
+        if pos[0] > 0.0:
+            pos = np.r_[0.0, pos]
+            colors = [colors[0]] + colors
+        if pos[-1] < 1.0:
+            pos = np.r_[pos, 1.0]
+            colors = colors + [colors[-1]]
+
+    # Pair positions with RGBA
+    segment = list(zip(pos.tolist(), (to_rgba(c) for c in colors)))
+
+    # Create the colormap
+    return LinearSegmentedColormap.from_list(name, segment, N=N)