topoptlab.amg module

topoptlab.amg.create_interpolators_amg(A: sparray, interpol_fnc: Callable = <function direct_interpolation>, interpol_kw: Dict = {}, coupling_fnc: Callable = <function rubestueben_coupling>, coupling_kw: [None, typing.Dict]={'c_neg': 0.2, 'c_pos': 0.5}, cf_splitting_fnc: Callable = <function standard_coarsening>, cf_splitting_kw: Dict = {}, wght_trunc_fnc: None | Callable = None, wght_trunc_kw: Dict = {}, nlevels: int = 2, _lvl: None | int = None, **kwargs: Any) → List[sparray]

Create a generic algebraic multigrid (AMG) solver for the linear problem Ax=b. The key ingredients in are i) coarse/fine splitting ii) interpolation method. The first is typically based on some notion of the strength/importance of connections between two variables via the matrix entry a_{ij} of the matrix A.

Parameters:

• A (scipy.sparse.sparse_array) – system matrix (e. g. stiffness matrix)

• interpol_fnc (callable) – interpolation function that with the mask for coarse variables/dofs ultimately constructs the interpolator

• interpol_kw (dict) – keywords for the interpolation function that ultimately constructs the interpolator.

• coupling_fnc (callable) – method to find (strong) couplings which may be used to find coarse variables.

• coupling_kw (callable) – keywords to find (strong) couplings which may be used to find coarse variables.

• cf_splitting_fnc (callable) – function to find (strong) couplings which are used to find coarse variables.

• cf_splitting_kw (dict) – keywords to find (strong) couplings which are used to find coarse variables.

• wght_trunc_fnc (None or callable) – function to truncate weights from the interpolator constructed from the interpolation function.

• wght_trunc_kw (None or dict) – keywords to truncate weights from the interpolator constructed from the interpolation function.

• nlevels (int) – number of grid levels. Smallest number possible is 2 (one coarse and one fine grid).

• _lvl (None or int) – current level. Do not set when calling this function as it is used to construct the interpolators.

Returns:

interpolators – hierarchy of interpolator.

Return type:

list of scipy.sparse.csc_array

topoptlab.amg.direct_interpolation(A: sparray, mask_coarse: ndarray) → sparray

Implements page 70 of

Stuebgen, Klaus. “Algebraic multigrid (AMG): an introduction with applications.” GMD report (1999).

Parameters:

• A (scipy.sparse.sparse_array) – sparse matrix for which to find coupling of size (nvars,nvars)

• mask_coarse (np.ndarray) – has nc True entries and is True for coarse degrees of freedom

Returns:

prolongator – sparse matrix used to interpolate fine scale degrees of freedom. Interpolation is done by P u_c where P is the prolongator matrix of shape (nvars,nc).

Return type:

scipy.sparse.csc_array

topoptlab.amg.rigid_bodymodes(coords: ndarray, pbc: bool | List = False) → ndarray

Calculate rigid body modes from the coordinates of N nodes.

This function does not take into account any boundary conditions, so modes eliminated by Dirichlet boundary conditions have to be eliminated later. If periodic boundary conditions are active, it is assumed that they are already applied and no redundant nodes are in the list of coordinates.

Parameters:

• coords (np.ndarray) – x coordinates shape (N,ndim)

• pbc (bool or list) – bool flags whether dimension is periodic.

Returns:

B – rigid body modes of shape (ndim*N, (ndim**2 + ndim)/2.

Return type:

np.ndarray

topoptlab.amg.rubestueben_coupling(A: sparray, c_neg: float = 0.2, c_pos: None | float = 0.5, **kwargs: Any) → Tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]

Ruge-Stüben method to determine strong/weak coupling between variables in sparse array/matrix A. Works on the row index and the value of an entry of A to determine its coupling strength according to Eqs. 115 and 119 in

Stuebgen, Klaus. “Algebraic multigrid (AMG): an introduction with applications.” GMD report (1999).

We have slightly modified the expressions (their meaning stays the same): variable i is strongly negatively coupled to variable j if for the entry a_{ij} of matrix A and the the off-diagonal entries of the i-th row A_{i} of matrix A the following is true:

a_{ij} <= (-c_neg) *max(A_{i}) with a_{ij}<0

variable i is strongly negatively coupled to variable j if for the entry a_{ij} of matrix A and the negative off-diagonal entries of the i-th row A_{i} of matrix A the following is true:

a_{ij} >= c_pos *max(A_{i}) with a_{ij}>0

Parameters:

• A (scipy.sparse.sparse_array) – sparse matrix for which to find coupling of size (nvars,nvars)

• c_neg (float) – constant to determine strong coupling for negative variables.

• c_pos (float or None) – constant to determine strong coupling for positive variables.

Returns:

• row (np.ndarray) – row index

• col (np.ndarray) – column_index

• mask_strong (np.ndarray) – True if the variable of val is strongly linked to the variable in the respective row.

• s (list of len nvars) – strong couplings for each variable. Each element contains array of indices.

• s_t (list of len nvars) – strong transpose couplings for each variable. Each element contains array of indices.

• iso (np.ndarray) – indices of isolated variables.

topoptlab.amg.standard_coarsening(A: sparray, coupling_fnc: Callable = <function rubestueben_coupling>, coupling_kw: Dict = {'c_neg': 0.2, 'c_pos': 0.5}, **kwargs: Any) → ndarray

Standard coarsening according to page 64 and following in

Stuebgen, Klaus. “Algebraic multigrid (AMG): an introduction with applications.” GMD report (1999).

Parameters:

• A (scipy.sparse.sparse_array) – sparse matrix for which to find coupling of size (nvars,nvars)

• coupling_fnc (callable) – function that determines strong coupling between variables.

• coupling_kw (dictionary) – dictionary containing arguments needed for the coupling function.

Returns:

mask_coarse – mask for coarse variables shape (nvars).

Return type:

np.ndarray