快速入门

我们的Rust API简单，不需要用户创建临时元数据文件或设置辅助数据结构（如分层树），只需使用构建器模式对FMM进行参数化，并通过操作符链来调节运行时对象类型。在最简单的情况下，用户只需指定与源点和目标点坐标以及相关源密度关联的缓冲区。为FMM对象实现的特形接口允许用户访问关联的对象，如核和多重扩张数据。

实际上，完整的API更广泛，包括启用通过树级数进行变量扩张的特性和基于随机化奇异值分解和替代场转换实现的BLAS基于字段转换的加速预计算。可以在仓库中找到Python和Rust示例。

use rand::{thread_rng, Rng};
use green_kernels::{laplace_3d::Laplace3dKernel, types::EvalType};
use kifmm::{BlasFieldTranslationSaRcmp, SingleNodeBuilder, FmmSvdMode};
use kifmm::traits::tree::{FmmTree, Tree};
use kifmm::traits::fmm::Fmm;


fn main() {
    // Generate some random source/target/charge data
    let dim = 3;
    let nsources = 1000000;
    let ntargets = 2000000;

    // The number of vectors of source densities, FMM is configured from data
    let n = 1;
    let mut rng = thread_rng();
    let mut sources = vec![0f32; nsources * dim * n];
    let mut targets = vec![0f32; ntargets * dim * n];
    let mut charges = vec![0f32; nsources * n];

    sources.iter_mut().for_each(|s| *s = rng.gen());
    targets.iter_mut().for_each(|t| *t = rng.gen());
    charges.iter_mut().for_each(|c| *c = rng.gen());

    // Set tree parameters
    // Library refines tree till fewer than 'n_crit' points per leaf box
    let n_crit = Some(150);
    // Alternatively, users can specify the tree depth they require
    let depth = None;
    // Choose to branches associated with empty leaves from constructed tree
    let prune_empty = true;

    // Set FMM Parameters
    // Can either set globally for whole tree, or level-by-level
    let expansion_order = &[6];
    // Parameters which control speed and accuracy of BLAS based field translation
    let singular_value_threshold = Some(1e-5);
    let check_surface_diff = Some(2);

    // Create an FMM
    let svd_mode = FmmSvdMode::Deterministic; // Choose SVD compression mode, random or deterministic

    let mut fmm = SingleNodeBuilder::new()
        .tree(&sources, &targets, n_crit, depth, prune_empty) // Create tree
        .unwrap()
        .parameters(
            &charges,
            expansion_order, // Set expansion order, by tree level or globally
            Laplace3dKernel::new(), // Choose kernel,
            EvalType::Value, // Choose potential or potential + deriv evaluation
            BlasFieldTranslationSaRcmp::new(
              singular_value_threshold,
              check_surface_diff,
              svd_mode), // Choose field translation
        )
        .unwrap()
        .build()
        .unwrap();

    // Run FMM
    fmm.evaluate(true); // Optionally time the operators

    // Lookup potentials by leaf from target leaf boxes
    let leaf_idx = 0;
    let leaf = fmm.tree().target_tree().all_leaves().unwrap()[leaf_idx];
    let leaf_potential = fmm.potential(&leaf);
}

Python绑定

我们使用Maturin进行Python绑定，并提供了使用Python包管理器uv的安装示例。

仅支持Python 3.10.*以启用MayaVi进行绘图

1. 首先在新虚拟环境中安装Maturin（和pip）。

uv venv --python=3.10 && source .venv/bin/activate && uv pip install maturin pip

2. 使用Maturin CLI将Python绑定安装到该虚拟环境。

注意，必须从kifmm crate根目录而不是工作区根目录运行Maturin。

maturin develop --release

我们在python/examples目录中提供了Python API的示例用法以及可视化。

C绑定

我们在c文件夹中提供了一个使用CMake的最小C示例，以直接使用C绑定。