update dispersion doc (#151)

* update disp doc

* update format

Author: jeanwsr

source/user/dft.rst

@@ -181,22 +181,29 @@ or - as an alternative - the same may be achieved in the following way:
 Dispersion corrections
 ======================
 
-Two main ways exist for adding dispersion (van der Waals) corrections to KS-DFT calculations. One is to augment mean-field results by Grimme's D3 corrections :cite:`DFTD3`, which can be added through an interface to the external library `libdftd3 <https://github.com/cuanto/libdftd3>`_, cf. `dftd3/00-hf_with_dftd3.py <https://github.com/pyscf/pyscf/blob/master/examples/dftd3/00-hf_with_dftd3.py>`_:
-
-  >>> from pyscf import dftd3
-  >>> mf_hf_d3 = dftd3.dftd3(dft.RKS(mol_hf))
-  >>> mf_hf_d3.kernel()
+Adding dispersion (van der Waals) corrections to KS-DFT calculations requires the `pyscf-dispersion <https://github.com/pyscf/dispersion>`_ extension, 
+which implements a simplified interface to `simple-dftd3 <https://github.com/dftd3/simple-dftd3>`_
+and `dftd4 <https://github.com/dftd4/dftd4>`_ libraries. 
+
+It is recommended to enable D3 :cite:`DFTD3`, D4 dispersion corrections through the KS class instantiation. 
+The values of attributes nlc, disp, and xc of KS object are automatically configured in this way. 
+Both the ``mol.KS`` method or ``dft.RKS`` function can be used, 
+cf. `dft/16-dft_d3.py <https://github.com/pyscf/pyscf/blob/master/examples/dft/16-dft_d3.py>`_:
+
+  >>> mf_d3 = mol_hf.KS(xc='wb97x-d4')
+  >>> #mf_d3 = mol_hf.KS(xc='b3lyp-d3bj')
+  >>> #mf_d3 = mol_hf.KS(xc='b3lyp-d3zero')
+  >>> mf_d3.kernel()
 
-Alternatively, non-local correlation may be added through the VV10 functional :cite:`vydrov_voorhis_vv10_functional_jcp_2010`, cf. `dft/33-nlc_functionals.py <https://github.com/pyscf/pyscf/blob/master/examples/dft/33-nlc_functionals.py>`_:
-
-  >>> mf_hf.xc = 'wb97m_v'
-  >>> mf_hf.nlc = 'vv10'
-  >>> mf_hf.grids.atom_grid = {'H': (99, 590), 'F': (99, 590)}
-  >>> mf_hf.grids.prune = None
-  >>> mf_hf.nlcgrids.atom_grid = {'H': (50, 194), 'F': (50, 194)}
-  >>> mf_hf.nlcgrids.prune = dft.gen_grid.sg1_prune
-  >>> mf_hf.kernel()
+Alternatively, non-local correlation may be added through the VV10 functional :cite:`vydrov_voorhis_vv10_functional_jcp_2010`, 
+cf. `dft/33-nlc_functionals.py <https://github.com/pyscf/pyscf/blob/master/examples/dft/33-nlc_functionals.py>`_:
+
+  >>> mf_nlc = dft.RKS(mol_hf)
+  >>> mf_nlc.xc = 'wb97m_v'
+  >>> mf_nlc.kernel()
 
+See `dft/33-nlc_functionals.py <https://github.com/pyscf/pyscf/blob/master/examples/dft/33-nlc_functionals.py>`_ 
+for more examples of setting the ``nlc`` and ``nlcgrids`` attribute.
 It's important to keep in mind that the evaluation of the VV10 functional involves a double grid integration, so differences in grid size can make an enormous difference in time.
 
 .. _user_dft_collinear:

source/user/scf.rst

@@ -318,8 +318,10 @@ Spin-restricted, spin-unrestricted, restricted open-shell, and generalized calcu
 
 The general spin-orbital used in the HF or KS-DFT wave function can be
 written as
-    .. math::
-        \psi_i(1) = \phi_{i\alpha}(r)\alpha + \phi_{i\beta}(r)\beta \;,
+
+.. math::
+    
+    \psi_i(1) = \phi_{i\alpha}(r)\alpha + \phi_{i\beta}(r)\beta \;,
 
 Four variants of the ansatz :math:`\psi(1)` are commonly used in
 quantum chemistry; they are also all available in PySCF.