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, **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

generator

Generator object associated with volume that supplies atoms.

Type

Generator

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.

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.