Transformation Module¶

General Transformations¶

class czone.transform.transform.BaseTransform(locked: bool = True, basis_only: bool = False)¶

Bases: abc.ABC

Base class for transformation objects which manipulate Generators and Volumes.

Transformation objects contain logic and parameters for manipulating the different types of objects used in Construction Zone, namely, Generators and Volumes. BaseTransform is typically not created directly. Use MatrixTransform for generalized matrix transformations.

locked¶

whether or not transformation applies jointly to volumes containing generators

Type: bool

basis_only¶

whether or not transformation applies only to basis of generators

Type: bool

params¶

parameters describing transformation

Type: tuple

abstract applyTransformation(points: numpy.ndarray) → numpy.ndarray¶

Apply transformation to a collection of points in space.

Parameters: points (np.ndarray) – Nx3 array of points to transform.
Returns: Nx3 array of transformed points.
Return type: np.ndarray

abstract applyTransformation_alg(alg_object: czone.volume.algebraic.BaseAlgebraic) → czone.volume.algebraic.BaseAlgebraic¶

Apply transformation to algebraic object.

Parameters: alg_object (BaseAlgebraic) – Algebraic object to transform.
Returns: Transformed object.
Return type: BaseAlgebraic

abstract applyTransformation_bases(points: numpy.ndarray) → numpy.ndarray¶

Apply transformation to bases of a generator.

Parameters: points (np.ndarray) – 3x3 array of bases from generator voxel.
Returns: transformed 3x3 array of bases.
Return type: np.ndarray

property basis_only: bool¶: Boolean value indicating whether or not transformation applied only to basis of Generators.

property locked: bool¶: Boolean value indicating whether or not transformation jointly applied to Volumes and Generators.

abstract property params: tuple¶: Return parameters describing transformation.

class czone.transform.transform.Inversion(matrix=None, origin=None, locked: bool = True, basis_only: bool = False)¶

Bases: czone.transform.transform.MatrixTransform

Transformation which applies inversion about an origin.

Inversion, Rotation, and Reflection classes are derived classes of MatrixTransform that have special setters which ensure validity of their respective transformations.

property matrix¶: Inversion matrix. Cannot be altered.

class czone.transform.transform.MatrixTransform(matrix=None, origin=None, locked: bool = True, basis_only: bool = False)¶

Bases: czone.transform.transform.BaseTransform

Transformation object that applies arbitrary matrix transformations.

Inversion, Rotation, and Reflection classes are derived classes of MatrixTransform that have special setters which ensure validity of their respective transformations.

matrix¶

3x3 matrix representing transformation

Type: np.ndarray

origin¶

point in R3 representing relative origin in which transformation is applied

Type: np.ndarray

applyTransformation(points)¶

Apply transformation to a collection of points in space.

Parameters: points (np.ndarray) – Nx3 array of points to transform.
Returns: Nx3 array of transformed points.
Return type: np.ndarray

applyTransformation_alg(alg_object)¶

Apply transformation to algebraic object.

Parameters: alg_object (BaseAlgebraic) – Algebraic object to transform.
Returns: Transformed object.
Return type: BaseAlgebraic

applyTransformation_bases(points)¶

Apply transformation to bases of a generator.

Parameters: points (np.ndarray) – 3x3 array of bases from generator voxel.
Returns: transformed 3x3 array of bases.
Return type: np.ndarray

property matrix: numpy.ndarray¶: 3x3 array representing matrix transformation

property origin: numpy.ndarray¶: Point in R3 representing relative origin of transformation

property params¶: Return parameters describing transformation.

class czone.transform.transform.MultiTransform(transforms=None)¶

Bases: czone.transform.transform.BaseTransform

Transformation sequence which applies a numeruous transformations in succession.

transforms¶

list of individual transformations applied

Type: list[BaseTransform]

locked¶

whether any of transformations applied is a joint transformation

Type: bool

basic_only¶

whether any of transformations applied transforms only the generator basis

Type: bool

add_transform(transform)¶: Add a transformation to sequence of transformations

applyTransformation(points)¶

Apply transformation to a collection of points in space.

Parameters: points (np.ndarray) – Nx3 array of points to transform.
Returns: Nx3 array of transformed points.
Return type: np.ndarray

applyTransformation_alg(alg_object)¶

Apply transformation to algebraic object.

Parameters: alg_object (BaseAlgebraic) – Algebraic object to transform.
Returns: Transformed object.
Return type: BaseAlgebraic

applyTransformation_bases(points)¶

Apply transformation to bases of a generator.

Parameters: points (np.ndarray) – 3x3 array of bases from generator voxel.
Returns: transformed 3x3 array of bases.
Return type: np.ndarray

property basis_only¶: Boolean value indicating whether or not any of transformations applies only to basis of generator

property locked¶: Boolean value indicating whether or not any of transformations applies jointly.

property params¶: Return parameters describing transformation.

property transforms¶: Sequence of individual transformations to apply

class czone.transform.transform.Reflection(plane=None, locked: bool = True, basis_only: bool = False)¶

Bases: czone.transform.transform.MatrixTransform

Transformation which applies a relfection about an arbitrary plane.

Inversion, Rotation, and Reflection classes are derived classes of MatrixTransform that have special setters which ensure validity of their respective transformations.

plane¶

plane about which reflection is performed

Type: Plane

applyTransformation_alg(alg_object)¶

Apply transformation to algebraic object.

Parameters: alg_object (BaseAlgebraic) – Algebraic object to transform.
Returns: Transformed object.
Return type: BaseAlgebraic

property matrix: numpy.ndarray¶: 3x3 array representing matrix transformation

property params¶: Return parameters describing transformation.

property plane¶

class czone.transform.transform.Rotation(matrix=None, origin=None, locked: bool = True, basis_only: bool = False)¶

Bases: czone.transform.transform.MatrixTransform

Transformation which applies a rotation about an origin.

Inversion, Rotation, and Reflection classes are derived classes of MatrixTransform that have special setters which ensure validity of their respective transformations.

property matrix: numpy.ndarray¶: 3x3 array representing matrix transformation

class czone.transform.transform.Translation(shift=None, locked: bool = True, basis_only: bool = False)¶

Bases: czone.transform.transform.BaseTransform

Transformation object that applies translations to Generators and Volumes.

shift¶

Translation vector in 3D space.

Type: np.ndarray

applyTransformation(points)¶

Apply transformation to a collection of points in space.

Parameters: points (np.ndarray) – Nx3 array of points to transform.
Returns: Nx3 array of transformed points.
Return type: np.ndarray

applyTransformation_alg(alg_object)¶

Apply transformation to algebraic object.

Parameters: alg_object (BaseAlgebraic) – Algebraic object to transform.
Returns: Transformed object.
Return type: BaseAlgebraic

applyTransformation_bases(points)¶

Apply transformation to bases of a generator.

Parameters: points (np.ndarray) – 3x3 array of bases from generator voxel.
Returns: transformed 3x3 array of bases.
Return type: np.ndarray

property params¶: Return parameters describing transformation.

property shift¶

czone.transform.transform.rot_align(v: numpy.ndarray, vt: numpy.ndarray) → numpy.ndarray¶

Calculate rotation aligning two sets of ordered vectors.

Parameters

v (np.ndarray) – Nx3 set of vectors
vt (np.ndarray) – Nx3 set of corresponding target vectors

Returns

3x3 rotation matrix

Return type

np.ndarray

czone.transform.transform.rot_v(v, theta)¶

Calculate rotation about an arbitary vector.

Parameters

v (np.ndarray) – axis of rotation
theta (float) – angle of rotation in radians

Returns

3x3 rotation matrix

Return type

np.ndarray

czone.transform.transform.rot_vtv(v: numpy.ndarray, vt: numpy.ndarray) → numpy.ndarray¶

Calculate rotation to align one vector to another.

Parameters

v (np.ndarray) – 1x3 original vector
vt (np.ndarray) – 1x3 target vector into which v is rotated

Returns

3x3 rotation matrix

Return type

np.ndarray

czone.transform.transform.rot_zxz(alpha: float, beta: float, gamma: float, convention='intrinsic') → numpy.ndarray¶

Rotate to orientation described by zxz euler angles.

Calculate rotation matrix as determined by zxz Euler angles. Convention can be either intrinsic, in which rotations are performed on the moving coordinate system XYZ in reference to a fixed coordinate system xyz, or extrinsic, in which the rotations are performed about the fixed coordinate system xyz. Intrisic rotations are performed alpha-beta-gamma, while extrinsic rotations are perfomed gamma-beta-alpha.

Parameters

alpha (float) – rotation around Z / z in radians
beta (float) – rotation around X’/ x in radians
gammma (float) – rotation around Z’’/ z in radians
convention (float) – “intrinsic” or “extrinsic” (default: “intrinsic”)

Returns

3x3 rotation matrix

Return type

np.ndarray

czone.transform.transform.s2s_alignment(M_plane: czone.volume.algebraic.Plane, T_plane: czone.volume.algebraic.Plane, M_point: numpy.ndarray, T_point: numpy.ndarray) → czone.transform.transform.MultiTransform¶

Calculates a transformation aligning two surfaces to eachother.

Aligns two surfaces, represented by algebraic plane objects, such that their normal vectors are anti-parallel. The translational degree of freedom is resolved by minimizing the distance of a point in the target alignment to a transformed point from the moving frame. Returned Transformation sequence is a rotation followed by translation.

Specifically, given a point in the moving frame M_p with plane M and a point in the target frame T_p with plane T, calculate rotation R such that (R @ M.normal ) .* T.normal = -1 and translation vector T_t under the constraint T_t = min T_t ||R @ M_p - T_p||

Parameters

M_plane (Plane) – Moving plane to align to another surface
T_plane (Plane) – Target plane to which M_plane is aligned
M_point (np.ndarray) – Point in moving plane reference frame
T_point (np.ndarray) – Point in target plane reference frame

Returns

Transformation routine represented by surface alignment.

Return type

MultiTransform

Strain Fields¶

class czone.transform.strain.BaseStrain¶

Bases: abc.ABC

Base class for strain fields that act on Generators.

Strain objects can be attached to generators, and transform the coordinates of the atoms post-generation of the supercell. Strain fields apply strain in crystal coordinate system by default.

origin¶

origin with which respect coordinates are strained

Type: np.ndarray

mode¶

“crystal” or “standard”, for straining in crystal coordinates or for straining coordinates with respect to standard R3 orthonromal basis and orientation, respectively

Type: str

bases¶

3x3 array representing generator basis vectors

Type: np.ndarray

abstract apply_strain(points: numpy.ndarray) → numpy.ndarray¶

Apply strain to a collection of points.

Parameters: points (np.ndarray) – Nx3 array of points in space
Returns: Nx3 array of strained points in space
Return type: np.ndarray

property bases¶: “Basis vectors of crystal coordinate system.

property mode¶: Coordinate system for strain application, either ‘crystal’ or ‘standard’.

property origin¶: Origin with respect to which strain is applied.

property origin_type¶

scrape_params(obj: BaseGenerator)¶

Helper method to grab origin and bases from host generator.

Parameters: obj (BaseGenerator) – generator to grab parameters from

class czone.transform.strain.HStrain(matrix=None, origin='generator', mode='crystal')¶

Bases: czone.transform.strain.BaseStrain

Strain class for applying homogeneous strain fields to generators.

HStrain objects can be attached to generators, and transform the coordinates of the atoms post-generation of the supercell via simple strain tensor. HStrain fields apply strain in crystal coordinate system by default.

matrix¶

Matrix representing homogeneous strain tensor. Can be set with 3 (x,y,z), 6 (Voigt notation), or 9 values (as list or 3x3 array).

Type: np.ndarray

apply_strain(points: numpy.ndarray) → numpy.ndarray¶

Apply strain to a collection of points.

Parameters: points (np.ndarray) – Nx3 array of points in space
Returns: Nx3 array of strained points in space
Return type: np.ndarray

property matrix¶: Homogeneous strain tensor.

class czone.transform.strain.IStrain(fun=None, origin='generator', mode='crystal', **kwargs)¶

Bases: czone.transform.strain.BaseStrain

Strain class for applying inhomogenous strain fields to generators.

IStrain objects can be attached to generators, and transform the coordinates of the atoms post-generation of the supercell via arbitrary strain functions. IStrain fields apply strain in crystal coordinate system by default.

User must input a custom strain function; strain functions by default should accept only points as positional arguments and can take any kwargs.

fun_kwargs¶

kwargs to pass to custom strain function

Type: dict

strain_fun¶

strain function F: R3 -> R3 for np.arrays of shape (N,3)->(N,3)

Type: Callable

apply_strain(points: numpy.ndarray) → numpy.ndarray¶

Apply strain to a collection of points.

Parameters: points (np.ndarray) – Nx3 array of points in space
Returns: Nx3 array of strained points in space
Return type: np.ndarray

property fun_kwargs¶: kwargs passed to custom strain function upon application of strain.

property strain_fun¶: Inhomogenous strain function to apply to coordinates.