Parameter passing in NWChem and the Runtime Database

Thoughts on parameter passing through the RTDB within NWChem.

Background

Despite a plethora of publications (Aprà et al. 2020; Mejia-Rodriguez et al. 2023), NWChem has little to nothing in terms of developer documentation ¹. For better integration over sockets with EON (described elsewhere), I ended up having to add user defined parameters, from which this short note stems.

Inputs in NWChem

The input file format in NWChem, like most codes of the era, consist of a keyword driven, whitespace delimited, block structured set of directives which are parsed once into a database and propagated across other modules.

Runtime Database (RTDB)

The run time database, as noted in (Bernholdt et al. 1995; Guest et al. 1996), is similar to the GAMESS dump file or GAUSSIAN checkpoint file. Allegedly it is easier and safer than both, and arrays of typed data are stored with ASCII strings for keys. Though the GAMESS and GAUSSIAN notes are not an immediately recognizable point of reference either, but it is essentially a key value store which is used to circumvent having an interoperable data-structure.

This centralized key-value approach decouples modules from the specifics of the input file; a routine only needs to know the key for a parameter, not how or where it was parsed. This contrasts with approaches where configuration objects must be passed through long call stacks or where multiple components parse the same configuration file independently.

Adding parameters to NWChem through the RTDB

Here, we will only be interested in this section:

1driver
2  socket unix eon_nwchem
3end

Which can be abstracted into:

1driver
2  socket (unix || ipi_client) <socketname>
3end

Concretely, we will consider the case of adding optional parameters to this so as to enable the following design:

1driver
2  socket (unix || ipi_client) <socketname> [retries <int>] [delay <int>]
3end

Conceptually this involves:

Parsing

To extract data from the input

Storing

Committing parsed values into the RTDB with rtdb_put

Retrieving

Accessing the values from the RTDB with rtdb_get

Parsing optional keyword arguments

Naming follows a conventional scheme², so the src/driver/driver_input.F is the first port of call. The implementation involves setting defaults and then looping through remaining fields on the line to check for overrides.

 1! socket ipi_client ip:port [retries <int>] [delay <int>]
 2max_retries = 30
 3retry_delay = 2
 4do while (inp_a(field))
 5   if (inp_compare(.false., 'retries', field)) then
 6      if (.not. inp_i(max_retries))
 7      call errquit('driver_input: expected integer for retries', 0,INPUT_ERR)
 8   else if (inp_compare(.false., 'delay', field)) then
 9      if (.not. inp_i(retry_delay))
10      call errquit('driver_input: expected int for delay',0,INPUT_ERR)
11   end if
12end do

Where inp_a parses a keyword, inp_compare checks against an expected value, and inp_i parses the value as an integer.

Comitting values to the RTDB

Once stored in a local variable, the value is then committed to the RTDB using rtdb_put, which is namespaced for modularity and to reduce key conflicts.

1if (inp_compare(.false.,'retries',field)) then
2  if (.not. inp_i(max_retries)) call errquit(...)
3    if (.not. rtdb_put(rtdb,'driver:socket_retries',mt_int,1,max_retries)) call errquit(...)
4end if

Where the signature notes the number of elements (1) being stored along with the type (mt_int).

Retrieval and usage

Where the values are to be retrieved, say, here in src/driver/socket_driver.F, defaults are used if the key is missing.

1if (.not. rtdb_get(rtdb, 'driver:socket_retries', mt_int, 1, max_retries)) then
2   max_retries = 30
3end if

Before being used as needed. The signature of rtdb_get conceptually mimics that of rtdb_put. In practice, since these are FORTRAN 77 files in nwchem, there are a few more continuation line characters and other marginalia, but otherwise this is all that is necessary to expose user parameters to modules in NWChem.

Conclusions

Although not the design taken by more modern software, the RTDB is pretty intuitive to work with, and probably better than GAMESS, GAUSSIAN, or even the bring your own data into a simulation development environment idea of NWChemEx (Richard et al. 2019). Better documentation would probably stemmed the split. Modern tools (e.g. EON) improve upon this by using more structured input files, e.g. using TOML ensures typing which can then be independently read into C/C++/Fortran etc. though the issue of consistency at runtime remains.

References