Update references (#129)

app/driver.f90

@@ -32,7 +32,7 @@ module dftd3_app_driver
       & turbomole_gradient, turbomole_gradlatt, ascii_gcp_param
    use dftd3_utils, only : wrap_to_central_cell
    use dftd3_citation, only : format_bibtex, is_citation_present, citation_type, &
-      & get_citation, doi_dftd3_0, doi_dftd3_bj, doi_dftd3_m, doi_dftd3_op, same_citation
+      & get_citation, doi_dftd3_0, doi_dftd3_bj, doi_dftd3_m, doi_dftd3_op, doi_joss, same_citation
    use dftd3_app_help, only : header
    use dftd3_app_cli, only : app_config, run_config, param_config, gcp_config, get_arguments
    use dftd3_app_toml, only : param_database
@@ -256,6 +256,8 @@ subroutine run_driver(config, error)
 
    if (config%citation) then
       open(file=config%citation_output, newunit=unit)
+      call format_bibtex(output, get_citation(doi_joss))
+      if (allocated(output)) write(unit, '(a)') output
       if (.not.same_citation(citation, param_citation)) then
          call format_bibtex(output, citation)
          if (allocated(output)) write(unit, '(a)') output

doc/_static/references.bib

@@ -1,3 +1,16 @@
+@article{ehlert2024,
+   title = {Simple DFT-D3: Library first implementation of the D3 dispersion correction},
+   author = {Sebastian Ehlert},
+   year = {2024},
+   publisher = {The Open Journal},
+   volume = {9},
+   number = {103},
+   pages = {7169},
+   journal = {Journal of Open Source Software},
+   doi = {10.21105/joss.07169},
+   url = {https://doi.org/10.21105/joss.07169},
+}
+
 @article{grimme2010,
    author = {S. Grimme and J. Antony and S. Ehrlich and H. Krieg},
    title = {A consistent and accurate ab initio parametrization of density functional

doc/api/c.rst

@@ -1,3 +1,5 @@
+.. _c-api:
+
 C API
 =====
 

doc/api/fortran.rst

@@ -1,3 +1,5 @@
+.. _fortran-api:
+
 Fortran API
 ===========
 

doc/comparison.rst

@@ -39,6 +39,7 @@ A non-comprehensive list of DFT-D3 implementations is provided here:
 
 Many more versions are probably around or redistributed in various quantum chemistry programs.
 
+.. _users:
 
 Users of this library
 ---------------------

doc/guide/citing.rst

@@ -0,0 +1,86 @@
+Suggesting references for D3 dispersion corrections
+---------------------------------------------------
+
+The D3 dispersion correction was originally introduced as D3(0)\ :footcite:`grimme2010` and later extended to D3(BJ).\ :footcite:`grimme2011`
+Additional damping functions and parametrizations for new functionals have been introduced in the literature over time.
+Providing proper attribution to the method, parameters and software can be challenging to keep up with.
+The *s-dftd3* library keeps track of the references for each method and parameter set, and provides an option to suggest the used references.
+
+For example when running a computation with SCAN-D3(BJ), we can use the following command to get the suggested references:
+
+.. code-block:: text
+
+   s-dftd3 structure.xyz --bj scan --citation
+
+In the output we will see
+
+.. code-block:: text
+
+   -----------------------------------
+    s i m p l e   D F T - D 3  v1.2.1
+   -----------------------------------
+
+   Rational (Becke-Johnson) damping: scan-D3(BJ)
+   ---------------------
+     s6         1.0000
+     s8         0.0000
+     s9         0.0000
+     a1         0.5380
+     a2         5.4200
+    alp        14.0000
+   --------------------
+
+   Dispersion energy:      -1.0554287327920E-02 Eh
+
+   [Info] Writing Dispersion energy to '.EDISP'
+   [Info] Citation information written to 'dftd3.bib'
+
+Inspecting this file shows three suggested references, here first the citation for the library itself used to perform the calculation, second the original publication of the D3(BJ) method and finally the publication introducing parameters for the SCAN functional.
+
+.. code-block:: bib
+   :caption: dftd3.bib
+
+   @article{10.21105/joss.07169,
+     title = {{Simple DFT-D3: Library first implementation of the D3 dispersion correction}},
+     author = {Sebastian Ehlert},
+     issue = {103},
+     volume = {9},
+     pages = {7169},
+     doi = {10.21105/joss.07169},
+     url = {https://doi.org/10.21105/joss.07169}
+   }
+   @article{10.1002/jcc.21759,
+     title = {{Effect of the damping function in dispersion corrected density functional theory}},
+     author = {Stefan Grimme
+       and Stephan Ehrlich
+       and Lars Goerigk},
+     issue = {7},
+     volume = {32},
+     pages = {1456-1465},
+     doi = {10.1002/jcc.21759},
+     url = {https://doi.org/10.1002/jcc.21759}
+   }
+   @article{10.1103/physrevb.94.115144,
+     title = {{Benchmark tests of a strongly constrained semilocal functional with a  long-range dispersion correction}},
+     author = {J. G. Brandenburg
+       and J. E. Bates
+       and J. Sun
+       and J. P. Perdew},
+     volume = {94},
+     pages = {115144},
+     doi = {10.1103/physrevb.94.115144},
+     url = {https://doi.org/10.1103/physrevb.94.115144}
+   }
+
+In the computational details section in a publication using SCAN-D3(BJ) we can now refer to these publications for example as
+
+.. code-block:: tex
+
+   The D3(BJ) dispersion correction\cite{10.1002/jcc.21759} for
+   SCAN-D3(BJ)\cite{10.1002/jcc.21759} was calculated
+   using the s-dftd3 library (version 1.2.1).\cite{10.21105/joss.07169}
+
+.. important::
+
+   The suggested references are based on the information available in the library.
+   Always check the original publications for the most recent references and the correct citation.

doc/guide/index.rst

@@ -6,3 +6,4 @@ This section contains guides on how to use D3 for your applications.
 .. toctree::
 
    minimal-example
+   citing

doc/index.rst

@@ -1,10 +1,28 @@
 Reimplementation of D3 dispersion correction
 ============================================
 
-This pages describe the usage and functionality of `s-dftd3`_ reimplementation of the D3 dispersion correction and geometric counter-poise correction.
-The *s-dftd3* project aims to provide a user-friendly and uniform interface to the D3 dispersion model and for the calculation of DFT-D3 dispersion corrections.
+This pages describe the library first implementation of the DFT-D3 dispersion correction, in the `s-dftd3`_ software package.\ :footcite:`ehlert2024`.
+This project aims to provide a user-friendly and uniform interface to the D3 dispersion model and for the calculation of DFT-D3 dispersion corrections.
 Additionally, it provides the geometric counter-poise correction to create composite electronic structure methods of the 3c family.
 
+Supported features include:
+
+- Rational damping function, D3(BJ).\ :footcite:`grimme2011`
+- Zero damping function D3(0).\ :footcite:`grimme2010`
+- Modified rational and zero damping functions, D3M(BJ) and D3M(0).\ :footcite:`smith2016`
+- Optimized power damping function, D3(op).\ :footcite:`witte2017`
+- Axilrod-Teller-Muto three-center contribution.
+- Pairwise analysis of dispersion contributions.
+- Extensive parameter support for (almost) all published D3 parameters.
+- Geometric counter-poise correction and short-range bond correction.\ :footcite:`kruse2012`
+- Readily available in Fortran (:ref:`dftd3 module <fortran-api>`),
+  C (:ref:`dftd3.h header <c-api>`),
+  Python (:ref:`dftd3 package <python>`),
+  and via command line (`s-dftd3 executable <https://github.com/dftd3/simple-dftd3/blob/main/man/s-dftd3.1.adoc>`__)
+
+
+.. footbibliography::
+
 
 .. _s-dftd3: https://github.com/dftd3/simple-dftd3
 

src/dftd3/citation.f90

@@ -26,7 +26,7 @@ module dftd3_citation
       & doi_drpa, doi_revdsd, doi_pw91_d3, doi_r2scan_d4, doi_scan_d3, &
       & doi_pbeh3c, doi_hse3c, doi_b973c, doi_hf3c, doi_gcp, doi_d3pbc, &
       & doi_r2scan_hyb, doi_r2scan_dhdf, doi_minnesota_d3, doi_b97m_d3, &
-      & doi_wb97x_d3, doi_hse06_d3
+      & doi_wb97x_d3, doi_hse06_d3, doi_joss
 
    !> Represents an author to allow creating author lists
    type :: author_type
@@ -82,7 +82,8 @@ module dftd3_citation
       & doi_minnesota_d3 = "10.1021/acs.jpclett.5b01591", &
       & doi_b97m_d3 = "10.1021/acs.jctc.8b00842", &
       & doi_wb97x_d3 = "10.1021/ct300715s", &
-      & doi_hse06_d3 = "10.1021/jp501237c"
+      & doi_hse06_d3 = "10.1021/jp501237c", &
+      & doi_joss = "10.21105/joss.07169"
 
 contains
 
@@ -605,7 +606,20 @@ pure function get_citation(doi) result(citation)
          pages="7615-7621", &
          year="2014" &
       )
+
+   case(doi_joss)
+      citation = new_citation( &
+         doi=doi, &
+         title="Simple DFT-D3: Library first implementation of the D3 dispersion correction", &
+         author=[ &
+         & author_name("Sebastian Ehlert")], &
+         journal="J. Open Source Softw.", &
+         issue="103", &
+         volume="9", &
+         pages="7169", &
+         year="2024" &
+      )
    end select
 end function get_citation
 
-end module dftd3_citation
+end module dftd3_citation

test/validation/02-energy-d3-zero.resp

@@ -2,5 +2,6 @@ run
 $ORIGIN/02-ser-xad.gen
 --zero
 b3lyp
+--citation
 --noedisp
 -s