Set Builders

Previous Next

Reference

Implementation-agnostic set builders.

This module defines a tiny DSL of lazy "set builders" that describe sets and set operations without committing to a concrete representation. A SetBuilder is realized by an Impl[R] (see pyspect.impls.*), which interprets operations (e.g., empty, complement, intersect, halfspace).

Key ideas
  • Builders are composable and track requirements on the target Impl.
  • Builders can carry named free variables (ReferredSet) resolved at realization.
  • AppliedSet defers a call to an Impl method by name until realization.

AbsurdSet

Bases: SetBuilder[R]

A builder that cannot be realized.

Used as a sentinel for impossible constructions. Realization raises.

AlignedBoxSet

Bases: SetBuilder[R]

Axis-aligned box possibly unbounded on one side per axis.

Bounds mapping: name -> (vmin, vmax). Use Ellipsis to denote an open side (e.g., (0, ...) or (..., 1)). For periodic axes where vmax < vmin, the range wraps around.

Example:

# Left half-circle bounded in y.
A = AlignedBoxSet(y=(-0.5, 0.5), theta=(+pi/2, -pi/2))
Requires
  • Impl < AxesImpl
  • Impl.complement(inp: R) -> R
  • Impl.halfspace(normal, offset, axes, ...) -> R
  • Impl.intersect(inp1: R, inp2: R) -> R

AppliedSet

Bases: SetBuilder[R]

Defer a call to a function f where args are realized builders.

The function is specified by name funcname and looked up on the Impl at realization, i.e. Impl.<funcname>(*args), or a direct lambda if func is a callable.

  • Accumulates required Impl methods from children and adds funcname.
  • Propagates and de-duplicates children's free variables.
  • On realization, calls child builders first, then invokes the Impl method.
  • Wraps child exceptions to pinpoint which argument failed.

BallSet

Bases: SetBuilder[R]

Ball in hyperspace.

The ball is defined over a subset of axes, with Euclidean radius in that subspace. If the selected axes span the whole space, this is a full hypersphere; otherwise it is a lower-dimensional ball embedded in the space.

Parameters:

Name Type Description Default
center list[float]

center coordinates along the selected axes

 required
radius float

ball radius

 required
axes list[Axis]

axis indices (or str if using AxesImpl) spanning the ball

 required
kwds Any

forwarded to Impl.ball

 {}

Example:

# 3D ball in x,y,z subspace
B = BallSet(center=[0.0, 0.0, 0.0], radius=2.0, axes=['x', 'y', 'z'])
Requires
  • Impl.ball(center, radius, axes, ...) -> R

CylinderSet

Bases: SetBuilder[R]

Cylinder in hyperspace.

The cylinder is defined over a subset of axes, with Euclidean radius in that subspace, and extends freely along all remaining axes.

Parameters:

Name Type Description Default
center list[float]

center coordinates along the selected axes

 required
radius float

cylinder radius

 required
vector list[float]

direction vector along which the cylinder extends

 required
kwds Any

forwarded to Impl.cylinder

 {}

Example:

# Infinite cylinder along all axes except x,y
C = CylinderSet(center=[0.0, 0.0], radius=1.0, vector=[0.0, 1.0], axes=['x', 'y'])
Requires
  • Impl.cylinder(center, radius, vector, axes, ...) -> R

EmptySet

Bases: SetBuilder[R]

Builder for the empty set.

Requires
  • Impl.empty() -> R

HalfSpaceSet

Bases: SetBuilder[R]

Half-space described by the normal and offset of a hyperplane.

Note: The set is in the direction of the normal.

Parameters:

Name Type Description Default
normal list[float]

coefficients along each axis

 required
offset list[float]

offsets along each axis

 required
axes list[Axis]

axis indices (or str if using AxesImpl) in the Impl's coordinate system

 required
kwds Any

forwarded to Impl.halfspace

 {}
Requires
  • Impl.halfspace(normal, offset, axes, ...) -> R

PolytopeSet

Bases: SetBuilder[R]

Polytope / polyhedral set as intersection of finitely many halfspaces.

The set is defined by rows of normals and corresponding offsets, i.e. one halfspace per row. Geometrically, this realizes

⋂_i { x | n_i · (x - o_i) >= 0 }

or whatever exact halfspace convention your Impl.halfspace(...) uses.

Note

This builder does not check boundedness. So mathematically this is really a general polyhedral set; whether it is a true polytope depends on the supplied halfspaces.

Parameters:

Name Type Description Default
normals list[list[float]]

one normal vector per halfspace

 required
offsets list[list[float]]

one offset point/vector per halfspace

 required
axes list[Axis]

axis indices (or str if using AxesImpl) in the Impl's coordinate system

 required
kwds Any

forwarded to each Impl.polytope call

 {}
Requires
  • Impl.polytope(normals, offsets, axes, ...) -> R

box(**bounds) classmethod

Convenience constructor for an axis-aligned box/hyper-cube.

halfspace(axes, normal, offset, **kwds) classmethod

Convenience constructor for a single halfspace.

polygon(order, radius, axes, center=None, basis=None, **kwds) classmethod

Convenience constructor for a regular polygon in 2D.

slab(axes, normal, offset, width, **kwds) classmethod

Convenience constructor for a slab between two parallel hyperplanes.

ReferredSet

Bases: SetBuilder[R]

Reference a named free variable resolved from the realization mapping.

ReferredSet('X')(impl, X=some_builder) realizes to some_builder(impl, ...). This is useful in two ways: 1. We can be lazy when constructing the call tree, i.e. we allow users to define which builder to use at a later stage. 2. This essentially allow variables to exist within the call tree which avoids having to reconstruct an entire tree in some cases.

Set

Bases: SetBuilder[R]

Wrap a concrete set value R and return it unchanged on realization.

SetBuilder

Bases: ImplClient[R]

Abstract base for all set builders.

Responsibilities
  • Be callable with an implementation Impl[R] to produce a concrete set R.
  • Track required Impl operations through ImplClient.
  • Track free variable names (see ReferredSet).

Subclasses should implement __call__, which is called to realize the sets.

uid property

Stable hexadecimal id derived from the object hash.

__repr__()

Return a compact identifier for the builder instance.

Compl(*args)

Return complement of a builder via Impl.complement.

Inter(*args)

Return intersection of builders via Impl.intersect.

Union(*args)

Return union of builders via Impl.union.

Get Started Logic Fragments