diff --git a/zonopy/contset/polynomial_zonotope/batch_mat_poly_zono.py b/zonopy/contset/polynomial_zonotope/batch_mat_poly_zono.py index 5d10aa9..0378bea 100644 --- a/zonopy/contset/polynomial_zonotope/batch_mat_poly_zono.py +++ b/zonopy/contset/polynomial_zonotope/batch_mat_poly_zono.py @@ -12,32 +12,43 @@ _matmul_genmpz_impl, ) -class batchMatPolyZonotope(): - ''' - +class batchMatPolyZonotope: + r''' Batched 2D Matrix Polynomial Zonotopes - c: center maxtrix of the matrix polyonmial zonotope - , shape: [nx,ny] - G: generator tensor containing the dependent generators - , shape: [N, nx, ny] - Grest: generator tensor containing the independent generators - , shape: [M, nx, ny] - expMat: matrix containing the exponents for the dependent generators - , shape: [N, p] - id: vector containing the integer identifiers for the dependent factors - , shape: [p] + Batched form of the :class:`matPolyZonotope` class. + This class is designed to represent a batch of 2D matrix polynomial zonotopes over the same domain + with arbitrary batch dimensions, extending the concept of polynomial zonotopes to matrix forms and allowing for batch processing. + It adheres to a formulation similar to the :class:`polyZonotope` and :class:`batchPolyZonotope` classes, + enabling efficient representation and manipulation of sets of matrix polynomial zonotopes. - Eq. (coeff. a1,a2,...,aN; b1,b2,...,bp \in [0,1]) - G = [[Gd1],[Gd2],...,[GdN]] - Grest = [[Gi1],[Gi2],...,[GiM]] - (Gd1,Gd2,...,GdN,Gi1,Gi2,...,GiM \in R^(nx,ny), matrix) - expMat = [[i11,i12,...,i1p],[i21,i22,...,i2p],...,[iN1,iN2,...,iNp]] - id = [0,1,2,...,p-1] + This results in a :math:`\mathbf{Z} \in \mathbb{R}^{B_1 \times B_2 \times \cdots \times B_b \times (N+M+1) \times dx \times dy}` tensor, + where :math:`dx` and :math:`dy` are the dimensions of the matrices. - pZ = c + a1*Gi1 + a2*Gi2 + ... + aN*GiN + b1^i11*b2^i21*...*bp^ip1*Gd1 + b1^i12*b2^i22*...*bp^ip2*Gd2 + ... - + b1^i1M*b2^i2M*...*bp^ipM*GdM + Refer to the :class:`matPolyZonotope` class for more detailed information on matrix polynomial zonotopes. ''' - def __init__(self,Z,n_dep_gens=0,expMat=None,id=None,copy_Z=True, device=None, dtype=None): + def __init__(self, Z, n_dep_gens=0, expMat=None, id=None, copy_Z=True, dtype=None, device=None): + r''' Constructor for the batchMatPolyZonotope class + + Initializes a batch of 2D matrix polynomial zonotopes with specified characteristics. + + Args: + Z (torch.Tensor): The center and generator tensor for the batch of matrix polynomial zonotopes. + The shape of Z should be :math:`(B_1, B_2, \cdots, B_b, N+M+1, dx, dy)`, where :math:`B_1, B_2, \cdots, B_b` are the batch dimensions, + :math:`N` is the number of dependent generators, :math:`M` is the number of independent generators, + and :math:`dx, dy` are the dimensions of the matrices. + n_dep_gens (int, optional): The number of dependent generators in the matrix polynomial zonotope. Default: 0. + expMat (torch.Tensor, optional): The exponent matrix for the dependent generators. If `None`, it will be assumed to be the identity matrix. Default: None. + id (torch.Tensor, optional): The integer identifiers for the dependent generators. If `None`, it will be the range of the number of dependent generators. Default: None. + copy_Z (bool, optional): If `True`, a copy of the input `Z` tensor will be made. Default: `True`. + dtype (torch.dtype, optional): The data type for the elements of the matrix polynomial zonotope. If `None`, it will be inferred from `Z`. Default: `None`. + device (torch.device, optional): The device on which the matrix polynomial zonotope is to be stored. If `None`, it will be inferred from `Z`. Default: `None`. + + Raises: + AssertionError: If the dimension of the `Z` input is not 5 or more, indicating incorrect batch dimensions or matrix dimensions. + AssertionError: If the exponent matrix does not seem to be valid for the given number of dependent generators or ids. + AssertionError: If the number of dependent generators does not match the number of ids provided. + AssertionError: If the exponent matrix is not a non-negative integer matrix. + ''' # If compress=2, it will always copy. # Make sure Z is a tensor and shaped right diff --git a/zonopy/contset/polynomial_zonotope/batch_poly_zono.py b/zonopy/contset/polynomial_zonotope/batch_poly_zono.py index 66eb0ff..47fed90 100644 --- a/zonopy/contset/polynomial_zonotope/batch_poly_zono.py +++ b/zonopy/contset/polynomial_zonotope/batch_poly_zono.py @@ -19,34 +19,39 @@ import zonopy.internal as zpi class batchPolyZonotope: - ''' - pZ: - - c: center of the polyonmial zonotope - , shape: [B1, B2, .. , Bb, nx] - G: generator matrix containing the dependent generators - , shape: [B1, B2, .. , Bb, N, nx] - Grest: generator matrix containing the independent generators - , shape: [B1, B2, .. , Bb, M, nx] - expMat: matrix containing the exponents for the dependent generators - , shape: [N, p] - id: vector containing the integer identifiers for the dependent factors - , shape: [p] - compress: level for compressing dependent generators with expodent - 0: no compress, 1: compress zero dependent generators, 2: compress zero dependent generators and remove redundant expodent - - Eq. (coeff. a1,a2,...,aN; b1,b2,...,bp \in [0,1]) - G = [gd1,gd2,...,gdN] - Grest = [gi1,gi2,...,giM] - expMat = [[i11,i12,...,i1N],[i21,i22,...,i2N],...,[ip1,ip2,...,ipN]] - id = [0,1,2,...,p-1] - - pZ = c + a1*gi1 + a2*gi2 + ... + aN*giN + b1^i11*b2^i21*...*bp^ip1*gd1 + b1^i12*b2^i22*...*bp^ip2*gd2 + ... - + b1^i1M*b2^i2M*...*bp^ipM*gdM - + r''' Batched 1D polynomial zonotope + + Batched form of the :class:`polyZonotope` class. + This class is used to represent a batch of polynomial zonotopes over the same domain + with arbitrary batch dimensions. + It follows a similar formulation from the :class:`polyZonotope` class as the + :class:`batchZonotope` class did from :class:`zonotope`. + + This results in a :math:`\mathbf{Z} \in \mathbb{R}^{B_1 \times B_2 \times \cdots \times B_b \times (N+M+1) \times d}` tensor + + Refer to the :class:`polyZonotope` class for more information polynomial zonotops. ''' # NOTE: property for mat pz def __init__(self,Z,n_dep_gens=0,expMat=None,id=None,copy_Z=True, dtype=None, device=None): + r''' Constructor for the batchPolyZonotope class + + Args: + Z (torch.Tensor): The center and generator matrix of the polynomial zonotope. + The shape of Z should be :math:`(B_1, B_2, \cdots, B_b, N+M+1, d)` where :math:`B_1, B_2, \cdots, B_b` are the batch dimensions, + :math:`N` is the number of dependent generators, :math:`M` is the number of independent generators, and :math:`d` is the dimension of the zonotope. + n_dep_gens (int, optional): The number of dependent generators in the polynomial zonotope. Default is 0. + expMat (torch.Tensor, optional): The exponent matrix of the dependent generators. If ``None``, it will be the identity matrix. Default: None + id (torch.Tensor, optional): The integer identifiers for the dependent generators. If ``None``, it will be the range of the number of dependent generators. Default: None + copy_Z (bool, optional): If ``True``, it will copy the input ``Z`` value. Default: ``True`` + dtype (torch.dtype, optional): The data type of the polynomial zonotope. If ``None``, it will be inferred. Default: ``None`` + device (torch.device, optional): The device of the polynomial zonotope. If ``None``, it will be inferred. Default: ``None`` + + Raises: + AssertionError: If the dimension of Z input is not 3 or more. + AssertionError: If the exponent matrix does not seem to be valid for the given dependent generators or ids. + AssertionError: If the number of dependent generators does not match the number of ids. + AssertionError: If the exponent matrix is not a non-negative integer matrix. + ''' # If compress=2, it will always copy. # Make sure Z is a tensor and shaped right