1. API
  2. Chemistry

Chemistry

This module is the outcome of a student summer project and provides ways to identify symmetry groups of molecules.

Molecule

class replab.Molecule(name, coords, symbols)

Bases: replab.Str

Gives information about a molecule

References

Beruski, O., Vidal, L. N. (2013). Algorithms for computer detection of symmetry elements in molecular systems. Journal of Computational Chemistry, Volume 35, Issue 4. https://doi-org/10.1002/jcc.23493

Vallance, C. (2020). Symmetry Classification of Molecules: Point Groups. Chemistry LibreTexts. https://chem.libretexts.org

Class members list

Properties

  • coords – the coordinates of atoms in the molecule (coords are sorted by increasing values)

  • id – identification of molecular point group through an axis on coordinates

  • masses – masses of atoms corresponding to coordinates

  • name – name of replab.Molecule object

  • natoms – total number of atoms

  • symbols – symbols of atoms corresponding to coordinates

Prettyprinting

  • additionalFields – Returns the name/value pairs corresponding to additional fields to be printed

  • disp – Standard MATLAB/Octave display method

  • headerStr – Tiny single line description of the current object type

  • hiddenFields – Returns the names of the fields that are not printed as a row vector

  • longStr – Multi-line description of the current object

  • shortStr – Single line text description of the current object

General

  • ImproperRotationAction – Finds action of a rotation by 2pi/k then a reflection on the molecule

  • Molecule – Creates a molecule object

  • ReflectionAction – Finds action of a reflection by 2pi/k on the molecule

  • RotationAction – Finds action of a rotation by 2pi/k on the molecule

  • fromAtoms – Creates a molecule object atomic information

  • fromFile – Creates a molecule object from a file

  • getMasses – Get the atomic masses for the atom represented by each symbol

  • readXYZ – Reads the coordinates and atomic symbols from an xyz file

Inherited elements

additionalFields(self)

Documentation in replab.Str.additionalFields()

disp(self)

Documentation in replab.Str.disp()

headerStr(self)

Documentation in replab.Str.headerStr()

hiddenFields(self)

Documentation in replab.Str.hiddenFields()

longStr(self, maxRows, maxColumns)

Documentation in replab.Str.longStr()

shortStr(self, maxColumns)

Documentation in replab.Str.shortStr()

Own members

coords

the coordinates of atoms in the molecule (coords are sorted by increasing values)

Type

double(3, natoms)

id

identification of molecular point group through an axis on coordinates

Type

replab.IdentifyPointGroup

masses

masses of atoms corresponding to coordinates

Type

double(1, natoms)

name

name of replab.Molecule object

Type

charstring

natoms

total number of atoms

Type

integer

symbols

symbols of atoms corresponding to coordinates

Type

cell(1, natoms) of charstring

ImproperRotationAction(self, k, axis, ndec)

Finds action of a rotation by 2pi/k then a reflection on the molecule

Parameters

  • k (integer) – rotation by angle 2*pi/k

  • axis (double(1, 3)) – rotation axis and normal of reflection plane

  • ndec (integer) (optional) – the number of decimals to round for equality

Molecule(name, coords, symbols)

Creates a molecule object

Convention: automatically sort coordinates in ascending order rounding to 2 decimal places for equality

Parameters

  • coords (double(3, natoms)) – a set of coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols of coordinates

  • ndec (integer) – number of decimal places to round when checking for equality

ReflectionAction(self, normal, ndec)

Finds action of a reflection by 2pi/k on the molecule

Parameters

  • normal (double(1, 3)) – normal of reflection plane

  • ndec (integer) (optional) – the number of decimals to round for equality

RotationAction(self, k, axis, ndec)

Finds action of a rotation by 2pi/k on the molecule

Parameters

  • k (integer) – rotation by angle 2*pi/k

  • axis (double(1, 3)) – axis about which we rotate molecule

  • ndec (integer) (optional) – the number of decimals to round for equality

static fromAtoms(coords, symbols, atomicSymbols, atomicMasses)

Creates a molecule object atomic information

Parameters

  • coords (double(3, natoms)) – atomic coordinates (can be unsorted)

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • atomicSymbols (optional cell(1, *) of charstring) – atomic symbols of masses to replace or add to stored masses

  • atomicMasses (optional cell(1, *) of double) – atomic masses corresponding to atomicSymbols

Returns

molecule object

Return type

mol (replab.Molecule)

static fromFile(filename, atomicSymbols, atomicMasses)

Creates a molecule object from a file

Parameters

  • filename (charstring) – name of file with molecular information

  • atomicSymbols (optional cell(1, *) of charstring) – atomic symbols of masses to replace or add to stored masses

  • atomicMasses (optional cell(1, *) of double) – atomic masses corresponding to atomicSymbols

Returns

molecule object

Return type

mol (replab.Molecule)

static getMasses(symbols, atomicSymbols, atomicMasses)

Get the atomic masses for the atom represented by each symbol

Parameters

  • symbols (cell(1, natoms) of charstring) – symbols of atoms

  • atomicSymbols (optional cell(1, *) of charstring) – atomic symbols of masses to replace or add to stored masses

  • atomicMasses (optional cell(1, *) of double) – atomic masses corresponding to atomicSymbols

Returns

masses (cell(1, natoms) of double): masses of atoms

static readXYZ(filename)

Reads the coordinates and atomic symbols from an xyz file

Parameters

filename (charstring) – name and location of xyz file

Returns

coords (double(3, natoms)): coordinates from xyz file symbols (cell(1, natoms) of charstring): symbols of atoms from xyz file

IdentifyPointGroup

class replab.IdentifyPointGroup(coords, symbols, masses, ndec)

Bases: replab.Str

Gives information about a molecule

References

Beruski, O., Vidal, L. N. (2013). Algorithms for computer detection of symmetry elements in molecular systems. Journal of Computational Chemistry, Volume 35, Issue 4. https://doi-org/10.1002/jcc.23493

Vallance, C. (2020). Symmetry Classification of Molecules: Point Groups. Chemistry LibreTexts. https://chem.libretexts.org

Class members list

Properties

  • ndec – number of decimal places to check for equality

  • ord – highest order rotation of the molecule that preserves symmetry

  • pointGroup – characters representing the point group

  • principalAxis – principal axis of rotation of the molecule

  • table – the character table for the molecule’s point group

Prettyprinting

  • additionalFields – Returns the name/value pairs corresponding to additional fields to be printed

  • disp – Standard MATLAB/Octave display method

  • headerStr – Tiny single line description of the current object type

  • hiddenFields – Returns the names of the fields that are not printed as a row vector

  • longStr – Multi-line description of the current object

  • shortStr – Single line text description of the current object

General

  • IdentifyPointGroup – Creates a molecule object

  • ImproperRotation – Apply rotation of 2*pi/k and then reflection through rotation plane

  • InertiaTensor – calculates the inertia tensor for a group of atoms

  • Reflection – Reflect coords through a plane with a given normal

  • Rotation – Apply rotation of 2*pi/k to coords about an axis

  • checkPlanar – Determines if molecule is planar

  • coordsEqual – Checks whether a new set of coordinates is equivalent to original ones

  • determineLowSymmetry – Determines point group on molecules without Cn axis

  • determineSphericalGroup – Determine spherical group of the molecule

  • distanceMatrix – Determine the distance matrix of the molecules

  • findC2Axes – Determines whether molecule has a C2 axis and returns first one found

  • findCharacterTable – Determines the character table of a molecule with a certain point group

  • findCnAxes – Find whether there are multiple higher order rotation axes

  • findDihedralMirrorPlanes – Determines number of dihedral mirror planes in the molecule

  • findPerpendicularAxes – Finds all C2 axes perpendicular to the principal axis

  • findPointGroup – Determine the point group of molecule by symmetry operation flowchart

  • findReflections – Finds reflection planes in the molecule

  • findRotations – Determine the rotation order and axis for a group of atoms

  • groupAtoms – Finds atoms of same type with same distances

  • sortCoords – Sorts coordinates in ascending order

Inherited elements

additionalFields(self)

Documentation in replab.Str.additionalFields()

disp(self)

Documentation in replab.Str.disp()

headerStr(self)

Documentation in replab.Str.headerStr()

hiddenFields(self)

Documentation in replab.Str.hiddenFields()

longStr(self, maxRows, maxColumns)

Documentation in replab.Str.longStr()

shortStr(self, maxColumns)

Documentation in replab.Str.shortStr()

Own members

ndec

number of decimal places to check for equality

Type

integer

ord

highest order rotation of the molecule that preserves symmetry

Type

integer

pointGroup

characters representing the point group

Type

charstring

principalAxis

principal axis of rotation of the molecule

Type

double(3, 1)

table

the character table for the molecule’s point group

Type

ComplexCharacterTable

IdentifyPointGroup(coords, symbols, masses, ndec)

Creates a molecule object

Parameters

  • coords (double(3, natoms)) – a set of coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols of coordinates

  • masses (cell(1, natoms) of charstring) – atomic masses of coordinates

  • ndec (integer) – number of decimal places to round when checking for equality

static ImproperRotation(k, axis, coords, symbols, ndec)

Apply rotation of 2*pi/k and then reflection through rotation plane

Parameters

  • k (integer) – number of rotations then reflection which should keep coordinates the same

  • axis (double(1, 3)) – axis about which to rotate coordinates and normal for reflection plane

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols of coords

  • ndec (integer) – number of decimals to round

Returns

whether reflection keeps coordinates the same inds (integer(1, natoms)): action of improper rotation on coordinates

Return type

ok (logical)

static InertiaTensor(coords, masses)

calculates the inertia tensor for a group of atoms

Parameters

  • coords (double(3, *)) – coordinates of atoms

  • masses (double(1, *)) – masses of atoms

Returns

inertia tensor of given coordinates rcm (double(1, 3)): center of mass vector

Return type

I (double(3, 3))

static Reflection(normal, coords, symbols, ndec)

Reflect coords through a plane with a given normal

Parameters

  • normal (double(1, 3)) – normal of plane through which to reflect

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols of coords

  • ndec (integer) – number of decimals to round

Returns

whether reflection keeps coordinates the same inds (integer(1, natoms)): action of reflection on coordinates

Return type

ok (logical)

static Rotation(k, axis, coords, symbols, ndec)

Apply rotation of 2*pi/k to coords about an axis

Parameters

  • k (integer) – number of rotations which should keep coordinates the same

  • axis (double(1, 3)) – axis about which to rotate coordinates

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols of coords

  • ndec (integer) – number of decimals to round

Returns

whether reflection keeps coordinates the same inds (integer(1, natoms)): action of rotation on coordinates

Return type

ok (logical)

checkPlanar(self, coords)

Determines if molecule is planar

Parameters

coords (double(3, natoms)) – atomic coordinates

Returns

whether molecule is planar normal (double(3, 1)): normal of plane formed by first three atoms

Return type

planar (logical)

static coordsEqual(old_coords, new_coords, symbols, ndec)

Checks whether a new set of coordinates is equivalent to original ones

Convention: assumes self.coords is already sorted

Parameters

  • old_coords (double(3, natoms)) – reference coordinates

  • new_coords (double(3, natoms)) – new set of coordinates to check for equality

  • symbols (cell(1, natoms) of charstring) – molecular symbols of coordinates

  • ndec (integer) – number of decimal places to round for equality testing

Returns

whether new coordinates are equal to self.coords inds (integer(1, natoms)): vector that will sort old_coords to new_coords

Return type

ok (logical)

determineLowSymmetry(self, coords, symbols, SEAs)

Determines point group on molecules without Cn axis

Parameters

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • SEAs (cell(1, *) of double(*, 1)) – cell array of vectors of the indices of similar atoms

determineSphericalGroup(self, coords, symbols, SEAs)

Determine spherical group of the molecule

Determines whether molecule has tetrahedral, octahedral, or icosahedral symmetry and assigns point group

Parameters

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • SEAs (cell(1, *) of double(*, 1)) – cell array of vectors of the indices of similar atoms

Check number of C5 axes greater than 2

static distanceMatrix(coords)

Determine the distance matrix of the molecules

Convention: entries of row i are the distances of atom i from

atoms 1, 2, …, natoms so D(i, i) = 0

Parameters

coords (double(3, natoms)) – molecular coordinates

Returns

distance matrix

Return type

D (double(natoms, natoms))

findC2Axes(self, coords, symbols, SEAs, rcm)

Determines whether molecule has a C2 axis and returns first one found

Parameters

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • SEAs (cell(1, *) of double(*, 1)) – cell array of vectors of the indices of similar atoms

  • rcm (double(1, 3)) – centre of mass vector

Returns

whether molecule contains C2 axis axis (double(1, 3)): axis of C2 rotation

Return type

ok (logical)

static findCharacterTable(pointGroup)

Determines the character table of a molecule with a certain point group

Parameters

pointGroup (charstring) – name of point group (i.e. C3v or D4d)

Returns

character table of point group

Return type

ct (replab.CharacterTable)

findCnAxes(self, n, max_rotations, coords, symbols, SEAs)

Find whether there are multiple higher order rotation axes

Parameters

  • n (integer) – order of rotation

  • max_rotations (integer) – check whether there are at least this many rotation axes of order n

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • SEAs (cell(1,*) of double(*,1)) – cell array of vectors of the indices of similar atoms

Returns

ok (logical): whether there are at least max_rotations rotation axes of order n

findDihedralMirrorPlanes(self, coords, symbols, perpAxes)

Determines number of dihedral mirror planes in the molecule

Parameters

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • perpAxes (double(3, *)) – axes of rotation perpendicular to principal axis

Returns

number of dihedral mirror planes

Return type

nsigmad (integer)

findPerpendicularAxes(self, axes, ords, rcm, SEAs, coords, symbols)

Finds all C2 axes perpendicular to the principal axis

Parameters

  • axes (double(3, *)) – any already known axes

  • ords (integer(1, *)) – orders of known axes of rotation

  • rcm (double(1, 3)) – centre of mass vector

  • SEAs (cell(1, *) of double(*, 1)) – cell array of vectors of the indices of similar atoms

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

Returns

number of perpendicular axes perpAxes (double(3, *)): axes of rotation perpendicular to principal axis

Return type

ind (integer)

findPointGroup(self, coords, symbols, masses, SEAs)

Determine the point group of molecule by symmetry operation flowchart

Algorithm from Beruski and flowchart from Vallance

Parameters

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • masses (double(1, natoms)) – atomic masses

  • SEAs (cell(1, *) of double(*, 1)) – cell array of vectors of the indices of similar atoms

findReflections(self, coords, symbols, SEAs)

Finds reflection planes in the molecule

Parameters

  • coords (double(3, natoms)) – atomic coordinates

  • symbols (cell(1, natoms) of charstring) – atomic symbols

  • SEAs (cell(1, *) of double(*, 1)) – cell array of vectors of the indices of similar atoms

Returns

whether there is a horizontal reflection plane nv (integer): number of vertical reflection planes

Return type

horizontal (logical)

findRotations(self, coords, symbols, masses, inds)

Determine the rotation order and axis for a group of atoms

From Beruski

Parameters

  • coords (double(3, natoms)) – coordinates of atoms

  • symbols (cell(1, natoms) of charstring) – atomic symbols of coordinates

  • masses (cell(1, natoms) of charstring) – atomic masses of coordinates

  • inds (integer(1, *)) – indices of group of atoms whose rotations we find

Returns

highest order rotation possible axis (double(1, 3)): axis of rotation

Return type

order (integer)

static groupAtoms(D, ndec)

Finds atoms of same type with same distances

Parameters

  • D (double(natoms, natoms)) – distance matrix

  • ndec (integer) – number of decimal places to test equality

Returns

SEAs (cell(1, *) of integer(1, *)): array of lists of same atoms with same distances

static sortCoords(coords, ndec)

Sorts coordinates in ascending order

Convention: atoms are sorted by increasing x-coordinate, then

y-coordinate, and then z-coordinate

Parameters

  • coords (double(3, natoms)) – set of coordinates

  • ndec (integer) – number of decimals to check equality

Returns

sorted coordinates i1 (integer(1, natoms)): indices that revert coords to original order

Return type

coords (double(3, natoms))

© Copyright 2018-2022, Denis Rosset, Jean-Daniel Bancal and collaborators. Created using Sphinx.