hj_reachability

Previous Next

Reference

Hamilton-Jacobi backend implementations.

This module integrates the external hj_reachability package with pyspect by providing a concrete backend for level-set operations and time-varying reachability queries used during TLT realization.

Provided classes
  • TVHJImpl: Main HJ backend operating on gridded level-set arrays.
  • TVHJImplDebugger: Debug helper for inspecting HJ backend behavior.
Backend capabilities
  • Set operations: empty, complement, intersect, union
  • Geometry: halfspace and axis-aware projections
  • Reachability: pre, reach, avoid with time-varying targets/constraints
  • Visualization: Plotly-based bitmap/surface/isosurface transforms
Requires
  • hj_reachability
  • jax_tqdm
Notes
  • Uses JAX arrays as the underlying set/value representation.

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 R - a tuple of plot inputs accepted by plot - a single (R, dict) pair for per-input kwargs

 required
method

Plotting method passed to plot.

 required
fig BaseFigure

Figure to animate into. If not provided, a new figure is created.

 required
**kwds

Plot kwargs plus optional animate_* options.

 {}
Animate options

animate_names: Optional list of frame labels. animate_prefix: Slider current value prefix (default: "Frame: "). animate_frame_duration: Frame duration in ms (default: 500). animate_transition_duration: Transition duration in ms (default: 300). animate_redraw: Whether to redraw each frame (default: True). animate_easing: Transition easing (default: "quad-in-out").

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 {method} or plot_{method}.

 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.

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

TLT Primitives ZonoOpt