qcserenity 1.6.3.post2

A quantum chemistry program focused on subsystems and embedding

Table of Contents

• Synopsis
• License and Copyright Info
• Download
• Install
  • Installing Precompiled Binaries of the Python Interface
  • Prerequisites For Building From Source
  • Build From Source Using CMake and Make
  • Build From Source Including Python Interface
  • Tests
  • Documentation
  • Troubleshooting:
• User Manual
• Getting Started
• How to Cite Serenity
• Contact
  • Bugs and Feature Requests
  • Other

Synopsis

Serenity is a quantum chemistry code originally developed in the group of Johannes Neugebauer at the University of Münster.
Serenity has a strong focus on quantum chemical subsystem/embedding methods.

License and Copyright Info

Serenity is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Download

The source code is available on Github and on PyPI.

Install

Please read the following instructions carefully.

Installing Precompiled Binaries of the Python Interface

For CPython versions 3.7 - 3.13, wheels are available via PyPI. Just run

pip install qcserenity

which installs the qcserenity python package. Directly in this package are some python utility functions. The pybind11 wrapper to the C++ code resides in a submodule of qcserenity called serenipy. Also see the manual and Getting Started

Prerequisites For Building From Source

The code has been tested and compiled on Linux with GCC/G++ (Versions 7 and newer) and Clang (Versions 8 and newer). Compilation with other compilers such as ICC should be possible on Linux. Old GCC/G++ compilers (4.8.5 or older) are known to be insufficient.

Furthermore, the code has been compiled on macOS using Clang but may experience problems depending on the CPU architecture. Compilation with GCC on macOS should most likely also be possible.

Compilation on and for Windows is not supported at the moment.

The following programs/libraries must be available on your system:

• CMake (Version >= 3.15)
• Boost (for package managers: including boost-devel)
• OpenMP
• Eigen3
• HDF5 (Version >= 1.10.1; including header files and cmake files)
• A recent GMP version, including C++ support (for libint2)
• The standard GNU toolchain (make, tar, autoconf, libtool)

The following libraries will be automatically downloaded and installed together with Serenity (unless SERENITY_DOWNLOAD_DEPENDENCIES=OFF is set):

• libint2 (Version 2.7.0-beta6, pre-configured and hosted at: https://www.uni-muenster.de/Chemie.oc/THCLAB/libint)
• libecpint (v1.0.7 from https://github.com/robashaw/libecpint.git)
• libxc (v6.1.0 from https://gitlab.com/libxc/libxc)
• xcfun (the Serenity version is forked to: https://github.com/qcserenity/xcfun)
• GoogleTest (v1.13.0 from https://github.com/google/googletest.git)

The following libraries are optional and needed for additional features:

• Intel MKL (for SMP parallel Eigen3 eigenvalue solvers)
• Doxygen (for the documentation)
• Python-devel (for the python wrapper)
• pybind11 (for the python wrapper)
• laplace-minimax (for Laplace-Transform MP2/ADC(2)/CC2/GW, commit: '55414f3', https://github.com/bhelmichparis/laplace-minimax.git)

Build From Source Using CMake and Make

Extract or pull the source code, then create a build directory:

cd serenity
mkdir build
cd build

Then run cmake:

cmake ..

To compile Serenity for your specific CPU architecture, you can add:

cmake -DSERENITY_MARCH=native ..

To compile the Laplace-Minimax library, activate the SERENITY_USE_LAPLACE_MINIMAX option.

cmake -DSERENITY_USE_LAPLACE_MINIMAX=ON

(If the build folder is not located inside the main directory of Serenity please adapt the path accordingly.)

Finally run make to build the program:

make

Instead of additionally running make install, you can source serenity.sh located in the main folder (if SERENITY_USAGE_FROM_SOURCE is set, which is the default) to set all necessary environment variables:

cd ..
source serenity.sh

Build From Source Including Python Interface

In order to activate the compilation of a Python interface to the code a flag can be set as follows

cmake -DSERENITY_PYTHON_BINDINGS=ON ..

Additionally this and other flags can be toggled using ccmake

ccmake ..

The wrapper will be built for the Python version that CMake finds first. In order to point CMake to a specific version of Python the following option can be used:

cmake -DPYTHON_EXECUTABLE=/usr/bin/python3 ..

The wrapper is shipped in form of a shared library (serenipy.so). In order for Python to find this package the library folder has to be present in the PYTHONPATH environment variable and the Serenity library has to be present in a path searched by the system for shared libraries. The latter is done when sourcing the serenity.sh script, the former requires to un-comment one line in this file. Afterwards the interface should be importable as follows:

python
import qcserenity.serenipy as spy

Alternatively, if you have the python packages cibuildwheel and scikit-build-core as well as Docker, you can build the python wheels yourself by simply invoking cibuildwheel in the Serenity main folder.

Tests

Serenity comes with a decent set of unittests; in order to run them, source the serenity.sh script and run

serenity_tests

The Python wrapper comes with its own set of tests, these can be run using

python -m unittest discover PATH_TO_SERENITY/qcserenity/tests

or alternatively inside a python environment

from qcserenity.tests import * run_all_tests()

Documentation

After configuring the project using CMake it is possible to create the documentation using:

make doc

Then you can open up the doc/html/index.html in a browser.
The python wrapper is not featured inside the documentation. Its documentation is available via pythons help() function, which displays the built-in doc-strings.

Troubleshooting:

If you run into trouble during the compilation please make sure all required libraries are present and read the output carfully. If you can make sure that your problems are not due to lacking requirements feel free to contact the main developers or preferably open an issue in the repository.

User Manual

The user manual resides in a separate folder (manual) in this repository.

Getting Started

After building from source, test.input lies in the main directory. After sourcing serenity.sh, the first calculation can be performed by running

serenity test.input

which will generate some output and also a folder called hydrogen in the directory from which serenity is executed.

In case qcserenity was installed via pip, the first calculation can be run like this:

python3
from qcserenity.serenipy import *
settings = Settings()
settings.geometry = "data/xyzfiles/h2.xyz"
settings.method = DFT
settings.dft.functional = PBE

sys = System(settings)
scf = ScfTask_R(sys)
scf.run()

How to Cite Serenity

Serenity is published as:

J. P. Unsleber, T. Dresselhaus, K. Klahr, D. Schnieders, M. Böckers, D. Barton and J. Neugebauer,
Serenity: A Subsystem Quantum Chemistry Program,
J. Comput. Chem., 39, 788--798, (2018).

The BibTeX code would thus be:

@article{serenity_pub,
title = {Serenity: A Subsystem Quantum Chemistry Program},
author = {Jan P. Unsleber and Thomas Dresselhaus and Kevin Klahr and David Schnieders and Michael B{"o}ckers and Dennis Barton and Johannes Neugebauer},
journal = {J. Comput. Chem.},
volume = {39},
pages = {788--798},
year = {2018}
}

Please also cite the second publication: N. Niemeyer, P. Eschenbach, M. Bensberg, J. Tölle, L. Hellmann, L. Lampe, A. Massolle, A. Rikus, D. Schnieders, J. P. Unsleber, and J. Neugebauer, The subsystem quantum chemistry program Serenity, Wiley Interdiscip. Rev. Comput. Mol. Sci., 13, e1647, (2023).

The BibTeX code would thus be:

@article{serenity_update, title={The Subsystem Quantum Chemistry Program Serenity}, author={Niemeyer, Niklas and Eschenbach, Patrick and Bensberg, Moritz and T{"o}lle, Johannes and Hellmann, Lars and Lampe, Lukas and Massolle, Anja and Rikus, Anton and Schnieders, David and Unsleber, Jan P and Neugebauer, Johannes}, journal={Wiley Interdiscip. Rev. Comput. Mol. Sci.}, volume={13}, number={3}, pages={e1647}, year={2023}, publisher={Wiley Online Library} }

In order to allow others to reproduce your data and to give credit to all recent developers, please also reference the version of Serenity used by citing the correct code reference generated on Zenodo. The following DOI will always link to the newest version of the code:

10.5281/zenodo.4017420

For specific versions, please use the appropriate DOI.

Serenity relies on a few external libraries. Please cite Libint:
Libint: A library for the evaluation of molecular integrals of many-body operators over Gaussian functions, v2.7.0-beta6 Edward F. Valeev, http://libint.valeyev.net/ .

In case density functionals (for exchange-correlation or kinetic energy) are used, depending on the settings when compiling, please cite either Libxc or XCFun.
Libxc (6.1.0): S. Lehtola, C. Steigemann, M. J.T. Oliveira, and M. A.L. Marques. SoftwareX 7, 1–5 (2018). DOI: 10.1016/j.softx.2017.11.002
XCFun (v2.0.2): Ekström, U. (2020). XCFun: A library of exchange-correlation functionals with arbitrary-order derivatives. Zenodo. https://doi.org/10.5281/zenodo.3946698

Integrals over effective core potentials are provided by Libecpint.
Libecpint (1.0.7) : R. A. Shaw, J. G. Hill, J. Chem. Phys. 147, 074108 (2017); doi: 10.1063/1.4986887

Also, please include the scientific citations for the basis sets and density functionals you use.

Contact

Bugs and Feature Requests

For both bugs and feature requests please use the issue tracker on GitHub.

Other

For other questions, requests or simply to give some feedback feel free to send an e-mail to: [e-mail]