diff --git a/source/user/gto.rst b/source/user/gto.rst index e6ea490f..98969e30 100644 --- a/source/user/gto.rst +++ b/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. diff --git a/source/user/pbcgto.md b/source/user/pbcgto.md index 3bd467cf..ba4e2620 100644 --- a/source/user/pbcgto.md +++ b/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) +```