fast_multipole_matrix

The fast multipole matrix uses the KATRIN FFTM method to compute the multiplication of the charge density problem matrix with a vector. It works by constructing an adaptive tree of cubes and subcubes, computing multipole expansions as approximations of the electric field by local charges and converting them into local expansion to approximate the field of far away charges. Then the result vector is created by evaluating at the source element’s centroids.

Most important for accuracy of this approximate multiplication method are the neighbor_order and expansion_degree.

The level divisions and maximum tree depth allow to optimize the computation time.

The world cube is the top level cube that has to contain all source elements and is a starting point for the algorithm.

XML element: <fast_multipole_matrix>
C++ type: KFastMultipoleMatrixGenerator
Also available as: fftm_multiplication
Attributes

Attribute

Type

Description

allowed_fraction

double

if strategy = Guided, fraction of elements abouve which subdivision is triggered

allowed_number

unsigned int

if strategy = Guided, number of elements above which subdivision is triggered

bias_degree

double

if strategy = Balanced, scale factor for biasing fft events

expansion_degree

unsigned int

the maximum degree of the multipole and local expansions used in the algorithm for precise results values in the range of 10 to 13 are recommended combined with a zero_mask size of 3. The example uses smaller values to speed up the computation to a manageable time for a demonstation.

insertion_ratio

double

elements are accepted by a cube if they are within the smallest ball around the cube multiplied by this factor which should be greater than one (for example 1.3). This allows small elements sitting on the borders of cubes to be accepted by small cubes and limit direct evaluation to a more local region.

integrator

string

Values: numeric, analytic, rwg, reference, default.

maximum_tree_depth

unsigned int

the maximum depth to which cubes are subdivided this restricts the tree size and computation time for the local moments at the cost of more direct evaluations later

neighbor_order

unsigned int

the distance in cubes that neighbors are defined by Cubes being having less than this number of cubes inbetween them in any direction are considered neighbors. Neighbors define the dead zone where the multipole expansion is not valid. Greater numbers like 3 make the algorithm more accurate but slower

region_expansion_factor

double

the factor by which the estimated region for the world cube is expanded in size to compensate for slight errors in the region estimation algorithm and to ensure all source elements are inside the world cube

strategy

string

strategy for the construction of the tree of cubes. The options are:

  • aggressive: divide a cube into smaller subcubes if at least one element can be used for at least one of the subcubes multipole expansions. This option, like all others, respects the maximum_tree_depth.

  • balanced

  • guided

Values: aggressive, balanced, guided.

top_level_divisions

unsigned int

the world cube gets divided into this many cubes along each side to create the first level of cubes. For MPI the number of top level cubes (which is top_level_divisions^3) has to be at least the number of MPI nodes.

tree_level_divisions

unsigned int

in all but the first subdivision the cubes get divided into this many cubes along each side. Two is the smallest useful value and a very good choice, too.

use_caching

bool

currently without effect

use_region_size_estimation

bool

this boolean option allows the automatic selection of the world cube from the underlying geometry so that all field sources are covered. Use with a region expansion factor (for example 1.1) to compensate for slight errors in the estimate. Try larger ones if elements are missed out.

verbosity

unsigned int

values between 0 and 3 define the amount of output on the console. A value of zero is mostly silent and a value of three gives maximum information.

world_cube_center

KEMStreamableThreeVector

if the region estimation in not used, the cube center can be defined manually by passing this option the vector of the user’s choice

world_cube_length

double

manually set the side length of the world cube

Example:

<fast_multipole_matrix
    strategy="balanced"
    top_level_divisions="4"
    tree_level_divisions="2"
    expansion_degree="4"
    neighbor_order="2"
    maximum_tree_depth="2"
    region_expansion_factor="1.1"
    use_region_size_estimation="true"
    world_cube_center="0 0 0"
    world_cube_length="10"
    use_caching="false"
    verbosity="3"
    insertion_ratio="1.33333333333"
    bias_degree="2"
    allowed_number="1"
    allowed_fraction="0.5"

/>

Used as:

More information

Appears in the documentation: