C++ calculators of PDF, bond valence sum and other pair quantities.
libdiffpy is a C++ library for calculating atomic pair distribution function (PDF), bond valence sums, atom overlaps for a hard-sphere model, bond distances and directions up to a specified maximum distance. The atomic structure models are represented by classes for non-periodic, periodic or structures with space group symmetries. libdiffpy supports Crystal and Molecule classes from the ObjCryst crystallographic library. Calculators support two evaluation models - BASIC, which performs a full pair-summation every time, and OPTIMIZED, which updates only pair contributions that have changed since the last evaluation. libdiffpy supports object serialization and parallel computations using parallel map function. PDF calculations can be performed in two modes - either as a real-space summation of peak profiles (PDFCalculator) or as a reciprocal-space Debye summation and Fourier transform of the total scattering structure function (DebyePDFCalculator).
The calculator objects in libdiffpy share a common procedure for iteration over atom pairs and only specialize the processing of pair contributions. New calculator classes can thus be readily defined for any quantity that is obtained by iteration over atom pairs.
A Python interface to libdiffpy is provided by the diffpy.srreal package.
For more information about the libdiffpy library, please consult our online documentation.
If you use libdiffpy in a scientific publication, we would like you to cite this package as
libdiffpy Package, https://github.com/diffpy/libdiffpy
The preferred method is to use Miniconda Python and install from the "conda-forge" channel of Conda packages.
To add "conda-forge" to the conda channels, run the following in a terminal.
conda config --add channels conda-forge
We want to install our packages in a suitable conda environment.
The following creates and activates a new environment named libdiffpy_env
conda create -n libdiffpy_env libdiffpy conda activate libdiffpy_env
To verify the installation, compile and run the included test code examples/testlib.cpp
cd examples c++ testlib.cpp -I$CONDA_PREFIX/include -L$CONDA_PREFIX/lib -Wl,-rpath,$CONDA_PREFIX/lib -ldiffpy ./a.out
The conda package for libdiffpy is built with C++ compilers provided by conda-forge, which may be incompatible with the system C++ compiler. In such case please use the conda-forge C++ compiler to link with libdiffpy.
If you prefer to install from sources, obtain the source archive from
GitHub and cd into your
libdiffpy directory. Create a conda environment with the build
dependencies listed in the requirements folder
conda create -n libdiffpy_env --file requirements/build.txt --file requirements/conda.txt --file requirements/tests.txt conda activate libdiffpy_env
Then build and install libdiffpy into the active conda environment
scons -j4 install
See the output from scons --help for the available build targets and options.
You may consult our online documentation for tutorials and API references.
If you see a bug or want to request a feature, please report it as an issue and/or submit a fix as a PR.
Feel free to fork the project and contribute. When developing it is
preferable to compile with the build=develop option, which compiles the
library without optimizations and with C-assertions checks
scons -j4 build=develop
The library integrity can be verified by executing the unit tests
scons -j4 test
The build script checks for a presence of sconsvars.py file, which
can be used to permanently set the build variable. The SCons
construction environment can be further customized in a sconscript.local
script.
See also the development guide for build variants, running a subset of the unit tests, coverage analysis and testing changes with diffpy.srreal.
To ensure code quality and to prevent accidental commits into the default branch, please set up the use of our pre-commit hooks.
- Install pre-commit in your working environment by running
conda install pre-commit. - Initialize pre-commit (one time only)
pre-commit install.
Thereafter C++ sources will be formatted by clang-format, Python build scripts will be linted by black and isort and checked against flake8, and spelling will be checked by codespell before you can commit. If it fails by clang-format, black or isort, just rerun and it should pass (these hooks modify the files so should pass after they are modified). If the flake8 or codespell checks fail please see the error messages and fix them manually before trying to commit again.
Improvements and fixes are always appreciated.
Before contributing, please read our Code of Conduct.
For more information on libdiffpy please visit the project web-page or email the maintainers Simon Billinge(sbillinge@ucsb.edu).
libdiffpy is an open-source software developed as a part of the DiffPy-CMI complex modeling initiative at the Brookhaven National Laboratory.
libdiffpy is built and maintained with scikit-package.