Ferreus RBF

https://docs.rs/ferreus_rbf/latest/ferreus_rbf/
Admin
Ferreus RBF is a scalable Rust crate that provides fast global Radial Basis Function (RBF)...
Tokens:56,816
Snippets:598
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Spheroidal Kernel Isosurface Setup

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Example demonstrating the configuration of an RBFInterpolator using a spheroidal kernel.

```rust
69fn main() -> Result<(), Box<dyn std::error::Error>> {
70    let cwd = env::current_dir().unwrap();
71
72    // Define the filepath for the albatite test dataset
73    let file_path = cwd
74        .join("examples")
75        .join("datasets")
76        .join("albatite_SD_points.csv");
77
78    // Extract the source point coordinates and signed distance values
79    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
80        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;
81
82    // Get the axis aligned bounding box extents of the source points
83    // to use for the isosurface extraction
84    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());
85
86    // Define the RBF kernel to use
87    let kernel_type = RBFKernelType::Spheroidal;
88
89    // Define the spheroidal interpolant parameters
90    let order = SpheroidalOrder::Three;
91    let base_range = 50.0;
92    let sill = 10.0;
93
94    // Define the desired fitting accuracy
95    let fitting_accuracy = FittingAccuracy {
96        tolerance: 0.01,
97        tolerance_type: FittingAccuracyType::Absolute,
98    };
99
100    // Initialise an InterpolantSettings instance
101    let interpolant_settings = InterpolantSettings::builder(kernel_type)
102        .fitting_accuracy(fitting_accuracy)
103        .spheroidal_order(order)
104        .base_range(base_range)
105        .total_sill(sill)
106        .build();
107
108    // Create a callback to receive progress updates from the RBFInterpolator
```

--------------------------------

### Basic Isosurface Extraction Usage

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

A minimal example showing the parameters required to invoke the build_isosurface method.

```rust
let extents = vec![0.0, 0.0, 0.0, 100.0, 100.0, 100.0]; // [mins..., maxs...]
let resolution = 2.0;
let iso = 0.0;
let boundary_closure = BoundaryClosure::None;
let mesh = rbfi.build_isosurface(&extents, resolution, iso, boundary_closure);
```

--------------------------------

### Params Builder Usage

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/config/struct.Params.html?search=std%3A%3Avec

Examples demonstrating how to instantiate Params using the builder pattern with default and custom settings.

```rust
use ferreus_rbf::{
    config::Params, 
    interpolant_config::RBFKernelType
};

let params = Params::builder(RBFKernelType::Linear).build();
assert_eq!(params.solver_type, ferreus_rbf::config::Solvers::FGMRES);
```

```rust
use ferreus_rbf::{
    config::{Params, ParamsBuilder, Solvers}, 
    interpolant_config::RBFKernelType,
};

let params = Params::builder(RBFKernelType::Linear)
    .solver_type(Solvers::DDM)
    .naive_solve_threshold(2048)
    .test_unique(false)
    .build();

assert_eq!(
    (params.solver_type, params.naive_solve_threshold, params.test_unique),
    (Solvers::DDM, 2048, false)
);
```

--------------------------------

### Isosurface RBF evaluation setup

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=

Example of configuring an RBFInterpolator and building an evaluator with custom extents for isosurface extraction.

```rust
69fn main() -> Result<(), Box<dyn std::error::Error>> {
70    let cwd = env::current_dir().unwrap();
71
72    // Define the filepath for the albatite test dataset
73    let file_path = cwd
74        .join("examples")
75        .join("datasets")
76        .join("albatite_SD_points.csv");
77
78    // Extract the source point coordinates and signed distance values
79    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
80        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;
81
82    // Get the axis aligned bounding box extents of the source points
83    // to use for the isosurface extraction
84    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());
85
86    // Define the RBF kernel to use
87    let kernel_type = RBFKernelType::Linear;
88
89    // Define the desired fitting accuracy
90    let fitting_accuracy = FittingAccuracy {
91        tolerance: 0.01,
92        tolerance_type: FittingAccuracyType::Absolute,
93    };
94
95    // Initialise an InterpolantSettings instance
96    let interpolant_settings = InterpolantSettings::builder(kernel_type)
97        .fitting_accuracy(fitting_accuracy)
98        .build();
99
100    // Create a callback to receive progress updates from the RBFInterpolator
101    let callback = get_callback_sink();
102
103    // Setup and solve the RBF system
104    let mut rbfi = RBFInterpolator::builder(
105        source_points.clone(),
106        source_values.clone(),
107        interpolant_settings,
108    )
109    .progress_callback(callback.clone())
110    .build();
111
112    // Define the sampling grid resolution for the surfacer
113    let resolution = 10.0;
114
115    let evaluator_extents: Vec<f64> = source_point_extents
116        .iter()
117        .enumerate()
118        .map(|(idx, val)| match idx < 3 {
119            true => val - resolution * 10.0,
120            false => val + resolution * 10.0,
121        })
122        .collect();
123
124    rbfi.build_evaluator(Some(evaluator_extents));
125
126    let rbfi = Rc::new(RefCell::new(rbfi));
127    let rbfi_surface = Rc::clone(&rbfi);
128    let rbfi_grad = Rc::clone(&rbfi);
129
130    let mut surface_fn =
131        move |targets: MatRef<f64>| rbfi_surface.borrow_mut().evaluate_targets(targets.as_ref());
```

--------------------------------

### Isosurface Extraction Workflow

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

A complete example demonstrating the setup of an RBF system, building an evaluator, and generating an isosurface mesh from source points.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cwd = env::current_dir().unwrap();

    // Define the filepath for the albatite test dataset
    let file_path = cwd
        .join("examples")
        .join("datasets")
        .join("albatite_SD_points.csv");

    // Extract the source point coordinates and signed distance values
    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;

    // Get the axis aligned bounding box extents of the source points
    // to use for the isosurface extraction
    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());

    // Define the RBF kernel to use
    let kernel_type = RBFKernelType::Linear;

    // Define the desired fitting accuracy
    let fitting_accuracy = FittingAccuracy {
        tolerance: 0.01,
        tolerance_type: FittingAccuracyType::Absolute,
    };

    // Initialise an InterpolantSettings instance
    let interpolant_settings = InterpolantSettings::builder(kernel_type)
        .fitting_accuracy(fitting_accuracy)
        .build();

    // Create a callback to receive progress updates from the RBFInterpolator
    let callback = get_callback_sink();

    // Setup and solve the RBF system
    let mut rbfi = RBFInterpolator::builder(
        source_points.clone(),
        source_values.clone(),
        interpolant_settings,
    )
    .progress_callback(callback.clone())
    .build();

    // Define the sampling grid resolution for the surfacer
    let resolution = 10.0;

    let evaluator_extents: Vec<f64> = source_point_extents
        .iter()
        .enumerate()
        .map(|(idx, val)| match idx < 3 {
            true => val - resolution * 10.0,
            false => val + resolution * 10.0,
        })
        .collect();

    rbfi.build_evaluator(Some(evaluator_extents));

    let rbfi = Rc::new(RefCell::new(rbfi));
    let rbfi_surface = Rc::clone(&rbfi);
    let rbfi_grad = Rc::clone(&rbfi);

    let mut surface_fn =
        move |targets: MatRef<f64>| rbfi_surface.borrow_mut().evaluate_targets(targets.as_ref());

    let mut gradient_fn = move |targets: MatRef<f64>| {
        rbfi_grad
            .borrow_mut()
            .evaluate_targets_with_gradients(targets.as_ref())
    };

    let rmt_callback = callback.clone().into_rmt_progress();

    //  Define the isovalue at which to surface
    let isovalue = 0.0;

    // Generate an isosurface directly from the RMT extractor.
    let mesh = build_isosurface(
        source_points.as_ref(),
        &source_point_extents,
        resolution,
        isovalue,
        &mut surface_fn,
        Some(&mut gradient_fn),
        ClusterMethod::CurvatureWeighted,
        BoundaryClosure::ClosePositive,
        Some(rmt_callback.as_ref()),
    );

    //Save the isosurface out to an obj file
    let name = format!("isosurface_linear_{}m", fmt_num(resolution));
```

--------------------------------

### Initialize Dataset Processing

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Initial setup for loading CSV data and calculating bounding box extents.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cwd = env::current_dir().unwrap();

    // Define the filepath for the albatite test dataset
    let file_path = cwd
        .join("examples")
        .join("datasets")
        .join("albatite_SD_points.csv");

    // Extract the source point coordinates and signed distance values
    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;

    // Get the axis aligned bounding box extents of the source points
```

--------------------------------

### Initialize Spheroidal Kernel Parameters

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Partial setup code for defining spheroidal kernel parameters including order, range, and sill.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cwd = env::current_dir().unwrap();

    // Define the filepath for the albatite test dataset
    let file_path = cwd
        .join("examples")
        .join("datasets")
        .join("albatite_SD_points.csv");

    // Extract the source point coordinates and signed distance values
    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;

    // Get the axis aligned bounding box extents of the source points
    // to use for the isosurface extraction
    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());

    // Define the RBF kernel to use
    let kernel_type = RBFKernelType::Spheroidal;

    // Define the spheroidal interpolant parameters
    let order = SpheroidalOrder::Three;
    let base_range = 50.0;
    let sill = 10.0;
```

--------------------------------

### Constructing an RBFInterpolator

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Example demonstrating how to generate random data and build an RBFInterpolator using the builder pattern.

```rust
use ferreus_rbf::{
    RBFInterpolator,
    interpolant_config::{
        InterpolantSettings, 
        RBFKernelType,
    },
    generate_random_points,
    RBFTestFunctions,
};

// Generate some random data in the unit hypercube
let dimensions = 2;
let num_points = 100;
let source_points = generate_random_points(num_points, dimensions, Some(42));

// Assign some values to the source points using Franke's function
let source_values = RBFTestFunctions::franke_2d(&source_points);

// Create a InterpolantSettings instance
let interpolant_settings = InterpolantSettings::builder(RBFKernelType::Linear).build();

// Setup and solve the RBF
let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings).build();
```

--------------------------------

### Usage in RBF Interpolation

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/fn.csv_to_point_arrays.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example demonstrating how to load CSV data and use it to initialize an RBFInterpolator.

```rust
69fn main() -> Result<(), Box<dyn std::error::Error>> {
70    let cwd = env::current_dir().unwrap();
71
72    // Define the filepath for the albatite test dataset
73    let file_path = cwd
74        .join("examples")
75        .join("datasets")
76        .join("albatite_SD_points.csv");
77
78    // Extract the source point coordinates and signed distance values
79    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
80        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;
81
82    // Get the axis aligned bounding box extents of the source points
83    // to use for the isosurface extraction
84    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());
85
86    // Define the RBF kernel to use
87    let kernel_type = RBFKernelType::Linear;
88
89    // Define the desired fitting accuracy
90    let fitting_accuracy = FittingAccuracy {
91        tolerance: 0.01,
92        tolerance_type: FittingAccuracyType::Absolute,
93    };
94
95    // Initialise an InterpolantSettings instance
96    let interpolant_settings = InterpolantSettings::builder(kernel_type)
97        .fitting_accuracy(fitting_accuracy)
98        .build();
99
100    // Create a callback to receive progress updates from the RBFInterpolator
101    let callback = get_callback_sink();
102
103    // Setup and solve the RBF system
104    let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings)
105        .progress_callback(callback.clone())
106        .build();
107
108    // Define the sampling grid resolution for the surfacer
109    let resolution = 5.0;
110
111    //  Define the isovalue at which to surface
112    let isovalue = 0.0;
113
114    // Generate an isosurface
115    let mesh = rbfi.build_isosurface(
116        &source_point_extents,
117        resolution,
118        isovalue,
119        BoundaryClosure::None,
120    );
121
122    //Save the isosurface out to an obj file
123    let name = format!("isosurface_linear_{}m", fmt_num(resolution));
124    let outpath = cwd.join("examples").join(format!("{}.obj", &name));
125    mesh.save_obj(outpath, &name)?;
126
127    Ok(())
128}
```

--------------------------------

### Save Mesh as OBJ

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/isosurfacing/struct.Mesh.html?search=

Examples demonstrating how to save a generated isosurface mesh to a Wavefront OBJ file using the save_obj method.

```rust
32fn main() -> Result<(), Box<dyn std::error::Error>> {
33    let cwd = env::current_dir().unwrap();
34
35    // Define the extents for the isosurfacer
36    let extents = vec![-1.1, -1.1, -1.1, 1.1, 1.1, 1.1];
37
38    // Define the resolution to evaluate at
39    let resolution = 0.1;
40
41    // Define some seed points on the isosurface
42    let seed_points = mat![[1.0, 0.0, 0.0,], [-1.0, 0.0, 0.0],];
43
44    // Define the isovalue at which to surface
45    let isovalue = 0.0;
46
47    let mut surface_fn = |targets: MatRef<f64>| sphere(targets);
48
49    // Extract the isosurface
50    let mesh = build_isosurface(
51        seed_points.as_ref(),
52        &extents,
53        resolution,
54        isovalue,
55        &mut surface_fn,
56        None,
57        ClusterMethod::CurvatureWeighted,
58        BoundaryClosure::None,
59        None,
60    );
61
62    //Save the isosurface out to an obj file
63    let name = format!("isosurface_sphere_{}m", fmt_num(resolution));
64    let outpath = cwd.join(format!("{}.obj", &name));
65    mesh.save_obj(outpath, &name)?;
66
67    Ok(())
68}
```

```rust
69fn main() -> Result<(), Box<dyn std::error::Error>> {
70    let cwd = env::current_dir().unwrap();
71
72    // Define the filepath for the albatite test dataset
73    let file_path = cwd
74        .join("examples")
75        .join("datasets")
76        .join("albatite_SD_points.csv");
77
78    // Extract the source point coordinates and signed distance values
79    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
80        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;
81
82    // Get the axis aligned bounding box extents of the source points
83    // to use for the isosurface extraction
84    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());
85
86    // Define the RBF kernel to use
87    let kernel_type = RBFKernelType::Linear;
88
89    // Define the desired fitting accuracy
90    let fitting_accuracy = FittingAccuracy {
91        tolerance: 0.01,
92        tolerance_type: FittingAccuracyType::Absolute,
93    };
94
95    // Initialise an InterpolantSettings instance
96    let interpolant_settings = InterpolantSettings::builder(kernel_type)
97        .fitting_accuracy(fitting_accuracy)
98        .build();
99
100    // Create a callback to receive progress updates from the RBFInterpolator
101    let callback = get_callback_sink();
102
103    // Setup and solve the RBF system
104    let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings)
105        .progress_callback(callback.clone())
106        .build();
107
108    // Define the sampling grid resolution for the surfacer
109    let resolution = 5.0;
110
111    //  Define the isovalue at which to surface
112    let isovalue = 0.0;
113
114    // Generate an isosurface
115    let mesh = rbfi.build_isosurface(
116        &source_point_extents,
117        resolution,
118        isovalue,
119        BoundaryClosure::None,
120    );
121
122    //Save the isosurface out to an obj file
123    let name = format!("isosurface_linear_{}m", fmt_num(resolution));
124    let outpath = cwd.join("examples").join(format!("{}.obj", &name));
125    mesh.save_obj(outpath, &name)?;
126
127    Ok(())
128}
```

--------------------------------

### Initialize InterpolantSettings with Linear Kernel

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/interpolant_config/struct.InterpolantSettings.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates creating settings for a linear kernel using the builder pattern, which defaults the drift to constant.

```rust
use ferreus_rbf::{interpolant_config::{RBFKernelType, InterpolantSettings, Drift}};

let interpolant_settings = InterpolantSettings::builder(RBFKernelType::Linear).build();

assert_eq!(
    (interpolant_settings.kernel_type, interpolant_settings.drift),
    (RBFKernelType::Linear, Drift::Constant) 
)
```

--------------------------------

### Configure and Solve RBF System

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolatorBuilder.html

Demonstrates initializing an RBFInterpolator using the builder pattern with custom settings and generating an isosurface.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cwd = env::current_dir().unwrap();

    // Define the filepath for the albatite test dataset
    let file_path = cwd
        .join("examples")
        .join("datasets")
        .join("albatite_SD_points.csv");

    // Extract the source point coordinates and signed distance values
    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;

    // Get the axis aligned bounding box extents of the source points
    // to use for the isosurface extraction
    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());

    // Define the RBF kernel to use
    let kernel_type = RBFKernelType::Spheroidal;

    // Define the spheroidal interpolant parameters
    let order = SpheroidalOrder::Three;
    let base_range = 50.0;
    let sill = 10.0;

    // Define a drift other than the default
    let drift = Drift::Constant;

    // Define the desired fitting accuracy
    let fitting_accuracy = FittingAccuracy {
        tolerance: 0.01,
        tolerance_type: FittingAccuracyType::Absolute,
    };

    // Initialise an InterpolantSettings instance
    let interpolant_settings = InterpolantSettings::builder(kernel_type)
        .fitting_accuracy(fitting_accuracy)
        .spheroidal_order(order)
        .base_range(base_range)
        .total_sill(sill)
        .drift(drift)
        .build();

    // Create a callback to receive progress updates from the RBFInterpolator
    let callback = get_callback_sink();

    // Setup and solve the RBF system
    let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings)
        .progress_callback(callback.clone())
        .build();

    // Define the sampling grid resolution for the surfacer
    let resolution = 5.0;

    //  Define the isovalue at which to surface
    let isovalue = 0.0;

    // Generate an isosurface
    let mesh = rbfi.build_isosurface(
        &source_point_extents,
        resolution,
        isovalue,
        BoundaryClosure::None,
    );

    //Save the isosurface out to an obj file
    let name = format!("isosurface_spheroidal_drift_{}m", fmt_num(resolution));
    let outpath = cwd.join("examples").join(format!("{}.obj", &name));
    mesh.save_obj(outpath, &name)?;

    Ok(())
}
```

--------------------------------

### Configure and solve RBF system with drift

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html

Demonstrates initializing an RBFInterpolator with specific drift and fitting accuracy settings, then generating an isosurface.

```rust
95    // Define a drift other than the default
96    let drift = Drift::Constant;
97
98    // Define the desired fitting accuracy
99    let fitting_accuracy = FittingAccuracy {
100        tolerance: 0.01,
101        tolerance_type: FittingAccuracyType::Absolute,
102    };
103
104    // Initialise an InterpolantSettings instance
105    let interpolant_settings = InterpolantSettings::builder(kernel_type)
106        .fitting_accuracy(fitting_accuracy)
107        .spheroidal_order(order)
108        .base_range(base_range)
109        .total_sill(sill)
110        .drift(drift)
111        .build();
112
113    // Create a callback to receive progress updates from the RBFInterpolator
114    let callback = get_callback_sink();
115
116    // Setup and solve the RBF system
117    let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings)
118        .progress_callback(callback.clone())
119        .build();
120
121    // Define the sampling grid resolution for the surfacer
122    let resolution = 5.0;
123
124    //  Define the isovalue at which to surface
125    let isovalue = 0.0;
126
127    // Generate an isosurface
128    let mesh = rbfi.build_isosurface(
129        &source_point_extents,
130        resolution,
131        isovalue,
132        BoundaryClosure::None,
133    );
134
135    //Save the isosurface out to an obj file
136    let name = format!("isosurface_spheroidal_drift_{}m", fmt_num(resolution));
137    let outpath = cwd.join("examples").join(format!("{}.obj", &name));
138    mesh.save_obj(outpath, &name)?;
139
140    Ok(())
141}
```

--------------------------------

### Initialize InterpolantSettings with Default Builder

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/interpolant_config/struct.InterpolantSettingsBuilder.html?search=std%3A%3Avec

Demonstrates the basic usage of the InterpolantSettings builder to create settings with a specified kernel type.

```rust
    // Select the Linear RBF kernel
    let interpolant_settings = InterpolantSettings::builder(RBFKernelType::ThinPlateSpline).build();
```

--------------------------------

### equivalent

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/config/enum.Solvers.html?search=u32+-%3E+bool

Checks for equivalence between the current instance and a provided u32 key.

```APIDOC
## Method: equivalent

### Description
Checks if the instance is equivalent to the provided key of type u32.

### Signature
`fn equivalent(&self, key: &u32) -> bool`

### Supported Types
- ferreus_rbf::interpolant_config::SpheroidalOrder
- ferreus_rbf::interpolant_config::Drift
- ferreus_rbf::isosurfacing::BoundaryClosure
- ferreus_rbf::isosurfacing::ClusterMethod
```

--------------------------------

### Initialize Params with defaults

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/config/struct.Params.html

Create a Params instance using the builder pattern with default settings.

```rust
use ferreus_rbf::{
    config::Params, 
    interpolant_config::RBFKernelType
};

let params = Params::builder(RBFKernelType::Linear).build();
assert_eq!(params.solver_type, ferreus_rbf::config::Solvers::FGMRES);
```

--------------------------------

### Initialize InterpolantSettings for Spheroidal RBF

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/interpolant_config/struct.InterpolantSettings.html

Demonstrates the builder pattern to configure kernel type, fitting accuracy, and spheroidal parameters before building an RBFInterpolator.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cwd = env::current_dir().unwrap();

    // Define the filepath for the albatite test dataset
    let file_path = cwd
        .join("examples")
        .join("datasets")
        .join("albatite_SD_points.csv");

    // Extract the source point coordinates and signed distance values
    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;

    // Get the axis aligned bounding box extents of the source points
    // to use for the isosurface extraction
    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());

    // Define the RBF kernel to use
    let kernel_type = RBFKernelType::Spheroidal;

    // Define the spheroidal interpolant parameters
    let order = SpheroidalOrder::Three;
    let base_range = 50.0;
    let sill = 10.0;

    // Define the desired fitting accuracy
    let fitting_accuracy = FittingAccuracy {
        tolerance: 0.01,
        tolerance_type: FittingAccuracyType::Absolute,
    };

    // Initialise an InterpolantSettings instance
    let interpolant_settings = InterpolantSettings::builder(kernel_type)
        .fitting_accuracy(fitting_accuracy)
        .spheroidal_order(order)
        .base_range(base_range)
        .total_sill(sill)
        .build();

    // Create a callback to receive progress updates from the RBFInterpolator
    let callback = get_callback_sink();

    // Setup and solve the RBF system
    let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings)
        .progress_callback(callback.clone())
        .build();

    // Define the sampling grid resolution for the surfacer
    let resolution = 5.0;

    //  Define the isovalue at which to surface
    let isovalue = 0.0;

    // Generate an isosurface
    let mesh = rbfi.build_isosurface(
        &source_point_extents,
        resolution,
        isovalue,
        BoundaryClosure::None,
    );

    //Save the isosurface out to an obj file
    let name = format!("isosurface_spheroidal_{}m", fmt_num(resolution));
    let outpath = cwd.join("examples").join(format!("{}.obj", &name));
    mesh.save_obj(outpath, &name)?;

    Ok(())
}
```

--------------------------------

### Configure RBFInterpolator with Drift

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Demonstrates initializing an RBFInterpolator with custom drift and fitting accuracy settings.

```rust
    // Define a drift other than the default
    let drift = Drift::Constant;

    // Define the desired fitting accuracy
    let fitting_accuracy = FittingAccuracy {
        tolerance: 0.01,
        tolerance_type: FittingAccuracyType::Absolute,
    };

    // Initialise an InterpolantSettings instance
    let interpolant_settings = InterpolantSettings::builder(kernel_type)
        .fitting_accuracy(fitting_accuracy)
        .spheroidal_order(order)
        .base_range(base_range)
        .total_sill(sill)
        .drift(drift)
        .build();

    // Create a callback to receive progress updates from the RBFInterpolator
    let callback = get_callback_sink();

    // Setup and solve the RBF system
    let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings)
        .progress_callback(callback.clone())
        .build();

    // Define the sampling grid resolution for the surfacer
    let resolution = 5.0;

    //  Define the isovalue at which to surface
    let isovalue = 0.0;

    // Generate an isosurface
    let mesh = rbfi.build_isosurface(
        &source_point_extents,
        resolution,
        isovalue,
        BoundaryClosure::None,
    );

    //Save the isosurface out to an obj file
    let name = format!("isosurface_spheroidal_drift_{}m", fmt_num(resolution));
    let outpath = cwd.join("examples").join(format!("{}.obj", &name));
    mesh.save_obj(outpath, &name)?;

    Ok(())
}
```

--------------------------------

### InterpolantSettingsBuilder::build()

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/interpolant_config/struct.InterpolantSettingsBuilder.html

Finalizes the configuration and returns an InterpolantSettings instance.

```APIDOC
## InterpolantSettingsBuilder::build()

### Description
Consumes the builder and returns a fully configured InterpolantSettings instance.

### Returns
- **InterpolantSettings** - The constructed settings object.
```

--------------------------------

### Progress Monitoring

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=

Configuring progress callbacks to receive updates during the iterative solver process.

```APIDOC
## progress_callback(sink: ProgressSink)

### Description
Attaches a progress callback to the RBFInterpolatorBuilder. The callback receives `ProgressMsg` variants, including solver iterations, residual values, and surfacing progress.

### Usage
Use `closure_sink` to define a closure that processes `ProgressMsg` variants such as `SolverIteration`, `SurfacingProgress`, or `DuplicatesRemoved`.
```

--------------------------------

### Configure Params with custom settings

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/config/struct.Params.html

Customize solver parameters using the builder methods before calling build().

```rust
use ferreus_rbf::{
    config::{Params, ParamsBuilder, Solvers}, 
    interpolant_config::RBFKernelType,
};

let params = Params::builder(RBFKernelType::Linear)
    .solver_type(Solvers::DDM)
    .naive_solve_threshold(2048)
    .test_unique(false)
    .build();

assert_eq!(
    (params.solver_type, params.naive_solve_threshold, params.test_unique),
    (Solvers::DDM, 2048, false)
);
```

--------------------------------

### Configure RBF Interpolant Settings

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/interpolant_config/struct.InterpolantSettings.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates initializing InterpolantSettings with a specific kernel type and optional fitting accuracy parameters.

```rust
7fn main() -> Result<(), Box<dyn std::error::Error>> {
8    // Define input source points in a 2D grid within [0, 1]^2
9    let dim = 2usize;
10    let num_points = 100usize;
11    let points = generate_random_points(num_points, dim, Some(42));
12
13    // Define some values at the source points using Franke's function
14    let point_values = RBFTestFunctions::franke_2d(&points);
15
16    // Select the Linear RBF kernel
17    let interpolant_settings = InterpolantSettings::builder(RBFKernelType::ThinPlateSpline).build();
18
19    // Setup and solve the RBF
20    let rbfi = RBFInterpolator::builder(points, point_values, interpolant_settings).build();
21
22    // Build a 2D grid of target points in [0, 1]^2 to evaluate the RBF at
23    let n = 50;
24    let target_points = create_evaluation_grid(&[(0.0, 1.0), (0.0, 1.0)], &[n, n]);
25
26    // Evaluate the RBF at the target points
27    let _interpolated_values = rbfi.evaluate(target_points.as_ref());
28
29    Ok(())
30}
```

```rust
69fn main() -> Result<(), Box<dyn std::error::Error>> {
70    let cwd = env::current_dir().unwrap();
71
72    // Define the filepath for the albatite test dataset
73    let file_path = cwd
74        .join("examples")
75        .join("datasets")
76        .join("albatite_SD_points.csv");
77
78    // Extract the source point coordinates and signed distance values
79    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
80        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;
81
82    // Get the axis aligned bounding box extents of the source points
83    // to use for the isosurface extraction
84    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());
85
86    // Define the RBF kernel to use
87    let kernel_type = RBFKernelType::Linear;
88
89    // Define the desired fitting accuracy
90    let fitting_accuracy = FittingAccuracy {
91        tolerance: 0.01,
92        tolerance_type: FittingAccuracyType::Absolute,
93    };
94
95    // Initialise an InterpolantSettings instance
96    let interpolant_settings = InterpolantSettings::builder(kernel_type)
97        .fitting_accuracy(fitting_accuracy)
98        .build();
99
100    // Create a callback to receive progress updates from the RBFInterpolator
101    let callback = get_callback_sink();
102
103    // Setup and solve the RBF system
104    let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings)
105        .progress_callback(callback.clone())
106        .build();
107
108    // Define the sampling grid resolution for the surfacer
109    let resolution = 5.0;
110
111    //  Define the isovalue at which to surface
112    let isovalue = 0.0;
113
114    // Generate an isosurface
115    let mesh = rbfi.build_isosurface(
116        &source_point_extents,
117        resolution,
118        isovalue,
119        BoundaryClosure::None,
120    );
121
122    //Save the isosurface out to an obj file
123    let name = format!("isosurface_linear_{}m", fmt_num(resolution));
124    let outpath = cwd.join("examples").join(format!("{}.obj", &name));
125    mesh.save_obj(outpath, &name)?;
126
127    Ok(())
128}
```

--------------------------------

### Create an evaluation grid in Rust

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/fn.create_evaluation_grid.html

Generates a 2D grid of target points within the range [0, 1] for both dimensions using 50 samples per dimension.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Define input source points in a 2D grid within [0, 1]^2
    let dim = 2usize;
    let num_points = 100usize;
    let points = generate_random_points(num_points, dim, Some(42));

    // Define some values at the source points using Franke's function
    let point_values = RBFTestFunctions::franke_2d(&points);

    // Select the Linear RBF kernel
    let interpolant_settings = InterpolantSettings::builder(RBFKernelType::ThinPlateSpline).build();

    // Setup and solve the RBF
    let rbfi = RBFInterpolator::builder(points, point_values, interpolant_settings).build();

    // Build a 2D grid of target points in [0, 1]^2 to evaluate the RBF at
    let n = 50;
    let target_points = create_evaluation_grid(&[(0.0, 1.0), (0.0, 1.0)], &[n, n]);

    // Evaluate the RBF at the target points
    let _interpolated_values = rbfi.evaluate(target_points.as_ref());

    Ok(())
}
```

--------------------------------

### RBFInterpolator Construction

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Demonstrates how to construct an RBFInterpolator using the builder pattern with provided source points, values, and interpolant settings.

```APIDOC
## RBFInterpolator::builder

### Description
Constructs a new RBFInterpolator instance using the builder pattern. This method requires source points, source values, and interpolant settings to configure and solve the RBF model.

### Usage
```rust
let mut rbfi = RBFInterpolator::builder(source_points, source_values, interpolant_settings).build();
```
```

--------------------------------

### pub fn params(self, params: Params) -> Self

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolatorBuilder.html?search=u32+-%3E+bool

Sets custom solver and algorithm parameters for the interpolator.

```APIDOC
## pub fn params(self, params: Params) -> Self

### Description
Sets custom solver and algorithm parameters for the RBFInterpolator being built.

### Parameters
- **params** (Params) - Required - The solver and algorithm configuration parameters.
```

--------------------------------

### Configure Linear RBF Interpolant with Global Trend

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Shows the initialization of an InterpolantSettings instance using a linear kernel and defining global trend parameters.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cwd = env::current_dir().unwrap();

    // Define the filepath for the albatite test dataset
    let file_path = cwd
        .join("examples")
        .join("datasets")
        .join("albatite_SD_points.csv");

    // Extract the source point coordinates and signed distance values
    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;

    // Get the axis aligned bounding box extents of the source points
    // to use for the isosurface extraction
    let source_point_extents = ferreus_rbf_utils::get_pointarray_extents(source_points.as_ref());

    // Define the RBF kernel to use
    let kernel_type = RBFKernelType::Linear;

    // Define the desired fitting accuracy
    let fitting_accuracy = FittingAccuracy {
        tolerance: 0.01,
        tolerance_type: FittingAccuracyType::Absolute,
    };

    // Initialise an InterpolantSettings instance
    let interpolant_settings = InterpolantSettings::builder(kernel_type)
        .fitting_accuracy(fitting_accuracy)
        .build();

    // Define a global trend
    let dip = 87.0;
    let dip_direction = 255.0;
    let pitch = 25.0;
```

--------------------------------

### Extract source points for RBF interpolation

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html

Initializes the environment and extracts source points from a CSV file for RBF interpolation.

```rust
69fn main() -> Result<(), Box<dyn std::error::Error>> {
70    let cwd = env::current_dir().unwrap();
71
72    // Define the filepath for the albatite test dataset
73    let file_path = cwd
74        .join("examples")
75        .join("datasets")
76        .join("albatite_SD_points.csv");
77
78    // Extract the source point coordinates and signed distance values
79    let (source_points, source_values): (Mat<f64>, Mat<f64>) =
80        csv_to_point_arrays(file_path.to_str().expect("valid UTF-8 path"), true)?;
81
82    // Get the axis aligned bounding box extents of the source points
```

--------------------------------

### Configure Progress Callbacks

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolator.html?search=u32+-%3E+bool

Uses closure_sink to monitor solver iterations and surfacing progress during interpolation.

```rust
use ferreus_rbf::{
    RBFInterpolator,
    interpolant_config::{
        InterpolantSettings, 
        RBFKernelType,
    },
    generate_random_points,
    RBFTestFunctions,
    progress::{
        ProgressMsg, 
        closure_sink,
    },
};

// Generate some random data in the unit hypercube
let dimensions = 2;
let num_points = 10000;
let source_points = generate_random_points(num_points, dimensions, Some(42));

// Assign some values to the source points using Franke's function
let source_values = RBFTestFunctions::franke_2d(&source_points);

// Use the closure_sink function to setup a way to process the progress messages.
// In this example we just print each message as it arrives.
let (sink, _listener) = closure_sink(256, |msg| match msg {
    ProgressMsg::SolverIteration {
        iter,
        residual,
        progress,
    } => {
        println!(
            "Iteration: {:>3}    {:>.5E} {:>.1}%",
            iter,
            residual,
            progress * 100.0
        );
    }
    ProgressMsg::SurfacingProgress {
        isovalue,
        stage,
        progress,
    } => {
        println!(
            "Isovalue: {:?}    Stage: {} {:>.1}%",
            isovalue,
            stage,
            progress * 100.0
        );
    }
    ProgressMsg::DuplicatesRemoved { num_duplicates } => {
        println!("Removed {:>3} duplicate points", num_duplicates);
    }

    ProgressMsg::Message { message } => {
        println!("{message}");
    }
});

let kernel = RBFKernelType::Linear;

// Create a InterpolantSettings instance
let interpolant_settings = InterpolantSettings::builder(kernel).build();

// Setup and solve the RBF
let mut rbfi = RBFInterpolator::builder(
        source_points, 
        source_values, 
        interpolant_settings,
    )
    .progress_callback(sink.clone())
    .build();
```

--------------------------------

### params(self, params: Params) -> Self

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/struct.RBFInterpolatorBuilder.html

Sets custom solver and algorithm parameters for the interpolator.

```APIDOC
### pub fn params(self, params: Params) -> Self

Sets custom solver and algorithm parameters for the RBF system.
```

--------------------------------

### Configure Spheroidal Kernel with Drift and Nugget

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/interpolant_config/struct.InterpolantSettings.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes an InterpolantSettings instance with Spheroidal order, constant drift, and a nugget parameter.

```rust
use ferreus_rbf::{interpolant_config::{RBFKernelType, InterpolantSettings, Drift, SpheroidalOrder}};

let interpolant_settings = InterpolantSettings::builder(RBFKernelType::Spheroidal)
    .spheroidal_order(SpheroidalOrder::Five)
    .drift(Drift::Constant)
    .nugget(10.0)
    .base_range(100.0)
    .total_sill(10.0)
    .build();

assert_eq!(
    (
        interpolant_settings.kernel_type, 
        interpolant_settings.spheroidal_order,
        interpolant_settings.drift,
        interpolant_settings.nugget,
        interpolant_settings.base_range,
        interpolant_settings.total_sill,
    ),
    (
        RBFKernelType::Spheroidal, 
        SpheroidalOrder::Five,
        Drift::Constant,
        10.0,
        100.0,
        10.0
    ) 
)
```

--------------------------------

### Usage of create_evaluation_grid in RBF Interpolation

Source: https://docs.rs/ferreus_rbf/latest/ferreus_rbf/fn.create_evaluation_grid.html?search=

Demonstrates generating a 2D grid of target points within [0, 1] for evaluating an RBF interpolant.

```rust
7fn main() -> Result<(), Box<dyn std::error::Error>> {
8    // Define input source points in a 2D grid within [0, 1]^2
9    let dim = 2usize;
10    let num_points = 100usize;
11    let points = generate_random_points(num_points, dim, Some(42));
12
13    // Define some values at the source points using Franke's function
14    let point_values = RBFTestFunctions::franke_2d(&points);
15
16    // Select the Linear RBF kernel
17    let interpolant_settings = InterpolantSettings::builder(RBFKernelType::ThinPlateSpline).build();
18
19    // Setup and solve the RBF
20    let rbfi = RBFInterpolator::builder(points, point_values, interpolant_settings).build();
21
22    // Build a 2D grid of target points in [0, 1]^2 to evaluate the RBF at
23    let n = 50;
24    let target_points = create_evaluation_grid(&[(0.0, 1.0), (0.0, 1.0)], &[n, n]);
25
26    // Evaluate the RBF at the target points
27    let _interpolated_values = rbfi.evaluate(target_points.as_ref());
28
29    Ok(())
30}
```
Tokens:
Raw