From c5ab4873c4a4717823eace1a8c571ffb2ecdcefc Mon Sep 17 00:00:00 2001 From: Stefan Kroboth Date: Fri, 16 Feb 2024 08:21:09 +0100 Subject: [PATCH] Documentation for argmin_testfunctions and python module --- crates/argmin-testfunctions/README.md | 97 +++++++++++++++++++++++- crates/argmin-testfunctions/src/lib.rs | 69 ++++++++++++++++- python/argmin-testfunctions-py/README.md | 7 +- 3 files changed, 164 insertions(+), 9 deletions(-) diff --git a/crates/argmin-testfunctions/README.md b/crates/argmin-testfunctions/README.md index 0a444fd77..c7ddc7d94 100644 --- a/crates/argmin-testfunctions/README.md +++ b/crates/argmin-testfunctions/README.md @@ -1,9 +1,97 @@ -# argmin-testfunctions +

+ +

+

argmin_testfunctions

-Test functions for optimization algorithms in Rust. +

+ Website + | + Book + | + Docs (latest release) + | + Docs (main branch) +

-[Documentation](https://docs.rs/argmin_testfunctions/). +

+ Crates.io version + Crates.io downloads + GitHub Actions workflow status + License + argmin Discord +

+A collection of two- and multidimensional test functions (and their derivatives and Hessians) for optimization algorithms. +For two-dimensional test functions, the derivate and Hessian calculation does not allocate. For multi-dimensional tes functions, +the derivative and Hessian calculation comes in two variants. One variant returns `Vec`s and hence does allocate. This is +needed for cases, where the number of parameters is only known at run time. In case the number of parameters are known at +compile-time, the `_const` variants can be used, which return fixed size arrays and hence do not allocate. + +The derivative and Hessian calculation is always named `_derivative` and +`_hessian`, respectively. The const generics variants are defined as +`_derivative_const` and `_hessian_const`. + +Some functions, such as `ackley`, `rosenbrock` and `rastrigin` come with additional optional parameters which change +the shape of the fuctions. These additional parameters are exposed in `ackley_abc`, `rosenbrock_ab` and `rastrigin_a`. + +All functions are generic over their inputs and work with `[f64]` and `[f32]`. + +For a list of all implemented functions see the documentation linked above. + +## Python wrapper + +Thanks to the python module [`argmin-testfunctions-py`](https://pypi.org/project/argmin-testfunctions-py/), it is possible to use the functions in Python as well. +Note that the derivative and Hessian calculation used in the wrapper will always allocate. + +## Running the tests and benchmarks + +The tests can be run with + +```bash +cargo test +``` + +The test functions derivatives and Hessians are tested against [finitediff](https://crates.io/crates/finitediff) using +[proptest](https://crates.io/crates/proptest) to sample the functions at various points. + +All functions are benchmarked using [criterion.rs](https://crates.io/crates/criterion). Run the benchmarks with + +```bash +cargo bench +``` + +The report is available in `target/criterion/report/index.html`. + +## Contributing + +This library is the most useful the more test functions it contains, therefore any contributions are highly +welcome. For inspiration on what to implement and how to proceed, feel free to have a look at this +[issue](https://github.com/argmin-rs/argmin/issues/450). + +While most of the implemented functions are probably already quite efficient, there are probably a few +which may profit from performance improvements. ## License @@ -16,4 +104,5 @@ at your option. ### Contribution -Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, +as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/crates/argmin-testfunctions/src/lib.rs b/crates/argmin-testfunctions/src/lib.rs index ef46974b6..268a07107 100644 --- a/crates/argmin-testfunctions/src/lib.rs +++ b/crates/argmin-testfunctions/src/lib.rs @@ -5,7 +5,74 @@ // http://opensource.org/licenses/MIT>, at your option. This file may not be // copied, modified, or distributed except according to those terms. -//! # Test functions for optimization algorithms +//! A collection of two- and multidimensional test functions (and their derivatives and Hessians) +//! for optimization algorithms. For two-dimensional test functions, the derivate and Hessian +//! calculation does not allocate. For multi-dimensional tes functions, the derivative and Hessian +//! calculation comes in two variants. One variant returns `Vec`s and hence does allocate. This is +//! needed for cases, where the number of parameters is only known at run time. In case the number +//! of parameters are known at compile-time, the `_const` variants can be used, which return fixed +//! size arrays and hence do not allocate. +//! +//! The derivative and Hessian calculation is always named `_derivative` and +//! `_hessian`, respectively. The const generics variants are defined as +//! `_derivative_const` and `_hessian_const`. +//! +//! Some functions, such as `ackley`, `rosenbrock` and `rastrigin` come with additional optional +//! parameters which change the shape of the fuctions. These additional parameters are exposed in +//! `ackley_abc`, `rosenbrock_ab` and `rastrigin_a`. +//! +//! All functions are generic over their inputs and work with `[f64]` and `[f32]`. +//! +//! ## Python wrapper +//! +//! Thanks to the python module +//! [`argmin-testfunctions-py`](https://pypi.org/project/argmin-testfunctions-py/), it is possible +//! to use the functions in Python as well. Note that the derivative and Hessian calculation used +//! in the wrapper will always allocate. +//! +//! ## Running the tests and benchmarks +//! +//! The tests can be run with +//! +//! ```bash +//! cargo test +//! ``` +//! +//! The test functions derivatives and Hessians are tested against +//! [finitediff](https://crates.io/crates/finitediff) using +//! [proptest](https://crates.io/crates/proptest) to sample the functions at various points. +//! +//! All functions are benchmarked using [criterion.rs](https://crates.io/crates/criterion). +//! Run the benchmarks with +//! +//! ```bash +//! cargo bench +//! ``` +//! +//! The report is available in `target/criterion/report/index.html`. +//! +//! ## Contributing +//! +//! This library is the most useful the more test functions it contains, therefore any contributions +//! are highly welcome. For inspiration on what to implement and how to proceed, feel free to have +//! a look at this [issue](https://github.com/argmin-rs/argmin/issues/450). +//! +//! While most of the implemented functions are probably already quite efficient, there are probably +//! a few which may profit from performance improvements. +//! +//! ## License +//! +//! Licensed under either of +//! +//! * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or ) +//! * MIT License ([LICENSE-MIT](LICENSE-MIT) or ) +//! +//! at your option. +//! +//! ### Contribution +//! +//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, +//! as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. mod ackley; mod beale; diff --git a/python/argmin-testfunctions-py/README.md b/python/argmin-testfunctions-py/README.md index 6ffb8662c..dcf414d22 100644 --- a/python/argmin-testfunctions-py/README.md +++ b/python/argmin-testfunctions-py/README.md @@ -33,17 +33,16 @@ />

-This makes the test functions of the `argmin_testfunctions` Rust crate available in Python. +This Python module makes the test functions of the `argmin_testfunctions` Rust crate available in Python. For each test function the derivative and Hessian are available as well. -Most functions are 2D only, but some allow an arbitrary number of parameters. +While most functions are two-dimensional, some allow an arbitraty number of parameters. For some functions additional optional parameters are accessible, which can be used to modify the shape of the test function. -For details on the individual test functions please consult the Rust docs, either for the +For details on the individual test functions please consult the docs of the Rust library, either for the [latest release](https://docs.rs/argmin_testfunctions) or the [current main branch](https://argmin-rs.github.io/argmin/argmin_testfunctions/index.html). ## Examples - ```python from argmin_testfunctions_py import *