How do I …¶
… install crystally?¶
crystally is obtainable via pip. To install the package simply type:
python3 -m pip install crystally [--user]
After this step you can import crystally:
import crystally
… create a lattice?¶
To create a lattice, you need to specify the cartesian lattice vectors and the atoms with their fractional coordinates. An atom has three attributes: an element, a position and a sublattice. The last of these attributes is more of a wildcard, to help with sorting or filtering operations.
The ceria system is then easily created by:
>>> from crystally import Lattice, Atom
>>> ceria = Lattice(vectors = [[5.499, 0, 0], [0, 5.499, 0], [0, 0, 5.499]],
atoms = [Atom("Ce", [0, 0, 0], "cations"),
Atom("Ce", [0, 0.5, 0.5], "cations"),
Atom("Ce", [0.5, 0, 0.5], "cations"),
Atom("Ce", [0.5, 0.5, 0], "cations"),
Atom("O", [0.25, 0.25, 0.25], "anions"),
Atom("O", [0.75, 0.25, 0.25], "anions"),
Atom("O", [0.25, 0.75, 0.25], "anions"),
Atom("O", [0.25, 0.25, 0.75], "anions"),
Atom("O", [0.75, 0.75, 0.25], "anions"),
Atom("O", [0.25, 0.75, 0.75], "anions"),
Atom("O", [0.75, 0.25, 0.75], "anions"),
Atom("O", [0.75, 0.75, 0.75], "anions")])
We will use this system in the following explanations.
… view the lattice?¶
To get a nicely readable representation of the lattice simply use the print command:
>>> print(ceria)
Lattice:
Vectors:
5.4994687617 0.0000000000 0.0000000000
0.0000000000 5.4994687617 0.0000000000
0.0000000000 0.0000000000 5.4994687617
Positions:
0 Atom: Ce [ 0.0000000000, 0.0000000000, 0.0000000000] cations
1 Atom: Ce [ 0.0000000000, 0.5000000000, 0.5000000000] cations
2 Atom: Ce [ 0.5000000000, 0.0000000000, 0.5000000000] cations
3 Atom: Ce [ 0.5000000000, 0.5000000000, 0.0000000000] cations
4 Atom: O [ 0.2500000000, 0.2500000000, 0.2500000000] anions
5 Atom: O [ 0.7500000000, 0.2500000000, 0.2500000000] anions
6 Atom: O [ 0.2500000000, 0.7500000000, 0.2500000000] anions
7 Atom: O [ 0.2500000000, 0.2500000000, 0.7500000000] anions
8 Atom: O [ 0.7500000000, 0.7500000000, 0.2500000000] anions
9 Atom: O [ 0.2500000000, 0.7500000000, 0.7500000000] anions
10 Atom: O [ 0.7500000000, 0.2500000000, 0.7500000000] anions
… create a supercell?¶
After defining your unitcell, you may want to create a larger supercell. This is pretty easy. In the following example we want to create a ceria supercell of size 2x2x2:
>>> supercell = Lattice.from_lattice(ceria, 2, 2, 2)
As you see, the function from_lattice() takes four arguments. The first one is the base lattice that is taken
as starting point. The three following values describe the size multiplier for each direction: x, y and z.
… select an atom?¶
The index-method of the lattice objects returns the atom from the atom list with the provided index:
>>> ceria[0]
Atom('Ce',FractionalVector([0.0, 0.0, 0.0]),'Ce')
You can also search for atoms with the find()-method. You can specify the element, sublattice and the position
in fractinoal coordinates of the atoms to search for. Mind that only one argument is allowed for each criteria.
In addition you can specify the tolerance for the positional criteria in angstrom. If the distance between
the specified position and the atom is smaller than the tolerance, it will be found. Let’s say that you want to find
the atom that is located at 0, 0, 0:
>>> caria.find(position=[0, 0, 0])
[Atom('Ce',FractionalVector([0.0, 0.0, 0.0]),'Ce')]
The return value is always a list, unless you set first=True. Then the first found atom is returned:
>>> print(ceria.find(position=[0, 0.5, 0.51]))
None
… create a vacancy?¶
To delete entries from the atom list of a lattice, you can use the remove()-method. You need to specify
an atom that really is in the atom list of the lattice. Otherwise a ValueError is raised.
>>> supercell.remove(supercell[0])
… get the distance between two points in the lattice?¶
Every lattice object comes with a distance() method. If you specify two points in fractional coordinates or
two atoms, it will return the distance between the two points in angstrom. This will take the periodic boundary
into consideration. You can turn this off by setting `periodic=False`.
>>> supercell.distance([0,0,0], [0.8, 0.8, 0.8])
3.8101437239430154
>>> supercell.distance([0,0,0], [0.8, 0.8, 0.8], periodic=False)
15.240574895772065
… change the position of an atom?¶
crystally was created with the intend to manipulate lattices. Changing the position of an atom is therefore
very simple. First select the atom you would like to manipulate. Then change the position attribute:
>>> atom = lattice[0]
>>> atom.position = [0.1, 0.1, 0.1]
… increase the distance between two atoms?¶
If you want to increase the distance of one point to a fixed center point you can either use increase_distance_abs()
or increase_distance_rel() from the Lattice object. Both methods return the new position. With the first
method you can specify the distance increase as absolute value in angstrom. The second method increases the distance
on a relative basis.
Examples: To increase the distance of a point at (0.5, 0.5, 0.5) from the origin by 1 Angstrom, do:
>>> print(supercell.increase_distance_abs([0,0,0], [0.5, 0.5, 0.5], 1))
[0.55249146 0.55249146 0.55249146]
… read and write vasp files?¶
To read a POSCAR or CONTCAR file, you can use the read_poscar() function. For example, if you would like to
read the file “POSCAR”, type:
>>> lattice = crystally.read_poscar("POSCAR")
To write a Lattice object to a POSCAR file, use the write_poscar() function. You need to specify the
Lattice object, the name and location of the file and a short description for the header of the POSCAR file.
>>> cr.vasp.write_poscar(supercell, "POSCAR", "ceria supercell structure")