# pyscal Reference¶

## pyscal.core module¶

Main module of pyscal. This module contains definitions of the two major classes in pyscal - the System and Atom. Atom is a pure pybind11 class whereas System is a hybrid class with additional python definitions. For the ease of use, Atom class should be imported from the core module. The original pybind11 definitions of Atom and System can be found in catom and csystem respectively.

class pyscal.catom.Atom

Bases: pybind11_builtins.pybind11_object

Class to store atom details.

Parameters: pos (list of floats of length 3) – position of the Atom, default [0,0,0] id (int) – id of the Atom, default 0 type (int) – type of the Atom, default 1

Notes

A pybind11 class for holding the properties of a single atom. Various properties of the atom can be accessed through the attributes and member functions which are described below in detail. Atoms can be created individually or directly by reading a file. Check the examples for more details on how atoms are created. For creating atoms directly from an input file check the documentation of System class.

Although an Atom object can be created independently, Atom should be thought of inherently as members of the System class. All the properties that define an atom are relative to the parent class. System has a list of all atoms. All the properties of an atom, hence should be calculated through System.

Examples

>>> #method 1 - individually
>>> atom = Atom()
>>> #now set positions of the atoms
>>> atom.pos = [23.0, 45.2, 34.2]
>>> #now set id
>>> atom.id = 23
>>> #now set type
>>> atom.type = 1
>>> #Setting through constructor
>>> atom = Atom([23.0, 45.2, 34.2], 23, 1)


References

allaq

list of floats. list of all averaged q values of the atom.

allq

list of floats. list of all q values of the atom.

angular

Float. The value of angular parameter A of an atom. The angular parameter measures the tetrahedral coordination of an atom. Meaningful values are only returned if the property is calculated using calculate_angularcriteria().

avg_angular

Float. The average angular parameter value. Not used currently.

avg_disorder

Float. The value of averaged disorder parameter.

avg_energy

Float. Value of averaged energy.

avg_entropy

Float. Value of averaged entropy parameter.

avg_sij

float. Value of averaged s_ij which is used for identification of solid atoms. s_ij is defined by

$s_{ij} = \sum_{m=-l}^l q_{lm}(i) q_{lm}^*(i)$
avg_volume

float. Averaged version of the Voronoi volume which is calculated as an average over itself and its neighbors. Only calculated when the find_neighbors() using the method=’voronoi’ option is used.

bonds

Int. The number of solid bonds of an atom.

calculate_adaptive_cna()
centrosymmetry

Float. The value of centrosymmetry parameter.

chiparams

Float. The value of chiparameter of an atom. The return value is a vector of length 8. Meaningful values are only returned if chi params are calculated using calculate_chiparams().

cluster

int. identification number of the cluster that the atom belongs to.

common_neighbor_count
condition

int. condition that specifies if an atom is included in the clustering algorithm or not. Only atoms with the value of condition=1 will be used for clustering in cluster_atoms().

coordination

int. coordination number of the atom. Coordination will only be updated after neighbors are calculated using find_neighbors().

custom

dict. dictionary specfying custom values for an atom. The module only stores the id, type and position of the atom. If any extra values need to be stored, they can be stored in custom using atom.custom = {“velocity”:12}. read_inputfile() can also read in extra atom information. By default, custom values are treated as string.

cutoff

double. cutoff used for finding neighbors for each atom.

disorder

Float. The value of disorder parameter.

edge_lengths

list of floats. For each face, this vector contains the lengths of edges that make up the Voronoi polyhedra of the atom. Only calculated when the find_neighbors() using the method=’voronoi’ option is used.

energy

Float. Value of energy.

entropy

Float. Value of entropy parameter.

face_perimeters

list of floats. List consisting of the perimeters of each Voronoi face of an atom. Only calculated when the find_neighbors() using the method=’voronoi’ option is used.

face_vertices

list of floats. A list of the number of vertices shared between an atom and its neighbors. Only calculated when the find_neighbors() using the method=’voronoi’ option is used.

get_q()

Calculate the steinhardt parameter q_l value.

Parameters: q (int or list of ints) – number of the required q_l - from 2-12 averaged (bool, optional) – If True, return the averaged q values, If False, return the non averaged ones default False q_l – the value(s) of the queried Steinhardt parameter(s). float or list of floats

Notes

Meaningful values are only returned if calculate_q() is used.

get_qlm()

Get the q_lm values.

Parameters: q (int) – number of the required q_l - from 2-12 averaged (bool, optional) – If True, return the averaged qlm values, If False, return the non averaged ones default False q_lm (complex vector) – vector of complex numbers. Meaningful values are only returned if calculate_q() is used.
ghost

int. int specifying ghost status of the atom.

id

int. Id of the atom.

largest_cluster

bool. True if the atom belongs to the largest cluster, False otherwise. Largest cluster is only identified after using the cluster_atoms() function.

loc

int. indicates the position of the atom in the list of all atoms.

local_angles

List of floats of length 2. List of longitude and colatitude of an atom to its neighbors.

mask

bool. Mask variable for atom. If mask is true, the atom is ignored from calculations.

neighbor_distance

List of floats. List of neighbor distances of the atom.

neighbor_vector

List of floats of length 3. List of vectors connecting an atom to its neighbors.

neighbor_weights

List of floats. Used to weight the contribution of each neighbor atom towards the value of Steinhardt’s parameters. By default, each atom has a weight of 1 each. However, if find_neighbors() is used with method=’voronoi’, each neighbor gets a weight proportional to the area shared between the neighboring atom and host atom.

neighbors

List of ints. List of neighbors of the atom. The list contains indices of neighbor atoms which indicate their position in the list of all atoms.

next_neighbor_distances

double. cutoff used for finding neighbors for each atom.

next_neighbors

double. cutoff used for finding neighbors for each atom.

pos

List of floats of the type [x, y, z], default [0, 0, 0]. Position of the atom.

set_q()

Set the value of steinhardt parameter q_l.

Parameters: q (int or list of ints) – number of the required q_l - from 2-12 val (float or list of floats) – value(s) of Steinhardt parameter(s). averaged (bool, optional) – If True, return the averaged q values, If False, return the non averaged ones default False None
sij

float. Value of s_ij which is used for identification of solid atoms. s_ij is defined by

$s_{ij} = \sum_{m=-l}^l q_{lm}(i) q_{lm}^*(i)$
solid

bool. True if the atom is solid, False otherwise. Solid atoms are only identified after using the find_solids() function.

sro

Float. The value of short range order parameter.

structure

int. Indicates the structure of atom. Not used currently.

surface

bool. True if the atom has at least one liquid neighbor, False otherwise. Surface atoms are only identified after using the find_solids() function.

type

int. int specifying type of the atom.

vertex_numbers

list of floats. For each Voronoi face of the atom, this values includes a List of vertices that constitute the face. Only calculated when the find_neighbors() using the method=’voronoi’ option is used.

vertex_vectors

list of floats. A list of positions of each vertex of the Voronoi polyhedra of the atom. Only calculated when the find_neighbors() using the method=’voronoi’ option is used.

volume

float. Voronoi volume of the atom. The Voronoi volume is only calculated if neighbors are found using the find_neighbors() using the method=’voronoi’ option.

vorovector

list of ints. A vector of the form (n3, n4, n5, n6) where n3 is the number of faces with 3 vertices, n4 is the number of faces with 4 vertices and so on. This can be used to identify structures [1][2]. Vorovector is calculated if the calculate_vorovector() method is used.

References

 [1] Finney, JL, Proc. Royal Soc. Lond. A 319, 1970
 [2] Tanemura, M, Hiwatari, Y, Matsuda, H,Ogawa, T, Ogita, N, Ueda, A. Prog. Theor. Phys. 58, 1977

## pyscal.crystal_structures module¶

pyscal module for creating crystal structures.

pyscal.crystal_structures.make_crystal(structure, lattice_constant=1.0, repetitions=None, ca_ratio=1.633, noise=0)[source]

Create a basic crystal structure and return it as a list of Atom objects and box dimensions.

Parameters: structure ({'bcc', 'fcc', 'hcp', 'diamond' or 'l12'}) – type of the crystal structure lattice_constant (float, optional) – lattice constant of the crystal structure, default 1 repetitions (list of ints of len 3, optional) – of type [nx, ny, nz], repetions of the unit cell in x, y and z directions. default [1, 1, 1]. ca_ratio (float, optional) – ratio of c/a for hcp structures, default 1.633 noise (float, optional) – If provided add normally distributed noise with standard deviation noise to the atomic positions. atoms (list of Atom objects) – list of all atoms as created by user input box (list of list of floats) – list of the type [[xlow, xhigh], [ylow, yhigh], [zlow, zhigh]] where each of them are the lower and upper limits of the simulation box in x, y and z directions respectively.

Examples

>>> atoms, box = make_crystal('bcc', lattice_constant=3.48, repetitions=[2,2,2])
>>> sys = System()
>>> sys.assign_atoms(atoms, box)


## pyscal.traj_process module¶

pyscal module containing methods for processing of a trajectory. Methods for reading of input files formats, writing of output files etc are provided in this module.

pyscal.traj_process.convert_to_ase(sys, species=None)[source]

Convert a given pyscal structure to ase object

Parameters: sys (System object) – the system object to be converted species (list of str) – a list of species in the system aseobject ASE atoms object

Notes

ASE needs the species of atoms. If a property called species exist in custom, this value is used for species. However if the value is not present, the keyword species is required. This should contain a mapping between type and species name. For example, if species is [‘Au’, ‘Ge’], all atoms of type 1 are assigned as Au and those of type 2 are assigned as Ge. Note that ase is required to run this method.

pyscal.traj_process.read_ase(aseobject, check_triclinic=False)[source]

Function to read from a ASE atoms objects

Parameters: aseobject (ASE Atoms object) – name of the ASE atoms object triclinic (bool, optional) – True if the configuration is triclinic
pyscal.traj_process.read_lammps_dump(infile, compressed=False, check_triclinic=False, customkeys=None)[source]

Function to read a lammps dump file format - single time slice.

Parameters: infile (string) – name of the input file compressed (bool, optional) – force to read a gz zipped file. If the filename ends with .gz, use of this keyword is not necessary. Default True. check_triclinic (bool, optional) – If true check if the sim box is triclinic. Default False. customkeys (list of strings, optional) – A list of extra keywords to read from trajectory file. atoms (list of Atom objects) – list of all atoms as created by user input boxdims (list of list of floats) – The dimensions of the box. This is of the form [[xlo, xhi],[ylo, yhi],[zlo, zhi]] where lo and hi are the upper and lower bounds of the simulation box along each axes. For triclinic boxes, this is scaled to [0, scalar length of the vector]. box (list of list of floats) – list of the type [[x1, x2, x3], [y1, y2, y3], [zz1, z2, z3]] which are the box vectors. Only returned if box_vectors is set to True. triclinic (bool) – True if the box is triclinic. Only returned if check_triclinic is set to True .. note:: – Values are always returned in the order atoms, boxdims, box, triclinic if all return keywords are selected. For example, ff check_triclinic is not selected, the return values would still preserve the order and fall back to atoms, boxdims, box.

Notes

Read a lammps-dump style snapshot that can have variable headers, reads in type and so on. Zipped files which end with a .gz can also be read automatically. However, if the file does not end with a .gz extension, keyword compressed = True can also be used.

Examples

>>> atoms, box = read_lammps_dump('conf.dump')
>>> atoms, box = read_lammps_dump('conf.d', compressed=True)

pyscal.traj_process.read_mdtraj(mdobject, check_triclinic=False)[source]

Function to read from an MDTraj atoms objects

Parameters: mdobject (MDTraj Atoms object) – name of the MDTraj atoms object triclinic (bool, optional) – True if the configuration is triclinic
pyscal.traj_process.read_poscar(infile, compressed=False)[source]

Function to read a POSCAR format.

Parameters: infile (string) – name of the input file compressed (bool, optional) – force to read a gz zipped file. If the filename ends with .gz, use of this keyword is not necessary, Default False atoms (list of Atom objects) – list of all atoms as created by user input box (list of list of floats) – list of the type [[xlow, xhigh], [ylow, yhigh], [zlow, zhigh]] where each of them are the lower and upper limits of the simulation box in x, y and z directions respectively.

Examples

>>> atoms, box = read_poscar('POSCAR')
>>> atoms, box = read_poscar('POSCAR.dat', compressed=True)

pyscal.traj_process.split_traj_lammps_dump(infile, compressed=False)[source]

Read in a LAMMPS dump trajectory file and convert it to individual time slices.

Parameters: filename (string) – name of input file compressed (bool, optional) – force to read a gz zipped file. If the filename ends with .gz, use of this keyword is not necessary, Default False. snaps – a list of filenames which contain individual frames from the main trajectory. list of strings
pyscal.traj_process.split_trajectory(infile, format='lammps-dump', compressed=False)[source]

Read in a trajectory file and convert it to individual time slices.

Parameters: filename (string) – name of input file format (format of the input file) – only lammps-dump is supported now. compressed (bool, optional) – force to read a gz zipped file. If the filename ends with .gz, use of this keyword is not necessary. snaps – a list of filenames which contain individual frames from the main trajectory. list of strings

Notes

This is a wrapper function around split_traj_lammps_dump function.

pyscal.traj_process.write_poscar(sys, outfile, comments='pyscal')[source]

Function to read a POSCAR format.

Parameters: outfile (string) – name of the input file
pyscal.traj_process.write_structure(sys, outfile, format='lammps-dump', compressed=False, customkey=None, customvals=None, timestep=0)[source]

Write the state of the system to a trajectory file.

Parameters: sys (System object) – the system object to be written out outfile (string) – name of the output file format (string, optional) – the format of the output file, as of now only lammps-dump format is supported. compressed (bool, default false) – write a .gz format customkey (string or list of strings, optional) – If specified, it adds this custom column to the dump file. Default None. customvals (list or list of lists, optional) – If customkey is specified, customvals take an array of the same length as number of atoms, which contains the values to be written out. timestep (int, optional) – Specify the timestep value, default 0 None