0
# Properties
1
2
Molecular properties including analytical derivatives, vibrational analysis, and response properties for structure optimization, transition state searches, and spectroscopic property calculations.
3
4
## Capabilities
5
6
### Analytical Gradients
7
8
First derivatives of the energy with respect to nuclear coordinates for geometry optimization and force calculations.
9
10
```python { .api }
11
class Gradients:
12
"""
13
Base analytical gradient class.
14
15
Provides framework for calculating analytical first derivatives
16
of electronic energy with respect to nuclear coordinates.
17
"""
18
19
def __init__(self, method):
20
"""Initialize gradient calculation for given method."""
21
22
def run(self, mo_coeff=None, mo_occ=None, atmlst=None):
23
"""
24
Calculate analytical gradients.
25
26
Parameters:
27
- mo_coeff: ndarray, molecular orbital coefficients
28
- mo_occ: ndarray, orbital occupations
29
- atmlst: list, atoms for which to calculate gradients
30
31
Returns:
32
ndarray, gradients for each atom (natm, 3)
33
"""
34
35
class RHF_Gradients:
36
"""Analytical gradients for restricted Hartree-Fock."""
37
38
class UHF_Gradients:
39
"""Analytical gradients for unrestricted Hartree-Fock."""
40
41
class RKS_Gradients:
42
"""Analytical gradients for restricted Kohn-Sham DFT."""
43
44
class UKS_Gradients:
45
"""Analytical gradients for unrestricted Kohn-Sham DFT."""
46
47
class MP2_Gradients:
48
"""Analytical gradients for MP2 correlation method."""
49
50
class CCSD_Gradients:
51
"""Analytical gradients for CCSD correlation method."""
52
```
53
54
### Analytical Hessians
55
56
Second derivatives for vibrational frequency analysis, transition state optimization, and reaction path following.
57
58
```python { .api }
59
class Hessian:
60
"""
61
Base analytical Hessian class.
62
63
Calculates second derivatives of energy with respect to
64
nuclear coordinates for vibrational analysis.
65
"""
66
67
def __init__(self, method):
68
"""Initialize Hessian calculation for given method."""
69
70
def run(self, mo_coeff=None, mo_occ=None, atmlst=None):
71
"""
72
Calculate analytical Hessian matrix.
73
74
Returns:
75
ndarray, Hessian matrix (3*natm, 3*natm)
76
"""
77
78
def freq(self, anharm=False):
79
"""
80
Calculate vibrational frequencies from Hessian.
81
82
Parameters:
83
- anharm: bool, include anharmonic corrections
84
85
Returns:
86
tuple of (frequencies, normal_modes)
87
"""
88
89
class RHF_Hessian:
90
"""Analytical Hessian for restricted Hartree-Fock."""
91
92
class UHF_Hessian:
93
"""Analytical Hessian for unrestricted Hartree-Fock."""
94
95
class RKS_Hessian:
96
"""Analytical Hessian for restricted Kohn-Sham DFT."""
97
```
98
99
### Time-Dependent Response Properties
100
101
Linear response methods for excited states, transition properties, and dynamic response functions.
102
103
```python { .api }
104
class TDHF:
105
"""
106
Time-dependent Hartree-Fock (Random Phase Approximation).
107
108
Calculates excited state energies and transition properties
109
using linear response theory with HF reference.
110
111
Attributes:
112
- nstates: int, number of excited states (default: 3)
113
- singlet: bool, calculate singlet states (default: True)
114
- triplet: bool, calculate triplet states (default: False)
115
"""
116
117
def __init__(self, mf):
118
"""Initialize TDHF from SCF reference."""
119
120
def run(self, nstates=None):
121
"""
122
Run TDHF calculation.
123
124
Returns:
125
tuple of (excitation_energies, transition_dipoles)
126
"""
127
128
class TDDFT:
129
"""
130
Time-dependent Density Functional Theory.
131
132
Linear response DFT including exchange-correlation kernel
133
for improved treatment of excitation energies.
134
"""
135
136
class TDA:
137
"""
138
Tamm-Dancoff Approximation.
139
140
Simplified TDDFT with only particle-hole excitations,
141
neglecting hole-particle coupling terms.
142
"""
143
```
144
145
### Polarizabilities and Hyperpolarizabilities
146
147
Response properties for describing molecular response to external electric fields.
148
149
```python { .api }
150
def polarizability(mf, freq=0):
151
"""
152
Calculate static or frequency-dependent polarizability.
153
154
Parameters:
155
- mf: SCF object
156
- freq: float or array, frequencies (default: 0 for static)
157
158
Returns:
159
ndarray, polarizability tensor (3, 3) or (nfreq, 3, 3)
160
"""
161
162
def hyperpolarizability(mf, freq=None):
163
"""
164
Calculate first hyperpolarizability (beta tensor).
165
166
Parameters:
167
- mf: SCF object
168
- freq: frequency specification
169
170
Returns:
171
ndarray, hyperpolarizability tensor
172
"""
173
```
174
175
### Nuclear Magnetic Resonance Properties
176
177
NMR chemical shifts, coupling constants, and magnetic properties.
178
179
```python { .api }
180
def nmr_shielding(mf, atoms=None):
181
"""
182
Calculate NMR shielding tensors.
183
184
Parameters:
185
- mf: SCF object
186
- atoms: list, atom indices (default: all atoms)
187
188
Returns:
189
dict, shielding tensors for each atom
190
"""
191
192
def spin_spin_coupling(mf, atom1, atom2):
193
"""
194
Calculate spin-spin coupling constant between two nuclei.
195
196
Parameters:
197
- mf: SCF object
198
- atom1, atom2: int, atom indices
199
200
Returns:
201
float, coupling constant in Hz
202
"""
203
```
204
205
### Electric Field Gradients
206
207
Quadrupolar coupling and electric field gradient calculations.
208
209
```python { .api }
210
def efg(mf, atoms=None):
211
"""
212
Calculate electric field gradients at nuclei.
213
214
Parameters:
215
- mf: SCF object
216
- atoms: list, atom indices
217
218
Returns:
219
dict, EFG tensors for each atom
220
"""
221
```
222
223
## Usage Examples
224
225
### Gradient Calculations and Geometry Optimization
226
227
```python
228
import pyscf
229
from pyscf import geomopt
230
231
# Calculate analytical gradients
232
mol = pyscf.M(atom='H2O', basis='6-31g')
233
mf = mol.RHF().run()
234
grad = pyscf.grad.RHF(mf)
235
forces = grad.run()
236
print("Forces on atoms:", forces)
237
238
# Geometry optimization using gradients
239
mol_opt = geomopt.optimize(mf)
240
print("Optimized geometry:", mol_opt.atom_coords())
241
242
# DFT gradients
243
mf_dft = mol.RKS(xc='b3lyp').run()
244
grad_dft = pyscf.grad.RKS(mf_dft).run()
245
```
246
247
### Vibrational Frequency Analysis
248
249
```python
250
# Calculate Hessian and frequencies
251
mol = pyscf.M(atom='H2O', basis='6-31g')
252
mf = mol.RHF().run()
253
hess = pyscf.hessian.RHF(mf)
254
hessian_matrix = hess.run()
255
256
# Extract vibrational frequencies
257
freqs, modes = hess.freq()
258
print("Vibrational frequencies (cm^-1):")
259
for i, freq in enumerate(freqs):
260
if freq > 0:
261
print(f"Mode {i}: {freq:.1f}")
262
else:
263
print(f"Mode {i}: {freq:.1f}i (imaginary)")
264
```
265
266
### Excited State Calculations
267
268
```python
269
# TDDFT for excited states
270
mol = pyscf.M(atom='CH2O', basis='6-31g')
271
mf = mol.RKS(xc='b3lyp').run()
272
td = pyscf.tdscf.TDDFT(mf)
273
td.nstates = 5
274
excitation_energies = td.run()
275
276
print("Excitation energies (eV):")
277
for i, energy in enumerate(excitation_energies):
278
eV = energy * 27.2114
279
print(f"State {i+1}: {eV:.2f} eV")
280
281
# Calculate oscillator strengths
282
osc_strengths = td.oscillator_strength()
283
for i, f in enumerate(osc_strengths):
284
print(f"State {i+1} oscillator strength: {f:.4f}")
285
```
286
287
### Response Properties
288
289
```python
290
# Static polarizability
291
mol = pyscf.M(atom='H2O', basis='aug-cc-pvdz')
292
mf = mol.RHF().run()
293
alpha = pyscf.prop.polarizability.polarizability(mf)
294
print("Polarizability tensor:", alpha)
295
296
# Frequency-dependent polarizability
297
freqs = [0.0, 0.1, 0.2] # atomic units
298
alpha_w = pyscf.prop.polarizability.polarizability(mf, freq=freqs)
299
print("Frequency-dependent polarizability:", alpha_w)
300
```
301
302
### NMR Properties
303
304
```python
305
# NMR shielding constants
306
mol = pyscf.M(atom='CH4', basis='pcSseg-1')
307
mf = mol.RHF().run()
308
nmr_data = pyscf.prop.nmr.shielding(mf)
309
310
for i, atom in enumerate(mol.atom):
311
symbol = atom[0]
312
shielding = nmr_data[i]
313
isotropic = (shielding[0,0] + shielding[1,1] + shielding[2,2]) / 3
314
print(f"{symbol} NMR shielding: {isotropic:.1f} ppm")
315
```
316
317
### Advanced Property Calculations
318
319
```python
320
# Electric field gradient
321
mol = pyscf.M(atom='H2O', basis='6-311g')
322
mf = mol.RHF().run()
323
efg_tensors = pyscf.prop.efg.efg(mf)
324
325
# Spin-orbit coupling matrix elements
326
soc = pyscf.prop.soc.soc_matrix(mf)
327
328
# Magnetic susceptibility
329
chi = pyscf.prop.magnetizability.magnetizability(mf)
330
```
331
332
## Types
333
334
```python { .api }
335
from typing import Dict, TypedDict
336
import numpy as np
337
ndarray = np.ndarray
338
339
# Property result types
340
PropertyTensor = ndarray # General property tensor
341
342
# Gradient types
343
Forces = ndarray # Shape (natm, 3)
344
Hessian = ndarray # Shape (3*natm, 3*natm)
345
346
# Excited state properties
347
ExcitationData = TypedDict('ExcitationData', {
348
'energies': ndarray,
349
'oscillator_strengths': ndarray,
350
'transition_dipoles': ndarray
351
})
352
353
# Vibrational data
354
VibrationalData = TypedDict('VibrationalData', {
355
'frequencies': ndarray,
356
'normal_modes': ndarray,
357
'reduced_masses': ndarray,
358
'force_constants': ndarray
359
})
360
361
# NMR data structures
362
NMRShielding = Dict[int, ndarray] # atom_id -> shielding tensor
363
```