Serialization of ORCA input parameters

[brockdyer03]

Problem

As of late I have noticed that the ORCA Manual and the opi source code can occasionally differ on the availability of ORCA input blocks and simple input keywords. One example is the optimization keywords. The ORCA Manual does not list a SloppyOpt in the optimization keywords, but it is present in src/opi/input/simple_keywords/opt.py, along with CrudeOpt, which is also not in the ORCA Manual.

It is difficult if you are a user, or perhaps a developer looking to make an interface to ORCA in another program, to know what options are actually available.

Solution

Given the access that the opi developers have to the ORCA source code, you are in a unique position to provide a 100% accurate, serialized version of the ORCA input parameters. Ideally this would be in an easily-parsed yet still human-readable format such as TOML, and could be provided in this repository for anyone who is looking for programmatic access to ORCA input variables.

As a brief idea of how this might look, consider the following layout:

orca-version = "6.1.1"

[[blocks.cis]]
nroots        = {type = "int"}
iroot         = {type = "int"}
irootmult     = {type = "str", options = ["singlet", "triplet"]}
maxdim        = {type = "int"}
maxiter       = {type = "int"}
nguessmat     = {type = "int"}
maxcore       = {type = "int"}
etol          = {type = "float"}
rtol          = {type = "float"}
tda           = {type = "bool"}
lrcpcm        = {type = "bool"}
cpcmeq        = {type = "bool"}
donto         = {type = "bool"}
saveunrnatorb = {type = "bool"}
spinflip      = {type = "bool"}
soc           = {type = "bool"}
socgrad       = {type = "bool"}
triplets      = {type = "bool"}
dotrans       = {type = "bool"}
dcorr         = {type = "int"}
doscs         = {type = "bool"}
intaccxc      = {type = "float"}
gridxc        = {type = "int"}
gridx         = {type = "int"}

[[blocks.ice]]
nel       = {type = "int"}
norb      = {type = "int"}
nroots    = {type = "int"}
mult      = {type = "int"}
irrep     = {type = "int"}
tgen      = {type = "float"}
tvar      = {type = "float"}
etol      = {type = "float"}
icetype   = {type = "str", options = ["CFGs", "CSFs", "DETs"]}
integrals = {type = "str", options = ["exact", "ri"]}

Alternatives

My only alternative as of right now is to comb through the ORCA manual and try to catch all of the input blocks and simple input keywords, then hope that it's accurate. When it gets updated either I or someone else will have to comb through it again to try and catch the changes, if there are any.

[haneug]

The gap between what is in the ORCA source code and what appears in the manual is intentional. Many internal keywords are experimental or intended for internal and developer use only, they are deliberately undocumented for this reason. Publishing a serialized list of everything ORCA accepts would give these keywords a visibility and legitimacy they are not meant to have, and would require exposing ORCA internals that we are not in a position to share publicly.

The ORCA manual remains the authoritative reference for what is supported, and OPI aims to reflect that, not to go beyond it. The examples you mentioned should actually not be in OPI and slipped by me.

[brockdyer03]

Perhaps then a filtered keyword list could be published? I had made a post on the forum that talked about keywords not always appearing where they should or being different from place to place, and the response was that the keywords in OPI are guaranteed to work, and that the manual will receive corrections as it gets updated.

It'd be really convenient to get something that is a machine-readable version of the keywords, and while I am determined to create that list no matter what, it would be very convenient if it could be supplied by FACCTs after say, each release.

[haneug]

Sorry if my initial response came across as completely dismissive, that was not the intention! In principle, I would be interested in generating such a filtered list with at least a minimal amount of documentation (e.g. see #37). That said, it is not something I can commit to in the near term but I will discuss it internally.

[brockdyer03]

I (among others) would be very grateful for that, thanks!