Crate rusty_green_kernel
source · [−]Expand description
Welcome to rusty-green-kernel
. This crate contains routines 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. To make sure that all native CPU features are activated use
export RUSTFLAGS="-C target-cpu=native"
cargo build --release
The activated compiler features can also be tested with cargo rustc --release -- --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 = f64::assemble_kernel(sources, targets, KernelType::Laplace, num_threads);
The variable num_threads
specifies how many CPU threads to use for the execution. For single precision
evaluation replace f64
by f32
. For Helmholtz or modified Helmholtz problems use
KernelType::Helmholtz(wavenumber)
or KernelType::ModifiedHelmholtz(omega)
. Note that for Helmholtz
the type of the result is complex, and the corresponding routine would therefore by
kernel_matrix = c64::assemble_kernel(sources, targets, KernelType::Helmholtz(wavenumber), num_threads);
or the corresponding with c32
.
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 c32
or c64
.
We can then evaluate the potential sum by
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.
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 rayon;
Modules
This module defines C API function to access all assembly and evaluation routines.
Structs
An axis index.
Enums
This enum provides the keywords scalar and vectorial
This enum defines the Evaluation Mode for kernels.
This enum defines the type of the kernel.
Traits
Functions
Return the dimension type (scalar or vectorial) for a kernel.
Type Definitions
two-dimensional array
three-dimensional array
two-dimensional array view
two-dimensional read-write array view
three-dimensional read-write array view