From 078811ae8235c84f6d2c540872e0ea2ae568e241 Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Wed, 13 May 2026 09:05:54 -0700 Subject: [PATCH 1/4] Add dispersion doc page --- source/user/dft.rst | 7 +++ source/user/dispersion.md | 113 ++++++++++++++++++++++++++++++++++++++ source/user/pbc/scf.rst | 2 +- 3 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 source/user/dispersion.md diff --git a/source/user/dft.rst b/source/user/dft.rst index 38f7ee030..46f24fdb5 100644 --- a/source/user/dft.rst +++ b/source/user/dft.rst @@ -61,6 +61,13 @@ For complete lists of the available density functional approximations, the user The constant maintenance and development of density functional libraries is hard work at little personal benefit, while everyone benefits from having a huge variety of density functionals in numerically stable form for use in applications. If you use Libxc in your calculations, please cite the most up-to-date work on Libxc in your paper. You can see the most up-to-date citation on the `Libxc web page `_; at the moment, this is :cite:`lehtola_libxc_softwarex_2018`. Likewise, if you use XCFun in your calculations, please cite the most up-to-date work on XCFun in your paper. You can find recent citations on the `XCFun web page `_; at present, this is :cite:`ekstroem_xcfun_jctc_2010`. Please check your log files for the library used in your calculation (you may need to increase the ``DFT.verbose`` setting of your calculation to see this). +Dispersion Corrections +---------------------- +Dispersion corrections can be specified through the ``xc`` keyword. For example, ``'wb97x-d3bj'`` enables the ``wb97x`` functional with the ``d3bj`` dispersion correction. + +More details on the dispersion keyword conventions are provided in :doc:`dispersion`. + + .. _user_dft_custom_func: Customizing *xc* functionals diff --git a/source/user/dispersion.md b/source/user/dispersion.md new file mode 100644 index 000000000..2cf2de02c --- /dev/null +++ b/source/user/dispersion.md @@ -0,0 +1,113 @@ +# Dispersion Convention + +Dispersion corrections in DFT can be enabled either: + +1. implicitly through the `xc` functional string, +2. or explicitly through the `disp` keyword. + +The explicit `disp` keyword always takes precedence over the dispersion information encoded in `xc`. + +## Enabling Dispersion through `xc` + +Some functionals encode the dispersion model directly in the XC name. For examples, +``` +mf.xc = 'wb97x-d3bj' +mf.xc = 'wb97x-d4' +mf.xc = 'wb97x-3c' +``` +These automatically enable dispersion corrections. + +When calling the dispersion module, the `xc` attribute is parsed and normalized to the internal representation `(disp_method, disp_version, with_3body)`. For example, + +|xc |Parsed dispersion | +|-------------|-------------------------| +|'b3lyp' |no dispersion | +|'wb97x-d3bj' |('wb97x', 'd3bj', False) | +|'wb97x-d4' |('wb97x', 'd4', True) | +|'wb97x-3c' |('wb97x-3c', 'd4', True) | + +## Enabling Dispersion through `disp` + +Dispersion can also be enabled explicitly through the `disp` attribute: +``` +mf.xc = 'b3lyp' +mf.disp = 'd3bj' +``` +This corresponds to `('b3lyp', 'd3bj', False)`. + +The disp keyword overrides any dispersion setting implied by xc. For example, +``` +mf.xc = 'wb97x-d3bj' +mf.disp = 'd4' +``` +This uses D4 dispersion instead of D3(BJ). + +## 2-Body vs 3-Body Convention +Internally, the normalized representation separates the dispersion version and +the 3-body flag. Rules: +* suffix 2b disables the 3-body term, +* suffix atm enables the ATM 3-body term, +* D4 always includes the 3-body contribution. + +For example, +``` +mf.disp = 'd3bj2b' # D3(BJ), pairwise only +mf.disp = 'd3bjatm' # D3(BJ) + ATM +``` + +## Custom Dispersion Parameterization +The dispersion version can be specified using the syntax +``` +disp_version:method +``` + +For example, +``` +mf.disp = 'd4:wb97x-3c' +``` +employs DFTD4 dispersion and passes `wb97x-3c` as the DFT functional name to the underlying dispersion library. +In the internal representation (returned by `parse_disp` function), this +setting leads to `('wb97x-3c', 'd4', True)`. +Another example, +``` +mf.disp = 'd3bj:pbe' +``` +corresponds to `('pbe', 'd3bj', False)`. + +## Examples +* No dispersion +``` +mf.xc = 'pbe' +mf.disp = None +``` + +* Implicit dispersion from XC +``` +mf.xc = 'wb97x-d3bj' +mf.disp = None +``` +This setting enables `d3bj` type of dispersion parameterized for the `wb97x` functional. + +* Explicit dispersion +``` +mf.xc = 'b3lyp' +mf.disp = 'd3bj' +``` +This setting leads to `d3bj` type of dispersion parameterized for the `b3lyp` functional. + +* Three-body ATM term +``` +mf.xc = 'b3lyp' +mf.disp = 'd3bjatm' +``` +This setting provides `d3bj` dispersion with 3-body contribution for the `b3lyp` functional. + +* Explicit dispersion version +``` +mf.xc = 'scan' +mf.disp = 'd4:pbe' +``` +This setting ignores the `xc` attribute and uses `d4` dispersion parameterized +for the `pbe` functional. + + diff --git a/source/user/pbc/scf.rst b/source/user/pbc/scf.rst index 48f0647f6..2161523d8 100644 --- a/source/user/pbc/scf.rst +++ b/source/user/pbc/scf.rst @@ -257,7 +257,7 @@ Multi-grid 5000 N/A RS 1000 1000 ============= ================ ================ -3. Relative performance for systems of 100 AOs per unit cell, 10 k-points +3. Relative costs for systems of 100 AOs per unit cell, 10 k-points ============= ================ ================ Scheme Pure DFT hybrid DFT From bb623fe6b40b07533ee5df04e20be073aa40e435 Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 14 May 2026 08:54:13 -0700 Subject: [PATCH 2/4] Remove wb97x-3c --- source/user/dispersion.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/source/user/dispersion.md b/source/user/dispersion.md index 2cf2de02c..c34565744 100644 --- a/source/user/dispersion.md +++ b/source/user/dispersion.md @@ -13,7 +13,6 @@ Some functionals encode the dispersion model directly in the XC name. For exampl ``` mf.xc = 'wb97x-d3bj' mf.xc = 'wb97x-d4' -mf.xc = 'wb97x-3c' ``` These automatically enable dispersion corrections. @@ -24,7 +23,6 @@ When calling the dispersion module, the `xc` attribute is parsed and normalized |'b3lyp' |no dispersion | |'wb97x-d3bj' |('wb97x', 'd3bj', False) | |'wb97x-d4' |('wb97x', 'd4', True) | -|'wb97x-3c' |('wb97x-3c', 'd4', True) | ## Enabling Dispersion through `disp` @@ -63,11 +61,11 @@ disp_version:method For example, ``` -mf.disp = 'd4:wb97x-3c' +mf.disp = 'd4:pbe0' ``` -employs DFTD4 dispersion and passes `wb97x-3c` as the DFT functional name to the underlying dispersion library. +employs DFTD4 dispersion and passes `pbe0` as the DFT functional name to the underlying dispersion library. In the internal representation (returned by `parse_disp` function), this -setting leads to `('wb97x-3c', 'd4', True)`. +setting leads to `('pbe0', 'd4', True)`. Another example, ``` mf.disp = 'd3bj:pbe' From 9390e911dda48981aaaf4a6c7ac266c7ab80bf6f Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 14 May 2026 08:54:28 -0700 Subject: [PATCH 3/4] Merge "Dispersion Corrections" section in dft.rst --- source/user/dft.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/source/user/dft.rst b/source/user/dft.rst index 46f24fdb5..e9424ab97 100644 --- a/source/user/dft.rst +++ b/source/user/dft.rst @@ -61,12 +61,6 @@ For complete lists of the available density functional approximations, the user The constant maintenance and development of density functional libraries is hard work at little personal benefit, while everyone benefits from having a huge variety of density functionals in numerically stable form for use in applications. If you use Libxc in your calculations, please cite the most up-to-date work on Libxc in your paper. You can see the most up-to-date citation on the `Libxc web page `_; at the moment, this is :cite:`lehtola_libxc_softwarex_2018`. Likewise, if you use XCFun in your calculations, please cite the most up-to-date work on XCFun in your paper. You can find recent citations on the `XCFun web page `_; at present, this is :cite:`ekstroem_xcfun_jctc_2010`. Please check your log files for the library used in your calculation (you may need to increase the ``DFT.verbose`` setting of your calculation to see this). -Dispersion Corrections ----------------------- -Dispersion corrections can be specified through the ``xc`` keyword. For example, ``'wb97x-d3bj'`` enables the ``wb97x`` functional with the ``d3bj`` dispersion correction. - -More details on the dispersion keyword conventions are provided in :doc:`dispersion`. - .. _user_dft_custom_func: @@ -201,6 +195,8 @@ cf. `dft/16-dft_d3.py >> #mf_d3 = mol_hf.KS(xc='b3lyp-d3bj') >>> #mf_d3 = mol_hf.KS(xc='b3lyp-d3zero') >>> mf_d3.kernel() + +More details on the dispersion keyword conventions are provided in :doc:`dispersion`. Alternatively, non-local correlation may be added through the VV10 functional :cite:`vydrov_voorhis_vv10_functional_jcp_2010`, cf. `dft/33-nlc_functionals.py `_: From 91104d158b60ecac5845d8ec8698c7ed165d562f Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 14 May 2026 08:58:49 -0700 Subject: [PATCH 4/4] Update description of the three-body contribution --- source/user/dispersion.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/user/dispersion.md b/source/user/dispersion.md index c34565744..0347f22af 100644 --- a/source/user/dispersion.md +++ b/source/user/dispersion.md @@ -41,11 +41,11 @@ mf.disp = 'd4' This uses D4 dispersion instead of D3(BJ). ## 2-Body vs 3-Body Convention -Internally, the normalized representation separates the dispersion version and -the 3-body flag. Rules: -* suffix 2b disables the 3-body term, -* suffix atm enables the ATM 3-body term, -* D4 always includes the 3-body contribution. +Internally, the normalized representation separates the dispersion version from +the 3-body flag. By default, D4 includes the 3-body contribution, whereas D3 +does not. They can both be adjusted by suffix 2b and atm: +* suffix 2b disables the 3-body term; +* suffix atm enables the ATM 3-body term. For example, ```