Getting started with pyscal

The System class

System is the central class in pyscal. It is required for setting up calculations. We start by importing the class,

from pyscal import System

And then create a system

sys = System()

sys is a System object. But at this point, it is completely empty. We have to provide the system with the following information- * the simulation box dimensions * the positions of individual atoms.

Let us try to set up a small system, which is the bcc unitcell of lattice constant 1. The simulation box dimensions of such a unit cell would be [[0.0, 1.0], [0.0, 1.0], [0.0, 1.0]] where the first set correspond to the x axis, second to y axis and so on.

The unitcell has 2 atoms and their positions are [0,0,0] and [0.5, 0.5, 0.5].

sys.box = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]

We can easily check if everything worked by getting the box dimensions

sys.box

[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]

The Atoms class

We start by importing the Atoms class

from pyscal import Atoms

The next part is assigning the atoms. This can be done using the Atom class.

First, we prepare the positions

adict = {"positions": [[0, 0, 0], [0.5, 0.5, 0.5]]}

Now we can create atoms

atoms = Atoms(adict)

Atoms is python class and you can access the various keys.

atoms.positions

[[0, 0, 0], [0.5, 0.5, 0.5]]

It is also a dictionary and you can check the available keys.

atoms.keys()

dict_keys(['positions', 'ids', 'ghost', 'types', 'species', 'mask_1', 'mask_2', 'condition', 'head'])

There are more keys that were auto-generated, which is not important for us for the moment.

For more details about the Atoms class, please see further examples.

Combining System and Atoms

Now we can add the atoms to the System we created before.

sys.atoms = atoms

We are all set! The System is ready for calculations. However, in most realistic simulation situations, we have many atoms and it can be difficult to set each of them

individually. In this situation we can read in input file directly. An example input file containing 500 atoms in a simulation box can be read in automatically. The file we use for this example is a file of the lammps-dump format. pyscal can also read in a number of other file formats. In principle, pyscal only needs the atom positions and simulation box size, so you can write a python function to process the input file, extract the details and pass to pyscal.

sys = System('conf.dump')

sys.atoms.positions[:5]

[[-5.66782, -6.06781, -6.58151],
 [-3.61832, -5.66888, -5.46712],
 [-0.947172, 10.3193, 11.3033],
 [-0.10301, -6.35752, -6.44787],
 [1.61271, -5.30872, -7.68795]]

Alternatively, it can be a two-step process

sys = System()

sys.read_inputfile('conf.dump')

The read_inputfile function supports a number of other options as well.

sys.read_inputfile?

Signature:
sys.read_inputfile(
    filename,
    format='lammps-dump',
    compressed=False,
    customkeys=None,
)
Docstring:
Read input file that contains the information of system configuration.

Parameters
----------
filename : string
    name of the input file.

format : {'lammps-dump', 'poscar', 'ase', 'mdtraj'}
    format of the input file, in case of `ase` the ASE Atoms object

compressed : bool, optional
    If True, force to read a `gz` compressed format, default False.

customkeys : list
    A list containing names of headers of extra data that needs to be read in from the
    input file.

Returns
-------
None

Notes
-----
`format` keyword specifies the format of the input file. Currently only
a `lammps-dump` and `poscar` files are supported.  Additionaly, the widely
use Atomic Simulation environment (https://wiki.fysik.dtu.dk/ase/ase/ase.html).
mdtraj objects (http://mdtraj.org/1.9.3/) are also supported by using the keyword
`'mdtraj'` for format. Please note that triclinic boxes are not yet supported for
mdtraj format.
Atoms object can also be used directly. This function uses the
:func:`~pyscal.traj_process` module to process a file which is then assigned to system.

`compressed` keyword is not required if a file ends with `.gz` extension, it is
automatically treated as a compressed file.

Triclinic simulation boxes can also be read in.

If `custom_keys` are provided, this extra information is read in from input files if
available. This information is can be accessed directly as `self.atoms['customkey']`
File:      ~/miniconda3/envs/pyscal-test/lib/python3.10/site-packages/pyscal/core.py
Type:      method