zfergus / finite-diff

A simple finite-difference library using Eigen.

Finite Differences

A simple finite-difference library using Eigen.

Usage

Add it to CMake

The easiest way to add the library to an existing CMake project is to download it through CMake. CMake provides functionality for doing this called FetchContent (requires CMake ≥ 3.14). We use this same process to download all external dependencies. For example,

include(FetchContent)
FetchContent_Declare(
    finite-diff
    GIT_REPOSITORY https://github.com/zfergus/finite-diff.git
    GIT_TAG ${FINITE_DIFF_GIT_TAG}
    GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(finite-diff)

where FINITE_DIFF_GIT_TAG is set to the version you want to use. This will download and add the library to CMake. The library can then be linked against using

target_link_libraries(${TARGET_NAME} PUBLIC finitediff::finitediff)

where TARGET_NAME is the name of your library/executable.

API

All functiononality can be included with #include <finitediff.hpp>.

The library provides three main functions finite_gradient, finite_jacobian, and finite_hessian.

finite_gradient:

void finite_gradient(
    const Eigen::VectorXd& x,
    const std::function<double(const Eigen::VectorXd&)>& f,
    Eigen::VectorXd& grad,
    const AccuracyOrder accuracy = SECOND,
    const double eps = 1.0e-8);

The finite_gradient function computes the gradient (first derivative) grad of a function f: ℝⁿ ↦ ℝ at a point x. This will result in a vector of size n.

finite_jacobian:

void finite_jacobian(
    const Eigen::VectorXd& x,
    const std::function<Eigen::VectorXd(const Eigen::VectorXd&)>& f,
    Eigen::MatrixXd& jac,
    const AccuracyOrder accuracy = SECOND,
    const double eps = 1.0e-8);

The finite_jacobian function computes the Jacobian (first derivative) jac of a function f: ℝⁿ ↦ ℝᵐ at a point x. This will result in a matrix of size m × n.

finite_hessian:

void finite_hessian(
    const Eigen::VectorXd& x,
    const std::function<double(const Eigen::VectorXd&)>& f,
    Eigen::MatrixXd& hess,
    const AccuracyOrder accuracy = SECOND,
    const double eps = 1.0e-5);

The finite_hessian function computes the Hessian (second derivative) hess of a function f: ℝⁿ ↦ ℝ at a point x. This will result in a matrix of size n × n.

AccuracyOrder:

Each finite difference function takes as input the accuracy order for the method. Possible options are:

enum AccuracyOrder {
    SECOND, // Second order accuracy.
    FOURTH, // Fourth order accuracy.
    SIXTH,  // Sixth order accuracy.
    EIGHTH  // Eighth order accuracy.
};

eps:

The parameter eps is the finite difference step size. Smaller values result in a more accurate approximation, but too small of a value can result in a large numerical error because the difference will be divided by a small number.

Dependencies

All dependencies are downloaded through CMake depending on the build options. The following libraries are used in this project:

• Eigen: linear algebra
• spdlog: logging information

Optional

• Catch2: testing (see Unit Tests)

Unit Tests

We provide unit tests for ensuring the correctness of our functions. To enable the unit tests, use the flag -DFINITE_DIFF_BUILD_UNIT_TESTS=ON with CMake.

Contributing

This project is open to contributors! Contributions can come in the form of feature requests, bug fixes, documentation, tutorials and the like. We highly recommend filing an Issue first before submitting a Pull Request.

Simply fork this repository and make a Pull Request! We'd appreciate:

• Implementation of new features
• Bug Reports
• Documentation
• Testing

License

MIT License © 2019, Zachary Ferguson (See LICENSE.txt for details).

Acknowledgements

Based on the functions in CppNumericalSolvers by Patrick Wieschollek and rewritten to use Eigen.