diff --git a/app/driver.f90 b/app/driver.f90 index bf13f579..1afc0d91 100644 --- a/app/driver.f90 +++ b/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 diff --git a/doc/_static/references.bib b/doc/_static/references.bib index fcd348c4..962ef456 100644 --- a/doc/_static/references.bib +++ b/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 diff --git a/doc/api/c.rst b/doc/api/c.rst index c9835207..fb5e5544 100644 --- a/doc/api/c.rst +++ b/doc/api/c.rst @@ -1,3 +1,5 @@ +.. _c-api: + C API ===== diff --git a/doc/api/fortran.rst b/doc/api/fortran.rst index efad0130..cd385887 100644 --- a/doc/api/fortran.rst +++ b/doc/api/fortran.rst @@ -1,3 +1,5 @@ +.. _fortran-api: + Fortran API =========== diff --git a/doc/comparison.rst b/doc/comparison.rst index 85569032..4ddbdc61 100644 --- a/doc/comparison.rst +++ b/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 --------------------- diff --git a/doc/guide/citing.rst b/doc/guide/citing.rst new file mode 100644 index 00000000..a16d4389 --- /dev/null +++ b/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. diff --git a/doc/guide/index.rst b/doc/guide/index.rst index ce44a03b..54e3066a 100644 --- a/doc/guide/index.rst +++ b/doc/guide/index.rst @@ -6,3 +6,4 @@ This section contains guides on how to use D3 for your applications. .. toctree:: minimal-example + citing diff --git a/doc/index.rst b/doc/index.rst index b6b44d74..ca6f9634 100644 --- a/doc/index.rst +++ b/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 `), + C (:ref:`dftd3.h header `), + Python (:ref:`dftd3 package `), + and via command line (`s-dftd3 executable `__) + + +.. footbibliography:: + .. _s-dftd3: https://github.com/dftd3/simple-dftd3 diff --git a/src/dftd3/citation.f90 b/src/dftd3/citation.f90 index 1857d02a..fe8f7410 100644 --- a/src/dftd3/citation.f90 +++ b/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 \ No newline at end of file +end module dftd3_citation diff --git a/test/validation/02-energy-d3-zero.resp b/test/validation/02-energy-d3-zero.resp index 4e40bc7d..4645d275 100644 --- a/test/validation/02-energy-d3-zero.resp +++ b/test/validation/02-energy-d3-zero.resp @@ -2,5 +2,6 @@ run $ORIGIN/02-ser-xad.gen --zero b3lyp +--citation --noedisp -s