Python program for calculation of numerical derivatives in conjunction with ORCA. While in the long term, this program is supposed to enable a broader range of numerical derivative applications, it is currently fixed to numerical derivatives associated with the q-vSZP basis set.
numgradpy
in its current state depends on existing installations of
- the
qvSZP
Fortran program for setting up ORCA input files with the q-vSZP basis set (for details and installation instructions, see github.com/grimme-lab/qvSZP) - the
ORCA
quantum chemistry package in version >= 5.0.3. For further details and installation instructions, see ORCA input library
After cloning the code via git clone [email protected]:grimme-lab/NumgradPy.git
, a new virtual conda
environment with required pre-requisites can be set up with:
conda env create -f environment.yml
conda activate numgradpy
numgradpy
can be installed into this environment with
pip install -e .
The flag -e
allows modification of the code without the need to reinstall.
Before using the program, a global configuration file ~/.numgradpyrc
should be generated. This is required for user-individual paths for basis sets and the ORCA installation. It could look as follows:
$qvszp
mpi=1
guess=hueckel
conv=VeryTightSCF
efile=/home/XXX/source/qvSZP/q-vSZP_basis/ecpq
bfile=/home/XXX/source/qvSZP/q-vSZP_basis/basisq
$orca
path=/home/XXX/app/orca504
$end
After installation, the package can be used to calculate different types of numerical derivatives. Currently available are nuclear gradients (dE/dR, -g
), dipole moments (dE/dF, -d
), and polarizabilities (dµ/dF, -a
) (with E = electronic energy; F = external electric field; µ = electric dipole moment).
The desired type of gradient can be chosen with the corresponding flag.
Two flags are required for execution. The first is the type of binary, which is used to generate the ORCA input files (here always: -b qvSZP
), and the second is the desired molecular structure -s <file>
.
A typical command-line call for a polarizability calculation with a finite-field step size of 0.0001 a.u. would look as follows:
numgradpy -b qvSZP -s lih.xyz -a -f 0.0001
The result of each derivative calculation is saved in a common text file format to disk. Further documentation is provided via the -h/--help
flag.
By default, numgradpy
runs the ORCA single-point calculations in parallel with one core per execution. This setting can be modified via the mpi
setting in the ~/.numgradpyrc
configuration file.
All of the source code is in the src/numgradpy directory. Here, also some dunder files can be found:
- __version__.py: just the version number as a string, used by config files
- __init__.py: entry point for program/library
- __main__.py: same as
__init__.py
allowing calls viapython -m <prog>
Packaging is done with setuptools
, which is configured through the pyproject.toml
and/or setup.cfg
/setup.py
files.
pyproject.toml
vs.
setup.cfg
vs
setup.py
The setup.py
file is a Python script, and configuration is passed through keyword arguments of setuptools.setup()
. This is not recommended due to possible security and parsing issues. The same setup can be accomplished in a declarative style within setup.cfg
, and setup.py
remains mostly empty only calling setuptools.setup()
.
The pyproject.toml
file aims to unify configuration files including various tools like black or pytest. For packaging, it is very similar to setup.cfg
. However, pyproject.toml
has not been adopted as the default yet, and many projects still use setup.cfg
to declare the packaging setup. Note that setup.py
is not necessary if a pyproject.toml
is present.
- minimal build specification to use with setuptools
- configuration of other tools (black, pytest, mypy, ...)
- declarative configuration for setuptools
- metadata: must at least contain name and version
- options: package discovery, dependencies
- additional setup required for
src/
layout
- additional setup required for
- options.extras_require: optional dependencies (dev tools, docs, ...)
- options.package_data: inclusion of other, non-Python files (marker files, data, ...)
- alternative:
MANIFEST.in
- alternative:
- options.entry_points: entry point for command line interface
- can also hold configuration of other tools
The package can be installed with pip install .
or something like pip install .[dev]
to also install additional dependencies specified in setup.cfg
's options.extras_require. Pass the -e
flag for editable mode, which loads the package from the source directory, i.e., changing the source code does not require a new installation.