Polyhedron

Bases: object

Represents a polyhedron (linear region) in d-dimensional space.

Several methods use Gurobi environments for optimization. If one is not provided, an environment will be created automatically.

Interior-point search radius follows relucent.config.MAX_RADIUS unless overridden per call.

clean_data() → None

Clear cached data to reduce memory usage.

Drops large tensors (halfspaces, W, b) and Qhull-derived geometry (_hs, vertices, hull, volume). Resets _attempted_compute_properties so compute_properties() can run again. Keeps the sign sequence, interior-point cache, and lightweight Chebyshev classification (finite, center, inradius, and related flags) so search/plotting need not redo Gurobi Chebyshev solves after a cleanup pass.

get_bounded_halfspaces(bound: float, env: Any = None) → ndarray

Get halfspaces after adding bounding box constraints.

Adds constraints that bound the space to a hypercube of radius bound around the origin. Useful for plotting and visualization.

Parameters:

bound – Radius of the bounding hypercube.
env – Gurobi environment for feasibility checking. If None, uses a cached environment. Defaults to None.

Returns:

Halfspaces with bounding constraints added.

Return type:

np.ndarray

Raises:

ValueError – If the polyhedron does not intersect the bounded region.

get_bounded_vertices(bound: float, qhull_mode: str | None = None) → ndarray | None

Get the vertices of the polyhedron within a bounding hypercube.

Computes the vertices of the polyhedron after intersecting it with a hypercube of radius ‘bound’. Primarily used for plotting and visualization.

Parameters:

bound – Radius of the bounding hypercube.

Returns:

Array of vertex coordinates, or None if the: polyhedron doesn’t intersect the bounded region or computation fails.

Return type:

np.ndarray or None

get_center_inradius(env: Any = None) → tuple[ndarray | None, float | None]

Get the Chebyshev center and inradius of the polyhedron.

This method is “compute-only”: it returns (center, inradius) but does not mutate cached attributes like self._center, self._inradius, or self._finite.

Parameters:: env – Gurobi environment for optimization. If None, uses a cached environment. Defaults to None.
Returns:: (center, inradius). inradius is None if the halfspace system is infeasible (empty); center is None and inradius is inf for nonempty unbounded polyhedra (with infinite Chebyshev formulation).
Return type:: tuple

get_interior_point(env: Any = None, max_radius: float | None = None) → ndarray

Get a point inside the polyhedron.

Computes an interior point of the polyhedron.

This method is “compute-only”: it returns the interior point but does not mutate cached attributes like self._interior_point.

Parameters:

env – Gurobi environment for optimization. If None, uses a cached environment. Defaults to None.
max_radius – Maximum radius constraint for the search. If None, uses relucent.config.MAX_RADIUS. Defaults to None.
zero_indices – Indices of sign sequence elements that are zero (for lower-dimensional polyhedra). Defaults to None.

Returns:

An interior point of the polyhedron.

Return type:

np.ndarray

Raises:

ValueError – If no interior point can be found.

get_neighbor(shi: int) → Polyhedron

Get the neighbor polyhedron across the supporting hyperplane at index shi.

Parameters:: shi – Index of the supporting hyperplane to cross.
Returns:: The neighbor polyhedron.
Return type:: Polyhedron

is_face_of(other: Polyhedron) → bool

Check if this polyhedron is a face of another polyhedron.

Parameters:: other – Another Polyhedron object to check against.
Returns:: True if this polyhedron is a face of the other.
Return type:: bool

nflips(other: Polyhedron) → int

Calculate the number of non-zero sign sequence elements that differ.

Parameters:: other – Another Polyhedron object to compare with.
Returns:: The number of sign sequence elements that differ.
Return type:: int

plot_cells(fill: str = 'toself', showlegend: bool = False, bound: float | None = None, filled: bool = False, plot_halfspaces: bool = False, halfspace_shade: bool = True, **kwargs: Any) → list[Scatter] | list[Mesh3d | Scatter3d]

Plot this cell in input space (2D Scatter or 3D Mesh3d / Scatter3d traces).

Chooses 2D vs 3D from ambient_dim (input-space dimension; typically matches Complex.dim when this polyhedron belongs to a complex).

plot_graph(fill: str = 'toself', showlegend: bool = False, bound: float | None = None, project: float | None = None, **kwargs: Any) → dict[str, Mesh3d | Scatter3d] | None

remove_shi(shi: int) → None

Remove a supporting halfspace index from the cached SHI list.

Raises:: ValueError – If shi is not present in the cached list.

property W: Tensor | ndarray

Affine transformation matrix W such that the polyhedron maps to W*x + b.

Returns:: Transformation matrix.
Return type:: torch.Tensor or np.ndarray

property Wl2: float: L2 norm of the transformation matrix W.

property ambient_dim: int: Dimension of the ambient space.

property b: Tensor | ndarray

Affine transformation bias vector such that the polyhedron maps to W*x + b.

Returns:: Bias vector.
Return type:: torch.Tensor or np.ndarray

property center: ndarray | None: Chebyshev center of the polyhedron for finite polyhedra, or None for unbounded or infeasible.

property ch: ConvexHull | None: Convex hull of the polyhedron for finite polyhedra, or None if unbounded or computation fails.

property codim: int: Codimension of the polyhedron, equal to the number of zero sign sequence elements.

property dim: int: Dimension of the polyhedron, equal to the dimension of the ambient space minus the number of zero sign sequence elements.

property equalities: ndarray: Rows of halfspaces_np corresponding to equality constraints (zeros in the sign sequence).

property feasible: bool: Whether the halfspace system is nonempty (finite is not None).

property finite: bool | None

True, unbounded nonempty False, or empty None.

Type:: Whether the polyhedron is bounded

property halfspaces: Tensor | ndarray

Halfspace representation of the polyhedron.

Returns:

Array of shape (n_constraints, n_dim+1): where each row is [a1, a2, …, ad, b] representing the constraint a^T x + b <= 0.

Return type:

torch.Tensor or np.ndarray

property halfspaces_np: ndarray: Cached NumPy representation of halfspaces.

property hs: HalfspaceIntersection: Halfspace intersection object from scipy.

property hyperplanes: ndarray: Hyperplanes that are safe to use for computation of polyhedron properties.

property inequalities: ndarray

property inradius: float | None: Inradius of the polyhedron, inf if unbounded feasible, None if infeasible.

property interior_point: ndarray | None: A point guaranteed to be inside the polyhedron.

property interior_point_norm: float | None: L2 norm of the interior point.

property net: NN: The neural network I belong to

property non_zero_indices: ndarray: Indices of sign sequence elements that are not zero.

property num_dead_relus: int

Number of dead ReLU neurons (neurons always outputting zero).

Returns:: Count of ReLU neurons that are always inactive for this polyhedron.
Return type:: int

property num_faces: int: Alias for Polyhedron.num_shis

property num_shis: int: Number of faces.

property shis: list[int]: Supporting halfspace indices (SHIs).

property ss: ndarray | Tensor: My sign sequence.

property ss_np: ndarray: Cached NumPy representation of the sign sequence.

property tag: bytes: Unique tag for this polyhedron, computed as a hashable representation of the sign sequence.

property vertices: ndarray | None: Vertices of the polyhedron (not always reliable).

property volume: float: Volume of the polyhedron, infinity for unbounded polyhedra, or -1 if computation fails.

property zero_indices: ndarray: Indices of sign sequence elements that are zero.