Contributing to Peroxide

Thank you for your interest in improving Peroxide! Whether you want to report a bug, request a feature, or send a code change, this document explains the conventions the project follows.

Reporting bugs and requesting features

Please open an issue at https://github.com/Axect/Peroxide/issues.

When reporting a bug, the following information makes it much easier to diagnose:

• A minimal Rust snippet that reproduces the problem
• Peroxide version (from Cargo.toml or cargo tree | head)
• Cargo features enabled (e.g. O3-openblas, plot, nc)
• Rust toolchain (rustc --version)
• Operating system and, when relevant, the BLAS / Python / HDF5 versions in use

Feature requests are also welcome through the issue tracker; describe the use case and, if you have one in mind, a suggested API shape.

Asking for help

For questions that are not bug reports (usage, design discussion, "is this the right approach"), please use GitHub Discussions or open an issue tagged as a question.

Submitting code changes

Peroxide follows the Gitflow workflow. A few practical rules:

1. Do not commit to master directly. master only receives merges from dev through reviewed pull requests.
2. Branch from dev for new work. Use the features/<short-name> convention (for example features/dataframe-cleanup). Open the pull request against dev.
3. Run the test suite before pushing. Enable the same Cargo features your change touches:

   cargo test --features "<features-you-touch>"
   

   For O3 work, pick the convenience flag that matches your platform (O3-openblas, O3-accelerate, O3-mkl, or O3-netlib); see the README "Pre-requisite" section for details.
4. Format and lint before opening the PR:

   cargo fmt
   cargo clippy --all-targets
   

   The continuous integration on push / pull_request runs the default, O3-openblas, pure-Rust, and plot feature jobs, so keeping these green locally avoids round-trips.

Source layout

• src
  • lib.rs : mod and re-export
  • complex: For complex vector, matrix & integrals.
    • mod.rs
    • integrate.rs : Complex integral
    • matrix.rs : Complex matrix
    • vector.rs : Complex vector
  • fuga : Fuga for controlling numerical algorithms.
    • mod.rs
  • macros : Macro files
    • julia_macro.rs : Julia like macro
    • matlab_macro.rs : MATLAB like macro
    • mod.rs
    • r_macro.rs : R like macro
  • ml : For machine learning (Beta)
    • mod.rs
    • reg.rs : Regression tools
  • numerical : To do numerical things
    • mod.rs
    • eigen.rs : Eigenvalue, Eigenvector algorithm
    • integral.rs : Numerical integration
    • interp.rs : Interpolation
    • newton.rs : Newton's Method
    • ode.rs : Main ODE solver with various algorithms
    • optimize.rs : Non-linear regression
    • root.rs : Root finding
    • spline.rs : Cubic spline, Cubic Hermite spline & B-Spline
    • utils.rs : Utils to do numerical things (e.g. jacobian)
  • prelude : Prelude for using simple
    • mod.rs
    • simpler.rs : Provides more simple api
  • special : Special functions written in pure Rust (Wrapper of puruspe)
    • mod.rs
    • function.rs : Special functions
  • statistics : Statistical Tools
    • mod.rs
    • dist.rs : Probability distributions
    • ops.rs : Some probabilistic operations
    • rand.rs : Wrapper for rand crate & Piecewise Rejection Sampling
    • stat.rs : Statistical tools
  • structure : Fundamental data structures
    • mod.rs
    • ad.rs : Automatic Differentiation (Jet<N> const-generic forward AD)
    • dataframe.rs : Dataframe
    • matrix.rs : Matrix
    • polynomial.rs : Polynomial
    • sparse.rs : For sparse structure (Beta)
    • vector.rs : Extra tools for Vec<f64>
  • traits
    • mod.rs
    • fp.rs : Functional programming toolbox
    • general.rs : General algorithms
    • math.rs : Mathematics
    • matrix.rs : Matrix traits
    • mutable.rs : Mutable toolbox
    • num.rs : Number, Real and more operations
    • pointer.rs : Matrix pointer and Vector pointer for convenience
    • stable.rs : Implement nightly-only features in stable
    • sugar.rs : Syntactic sugar for Vector
  • util
    • mod.rs
    • api.rs : Matrix constructor for various language style
    • low_level.rs : Low-level tools
    • non_macro.rs : Primordial version of macros
    • plot.rs : To draw plot (using pyo3)
    • print.rs : To print conveniently
    • useful.rs : Useful utils to implement library
    • wrapper.rs : Wrapper for other crates (e.g. rand)
    • writer.rs : More convenient write system

Code of conduct

By contributing you agree to abide by the project's Code of Conduct.

Thanks for all contributions!