Update docs for Method Instantiation

source/user/gto.rst

@@ -603,3 +603,106 @@ to obtain the one- and two-electron AO integrals::
   eri = mol.intor('int2e')
 
 For a full list of supported AO integrals, see :ref:`pyscf.gto.moleintor module`.
+
+
+Initializing Mean-Field and Post-SCF Methods
+============================================
+
+In PySCF, both mean-field and post-SCF methods are provided as classes (see also
+:doc:`using`). These classes can be imported and instantiated just like standard
+Python modules and functions. However, this requires users to remember the
+specific paths to these modules or classes. To simplify the initialization
+process, PySCF provides a convenient shortcut for initializing a mean-field or
+post-SCF method instance directly from the `Mole` instance.
+
+Instantiating Mean-Field Methods
+--------------------------------
+Mean-field methods can be easily instantiated as follows::
+
+  mf = mol.HF()
+  mf = mol.KS()
+
+This approach automatically determines the appropriate mean-field method to use,
+such as restricted closed-shell, open-shell, or symmetry-adapted methods. By
+default:
+* Restricted closed-shell methods are used for molecules without unpaired electrons (`mol.spin=0`).
+* Unrestricted methods (UHF, UKS) are used for molecules with unpaired electrons (`mol.spin > 0`).
+* Symmetry-adapted methods are used if `mol.symmetry` is enabled.
+
+Explicit Mean-field Methods
+---------------------------
+
+For more specific method instantiation, such as RHF, UKS, or GKS, the following can be used:
+
+* `mol.RHF()` and `mol.RKS()` creates restricted Hartree-Fock or Kohn-Sham
+  methods. It can be used for molecules with unpaired electrons, leading to ROHF
+  and ROKS methods.
+
+* `mol.ROHF()` and `mol.ROKS()` are applicable to molecules with `mol.spin=0`.
+  They create restricted open-shell HF or KS methods, even though these systems
+  can be modeled by restricted closed-shell methods.
+
+* `mol.UHF()` and `mol.UKS()` create unrestricted Hartree-Fock or Kohn-Sham
+  methods, regardless of the number of unpaired electrons in the molecule.
+
+* `mol.GHF()` and `mol.GKS()` create generalized mean-field methods, which
+  allow for the mixing of alpha and beta spins in the spin-orbitals.
+
+* `mol.DHF()` and `mol.DKS()` create four-component Dirac-Coulomb mean-field methods.
+
+Keyword Parameters for Mean-field Methods
+-----------------------------------------
+When creating mean-field methods, their configuration parameters such as
+`conv_tol` and `max_cycle` can be specified through keyword arguments of the
+instantiation methods. For example, in DFT methods, the exchange-correlation
+(XC) functional can be specified using the `xc` keyword argument::
+
+  mf = mol.RKS(xc='b3lyp', conv_tol=1e-6)
+  mf = mol.GKS(xc='pbe,p86')
+
+Instantiating Post-SCF Methods
+------------------------------
+Post-SCF methods can be instantiated on top of a mean-field instance::
+
+  mf = mol.HF().run()
+  mycc = mf.CCSD()
+
+Alternatively, you can bypass the creation of the mean-field instance and
+directly apply the post-SCF method on the `Mole` instance::
+
+  mycc = mol.CCSD(frozen=1)
+
+This approach automatically creates a mean-field instance and applies the
+post-SCF method. Any keyword arguments for the post-SCF methods will be passed
+to the `mf.CCSD()` method. It is important to note that, unlike the
+initialization of mean-field methods, configurational parameters for post-SCF
+methods cannot be set through keyword arguments. They must be explicitly
+assigned to the post-SCF instance. For example, the initialization statement
+`mol.CCSD(conv_tol=1e-5)` will fail.
+
+MCSCF Methods
+-------------
+
+The initialization of MCSCF methods is similar to that of post-SCF methods. You
+can first create a mean-field instance and then apply a MCSCF method. Applying
+MCSCF methods directly on the `Mole` instance will also automatically
+create a mean-field instance and apply the MCSCF method::
+
+  norb_cas, nelec_cas = 6, 8
+  mycas = mol.CASSCF(norb_cas, nelec_cas)
+
+TDDFT Methods
+-------------
+Like post-SCF methods, TDDFT can be instantiated based on a mean-field instance.
+When creating a TDDFT method from the `Mole` instance, the XC functional can be
+specified as a keyword argument::
+
+  mytd = mol.TDA(xc='pbe')
+  mytd = mol.TDDFT(xc='pbe')
+
+Alternatively, the XC functional can be specified as part of the TDDFT function name:
+
+    mytd = mol.TDB3LYP() # == mol.TDA(xc='B3LYP')
+    mytd = mol.TDPBE() # == mol.TDA(xc='PBE')
+
+This API will create a TDA method with the specified XC functional.

source/user/pbcgto.md

@@ -218,3 +218,92 @@ eri = df.DF(cell).get_eri()
 ```
 See [Periodic density fitting](pbc/df) for more details.
 
+
+## Initializing Mean-Field and Post-SCF Methods
+
+Mean-field and post-SCF methods can be initialized directly from the `Cell` instance.
+
+### Instantiating Mean-Field Methods
+For single k-point mean-field methods, you can pass the k-point to the `cell.HF`
+or `cell.KS` methods.
+
+```python
+kpt = np.array([0., 0., 0.])
+mf = cell.HF(kpt=kpt)
+mf = cell.KS(kpt=kpt)
+```
+
+To create mean-field methods with a k-point mesh, the HF and KS methods are
+prefixed with "K". The k-points should be created and passed to these K-prefixed
+mean-field methods.
+
+```python
+kpts = cell.make_kpts([3,3,3])
+mf = cell.KHF(kpts=kpts)
+mf = cell.KKS(kpts=kpts)
+```
+
+Based on the `cell.spin` setting, different mean-field instances are created. By default:
+* Restricted closed-shell methods are used for molecules without unpaired electrons (`cell.spin=0`).
+* Unrestricted methods (UHF, UKS) are used for molecules with unpaired electrons (`cell.spin > 0`).
+
+The use of k-point symmetry in KHF  and KKS depends on the supplied `kpts`. If
+`kpts` are created as a k-point symmetry-enabled (`KPoint`) instance, k-point
+symmetry-adapted mean-field methods will be created.
+
+```python
+kpts = cell.make_kpts([3,3,3], space_group_symmetry=True)
+mf = cell.KHF(kpts=kpts) # KsymAdaptedKRHF
+mf = cell.KKS(kpts=kpts) # KsymAdaptedKRKS
+```
+
+### Explicit Mean-field Methods
+To create specific mean-field instances, such as unrestricted or generalized HF
+or KS methods, they can be explicitly called from the `Cell` instance. The
+following rules apply:
+
+* `cell.RHF()` and `cell.RKS()` create single k-point restricted Hartree-Fock or
+  Kohn-Sham methods. When `cell.spin != 0`, ROHF and ROKS methods are
+  instantiated. However, for k-point mean-field methods, `cell.KRHF()` and
+  `cell.KRKS()` always create restricted closed-shell models, regardless of the
+  `cell.spin` setting. This is different from the treatment in single k-point methods.
+
+* `cell.ROHF()`, `cell.ROKS()`, `cell.KROHF()`, and `cell.KROKS()` create
+  restricted open-shell HF or KS methods.
+
+* `cell.UHF()`, `cell.UKS()`, `cell.KUHF()`, and `cell.KUKS()` create
+  unrestricted Hartree-Fock or Kohn-Sham methods, regardless of the `cell.spin`
+  setting.
+
+* `cell.GHF()`, `cell.GKS()`, `cell.KGHF()` and `cell.KGKS()` create generalized
+  mean-field methods.
+
+* K-point symmetry adaptation is available for K-prefixed methods, which is
+  determined by the `kpts` argument.
+
+### Keyword Parameters for Mean-field Methods
+Configuration parameters for mean-field methods can be specified through keyword
+arguments of the instantiation methods. For example,
+
+```python
+mf = cell.RKS(xc='b3lyp', max_cycle=20)
+mf = cell.KGKS(xc='pbe', kpts=cell.make_kpts([2,2,2]))
+```
+
+### Instantiating Post-SCF Methods
+Post-SCF methods at the gamma point can be specified for the `Cell` instance.
+Keyword arguments can be supplied, and they will be passed to the post-SCF
+methods.
+
+```python
+mycc = cell.CCSD(frozen=1)
+mytd = cell.TDA()
+```
+
+For post-SCF methods with k-point sampling, the method should be prefixed with "K".
+Additionally, k-points can be supplied as keyword arguments, and they will be
+automatically applied when creating the underlying mean-field object.
+
+```python
+mycc = cell.KCCSD(kpts=cell.make_kpts([2,2,2]), frozen=1)
+```