0
# SCF Methods
1

2
Self-consistent field methods including Hartree-Fock and density functional theory that form the foundation for quantum chemistry calculations, with support for restricted, unrestricted, and relativistic variants.
3

4
## Capabilities
5

6
### Hartree-Fock Methods
7

8
Core self-consistent field methods for solving the electronic Schrödinger equation at the mean-field level.
9

10
```python { .api }
11
class RHF:
12
    """
13
    Restricted Hartree-Fock for closed-shell systems.
14
    
15
    Attributes:
16
    - mol: Mole object
17
    - conv_tol: float, convergence tolerance (default: 1e-10)
18
    - max_cycle: int, maximum SCF iterations (default: 50)
19
    - init_guess: str, initial guess method ('minao', 'atom', '1e', 'chkfile')
20
    - mo_coeff: ndarray, molecular orbital coefficients
21
    - mo_energy: ndarray, orbital energies
22
    - mo_occ: ndarray, orbital occupations
23
    """
24
    
25
    def __init__(self, mol):
26
        """Initialize RHF object."""
27
    
28
    def run(self, dm0=None):
29
        """Run SCF calculation and return self."""
30
    
31
    def kernel(self, dm0=None):
32
        """SCF kernel returning converged energy."""
33

34
class UHF:
35
    """
36
    Unrestricted Hartree-Fock for open-shell systems.
37
    
38
    Allows different spatial orbitals for alpha and beta electrons.
39
    """
40

41
class ROHF:
42
    """
43
    Restricted open-shell Hartree-Fock.
44
    
45
    Constrains paired electrons to same spatial orbitals while allowing
46
    unpaired electrons in singly occupied orbitals.
47
    """
48

49
class GHF:
50
    """
51
    Generalized Hartree-Fock with complex orbitals.
52
    
53
    Most general HF method allowing complex orbital coefficients
54
    and spin-unrestricted alpha/beta mixing.
55
    """
56

57
def HF(mol, *args):
58
    """
59
    Generic HF method selector based on molecule properties.
60
    
61
    Automatically selects RHF for closed-shell, UHF for open-shell systems.
62
    """
63
```
64

65
### Density Functional Theory
66

67
Kohn-Sham density functional theory methods with extensive exchange-correlation functional support.
68

69
```python { .api }
70
class RKS:
71
    """
72
    Restricted Kohn-Sham DFT for closed-shell systems.
73
    
74
    Attributes:
75
    - xc: str, exchange-correlation functional ('lda', 'pbe', 'b3lyp', etc.)
76
    - grids: Grids object for numerical integration
77
    - nlc: str, non-local correlation functional
78
    - omega: float, range-separation parameter for RSH functionals
79
    """
80
    
81
    def __init__(self, mol, xc='lda'):
82
        """Initialize RKS object with XC functional."""
83

84
class UKS:
85
    """Unrestricted Kohn-Sham DFT for open-shell systems."""
86

87
class ROKS:
88
    """Restricted open-shell Kohn-Sham DFT."""
89

90
class GKS:
91
    """Generalized Kohn-Sham with complex orbitals."""
92

93
def KS(mol, *args):
94
    """Generic KS method selector based on molecule properties."""
95
```
96

97
### Relativistic Methods
98

99
Relativistic enhancements for heavy elements including scalar and spin-orbit coupling effects.
100

101
```python { .api }
102
class DHF:
103
    """
104
    Dirac-Hartree-Fock for fully relativistic calculations.
105
    
106
    Includes both scalar relativistic and spin-orbit coupling effects
107
    using 4-component spinor basis.
108
    """
109

110
class X2C:
111
    """
112
    Exact two-component relativistic method.
113
    
114
    Provides scalar relativistic effects with 2-component efficiency
115
    by exact decoupling of positive/negative energy states.
116
    """
117

118
def sfx2c1e(mf):
119
    """
120
    Spin-free X2C with 1-electron X-matrix approximation.
121
    
122
    Efficient approximation including scalar relativistic effects
123
    in the 1-electron integrals only.
124
    """
125
```
126

127
### SCF Enhancement Methods
128

129
Techniques for improving SCF convergence, stability, and computational efficiency.
130

131
```python { .api }
132
def density_fit(mf, auxbasis=None, with_df=None, only_dfj=False):
133
    """
134
    Add density fitting (RI) acceleration to SCF method.
135
    
136
    Parameters:
137
    - mf: SCF object to enhance
138
    - auxbasis: str, auxiliary basis set name
139
    - with_df: DF object for custom density fitting
140
    - only_dfj: bool, fit only Coulomb integrals (default: False)
141
    
142
    Returns:
143
    density-fitted SCF object
144
    """
145

146
def newton(mf):
147
    """
148
    Second-order Newton-Raphson SCF acceleration.
149
    
150
    Uses exact Hessian for quadratic convergence near minimum.
151
    Significantly faster convergence for well-behaved systems.
152
    """
153

154
def fast_newton(mf):
155
    """
156
    Fast Newton-Raphson with approximate Hessian.
157
    
158
    Uses approximate Hessian construction for improved efficiency
159
    while maintaining enhanced convergence properties.
160
    """
161
```
162

163
### DIIS Convergence Acceleration
164

165
Direct inversion in iterative subspace methods for SCF convergence acceleration.
166

167
```python { .api }
168
class DIIS:
169
    """
170
    Direct Inversion in Iterative Subspace extrapolation.
171
    
172
    Standard DIIS using Fock matrix commutators as error vectors.
173
    """
174

175
class CDIIS:
176
    """
177
    Commutator DIIS for SCF acceleration.
178
    
179
    Uses [F,DS] commutators as error metric for extrapolation.
180
    Most common DIIS variant for SCF calculations.
181
    """
182

183
class EDIIS:
184
    """
185
    Energy DIIS for difficult SCF cases.
186
    
187
    Uses energy changes rather than commutators as error metric.
188
    Useful for cases where standard DIIS fails.
189
    """
190

191
class ADIIS:
192
    """
193
    Augmented DIIS combining DIIS and EDIIS.
194
    
195
    Adaptively switches between DIIS and EDIIS based on
196
    convergence behavior for robust SCF convergence.
197
    """
198
```
199

200
### Utility Functions
201

202
Helper functions for SCF calculations, analysis, and data management.
203

204
```python { .api }
205
def get_init_guess(mol, key='minao'):
206
    """
207
    Generate initial guess for SCF orbitals.
208
    
209
    Parameters:
210
    - mol: Mole object
211
    - key: str, guess method ('minao', 'atom', '1e', 'huckel')
212
    
213
    Returns:
214
    ndarray, initial density matrix
215
    """
216

217
def spin_square(mo_coeff, s, mo_occ):
218
    """
219
    Calculate spin contamination and total spin.
220
    
221
    Parameters:
222
    - mo_coeff: orbital coefficients
223
    - s: overlap matrix
224
    - mo_occ: orbital occupations
225
    
226
    Returns:
227
    tuple of (S^2, 2S+1) values
228
    """
229

230
def analyze(mf, verbose=None, **kwargs):
231
    """
232
    Analyze SCF results including Mulliken populations and orbital energies.
233
    """
234
```
235

236
## Usage Examples
237

238
### Basic SCF Calculations
239

240
```python
241
import pyscf
242

243
# Restricted Hartree-Fock
244
mol = pyscf.M(atom='H2O', basis='6-31g')
245
mf = mol.RHF()
246
mf.run()
247
print(f"RHF energy: {mf.e_tot}")
248

249
# Unrestricted for open-shell
250
mol_radical = pyscf.M(atom='OH', basis='6-31g', spin=1)
251
mf = mol_radical.UHF()
252
mf.run()
253
print(f"UHF energy: {mf.e_tot}")
254
```
255

256
### DFT Calculations
257

258
```python
259
# Restricted Kohn-Sham with different functionals
260
mol = pyscf.M(atom='CH4', basis='cc-pvdz')
261

262
# LDA functional
263
mf_lda = mol.RKS(xc='lda')
264
mf_lda.run()
265

266
# GGA functional
267
mf_pbe = mol.RKS(xc='pbe')
268
mf_pbe.run()
269

270
# Hybrid functional
271
mf_b3lyp = mol.RKS(xc='b3lyp')
272
mf_b3lyp.run()
273

274
# Range-separated hybrid
275
mf_camb3lyp = mol.RKS(xc='camb3lyp')
276
mf_camb3lyp.run()
277
```
278

279
### Advanced SCF Options
280

281
```python
282
# Custom convergence settings
283
mol = pyscf.M(atom='H2', basis='cc-pvtz')
284
mf = mol.RHF()
285
mf.conv_tol = 1e-12
286
mf.max_cycle = 100
287
mf.init_guess = 'atom'
288
mf.run()
289

290
# With density fitting acceleration
291
mf_df = pyscf.scf.density_fit(mf, auxbasis='cc-pvtz-jkfit')
292
mf_df.run()
293

294
# Newton-Raphson acceleration
295
mf_newton = pyscf.scf.newton(mf)
296
mf_newton.run()
297
```
298

299
### Relativistic Calculations
300

301
```python
302
# X2C for scalar relativistic effects
303
mol_heavy = pyscf.M(atom='Au 0 0 0; H 0 0 1.5', basis='cc-pvdz-pp')
304
mf_x2c = pyscf.scf.X2C(mol_heavy).RHF()
305
mf_x2c.run()
306

307
# Dirac-Hartree-Fock for full relativistic treatment
308
mf_dhf = mol_heavy.DHF()
309
mf_dhf.run()
310
```
311

312
## Types
313

314
```python { .api }
315
from typing import Union, Tuple, TypedDict
316
from typing_extensions import Literal
317
import numpy as np
318
ndarray = np.ndarray
319

320
# SCF base classes
321
class SCF:
322
    """Base SCF class with common functionality."""
323

324
# Functional specifications for DFT
325
XCFunctional = Union[str, Tuple[str, float]]
326

327
# Convergence status
328
class ConvergenceError(RuntimeError):
329
    """Raised when SCF fails to converge."""
330

331
# Common SCF result structure
332
SCFResult = TypedDict('SCFResult', {
333
    'converged': bool,
334
    'e_tot': float,
335
    'mo_energy': ndarray,
336
    'mo_coeff': ndarray,
337
    'mo_occ': ndarray
338
})
339
```