# API¶

## Operators¶

lfa_lab.operator.from_periodic_stencil(stencils, grid)

Create an operator from a periodic stencil.

Parameters: stencils (NdArray) – An $$n$$-D array of stencils.
lfa_lab.operator.from_stencil(stencil, grid)

Create an operator from a stencil.

Parameters: stencil – The stencil that should be transformed into an operator. This parameter has to be assigned to either a SparseStencil or a list of tuples, where each tuple consists of an offset and a value. grid (Grid) – The grid where the operator is defined.
lfa_lab.operator.hp_filter(fine_grid, coarse_grid)

Create a high-pass filter.

Parameters: fine_grid (Grid) – The grid corresponding to all frequencies. coarse_grid (Grid) – The grid of the low modes.
lfa_lab.operator.identity(grid)

The identity operator.

Parameters: grid (Grid) – The grid where the operator is defined.
lfa_lab.operator.injection_interpolation(fine_grid, coarse_grid)

Create an injection interpolation operator.

Parameters: fine_grid (Grid) – The codomain of the operator. coarse_grid (Grid) – The domain of the operator.
lfa_lab.operator.injection_restriction(fine_grid, coarse_grid)

Create an injection restriction operator.

Parameters: fine_grid (Grid) – The domain of the operator. coarse_grid (Grid) – The codomain of the operator.
lfa_lab.operator.lp_filter(fine_grid, coarse_grid)

Create a low-pass filter.

Parameters: fine_grid (Grid) – The grid corresponding to all frequencies. coarse_grid (Grid) – The grid of the low modes.
lfa_lab.operator.system(entries)

Given a list of lists, returns a system of operators.

lfa_lab.operator.zero(grid)

The zero operator.

Parameters: grid (Grid) – The grid where the operator is defined.
class lfa_lab.dag.Node

This node represents general operators whose symbols can be computed.

The addition, multiplication and power operators exist for this class.

This class should not be instanciated directly.

__add__(other)

The sum of self and other.

__getitem__(index)

Access the element of a system.

Return type: Node
__mul__(other)

The composition of self and other.

__pow__(p)

Compute the power of an operator.

__rmul__(other)

Scalar multiplication of self and other.

__sub__(other)

The difference of self and other.

__weakref__

list of weak references to the object (if defined)

adjoint()

Return type: Node
inverse()

The inverse of the operator.

Return type: Node
symbol(desired_resolution=None)

The symbol of the operator.

Return type: Symbol
class lfa_lab.dag.StencilNode(stencil, grid)

An Operator given by a stencil.

To construct a stencil node, use the lfa_lab.operator.from_stencil() method.

Parameters: stencil (SparseStencil) – The stencil that should be turned into an operator. grid (Grid) – The corresponding grid. stencil – The stencil of the operator. grid – The grid of the operator.
diag()

A stencil operator that was constructed using the diagonal entries of the stencil of this operator.

lower()

A stencil operator that was constructed using the strictly lower triangular part of the stencil of this operator.

matching_identity()

An identity operator that has the same output and input grid as the current one.

matching_zero()

A zero operator that has the same output and input grid as the current one.

upper()

A stencil operator that was constructed using the strictly upper triangular part of the stencil of this operator.

## Smoother¶

lfa_lab.smoother.jacobi(op, weight=1.0)

The Jacobi smoother.

Given by

$I - \omega D^{-1} A \,.$

where $$D$$ is the diagonal part of $$A$$.

Parameters: op (StencilNode) – The original operator $$A$$. weight – The weight $$\omega$$.
lfa_lab.smoother.gs_lex(op)

The Gauss-Seidel lexicographic smoother.

Given by

$I - (D + L)^{-1} A$

where $$D$$ is the diagonal part and $$L$$ the strictly lower triangular part of $$A$$.

Parameters: op (StencilNode) – The original operator $$A$$.
lfa_lab.smoother.rb_jacobi(stencil, weight=1.0)

The red-black Jacobi method.

Parameters: stencil (StencilNode) – The original operator. weight (double) – The weight of the Jacobi methods, see lfa_lab.smoother.jacobi().

This module contains methods for construction block smoothers.

lfa_lab.block_smoother.block_jacobi(op, block_size, weight=1.0)

Returns the operator of the block jacobi method.

Parameters: op (StencilNode) – The original operator. block_size (tuple) – A tuple containing the block size per dimension. weight – The weight applied to the correction.
lfa_lab.block_smoother.rb_block_jacobi(op, block_size, weight=1.0)

The red-black block Jacobi method.

Parameters: op (StencilNode) – The original operator. block_size (tuple) – A tuple containing the block size per dimension. weight – The weight applied to the correction. The error propagation operator of the method. Node

## Multigrid¶

lfa_lab.two_grid.coarse_grid_correction(operator, coarse_operator, interpolation, restriction, coarse_error=None)

The error propagator of a coarse grid correction.

Parameters: operator (Node) – The operator of the linear system. coarse_operator (Node) – The operator of the coarse linear system. interpolation (Node) – The interpolation operator. restriction (Node) – The restriction operator. coarse_error (Node) – The coarse error propagation operation. This entry is optional. It can be specified when the coarse grid system is solved inexactly. The error propagator of the coarse grid correction. Node
lfa_lab.two_grid.galerkin_coarsening(operator, interpolation, restriction)

The error propagator of the Galerkin coarse grid approximation (GCA).

The GCA is defined as

$L_c = R L P \,.$
Parameters: operator (Node) – The fine grid operator $$L$$. interpolation (Node) – The interpolation operator $$P$$. restriction (Node) – The restriction operator $$R$$. The error propagation operator. Node
lfa_lab.two_grid.two_grid(pre_smoother, post_smoother, coarse_grid_correction)

The error propagator of a two-grid method.

## Gallery¶

lfa_lab.gallery.fw_restriction(fine_grid, coarse_grid)

Return full weighting restriction operator.

Return type: Node
lfa_lab.gallery.ml_interpolation_stencil(fine_grid, coarse_grid)

Return the stencil of a multilinear interpolation.

Return type: SparseStencil
lfa_lab.gallery.ml_interpolation(fine_grid, coarse_grid)

Multilinear interpolation

Return type: Node
lfa_lab.gallery.fw_restriction_stencil(fine_grid, coarse_grid)

Return the stencil of a full weighting restriction.

Return type: SparseStencil
lfa_lab.gallery.poisson_2d(grid, eps=1.0)

The stencil of the discrete Poisson equation in 2D.

This operator is the discrete version of the operator $$L$$ given by

$L u = -\left( \epsilon \frac{\partial^2 u}{\partial x^2} + \frac{\partial^2 u}{\partial y^2} \right) \,.$

Using finite differences leads to the discrete operator $$L_h$$, which is computed by this function (see Poisson Equation).

Return type: StencilNode

## Stencil¶

class lfa_lab.stencil.SparseStencil(entries=None)

Storage for a stencil.

A (constant) stencil is a map $$s: \mathbb{Z}^d \to \mathbb{C}$$. We assume that only finitely many function values are non-zero. Therefore, we can represent the stencil by a list containing of pairs consisting of the function argument and the corresponding value.

Parameters: entries (list of (tuple of (tuple, double))) – The entries of the stencil. This argument is supposed to be a list of entries. Each entry is a tuple consisting of the offset (a tuple) and the corresponding scalar.
class lfa_lab.stencil.PeriodicStencil(entries)

Storage for a periodic stencil.

A periodic stencil is a family of stencils $$\{ s_\mathbf{x} \}_\mathbf{x \in \mathbb{Z}^d}$$ such that $$s_\mathbf{x} = s_{\mathbf{x}'}$$ for $$(\mathbf{x} - \mathbf{x}') \in \mathbf{p} \mathbb{Z}^d$$. We call $$\mathbf{p}$$ the period of the stencil. We store a periodic stencil by storing the stencils for $$0 \le \mathbf{x} < \mathbf{p}$$ in an instance of lfa_tool.util.NdArray.

Parameters: entries – The entries as an lfa_tool.util.NdArray or as a proper argument to the constructor of lfa_tool.util.NdArray.

## Plotting¶

Plotting commands for Fourier symbols.

lfa_lab.plot.plot_2d(sym, **kwargs)

Plot the sampling of a symbol.

Parameters: sym (Symbol) – The symbol that should be plotted. norm_type (str) – The type of the norm. Possible values: ‘rows’, ‘output’, ‘columns’, and ‘input’. style_2d (str) – The plotting style for 2D symbols. It can be set to ‘mesh’, ‘image’, or ‘contour’.
lfa_lab.plot.plot_1d(op, **kwargs)

Plot a 1d symbol.

Parameters: norm_type (str) – The type of the norm. Possible values: ‘rows’, ‘output’, ‘columns’, and ‘input’.
lfa_lab.plot.default_options

The default options that will be used when no option argument is provided to a plotting call.

## Printing Reports¶

Produces a report for an operator

lfa_lab.report.print_report(E, title='')

Print a report about the operator E on the screen.

This opens a figure. You may have to call matplotlib.pyplot.show() to show it.

lfa_lab.report.save_report(E, file_name_prefix, title='', standalone=False)

Store a report about an operator as a LaTeX file.

Parameters: file_name_prefix (str) – The file name without file extension. title (str) – A short description of the operator. standalone (bool) – Whether the TeX file contains the preamble or is suitable for embedding into another document.

## Util¶

class lfa_lab.util.NdArray(entries=None, dim=None, bottom_p=None, shape=None)

An $$n$$-D array.

When constructing an NdArray either entires or shape must be given. When entries is given, either dim of bottom_p must be defined.

Here is a simple example for the usage of this class:

x = lfa_lab.util.NdArray([[1,2,3],[4,5,6]], dim=2)
print(x[1,2]) # prints 6
x[1,2] = 7
print(x)      # prints NdArray: [[1, 2, 3], [4, 5, 7]]

Parameters: entries (list of (list of ... (list of object) ... )) – The entries of the n-D array as a nested list. dim (int) – The dimension $$n$$ of the array. bottom_p (object -> bool) – A predicate to determine the dimension of the array. shape (tuple) – The number of entries per dimension.
__getitem__(pos)

Return the element at position pos.

Parameters: pos (tuple) – The index of the entry.
lfa_lab.util.lex_less(a, b)

Lexicographical comparison.

## Core Classes and Functions¶

class lfa_lab.core.extension.BdMatrix

Block diagonal matrix.

block(i)

The i-th block of the matrix.

full()

The full matrix.

class lfa_lab.core.extension.Grid(*args)

Description of an infinite grid.

Parameters: arg1 (int or tuple) – The number of dimensions or a tuple with spacings per dimension. arg2 – The step-sizes per dimension, given as a tuple. (optional)
dimension()

The number of dimensions of the grid.

step_size()

The step size.

class lfa_lab.core.extension.Symbol

Approximation of a matrix symbols.

col_norms()

The norms of the columns of the symbol as $$n$$-D array.

col_norms_1d()

The norms of the columns of a 1D symbol as a vector.

col_norms_2d()

The norms of the columns of a 2D symbol as a matrix.

dimension()

The dimension of the symbol.

eigenvalues()

The eigenvalues of the symbol as a vector.

matrix()

The matrix representation of the symbol.

row_norms()

The norms of the rows of the symbol as an $$n$$-D array.

row_norms_1d()

The norms of the rows of a 1D symbol as a vector.

row_norms_2d()

The norms of the rows of a 2D symbol as a matrix.

spectral_norm()

The (spectral) norm of the symbol.

spectral_radius()

The spectral radius of the symbol.