# Crate rusty_green_kernel[−][src]

Welcome to `rusty-green-kernel`

. This crate contains routine for the evaluation of sums of the form

$$f(\mathbf{x}_i) = \sum_jg(\mathbf{x}_i, \mathbf{y}_j)c_j$$

and the corresponding gradients

$$\nabla_{\mathbf{x}}f(\mathbf{x}_i) = \sum_j\nabla_{\mathbf{x}}g(\mathbf{x}_i, \mathbf{y}_j)c_j.$$ The following kernels are supported.

- The Laplace kernel: $g(\mathbf{x}, \mathbf{y}) = \frac{1}{4\pi|\mathbf{x} - \mathbf{y}|}$.
- The Helmholtz kernel: $g(\mathbf{x}, \mathbf{y}) = \frac{e^{ik|\mathbf{x} - \mathbf{y}|}}{4\pi|\mathbf{x} - \mathbf{y}|}$
- The modified Helmholtz kernel:$g(\mathbf{x}, \mathbf{y}) = \frac{e^{-\omega|\mathbf{x} - \mathbf{y}|}}{4\pi|\mathbf{x} - \mathbf{y}|}$

Within the library the $\mathbf{x}_i$ are named `targets`

and the $\mathbf{y}_j$ are named `sources`

. We use
the convention that $g(\mathbf{x}_i, \mathbf{y}_j) := 0$, whenever $\mathbf{x}_i = \mathbf{y}_j$.

The library provides a Rust API, C API, and Python API.

### Installation hints

The performance of the library strongly depends on being compiled with the right parameters for the underlying CPU. Almost any modern CPU supports AVX2 and FMA. To activate these features compile with

export RUSTFLAGS="-C target-feature=+avx2,+fma" cargo build --release

The activated compiler features can also be tested with `cargo rustc -- --print cfg`

.

To compile and install the Python module make sure that the wanted Python virtual environment is active.
The installation is performed using `maturin`

, which is available from Pypi and conda-forge.

After compiling the library as described above use

`maturin develop --release -b cffi`

to compile and install the Python module. It is important that the `RUSTFLAGS`

environment variable is set as stated above.
The Python module is called `rusty_green_kernel`

.

### Rust API

The `sources`

and `targets`

are both arrays of type `ndarray<T>`

with `T=f32`

or `T=f64`

. For `M`

targets and `N`

sources
the `sources`

are a `(3, N)`

array and the `targets`

are a `(3, M)`

array.

To evaluate the kernel matrix of all interactions between a vector of `sources`

and a `vector`

of targets for the Laplace kernel
use

`kernel_matrix = make_laplace_evaluator(sources, targets).assemble()`

To evaluate $f(\mathbf{x}_i) = \sum_jg(\mathbf{x}_i, \mathbf{y}_j)c_j$ we define the charges as `ndarray`

of
size `(ncharge_vecs, nsources)`

, where `ncharge_vecs`

is the number of charge vectors we want to evaluate and
`nsources`

is the number of sources. For Laplace and modified Helmholtz problems `charges`

must be of type `f32`

or `f64`

and for Helmholtz problems it must be of type `Complex<f32>`

or `Complex<f64>`

.

We can then evaluate the potential sum by

potential_sum = make_laplace_evaluator(sources, targets).evaluate( charges, EvalMode::Values, EvalMode::Value, ThreadingType::Parallel)

The result `potential_sum`

is a real `ndarray`

(for Laplace and modified Helmholtz) or a complex `ndarray`

(for Helmholtz).
It has the shape `(ncharge_vecs, ntargets, 1)`

. For `EvalMode::Value`

the function only computes the values $f(\mathbf{x}_i)$. For
`EvalMode::ValueGrad`

the array `potential_sum`

is of shape `(ncharge_vecs, ntargets, 4)`

and
returns the function values and the three components of the gradient along the most-inner dimension. The value
`ThreadingType::Parallel`

specifies that the evaluation is multithreaded. For this the Rayon library is used. For the
value `ThreadingType::Serial`

the code is executed single-threaded. The enum `ThreadingType`

is defined in the
crate `rusty-kernel-tools`

.

Basic access to `sources`

and `targets`

is provided through the trait `DirectEvaluatorAccessor`

, which is implemented by
the struct `DirectEvaluator`

. The Helmholtz kernel uses the trait `ComplexDirectEvaluator`

and the Laplace and modified
Helmholtz kernels use the trait `RealDirectEvaluator`

.

### C API

The C API in `c_api`

provides direct access to the functionality in a C compatible interface. All functions come in variants
for `f32`

and `f64`

types. Details are explaineed in the documentation of the corresponding functions.

### Python API

For details of the Python module see the Python documentation in the `rusty_green_kernel`

module.

## Re-exports

`pub use evaluators::*;` | |

`pub use kernels::EvalMode;` |

## Modules

c_api | This module defines C API function to access all assembly and evaluation routines. |

evaluators | |

kernels | Definitions of the supported Greens function kernels. |