Standard Gollum plugin¶

Description¶

The AiiDA Gollum plugin is an AiiDA extension, written in Python, which allows to run in a user friendly way highly automated transport simulations with the Gollum code. It has two main parts, the input and the output, which facilitate the design, analysis and postprocessing of transport calculations within the AiiDA framework.

These docs are for version: aiida-0.12.0–plugin-0.1.0 of the plugin.

Supported Gollum versions¶

At least 2.0.0 version of the code, which can be downloaded from the Golum webpage (http://www.physics.lancs.ac.uk/gollum/index.php/downloads).

Inputs¶

settings, class ParameterData

The name of the localfolder that contains the Extended_Molecule and Lead_* input files (in case they are necessary) and the path of the (remote) directory where the Matlab MCR is located. For example:

emname = os.path.realpath(os.path.join(os.path.dirname(__file__),
    "../data"))+'/Extended_Molecule'
l1name = os.path.realpath(os.path.join(os.path.dirname(__file__),
    "../data"))+'/Lead_1'
l2name = os.path.realpath(os.path.join(os.path.dirname(__file__),
    "../data"))+'/Lead_2'
settings_dict={'additional_local_copy_list': [emname, l1name, l2name],
               'cmdline': '/share/apps/MATLAB/MCR/MCR_R2017b/v92/'}
settings = ParameterData(dict=settings_dict)

parameters, class ParameterData

A dictionary with scalar and string variables and blocks, which are the basic elements of the Gollum input file. The definition of each parameter is simpler than in the Gollum original input file (it is not necessary to specify the type of variable and the number of rows and columns):

'Mode': 1,
'Verbose': 0,
'HamiltonianProvider': 'tbm',
'Path_EM': './Extended_Molecule',

Complex data structures such as blocks with various rows and columns are defined by using an appropriate key and Python’s multiline string constructor. It is necessary to distinguish between numerical blocks (NBlock):

'NBlock leadp': """
2 2 -1
2 2  1 """,

and string blocks (SBlock):

'SBlock Path_Leads': """
1 ./Lead_1
2 ./Lead_2""",

The only block that is defined differently is the atom block:

'atom': """
2  2
0 10
2  2 """

The first column of the atom block indicates the lead number or the extended molecule (0), the second column the number of principal layers in each lead (0 again for the extended molecule) and the third column the number of atoms in each lead. From these numbers the plugin constructs and writes in the input file the typical atom block.

Outputs¶

Different output nodes can be created by the plugin, according to the calculation details. All output nodes can be accessed with the calculation.out method.

The output parser gets information the Gollum output file (where the output of the run is redirected) and from data files generated by the run (transmission and open-channels files).

output_parameters ParameterData (accessed by calculation.res)

A dictionary with metadata, scalar result values, errors and warnings lists, and time information:

{
   "gollum_version": "Version 2.0 GAMMA (Feb. 2018)",
   "oc_ef": 3.0,
   "oc_M": 6.0,
   "oc_m": 0.0,
   "tt_ef": 2.999997,
   "tt_M": 5.999995,
   "tt_m": 0.0,
   "start_of_run": "05-Jun-2018 16:59:41",
   "end_of_run": "05-Jun-2018 16:59:50",
   "total_time": 8.375386,
   "warnings": [],
   "errors": []
}

The data include the number of open channels at the Fermi level (oc_ef), the maximum (oc_M) and minimum (oc_m) open channels, the transmission at the Fermi level (tt_ef) and the maximum (tt_M) and minimum (tt_m) transmission. All these values are converted to ‘float’. The parser also distinguishes between spin-unpolarized and -polarized calculations. In the former case it gives the values ou_ef, ou_M, ou_m, tu_ef, tu_M and tu_m, for the up open channels and transmission and od_ef, od_M, od_m, td_ef, td_M and td_m for the down open channels and transmission, respectively.

The warnings list contains program warnings which do not stop the execution of Gollum. The errors list contains the last line of the output file when the execution stops for errors or for external reasons.

output_array ArrayData

Contains the open channels and the transmission in an array form (the energy in the x axis and the open channels or transmission in the y axis).

Errors¶

Errors during the parsing stage are reported in the log of the calculation (accessible with the verdi calculation logshow command). They are also stored in the ParameterData under the key warnings, and are accessible with Calculation.res.warnings.

Restarts¶

A restarting capability is implemented following the basic idiom:

c = load_node(Failed_Calc_PK)
c2 = c.create_restart(force_restart=True)
c2.store_all()
c2.submit()

The partial.mat file is copied from the old calculation scratch folder to the new calculation’s one.

This approach enables continuation of runs that may have failed due to lack of time or other problems.

Additional advanced features¶

Additional settings can be specified in the settings input, of type ParameterData, as explained before.

Some of the options that can be specified are summarized below. In each case, after having defined the content of settings_dic, it can be used as input of a calculation calc by doing:

calc.use_settings(ParameterData(dict=settings_dict))

The keys of the settings dictionary are internally converted to uppercase by the plugin.

Adding command-line options¶

In order to add command-line options to the executable (particularly relevant e.g. to tune the parallelization level), each option can be passed as a string in a list, as follows:

settings_dict = {
'cmdline': ['-option1', '-option2'],
}

Note that very few user-level command-line options (besides those already inserted by AiiDA for MPI operation) are currently implemented.

Retrieving more files¶

If there are additional files produced by the calculation that need to be retrieved (and preserved in the AiiDA repository), they can be added as a list as follows:

settings_dict = {
'additional_retrieve_list': ['aiida.EIG', 'aiida.ORB_INDX'],
}

These files are then copied from the remote folder to the local repository.