tessl/pypi-pyamg

Algebraic Multigrid (AMG) solvers for large sparse linear systems with Python interface

—

Pending

Overview

Eval results

Files

AMG Solver Constructors

Name: tessl/pypi-pyamg
Author: tessl

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.

Capabilities

Classical AMG (Ruge-Stuben)

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

def ruge_stuben_solver(A, strength=('classical', {'theta': 0.25}),
                      CF=('RS', {'second_pass': False}),
                      interpolation='classical',
                      presmoother=('gauss_seidel', {'sweep': 'symmetric'}),
                      postsmoother=('gauss_seidel', {'sweep': 'symmetric'}),
                      max_levels=30, max_coarse=10, keep=False, **kwargs):
    """
    Create Classical (Ruge-Stuben) AMG solver.
    
    Implements the classical AMG algorithm with C/F splitting,
    classical interpolation, and various smoothing options.
    
    Parameters:
    - A: sparse matrix, coefficient matrix (must be square)
    - strength: str or tuple, strength of connection measure:
        * ('classical', {'theta': 0.25}): classical SOC (default)
        * 'classical': classical SOC with default theta
        * 'distance': distance-based SOC  
        * tuple: custom strength with parameters
    - CF: str or tuple, coarse/fine splitting method:
        * ('RS', {'second_pass': False}): Ruge-Stuben splitting (default)
        * 'RS': Ruge-Stuben with default parameters
        * 'PMIS': Parallel maximal independent set
        * 'CLJP': Cleary-Luby-Jones-Plassmann
    - interpolation: str, interpolation method:
        * 'classical': classical interpolation
        * 'direct': direct interpolation
        * 'injection': injection interpolation
    - presmoother: str or tuple, pre-smoothing method:
        * ('gauss_seidel', {'sweep': 'symmetric'}): symmetric GS (default)
        * 'gauss_seidel': Gauss-Seidel with default parameters
        * 'jacobi': Jacobi relaxation
        * tuple: custom method with parameters
    - postsmoother: str or tuple, post-smoothing method (same options as presmoother)
    - max_levels: int, maximum number of levels (default 30)
    - max_coarse: int, maximum coarse grid size (default 10)
    - keep: bool, keep extra operators for debugging (default False)
    - interpolation: str, interpolation method (default 'classical')
    
    Returns:
    MultilevelSolver: Classical AMG solver
    
    Raises:
    ValueError: if matrix is not square or parameters are invalid
    """

Usage Examples:

import pyamg
import numpy as np

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

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

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

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

# Control hierarchy size
ml = pyamg.ruge_stuben_solver(A, max_levels=6, max_coarse=100)

Smoothed Aggregation AMG

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

def smoothed_aggregation_solver(A, B=None, BH=None,
                               symmetry='hermitian', strength='symmetric',
                               aggregate='standard',
                               smooth=('jacobi', {'omega': 4.0/3.0}),
                               presmoother=('block_gauss_seidel', {'sweep': 'symmetric'}),
                               postsmoother=('block_gauss_seidel', {'sweep': 'symmetric'}),
                               improve_candidates=(('block_gauss_seidel', 
                                                   {'sweep': 'symmetric', 'iterations': 4}), None),
                               max_levels=10, max_coarse=10,
                               diagonal_dominance=False, keep=False, **kwargs):
    """
    Create Smoothed Aggregation AMG solver.
    
    Implements smoothed aggregation AMG with flexible aggregation
    strategies and prolongation smoothing options.
    
    Parameters:
    - A: sparse matrix, coefficient matrix (preferably SPD)
    - B: array, near-nullspace vectors (default: constant vector)
    - BH: array, adjoint near-nullspace vectors (optional)
    - symmetry: str, matrix symmetry ('hermitian', 'symmetric', 'nonsymmetric')
    - strength: str, strength of connection measure ('symmetric' default)
    - aggregate: str, aggregation method ('standard' default)
    - smooth: str or tuple, prolongation smoothing:
        * ('jacobi', {'omega': 4.0/3.0}): Jacobi smoother (default)
        * 'energy': energy-minimizing smoother
        * None: no smoothing (tentative prolongation)
    - presmoother: tuple, pre-smoothing method:
        * ('block_gauss_seidel', {'sweep': 'symmetric'}): default
    - postsmoother: tuple, post-smoothing method (same as presmoother)
    - improve_candidates: tuple, candidate improvement method
    - max_levels: int, maximum number of levels (default 10)
    - max_coarse: int, maximum coarse grid size (default 10)
    - diagonal_dominance: bool, handle diagonally dominant problems
    - keep: bool, keep extra operators for debugging
    
    Returns:
    MultilevelSolver: Smoothed Aggregation AMG solver
    
    Raises:
    ValueError: if matrix properties are incompatible with SA
    """

Usage Examples:

# Basic smoothed aggregation
A = pyamg.gallery.linear_elasticity((20, 20))
ml = pyamg.smoothed_aggregation_solver(A)

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

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

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

# Energy-based smoothing
ml = pyamg.smoothed_aggregation_solver(A, smooth='energy')

Approximate Ideal Restriction (AIR)

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

def air_solver(A, strength='classical', 
               presmoother='l1_gauss_seidel',
               postsmoother='l1_gauss_seidel',
               max_levels=10, max_coarse=500,
               coarse_solver='pinv2', **kwargs):
    """
    Create Approximate Ideal Restriction AMG solver.
    
    Experimental AMG method using approximate ideal restriction
    operators. Can be effective for problems where classical
    methods have difficulties.
    
    Parameters:
    - A: sparse matrix, coefficient matrix  
    - strength: str or function, strength of connection measure
    - presmoother: str or tuple, pre-smoothing method:
        * 'l1_gauss_seidel': l1-scaled Gauss-Seidel (recommended)
        * 'gauss_seidel': standard Gauss-Seidel
        * 'jacobi': Jacobi relaxation
    - postsmoother: str or tuple, post-smoothing method
    - max_levels: int, maximum number of levels
    - max_coarse: int, maximum coarse grid size  
    - coarse_solver: str, coarse grid solver
    - theta: float, strength threshold
    - degree: int, polynomial degree for restriction
    
    Returns:
    MultilevelSolver: AIR AMG solver
    
    Raises:
    ValueError: if matrix is not suitable for AIR method
    """

Usage Examples:

# Basic AIR solver
A = pyamg.gallery.poisson((40, 40))
ml = pyamg.air_solver(A)

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

# Different smoothing
ml = pyamg.air_solver(A, 
                     presmoother='jacobi',
                     postsmoother='jacobi')

Adaptive Smoothed Aggregation AMG

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

def adaptive_sa_solver(A, initial_candidates=None, symmetry='hermitian',
                       pdef=True, num_candidates=1, candidate_iters=5,
                       improvement_iters=0, epsilon=0.1,
                       max_levels=10, max_coarse=10, aggregate='standard',
                       prepostsmoother=('gauss_seidel',
                                        {'sweep': 'symmetric'}),
                       smooth=('jacobi', {}), strength='symmetric',
                       coarse_solver='pinv',
                       eliminate_local=(False, {'thresh': 1.0}), keep=False,
                       **kwargs):
    """
    Create Adaptive Smoothed Aggregation AMG solver.
    
    Implements adaptive SA that automatically discovers near-nullspace
    candidates through an adaptive procedure rather than requiring
    a priori knowledge of appropriate candidate vectors.
    
    Parameters:
    - A: sparse matrix, coefficient matrix (must be square CSR/BSR)
    - initial_candidates: array, initial candidate basis (default None)
    - symmetry: str, matrix symmetry ('hermitian' or 'symmetric')
    - pdef: bool, whether matrix is positive definite (default True)
    - num_candidates: int, number of candidates to generate (default 1)
    - candidate_iters: int, smoothing iterations per candidate (default 5)
    - improvement_iters: int, candidate improvement iterations (default 0)
    - epsilon: float, target convergence factor (default 0.1)
    - max_levels: int, maximum number of levels (default 10)
    - max_coarse: int, maximum coarse grid size (default 10)
    - aggregate: str, aggregation method ('standard', 'lloyd', 'naive')
    - prepostsmoother: tuple, smoother for adaptive setup phase
    - smooth: tuple, prolongation smoothing method
    - strength: str, strength of connection measure
    - coarse_solver: str, coarse grid solver method
    - eliminate_local: tuple, local candidate elimination parameters
    - keep: bool, keep extra operators for debugging
    
    Returns:
    MultilevelSolver: Adaptive SA AMG solver
    
    Raises:
    ValueError: if matrix properties are incompatible with method
    """

Usage Examples:

import pyamg
import numpy as np

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

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

# Custom adaptive parameters
ml = pyamg.adaptive_sa_solver(A, 
                             candidate_iters=10,
                             epsilon=0.05,
                             improvement_iters=2)

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

# Lloyd aggregation with adaptation
ml = pyamg.adaptive_sa_solver(A, aggregate='lloyd')

Specialized Aggregation Solvers

Additional solver constructors for specific aggregation strategies.

def rootnode_solver(A, strength='symmetric', 
                   presmoother='block_gauss_seidel',
                   postsmoother='block_gauss_seidel', **kwargs):
    """
    Create Root-node aggregation AMG solver.
    
    Uses root-node aggregation strategy where aggregates
    are formed around selected root nodes.
    
    Parameters:
    - A: sparse matrix, coefficient matrix
    - strength: str, strength of connection measure
    - presmoother: str or tuple, pre-smoothing method
    - postsmoother: str or tuple, post-smoothing method
    - Additional SA solver parameters
    
    Returns:
    MultilevelSolver: Root-node aggregation AMG solver
    """

def pairwise_solver(A, strength='symmetric',
                   presmoother='block_gauss_seidel', 
                   postsmoother='block_gauss_seidel', **kwargs):
    """
    Create Pairwise aggregation AMG solver.
    
    Uses pairwise aggregation where fine grid points
    are paired to form 2-point aggregates.
    
    Parameters:
    - A: sparse matrix, coefficient matrix
    - strength: str, strength of connection measure  
    - presmoother: str or tuple, pre-smoothing method
    - postsmoother: str or tuple, post-smoothing method
    - Additional SA solver parameters
    
    Returns:
    MultilevelSolver: Pairwise aggregation AMG solver
    """

Usage Examples:

# Root-node aggregation
A = pyamg.gallery.poisson((30, 30))
ml = pyamg.rootnode_solver(A)

# Pairwise aggregation
ml = pyamg.pairwise_solver(A)

Coarse Grid Solver

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

def coarse_grid_solver(solver='pinv2', **kwargs):
    """
    Create coarse grid solver for bottom level of AMG hierarchy.
    
    Parameters:
    - solver: str, solver method:
        * 'pinv2': Moore-Penrose pseudoinverse (default)
        * 'spsolve': sparse direct solver
        * 'lu': LU factorization
        * 'cg': conjugate gradient
        * 'gmres': GMRES
    - tol: float, tolerance for iterative solvers
    - maxiter: int, maximum iterations for iterative solvers
    
    Returns:
    callable: coarse grid solver function
    """