optimization_engine 0.12.0

A pure Rust framework for embedded nonconvex optimization. Ideal for robotics!
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

#![deny(missing_docs)]
//! Augmented Lagrangian and Penalty Methods
//!
//! A module that contains structures and implementations that allow
//! to formulate parametric constrained nonconvex optimization problems
//! in the form specified in [`AlmProblem`]
//!
//! Such problems can then be solved using [`AlmOptimizer`], which combines the
//! augmented Lagrangian and the penalty method.
//!
//! The user needs to create an [`AlmCache`] object, which can then be passed to
//! different instances of `AlmOptimizer`. An `AlmCache` allocates the necessary
//! memory that the optimizer needs.
//!
//! Upon completion of its execution, `AlmOptimizer` returns information about
//! the iterative procedure, such as the solution time, number of iterations,
//! measures of accuracy and more, in the form of an [`AlmOptimizerStatus`]
//!
//! All public ALM types are generic over a scalar type `T`, which is typically
//! `f64` or `f32`. The default is `f64`, so existing code can often omit `T`.
//! The examples in this module use `f64` for brevity.
//!
//! When using `AlmOptimizer`,  the user is expected to provide a modified cost
//! function, `psi` (see [`AlmOptimizer`] for details). This should not be a problem
//! for users that use Optimization Engine via its Python or MATLAB interfaces.
//! Should the user need to use Optimization Engine in Rust, she can construct
//! function `psi` using [`AlmFactory`]
//!
//! [`AlmProblem`]: struct.AlmProblem.html
//! [`AlmOptimizer`]: struct.AlmOptimizer.html
//! [`AlmCache`]: struct.AlmCache.html
//! [`AlmOptimizerStatus`]: struct.AlmOptimizerStatus.html
//! [`AlmFactory`]: struct.AlmFactory.html
//!
mod alm_cache;
mod alm_factory;
mod alm_optimizer;
mod alm_optimizer_status;
mod alm_problem;

pub use alm_cache::AlmCache;
pub use alm_factory::AlmFactory;
pub use alm_optimizer::AlmOptimizer;
pub use alm_optimizer_status::AlmOptimizerStatus;
pub use alm_problem::AlmProblem;

/// Type of mappings $F_1(u)$ and $F_2(u)$
///
/// The scalar type `T` is a floating-point type, typically `f64` or `f32`.
///
/// Mappings $F_1$ and $F_2$ are computed by functions with signature
///
/// ```ignore
/// fn mapping_f(&[T], &mut [T]) -> Result<(), crate::SolverError>
/// ```
pub type MappingType<T = f64> = fn(&[T], &mut [T]) -> Result<(), crate::SolverError>;

/// Type of the Jacobian of mappings $F_1$ and $F_2$
///
/// The scalar type `T` is a floating-point type, typically `f64` or `f32`.
///
/// These are mappings $(u, d) \mapsto JF_1(u)^\top d$, for given vectors $u\in\mathbb{R}$
/// and $d\in\mathbb{R}^{n_1}$ (similarly for $F_2$)
pub type JacobianMappingType<T = f64> = fn(&[T], &[T], &mut [T]) -> Result<(), crate::SolverError>;

/// No mapping $F_1(u)$ or $F_2(u)$ is specified
pub const NO_MAPPING: Option<MappingType> = None::<MappingType>;

/// No Jacobian mapping is specified for $F_1$ and $F_2$
pub const NO_JACOBIAN_MAPPING: Option<JacobianMappingType> = None::<JacobianMappingType>;

/// No set is specified (when specifying a set is optional)
pub const NO_SET: Option<crate::constraints::NoConstraints> =
    None::<crate::constraints::NoConstraints>;

/// Helper for the generic case where no mapping is provided.
///
/// This is useful when the scalar type is not the default `f64`, for example
/// when using `f32`.
pub fn no_mapping<T>() -> Option<MappingType<T>> {
    None::<MappingType<T>>
}

/// Helper for the generic case where no Jacobian mapping is provided.
///
/// This is useful when the scalar type is not the default `f64`, for example
/// when using `f32`.
pub fn no_jacobian_mapping<T>() -> Option<JacobianMappingType<T>> {
    None::<JacobianMappingType<T>>
}

/// Helper for the generic case where no set is provided.
///
/// This is useful when the scalar type is not the default `f64`, for example
/// when using `f32`.
pub fn no_set<T>() -> Option<crate::constraints::NoConstraints> {
    let _ = std::marker::PhantomData::<T>;
    None::<crate::constraints::NoConstraints>
}

/* ---------------------------------------------------------------------------- */
/*          TESTS                                                               */
/* ---------------------------------------------------------------------------- */
#[cfg(test)]
mod tests;