Geometry

This page lists the geometry types you use to place materials in a Scene. You need it whenever you add a Structure, a MaterialRegion, or a MeshOverrideStructure.

Most classes here come from the shared base package witwin.core (PyPI witwin 0.4.x, which witwin-maxwell 0.5.1 requires) and are re-exported by witwin.maxwell: Box, Sphere, Cylinder, Ellipsoid, Cone, Pyramid, Prism, Torus, HollowBox, Mesh and Structure. mw.Box and witwin.core.Box are the same class. PolySlab and ComplexPolySlab are Maxwell's own and live in witwin.maxwell.geometry.

import witwin.maxwell as mw
 
scene.add_structure(
    mw.Structure(
        geometry=mw.Box(position=(0.0, 0.0, 0.0), size=(0.24, 0.24, 0.24)),
        material=mw.Material(eps_r=4.0),
        name="dielectric_box",
    )
)

Common conventions#

These rules hold for every geometry on this page.

• Units. All lengths are in metres.
• Storage. Lengths, positions and rotations are stored as float32 torch.Tensor values. You can pass plain numbers or tensors. A tensor with requires_grad=True stays in the autograd graph, so you can optimize shape parameters. See Differentiability.
• position. A length-3 value. For most shapes it is the centre. Cone and Pyramid put their apex there.
• rotation. None (no rotation), three Euler angles (roll, pitch, yaw) in radians, or a quaternion (w, x, y, z). A tensor of shape (3,) or (4,) is kept as is.
• axis. "x", "y" or "z", for shapes that have one. Other values raise ValueError.
• device. Keyword-only. Places the parameter tensors on that device. Tensor arguments must agree with it, or the constructor raises ValueError.
• Rasterization. Maxwell's material compiler samples each geometry on the Yee grid through to_mask, which is built on signed_distance.

Shared geometry methods#

Every geometry class below has these members.

signed_distance#

geometry.signed_distance(xx, yy, zz) -> torch.Tensor

Signed distance in metres from each query point to the surface: negative inside, positive outside. xx, yy, zz are coordinate tensors of the same shape, for example from torch.meshgrid(..., indexing="ij").

to_mask#

geometry.to_mask(xx, yy, zz, offset=0.0, beta=None) -> torch.Tensor

A smooth occupancy in the range 0 to 1: 0.5 * (1 - tanh((d - offset) / beta)) where d is the signed distance. offset grows (negative) or shrinks (positive) the shape, in metres. beta is the transition width in metres; None uses 5% of the smallest coordinate spacing found in the inputs.

to_mesh#

geometry.to_mesh(segments=16) -> tuple[torch.Tensor, torch.Tensor]

A triangle mesh (vertices, faces) in world coordinates: vertices of shape (N, 3) and int64 faces of shape (M, 3). segments sets the tessellation of curved shapes and is ignored by flat-faced ones.

kind and device#

kind is a class-level string such as "box" or "poly_slab". device is a property that returns the device of position.

Box#

class Box(position=(0, 0, 0), size=(1, 1, 1), rotation=None, *, device=None)

A rectangular box centred at position.

slab = mw.Box(position=(0.0, 0.0, 0.0), size=(0.52, 1.28, 0.12))

Sphere#

class Sphere(position=(0, 0, 0), radius=1.0, rotation=None, *, device=None)

A sphere centred at position. rotation is stored but has no effect on the shape.

Cylinder#

class Cylinder(position=(0, 0, 0), radius=1.0, height=1.0, axis="z", rotation=None, *, device=None)

A circular cylinder centred at position, with its axis along axis before rotation.

rod = mw.Cylinder(position=(0.0, 0.0, 0.0), radius=0.05, height=0.4, axis="x")

Ellipsoid#

class Ellipsoid(position=(0, 0, 0), radii=(1, 1, 1), rotation=None, *, device=None)

An ellipsoid centred at position.

Cone#

class Cone(position=(0, 0, 0), radius=1.0, height=1.0, axis="z", rotation=None, *, device=None)

A solid circular cone. The apex is at position, and the cone opens along the positive axis direction to a flat base at distance height.

Pyramid#

class Pyramid(position=(0, 0, 0), base_size=1.0, height=1.0, axis="z", rotation=None, *, device=None)

A pyramid with a square base. The apex is at position, and the base lies at distance height along the positive axis direction.

Prism#

class Prism(position=(0, 0, 0), radius=1.0, height=1.0, num_sides=6, axis="z", rotation=None, *, device=None)

A right prism with a regular polygon cross-section, centred at position.

Torus#

class Torus(position=(0, 0, 0), major_radius=1.0, minor_radius=0.25, axis="z", rotation=None, *, device=None)

A torus centred at position, with its symmetry axis along axis.

ring = mw.Torus(position=(0.0, 0.0, 0.0), major_radius=1.0, minor_radius=0.3)

HollowBox#

class HollowBox(position=(0, 0, 0), outer_size=(1, 1, 1), inner_size=(0.8, 0.8, 0.8), rotation=None, *, device=None)

A box with a box-shaped cavity, both centred at position. The shape is the outer box minus the inner box.

HollowBox.size is a property that returns outer_size as a tuple of floats.

shell = mw.HollowBox(position=(0.0, 0.0, 0.0), outer_size=(0.6, 0.6, 0.6), inner_size=(0.4, 0.4, 0.4))

Mesh#

class Mesh(
    vertices, faces, *,
    position=(0.0, 0.0, 0.0), scale=1.0, rotation=None, recenter=True,
    fill_mode="auto", surface_thickness=None, source_path=None,
    topology_diagnostics=None, device=None,
)

An explicit triangle mesh. World vertices are (local * scale) @ R.T + position, where local is the authored vertices (recentred when recenter=True) and R is the rotation matrix.

Raises: ValueError for wrong shapes, out-of-range indices, an unknown fill_mode or a non-positive surface_thickness; TypeError for wrong dtypes. At query time, signed_distance raises RuntimeError when fill_mode="auto" and no diagnostics were computed, or when the vertex or face tensors were changed in place after diagnostics ran.

import torch
 
vertices = torch.tensor([[0.0, 0.0, 0.0], [0.1, 0.0, 0.0], [0.0, 0.1, 0.0], [0.0, 0.0, 0.1]])
faces = torch.tensor([[0, 2, 1], [0, 1, 3], [0, 3, 2], [1, 2, 3]])
tetra = mw.Mesh(vertices, faces, fill_mode="solid")

Mesh.from_obj#

Mesh.from_obj(
    path, *, position=(0.0, 0.0, 0.0), scale=1.0, rotation=None, recenter=True,
    fill_mode="auto", surface_thickness=None, device=None,
) -> Mesh

Loads a Wavefront OBJ file. Polygon faces are triangulated, source_path is set to path, and topology diagnostics always run.

Raises: FileNotFoundError for a missing file; ValueError for malformed records or a file without vertices or triangles.

mesh = mw.Mesh.from_obj("cube.obj", position=(1.0, 2.0, 3.0), scale=2.0)
print(mesh.vertex_count, mesh.face_count, mesh.is_watertight)

Mesh properties#

Mesh methods#

PolySlab#

class PolySlab(
    vertices, bounds, axis="z", sidewall_angle=0.0, reference_plane="middle",
    position=(0, 0, 0), rotation=None, *, device=None,
)

A 2D polygon extruded along an axis, with an optional linear sidewall taper. Defined in witwin.maxwell.geometry. The inside test uses the even-odd rule, so non-convex polygons work and vertex winding does not matter.

Raises: ValueError for vertices not shaped (N, 2) with N of 3 or more, bounds without two values, an integer axis outside 0 to 2, or an unknown reference_plane. to_mesh raises ValueError when the polygon is not simple enough to triangulate.

UM = 1e-6
waveguide = mw.PolySlab(
    vertices=[(0.0, 0.0), (2.0 * UM, 0.0), (2.0 * UM, 0.5 * UM), (0.0, 0.5 * UM)],
    bounds=(0.0, 0.22 * UM),
    sidewall_angle=0.1,
)

ComplexPolySlab#

class ComplexPolySlab(
    loops, bounds, axis="z", sidewall_angle=0.0, reference_plane="middle",
    position=(0, 0, 0), rotation=None, *, device=None,
)

A PolySlab whose cross-section is built from several vertex loops. Self-intersecting loops (such as a bowtie) and multiple loops are allowed. The inside test is the even-odd rule over all loops together, so an inner loop carves a hole. Defined in witwin.maxwell.geometry.

The other parameters match PolySlab. loop_sizes holds the vertex count of each loop.

Raises: ValueError for an empty loops list or a malformed loop. to_mesh raises NotImplementedError, so a ComplexPolySlab cannot be exported as a mesh.

UM = 1e-6
outer = [(0.0, 0.0), (2.0 * UM, 0.0), (2.0 * UM, 1.0 * UM), (0.0, 1.0 * UM)]
hole = [(0.5 * UM, 0.25 * UM), (1.5 * UM, 0.25 * UM), (1.5 * UM, 0.75 * UM), (0.5 * UM, 0.75 * UM)]
holed = mw.ComplexPolySlab(loops=[outer, hole], bounds=(0.0, 0.22 * UM))

Structure#

class Structure(
    geometry, material, name=None, priority=0, enabled=True, tags=(), metadata=None, *,
    structure_id=None, material_id=None, assignment_id=None, surface_id=None,
    primitive_ids=(), phase_screen=None, uv=None, face_uv=None,
)

Binds one geometry to one material. Immutable. Re-exported from witwin.core; add it to a scene with Scene.add_structure.

The keyword-only arguments belong to the shared witwin.core scene contract:

Maxwell's solver does not read phase_screen, uv or face_uv.

Raises: TypeError for an unsupported geometry, material, phase screen or UV dtype; ValueError for mismatched UV shapes or devices.

Structure.primitive_id#

Structure.primitive_id(local_index) -> PrimitiveId

Returns the identity of primitive local_index. With primitive_ids set it indexes that tuple; otherwise it combines structure_id and the index. Raises ValueError for a negative index or one that does not fit in 32 bits, and IndexError when the index is outside primitive_ids.

structure = mw.Structure(
    geometry=mw.Box(position=(0.0, 0.0, 0.0), size=(1.0, 1.0, 1.0)),
    material=mw.Material(eps_r=3.0, sigma_e=0.25),
    name="target",
    priority=7,
)