The bse command line interface

The basis set exchange package contains a command-line interface called bse. This command can be used to obtain/print basis sets and references, as well as query the library for information and metadata.

Installation

The command line is automatically installed when the library is installed via pip or similar python package managers.

Depending on how packages are installed, you may need to add the path to the bse program to the PATH environment variable.

TAB completion

Tab completion is available for the bash interpreter and is tremendously useful. If enabled, TAB autocompletion will be enabled for

  • Directories

  • Arguments (--elements, etc)

  • Basis set names

  • Basis set families

  • Roles

  • Basis set formats and reference formats

Autocompletion is implemented via the argcomplete library (https://argcomplete.readthedocs.io). TAB completion can be enabled one of two ways:

  • Run eval "$(register-python-argcomplete bse)" on the command line

  • Enable globally by running activate-global-python-argcomplete and then sourcing ~/.bash_completion.d/python-argcomplete.sh manually or in .bashrc.

The first method must be run every time a new terminal is opened. For the second method, you can change the path where the python-argcomplete.sh script is installed.

For more details, see the documentation for argcomplete (particularly here and here)

Note that both the register-python-argcomplete and activate-global-python-argcomplete are part of the python argcomplete package and you may need to add the path manually to the PATH environment variable.

General usage

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

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

Description of your program

positional arguments:
  subcommand
    list-formats        Output a list of basis set formats that can be used
                        with obtaining a basis set
    list-writer-formats
                        Output a list available basis set formats that can be
                        written
    list-reader-formats
                        Output a list of basis set formats that can be read
    list-ref-formats    Output a list all available reference formats and
                        descriptions
    list-roles          Output a list all available roles and descriptions
    get-data-dir        Output the default data directory of this package
    list-basis-sets     Output a list all available basis sets and
                        descriptions
    list-families       Output a list all available basis set families
    lookup-by-role      Lookup a companion/auxiliary basis by primary basis
                        and role
    get-basis           Output a formatted basis set
    get-refs            Output references for a basis set
    get-info            Output general info and metadata for a basis set
    get-notes           Output the notes for a basis set
    get-family          Output the family of a basis set
    get-versions        Output a list all available versions of a basis set
    get-family-notes    Get the notes of a family of basis sets
    convert-basis       Convert basis set files from one format to another
    create-bundle       Create a bundle of basis sets

optional arguments:
  -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. By default, the built-in data directory will be used.

$ bse -d ${HOME}/my_data_dir list-basis-sets
bppfakebasis        A fake basis set for testing the BSE
bppfakebasis-jkfit  A fake jkfit basis set for testing the BSE

Also, output can be written to a file rather than to the terminal

$ bse -o /tmp/my_out_file list-basis-sets
$ cat /tmp/my_out_file
2ZaPa-NR                               Double Zeta augmented + polarization (nonrelativistic)
2ZaPa-NR-CV                            Double zeta augmented +polarization (nonrelativistic + core-valence)
3-21G                                  3-21G Split-valence basis set
...

Element strings

Some subcommands take a string specifying which elements the subcommand will work with. This string is a comma-separated list of element symbols and/or Z numbers. Ranges can also be used.

Symbols are not case sensitive and can be mixed with Z-numbers.

Examples:
  • H-Ne - for hydrogen through neon (inclusive)

  • 1-10 - same as above

  • C,8,p-17 - carbon, oxygen, phosphorus through chlorine

Subcommands

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

$ bse get-basis -h
usage: bse get-basis [-h] [--elements ELEMENTS] [--version VERSION]
                     [--noheader] [--unc-gen] [--unc-spdf] [--unc-seg]
                     [--opt-gen] [--make-gen]
                     basis fmt

positional arguments:
  basis                Name of the basis set to output
  fmt                  Which format to output the basis set as
...

list-formats

Lists the available output formats of basis sets. With -n or --no-description, the command will hide the description of the formats.

$ bse list-formats
acesii      ACES II
bdf         BDF
bsedebug    BSE Debug
cfour       CFOUR
cp2k        CP2K
dalton      Dalton
demon2k     deMon2K
gamess_uk   GAMESS UK
gamess_us   GAMESS US
gaussian94  Gaussian
json        JSON
molcas      Molcas
molpro      Molpro
nwchem      NWChem
orca        ORCA
pqs         PQS
psi4        Psi4
qchem       Q-Chem
qcschema    QCSchema
turbomole   Turbomole
xtron       xTron
$ bse list-formats -n
acesii
bdf
bsedebug
cfour
cp2k
dalton
demon2k
gamess_uk
gamess_us
gaussian94
json
molcas
molpro
nwchem
orca
pqs
psi4
qchem
qcschema
turbomole
xtron

list-ref-formats

Lists the available output formats of references. With -n or --no-description, the command will hide the description of the formats.

$ bse list-ref-formats
txt      Plain Text
bib      BibTeX
ris      RIS
endnote  EndNote
json     JSON
$ bse list-ref-formats -n
txt
bib
ris
endnote
json

list-wrtier-formats

Print a list of the formats that can be written to by the library

$ bse list-writer-formats
acesii      ACES II
bdf         BDF
bsedebug    BSE Debug
cfour       CFOUR
cp2k        CP2K
dalton      Dalton
demon2k     deMon2K
gamess_uk   GAMESS UK
gamess_us   GAMESS US
gaussian94  Gaussian
json        JSON
molcas      Molcas
molpro      Molpro
nwchem      NWChem
orca        ORCA
pqs         PQS
psi4        Psi4
qchem       Q-Chem
qcschema    QCSchema
turbomole   Turbomole
xtron       xTron

list-reader-formats

Print a list of the formats that can be read by the library

$ bse list-reader-formats
turbomole   Turbomole
gaussian94  Gaussian94
nwchem      NWChem
dalton      Dalton
molcas      MolCAS
cfour       CFOUR
genbas      Genbas
gbasis      GBasis

list-roles

Lists the available basis set roles. Takes no arguments

$ bse list-roles
orbital  Orbital basis
jfit     J-fitting
jkfit    JK-fitting
rifit    RI-fitting
optri    Optimized RI-fitting
admmfit  Auxiliary-Density Matrix Method Fitting
dftxfit  DFT Exchange Fitting
dftjfit  DFT Correlation Fitting
guess    Initial guess

get-data-dir

Print the default data directory (built into the BSE package)

$ bse get-data-dir
/home/ben/programming/bse_ng/basis_set_exchange/basis_set_exchange/data

list-basis-sets

Lists the available basis sets. This command respects the --data-dir option. With -n or --no-description, the command will hide the description of the basis set.

$ bse list-basis-sets
2ZaPa-NR                               Double Zeta augmented + polarization (nonrelativistic)
2ZaPa-NR-CV                            Double zeta augmented +polarization (nonrelativistic + core-valence)
3-21G                                  3-21G Split-valence basis set
...

Basis sets can be filtered by role, family, or by arbitrary search string (case insensitive). See list-roles and list-families.

$ bse list-basis-sets -r jfit
def2-universal-JFIT  Coulomb fitting auxiliary basis for def2 basis sets
x2c-JFIT             x2c coulomb fitting
...
$ bse list-basis-sets -f pople -s '31g'
4-31G           4-31G valence double-zeta basis set
6-31G           6-31G valence double-zeta
6-31G(2df,p)    6-31G(2df,p)
...

list-families

List all basis set families. This command respects the --data-dir option.

$ bse list-families
acvxz-j
ahlrichs
ahlrichs_dhf
ahlrichs_fit
ahlrichs_x2c
...

lookup-by-role

Find the name of an auxiliary basis set given the primary basis and the desired role.

$ bse lookup-by-role def2-tzvp jfit
def2-universal-jfit

get-basis

Print a formatted basis set from the library. This command has several options. See bse get-basis -h for a complete list.

This subcommand takes two required arguments: the name of the basis set and the format. See list-basis-sets and list-formats.

The main popular option is --elements which takes an element string. See Element strings. By default, all elements for which the basis set is defined are included.

A version of the basis set can be specified with --version. See get-versions for how to list versions available for a basis set.

By default, a descriptive header is included. This may be disabled with --noheader

Some examples:

$ bse get-basis sto-3g nwchem
#----------------------------------------------------------------------
# Basis Set Exchange
# Version v0.8.12+27.g4f1f50f8.dirty
# https://www.basissetexchange.org
#----------------------------------------------------------------------
#   Basis set: STO-3G
# Description: STO-3G Minimal Basis (3 functions/AO)
#        Role: orbital
#     Version: 1  (Data from Gaussian09)
#----------------------------------------------------------------------


BASIS "ao basis" PRINT
#BASIS SET: (3s) -> [1s]
H    S
      0.3425250914E+01       0.1543289673E+00
      0.6239137298E+00       0.5353281423E+00
      0.1688554040E+00       0.4446345422E+00
#BASIS SET: (3s) -> [1s]
He    S
...
$ bse get-basis sto-3g gaussian94 --noheader
H     0
S    3   1.00
      0.3425250914D+01       0.1543289673D+00
      0.6239137298D+00       0.5353281423D+00
      0.1688554040D+00       0.4446345422D+00
****
He     0
S    3   1.00
      0.6362421394D+01       0.1543289673D+00
      0.1158922999D+01       0.5353281423D+00
      0.3136497915D+00       0.4446345422D+00
****
Li     0
S    3   1.00
      0.1611957475D+02       0.1543289673D+00
      0.2936200663D+01       0.5353281423D+00
      0.7946504870D+00       0.4446345422D+00
SP   3   1.00
      0.6362897469D+00      -0.9996722919D-01       0.1559162750D+00
      0.1478600533D+00       0.3995128261D+00       0.6076837186D+00
...
$ bse get-basis sto-3g gaussian94 --elements C,7,11-13 --noheader
C     0
S    3   1.00
      0.7161683735D+02       0.1543289673D+00
      0.1304509632D+02       0.5353281423D+00
      0.3530512160D+01       0.4446345422D+00
SP   3   1.00
      0.2941249355D+01      -0.9996722919D-01       0.1559162750D+00
      0.6834830964D+00       0.3995128261D+00       0.6076837186D+00
      0.2222899159D+00       0.7001154689D+00       0.3919573931D+00
****
...
$ bse get-basis cc-pvtz nwchem --noheader --version 0 --elements C --make-gen
BASIS "ao basis" PRINT
#BASIS SET: (10s,5p,2d,1f) -> [4s,3p,2d,1f]
C    S
   8236.0000000              0.0005310             -0.0001130              0.0000000              0.0000000
   1235.0000000              0.0041080             -0.0008780              0.0000000              0.0000000
    280.8000000              0.0210870             -0.0045400              0.0000000              0.0000000
     79.2700000              0.0818530             -0.0181330              0.0000000              0.0000000
     25.5900000              0.2348170             -0.0557600              0.0000000              0.0000000
      8.9970000              0.4344010             -0.1268950              0.0000000              0.0000000
      3.3190000              0.3461290             -0.1703520              0.0000000              0.0000000
...

get-refs

Print formatted reference info for a basis set.

This subcommand takes two required arguments: the name of the basis set, and the desired reference format. See list-basis-sets and list-ref-formats.

Elements can be restricted with --elements. See Element strings. By default, all elements for which the basis set is defined are included.

A version of the basis set can be specified with --version. See get-versions for how to list versions available for a basis set.

$ bse get-refs def2-tzvp --elements 1 bib
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% If you downloaded data from the basis set
% exchange or used the basis set exchange python library, please cite:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@article{pritchard2019a,
    author = {Pritchard, Benjamin P. and Altarawy, Doaa and Didier, Brett and Gibsom, Tara D. and Windus, Theresa L.},
    title = {A New Basis Set Exchange: An Open, Up-to-date Resource for the Molecular Sciences Community},
    journal = {J. Chem. Inf. Model.},
    volume = {59},
    pages = {4814-4820},
    year = {2019},
    doi = {10.1021/acs.jcim.9b00725}
}

@article{feller1996a,
    author = {Feller, David},
    title = {The role of databases in support of computational chemistry calculations},
    journal = {J. Comput. Chem.},
    volume = {17},
    pages = {1571-1586},
    year = {1996},
    doi = {10.1002/(SICI)1096-987X(199610)17:13<1571::AID-JCC9>3.0.CO;2-P}
}

@article{schuchardt2007a,
    author = {Schuchardt, Karen L. and Didier, Brett T. and Elsethagen, Todd and Sun, Lisong and Gurumoorthi, Vidhya and Chase, Jared and Li, Jun and Windus, Theresa L.},
    title = {Basis Set Exchange: A Community Database for Computational Sciences},
    journal = {J. Chem. Inf. Model.},
    volume = {47},
    pages = {1045-1052},
    year = {2007},
    doi = {10.1021/ci600510j}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% References for the basis set
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% H
%     Common base shells for def2-TZV*
%         weigend2005a
%
%     Additional functions to form def2-TZVP
%         weigend2005a
%


@article{weigend2005a,
    author = {Weigend, Florian and Ahlrichs, Reinhart},
    title = {Balanced basis sets of split valence, triple zeta valence and quadruple zeta valence quality for H to Rn: Design and assessment of accuracy},
    journal = {Phys. Chem. Chem. Phys.},
    volume = {7},
    pages = {3297},
    year = {2005},
    doi = {10.1039/b508541a}
}

get-info

Print some metadata about a basis set. This takes only one required argument (the name of the basis set).

$ bse get-info cc-pvdz
--------------------------------------------------------------------------------
cc-pvdz
--------------------------------------------------------------------------------
    Display Name: cc-pVDZ
     Description: cc-pVDZ
            Role: orbital
          Family: dunning
  Function Types: gto,gto_spherical
  Latest Version: 1

Auxiliary Basis Sets:
    rifit  cc-pvdz-rifit

Versions:
    0  2011-02-14  H-Ar,Ca-Kr  Data from the Original Basis Set Exchange
    1  2018-10-03  H-Ar,Ca-Kr  Data from ccRepo/Grant Hill

get-notes

Print the notes about a basis set. This takes only one required argument (the name of the basis set).

$ bse get-notes sto-3g
--------------------------------------------------------------------------------
   Original BSE Contributor: Dr. David Feller
            Original BSE PI: (none)
 Original BSE Last Modified: Mon, 15 Jan 2007 23:47:11 GMT
--------------------------------------------------------------------------------

Notes from the original BSE
===========================

STO-3G Minimal Basis
--------------------

The exponents and contraction coefficients for the STO-3G basis sets were
obtained by least-squares fitting of Slater-type AO's, with scaling factors
based on optimal values for a variety of molecules.  The s and p exponents for
the valence shell were constrained to be equal.

The original scaling factors for Li, Be and B were superceded by values given
in the paper on second row basis sets.

3s and 3p exponents and contraction coefficients are taken from the work of
Hehre et al. JCP 52, 2769 (1970) while the scaling factors for K, Ca, etc.
come from J. Am. Chem. Soc. 19, 2225 (1980).

Note: Whenever the exponents for transition metals differed between programs
      such as Gaussian and GAMESS or HONDO, the Gaussian exponents were used.
      Attempts to obtain information from W. J. Hehre to arbitrate the
      differences proved unsuccessful. The Gaussian 5d convention was used.

                       STO-3G Atomic Energies
                                                    ROHF
   State  UHF (noneq) ROHF (noneq)  ROHF(equiv)   HF Limit (equiv)
   -----  ----------  -----------   -----------   ---------
H   2-S    -0.466582    -0.466582    -0.466582     -0.50000
He  1-S    -2.807784    -2.807784    -2.807784     -2.86168
Li  2-S    -7.315526    -7.315526    -7.315526     -7.43273
Be  1-S   -14.351880   -14.351880   -14.351880    -14.57302
B   2-P   -24.148989   -24.148989   -24.148989    -24.52906
C   3-P   -37.198393   -37.198393   -37.198393    -37.68862
N   4-S   -53.719010   -53.719010   -53.719010    -54.40094
O   3-P   -73.804150   -73.804150   -73.804150    -74.80940
F   2-P   -97.986505   -97.986505   -97.986505    -99.40935
Ne  1-S  -126.132546  -126.132546  -126.132546   -128.54710
Na  2-S  -159.668424  -159.668211  -159.668211   -161.85891
Mg  1-S  -197.007354  -197.007354  -197.007354   -199.61463
Al  2-P  -238.858362  -238.858358  -238.858358   -241.87671
Si  3-P  -285.466217  -285.466211  -285.466211   -288.85436
P   4-S  -336.868770  -336.868770  -336.868770   -340.71878
S   3-P  -393.130219  -393.130219  -393.130219   -397.50490
Cl  2-P  -454.542192  -454.542192  -454.542192   -459.48207
Ar  1-S  -521.222880  -521.222880  -521.222880   -526.81751
K   2-S  -593.077768  -593.077768  -593.077768   -599.16479
Ca  1-S  -669.988870                             -676.75817
Sc  2-D  -751.993610                             -759.73572
Ti  3-F  -839.555178                             -848.40600
V   4-F  -933.024609                             -942.88433
Cr  7-S -1032.076131                            -1043.35636
Mn  6-S -1137.648436                            -1149.86624
Fe  5-D -1248.758435                            -1262.44366
Co  4-F -1366.389467                            -1381.41454
Ni  3-F -1488.312456                            -1506.87089
Cu  2-S -1618.323760                            -1638.96371
Zn  1-S -1756.295868                            -1777.84810
Ga  2-P -1900.728501                            -1923.26098
Ge  3-P -2051.636259                            -2075.35971
As  4-S -2209.263672                            -2234.23864
Se  3-P -2373.527343                            -2399.86759
Br  2-P -2544.636781                            -2572.44130
Kr  1-S -2722.706000                            -2752.05496
Rb  2-S -2907.604271
Sr  1-S -3099.116725
Y   2-D
Zr  3-F
Nb  4-F

HF Limit values are taken from C. Froese Fischer, The Hartree-Fock Method for
Atoms, A numerical Approach.  (John Wylie and Sons, N.Y., 1977)

get-family

Get the family of the basis set. This takes only one required argument (the name of the basis set).

$ bse get-family cc-pvtz-rifit
dunning_fit

get-versions

Get the available versions of a basis set. This takes only one required argument (the name of the basis set).

With -n or --no-description, the command will hide the description of the version.

$ bse get-versions aug-cc-pvtz
0  Data from the Original Basis Set Exchange
1  Data from ccRepo/Grant Hill
$ bse get-versions aug-cc-pvtz -n
0
1

get-family-notes

Print the notes about a basis set family. This takes only one required argument (the basis set family).

$ bse get-family-notes sto
Notes about STO basis sets
============================

STO basis sets are formed by fitting a set of 2/3/4/5/6 exponents/coefficients to
a corresponding Slater function. A set of elements (first row main group, for example)
will share a set of coefficients and a common set of base exponents which are
multiplied by the square of an element-specific scaling factor.

The data in this library corresponds to that found in Gaussian09. Scaling
factors were taken from the literature and verified by dividing them out
...

create-bundle

See Creating Basis Set Bundles

convert-basis

See Converting basis sets