0
# Periodic Systems
1
2
Complete support for crystalline systems with periodic boundary conditions, k-point sampling, and all electronic structure methods adapted for solid-state calculations using plane wave and Gaussian basis approaches.
3
4
## Capabilities
5
6
### Crystal Structure Definition
7
8
Core functionality for defining periodic systems with lattice parameters, k-point meshes, and crystal symmetry.
9
10
```python { .api }
11
class Cell:
12
"""
13
Periodic system (crystal) class with lattice parameters.
14
15
Extends Mole functionality to include periodicity, lattice vectors,
16
and k-point sampling for solid-state calculations.
17
18
Attributes:
19
- a: ndarray, lattice vectors (3, 3)
20
- atom: atomic coordinates and symbols
21
- basis: basis set specification
22
- pseudo: pseudopotential specification
23
- mesh: tuple, FFT mesh for plane wave calculations
24
- ke_cutoff: float, kinetic energy cutoff for plane waves
25
"""
26
27
def __init__(self, **kwargs):
28
"""Initialize periodic cell."""
29
30
def build(self):
31
"""Build cell and initialize periodic data structures."""
32
33
def make_kpts(self, nks, wrap_around=False):
34
"""
35
Generate k-point mesh.
36
37
Parameters:
38
- nks: tuple, k-point mesh dimensions (nkx, nky, nkz)
39
- wrap_around: bool, wrap k-points to first Brillouin zone
40
41
Returns:
42
ndarray, k-point coordinates
43
"""
44
45
def M(**kwargs):
46
"""
47
Create Cell object for periodic systems.
48
49
Automatically creates Cell when lattice parameter 'a' is provided,
50
otherwise creates molecular Mole object.
51
"""
52
```
53
54
### Periodic SCF Methods
55
56
Self-consistent field methods adapted for periodic boundary conditions with k-point sampling.
57
58
```python { .api }
59
class KRHF:
60
"""
61
k-point sampling restricted Hartree-Fock.
62
63
Handles Brillouin zone sampling for periodic Hartree-Fock
64
calculations in crystalline systems.
65
66
Attributes:
67
- kpts: ndarray, k-point coordinates
68
- exxdiv: str, treatment of Coulomb divergence ('ewald', 'vcut_sph')
69
"""
70
71
def __init__(self, cell, kpts=None):
72
"""Initialize k-point RHF calculation."""
73
74
class KUHF:
75
"""k-point sampling unrestricted Hartree-Fock."""
76
77
class KRKS:
78
"""
79
k-point sampling restricted Kohn-Sham DFT.
80
81
Periodic DFT with k-point sampling and plane wave
82
or Gaussian basis representations.
83
"""
84
85
class KUKS:
86
"""k-point sampling unrestricted Kohn-Sham DFT."""
87
```
88
89
### Periodic Post-SCF Methods
90
91
Advanced correlation methods adapted for periodic systems including MP2, coupled cluster, and CI.
92
93
```python { .api }
94
class KMP2:
95
"""k-point sampling MP2 for periodic systems."""
96
97
class KCCSD:
98
"""k-point sampling coupled cluster for solids."""
99
100
class KRPA:
101
"""k-point random phase approximation."""
102
```
103
104
### Plane Wave Methods
105
106
Plane wave basis implementations for solid-state calculations with pseudopotentials.
107
108
```python { .api }
109
def get_coulG(cell, k=None, exx=False, mf=None):
110
"""
111
Coulomb kernel in reciprocal space.
112
113
Parameters:
114
- cell: Cell object
115
- k: ndarray, k-point
116
- exx: bool, exact exchange treatment
117
- mf: SCF object for screening
118
119
Returns:
120
ndarray, Coulomb kernel
121
"""
122
123
def get_ao_pairs_G(cell, kpts=None):
124
"""
125
AO pair products in reciprocal space for plane wave calculations.
126
"""
127
```
128
129
## Usage Examples
130
131
### Basic Periodic Calculations
132
133
```python
134
import pyscf.pbc as pbc
135
import numpy as np
136
137
# Create unit cell for diamond
138
cell = pbc.gto.M(
139
atom='C 0 0 0; C 0.25 0.25 0.25',
140
a=np.eye(3) * 3.5668, # lattice vectors in Bohr
141
basis='gth-szv',
142
pseudo='gth-pade'
143
)
144
145
# Gamma-point calculation
146
mf = cell.RHF()
147
mf.run()
148
print(f"Total energy: {mf.e_tot}")
149
150
# k-point sampling
151
kpts = cell.make_kpts([2, 2, 2]) # 2x2x2 k-mesh
152
mf_k = cell.KRHF(kpts=kpts)
153
mf_k.run()
154
```
155
156
### DFT for Solids
157
158
```python
159
# Periodic DFT calculation
160
cell = pbc.gto.M(
161
atom='Si 0 0 0; Si 0.25 0.25 0.25',
162
a=np.array([[0.0, 2.715, 2.715],
163
[2.715, 0.0, 2.715],
164
[2.715, 2.715, 0.0]]),
165
basis='gth-szv',
166
pseudo='gth-pade'
167
)
168
169
# DFT with k-points
170
mf_dft = cell.KRKS(xc='pbe')
171
mf_dft.kpts = cell.make_kpts([4, 4, 4])
172
mf_dft.run()
173
```
174
175
### Band Structure Calculations
176
177
```python
178
# Calculate band structure along high-symmetry path
179
kpath = cell.get_kpts_path('Gamma-X-W-K-Gamma', npoints=100)
180
mf_bands = cell.KRKS(kpts=kpath[0])
181
mf_bands.run()
182
183
# Extract eigenvalues for plotting
184
eigenvalues = mf_bands.mo_energy
185
```
186
187
## Types
188
189
```python { .api }
190
from typing import Union, Tuple
191
import numpy as np
192
ndarray = np.ndarray
193
194
# Lattice specification
195
LatticeVectors = ndarray # Shape (3, 3)
196
197
# k-point specifications
198
KPoints = Union[ndarray, int, Tuple[int, int, int]]
199
200
# Pseudopotential specification
201
PseudoPotential = Union[str, Dict[str, str]]
202
```