Volume Module¶
Volumes and MultiVolumes¶
- class czone.volume.volume.BaseVolume(**kwargs)¶
Bases:
abc.ABC
Base abstract class for Volume objects.
Volume objects are subtractive components in Construction Zone. When designing nanostructures, Volumes contain information about where atoms should and should not be placed. Semantically, volumes can be thought of as singular objects in space.
BaseVolumes are typically not created directly. Use the Volume class for generalized convex objects, and the MultiVolume class for unions of convex objects.
- atoms¶
Nx3 array of atom positions of atoms lying within volume.
- Type
np.ndarray
- species¶
Nx1 array of atomic numbers of atoms lying within volume.
- Type
np.ndarray
- ase_atoms¶
Collection of atoms in volume as ASE Atoms object.
- Type
Atoms
- priority¶
Relative generation precedence of volume.
- Type
int
- property ase_atoms¶
Collection of atoms in volume as ASE Atoms object.
- property atoms¶
Array of atomic positions of atoms lying within volume.
- abstract checkIfInterior(testPoints: numpy.ndarray)¶
Check points to see if they lie in interior of volume.
- Returns
Logical array indicating which points lie inside the volume.
- abstract populate_atoms()¶
Fill volume with atoms.
- property priority¶
Relative generation precedence of volume.
- property species¶
Array of atomic numbers of atoms lying within volume.
- to_file(fname, **kwargs)¶
Write object to an output file, using ASE write utilities.
- Parameters
fname (str) – output file name.
**kwargs – any key word arguments otherwise accepted by ASE write.
- abstract transform(transformation)¶
Transform volume with given transformation.
- Parameters
transformation (BaseTransform) – transformation to apply to volume.
- class czone.volume.volume.MultiVolume(volumes: Optional[List[czone.volume.volume.BaseVolume]] = None, priority: Optional[int] = None)¶
Bases:
czone.volume.volume.BaseVolume
Volume object for representing arbitrary union of convex spaces.
Volume objects are subtractive components in Construction Zone. When designing nanostructures, Volumes contain information about where atoms should and should not be placed. Semantically, volumes can be thought of as singular objects in space. In order to supply atoms, Volumes must be given a Generator.
MultiVolumes group multiple Volume objects together into a single semantic object. Within the MultiVolume, Volume intersection is handled with relative precedence levels, analagous to the precedence relationships that are used to handle conflict resolution between Volumes in scenes. Transformations applied to a MultiVolume are applied to every owned volume. MultiVolumes can be nested.
- volumes¶
Nx3 array of points used to defined convex hull.
- Type
np.ndarray
- atoms¶
Nx3 array of atom positions of atoms lying within volume.
- Type
np.ndarray
- species¶
Nx1 array of atomic numbers of atoms lying within volume.
- Type
np.ndarray
- ase_atoms¶
Collection of atoms in volume as ASE Atoms object.
- Type
Atoms
- priority¶
Relative generation precedence of volume.
- Type
int
- add_volume(volume: czone.volume.volume.BaseVolume)¶
Add volume to MultiVolume.
- Parameters
volume (BaseVolume) – Volume object to add to MultiVolume.
- checkIfInterior(testPoints: numpy.ndarray)¶
Check points to see if they lie in interior of volume.
- Returns
Logical array indicating which points lie inside the volume.
- from_volume(**kwargs)¶
Constructor for new MultiVolume based on existing MultiVolume object.
**kwargs passed to volume are applied to every owned Volume individually.
- Parameters
**kwargs –
transformation=List[BaseTransformation] to apply a series
of transfomrations to copied Volume.
generator=BaseGenerator to replace generator associated with volume.
Any kwargs accepted in creation of Volume object.
- populate_atoms()¶
Fill volume with atoms.
- transform(transformation: czone.transform.transform.BaseTransform)¶
Transform volume with given transformation.
- Parameters
transformation (BaseTransform) – transformation to apply to volume.
- property volumes¶
Collection of volumes grouped in MultiVolume.
- class czone.volume.volume.Volume(points: Optional[numpy.ndarray] = None, alg_objects: Optional[numpy.ndarray] = None, generator: Optional[czone.generator.generator.BaseGenerator] = None, priority: int = 0, tolerance: float = 1e-10, **kwargs)¶
Bases:
czone.volume.volume.BaseVolume
Volume object for representing convex spaces.
Volume objects are subtractive components in Construction Zone. When designing nanostructures, Volumes contain information about where atoms should and should not be placed. Semantically, volumes can be thought of as singular objects in space. In order to supply atoms, Volumes must be given a Generator.
Volumes can be created with a series of points in space, in which the interior of the volume is taken as the convex hull of the points in space. They can also be created with a series of algebraic surfaces, such as planes and spheres. Both points and algebraic objects can be used to define a Volume, in which the interior of the Volume is taken as the intersection of the interior region defined by the convex hull of the points and the interior regions of the algebraic objects.
- points¶
Nx3 array of points used to defined convex hull.
- Type
np.ndarray
- alg_objects¶
Algebraic objects used to define convex region.
- Type
List[BaseAlgebraic]
- hull¶
Convex hull of points defining volume.
- Type
ConvexHull
- tri¶
Delaunay triangulation of facets of convex hull.
- Type
Delaunay
- atoms¶
Nx3 array of atom positions of atoms lying within volume.
- Type
np.ndarray
- species¶
Nx1 array of atomic numbers of atoms lying within volume.
- Type
np.ndarray
- ase_atoms¶
Collection of atoms in volume as ASE Atoms object.
- Type
Atoms
- priority¶
Relative generation precedence of volume.
- Type
int
- addPoints(points: numpy.ndarray)¶
Add points to list of points defining convex hull and update hull.
- Parameters
points (np.ndarray) – Nx3 array of points to add to hull.
- add_alg_object(obj: czone.volume.algebraic.BaseAlgebraic)¶
Add an algebraic surface to the volume.
- Parameters
obj (BaseAlgebraic) – Algebraic surface to add to volume.
- add_generator(generator, origin=None)¶
- property alg_objects¶
Algebraic objects used to define convex region.
- checkIfInterior(testPoints: numpy.ndarray)¶
Check points to see if they lie in interior of volume.
- Returns
Logical array indicating which points lie inside the volume.
- createHull()¶
Create convex hull from points defining volume boundaries.
- from_volume(**kwargs)¶
Constructor for new Volumes based on existing Volume object.
- Parameters
**kwargs –
transformation=List[BaseTransformation] to apply a series
of transfomrations to copied Volume.
generator=BaseGenerator to replace generator associated with volume.
Any kwargs accepted in creation of Volume object.
- property generator¶
Generator object associated with volume that supplies atoms.
- get_bounding_box()¶
Get some minimal bounding box defining extremities of regions.
- Returns
Nx3 array of points defining extremities of region enclosed by volume.
- property hull¶
Convex hull of points defining volume.
- property points¶
Nx3 array of points used to defined convex hull.
- populate_atoms()¶
Fill volume with atoms.
- property tolerance¶
Numerical tolerance for simplex checking with convex hulls. Defaults to 1e-10
- transform(transformation: czone.transform.transform.BaseTransform)¶
Transform volume with given transformation.
- Parameters
transformation (BaseTransform) – transformation to apply to volume.
- property tri¶
Delaunay triangulation of facets of convex hull.
- czone.volume.volume.makeRectPrism(a, b, c, center=None)¶
Create rectangular prism.
- Parameters
a (float) – dimension of prism along x
b (float) – dimension of prism along y
c (float) – dimension of prism along z
center (np.ndarray) – center of prism, default None. If None, corner of prism is at origin. Else, prism is translated to have midpoint at center.
- Returns
8x3 numpy array of 8 points defining a rectangular prism in space.
Algebraic Surfaces¶
- class czone.volume.algebraic.BaseAlgebraic(tol: float = 1e-05)¶
Bases:
abc.ABC
Base class for algebraic surfaces.
- params¶
parameters describing algebraic object
- Type
Tuple
- tol¶
numerical tolerance used to pad interiority checks. Default is 1e-5.
- Type
float
- abstract checkIfInterior(testPoints: numpy.ndarray)¶
Check if points lie on interior side of geometric surface.
- Parameters
testPoints (np.ndarray) – Nx3 array of points to check.
- Returns
Nx1 logical array indicating whether or not point is on interior of surface.
- abstract property params¶
- property tol¶
- class czone.volume.algebraic.Cylinder(axis: numpy.ndarray = [0, 0, 1], point: numpy.ndarray = [0, 0, 0], radius: float = 1.0, tol: float = 1e-05)¶
Bases:
czone.volume.algebraic.BaseAlgebraic
Algebraic surface for circular cylinders in R3.
Cylinders are defined with vectors, pointing parallel to central axis; points, lying along central axis; and radii, defining size of cylinder.
- axis¶
vector parallel to central axis of cylinder.
- Type
np.ndarray
- point¶
point which lies along central axis of cylinder.
- Type
np.ndarray
- radius¶
radius of cylinder.
- Type
float
- tol¶
Tolerance value for interiority check. Default is 1e-5.
- Type
float
- property axis¶
Vector lying parallel to central axis.
- checkIfInterior(testPoints)¶
Check if points lie on interior side of geometric surface.
- Parameters
testPoints (np.ndarray) – Nx3 array of points to check.
- Returns
Nx1 logical array indicating whether or not point is on interior of surface.
- params()¶
Return axis, point, and radius of cylinder.
- property point¶
Point lying along central axis.
- property radius¶
Radius of cylinder.
- class czone.volume.algebraic.Plane(normal: Optional[numpy.ndarray] = None, point: Optional[numpy.ndarray] = None, tol: float = 1e-05)¶
Bases:
czone.volume.algebraic.BaseAlgebraic
Algebraic surface for planes in R3.
Interior points lie opposite in direction of plane normal.
- point¶
point lying on plane.
- Type
np.ndarray
- normal¶
normal vector describing orientation of plane.
- Type
np.ndarray
- tol¶
Tolerance value for interiority check. Default is 1e-5.
- Type
float
- checkIfInterior(testPoints: numpy.ndarray)¶
Check if points lie on interior side of geometric surface.
- Parameters
testPoints (np.ndarray) – Nx3 array of points to check.
- Returns
Nx1 logical array indicating whether or not point is on interior of surface.
- dist_from_plane(point: numpy.ndarray)¶
Calculate the distance from a point or series of points to the Plane.
- Arg:
point (np.ndarray): Point in space to calculate distance.
- Returns
Array of distances to plane.
- flip_orientation()¶
Flip the orientation of the plane.
- property normal¶
Normal vector defining orientation of Plane in space.
- property params¶
Return normal vector, point on plane of Plane.
- property point¶
Point lying on surface of Plane.
- project_point(point: numpy.ndarray)¶
Project a point in space onto Plane.
- Arg:
point (np.ndarray): Point in space to project onto Plane.
- Returns
Projected point lying on surface of Plane.
- class czone.volume.algebraic.Sphere(radius: Optional[float] = None, center: Optional[numpy.ndarray] = None, tol=1e-05)¶
Bases:
czone.volume.algebraic.BaseAlgebraic
Algebraic surface for spheres.
Interior points are points with distance from center smaller than the radius.
- radius¶
Radius of sphere.
- Type
float
- center¶
3x1 array representing center of sphere in space.
- Type
np.ndarray
- tol¶
Tolerance value for interiority check. Default is 1e-5.
- Type
float
- property center¶
Center of sphere in space.
- checkIfInterior(testPoints: numpy.ndarray) numpy.ndarray ¶
Check if points lie on interior side of geometric surface.
- Parameters
testPoints (np.ndarray) – Nx3 array of points to check.
- Returns
Nx1 logical array indicating whether or not point is on interior of surface.
- property params¶
Return radius, center of Sphere.
- property radius¶
Radius of sphere.
- czone.volume.algebraic.get_bounding_box(planes: List[czone.volume.algebraic.Plane])¶
Get convex region interior to set of Planes, if one exists.
Determines if set of planes forms a valid interior convex region. If so, returns vertices of convex region. Uses scipy half space intersection and linear progamming routines to determine boundaries of convex region and valid interior points.
- Parameters
planes (List[Plane]) – set of planes to check mutual intersection of.
- Returns
Nx3 array of vertices of convex region. 2: no valid intersection. 3: if intersection is unbounded.
- Return type
np.ndarray
- czone.volume.algebraic.snap_plane_near_point(point: numpy.ndarray, generator: Generator, miller_indices: Tuple[int], mode: str = 'nearest')¶
Determine nearest crystallographic nearest to point in space for given crystal coordinate system.
- Parameters
point (np.ndarray) – Point in space.
generator (Generator) – Generator describing crystal coordinat system.
miller_indices (Tuple[int]) – miller indices of desired plane.
mode (str) – “nearest” for absolute closest plane to point; “floor” for next nearest valid plane towards generator origin; “ceil” for next furthest valid plane from generator origin.
- Returns
Plane in space with orientation given by Miller indices snapped to nearest valid location.
Voxels¶
- class czone.volume.voxel.Voxel(bases: numpy.ndarray = array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]), scale: float = array([1]), origin: numpy.ndarray = array([0.0, 0.0, 0.0]))¶
Bases:
object
Voxel class used to span space for generators and track transformations.
Voxels provide an alterable view of bases and orientation of crystalline generators and are the actual transformed object, not Generators. This is in contrst to applying transformations directly to the underlying pymatgen Structure object, for speed and ease of manipulation. Voxels also help determine how much of a “block” to a Generator needs to build for the purpose of supplying atoms to a larger volume.
- scale¶
Scaling factor of basis set.
- Type
float
- bases¶
Basis vectors defining crystal unit cell.
- Type
np.ndarray
- sbases¶
Scaled basis set.
- Type
np.ndarray
- reciprocal_bases¶
Basis vectors defining unit cell of reciprocal lattice.
- Type
np.ndarray
- origin¶
Origin of Voxel grid.
- Type
np.ndarray
- property bases¶
Basis vectors defining crystal unit cell. Vectors are rows of matrix.
- get_extents(box: numpy.ndarray)¶
Determine minimum contiguous block of voxels that fully covers a space.
- Parameters
box (np.ndarray) – Set of points defining extremities of space.
- Returns
Tuple of minimum extents and maximum extents indicating how many voxels to tile in space, and where, to span a given region.
- property origin¶
Origin of Voxel grid in space.
- property reciprocal_bases¶
Basis vectors defining unit cell of reciprocal lattice.
- property sbases¶
Basis vectors defining crystal unit cell, scaled by scaling factor.
- property scale¶
Scaling factor of basis set.