Getting Started

Get started by completing the total energy tutorial.

Input files

RESCU+ reads input files in the JSON format. The JSON format is lightweight, portable and essentially composed of Python’s basic types like: dict, list, int, float, str. It is thus convenient to prepare, read or write input files in Python using the JSON module. RESCU+ accepts so-called exhaustive input files, which contain almost all of a simulation parameters, including:

  • atomic orbital basis functions (if any)

  • geometry

  • pseudopotentials

  • solver parameters

  • etc.

Such files are convenient to keep as reference input, since they are not susceptible to changes in default parameters between version, among other advantages. But it is impractical to produce them from manually. Which is why RESCU+ works in tandem with RESCUPy, a Python interface which makes it convenient to create structures, write input files and read the output files produced by RESCU+.

System and calculator classes

Atomic systems are described by the System class. System objects can be initialized from an Atoms and a Cell object (or their corresponding dictionaries). System objects have additional attributes (such as Kpoint) which are described here. RESCUPy includes various calculator classes like the basic (and most important) TotalEnergy class. A TotalEnergy instance holds all the data regarding a given calculation:

  • the system description and simulation parameters;

  • the solvers’ parameters;

  • the output data.

A TotalEnergy object can be initialized from a System object or a corresponding dictionary or JSON file. All parameters are initialized during its creation, while retaining values specified in the seed objects or dictionary. The resulting object then maps to an exhaustive input file required by RESCU+. It contains additional methods which may provide valuable information about the system (e.g. number of atoms, converting units). The structure is easily deduced from the API documentation.

A typical input file (here GaAs-FCC) looks as follows:

Listing 1 Input file for a GaAs crystal
from rescupy import Atoms, Cell, Kpoint, System, TotalEnergy
a = 2.818
cell = Cell(avec=[[0.,a,a],[a,0.,a],[a,a,0.]], resolution=0.12)
fxyz = [[0.00,0.00,0.00],[0.25,0.25,0.25]]
atoms = Atoms(fractional_positions=fxyz, formula="GaAs")
sys = System(cell=cell, atoms=atoms)
calc = TotalEnergy(sys)
calc.solve()
print(calc.energy.etot)

Atomic configurations

Atomic configurations consist in sets of coordinates and species. The coordinates are specified either by the positions or fractional_positions attribute of Atoms objects. The atomic species are specified in the attribute formula of an Atoms object. Each atom has a position and a corresponding label or symbol, and each label corresponds to a species. In supercells, one can use the following short hand instead of repeating symbols.

formula="GaGaGaGaGaGaGaGaGaGaGaGaGaGaGaGaAsAsAsAsAsAsAsAsAsAsAsAsAsAsAsAs"

is equivalent to

formula="Ga(16)As(16)"

For larger systems, one can simply specify the configuration in an xyz-file and pass it to either the positions or fractional_positions attribute. In this case formula need not be set.

Pseudopotentials

RESCUPy can read pseudopotential and atomic orbital basis files generated by Nanobase, i.e. the same as those used by NanoDCAL and RESCU. To install the pseudopotentials, simply untar the pseudopotential archive provided to you with the source code in a known location. Finally, set the environment variable NANODCALPLUS_PSEUDO or RESCUPLUS_PSEUDO to a directory where pseudopotential are found. Note that you may have to change this depending on the calculation. For instance, when using LDA you may set NANODCALPLUS_PSEUDO=path/to/lda/pseudos while when using PBE you may set RESCUPLUS_PSEUDO=path/to/pbe/pseudos. Or simply copy the pseudopotential files you would like to use to $PWD and set RESCUPLUS_PSEUDO=$PWD.

Arrays

Many quantities are conveniently represented as arrays. For example, lattice vectors are written as

avec = [[1.,2.,3.],[4.,5.,6.],[7.,8.,9.]]

If arrays with more than one dimension are written as vectors, they will be reshaped automatically. We strongly suggest to explicitly specify the multidimensional array as above. If for some reason you need to employ one-dimensional arrays, read the following. RESCU+ uses the so-called Fortran order, which means that a vector is reshaped filling the 1st dimension, then the 2nd, then the 3rd etc. This means that

avec = [1.,2.,3.,4.,5.,6.,7.,8.,9.]

is reshaped to

avec = [[1.,4.,7.],[2.,5.,8.],[3.,6.,9.]]

which corresponds to a matrix

\[\begin{split}\begin{pmatrix} 1 & 4 & 7\\ 2 & 5 & 8\\ 3 & 6 & 9\\ \end{pmatrix}\end{split}\]

By contrast, there exist the so-called C ordering where multidimensional arrays are filled backward, i.e. starting by the last dimension.

This means that

avec = [1.,2.,3.,4.,5.,6.,7.,8.,9.]

is reshaped to

avec = [[1.,2.,3.],[4.,5.,6.],[7.,8.,9.]]

which corresponds to a matrix

\[\begin{split}\begin{pmatrix} 1 & 2 & 3\\ 4 & 5 & 6\\ 7 & 8 & 9\\ \end{pmatrix}\end{split}\]

Units

RESCU+ uses the Python library Pint to keep track of units. What you need to know to get started is that

  • Quantities with units in RESCU+ are Quantity instances.

  • You can get the magnitude of a Quantity object a with a.m.

  • You can get the unit of a Quantity object a with a.u.

  • You can import the unit registry from rescupy.utils, would you like to create Quantity objects of your own.

You may refer to the Pint documentation if you would like to know more about the library’s functionalities.

RESCU+ works with two unit systems:

  • extended SI: eV and \(\mathring{\text{A}}\)

  • atomic: hartree and bohr

The units of the exhaustive input file are hartree and bohr by default, since these files are intended for internal use of the Fortran code. Python entities, like a seed dictionary or any data in a TotalEnergy object, are in SI by default. Attributes which are of the Quantity class are automatically converted on entry. One can specify units in two ways:

  • use the unit registry from rescupy.utils.

  • pass a two-element tuple containing the magnitude and the unit as a string.

For example, in Listing 1, I can specify the units of avec as follows

from rescupy.utils import Quantity, ureg
a = 2.818
cell = Cell(avec=[[0.,a,a],[a,0.,a],[a,a,0.]] * ureg.angstrom, resolution=(0.2, "bohr"))
# [...]
print(calc.energy.etot.to("picojoules"))

First, avec is converted to a Quantity with units of angstrom multiplying by ureg.angstrom. Then, resolution is specified in bohr, passing a tuple consisting of a float and the string bohr.

Return switches

To save time, a user may set return switches to perform or skip certain calculations. For example the atomic forces, obtained upon completing a ground state calculation, are not always necessary. It is thus possible to set ["energy"]["forces_return"], which corresponds to ["energy"]["forces"], to false and save time by skipping the force calculation. Similarly, several output parameters have a corresponding _return parameter.