Set Operations

Set operations for ZonoOpt library. More...

Functions
std::unique_ptr< HybZono >	ZonoOpt::affine_inclusion (const HybZono &Z, const IntervalMatrix &R, const Eigen::Vector< zono_float, -1 > &s=Eigen::Vector< zono_float, -1 >())
	Returns inclusion of zonotopic set for uncertain affine map R*Z + s.
std::unique_ptr< HybZono >	ZonoOpt::affine_map (const HybZono &Z, const Eigen::SparseMatrix< zono_float > &R, const Eigen::Vector< zono_float, -1 > &s=Eigen::Vector< zono_float, -1 >())
	Returns affine map R*Z + s of set Z.
std::unique_ptr< HybZono >	ZonoOpt::cartesian_product (const HybZono &Z1, HybZono &Z2)
	Computes the Cartesian product of two sets Z1 and Z2.
std::unique_ptr< HybZono >	ZonoOpt::constrain (HybZono &Z, const Eigen::SparseMatrix< zono_float > &H, const Eigen::Vector< zono_float, -1 > &f, char direction, const Eigen::SparseMatrix< zono_float > &R=Eigen::SparseMatrix< zono_float >())
	Computes the generalized intersection of set Z with H*x <= f, H*x >= f, or H*x = f over matrix R.
std::unique_ptr< ConZono >	ZonoOpt::convex_hull (const std::vector< std::shared_ptr< HybZono > > &Zs, bool exact=true)
	Computes convex hull of several sets.
std::unique_ptr< HybZono >	ZonoOpt::halfspace_intersection (HybZono &Z, const Eigen::SparseMatrix< zono_float > &H, const Eigen::Vector< zono_float, -1 > &f, const Eigen::SparseMatrix< zono_float > &R=Eigen::SparseMatrix< zono_float >())
	Computes the intersection generalized intersection of set Z with halfspace H*x <= f over matrix R.
std::unique_ptr< HybZono >	ZonoOpt::intersection (const HybZono &Z1, HybZono &Z2, const Eigen::SparseMatrix< zono_float > &R=Eigen::SparseMatrix< zono_float >())
	Computes the generalized intersection of sets Z1 and Z2 over the matrix R.
std::unique_ptr< HybZono >	ZonoOpt::intersection_over_dims (const HybZono &Z1, HybZono &Z2, const std::vector< int > &dims)
	Computes the generalized intersection of sets Z1 and Z2 over the specified dimensions.
std::unique_ptr< HybZono >	ZonoOpt::minkowski_sum (const HybZono &Z1, HybZono &Z2)
	Computes Minkowski sum of two sets Z1 and Z2.
std::unique_ptr< HybZono >	ZonoOpt::pontry_diff (HybZono &Z1, Zono &Z2, bool exact=true)
	Computes the Pontryagin difference Z1 - Z2.
std::unique_ptr< HybZono >	ZonoOpt::project_onto_dims (const HybZono &Z, const std::vector< int > &dims)
	Projects set Z onto the dimensions specified in dims.
std::unique_ptr< HybZono >	ZonoOpt::set_diff (const HybZono &Z1, HybZono &Z2, zono_float delta_m=100, bool remove_redundancy=true, const SolverSettings &settings=get_default_solver_settings(), std::shared_ptr< OptSolution > *solution=nullptr, int n_leaves=std::numeric_limits< int >::max(), int contractor_iter=10)
	Set difference Z1 \ Z2.
std::unique_ptr< HybZono >	ZonoOpt::union_of_many (const std::vector< std::shared_ptr< HybZono > > &Zs, bool preserve_sharpness=false, bool expose_indicators=false)
	Computes union of several sets.

Detailed Description

Set operations for ZonoOpt library.

Function Documentation

affine_inclusion()

std::unique_ptr< HybZono > ZonoOpt::affine_inclusion	(	const HybZono &	Z,
		const IntervalMatrix &	R,
		const Eigen::Vector< zono_float, -1 > &	s = Eigen::Vector<zono_float, -1>()
	)

Returns inclusion of zonotopic set for uncertain affine map R*Z + s.

Parameters

Z	zonotopic set
R	interval matrix
s	vector offset

Returns

zonotopic set

This computes an over-approximation of the affine map using the method of Rego et. al. (2020) "Guaranteed methods based on constrained zonotopes for set-valued state estimation of nonlinear discrete-time systems" The SVD-based zonotope over-approximation method is used in this function when Z is a constrained zonotope. When Z is a hybrid zonotope, the convex relaxation is used to produce a constrained zonotope, and then the SVD-based method is applied.

Exceptions

std::invalid_argument

if R, s, and Z have inconsistent dimensions.

affine_map()

std::unique_ptr< HybZono > ZonoOpt::affine_map	(	const HybZono &	Z,
		const Eigen::SparseMatrix< zono_float > &	R,
		const Eigen::Vector< zono_float, -1 > &	s = Eigen::Vector<zono_float, -1>()
	)

Returns affine map R*Z + s of set Z.

Parameters

Z	zonotopic set
R	affine map matrix
s	vector offset

Returns

zonotopic set

Exceptions

std::invalid_argument

if R, s, and Z have inconsistent dimensions.

cartesian_product()

std::unique_ptr< HybZono > ZonoOpt::cartesian_product	(	const HybZono &	Z1,
		HybZono &	Z2
	)

Computes the Cartesian product of two sets Z1 and Z2.

Parameters

Z1	zonotopic set
Z2	zonotopic set

Returns

zonotopic set

constrain()

std::unique_ptr< HybZono > ZonoOpt::constrain	(	HybZono &	Z,
		const Eigen::SparseMatrix< zono_float > &	H,
		const Eigen::Vector< zono_float, -1 > &	f,
		char	direction,
		const Eigen::SparseMatrix< zono_float > &	R = Eigen::SparseMatrix<zono_float>()
	)

Computes the generalized intersection of set Z with H*x <= f, H*x >= f, or H*x = f over matrix R.

Parameters

Z	zonotopic set
H	constraint matrix
f	constraint vector
direction	'<' for <=, '>' for >=, '=' for =
R	affine map matrix, defaults to identity

Returns

zonotopic set

Exceptions

std::invalid_argument

if direction is not one of '<', '>', '=', or if Z, H, f, and R have inconsistent dimensions.

convex_hull()

std::unique_ptr< ConZono > ZonoOpt::convex_hull	(	const std::vector< std::shared_ptr< HybZono > > &	Zs,
		bool	exact = true
	)

Computes convex hull of several sets.

Parameters

Zs	Sets for which convex hull is to be computed.
exact	If false and all sets are zonotopes, a zonotope outer approximation is returned.

Returns

constrained zonotope convex hull

Computes convex hull of sets {Z0, Z1, ..., Zn}. If Zi is a hybrid zonotope, it must be sharp or this function will throw an error. Zonotope outer approximations are computed using the method of Girard 2005, "Reachability of Uncertain Linear Systems Using Zonotopes".

Exceptions

std::invalid_argument

if Zs is empty, if any member is a non-sharp hybrid zonotope, or if the outer-approximation path encounters a non-zonotope input.

halfspace_intersection()

std::unique_ptr< HybZono > ZonoOpt::halfspace_intersection	(	HybZono &	Z,
		const Eigen::SparseMatrix< zono_float > &	H,
		const Eigen::Vector< zono_float, -1 > &	f,
		const Eigen::SparseMatrix< zono_float > &	R = Eigen::SparseMatrix<zono_float>()
	)

Computes the intersection generalized intersection of set Z with halfspace H*x <= f over matrix R.

Parameters

Z	zonotopic set
H	halfspace matrix
f	halfspace vector
R	affine map matrix

Returns

zonotopic set

Calls constrain with '<'

Exceptions

std::invalid_argument

if Z, H, f, and R have inconsistent dimensions.

intersection()

std::unique_ptr< HybZono > ZonoOpt::intersection	(	const HybZono &	Z1,
		HybZono &	Z2,
		const Eigen::SparseMatrix< zono_float > &	R = Eigen::SparseMatrix<zono_float>()
	)

Computes the generalized intersection of sets Z1 and Z2 over the matrix R.

Parameters

Z1	zonotopic set
Z2	zonotopic set
R	affine map matrix

Returns

zonotopic set

Exceptions

std::invalid_argument

if Z1, Z2, and R have inconsistent dimensions.

intersection_over_dims()

std::unique_ptr< HybZono > ZonoOpt::intersection_over_dims	(	const HybZono &	Z1,
		HybZono &	Z2,
		const std::vector< int > &	dims
	)

Computes the generalized intersection of sets Z1 and Z2 over the specified dimensions.

Parameters

Z1	zonotopic set
Z2	zonotopic set
dims	vector of dimensions

Returns

zonotopic set

Exceptions

std::invalid_argument

if Z2.n does not match the number of dimensions, or if any entry in dims is not a valid dimension of Z1.

minkowski_sum()

std::unique_ptr< HybZono > ZonoOpt::minkowski_sum	(	const HybZono &	Z1,
		HybZono &	Z2
	)

Computes Minkowski sum of two sets Z1 and Z2.

Parameters

Z1	zonotopic set
Z2	zonotopic set

Returns

zonotopic set

Exceptions

std::invalid_argument

if Z1 and Z2 have different dimensions.

pontry_diff()

std::unique_ptr< HybZono > ZonoOpt::pontry_diff	(	HybZono &	Z1,
		Zono &	Z2,
		bool	exact = true
	)

Computes the Pontryagin difference Z1 - Z2.

Parameters

Z1	minuend
Z2	subtrahend
exact	require output to be exact, otherwise inner approximation will be returned (default true)

Returns

zonotopic set

For inner approximations (exact = false), the algorithm from Vinod et. al. 2025 is used. Note that this algorithm is exact when the minuend is a constrained zonotope and the matrix [G;A] is invertible. Exact Pontryagin difference can only be computed when the subtrahend is a zonotope.

Exceptions

std::invalid_argument	if Z1 and Z2 have different dimensions, or if the inexact difference is requested when the minuend is a hybrid zonotope.
std::runtime_error	if internal preconditions fail (e.g., redundancy-removal failure during the computation).

project_onto_dims()

std::unique_ptr< HybZono > ZonoOpt::project_onto_dims	(	const HybZono &	Z,
		const std::vector< int > &	dims
	)

Projects set Z onto the dimensions specified in dims.

Parameters

Z	zonotopic set
dims	vector of dimensions

Returns

zonotopic set

Exceptions

std::invalid_argument

if any entry in dims is not a valid dimension of Z.

set_diff()

std::unique_ptr< HybZono > ZonoOpt::set_diff	(	const HybZono &	Z1,
		HybZono &	Z2,
		zono_float	delta_m = 100,
		bool	remove_redundancy = true,
		const SolverSettings &	settings = get_default_solver_settings(),
		std::shared_ptr< OptSolution > *	solution = nullptr,
		int	n_leaves = std::numeric_limits<int>::max(),
		int	contractor_iter = 10
	)

Set difference Z1 \ Z2.

Parameters

Z1	zonotopic set
Z2	zonotopic set
delta_m	parameter defining range of complement
remove_redundancy	remove redundant constraints and unused generators in get_leaves function call
settings	optimization settings for get_leaves function call
solution	optimization solution for get_leaves function call
n_leaves	maximum number of leaves to return in get_leaves function call
contractor_iter	number of interval contractor iterations to run if using remove_redundancy

Returns

zonotopic set

union_of_many()

std::unique_ptr< HybZono > ZonoOpt::union_of_many	(	const std::vector< std::shared_ptr< HybZono > > &	Zs,
		bool	preserve_sharpness = false,
		bool	expose_indicators = false
	)

Computes union of several sets.

Parameters

Zs	Sets to be unioned.
preserve_sharpness	Flag to preserve sharpness of the union at expense of complexity.
expose_indicators	Flag to append indicator set to the union.

Returns

zonotopic set

Computes union of sets {Z0, Z1, ..., Zn}. If expose_indicators is true, returns union({Z0, ..., Zn}) x I where I is the indicator set for the union. Specifically, each dimension of I corresponds to one of the Zi in the union. So for union_of_many({Z0, Z1, Z2}, true) with Z0, Z1, Z2 not intersecting, if a vector [z, i] is in union({Z0, Z1, Z2}) x I, then i = [1, 0, 0] if z is in Z0, etc.

Exceptions

std::invalid_argument

if Zs is empty or if its members have inconsistent dimensions.