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, polytope).

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.

AppliedSet

Bases: SetBuilder[R]

Defer a call to a function f where args can be set builders.

The function is specified by name funcname and looked up on the Impl at realization, i.e. Impl.<funcname>(*args, **kwds), or a direct lambda if func is a callable. Only args are allowed to be set builders (or constants), i.e. kwds are passed directly to the function.

  • 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

QuadraticSet

Bases: SetBuilder[R]

ball(center, radius, axes, **kwds) classmethod

Convenience constructor; returns a BallSet.

cylinder(center, radius, vector, **kwds) classmethod

Convenience constructor; returns a CylinderSet.

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.

Debug Logic Fragments