The bsecurate command line interface

In addition to the user-oriented command-line interface, the BSE also contains a command-line interface for curation functions bsecurate. This can be used to query, add, or modify basis set data.

Installation and TAB completion

See Installation

Note that some functionality will require installing the curate section (ie, pip install basis_set_exchange[docs,tests,curate]).

Rendering/Viewing graphs will require graphviz.

General usage

The bsecurate command is generally followed by a subcommand (see below). bsecurate -h will display help and bsecurate -V will display the version and exit.

$ bsecurate -h
usage: bsecurate [-h] [-V] [-d PATH] [-o PATH] subcommand ...

Description of your program

positional arguments:
  subcommand
    elements-in-files   For a list of JSON files, output what elements are in
                        each file
    component-file-refs
                        For a list of component JSON files, output what
                        elements/references are in each file
    update-metadata     Update the metadata in the repository
    print-component-file
                        (Pretty) print the contents of a component file
    make-diff           Find/Store the differences between two groups of files
    compare-basis-sets  Compare two basis sets in the data directory
    compare-basis-files
                        Compare two formatted basis set files
    compare-basis-to-file
                        Compare basis set in data directory to file
    view-graph          View a file graph for a basis set
    make-graph-file     Make a dot file (and png file) for a basis set file
                        graph

options:
  -h, --help            show this help message and exit
  -V                    show program's version number and exit
  -d PATH, --data-dir PATH
                        Override which data directory to use
  -o PATH, --output PATH
                        Output to given file rather than stdout

In general, values provided to options (such as basis set names, formats, and elements) are not case sensitive.

There are two global options available to all subcommands. The first is an alternate data directory can be specified with -d or --data-dir. Also, output can be written to a file rather than to the terminal with -o. This is similar to the bse command line program.

Subcommands

Below is a list of the available subcommands. All subcommands can take the -h option to display help for that subcommand.

$ bsecurate elements-in-files -h
usage: bsecurate elements-in-files [-h] files [files ...]

positional arguments:
  files       List of files to inspect

options:
  -h, --help  show this help message and exit
...

elements-in-files

For a list of BSE JSON files, determine what elements the file contains data for. This works on table, element, and component data files.

$ DATADIR=`bse get-data-dir`; bsecurate elements-in-files ${DATADIR}/6-31G.0.table.json ${DATADIR}/dunning/*element*json
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/6-31G.0.table.json                           H-Zn
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pV5+dZ.1.element.json         Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pV5Z.1.element.json           H-Ar,Sc-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pV6Z.1.element.json           H,He,B-Ne,Al-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pVD+dZ.1.element.json         Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pVDZ.1.element.json           H-Ar,Sc-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pVQ+dZ.1.element.json         Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pVQZ.1.element.json           H-Ar,Sc-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pVT+dZ.1.element.json         Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-cc-pVTZ.1.element.json           H-Ar,Sc-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pV5Z-PP.1.element.json    Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pVDZ-PP.1.element.json    Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pVQZ-PP.1.element.json    Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pVTZ-PP.1.element.json    Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pwCV5Z-PP.1.element.json  Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pwCVDZ-PP.1.element.json  Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pwCVQZ-PP.1.element.json  Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/aug-seg-cc-pwCVTZ-PP.1.element.json  Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pV5+dZ.1.element.json             Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pV5Z.1.element.json               H-Ar,Ca-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pV6Z.1.element.json               H,He,Be-Ne,Al-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pVD+dZ.1.element.json             Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pVDZ.1.element.json               H-Ar,Ca-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pVQ+dZ.1.element.json             Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pVQZ.1.element.json               H-Ar,Ca-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pVT+dZ.1.element.json             Na-Ar
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pVTZ.1.element.json               H-Ar,Ca-Kr
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pV5Z-PP.1.element.json        Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pVDZ-PP.1.element.json        Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pVQZ-PP.1.element.json        Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pVTZ-PP.1.element.json        Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pwCV5Z-PP.1.element.json      Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pwCVDZ-PP.1.element.json      Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pwCVQZ-PP.1.element.json      Y-Cd,Hf-Hg
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/seg-cc-pwCVTZ-PP.1.element.json      Y-Cd,Hf-Hg

component-file-refs

$ DATADIR=`bse get-data-dir`; bsecurate component-file-refs ${DATADIR}/dunning/cc-pVDZ.1.json
/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/basis_set_exchange/data/dunning/cc-pVDZ.1.json
    H,B-Ne  dunning1989a
    He      woon1994a
    Ca      koput2002a
    Sc-Zn   balabanov2005a balabanov2006a
    Ga-Kr   wilson1999a

print-component-file

Pretty prints data from a component file.

$ DATADIR=`bse get-data-dir`; bsecurate print-component-file ${DATADIR}/dunning/cc-pVDZ.1.json
Description: The cc-pVDZ basis set

Element: H : (4s,1p) -> [2s,1p]
Shell: Index 0  Region: (none) AM: S
Function: gto
      1.301000E+01           1.968500E-02           0.000000E+00
      1.962000E+00           1.379770E-01           0.000000E+00
      4.446000E-01           4.781480E-01           0.000000E+00
      1.220000E-01           5.012400E-01           1.000000E+00

...

make-diff

Compute the difference between two groups of JSON files and store them in ‘.diff’ files.

For each file specified with the -l, subtract all the common shells in files specified with -r.

Multiple files are specified after the -r or -l flag. For example, -l file1 file2 -r file3 file3.

For each file specified with -l, an output file is created with the same name but with .diff appended to the filename.

compare-basis-sets

Compare two basis sets and print a report. These are read/composed from a data directory. Versions can be specified

$ bsecurate compare-basis-sets 6-31G 6-31G --version1 1 --version2 0

-------------------------------------
 Element 1: H
   Exponent   0: 18.7311370           0.1873113696E+02     ->   2.13548168e-09
Coefficient (  0,  0): 0.03349460           0.3349460434E-01     ->   1.29573125e-07
   Exponent   1: 2.8253937            0.2825394365E+01     ->   2.35365429e-07
Coefficient (  0,  1): 0.23472695           0.2347269535E+00     ->   1.49109423e-08
   Exponent   2: 0.6401217            0.6401216923E+00     ->   1.20289627e-08
...

     Not in bs1:  
     Not in bs2:  Ga-Kr
  No difference:  
Some difference:  H-Ar,Sc-Zn
 BIG difference:  K,Ca

DIFFERENCES FOUND. SEE ABOVE

compare-basis-files

Compare two formatted basis sets files and print a report. For valid formats, use get-reader-formats

view-graph-file

Similar to make-graph-file, but will instead create a temporary file, render the PNG, and then call the default viewer.

Requires graphviz and a graphical viewer to be installed.

make-graph-file

Make a graphviz DOT file (https://graphviz.org/documentation/) containing a graph that describes what files go into a basis set. Optionally takes a version of the basis set.

If --render is passed, a PNG file will also be created.

$ bsecurate make-graph-file 6-31g graph_631g.dot

$ cat graph_631g.dot
// Basis Set Graph: 6-31g
digraph {
	"6-31g" -> "pople/31G.1.element.json" [label="H,He"]
	"6-31g" -> "pople/6-31G.1.element.json" [label="Li-Kr"]
	"pople/31G.1.element.json" -> "pople/31G/31G.1.json" [label="H,He"]
	"pople/6-31G.1.element.json" -> "pople/6-31G/6-31G.1.json" [label="Li-Ne,K-Kr"]
	"pople/6-31G.1.element.json" -> "pople/21G/6-21G-core.1.json
pople/6-31G/6-31G-valence.1.json" [label="Na-Ar"]
}