0
# AMG Solver Constructors
1

2
Factory functions for creating specific types of AMG solvers with detailed control over algorithm parameters and behavior. These constructors provide access to the full range of PyAMG's AMG implementations.
3

4
## Capabilities
5

6
### Classical AMG (Ruge-Stuben)
7

8
Creates Classical AMG solvers based on the Ruge-Stuben algorithm, ideal for M-matrices and problems with strong coupling patterns.
9

10
```python { .api }
11
def ruge_stuben_solver(A, strength=('classical', {'theta': 0.25}),
12
                      CF=('RS', {'second_pass': False}),
13
                      interpolation='classical',
14
                      presmoother=('gauss_seidel', {'sweep': 'symmetric'}),
15
                      postsmoother=('gauss_seidel', {'sweep': 'symmetric'}),
16
                      max_levels=30, max_coarse=10, keep=False, **kwargs):
17
    """
18
    Create Classical (Ruge-Stuben) AMG solver.
19
    
20
    Implements the classical AMG algorithm with C/F splitting,
21
    classical interpolation, and various smoothing options.
22
    
23
    Parameters:
24
    - A: sparse matrix, coefficient matrix (must be square)
25
    - strength: str or tuple, strength of connection measure:
26
        * ('classical', {'theta': 0.25}): classical SOC (default)
27
        * 'classical': classical SOC with default theta
28
        * 'distance': distance-based SOC  
29
        * tuple: custom strength with parameters
30
    - CF: str or tuple, coarse/fine splitting method:
31
        * ('RS', {'second_pass': False}): Ruge-Stuben splitting (default)
32
        * 'RS': Ruge-Stuben with default parameters
33
        * 'PMIS': Parallel maximal independent set
34
        * 'CLJP': Cleary-Luby-Jones-Plassmann
35
    - interpolation: str, interpolation method:
36
        * 'classical': classical interpolation
37
        * 'direct': direct interpolation
38
        * 'injection': injection interpolation
39
    - presmoother: str or tuple, pre-smoothing method:
40
        * ('gauss_seidel', {'sweep': 'symmetric'}): symmetric GS (default)
41
        * 'gauss_seidel': Gauss-Seidel with default parameters
42
        * 'jacobi': Jacobi relaxation
43
        * tuple: custom method with parameters
44
    - postsmoother: str or tuple, post-smoothing method (same options as presmoother)
45
    - max_levels: int, maximum number of levels (default 30)
46
    - max_coarse: int, maximum coarse grid size (default 10)
47
    - keep: bool, keep extra operators for debugging (default False)
48
    - interpolation: str, interpolation method (default 'classical')
49
    
50
    Returns:
51
    MultilevelSolver: Classical AMG solver
52
    
53
    Raises:
54
    ValueError: if matrix is not square or parameters are invalid
55
    """
56
```
57

58
**Usage Examples:**
59

60
```python
61
import pyamg
62
import numpy as np
63

64
# Basic classical AMG
65
A = pyamg.gallery.poisson((50, 50))
66
ml = pyamg.ruge_stuben_solver(A)
67

68
# Custom strength threshold
69
ml = pyamg.ruge_stuben_solver(A, strength=('classical', {'theta': 0.5}))
70

71
# Different splitting method
72
ml = pyamg.ruge_stuben_solver(A, CF='PMIS')
73

74
# Custom smoothing
75
ml = pyamg.ruge_stuben_solver(A, 
76
                             presmoother=('jacobi', {'iterations': 2}),
77
                             postsmoother='gauss_seidel')
78

79
# Control hierarchy size
80
ml = pyamg.ruge_stuben_solver(A, max_levels=6, max_coarse=100)
81
```
82

83
### Smoothed Aggregation AMG
84

85
Creates Smoothed Aggregation AMG solvers, particularly effective for symmetric positive definite problems and finite element discretizations.
86

87
```python { .api }
88
def smoothed_aggregation_solver(A, B=None, BH=None,
89
                               symmetry='hermitian', strength='symmetric',
90
                               aggregate='standard',
91
                               smooth=('jacobi', {'omega': 4.0/3.0}),
92
                               presmoother=('block_gauss_seidel', {'sweep': 'symmetric'}),
93
                               postsmoother=('block_gauss_seidel', {'sweep': 'symmetric'}),
94
                               improve_candidates=(('block_gauss_seidel', 
95
                                                   {'sweep': 'symmetric', 'iterations': 4}), None),
96
                               max_levels=10, max_coarse=10,
97
                               diagonal_dominance=False, keep=False, **kwargs):
98
    """
99
    Create Smoothed Aggregation AMG solver.
100
    
101
    Implements smoothed aggregation AMG with flexible aggregation
102
    strategies and prolongation smoothing options.
103
    
104
    Parameters:
105
    - A: sparse matrix, coefficient matrix (preferably SPD)
106
    - B: array, near-nullspace vectors (default: constant vector)
107
    - BH: array, adjoint near-nullspace vectors (optional)
108
    - symmetry: str, matrix symmetry ('hermitian', 'symmetric', 'nonsymmetric')
109
    - strength: str, strength of connection measure ('symmetric' default)
110
    - aggregate: str, aggregation method ('standard' default)
111
    - smooth: str or tuple, prolongation smoothing:
112
        * ('jacobi', {'omega': 4.0/3.0}): Jacobi smoother (default)
113
        * 'energy': energy-minimizing smoother
114
        * None: no smoothing (tentative prolongation)
115
    - presmoother: tuple, pre-smoothing method:
116
        * ('block_gauss_seidel', {'sweep': 'symmetric'}): default
117
    - postsmoother: tuple, post-smoothing method (same as presmoother)
118
    - improve_candidates: tuple, candidate improvement method
119
    - max_levels: int, maximum number of levels (default 10)
120
    - max_coarse: int, maximum coarse grid size (default 10)
121
    - diagonal_dominance: bool, handle diagonally dominant problems
122
    - keep: bool, keep extra operators for debugging
123
    
124
    Returns:
125
    MultilevelSolver: Smoothed Aggregation AMG solver
126
    
127
    Raises:
128
    ValueError: if matrix properties are incompatible with SA
129
    """
130
```
131

132
**Usage Examples:**
133

134
```python
135
# Basic smoothed aggregation
136
A = pyamg.gallery.linear_elasticity((20, 20))
137
ml = pyamg.smoothed_aggregation_solver(A)
138

139
# Custom aggregation method
140
ml = pyamg.smoothed_aggregation_solver(A, aggregate='lloyd')
141

142
# No prolongation smoothing (tentative prolongation)
143
ml = pyamg.smoothed_aggregation_solver(A, smooth=None)
144

145
# Custom near-nullspace for elasticity (rigid body modes)
146
B = np.ones((A.shape[0], 3))  # Translation modes
147
ml = pyamg.smoothed_aggregation_solver(A, B=B)
148

149
# Energy-based smoothing
150
ml = pyamg.smoothed_aggregation_solver(A, smooth='energy')
151
```
152

153
### Approximate Ideal Restriction (AIR)
154

155
Creates AIR AMG solvers that use approximate ideal restriction operators, designed for challenging problems where classical methods struggle.
156

157
```python { .api }
158
def air_solver(A, strength='classical', 
159
               presmoother='l1_gauss_seidel',
160
               postsmoother='l1_gauss_seidel',
161
               max_levels=10, max_coarse=500,
162
               coarse_solver='pinv2', **kwargs):
163
    """
164
    Create Approximate Ideal Restriction AMG solver.
165
    
166
    Experimental AMG method using approximate ideal restriction
167
    operators. Can be effective for problems where classical
168
    methods have difficulties.
169
    
170
    Parameters:
171
    - A: sparse matrix, coefficient matrix  
172
    - strength: str or function, strength of connection measure
173
    - presmoother: str or tuple, pre-smoothing method:
174
        * 'l1_gauss_seidel': l1-scaled Gauss-Seidel (recommended)
175
        * 'gauss_seidel': standard Gauss-Seidel
176
        * 'jacobi': Jacobi relaxation
177
    - postsmoother: str or tuple, post-smoothing method
178
    - max_levels: int, maximum number of levels
179
    - max_coarse: int, maximum coarse grid size  
180
    - coarse_solver: str, coarse grid solver
181
    - theta: float, strength threshold
182
    - degree: int, polynomial degree for restriction
183
    
184
    Returns:
185
    MultilevelSolver: AIR AMG solver
186
    
187
    Raises:
188
    ValueError: if matrix is not suitable for AIR method
189
    """
190
```
191

192
**Usage Examples:**
193

194
```python
195
# Basic AIR solver
196
A = pyamg.gallery.poisson((40, 40))
197
ml = pyamg.air_solver(A)
198

199
# Custom polynomial degree
200
ml = pyamg.air_solver(A, degree=2)
201

202
# Different smoothing
203
ml = pyamg.air_solver(A, 
204
                     presmoother='jacobi',
205
                     postsmoother='jacobi')
206
```
207

208
### Adaptive Smoothed Aggregation AMG
209

210
Creates Adaptive Smoothed Aggregation AMG solvers that automatically discover near-nullspace candidates without prior knowledge, particularly useful when appropriate candidates are unknown.
211

212
```python { .api }
213
def adaptive_sa_solver(A, initial_candidates=None, symmetry='hermitian',
214
                       pdef=True, num_candidates=1, candidate_iters=5,
215
                       improvement_iters=0, epsilon=0.1,
216
                       max_levels=10, max_coarse=10, aggregate='standard',
217
                       prepostsmoother=('gauss_seidel',
218
                                        {'sweep': 'symmetric'}),
219
                       smooth=('jacobi', {}), strength='symmetric',
220
                       coarse_solver='pinv',
221
                       eliminate_local=(False, {'thresh': 1.0}), keep=False,
222
                       **kwargs):
223
    """
224
    Create Adaptive Smoothed Aggregation AMG solver.
225
    
226
    Implements adaptive SA that automatically discovers near-nullspace
227
    candidates through an adaptive procedure rather than requiring
228
    a priori knowledge of appropriate candidate vectors.
229
    
230
    Parameters:
231
    - A: sparse matrix, coefficient matrix (must be square CSR/BSR)
232
    - initial_candidates: array, initial candidate basis (default None)
233
    - symmetry: str, matrix symmetry ('hermitian' or 'symmetric')
234
    - pdef: bool, whether matrix is positive definite (default True)
235
    - num_candidates: int, number of candidates to generate (default 1)
236
    - candidate_iters: int, smoothing iterations per candidate (default 5)
237
    - improvement_iters: int, candidate improvement iterations (default 0)
238
    - epsilon: float, target convergence factor (default 0.1)
239
    - max_levels: int, maximum number of levels (default 10)
240
    - max_coarse: int, maximum coarse grid size (default 10)
241
    - aggregate: str, aggregation method ('standard', 'lloyd', 'naive')
242
    - prepostsmoother: tuple, smoother for adaptive setup phase
243
    - smooth: tuple, prolongation smoothing method
244
    - strength: str, strength of connection measure
245
    - coarse_solver: str, coarse grid solver method
246
    - eliminate_local: tuple, local candidate elimination parameters
247
    - keep: bool, keep extra operators for debugging
248
    
249
    Returns:
250
    MultilevelSolver: Adaptive SA AMG solver
251
    
252
    Raises:
253
    ValueError: if matrix properties are incompatible with method
254
    """
255
```
256

257
**Usage Examples:**
258

259
```python
260
import pyamg
261
import numpy as np
262

263
# Basic adaptive SA
264
A = pyamg.gallery.poisson((50, 50))
265
ml = pyamg.adaptive_sa_solver(A)
266

267
# Multiple candidates
268
ml = pyamg.adaptive_sa_solver(A, num_candidates=3)
269

270
# Custom adaptive parameters
271
ml = pyamg.adaptive_sa_solver(A, 
272
                             candidate_iters=10,
273
                             epsilon=0.05,
274
                             improvement_iters=2)
275

276
# For elasticity problems (unknown near-nullspace)
277
A = pyamg.gallery.linear_elasticity((20, 20))
278
ml = pyamg.adaptive_sa_solver(A, num_candidates=6, pdef=False)
279

280
# Lloyd aggregation with adaptation
281
ml = pyamg.adaptive_sa_solver(A, aggregate='lloyd')
282
```
283

284
### Specialized Aggregation Solvers
285

286
Additional solver constructors for specific aggregation strategies.
287

288
```python { .api }
289
def rootnode_solver(A, strength='symmetric', 
290
                   presmoother='block_gauss_seidel',
291
                   postsmoother='block_gauss_seidel', **kwargs):
292
    """
293
    Create Root-node aggregation AMG solver.
294
    
295
    Uses root-node aggregation strategy where aggregates
296
    are formed around selected root nodes.
297
    
298
    Parameters:
299
    - A: sparse matrix, coefficient matrix
300
    - strength: str, strength of connection measure
301
    - presmoother: str or tuple, pre-smoothing method
302
    - postsmoother: str or tuple, post-smoothing method
303
    - Additional SA solver parameters
304
    
305
    Returns:
306
    MultilevelSolver: Root-node aggregation AMG solver
307
    """
308

309
def pairwise_solver(A, strength='symmetric',
310
                   presmoother='block_gauss_seidel', 
311
                   postsmoother='block_gauss_seidel', **kwargs):
312
    """
313
    Create Pairwise aggregation AMG solver.
314
    
315
    Uses pairwise aggregation where fine grid points
316
    are paired to form 2-point aggregates.
317
    
318
    Parameters:
319
    - A: sparse matrix, coefficient matrix
320
    - strength: str, strength of connection measure  
321
    - presmoother: str or tuple, pre-smoothing method
322
    - postsmoother: str or tuple, post-smoothing method
323
    - Additional SA solver parameters
324
    
325
    Returns:
326
    MultilevelSolver: Pairwise aggregation AMG solver
327
    """
328
```
329

330
**Usage Examples:**
331

332
```python
333
# Root-node aggregation
334
A = pyamg.gallery.poisson((30, 30))
335
ml = pyamg.rootnode_solver(A)
336

337
# Pairwise aggregation
338
ml = pyamg.pairwise_solver(A)
339
```
340

341
### Coarse Grid Solver
342

343
Factory for creating coarse grid solvers used at the bottom of AMG hierarchies.
344

345
```python { .api }
346
def coarse_grid_solver(solver='pinv2', **kwargs):
347
    """
348
    Create coarse grid solver for bottom level of AMG hierarchy.
349
    
350
    Parameters:
351
    - solver: str, solver method:
352
        * 'pinv2': Moore-Penrose pseudoinverse (default)
353
        * 'spsolve': sparse direct solver
354
        * 'lu': LU factorization
355
        * 'cg': conjugate gradient
356
        * 'gmres': GMRES
357
    - tol: float, tolerance for iterative solvers
358
    - maxiter: int, maximum iterations for iterative solvers
359
    
360
    Returns:
361
    callable: coarse grid solver function
362
    """
363
```
364

365
## Solver Selection Guidelines
366

367
### Problem Type Recommendations
368

369
- **Symmetric Positive Definite**: Smoothed Aggregation AMG
370
- **M-matrices**: Classical AMG with Ruge-Stuben splitting
371
- **Indefinite Problems**: Classical AMG or AIR
372
- **Elasticity**: Smoothed Aggregation with rigid body modes
373
- **General**: Try Classical AMG first, then Smoothed Aggregation
374

375
### Parameter Tuning
376

377
- **Strength threshold**: Lower values (0.1-0.25) for stronger coupling
378
- **Max levels**: Reduce for memory-constrained problems
379
- **Smoothing**: Block methods for systems, point methods for scalars
380
- **Coarse solver**: 'spsolve' for better accuracy, 'pinv2' for robustness
381

382
### Performance Considerations
383

384
- Classical AMG setup is typically faster than SA
385
- SA solve phase is often more efficient for symmetric problems
386
- AIR has higher memory requirements but can handle difficult problems
387
- Block smoothers are more expensive but more effective for systems