Skip to content

Commit

Permalink
Documentation for argmin_testfunctions and python module
Browse files Browse the repository at this point in the history
  • Loading branch information
@stefan-k
stefan-k committed Feb 16, 2024
1 parent ca2e860 commit c5ab487
Show file tree
Hide file tree
Showing 3 changed files with 164 additions and 9 deletions.
97 changes: 93 additions & 4 deletions crates/argmin-testfunctions/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,97 @@
# argmin-testfunctions
<p align="center">
<img
width="400"
src="https://raw.githubusercontent.com/argmin-rs/argmin/main/media/logo.png"
/>
</p>
<h1 align="center">argmin_testfunctions</h1>

Test functions for optimization algorithms in Rust.
<p align="center">
<a href="https://argmin-rs.org">Website</a>
|
<a href="https://argmin-rs.org/book/">Book</a>
|
<a href="https://docs.rs/argmin_testfunctions">Docs (latest release)</a>
|
<a href="https://argmin-rs.github.io/argmin/argmin_testfunctions/index.html">Docs (main branch)</a>
</p>

[Documentation](https://docs.rs/argmin_testfunctions/).
<p align="center">
<a href="https://crates.io/crates/argmin"
><img
src="https://img.shields.io/crates/v/argmin_testfunctions?style=flat-square"
alt="Crates.io version"
/></a>
<a href="https://crates.io/crates/argmin"
><img
src="https://img.shields.io/crates/d/argmin_testfunctions?style=flat-square"
alt="Crates.io downloads"
/></a>
<a href="https://github.com/argmin-rs/argmin/actions"
><img
src="https://img.shields.io/github/actions/workflow/status/argmin-rs/argmin/python.yml?branch=main&label=argmin CI&style=flat-square"
alt="GitHub Actions workflow status"
/></a>
<img
src="https://img.shields.io/crates/l/argmin?style=flat-square"
alt="License"
/>
<a href="https://discord.gg/fYB8AwxxMW"
><img
src="https://img.shields.io/discord/1189119565335109683?style=flat-square&label=argmin%20Discord"
alt="argmin Discord"
/></a>
</p>

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 `<test function name>_derivative` and
`<test function name>_hessian`, respectively. The const generics variants are defined as
`<test function name>_derivative_const` and `<test function name>_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`.

Check warning on line 57 in crates/argmin-testfunctions/README.md

View workflow job for this annotation

GitHub Actions / Spell Check with Typos 

"fuctions" should be "functions".

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

Expand All @@ -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.
69 changes: 68 additions & 1 deletion crates/argmin-testfunctions/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<test function name>_derivative` and
//! `<test function name>_hessian`, respectively. The const generics variants are defined as
//! `<test function name>_derivative_const` and `<test function name>_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

Check warning on line 21 in crates/argmin-testfunctions/src/lib.rs

View workflow job for this annotation

GitHub Actions / Spell Check with Typos 

"fuctions" should be "functions".
//! `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 <http://www.apache.org/licenses/LICENSE-2.0>)
//! * MIT License ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
//!
//! 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;
Expand Down
7 changes: 3 additions & 4 deletions python/argmin-testfunctions-py/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,17 +33,16 @@
/></a>
</p>

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.

Check warning on line 38 in python/argmin-testfunctions-py/README.md

View workflow job for this annotation

GitHub Actions / Spell Check with Typos 

"arbitraty" should be "arbitrary".
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 *

Expand Down

0 comments on commit c5ab487

Please sign in to comment.