0
# Molecular Structure and Basis Sets
1

2
Core functionality for defining molecular systems, atomic coordinates, basis sets, and Gaussian type orbitals that form the foundation for all quantum chemistry calculations in PySCF.
3

4
## Capabilities
5

6
### Molecule Creation
7

8
Main interface for creating molecular systems with atomic coordinates, basis sets, and molecular properties.
9

10
```python { .api }
11
def M(**kwargs):
12
    """
13
    Main driver to create Molecule object (mol) or Material crystal object (cell).
14
    
15
    Parameters:
16
    - atom: str or list, atomic coordinates in various formats
17
    - basis: str or dict, basis set specification
18
    - charge: int, molecular charge (default: 0)
19
    - spin: int, spin multiplicity - 1 (default: 0)
20
    - unit: str, coordinate unit ('Bohr' or 'Angstrom', default: 'Angstrom')
21
    - symmetry: bool or str, use molecular symmetry (default: False)
22
    - verbose: int, output verbosity level (default: 3)
23
    
24
    Returns:
25
    Mole object for molecules or Cell object for crystals (if 'a' parameter provided)
26
    """
27

28
class Mole:
29
    """
30
    Main molecule class for quantum chemistry calculations.
31
    
32
    Attributes:
33
    - atom: atomic coordinates and symbols
34
    - basis: basis set specification
35
    - charge: molecular charge
36
    - spin: number of unpaired electrons
37
    - natm: number of atoms
38
    - nelectron: number of electrons
39
    - nelec: tuple of (alpha, beta) electrons
40
    """
41
    
42
    def build(self):
43
        """Build molecule and initialize internal data structures."""
44
    
45
    def RHF(self):
46
        """Create restricted Hartree-Fock object."""
47
    
48
    def UHF(self):
49
        """Create unrestricted Hartree-Fock object."""
50
    
51
    def RKS(self, xc='lda'):
52
        """Create restricted Kohn-Sham DFT object."""
53
    
54
    def UKS(self, xc='lda'):
55
        """Create unrestricted Kohn-Sham DFT object."""
56
    
57
    def ROHF(self):
58
        """Create restricted open-shell Hartree-Fock object."""
59
    
60
    def GHF(self):
61
        """Create generalized Hartree-Fock object."""
62
    
63
    def ROKS(self, xc='lda'):
64
        """Create restricted open-shell Kohn-Sham DFT object."""
65
    
66
    def GKS(self, xc='lda'):
67
        """Create generalized Kohn-Sham DFT object."""
68
    
69
    # Core molecular properties
70
    def copy(self, deep=True):
71
        """Create copy of molecule object."""
72
    
73
    def atom_coord(self, atm_id=None, unit='Angstrom'):
74
        """Get atomic coordinates."""
75
    
76
    def atom_charge(self, atm_id=None):
77
        """Get atomic charges."""
78
    
79
    def energy_nuc(self):
80
        """Calculate nuclear repulsion energy."""
81
    
82
    def tot_electrons(self):
83
        """Calculate total number of electrons."""
84
    
85
    # Basis set information  
86
    def nao_nr(self, cart=None):
87
        """Number of AO functions (non-relativistic)."""
88
    
89
    def nao_cart(self):
90
        """Number of Cartesian AO functions."""
91
    
92
    def ao_labels(self, fmt=True):
93
        """Get AO labels."""
94
    
95
    # Integral evaluation
96
    def intor(self, intor, comp=None, hermi=0, shls_slice=None):
97
        """General integral evaluation interface."""
98
```
99

100
### Atomic Coordinate Handling
101

102
Functions for parsing, formatting, and manipulating atomic coordinates in various formats.
103

104
```python { .api }
105
def format_atom(atoms, origin=0, axes=None, unit='Angstrom'):
106
    """
107
    Format and validate atomic coordinates.
108
    
109
    Parameters:
110
    - atoms: str or list, atomic coordinates
111
    - origin: array-like, coordinate origin (default: [0,0,0])
112
    - axes: array-like, coordinate system axes
113
    - unit: str, coordinate unit ('Bohr' or 'Angstrom')
114
    
115
    Returns:
116
    list of [symbol, [x, y, z]] entries
117
    """
118

119
def atom_types(atoms, basis=None, magmom=None):
120
    """
121
    Determine unique atom types in molecular system.
122
    
123
    Parameters:
124
    - atoms: atomic coordinate specification
125
    - basis: basis set specification
126
    - magmom: magnetic moments
127
    
128
    Returns:
129
    list of unique atom types
130
    """
131
```
132

133
### Basis Set Management
134

135
Functions for loading, parsing, and manipulating basis set definitions from various sources.
136

137
```python { .api }
138
def parse(string, symb=None, optimize=True):
139
    """
140
    Parse basis set definition from string format.
141
    
142
    Parameters:
143
    - string: str, basis set definition
144
    - symb: str, element symbol
145
    - optimize: bool, optimize basis set contractions
146
    
147
    Returns:
148
    list of basis functions
149
    """
150

151
def load(filename_or_basisname, symb, optimize=True):
152
    """
153
    Load basis sets from files or built-in library.
154
    
155
    Parameters:
156
    - filename_or_basisname: str, file path or basis set name
157
    - symb: str, element symbol
158
    - optimize: bool, optimize contractions
159
    
160
    Returns:
161
    list of basis functions
162
    """
163

164
def load_ecp(filename_or_basisname, symb):
165
    """
166
    Load effective core potentials.
167
    
168
    Parameters:
169
    - filename_or_basisname: str, file path or ECP name
170
    - symb: str, element symbol
171
    
172
    Returns:
173
    dict of ECP specification
174
    """
175

176
def optimize_contraction(basis):
177
    """Optimize basis set contractions for efficiency."""
178

179
# Built-in basis set aliases (extensive collection)
180
ALIAS: dict # Standard basis set aliases including:
181
            # Pople: '631g', '6311g', '631gs', '631gss', '6311gss' 
182
            # Correlation-consistent: 'ccpvdz', 'ccpvtz', 'ccpvqz', 'ccpv5z'
183
            # Def2: 'def2svp', 'def2tzvp', 'def2tzvpp', 'def2qzvp'
184
            # STO: 'sto3g', 'sto6g'
185
            # Relativistic: various 'dk' variants
186
```
187

188
### Gaussian Type Orbitals
189

190
Core functions for Gaussian type orbital properties, normalization, and transformations.
191

192
```python { .api }
193
def gto_norm(l, expnt):
194
    """
195
    Normalization factor for Gaussian type orbitals.
196
    
197
    Parameters:
198
    - l: int, angular momentum quantum number
199
    - expnt: float, Gaussian exponent
200
    
201
    Returns:
202
    float, normalization factor
203
    """
204

205
def gaussian_int(n, alpha):
206
    """
207
    Analytical Gaussian integral calculation.
208
    
209
    Parameters:
210
    - n: int, power in integrand
211
    - alpha: float, Gaussian exponent
212
    
213
    Returns:
214
    float, integral value
215
    """
216

217
def cart2sph(l, c_tensor=None, normalized=None):
218
    """
219
    Cartesian to spherical harmonic transformation matrix.
220
    
221
    Parameters:
222
    - l: int, angular momentum
223
    - c_tensor: array-like, transformation coefficients
224
    - normalized: bool, use normalized spherical harmonics
225
    
226
    Returns:
227
    transformation matrix
228
    """
229
```
230

231
### Integral Evaluation
232

233
Functions for evaluating integrals over Gaussian type orbitals at various levels.
234

235
```python { .api }
236
def getints(intor, atm, bas, env, shls_slice=None, comp=None, hermi=0, aosym='s1'):
237
    """
238
    General integral calculation interface.
239
    
240
    Parameters:
241
    - intor: str, integral type
242
    - atm: ndarray, atomic information
243
    - bas: ndarray, basis set information  
244
    - env: ndarray, environment array
245
    - shls_slice: tuple, shell slice for partial integrals
246
    - comp: int, number of components
247
    - hermi: int, hermiticity (0=no, 1=hermitian, 2=anti-hermitian)
248
    - aosym: str, AO symmetry ('s1', 's2ij', 's2kl', 's4', 's8')
249
    
250
    Returns:
251
    ndarray, integral values
252
    
253
    Supported integral types:
254
    1-electron: int1e_ovlp, int1e_kin, int1e_nuc, int1e_rinv
255
    1e derivatives: int1e_ipovlp, int1e_ipkin, int1e_ipnuc  
256
    2-electron: int2e, int2e_ip1, int2e_ip2, int2e_sph
257
    3-center: int3c2e, int3c2e_ip1, int3c2e_sph
258
    ECP: ECPscalar, ECPso
259
    Spinor: various _spinor variants
260
    """
261

262
def getints_by_shell(intor, shls, atm, bas, env, comp=1):
263
    """Evaluate integrals for specific shells."""
264

265
def make_cintopt(atm, bas, env, intor):
266
    """Create optimization objects for integral evaluation."""
267

268
def eval_gto(mol, eval_name, coords, comp=None, shls_slice=None, non0tab=None, ao_loc=None, cutoff=None, out=None):
269
    """
270
    Evaluate Gaussian type orbitals at specified coordinates.
271
    
272
    Parameters:
273
    - mol: Mole object
274
    - eval_name: str, evaluation type
275
    - coords: array-like, evaluation coordinates
276
    - comp: int, component to evaluate
277
    - shls_slice: tuple, shell slice
278
    - non0tab: screening table for efficiency
279
    - ao_loc: AO location array
280
    - cutoff: float, cutoff threshold
281
    - out: ndarray, output array
282
    
283
    Returns:
284
    ndarray, GTO values at coordinates
285
    
286
    Supported evaluation types:
287
    GTOval_sph, GTOval_cart: Basic GTO values
288
    GTOval_ip_sph, GTOval_ip_cart: First derivatives
289
    GTOval_deriv1 through GTOval_deriv4: Higher derivatives
290
    GTOval_*_spinor: Spinor variants
291
    """
292

293
def make_screen_index(mol, coords, shls_slice=None, cutoff=1e-8):
294
    """Create screening arrays for efficient GTO evaluation."""
295
```
296

297
## Usage Examples
298

299
### Basic Molecule Creation
300

301
```python
302
import pyscf
303

304
# Simple molecule from string
305
mol = pyscf.M(atom='H 0 0 0; H 0 0 1.4', basis='6-31g')
306

307
# Molecule with charge and spin
308
mol = pyscf.M(
309
    atom='C 0 0 0; O 0 0 1.4',
310
    basis='cc-pvdz',
311
    charge=0,
312
    spin=0  # singlet
313
)
314

315
# From list format
316
atoms = [
317
    ['H', [0.0, 0.0, 0.0]],
318
    ['H', [0.0, 0.0, 1.4]]
319
]
320
mol = pyscf.M(atom=atoms, basis='sto-3g')
321
```
322

323
### Advanced Basis Set Usage
324

325
```python
326
# Mixed basis sets
327
mol = pyscf.M(
328
    atom='H 0 0 0; He 0 0 2',
329
    basis={'H': '6-31g', 'He': 'cc-pvdz'}
330
)
331

332
# Custom basis set
333
custom_basis = pyscf.gto.basis.parse('''
334
H    S
335
     13.00773000              0.01968500
336
      1.96206100              0.13797700
337
      0.44453100              0.47814800
338
H    S
339
      0.12194300              1.00000000
340
''')
341
mol = pyscf.M(atom='H 0 0 0; H 0 0 1.4', basis={'H': custom_basis})
342
```
343

344
### Coordinate Manipulation
345

346
```python
347
# Different units
348
mol_bohr = pyscf.M(
349
    atom='H 0 0 0; H 0 0 2.6',  # in Bohr
350
    basis='sto-3g',
351
    unit='Bohr'
352
)
353

354
# With symmetry
355
mol_sym = pyscf.M(
356
    atom='N 0 0 0; H 1 1 1; H 1 -1 -1; H -1 1 -1; H -1 -1 1',
357
    basis='6-31g',
358
    symmetry=True
359
)
360
```
361

362
## Types
363

364
```python { .api }
365
from typing import Union, Dict, List, Tuple
366
import numpy as np
367
ndarray = np.ndarray
368

369
class MoleBase:
370
    """Base class for molecular systems providing common functionality."""
371

372
# Basis set format types
373
BasisSpec = Union[str, Dict[str, Union[str, List]], List]
374

375
# Atomic coordinate types  
376
AtomSpec = Union[str, List[List[Union[str, List[float]]]]]
377

378
# Physical constants and configuration
379
BOHR: float = 0.52917721092  # Bohr to Angstrom conversion
380
BASE: int = 0  # C-style 0-based indexing (can be 1 for Fortran-style)
381
NORMALIZE_GTO: bool = True  # Enable GTO normalization
382

383
# Nuclear models
384
NUC_POINT: int = 1  # Point nuclear model
385
NUC_GAUSS: int = 2  # Gaussian nuclear model  
386
NUC_FRAC_CHARGE: int = 3  # Fractional charge model
387
NUC_ECP: int = 4  # ECP nuclear model
388
```