molgri.space.rotobj
Grids on N-dimensional spheres.
This module is one of central building blocks of the molgri package. The central object here is the SphereGridNDim (And the corresponding Factory object that creates a sphere grid given the algorithm, dimension and number of points). A SphereGridNDim object implements a grid that consists of points on a N-dimensional unit sphere.
- Connected to:
polytope module - some algorithms for creating sphere grids are based of subdivision of polytopes
- fullgrid module - combines a 3D SphereGridNDim, a 4D SphereGridNDim and a translation grid to sample the full
approach space
Functions
|
Take an array of any shape in which each row is an element. |
Classes
|
This is a central object for studying the convergence of SphereGridNDim objects with the number of dimensions. |
|
|
|
|
|
|
|
|
|
|
|
|
This should be the only access point to all SphereGridNDim objects. |
|
|
This is a general and abstract implementation of a spherical grid in any number of dimensions (currently only using 3 or 4 dimensions). |
|
|
|
- class molgri.space.rotobj.SphereGridNDim(dimensions: int, N: int | None = None, use_saved: bool = True, print_messages: bool = False, time_generation: bool = False, filter_non_unique=False)
This is a general and abstract implementation of a spherical grid in any number of dimensions (currently only using 3 or 4 dimensions). Each subclass is a particular implementation that must implement the abstract method _gen_grid_4D. If the implementation of _gen_grid_3D is not overridden, the 3D grid will be created from the 4D one using 4D grid to act as rotational quaternions on the unit z vector.
- algorithm_name = 'generic'
- __init__(dimensions: int, N: int | None = None, use_saved: bool = True, print_messages: bool = False, time_generation: bool = False, filter_non_unique=False)
- get_N() int
Get the number of points in the self.grid array. It is important to use this getter and not the attribute self.N as they can differ if the self.filter_non_unique option is set.
- gen_grid() ndarray[Any, dtype[ScalarType]]
This method saves to self.grid if it has been None before (and checks the format) but returns nothing. This method only implements loading/timing/printing logic, the actual process of creation is outsourced to self._gen_grid() that is implemented by sub-classes.
To get the grid, use self.get_grid_as_array().
- gen_and_time() ndarray[Any, dtype[ScalarType]]
Same as generation, but prints the information about time needed. Useful for end users.
- get_name(with_dim: bool = True) str
This is a standard name that can be used for saving files, but not pretty enough for titles etc.
- Args:
with_dim: if True, include _3d or _4d to include dimensionality of the grid
- Returns:
a string usually of the form ‘ico_17’
- get_decorator_name() str
Name used in printing and decorators, not suitable for file names.
- get_grid_path(extension='npy') str
Get the entire path to where the fullgrid is saved.
- get_statistics_path(extension) str
get the entire path to where the statistics are saved.
- get_grid_as_array() ndarray[Any, dtype[ScalarType]]
Get the sphere grid. If not yet created but N is set, will generate/load the grid automatically.
- save_grid(extension: str = 'npy')
Deprecated - all necessary data is saved by individual methods using save_or_use_saved.
- save_uniformity_statistics(num_random: int = 100, alphas=None)
Deprecated - all necessary data is saved by individual methods using save_or_use_saved. Save both the short, user-friendly summary of statistics and the entire uniformity data.
- get_uniformity_df(alphas)
Get the dataframe necessary to draw violin plots showing how uniform different generation algorithms are.
- get_convergence_df(alphas: tuple, N_list: tuple = None)
Get the dataframe necessary to draw convergence plots for various values of N.
- get_spherical_voronoi_cells()
A spherical grid (in 3D) can be used as a basis for a spherical Voronoi grid. In this case, each grid point is used as a center of a Voronoi cell. The spherical Voronoi cells also have the radius 1.
The division into cells will fail in case points are not unique (too close to each other)
- get_voronoi_areas()
From Voronoi cells you may also calculate areas on the sphere that are closest each grid point. The order of areas is the same as the order of points in self.grid.
- molgri.space.rotobj.provide_unique(el_array: ndarray[Any, dtype[ScalarType]], tol: int = 5, as_quat=False) ndarray[Any, dtype[ScalarType]]
Take an array of any shape in which each row is an element. Return only the elements that are unique up to the tolerance. # TODO: maybe you could do some sort of decomposition to determine the point of uniqueness?
- Args:
el_array: array with M elements of any shape tol: number of decimal points to consider as_quat: select True if el_array is an array of quatenions and you want to consider q and -q to be non-unique
(respecting double-coverage of quaternions)
- Returns:
array with N <= M elements of el_array that are all unique
- class molgri.space.rotobj.RandomQRotations(dimensions: int, N: int | None = None, use_saved: bool = True, print_messages: bool = False, time_generation: bool = False, filter_non_unique=False)
- algorithm_name = 'randomQ'
- class molgri.space.rotobj.SystemERotations(dimensions: int, N: int | None = None, use_saved: bool = True, print_messages: bool = False, time_generation: bool = False, filter_non_unique=False)
- algorithm_name = 'systemE'
- class molgri.space.rotobj.RandomERotations(dimensions: int, N: int | None = None, use_saved: bool = True, print_messages: bool = False, time_generation: bool = False, filter_non_unique=False)
- algorithm_name = 'randomE'
- class molgri.space.rotobj.ZeroRotations(dimensions: int, N: int | None = None, use_saved: bool = True, print_messages: bool = False, time_generation: bool = False, filter_non_unique=False)
- algorithm_name = 'zero'
- class molgri.space.rotobj.Cube4DRotations(*args, **kwargs)
- algorithm_name = 'cube4D'
- __init__(*args, **kwargs)
- class molgri.space.rotobj.IcoAndCube3DRotations(*args, **kwargs)
- algorithm_name: str = None
- __init__(*args, **kwargs)
- get_z_projection_grid()
In this case, directly construct the 3D object
- class molgri.space.rotobj.IcoRotations(*args, **kwargs)
- algorithm_name: str = 'ico'
- __init__(*args, **kwargs)
- class molgri.space.rotobj.Cube3DRotations(*args, **kwargs)
- algorithm_name: str = 'cube3D'
- __init__(*args, **kwargs)
- class molgri.space.rotobj.SphereGridFactory
This should be the only access point to all SphereGridNDim objects. Simply provide the generation algorithm name, the number of points and dimensions as well as optional arguments. The requested object will be returned.
- classmethod create(alg_name: str, N: int, dimensions: int, **kwargs) SphereGridNDim
- class molgri.space.rotobj.ConvergenceSphereGridFactory(alg_name: str, dimensions: int, N_set=None, use_saved=True, **kwargs)
This is a central object for studying the convergence of SphereGridNDim objects with the number of dimensions.
- __init__(alg_name: str, dimensions: int, N_set=None, use_saved=True, **kwargs)
- get_name()
- create() list
- get_list_sphere_grids()
- get_spherical_voronoi_areas()
Get plotting-ready data on the size of Voronoi areas for different numbers of points.
- get_generation_times(repeats=5)
Get plotting-ready data on time needed to generate spherical grids of different sizes. Each generation is repeated several times to be able to estimate the error.