timor.Volume ============ .. py:module:: timor.Volume Classes ------- .. autoapisummary:: timor.Volume.BoxVolume timor.Volume.CylinderVolume timor.Volume.SphereVolume timor.Volume.Volume Module Contents --------------- .. py:class:: BoxVolume(limits, offset = Transformation.neutral()) .. autoapi-inheritance-diagram:: timor.Volume.BoxVolume :parts: 1 :private-bases: A box volume is an expansion in the three-dimensional euclidean space forming a solid box. The basic building block of a box volume. :param limits: Defined by :math:(x, y, z) with shape (3,2) :param offset: Transformation offset of the volume, inherited from super class .. py:attribute:: __slots__ :value: () .. py:attribute:: _limits :type: numpy.ndarray .. py:attribute:: _offset :type: timor.utilities.transformation.Transformation .. py:method:: _projection(point) Keep cartesian coordinates .. py:attribute:: _rounding_error :type: float :value: 1e-12 .. py:method:: contains(r_point) Check whether a given point (3,) locates within the volume .. py:method:: discretize(grid_size) Discretize points in grid form inside this volume. It should be noticed that a hyperrectangle must surround a sphere or cylinder, which also means there could be many points existing in the complementary space between the volume and hyperrectangle. So a contains check is a must for the volume subclass. Those not contained in the volume will be given "nan" value. :param grid_size: the number of grid along each side of the hyperbox, should be an integer array. :return: A (grid_size x grid_size x grid_size x 3) array as a point representing the center of the subgrid. Notice: There could also be "nan" for sphere and cylinder for those fail to pass the contains check. .. py:method:: is_convex() A fully filled box is always convex. .. py:property:: lim_x :type: numpy.ndarray Exposes the limits in x-direction .. py:property:: lim_y :type: numpy.ndarray Exposes the limits in y-direction .. py:property:: lim_z :type: numpy.ndarray Exposes the limits in z-direction .. py:property:: limit_rectangular_cuboid :type: numpy.ndarray Return the edge vertices for box with the minimal and maximal value in each dimension. .. py:method:: sample_uniform(rng = None) Sample points within the partial box which are defined by [x, y, z] uniformly. :param rng: Random number generator :return: A point which is sampled uniformly inside the volume .. py:property:: vol :type: float The actual volume of the partial sampling space .. py:class:: CylinderVolume(limits, offset = Transformation.neutral()) .. autoapi-inheritance-diagram:: timor.Volume.CylinderVolume :parts: 1 :private-bases: A cylindrical volume is an expansion in the three-dimensional euclidean space forming a solid cylinder. The basic building block of a cylindrical volume. :param limits: Defined by :math:(r, \phi, \z) with shape (3,2), where, :math:`\phi` is in the range of :math:`(-\pi, \pi).` :param offset: Transformation offset of the volume, inherited from super class .. py:attribute:: __slots__ :value: () .. py:attribute:: _limits :type: numpy.ndarray .. py:attribute:: _offset :type: timor.utilities.transformation.Transformation .. py:method:: _projection(point) Map cartesian to cylindrical coordinates .. py:attribute:: _rounding_error :type: float :value: 1e-12 .. py:method:: contains(r_point) Check whether a given point (3,) locates within the volume .. py:method:: discretize(grid_size) Discretize points in grid form inside this volume. It should be noticed that a hyperrectangle must surround a sphere or cylinder, which also means there could be many points existing in the complementary space between the volume and hyperrectangle. So a contains check is a must for the volume subclass. Those not contained in the volume will be given "nan" value. :param grid_size: the number of grid along each side of the hyperbox, should be an integer array. :return: A (grid_size x grid_size x grid_size x 3) array as a point representing the center of the subgrid. Notice: There could also be "nan" for sphere and cylinder for those fail to pass the contains check. .. py:method:: from_radius_height(r, z) :classmethod: The limits for the full cylinder with radius = r and height = z .. py:method:: is_convex() Check whether the cylinder volume is convex. .. py:property:: lim_phi :type: numpy.ndarray The azimuthal limits .. py:property:: lim_r :type: numpy.ndarray The radial limits .. py:property:: lim_z :type: numpy.ndarray The height limits .. py:property:: limit_rectangular_cuboid :type: numpy.ndarray Return the edge vertices for cylinder with the minimal and maximal value in each dimension .. py:method:: sample_uniform(rng = None) Sample points within the partial cylinder which are defined by [r, theta, height] uniformly. :param rng: Random number generator :return: A point which is sampled uniformly inside the volume .. py:property:: vol :type: float The actual volume of the partial sampling space .. py:class:: SphereVolume(limits, offset = Transformation.neutral()) .. autoapi-inheritance-diagram:: timor.Volume.SphereVolume :parts: 1 :private-bases: A spherical volume is an expansion in the three-dimensional euclidean space forming a fully/partially filled sphere. The basic building block of a spherical volume. :param limits: Defined by :math:(r, \theta, \phi)` with shape (3,2) according to ISO 80000-2:2019 representation where, :math:`\theta` is in the range of :math:`(0, \pi).` :math:`\phi` is in :math:`(-\pi, \pi).` :param offset: Transformation offset of the volume, inherited from super class .. py:attribute:: __slots__ :value: () .. py:attribute:: _limits :type: numpy.ndarray .. py:attribute:: _offset :type: timor.utilities.transformation.Transformation .. py:method:: _projection(point) Map cartesian to spherical coordinates .. py:attribute:: _rounding_error :type: float :value: 1e-12 .. py:method:: contains(r_point) Check whether a given point (3,) locates within the volume .. py:method:: discretize(grid_size) Discretize points in grid form inside this volume. It should be noticed that a hyperrectangle must surround a sphere or cylinder, which also means there could be many points existing in the complementary space between the volume and hyperrectangle. So a contains check is a must for the volume subclass. Those not contained in the volume will be given "nan" value. :param grid_size: the number of grid along each side of the hyperbox, should be an integer array. :return: A (grid_size x grid_size x grid_size x 3) array as a point representing the center of the subgrid. Notice: There could also be "nan" for sphere and cylinder for those fail to pass the contains check. .. py:method:: from_radius(r) :classmethod: The limits for the full sphere with radius equal to r .. py:method:: is_convex() Check whether the sphere volume is convex. .. py:property:: lim_phi :type: numpy.ndarray The polar limits .. py:property:: lim_r :type: numpy.ndarray The radial limits .. py:property:: lim_theta :type: numpy.ndarray The azimuthal limits .. py:property:: limit_rectangular_cuboid :type: numpy.ndarray Return the edge vertices for sphere with the minimal and maximal value in each dimension. It should be noticed that this could be quite a bit tighter if the allowed angles are restricted. .. py:method:: sample_uniform(rng = None) Sample points within the partial sphere which are defined by [r, theta, phi] uniformly. :param rng: Random number generator :source: stats.stackexchange.com/questions/8021 :return: A point which is sampled uniformly inside the volume .. py:property:: vol :type: float The actual volume of the partial sampling space .. py:class:: Volume(limits, offset = Transformation.neutral()) .. autoapi-inheritance-diagram:: timor.Volume.Volume :parts: 1 :private-bases: A Volume is a connected sub-set of a three-dimensional euclidean space. Initialize a volume with a transformation offset for every sample. :param limits: Limits for defining the shape of the volume -> (3,2) :param offset: Transformation offset of the volume with shape -> (4,4) .. py:attribute:: __slots__ :value: () .. py:attribute:: _limits :type: numpy.ndarray .. py:attribute:: _offset :type: timor.utilities.transformation.Transformation .. py:method:: _projection(point) :abstractmethod: Maps a point to the projection space of the limits .. py:attribute:: _rounding_error :type: float :value: 1e-12 .. py:method:: contains(r_point) Check whether a given point (3,) locates within the volume .. py:method:: discretize(grid_size) Discretize points in grid form inside this volume. It should be noticed that a hyperrectangle must surround a sphere or cylinder, which also means there could be many points existing in the complementary space between the volume and hyperrectangle. So a contains check is a must for the volume subclass. Those not contained in the volume will be given "nan" value. :param grid_size: the number of grid along each side of the hyperbox, should be an integer array. :return: A (grid_size x grid_size x grid_size x 3) array as a point representing the center of the subgrid. Notice: There could also be "nan" for sphere and cylinder for those fail to pass the contains check. .. py:property:: is_convex :type: bool :abstractmethod: Determines whether the volume is convex. This should be implemented by subclasses based on their specific geometric properties. .. py:property:: limit_rectangular_cuboid :type: numpy.ndarray :abstractmethod: Get the edge vertex with the extreme value in each dimension for a hyperrectangle over-approximating the volume. :return: 2x3 array with the first element for minimal vertex and the second for maximal vertex .. py:method:: sample_uniform(rng = None) :abstractmethod: Uniformly sample a point inside the volume. :param rng: Random number generator :return: A point as a (3,) np array .. py:property:: vol :type: float :abstractmethod: Calculate the actual volume of the sampling space