search

Axect / Peroxide

Rust numeric library with R, MATLAB & Python syntax
https://crates.io/crates/peroxide
Apache License 2.0
474 stars 27 forks source link
dataframe determinant interpolation jacobian linear-algebra lu-decomposition matlab matrix numerical-analysis numerical-integration optimization peroxide r regression rust rust-numeric-library scientific-computing simd-openblas spline statistics

readme

Peroxide

On crates.io On docs.rs DOI github

maintenance

Rust numeric library contains linear algebra, numerical analysis, statistics and machine learning tools with R, MATLAB, Python like macros.

Table of Contents

Why Peroxide?

1. Customize features

Peroxide provides various features.

If you want to do high performance computation and more linear algebra, then choose O3 feature. If you don't want to depend C/C++ or Fortran libraries, then choose default feature. If you want to draw plot with some great templates, then choose plot feature.

You can choose any features simultaneously.

2. Easy to optimize

Peroxide uses a 1D data structure to represent matrices, making it straightforward to integrate with BLAS (Basic Linear Algebra Subprograms). This means that Peroxide can guarantee excellent performance for linear algebraic computations by leveraging the optimized routines provided by BLAS.

3. Friendly syntax

For users familiar with numerical computing libraries like NumPy, MATLAB, or R, Rust's syntax might seem unfamiliar at first. This can make it more challenging to learn and use Rust libraries that heavily rely on Rust's unique features and syntax.

However, Peroxide aims to bridge this gap by providing a syntax that resembles the style of popular numerical computing environments. With Peroxide, you can perform complex computations using a syntax similar to that of R, NumPy, or MATLAB, making it easier for users from these backgrounds to adapt to Rust and take advantage of its performance benefits.

For example,

#[macro_use]
extern crate peroxide;
use peroxide::prelude::*;

fn main() {
    // MATLAB like matrix constructor
    let a = ml_matrix("1 2;3 4");

    // R like matrix constructor (default)
    let b = matrix(c!(1,2,3,4), 2, 2, Row);

    // Or use zeros
    let mut z = zeros(2, 2);
    z[(0,0)] = 1.0;
    z[(0,1)] = 2.0;
    z[(1,0)] = 3.0;
    z[(1,1)] = 4.0;

    // Simple but effective operations
    let c = a * b; // Matrix multiplication (BLAS integrated)

    // Easy to pretty print
    c.print();
    //       c[0] c[1]
    // r[0]     1    3
    // r[1]     2    4

    // Easy to do linear algebra
    c.det().print();
    c.inv().print();

    // and etc.
}

4. Can choose two different coding styles.

In peroxide, there are two different options.

For examples, let's see norm.

In prelude, use norm is simple: a.norm(). But it only uses L2 norm for Vec<f64>. (For Matrix, Frobenius norm.)

#[macro_use]
extern crate peroxide;
use peroxide::prelude::*;

fn main() {
    let a = c!(1, 2, 3);
    let l2 = a.norm();      // L2 is default vector norm

    assert_eq!(l2, 14f64.sqrt());
}

In fuga, use various norms. But you should write a little bit longer than prelude.

#[macro_use]
extern crate peroxide;
use peroxide::fuga::*;

fn main() {
    let a = c!(1, 2, 3);
    let l1 = a.norm(Norm::L1);
    let l2 = a.norm(Norm::L2);
    let l_inf = a.norm(Norm::LInf);
    assert_eq!(l1, 6f64);
    assert_eq!(l2, 14f64.sqrt());
    assert_eq!(l_inf, 3f64);
}

5. Batteries included

Peroxide can do many things.

6. Compatible with Mathematics

After 0.23.0, peroxide is compatible with mathematical structures. Matrix, Vec<f64>, f64 are considered as inner product vector spaces. And Matrix, Vec<f64> are linear operators - Vec<f64> to Vec<f64> and Vec<f64> to f64. For future, peroxide will include more & more mathematical concepts. (But still practical.)

7. Written in Rust

Rust provides a strong type system, ownership concepts, borrowing rules, and other features that enable developers to write safe and efficient code. It also offers modern programming techniques like trait-based abstraction and convenient error handling. Peroxide is developed to take full advantage of these strengths of Rust.

The example code demonstrates how Peroxide can be used to simulate the Lorenz attractor and visualize the results. It showcases some of the powerful features provided by Rust, such as the ? operator for streamlined error handling and the ODEProblem trait for abstracting ODE problems.

use peroxide::fuga::*;

fn main() -> Result<(), Box<dyn Error>> {
    let rkf45 = RKF45::new(1e-4, 0.9, 1e-6, 1e-2, 100);
    let basic_ode_solver = BasicODESolver::new(rkf45);
    let (_, y_vec) = basic_ode_solver.solve(
        &Lorenz,
        (0f64, 100f64),
        1e-2,
    )?; // Error handling with `?` - can check constraint violation and etc.
    let y_mat = py_matrix(y_vec);
    let y0 = y_mat.col(0);
    let y2 = y_mat.col(2);

    // Simple but effective plotting
    let mut plt = Plot2D::new();
    plt
        .set_domain(y0)
        .insert_image(y2)
        .set_xlabel(r"$y_0$")
        .set_ylabel(r"$y_2$")
        .set_style(PlotStyle::Nature)
        .tight_layout()
        .set_dpi(600)
        .set_path("example_data/lorenz_rkf45.png")
        .savefig()?;

    Ok(())
}

struct Lorenz;

impl ODEProblem for Lorenz {
    fn initial_conditions(&self) -> Vec<f64> {
        vec![10f64, 1f64, 1f64]
    }

    fn rhs(&self, t: f64, y: &[f64], dy: &mut [f64]) -> anyhow::Result<()> {
        dy[0] = 10f64 * (y[1] - y[0]);
        dy[1] = 28f64 * y[0] - y[1] - y[0] * y[2];
        dy[2] = -8f64 / 3f64 * y[2] + y[0] * y[1];
        Ok(())
    }
}

Running the code produces the following visualization of the Lorenz attractor:

lorenz_rkf45.png

Peroxide strives to leverage the benefits of the Rust language while providing a user-friendly interface for numerical computing and scientific simulations.

How's that? Let me know if there's anything else you'd like me to improve!

Latest README version

Corresponding to 0.37.7

Pre-requisite

Install

  1. Default

    cargo add peroxide

  2. OpenBLAS

    cargo add peroxide --features O3

  3. Plot

    cargo add peroxide --features plot

  4. NetCDF dependency for DataFrame

    cargo add peroxide --features nc

  5. CSV dependency for DataFrame

    cargo add peroxide --features csv

  6. Parquet dependency for DataFrame

    cargo add peroxide --features parquet

  7. Serialize or Deserialize with Matrix or polynomial

    cargo add peroxide --features serde

  8. All features

    cargo add peroxide --features "O3 plot nc csv parquet serde"

Useful tips for features

Module Structure

Documentation

Examples

Release Info

To see RELEASES.md

Contributes Guide

See CONTRIBUTES.md

LICENSE

Peroxide is licensed under dual licenses - Apache License 2.0 and MIT License.

TODO

To see TODO.md

Cite Peroxide

Hey there! If you're using Peroxide in your research or project, you're not required to cite us. But if you do, we'd be really grateful! 😊

To make citing Peroxide easy, we've created a DOI through Zenodo. Just click on this badge:

DOI

This will take you to the Zenodo page for Peroxide. At the bottom, you'll find the citation information in various formats like BibTeX, RIS, and APA.

So, if you want to acknowledge the work we've put into Peroxide, citing us would be a great way to do it! Thanks for considering it, we appreciate your support! 👍