Reference
ZonoOpt backend implementations.
This module integrates the external zonoopt library with pyspect by
providing a concrete backend for set operations and reachability queries used
during TLT realization.
Provided classes
ZonoOptImpl: Main backend operating onzono.HybZonosets.DoubleIntegrator: Convenience linear dynamics model for examples.
Backend capabilities
- Set operations:
empty,complement,intersect,union - Geometry:
halfspace - Reachability:
pre,reach,reachF
Requires
zonoopt
Notes
- Targets discrete-time linear dynamics workflows.
AxesImpl
Bases: Impl[R]
Base class for axis metadata containers.
AxesImpl is a lightweight container for axis metadata (names, bounds,
periodicity flags, and units). It does NOT store or manipulate the underlying
numerical data; instead it standardizes how set representations (of type R)
expose axis-aware interactions (selection, projection, formatting).
Construction (new):
AxesImpl([
dict(name= 'x', bounds=[xmin, xmax], unit='m'),
dict(name='*phi', bounds=[0, 2*pi], unit='rad'),
dict(name= 'y', bounds=[-5, 5]), # unit optional
])
Also accepted (shorthand): AxesImpl(['x', 'y', 'z']) # all (-inf,+inf), no units
Conventions
- Leading '' in name => periodic axis (name stored without '').
- bounds omitted or Ellipsis => (-inf, +inf)
- unit omitted => ''
- Each axis spec must be a dict with at minimum a 'name' key (unless list[str] form used).
Key properties / methods:
- ndim: number of axes
- axis(ax): resolve axis identifier (int index or name) to int
- axis_name(i): canonical name at index i
- axis_bounds(ax): (min, max) tuple for the resolved axis
- axis_is_periodic(ax): True if marked periodic (via leading '*')
- project_onto(inp, axes): subclasses implement projection onto one or multiple axes.
__init__(specs)
Construct AxesImpl.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axes
|
Either a list of axis spec dicts (preferred) or list of axis name strings. Dict form keys: name (required), bounds (optional), unit (optional), periodic (optional bool). Periodicity may also be encoded by leading '*' in the name. |
required |
assert_axis(ax)
Assert that the given axis identifier is valid.
axis(ax)
Resolve the given axis identifier to an integer index.
axis_bounds(ax)
Get the (min, max) bounds tuple of the given axis.
axis_is_periodic(ax)
Return True if the given axis is marked periodic.
axis_name(i)
Get the canonical name of the axis at the given index.
axis_unit(ax)
Get the unit string of the axis at the given index.
project_onto(inp, axes, **kwds)
Project the input set representation onto the specified axes.
This method should be implemented in subclasses.
The axes argument may be a single axis identifier or a tuple of them.
Additional keyword arguments may be accepted by subclasses.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
The input set to project. |
required |
axes
|
Axis | tuple[Axis, ...]
|
The axis or axes to project onto. |
required |
**kwds
|
Additional keyword arguments for subclass-specific behavior. |
{}
|
Returns:
| Type | Description |
|---|---|
R
|
The projected set. |
PlotlyImpl
Bases: AxesImpl
Example plotting interface.
Integrate these methods where pyspect emits data/sets/meshes
and call with either an existing fig= or let it create one.
PLOT
sph_to_cart(r, theta, phi)
staticmethod
Spherical (deg) → cartesian dict compatible with Plotly camera.eye.
animate(frames, fig, **kwds)
Create a slider-based Plotly animation by reusing plot methods.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frames
|
list[Any]
|
List of frame inputs. Each frame can be either:
- a single plot input |
required |
method
|
Plotting method passed to |
required | |
fig
|
BaseFigure
|
Figure to animate into. If not provided, a new figure is created. |
required |
**kwds
|
Plot kwargs plus optional |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing initial traces, frames, and controls. |
plot(*args, method, fig, **kwds)
General plotting interface.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*args
|
R | tuple[R, dict]
|
TODO. |
()
|
method
|
str
|
Plotting method to use. Implementation must provide |
required |
fig
|
BaseFigure
|
Existing figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments passed to the plotting method. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the plots. |
plot_bitmap(inp, *, value=0.5, axes=(0, 1), fig, **kwds)
Plot a 2D bitmap.
This method visualizes the input data as a 2D bitmap using a heatmap. To select the color
for the "True" values in the bitmap, use the value argument. This must be within the
range defined by zmin and zmax (arguments to go.Heatmap). zmin and zmax default to
0 and 1, respectively.
Note: Requires the transform_to_bitmap method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
value
|
float
|
Value to represent "True" in the bitmap. |
0.5
|
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the heatmap. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the bitmap plot. |
plot_contour(inp, *, axes=(0, 1), fig, **kwds)
Plot a 2D contour.
This method visualizes the input data as a 2D contour using a contour plot. The contour
levels are determined by the values in the 2D array returned by transform_to_surface.
Note: Requires the transform_to_surface method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the contour plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the contour plot. |
plot_fill(inp, *, axes=(0, 1), fig, **kwds)
Plot a filled 2D area.
This method visualizes the input data as a filled area using a scatter plot with
fill='toself'. The area is defined by the points returned by transform_to_scatter.
Note: Requires the transform_to_scatter method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the scatter plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the filled area plot. |
plot_isosurface(inp, *, level=0.0, axes=(0, 1, 2), fig, **kwds)
Plot a 3D isosurface.
This method visualizes the input data as a 3D isosurface using an isosurface plot. The
isosurface is extracted at the specified level from the 3D volume returned by
transform_to_isosurface.
Note: Requires the transform_to_isosurface method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
level
|
float
|
Level at which to extract the isosurface. |
0.0
|
axes
|
Axes3D
|
Three axes to project onto. |
(0, 1, 2)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the isosurface plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the isosurface plot. |
plot_surface(inp, *, axes=(0, 1), fig, **kwds)
Plot a 3D surface.
This method visualizes the input data as a 3D surface using a surface plot. The height of
the surface is determined by the values in the 2D array returned by transform_to_surface.
Note: Requires the transform_to_surface method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the surface plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the surface plot. |
transform_to_bitmap(inp, axes, **kwds)
Transform input data to a bitmap (2D boolean array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A 2D boolean numpy array representing the bitmap. |
transform_to_isosurface(inp, axes, **kwds)
Transform input data to a 3D volume (3D float array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes3D
|
Three axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A 3D float numpy array whose value represents the volume. |
transform_to_scatter(inp, axes, **kwds)
Transform input data to scatter points (N x 2 float array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
An (N, 2) float numpy array representing the scatter points. |
transform_to_surface(inp, axes, **kwds)
Transform input data to a 3D surface (2D float array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A 2D float numpy array whose value represents the surface. |
ZonoOptImpl
Bases: PlotlyImpl[HybZono], AxesImpl[HybZono]
complement(Z)
Computes the set difference between the current zonotopic bounds and another zonotopic set. i.e., returns set_diff(S, Z)
empty()
Returns a EmptySet object.
halfspace(normal, offset, axes=None)
Computes generalized halfspace intersection with bounds over specified axes. normal: array of normal vectors offset: array of offsets for the halfspaces axes: generalized intersection axes, if None, uses all axes
intersect(Z1, Z2)
Computes the intersection of two zonotopic sets. Z1, Z2: zonotopic sets to intersect
pre(target, constraints=None)
Computes one-step backward reachable set from target set
reach(target, constraints=None)
Computes N-step backward reachable set from target set States are confined to the constraint set, which defaults to the zonotopic bounds.
reachF(target, constraints=None)
Computes N-step forward reachable set from target set States are confined to the constraint set, which defaults to the zonotopic bounds.
transform_to_scatter(inp, *, axes=(0, 1, 2), t_max=60.0, settings=zono.OptSettings())
Transforms zonotopic set to scatter plot data. inp: zonotopic set to be transformed axes: axes to plot on t_max: maximum time to spend on finding vertices settings: optimization settings
union(Z1, Z2)
Computes the union of two zonotopic sets. Z1, Z2: zonotopic sets to union
with_figure(f=None, *, dim=None)
Decorator to handle figure creation and theming for plotting methods. Parameters: dim: Dimensionality of the plot (2 or 3).