SBUnitCell#

This class represent a unit cell.

See also

SAMSON SDK: SBDTypeUnitCell

class samson.SBUnitCell(*args, **kwargs)#

Bases: pybind11_object

This class is used to represent a unit cell.

SAMSON API: SBDTypeUnitCell

Overloaded function.

  1. __init__(self: samson.SBUnitCell) -> None

Constructs a unit cell with lengths and angles set to zero.

  1. __init__(self: samson.SBUnitCell, length: samson.SBQuantity.unitsSI, shapeType: samson.SBUnitCell.ShapeType = <ShapeType.Cubic: 1>) -> None

Constructs a cubic, rhombic dodecahedral, or truncated octahedral box with the box length length.

Parameters:

  1. __init__(self: samson.SBUnitCell, lengths: samson.SBPhysicalVector3) -> None

Constructs an orthorhombic unit cell with the box size lengths.

Parameters:

lengths (samson.SBPosition3) – The lengths vector

  1. __init__(self: samson.SBUnitCell, lengths: samson.SBPhysicalVector3, angles: samson.SBPhysicalVector3) -> None

Constructs a triclinic unit cell with the box size length and angles angles (in degrees).

Parameters:

  1. __init__(self: samson.SBUnitCell, a: samson.SBQuantity.unitsSI, b: samson.SBQuantity.unitsSI, c: samson.SBQuantity.unitsSI, alpha: samson.SBQuantity.unitsSI, beta: samson.SBQuantity.unitsSI, gamma: samson.SBQuantity.unitsSI) -> None

Constructs a triclinic unit cell with the box size and angles (in degrees).

Parameters:

  1. __init__(self: samson.SBUnitCell, vectorA: samson.SBPhysicalVector3, vectorB: samson.SBPhysicalVector3, vectorC: samson.SBPhysicalVector3) -> None

Constructs a unit cell based on 3 vectors vectorA, vectorB, vectorC.

Parameters:

  1. __init__(self: samson.SBUnitCell, matrix: samson.SBPhysicalMatrix33) -> None

Constructs a unit cell based on the matrix matrix (triclinic vectors).

Parameters:

matrix (samson.SBMatrix33) – The unit cell matrix

class Periodicity(self: samson.SBUnitCell.Periodicity, value: int)#

Bases: pybind11_object

Members:

NoPeriodicity : No periodic axis

X : Periodic along the a / x axis

Y : Periodic along the b / y axis

Z : Periodic along the c / z axis

XY : Periodic along the a / x and b / y axes

XZ : Periodic along the a / x and c / z axes

YZ : Periodic along the b / y and c / z axes

XYZ : Periodic along the three axes

NoPeriodicity = <Periodicity.NoPeriodicity: 0>#
X = <Periodicity.X: 1>#
XY = <Periodicity.XY: 3>#
XYZ = <Periodicity.XYZ: 7>#
XZ = <Periodicity.XZ: 5>#
Y = <Periodicity.Y: 2>#
YZ = <Periodicity.YZ: 6>#
Z = <Periodicity.Z: 4>#
property name#
property value#
class ShapeType(self: samson.SBUnitCell.ShapeType, value: int)#

Bases: pybind11_object

Members:

Undefined : Undefined or infinite unit cell

Infinite : Undefined or infinite unit cell

Cubic : A cubic unit cell

Orthorhombic : An orthorhombic unit cell

Triclinic : A triclinic unit cell

Dodecahedron : A rhombic dodecahedron unit cell

RhombicDodecahedron : A rhombic dodecahedron unit cell

Octahedron : A truncated octahedron unit cell

TruncatedOctahedron : A truncated octahedron unit cell

Cubic = <ShapeType.Cubic: 1>#
Dodecahedron = <ShapeType.Dodecahedron: 4>#
Infinite = <ShapeType.Undefined: 0>#
Octahedron = <ShapeType.Octahedron: 5>#
Orthorhombic = <ShapeType.Orthorhombic: 2>#
RhombicDodecahedron = <ShapeType.Dodecahedron: 4>#
Triclinic = <ShapeType.Triclinic: 3>#
TruncatedOctahedron = <ShapeType.Octahedron: 5>#
Undefined = <ShapeType.Undefined: 0>#
property name#
property value#
canUseMinimumImageConvention(self: samson.SBUnitCell, cutoff: samson.SBQuantity.unitsSI) → bool#

Returns whether minimum-image convention is valid for a cutoff.

Parameters:

cutoff (samson.SBQuantity.unitsSI) – Cutoff distance used in pair interactions.

Returns:

True when minimum-image convention can be safely applied.

Return type:

bool

checkTriclinicConditions(self: samson.SBUnitCell) → tuple#

Returns True if the box described by the unit cell satisfies a set of triclinic box conditions.

Returns:

A tuple with a boolean result and an error string, in case there is an error

Return type:

Tuple(bool, str)

static checkTriclinicConditionsForMatrix(matrix: samson.SBPhysicalMatrix33) → tuple#

Returns true if the box described by the matrix matrix satisfies a set of triclinic box conditions).

Parameters:

matrix (samson.SBMatrix33) – The matrix

Returns:

A tuple with a boolean result and an error string, in case there is an error

Return type:

Tuple(bool, str)

contains(self: samson.SBUnitCell, position: samson.SBPhysicalVector3) → bool#

Returns True if and only if position belongs to the primary unit cell

static createMatrix(lengths: samson.SBPhysicalVector3, angles: samson.SBPhysicalVector3) → samson.SBPhysicalMatrix33#

Returns box matrix based on lengths lengths and angles angles.

Parameters:
getAngles(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the angles of the unit cell

static getAnglesFromMatrix(matrix: samson.SBPhysicalMatrix33) → samson.SBPhysicalVector3#

Returns box angles based on the matrix matrix.

Parameters:

matrix (samson.SBMatrix33) – The matrix

getCartesianCoordinates(self: samson.SBUnitCell, fractionalCoordinates: samson.SBPhysicalVector3) → samson.SBPhysicalVector3#

Returns Cartesian coordinates associated with fractional coordinates.

Parameters:

fractionalCoordinates (samson.SBVector3) – Fractional coordinates in the unit-cell basis.

Returns:

Cartesian position in length units.

Return type:

samson.SBPosition3

getCenter(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the center of the primary unit cell.

Returns:

The center of the primary unit cell

Return type:

samson.SBPosition3

getCenterOfTriclinicCell(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the center of the triclinic unit cell.

Returns:

The center of the triclinic unit cell

Return type:

samson.SBPosition3

getFractionalCoordinates(self: samson.SBUnitCell, position: samson.SBPhysicalVector3) → samson.SBPhysicalVector3#

Returns fractional coordinates associated with a Cartesian position.

Parameters:

position (samson.SBPosition3) – Position in Cartesian length units.

Returns:

Fractional coordinates in the unit-cell basis.

Return type:

samson.SBVector3

getInverseLengths(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the inverse lengths of the unit cell

getInverseMatrix(self: samson.SBUnitCell) → samson.SBPhysicalMatrix33#

Returns the inverse matrix of the unit cell

getLengths(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the lengths of the unit cell

static getLengthsFromMatrix(matrix: samson.SBPhysicalMatrix33) → samson.SBPhysicalVector3#

Returns box length based on the matrix matrix.

Parameters:

matrix (samson.SBMatrix33) – The matrix

getMatrix(self: samson.SBUnitCell) → samson.SBPhysicalMatrix33#

Returns the matrix of the unit cell

getMinimumImageDisplacement(self: samson.SBUnitCell, position1: samson.SBPhysicalVector3, position2: samson.SBPhysicalVector3) → samson.SBPhysicalVector3#

Returns minimum-image displacement from position1 to position2.

Parameters:
Returns:

Minimum-image displacement vector.

Return type:

samson.SBLength3

getMinimumImageDistance(self: samson.SBUnitCell, position1: samson.SBPhysicalVector3, position2: samson.SBPhysicalVector3) → samson.SBQuantity.unitsSI#

Returns minimum-image distance between two Cartesian positions.

Parameters:
Returns:

Minimum-image distance.

Return type:

samson.SBQuantity.unitsSI

getMinimumImageSquaredDistance(self: samson.SBUnitCell, position1: samson.SBPhysicalVector3, position2: samson.SBPhysicalVector3) → samson.SBQuantity.unitsSI#

Returns minimum-image squared distance between two Cartesian positions.

Parameters:
Returns:

Squared minimum-image distance.

Return type:

samson.SBQuantity.unitsSI

getNearestPeriodicImage(self: samson.SBUnitCell, position: samson.SBPhysicalVector3, referencePosition: samson.SBPhysicalVector3) → samson.SBPhysicalVector3#

Returns the periodic image of position nearest to referencePosition.

Parameters:
Returns:

Nearest periodic image of position.

Return type:

samson.SBPosition3

getOrigin(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the origin of the unit cell

getReciprocalMatrix(self: samson.SBUnitCell, include2Pi: bool = False) → samson.SBPhysicalMatrix33#

Returns the reciprocal lattice matrix.

Parameters:

include2Pi (bool, default=False) – If True, includes the factor 2*pi in reciprocal vectors.

Returns:

Reciprocal matrix in inverse length units.

Return type:

samson.SBMatrix33

static getShapeType(matrix: samson.SBPhysicalMatrix33) → samson.SBUnitCell.ShapeType#

Returns the unit cell’s shape type based on the box matrix matrix.

Parameters:

matrix (samson.SBMatrix33) – The matrix

static getShapeTypeString(shapeType: samson.SBUnitCell.ShapeType) → str#

Returns the name of the unit cell’s shape type shapeType

Parameters:

shapeType (samson.SBUnitCell.ShapeType) – The shape type

getVectorA(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the first lattice vector

getVectorB(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the second lattice vector

getVectorC(self: samson.SBUnitCell) → samson.SBPhysicalVector3#

Returns the third lattice vector

getVolume(self: samson.SBUnitCell) → samson.SBQuantity.unitsSI#

Returns the volume of the unit cell

Returns:

The volume of the unit cell

Return type:

samson.SBQuantity.unitSI

getWrappedFractionalCoordinates(self: samson.SBUnitCell, fractionalCoordinates: samson.SBPhysicalVector3) → samson.SBPhysicalVector3#

Wraps fractional coordinates along periodic axes.

Parameters:

fractionalCoordinates (samson.SBVector3) – Input fractional coordinates.

Returns:

Wrapped fractional coordinates.

Return type:

samson.SBVector3

getWrappedPosition(self: samson.SBUnitCell, position: samson.SBPhysicalVector3) → samson.SBPhysicalVector3#

Returns the wrapped Cartesian position for periodic axes.

Parameters:

position (samson.SBPosition3) – Input Cartesian position.

Returns:

Wrapped position in Cartesian coordinates.

Return type:

samson.SBPosition3

isFinite(self: samson.SBUnitCell) → bool#

Returns True if and only if the unit cell is finite

isPeriodic(self: samson.SBUnitCell) → bool#

Returns True if and only if the unit cell is periodic along at least one axis

isPeriodicX(self: samson.SBUnitCell) → bool#

Returns True if and only if the unit cell is periodic along the a / x axis

isPeriodicY(self: samson.SBUnitCell) → bool#

Returns True if and only if the unit cell is periodic along the b / y axis

isPeriodicZ(self: samson.SBUnitCell) → bool#

Returns True if and only if the unit cell is periodic along the c / z axis

setOrigin(self: samson.SBUnitCell, origin: samson.SBPhysicalVector3) → None#

Sets the origin of the unit cell

Parameters:

origin (samson.SBPosition3) – The length vector

toPythonCode(self: samson.SBUnitCell) → str#

Returns the string representation that can reconstruct this object in Python

Cubic = <ShapeType.Cubic: 1>#
Dodecahedron = <ShapeType.Dodecahedron: 4>#
Infinite = <ShapeType.Undefined: 0>#
NoPeriodicity = <Periodicity.NoPeriodicity: 0>#
Octahedron = <ShapeType.Octahedron: 5>#
Orthorhombic = <ShapeType.Orthorhombic: 2>#
RhombicDodecahedron = <ShapeType.Dodecahedron: 4>#
Triclinic = <ShapeType.Triclinic: 3>#
TruncatedOctahedron = <ShapeType.Octahedron: 5>#
Undefined = <ShapeType.Undefined: 0>#
X = <Periodicity.X: 1>#
XY = <Periodicity.XY: 3>#
XYZ = <Periodicity.XYZ: 7>#
XZ = <Periodicity.XZ: 5>#
Y = <Periodicity.Y: 2>#
YZ = <Periodicity.YZ: 6>#
Z = <Periodicity.Z: 4>#
property periodicity#

The periodicity mask of the unit cell

property shapeType#

The unit cell’s shape type

property shapeTypeString#

Returns the name of the unit cell’s shape type