Expand description
f64ad_
| Documentation | API |
Introduction
This crate brings easy to use, efficient, and highly flexible automatic differentiation to the Rust programming language. Utilizing Rust’s extensive operator overloading and expressive Enum features, f64ad_ can be thought of as a drop-in replacement for f64 that affords forward mode or backwards mode automatic differentiation on any downstream computation in Rust.
Key features
- f64ad_ supports reverse mode or forward mode automatic differentiation
- f64ad_ supports not just first derivatives, but also any higher order derivatives on any functions.
- f64ad_ uses polymorphism such that any
f64ad_object can either be considered a derivative tracking variable or a standard f64 with very little overhead depending on your current use case. Thus, it is reasonable to replace almost all uses of f64 with f64ad_, and in return, you’ll be able to “turn on” derivatives with respect to these values whenever you need them. - The f64ad_ Enum type implements several useful traits that allow it to operate almost exactly as a
standard f64. For example, it even implements the
RealFieldandComplexFieldtraits, meaning it can be used in anynalgebraorndarraycomputations. - Certain functions can be pre-computed and locked to boost performance at run-time.
Crate structure
This crate is a cargo workspace with two member crates: (1) f64ad_core; and (2) f64ad_core_derive.
All core implementations for f64ad_ can be found in f64ad_core. The f64ad_core_derive is
currently a placeholder and will be used for procedural macro implementations.
Citing f64ad_
If you use any part of the f64ad_ library in your research, please cite the software as follows:
@misc{rakita_2022, url={https://djrakita.github.io/f64ad/},
author={Rakita, Daniel},
title={f64ad_: Efficient and Flexible Automatic Differentiation in Rust}
year={2022}}
Modules
Macros
Approximate equality of using the absolute difference.
Approximate inequality of using the absolute difference.
An assertion that delegates to [
abs_diff_eq!], and panics with a helpful error on failure.An assertion that delegates to [
abs_diff_ne!], and panics with a helpful error on failure.An assertion that delegates to [
relative_eq!], and panics with a helpful error on failure.An assertion that delegates to [
relative_ne!], and panics with a helpful error on failure.An assertion that delegates to [
ulps_eq!], and panics with a helpful error on failure.An assertion that delegates to [
ulps_ne!], and panics with a helpful error on failure.Approximate equality using both the absolute difference and relative based comparisons.
Approximate inequality using both the absolute difference and relative based comparisons.
Approximate equality using both the absolute difference and ULPs (Units in Last Place).
Approximate inequality using both the absolute difference and ULPs (Units in Last Place).
Structs
The requisite parameters for testing for approximate equality using a
absolute difference based comparison.
The requisite parameters for testing for approximate equality using a
relative based comparison.
The requisite parameters for testing for approximate equality using an ULPs
based comparison.
Enums
Traits
Equality that is defined using the absolute difference of two numbers.
A generic interface for casting between machine scalars with the
as operator, which admits narrowing and precision loss.
Implementers of this trait AsPrimitive should behave like a primitive
numeric type (e.g. a newtype around another primitive), and the
intended conversion must never fail.Numbers which have upper and lower bounds
Performs addition that returns
None instead of wrapping around on
overflow.Performs division that returns
None instead of panicking on division by zero and instead of
wrapping around on underflow and overflow.Performs multiplication that returns
None instead of wrapping around on underflow or
overflow.Performs negation that returns
None if the result can’t be represented.Performs an integral remainder that returns
None instead of panicking on division by zero and
instead of wrapping around on underflow and overflow.Performs a left shift that returns
None on shifts larger than
the type width.Performs a right shift that returns
None on shifts larger than
the type width.Performs subtraction that returns
None instead of wrapping around on underflow.Trait alias for
Add and AddAssign with result of type Self.Trait alias for
Div and DivAssign with result of type Self.Trait alias for
Mul and MulAssign with result of type Self.Trait alias for
Neg with result of type Self.Trait alias for
Sub and SubAssign with result of type Self.Trait shared by all complex fields and its subfields (like real numbers).
Trait implemented by fields, i.e., complex numbers and floats.
Generic trait for floating point numbers
A generic trait for converting a number to a value.
Unary operator for retrieving the multiplicative inverse, or reciprocal, of a value.
Fused multiply-add. Computes
(self * a) + b with only one rounding
error, yielding a more accurate result than an unfused multiply-add.The fused multiply-add assignment operation.
The base trait for numeric types, covering
0 and 1 values,
comparisons, basic numeric operations, and string conversion.The trait for
Num types which also implement assignment operators.Generic trait for types implementing numeric assignment operators (like
+=).The trait for
NumAssign types which also implement assignment operations
taking the second operand by reference.An interface for casting between machine scalars.
Generic trait for types implementing basic numeric operations
The trait for
Num types which also implement numeric operations taking
the second operand by reference.Defines a multiplicative identity element for
Self.Binary operator for raising a value to a power.
Generic trait for primitive integers.
Trait shared by all reals.
The trait for
Num references which implement numeric operations, taking the
second operand either by value or by reference.Equality comparisons between two numbers using both the absolute difference and
relative based comparisons.
Saturating math operations. Deprecated, use
SaturatingAdd, SaturatingSub and
SaturatingMul instead.Performs addition that saturates at the numeric bounds instead of overflowing.
Performs multiplication that saturates at the numeric bounds instead of overflowing.
Performs subtraction that saturates at the numeric bounds instead of overflowing.
Useful functions for signed numbers (i.e. numbers that can be negative).
Nested sets and conversions between them (using an injective mapping). Useful to work with
substructures. In generic code, it is preferable to use
SupersetOf as trait bound whenever
possible instead of SubsetOf (because SupersetOf is automatically implemented whenever
SubsetOf is).Nested sets and conversions between them. Useful to work with substructures. It is preferable
to implement the
SubsetOf trait instead of SupersetOf whenever possible (because
SupersetOf is automatically implemented whenever SubsetOf is).A generic trait for converting a value to a number.
Equality comparisons between two numbers using both the absolute difference and ULPs
(Units in Last Place) based comparisons.
A trait for values which cannot be negative
Performs addition that wraps around on overflow.
Performs multiplication that wraps around on overflow.
Performs a negation that does not panic.
Performs a left shift that does not panic.
Performs a right shift that does not panic.
Performs subtraction that wraps around on overflow.
Defines an additive identity element for
Self.Functions
Computes the absolute value.
The positive difference of two numbers.
Cast from one machine scalar to another.
Raises a value to the power of exp, returning
None if an overflow occurred.A value bounded by a minimum and a maximum
A value bounded by a maximum value
A value bounded by a minimum value
Returns the multiplicative identity,
1.Raises a value to the power of exp, using exponentiation by squaring.
Returns the sign of the number.
Returns the additive identity,
0.