build

libra_py.build.add_atom_to_system(syst, coords, MaxCoords, Nx, Ny, Nz, a, b, c, shift, elt, mass, scl, max_coord, rnd, inp_units=0)[source]

This function adds an atom and its periordic replicas to a (chemical) System object. The momenta of the atoms are also initialized and are drawn from the normal distribution along each of the directions (Cartesian x, y, and z), no center of mass momentum subtraction is made however. This is good for constructing lattices.

Parameters

  • syst (System object) – the chemical system to which we are going to add the atoms

  • coords (list of VECTORs) – coordinates of all atoms in a system

  • MaxCoords (list of ints) – Maximal coordination number of each atom

  • Nx (int) – how many times to replicate the atom along a direction

  • Ny (int) – how many times to replicate the atom along b direction

  • Nz (int) – how many times to replicate the atom along c direction

  • a (VECTOR) – the periodicity translation vector along the a direction [Bohr]

  • b (VECTOR) – the periodicity translation vector along the b direction [Bohr]

  • c (VECTOR) – the periodicity translation vector along the c direction [Bohr]

  • shift (VECTOR) – essentially a coordinate of the atom in the unit cell [Bohr]

  • elt (string) – Element name

  • mass (double) – mass of the atom [a.u. of mass, 1 = mass of an electron]

  • scl (VECTOR) – momentum rescaling factors along each direction [a.u. of momentum]

  • max_coord (int) – maximal coordination number of the added atom allowed

  • rnd (Random) – an instance of the random number generator class

  • inp_units (int) –

    defines the units of variables stored in shift, a,b, and c

    • 0 - Bohr ( default )

    • 1 - Angstrom

Returns

But the following objects will be updated:

  • syst - the new atoms will be added

  • coords - the new coordinates will be added

  • MaxCoords - the maximal coordination numbers for new atoms will be added

Return type

None

libra_py.build.add_atoms_to_system(syst, L, R, scl, mass, univ_file)[source]
Parameters

  • syst (System object) – the chemical system to which we are going to add the atoms

  • L (list of strings) – element names

  • R (list of VECTOR objects) – coordinates of the particles [ Bohrs ]

  • scl (VECTOR) – momentum rescaling factors along each direction [a.u. of momentum]

  • mass (list of doubles) – atomic masses [a.u. of mass]

  • univ_file (string) – name of the file that contains the Universe properties

Returns

but adds new atoms to the System object, modifies the syst variable

Return type

None

libra_py.build.crop_sphere_xyz(infile, outfile, Rcut)[source]

This function reads an .xyz file with the geometry, cuts the atoms that are outside of a sphere of given radius and then prints out the remaining atoms to a new file in .xyz format

Parameters

  • infile (string) – the name of the .xyz file that contains the original coordinates

  • outfile (string) – the name of the new .xyz file to create (with the cropped geometry)

  • Rcut (double) – the radius of the sphere from the center of the QD [ same units as used in infile ]

Returns

(lab, coords), where:

  • lab ( list of N strings ): the labels of all remaining atoms

  • coords ( list of N VECTORs ): the coordinates of all remaining atoms

Return type

tuple

Example

The example below read in a unit cell of Si (8 atoms), replicates in 5 times in x, y, and z directions (so we get a 6 x 6 x 6 supercell). The resulting structure is written to the “cube10.xyz” file. Then the file cube10.xyz is read and cropped to make a sphere of 5 Angstrom. The resulting system is then printed out to the “qd_5.xyz” file.

>>> a = [     5.4307100000000000,    0.0000000000000000,    0.0000000000000000 ]
>>> b = [     0.0000000000000000,    5.4307100000000000,    0.0000000000000000 ]
>>> c = [     0.0000000000000000,    0.0000000000000000,    5.4307100000000000 ]
>>> generate_replicas_xyz(a, b, c, 5, 5, 5 , "Si.xyz", "cube10.xyz")
>>> crop_sphere_xyz("cube10.xyz", "qd_5.xyz", 5.0)
libra_py.build.crop_sphere_xyz2(L, R, Rcut)[source]

This function removes all atoms that are outside of a sphere of Rcut radius. The sphere is centered on GEOMETRIC center of the system

Parameters

  • L (list of strings) – element names, this list will be trimmed accordingly

  • R (VECTORList or list of VECTOR objects) – coordinates of the particles [ Bohr ]

  • Rcut (double) – the radius of the sphere from the center of the QD [ Bohrs ]

Returns

(lab, coords), where:

  • lab ( list of N strings ): the labels of all remaining atoms

  • coords ( list of N VECTORs ): the coordinates of all remaining atoms

Return type

tuple

libra_py.build.crop_sphere_xyz3(L, R, Rcut, pairs, new_L)[source]

This function removes all atoms that are outside of a sphere of Rcut radius. The sphere is centered on GEOMETRIC center of the system

Parameters

  • L (list of strings) – element names, this list will be trimmed accordingly

  • R (VECTORList or list of VECTOR objects) – coordinates of the particles [ Bohr ]

  • Rcut (double) – the radius of the sphere from the center of the QD [ Bohrs ]

  • pairs (list of [int, int, VECTOR, VECTOR] lists) – integers describe the indices for the connected atoms, the VECTORs describe the translation vector by which the atoms should be translated before considering connected (e.g. for periodic boundary conditions) these VECTOR objects are not used in the present function, but the format is kept such that the output of other functions could be used in this function.

  • ( dictionary(string (new_L) – string) ): a map containing the key-value pairs, where the key string corresponds to the label of the atom that is inside the cropped sphere. The value string corresponds to the new label of the atom outside the sphere. The function will use the original connectivity information to decide how to cap the dangling bonds formed at cropping. So, if the atom A is connected to atom B, atom A is inside of the sphere and B is outside the sphere. The vaule element will become a new label for atom B, if the key element corresponds to atom type A.

Returns

(lab, coords), where:

  • lab ( list of N strings ): the labels of all remaining atoms

  • coords ( list of N VECTORs ): the coordinates of all remaining atoms

Return type

tuple

libra_py.build.generate_replicas_xyz(tv1, tv2, tv3, rep1, rep2, rep3, filename, outfile, inp_units=0, out_units=0)[source]

This function generates a lattice of coordinates and an array of corresponding atomic labels by replicating a given set of labeled atoms periodically in up to 3 dimensions (with a variable number of replicas in each direction). This function first reads in the atomic coordinates (supplied in an .xyz format) and then writes the resulting data into another file (.xyz format)

Parameters

  • tv1 (VECTOR) – translation vector in direction 1 [defined by inp_units]

  • tv2 (VECTOR) – translation vector in direction 2 [defined by inp_units]

  • tv3 (VECTOR) – translation vector in direction 3 [defined by inp_units]

  • rep1 (int) – the number of replications along the vector tv1, not counting the original cell

  • rep2 (int) – the number of replications along the vector tv2, not counting the original cell

  • rep3 (int) – the number of replications along the vector tv3, not counting the original cell

  • filename (string) – the name of the file containing input coordinates (original unit cell)

  • outfile (string) – the name of the file where the resulting lattice atoms will be written

  • inp_units (int) –

    defines the units of variables in filename, tv1, tv2, and tv3:

    • 0 - Bohr ( default )

    • 1 - Angstrom

  • out_units (int) –

    defines the units of the coordinates written to outfile

    • 0 - Bohr ( default )

    • 1 - Angstrom

Returns

but a new .xyz file will be printed out

Return type

None

Example

The example below read in a unit cell of Si (8 atoms), replicates in 5 times in x, y, and z directions (so we get a 6 x 6 x 6 supercell). The resulting structure is written to the “cube10.xyz” file

>>> a = [     5.4307100000000000,    0.0000000000000000,    0.0000000000000000 ]
>>> b = [     0.0000000000000000,    5.4307100000000000,    0.0000000000000000 ]
>>> c = [     0.0000000000000000,    0.0000000000000000,    5.4307100000000000 ]
>>> generate_replicas_xyz(a, b, c, 5, 5, 5 , "Si.xyz", "cube10.xyz")
libra_py.build.generate_replicas_xyz2(L, R, tv1, tv2, tv3, Nx, Ny, Nz, inp_units=0, out_units=0)[source]

This function generates a lattice of coordinates and an array of corresponding atomic labels by replicating a given set of labeled atoms periodically in up to 3 dimensions (with a variable number of replicas in each direction)

Parameters

  • L (list of strings) – atomis labels

  • R (list of VECTOR objects) – initial atomic coords [defined by inp_units]

  • tv1 (VECTOR) – translation vector in direction 1 [defined by inp_units]

  • tv2 (VECTOR) – translation vector in direction 2 [defined by inp_units]

  • tv3 (VECTOR) – translation vector in direction 3 [defined by inp_units]

  • Nx (int) – the number of replications along the vector tv1, not counting the original cell

  • Ny (int) – the number of replications along the vector tv2, not counting the original cell

  • Nz (int) – the number of replications along the vector tv3, not counting the original cell

  • inp_units (int) –

    defines the units of variables R, tv1, tv2, and tv3:

    • 0 - Bohr ( default )

    • 1 - Angstrom

  • out_units (int) –

    defines the units of the coordinates returned:

    • 0 - Bohr ( default )

    • 1 - Angstrom

Returns

(lab, newR), where:

  • lab ( list of N strings ): the labels of all atoms and their corresponding replicas

  • newR ( list of N VECTORs ): the coordinates of all replicated atoms [defined by out_units]

Return type

tuple

libra_py.build.make_system(R, E, step, U)[source]

This function creates a chemical system (System) oject from the corrdinates and atom labels provided. All atoms of the system are made into a single group.

Parameters

  • R (MATRIX(ndof, nsteps)) – molecular coordinates at different times The convention is R.get(dof, step) is the coordinate of the `dof`-th degree of freedom and `step`-th timestep. Note: ndof = 3*natoms. [ a.u. = Bohrs ]

  • E (list of `natoms` strings) – atomic labels

  • step (int) – selector of the timestep for which we want to construct the system

  • U (Universe object) – Universe

Returns

the chemical system with the coordinates of all atoms at a given time. All atoms

are grouped together into a single rigid body

Return type

System

libra_py.build.make_xyz(L, R, inp_units=0, out_units=1)[source]

Convert atomic labels and coordinates to a string formatted according to xyz

Parameters

  • L (list of N strings) – the labels of N atoms in the system

  • R (list of N VECTORs) – the coordinates of N atoms in the system

  • inp_units (int) –

    defines the units of variables stored in R:

    • 0 - Bohr ( default )

    • 1 - Angstrom

  • out_units (int) –

    defines the units of the coordinates written in xyz file:

    • 0 - Bohr

    • 1 - Angstrom ( default )

Returns

a string representing the xyz file of the system

Return type

string

libra_py.build.make_xyz_mat(E, R)[source]

This function returns a string in the xyz format with X, Y, Z where X,Y,Z are the coordinates

Parameters

  • E (list of ndof/3 string) – atom names (elements) of all atoms

  • R (MATRIX(ndof x nsteps-1)) – coordinates of all DOFs for all mid-timesteps

Returns

A string representing an xyz file

Return type

string

libra_py.build.read_xyz(filename, inp_units=1, out_units=0)[source]

Read an xyz file (single structure)

Parameters

  • filename (string) – the name of the xyz file to read

  • inp_units (int) –

    defines the coordinates’ units in the input file:

    • 0 - Bohr

    • 1 - Angstrom ( default )

  • out_units (int) –

    defines the output coordinates’ units:

    • 0 - Bohr ( default )

    • 1 - Angstrom

Returns

(L, coords), where:

  • L ( list of N strings ): the labels of N atoms read

  • coords ( list of N VECTORs ): the coordinates of N atoms read [defined by out_units]

Return type

tuple

libra_py.build.read_xyz_crystal(filename, a, b, c, inp_units=0, out_units=0)[source]

Read an xyz file with atomic coordinates given in fractional lattice vector units

Parameters

  • filename (string) – the name of the xyz file to read

  • a (VECTOR) – the unit cell vector in the direction a [units defined by inp_units]

  • b (VECTOR) – the unit cell vector in the direction b [units defined by inp_units]

  • c (VECTOR) – the unit cell vector in the direction c [units defined by inp_units]

  • inp_units (int) –

    defines the units of a,b,c:

    • 0 - Bohr ( default )

    • 1 - Angstrom

  • out_units (int) –

    defines the units of the coordinates in the ourput variable:

    • 0 - Bohr ( default )

    • 1 - Angstrom

Returns

(L, coords), where:

  • L ( list of N strings ): the labels of N atoms read

  • coords ( list of N VECTORs ): the coordinates of N atoms read [defined by out_units]

Return type

tuple