Skip to content

Commit

Permalink
Merge branch 'main' into feature/d3bj_for_mrcc
Browse files Browse the repository at this point in the history
  • Loading branch information
@foxtran
foxtran authored Sep 25, 2024
2 parents f8b1fd0 + 8bf8349 commit 4939be1
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 94 deletions.
161 changes: 70 additions & 91 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,83 +7,88 @@
[![docs](https://github.com/dftd3/simple-dftd3/actions/workflows/docs.yml/badge.svg)](https://dftd3.github.io/simple-dftd3/)
[![codecov](https://codecov.io/gh/dftd3/simple-dftd3/branch/main/graph/badge.svg)](https://codecov.io/gh/dftd3/simple-dftd3)

A simple drop-in replacement for ``dftd3``.

This program provides a small and easy to use implementation of the DFT-D3
dispersion correction
This package provides a library first implementation of the DFT-D3 dispersion correction
(see [*JCP* **132**, 154104 (2010)](https://dx.doi.org/10.1063/1.3382344)
and [*JCC* **32**, 1456 (2011)](https://dx.doi.org/10.1002/jcc.21759) for details).

It is mostly based on the [`dftd4`](https://github.com/dftd4/dftd4) program and
borrows one or two ideas from the implementation in [`ased3`](https://github.com/ehermes/ased3).
Usable via the command line interface of the [`s-dftd3` executable](man/s-dftd3.1.adoc),
in Fortran via the [`dftd3` module](https://dftd3.readthedocs.io/en/latest/api/fortran.html),
with the C interface by including the [`dftd3.h` header](https://dftd3.readthedocs.io/en/latest/api/c.html),
or in Python by using the [`dftd3` module](https://dftd3.readthedocs.io/en/latest/api/python.html).


## Installation

A full guide for installing this package or building from source can be found in the
[installation guide](https://dftd3.readthedocs.io/en/latest/installation.html).

### Conda package

[![Conda Version](https://img.shields.io/conda/vn/conda-forge/simple-dftd3.svg?label=simple-dftd3)](https://anaconda.org/conda-forge/simple-dftd3)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/dftd3-python.svg?label=dftd3-python)](https://anaconda.org/conda-forge/dftd3-python)

This project is packaged for the *conda* package manager and available on the *conda-forge* channel.
To install the *conda* package manager we recommend the [miniforge](https://github.com/conda-forge/miniforge/releases) installer.
If the *conda-forge* channel is not yet enabled, add it to your channels with
The preferred way of installing this package is from the *conda-forge* distribution via the *mamba* package manager.
To install the *mamba* package manager the [miniforge](https://github.com/conda-forge/miniforge/releases) installer can be used.
If you already have the *mamba* package manager installed add the *conda-forge* channel if it is not yet enabled:

```
conda config --add channels conda-forge
mamba config --add channels conda-forge
```

Once the *conda-forge* channel has been enabled, this project can be installed with:

```
conda install simple-dftd3
mamba install simple-dftd3
```

If you want to enable the Python API as well install

```
conda install dftd3-python
```

It is possible to list all of the versions available on your platform with:

```
conda search simple-dftd3 --channel conda-forge
mamba install dftd3-python
```

Now you are ready to use ``s-dftd3``.


### Building from Source

To build this project from the source code in this repository you need to have
a Fortran compiler supporting Fortran 2008 and one of the supported build systems:
- [meson](https://mesonbuild.com) version 0.55 or newer, with
a build-system backend, *i.e.* [ninja](https://ninja-build.org) version 1.7 or newer
- [cmake](https://cmake.org) version 3.14 or newer, with
a build-system backend, *i.e.* [ninja](https://ninja-build.org) version 1.10 or newer
- [fpm](https://github.com/fortran-lang/fpm) version 0.3.0 or newer
To build this project from the source code in this repository you need a Fortran compiler supporting
at least the Fortran 2008 standard.
If a C compiler is available the C interface tests will be build with this compiler.
For building the Python bindings a C compiler is required to build the Python extension module.

Meson is the primary build system and provides feature-complete functionality of this project.
CMake and fpm support is available but the functionality of the project is limited.
This project is currently tested with GCC 9 on Ubuntu, MacOS and Windows as well as Intel Fortran on Ubuntu.
For building from source the

- [meson](https://mesonbuild.com) version 0.58 or newer, with
a build-system backend, *i.e.* [ninja](https://ninja-build.org) version 1.7 or newer
- [asciidoctor](https://asciidoctor.org/) to build the manual page (optional)
- [FORD](https://forddocs.readthedocs.io/en/stable/) to build the developer documentation (optional)
- Python 3.7 or newer with the [CFFI](https://cffi.readthedocs.io/en/latest/), [NumPy](https://numpy.org/) and [setuptools](https://setuptools.pypa.io/en/latest/index.html) package installed to build the Python API

This project builds on many existing Fortran packages, the following ones are used as dependencies

#### Building with meson
- [mctc-lib](https://github.com/grimme-lab/mctc-lib):
For reading geometry files in a wide range of formats
(like xyz, PBD, mol, SDF, Turbomole, DFTB+, Vasp, FHI-aims, Gaussian, QChem, QCSchema JSON, Chemical JSON)
- [toml-f](https://toml-f.readthedocs.org)
For reading the parameter file with all damping parameters
(see [`assets/`](assets/parameters.toml))
- [mstore](https://github.com/grimme-lab/mstore)
For molecule fixtures to use when defining unit tests
(testing only)
- [test-drive](https://github.com/fortran-lang/test-drive)
Unit testing framework
(testing only)

Optional dependencies are
- asciidoctor to build the manual page
- FORD to build the developer documentation
- Python 3.6 or newer with the CFFI package installed to build the Python API
If these Fortran packages are not available, the build system will automatically fetch them and build
them as part of this project.

Setup a build with
To setup a build use

```
meson setup _build
meson setup _build --prefix=/path/to/install
```

You can select the Fortran compiler by the `FC` environment variable.
You can select the Fortran compiler by the `FC` environment variable, similarly the C compiler is selected from the `CC` environment variable.
To compile and run the projects testsuite use

```
Expand All @@ -93,99 +98,73 @@ meson test -C _build --print-errorlogs
If the testsuite passes you can install with

```
meson configure _build --prefix=/path/to/install
meson install -C _build
```

This might require administrator access depending on the chosen install prefix.

To include ``s-dftd3`` in your project add the following wrap file to your subprojects directory:
Meson is the primary build system and provides feature-complete functionality of this project.
If you for any reason cannot use meson, this project also supports CMake and fpm as build systems.
For more details checkout the [installation guide](https://dftd3.readthedocs.io/en/latest/installation.html#building-from-source).

```ini
[wrap-git]
directory = s-dftd3
url = https://github.com/dftd3/simple-dftd3
revision = head
```

You can retrieve the dependency from the wrap fallback with
## Generating docs

```meson
sdftd3_dep = dependency('s-dftd3', fallback: ['s-dftd3', 'sdftd3_dep'])
```
The documentation is generated using [sphinx](https://www.sphinx-doc.org) for the general documentation and the Python API,
[FORD](https://forddocs.readthedocs.io) for the Fortran API documentation,
and [asciidoctor](https://asciidoctor.org/) for the command line interface manpage.

and add it as dependency to your targets.

### Documentation pages (Sphinx)

#### Building with CMake
[![Documentation](https://readthedocs.org/projects/dftd3/badge/?version=latest)](https://dftd3.readthedocs.io/en/latest/)

Alternatively, this project can be build with CMake (in this case ninja 1.10 or newer is required):
For generating the main documentation pages, install the documentation dependencies with

```
cmake -B _build -G Ninja
pip install -f doc/requirements.txt
```

To compile the project with CMake run
The pages can be built with

```
cmake --build _build
sphinx-build doc _docs -b html
```

You can run the project testsuite with
To view the final pages you can start a HTTP server via

```
pushd _build && ctest && popd
```

To include ``s-dftd3`` in your CMake project retrieve it using the ``FetchContent`` module:

```cmake
if(NOT TARGET s-dftd3)
set("s-dftd3-url" "https://github.com/dftd3/simple-dftd3")
message(STATUS "Retrieving s-dftd3 from ${s-dftd3-url}")
include(FetchContent)
FetchContent_Declare(
"s-dftd3"
GIT_REPOSITORY "${s-dftd3-url}"
GIT_TAG "HEAD"
)
FetchContent_MakeAvailable("s-dftd3")
endif()
python -m http.server -d _docs
```

And link against the ``"s-dftd3"`` interface library.
And open the shown URL in a browser.
The documentation is automatically deployed from the main branch and can be viewed on [readthedocs](https://dftd3.readthedocs.io/).

```cmake
target_link_libraries("${PROJECT_NAME}-lib" PUBLIC "s-dftd3")
```

### API documentation (Ford)

#### Building with fpm
[![docs](https://github.com/dftd3/simple-dftd3/actions/workflows/docs.yml/badge.svg)](https://dftd3.github.io/simple-dftd3/)

Invoke fpm in the project root with
To generate the API documentation of the Fortran library install ford via

```
fpm build
mamba install ford
```

To run the testsuite use
The API documentation can be generated with

```
fpm test
ford docs.md -o _api
```

You can access the ``s-dftd3`` program using the run subcommand
To view the final pages you can start a HTTP server via

```
fpm run -- --help
python -m http.server -d _docs
```

To use ``s-dftd3`` for testing include it as dependency in your package manifest

```toml
[dependencies]
s-dftd3.git = "https://github.com/dftd3/simple-dftd3"
```
And open the shown URL in a browser.
The API documentation is automatically deployed from the main branch and can be viewed on [GitHub pages](https://dftd3.github.io/simple-dftd3).


## Usage
Expand All @@ -201,7 +180,7 @@ In case you want to access the DFT-D3 results from other programs, dump the resu
(the ``--noedisp`` flag prevents the ``.EDISP`` file generation):

```
s-dftd3 --bj pbe0 --atm --json --noedisp --grad struct.xyz
s-dftd3 --bj pbe0 --atm --json --noedisp --grad -- struct.xyz
```

Dispersion related properties can be calculated as well:
Expand Down
6 changes: 3 additions & 3 deletions docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ predocmark: >
source: true
graph: false
sort: alpha
preprocess: false
print_creation_date: true
extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
mctc_io:https://grimme-lab.github.io/mctc-lib/modules/mctc_io.html
Expand Down Expand Up @@ -60,7 +61,7 @@ subroutine calc_dftd3(mol, method, energy, gradient, sigma, error)
type(error_type), allocatable, intent(out) :: error
type(d3_model) :: disp
type(d3_param) :: inp
class(damping_param), allocatable :: param
type(rational_damping_param), allocatable :: param
call get_rational_damping(inp, method, error, s9=1.0_wp)
if (allocated(error)) return
Expand Down Expand Up @@ -222,6 +223,5 @@ Just add it to the dependencies in your `fpm.toml` file:

```toml
[dependencies]
[dependencies.s-dftd3]
git = "https://github.com/dftd3/s-dftd3"
s-dftd3.git = "https://github.com/dftd3/simple-dftd3"
```

0 comments on commit 4939be1

Please sign in to comment.