simgeometry 0.1.0__py3-none-any.whl

simgeometry/__init__.py

@@ -0,0 +1,38 @@
+"""Shapes, grids, and domains for numerical simulations."""
+
+from simgeometry.collection import GeometryCollection
+from simgeometry.grid import Grid
+from simgeometry.objects import (
+    Aperture2D,
+    Aperture3D,
+    Circle,
+    Cuboid,
+    FunctionObject2D,
+    FunctionObject3D,
+    Line,
+    Polygon,
+    Polyline,
+    Rectangle,
+    Sphere,
+    Triangle,
+)
+from simgeometry.simulation_domain import SimulationDomain
+
+__version__ = "0.1.0"
+__all__ = [
+    "GeometryCollection",
+    "Grid",
+    "SimulationDomain",
+    "Aperture2D",
+    "Aperture3D",
+    "Circle",
+    "Cuboid",
+    "FunctionObject2D",
+    "FunctionObject3D",
+    "Line",
+    "Polygon",
+    "Polyline",
+    "Rectangle",
+    "Sphere",
+    "Triangle",
+]

simgeometry/_bounds.py

@@ -0,0 +1,16 @@
+"""Array bounds shared by geometric regions and grids."""
+
+from __future__ import annotations
+
+
+class Bounds:
+    def __init__(self, lower_bound, upper_bound) -> None:
+        assert len(lower_bound) == len(upper_bound)
+        self.lower_bound = lower_bound
+        self.upper_bound = upper_bound
+        self.ndim = len(lower_bound)
+        assert self.ndim in (1, 2, 3)
+        for axis in range(self.ndim):
+            assert upper_bound[axis] >= lower_bound[axis]
+        self.sidelengths = upper_bound - lower_bound
+        self.midpoint = lower_bound + 0.5 * self.sidelengths

simgeometry/_normalize.py

@@ -0,0 +1,23 @@
+"""Normalize scalar and sequence geometry arguments."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+def ensure_dim_tuple(value: object, *, ndim: int | None = None) -> tuple:
+    if isinstance(value, tuple):
+        normalized = value
+    elif isinstance(value, list):
+        normalized = tuple(value)
+    elif isinstance(value, (str, bytes, dict)):
+        raise TypeError(
+            f"value must be a scalar number/bool or sequence, got {type(value)}"
+        )
+    elif isinstance(value, Iterable):
+        normalized = tuple(value)
+    else:
+        normalized = (value,)
+    if ndim is not None and len(normalized) != ndim:
+        raise ValueError(f"value must have length {ndim}, got {len(normalized)}")
+    return normalized

simgeometry/_particle_boundaries.py

@@ -0,0 +1,37 @@
+"""Apply particle boundary conditions on the active array backend."""
+
+from __future__ import annotations
+
+import cunumpy as xp
+
+
+def apply_particle_boundaries(
+    positions, velocities, alive, reinject, lower, upper, lower_type, upper_type
+) -> None:
+    """Update component-major particle arrays in place.
+
+    Boundary codes are kill=0, reflect=1, periodic=2, reinject=3.
+    """
+    reinject[:] = False
+    in_domain = alive.copy()
+    for axis in range(positions.shape[0]):
+        active = alive & ~reinject
+        x = positions[axis]
+        low, high = lower[axis], upper[axis]
+        below = active & (x < low)
+        above = active & ((x >= high) if upper_type[axis] == 2 else (x > high))
+        for mask, bound, side_type in (
+            (below, low, lower_type[axis]),
+            (above, high, upper_type[axis]),
+        ):
+            if side_type == 1:
+                x[mask] = 2.0 * bound - x[mask]
+                velocities[axis, mask] *= -1.0
+            elif side_type == 2:
+                wrapped = low + (x[mask] - low) % (high - low)
+                x[mask] = xp.where(wrapped >= high, low, wrapped)
+            elif side_type == 3:
+                reinject |= mask
+        checked = alive & ~reinject
+        in_domain &= ~checked | ((x >= low) & (x < high))
+    alive &= in_domain

simgeometry/_types.py

@@ -0,0 +1,22 @@
+"""Types used by geometry without importing simulation utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TypeAlias
+
+from numpy import ndarray
+
+Array: TypeAlias = ndarray
+Scalar: TypeAlias = str | int | float | bool | None
+ConfigValue: TypeAlias = (
+    Scalar
+    | Array
+    | list["ConfigValue"]
+    | tuple["ConfigValue", ...]
+    | set["ConfigValue"]
+    | dict[str, "ConfigValue"]
+)
+Printable: TypeAlias = str | int | float | bool | None
+BoundsLike: TypeAlias = Sequence[int | float] | ndarray
+Vertices2DLike: TypeAlias = Sequence[BoundsLike] | ndarray

simgeometry/api.py

@@ -0,0 +1,247 @@
+"""Shared inspection and construction methods for geometry objects.
+
+Array queries use component-major coordinates, ``(ndim, n)``. Inspection,
+meshing and labelled evaluation return host arrays; containment retains the
+selected cunumpy backend. Optional dependencies are imported on demand.
+"""
+
+from __future__ import annotations
+
+import copy
+
+
+class GeometryAPI:
+    """Convenience operations shared by shapes, sections and collections."""
+
+    def evaluate(
+        self,
+        x=None,
+        y=None,
+        z=None,
+        *,
+        grid=None,
+        bounds=None,
+        resolution=128,
+        quantity="occupancy",
+    ):
+        """Sample geometry as an xarray.DataArray (requires the ``evaluate`` extra).
+
+        Scalars fix axes, sequences form a tensor product, and DataArrays with
+        shared dimension names describe scattered points. Unspecified axes use
+        grid nodes, or ``resolution`` samples across ``bounds``/the shape bounds.
+        ``quantity`` is occupancy, labels (collections), or signed_distance.
+        This is a local host operation, with no implicit MPI collectives.
+        """
+        from simgeometry.evaluation import evaluate
+
+        return evaluate(
+            self,
+            x=x,
+            y=y,
+            z=z,
+            grid=grid,
+            bounds=bounds,
+            resolution=resolution,
+            quantity=quantity,
+        )
+
+    def slice(self, *, x=None, y=None, z=None, origin=None, normal=None):
+        """Return a queryable section with local-to-world coordinate mappings.
+
+        Fix exactly one coordinate, or give a 3D plane's origin and normal.
+        Axis-aligned sections retain the remaining coordinate names; oblique
+        sections use x/y as their local plane coordinates.
+        """
+        from simgeometry.operations import Section
+
+        return Section(self, x=x, y=y, z=z, origin=origin, normal=normal)
+
+    def show(self, **kwargs):
+        """Display geometry, dispatching to 3D unless a slice is requested.
+
+        Returns Matplotlib axes, or a PyVista plotter for ``backend='pyvista'``.
+        Set ``display=False`` for scripts. ``save=path`` saves the figure.
+        """
+        from simgeometry.visualization import show
+
+        return show(self, **kwargs)
+
+    def show_3d(self, **kwargs):
+        """Display a surface with optional wireframe, normals and clipping.
+
+        ``backend='pyvista'`` enables an interactive clipping-plane widget via
+        ``clip=True`` (requires the ``interactive`` extra). Matplotlib supports
+        a static ``clip=(origin, normal)`` plane. Meshes are resolution-dependent.
+        """
+        from simgeometry.visualization import show_3d
+
+        return show_3d(self, **kwargs)
+
+    def plot(self, ax=None, **kwargs):
+        """Draw without displaying and return axes for composition."""
+        return self.show(ax=ax, display=False, **kwargs)
+
+    def copy(self):
+        """Return an independent deep copy."""
+        return copy.deepcopy(self)
+
+    def transformed(self, matrix, offset=None):
+        """Return an affine-transformed snapshot; the source is unchanged."""
+        from simgeometry.operations import TransformedShape
+
+        return TransformedShape(self, matrix, offset)
+
+    def translated(self, offset):
+        """Return a translated snapshot (unlike legacy in-place translate)."""
+        import numpy as np
+
+        return self.transformed(np.eye(self.ndim), offset)
+
+    def rotated(self, angle, *, axis=(0, 0, 1), origin=None):
+        """Return a rotated snapshot; angle is in degrees, about origin (default 0)."""
+        from simgeometry.operations import rotation
+
+        return rotation(self, angle, axis=axis, origin=origin)
+
+    def scaled(self, factors, *, origin=None):
+        """Return a snapshot scaled by a nonzero scalar or per-axis factors."""
+        import numpy as np
+
+        factors = np.broadcast_to(factors, (self.ndim,)).astype(float)
+        centre = np.zeros(self.ndim) if origin is None else np.asarray(origin, float)
+        return self.transformed(np.diag(factors), centre * (1 - factors))
+
+    def union(self, other):
+        from simgeometry.operations import BooleanShape
+
+        return BooleanShape(self, other, "union")
+
+    def intersection(self, other):
+        from simgeometry.operations import BooleanShape
+
+        return BooleanShape(self, other, "intersection")
+
+    def difference(self, other):
+        from simgeometry.operations import BooleanShape
+
+        return BooleanShape(self, other, "difference")
+
+    def __or__(self, other):
+        return self.union(other)
+
+    def __and__(self, other):
+        return self.intersection(other)
+
+    def __sub__(self, other):
+        return self.difference(other)
+
+    def intersect_segment(self, start, end, *, samples=256, tolerance=1e-10):
+        """Return ordered surface hits, including multiple crossings and tangencies.
+
+        Primitive intersections are analytic. Generic membership functions use
+        ``samples`` intervals and may miss features smaller than that sampling.
+        Result.exact distinguishes these cases. Coincident surface segments do
+        not have a discrete set of hits; their end contacts may be returned.
+        """
+        from simgeometry.queries import intersect_segment
+
+        return intersect_segment(self, start, end, samples=samples, tolerance=tolerance)
+
+    def crossings(self, start, end, *, samples=64, iterations=40):
+        """First boundary crossing of every segment ``start[:, i] -> end[:, i]``.
+
+        ``start`` and ``end`` are ``(ndim, N)``, such as particle positions before and
+        after a step. Returns a :class:`~simgeometry.crossings.Crossings` with ``hit``,
+        ``fraction``, ``point`` and ``normal`` (out of the region where ``contains`` is
+        true) on the active array backend. Polygons, circles, spheres, boxes and their
+        affine transforms are analytic; other shapes sample ``samples`` points per
+        segment and bisect ``iterations`` times.
+        """
+        from simgeometry.crossings import crossings
+
+        return crossings(self, start, end, samples=samples, iterations=iterations)
+
+    def closest_point(self, points, *, resolution=64, bounds=None):
+        """Closest surface coordinates; primitives are exact, others use a mesh.
+
+        Mesh fallback requires ``mesh`` extras. Its accuracy is controlled by
+        resolution and may miss unresolved components. Points are (ndim, n),
+        or one (ndim,) point; the returned array has the same layout.
+        """
+        from simgeometry.queries import closest_point
+
+        return closest_point(self, points, resolution=resolution, bounds=bounds)
+
+    def signed_distance(self, points, *, resolution=64, bounds=None):
+        """Distance to the boundary, negative inside, positive outside.
+
+        Exact for balls, boxes and simple polygons; otherwise distance to the
+        sampled surface mesh. A membership function is not itself a distance.
+        """
+        from simgeometry.queries import signed_distance
+
+        return signed_distance(self, points, resolution=resolution, bounds=bounds)
+
+    def surface_normal(self, points, *, scale=None):
+        """Outward unit normals at boundary points; NaN where undefined.
+
+        Primitive faces use analytic normals. Other geometries estimate the
+        normal from nearby membership samples. At corners normals are not unique.
+        """
+        from simgeometry.queries import surface_normal
+
+        return surface_normal(self, points, scale=scale)
+
+    def to_mesh(self, *, resolution=64, bounds=None):
+        """Return sampled contours (2D) or triangles (3D), with spacing metadata.
+
+        Requires the ``mesh`` extra. Open contours/surfaces at the sampling bounds
+        remain open; no artificial caps are added. Refine to resolve thin features.
+        """
+        from simgeometry.mesh import to_mesh
+
+        return to_mesh(self, resolution=resolution, bounds=bounds)
+
+    def export(self, path, **kwargs):
+        """Export a sampled mesh as NPZ, OBJ, or STL (3D only)."""
+        return self.to_mesh(**kwargs).save(path)
+
+    def sample_interior(self, count, *, rng=None, bounds=None, max_draws=1_000_000):
+        """Uniform rejection samples, returned as (ndim, count).
+
+        Supply bounds for inverted/unbounded shapes. Raises if max_draws is
+        exhausted; it never silently returns too few samples.
+        """
+        from simgeometry.sampling import sample_interior
+
+        return sample_interior(self, count, rng=rng, bounds=bounds, max_draws=max_draws)
+
+    def sample_surface(self, count, *, rng=None, resolution=64, bounds=None):
+        """Uniform-by-length/area samples from the faceted boundary mesh."""
+        from simgeometry.sampling import sample_surface
+
+        return sample_surface(
+            self, count, rng=rng, resolution=resolution, bounds=bounds
+        )
+
+    def cut_edges(self, grid, **kwargs):
+        """Locate all detected grid-edge surface hits, without solver clamping."""
+        from simgeometry.cut_edges import cut_edges
+
+        return cut_edges(self, grid, **kwargs)
+
+    def diagnose(self, grid, **kwargs):
+        """Report sampled overlaps, unresolved components, and short cut distances."""
+        from simgeometry.cut_edges import diagnose
+
+        return diagnose(self, grid, **kwargs)
+
+    def cell_fractions(self, grid, *, samples_per_axis=4):
+        """Estimate solid cell-volume and face-area fractions by subcell sampling.
+
+        Increase samples_per_axis to check convergence; unresolved thin features
+        can be missed. This is not an exact finite-volume interface reconstruction.
+        """
+        from simgeometry.fractions import cell_fractions
+
+        return cell_fractions(self, grid, samples_per_axis=samples_per_axis)

simgeometry/boundingbox.py

@@ -0,0 +1,231 @@
+"""Boundingbox helpers for geometry, grids, and simulation domains."""
+
+from __future__ import annotations
+
+import cunumpy as xp
+from maybempi import MPI
+
+from simgeometry._bounds import Bounds
+from simgeometry._normalize import ensure_dim_tuple
+from simgeometry._types import Array, ConfigValue
+from simgeometry.domain_decomposition import DomainDecomposition
+
+
+class BoundingBox:
+    """Represent axis-aligned bounds for a simulation region."""
+
+    # Applications may supply their own seeded stream. The default follows
+    # the active cunumpy backend and works without any Picnic configuration.
+    random = staticmethod(xp.random.random)
+
+    def __init__(
+        self,
+        lower_bound: tuple,
+        upper_bound: tuple,
+        comm: MPI.Comm | None = None,
+        domain_decomposition: ConfigValue = None,
+        periodic: bool | None = None,
+    ) -> None:
+        """
+        Initialize the simulation domain.
+
+        Parameters:
+        ndim (int): Number of dimensions (e.g., 1, 2, or 3).
+        bounds (list of tuples): List of tuples specifying min and max for each dimension.
+                                For example, [(x_min, y_min, z_min), (y_max, y_max, z_max)] for 3D.
+        """
+
+        lower_bound = ensure_dim_tuple(lower_bound)
+        upper_bound = ensure_dim_tuple(upper_bound)
+        if len(lower_bound) != len(upper_bound):
+            raise ValueError(
+                "lower_bound and upper_bound must have the same length, "
+                f"got {len(lower_bound)} and {len(upper_bound)}",
+            )
+        ndim = len(lower_bound)
+        if ndim not in [1, 2, 3]:
+            raise ValueError("Number of dimensions must be 1, 2, or 3")
+        if domain_decomposition is not None:
+            domain_decomposition = ensure_dim_tuple(
+                domain_decomposition,
+                ndim=ndim,
+            )
+        if periodic is not None:
+            periodic = ensure_dim_tuple(periodic, ndim=ndim)
+        for dir in range(ndim):
+            if upper_bound[dir] < lower_bound[dir]:
+                raise ValueError("upper bound must be >= lower bound in each dimension")
+        # Set attributes
+        self._bounds = Bounds(
+            lower_bound=xp.array(lower_bound, dtype=float),
+            upper_bound=xp.array(upper_bound, dtype=float),
+        )
+
+        self._lower_bound = lower_bound
+        self._upper_bound = upper_bound
+        self._comm = comm
+
+        if isinstance(comm, MPI.Comm):
+            self._mpi_rank = comm.Get_rank()
+            self._mpi_size = comm.Get_size()
+        else:
+            self._mpi_rank = 0
+            self._mpi_size = 1
+
+        self._periodic = periodic
+        self._domain_decomposition = DomainDecomposition(
+            comm=comm,
+            decompose=domain_decomposition,
+            periodic=periodic,
+            ndim=self.ndim,
+        )
+        self._proc_sizes = self.domain_decomposition_class.proc_sizes
+
+        # TODO: Use a tuple here instead
+        self._sidelengths = tuple(
+            upper_bound[dir] - lower_bound[dir] for dir in range(ndim)
+        )
+
+    def contains(self, coords: tuple) -> bool:
+        """
+        Check if the given coordinates are inside the domain.
+
+        Parameters:
+        coords (float): Coordinates for each dimension.
+
+        Returns:
+        bool: True if all coordinates are within the domain bounds, False otherwise.
+        """
+
+        assert len(coords) == self.ndim, (
+            f"Expected {self.ndim} dimensions, got {len(coords)}."
+        )
+
+        return all(
+            self.lower_bound[i] <= coord < self.upper_bound[i]
+            for i, coord in enumerate(coords)
+        )
+
+    def get_relative_position(self, coords: Array) -> Array:
+        """
+        Determine the relative position of the given coordinates with respect to the domain bounds.
+
+        Parameters:
+            coords (float): Coordinates for each dimension.
+
+        Returns:
+            list: A list representing the relative position.
+                [0, 0] if inside,
+                [-1, 0] if to the left,
+                [1, 0] if to the right,
+                [0, -1] if below,
+                [0, 1] if above,
+                etc.
+        """
+        assert len(coords) == self.ndim, (
+            f"Expected {self.ndim} dimensions, got {len(coords)}."
+        )
+
+        position = [0] * self.ndim
+
+        for i, coord in enumerate(coords):
+            if coord < self.lower_bound[i]:
+                position[i] = -1
+            elif coord >= self.upper_bound[i]:
+                position[i] = 1
+            else:
+                position[i] = 0
+
+        return position
+
+    def draw_random_position(self) -> Array:
+        """Draw one random position inside the bounding box."""
+        pos = self.random(self.ndim)
+        for i, (b0, b1) in enumerate(zip(self.lower_bound, self.upper_bound)):
+            pos[i] = b0 + pos[i] * (b1 - b0)
+        return pos
+
+    def draw_random_positions(self, num_positions: int, out: Array = None) -> Array:
+        """Draw `num_positions` random positions inside the bounding box.
+
+        The result has shape ``(ndim, num_positions)``; ``out`` must have it.
+        """
+        shape = (self.ndim, num_positions)
+        if out is None:
+            out = self.random(shape)
+            ret = True
+        else:
+            assert out.shape == shape, (
+                f"Expected out with shape {shape}, got {out.shape}"
+            )
+            out[:] = self.random(shape)
+            ret = False
+
+        for dir in range(self.ndim):
+            out[dir] = out[dir] * self.bounds.sidelengths[dir] + self.lower_bound[dir]
+
+        if ret:
+            return out
+
+    @property
+    def ndim(self) -> int:
+        """Return the number of spatial dimensions."""
+        return self._bounds.ndim
+
+    @property
+    def bounds(self) -> Bounds:
+        """Return the lower and upper bounds."""
+        return self._bounds
+
+    @property
+    def lower_bound(self) -> tuple:
+        """Return the lower coordinate bounds."""
+        return self._lower_bound
+
+    @property
+    def upper_bound(self) -> tuple:
+        """Return the upper coordinate bounds."""
+        return self._upper_bound
+
+    @property
+    def comm(self) -> MPI.Comm | None:
+        """Return the MPI communicator."""
+        return self._comm
+
+    @property
+    def mpi_rank(self) -> int:
+        """Return the MPI rank."""
+        return self._mpi_rank
+
+    @property
+    def mpi_size(self) -> int:
+        """Return the MPI size."""
+        return self._mpi_size
+
+    @property
+    def domain_decomposition_class(self) -> ConfigValue:
+        """Return the domain decomposition class."""
+        return self._domain_decomposition
+
+    @property
+    def periodic(self) -> tuple[bool, ...]:
+        """Return periodicity flags for each axis."""
+        return self._periodic
+
+    @property
+    def proc_sizes(self) -> list[int]:
+        """Return process counts along each axis."""
+        return self._proc_sizes
+
+    @property
+    def midpoint(self) -> tuple[float, ...]:
+        """Return the center point of the bounding box."""
+        return tuple(
+            0.5 * (self.lower_bound[dir] + self.upper_bound[dir])
+            for dir in range(self.ndim)
+        )
+
+    @property
+    def sidelengths(self) -> tuple[float, ...]:
+        """Return the side lengths."""
+        return self._sidelengths

simgeometry/collection.py

@@ -0,0 +1,65 @@
+"""Named collections with explicit overlap precedence and display styles."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import cunumpy as xp
+import numpy as np
+
+from simgeometry.operations import mask
+from simgeometry.shapes import Shape, _component_major
+
+
+class GeometryCollection(Shape):
+    """Named objects; last listed object wins labels in overlaps.
+
+    Label 0 is background, labels 1..N follow insertion order. Styles map object
+    names to plotting keyword dictionaries. Explicit bounds also permit an empty
+    collection and define the default viewing/sampling region, without clipping
+    object membership. Collection objects are references, not snapshots.
+    """
+
+    def __init__(self, objects, *, bounds=None, styles=None):
+        if not isinstance(objects, Mapping):
+            objects = {f"object_{i + 1}": obj for i, obj in enumerate(objects)}
+        self.named_objects = dict(objects)
+        if any(not isinstance(name, str) or not name for name in self.named_objects):
+            raise ValueError("Object names must be nonempty strings")
+        self.names = tuple(self.named_objects)
+        self.objects = list(self.named_objects.values())
+        self.styles = dict(styles or {})
+        if set(self.styles) - set(self.names):
+            raise ValueError("Style names must identify objects")
+        if bounds is None:
+            if not self.objects:
+                raise ValueError("An empty collection needs bounds")
+            bounds = (
+                np.min([s.lower_bound for s in self.objects], axis=0),
+                np.max([s.upper_bound for s in self.objects], axis=0),
+            )
+        ndim = len(bounds[0])
+        if any(obj.ndim != ndim for obj in self.objects):
+            raise ValueError("All collection objects must have the same dimension")
+        self._inverted = any(obj.inverted for obj in self.objects)
+        super().__init__(ndim, *bounds)
+
+    def __getitem__(self, name):
+        return self.named_objects[name]
+
+    def labels(self, points):
+        """Integer object identities for (ndim, n) points; last object wins."""
+        points = np.asarray(xp.to_numpy(_component_major(points, self.ndim)), float)
+        result = np.zeros(points.shape[1], dtype=np.int64)
+        for label, obj in enumerate(self.objects, start=1):
+            result[mask(obj, points)] = label
+        return result
+
+    def contains_points(self, points):
+        return xp.asarray(self.labels(points) != 0)
+
+    def contains(self, coords):
+        return any(obj.contains(coords) for obj in self.objects)
+
+    def evaluate(self, *args, quantity="labels", **kwargs):
+        return super().evaluate(*args, quantity=quantity, **kwargs)