copp/
lib.rs

1//! `copp` crate public API.
2//!
3//! # What problem does this library solve?
4//! This library targets **OPP** (Optimal Path Parameterization) problems.
5//! Given a geometric path parameterization
6//! $q = q(s)$, the solver finds a time law $s = s(t)$ such that constraints are
7//! satisfied while an objective is optimized.
8//!
9//! In short, we convert geometry-space motion into time-space scheduling:
10//! $$
11//! q = q(s) \quad \Longrightarrow \quad s = s(t),
12//! $$
13//! and solve for globally optimal / KKT-satisfying / heuristic near-optimal
14//! trajectories under the selected backend and objective model.
15//!
16//! # Objective families: TOPP vs COPP
17//! - **TOPP**: Time-Optimal Path Parameterization (typical objective is minimum
18//!   traversal time).
19//! - **COPP**: Convex-Objective Path Parameterization (supports richer convex
20//!   objectives beyond pure time-optimality).
21//!
22//! For non-convex objectives, a practical approach is **SCP**:
23//! perform DC decomposition and iterative objective linearization. Constraint
24//! linearization (notably for third-order models) is already implemented in this
25//! crate. For objective modeling details, see COPP solver families and
26//! [`CoppObjective`](crate::prelude::CoppObjective)-related APIs.
27//!
28//! # Constraint-order families: 2nd vs 3rd order
29//! - **2nd-order** (TOPP2/COPP2): commonly covers velocity, acceleration,
30//!   and torque-related constraints.
31//! - **3rd-order** (TOPP3/COPP3): additionally models jerk-level effects.
32//!
33//! User-defined constraints are supported at different abstraction levels:
34//! - prefer [`robot::Robot`] for physically meaningful high-level ingestion;
35//! - use [`constraints::Constraints`] directly for maximum low-level flexibility.
36//!
37//! # Supported problem classes
38//! This crate provides solvers for four major classes:
39//! - `TOPP2`
40//! - `COPP2`
41//! - `TOPP3`
42//! - `COPP3`
43//!
44//! # Recommended onboarding path
45//! 1. Build constraints with [`robot::Robot`] (or directly with
46//!    [`constraints::Constraints`] for advanced customization).
47//! 2. Choose a solver family from [`solver`] based on objective/accuracy/runtime.
48//! 3. Start quickly with [`prelude`] for common imports.
49
50pub(crate) mod copp;
51pub mod diag;
52pub(crate) mod math;
53pub mod path;
54pub mod robot;
55
56#[doc(hidden)]
57pub mod ffi;
58
59pub use crate::copp::constraints;
60
61/// Solver entry namespace (TOPP2/TOPP3/COPP2/COPP3).
62///
63/// Each submodule exposes a solver family with stable public paths.
64/// Read the submodule summary first, then choose by objective and runtime budget.
65pub mod solver {
66    /// TOPP2 reachable-set construction.
67    ///
68    /// Input: TOPP2 problem + reach-set options.
69    /// Output: feasible acceleration range representation along the path.
70    /// Scenario: feasibility analysis or as a precursor for TOPP2/TOPP3 pipelines.
71    ///
72    /// # Example
73    /// ```rust, no_run
74    #[doc = include_str!("../examples/reach_set2.rs")]
75    /// ```
76    pub mod reach_set2 {
77        pub use crate::copp::copp2::stable::reach_set2::*;
78        pub use crate::topp2_basic::*;
79    }
80
81    /// TOPP2 reachability-analysis solver.
82    ///
83    /// Input: TOPP2 problem + RA options.
84    /// Output: time-optimal feasible `a` profile under second-order constraints.
85    /// Scenario: fast and reliable TOPP2 baseline for production pipelines.
86    ///
87    /// # Example
88    /// ```rust, no_run
89    #[doc = include_str!("../examples/topp2_ra.rs")]
90    /// ```
91    pub mod topp2_ra {
92        pub use crate::copp::copp2::stable::topp2_ra::*;
93        pub use crate::topp2_basic::*;
94    }
95
96    /// COPP2 SOCP backend (Clarabel).
97    ///
98    /// Input: COPP2 problem + convex objective + SOCP/Clarabel options.
99    /// Output: conic-optimization based solution and conversion helpers.
100    /// Scenario: when conic formulation is preferred over DP-style solvers.
101    ///
102    /// # Example
103    /// ```rust, no_run
104    #[doc = include_str!("../examples/copp2_socp.rs")]
105    /// ```
106    pub mod copp2_socp {
107        pub use crate::copp::clarabel_backend::{
108            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp2_solution,
109        };
110        pub use crate::copp::copp2::stable::copp2_socp::*;
111        pub use crate::copp2_basic::*;
112    }
113
114    /// COPP3 SOCP backend (Clarabel).
115    ///
116    /// Input: COPP3 problem + convex objective + SOCP/Clarabel options.
117    /// Output: `Topp3Profile` and expert conic-program diagnostics.
118    /// Scenario: third-order convex optimization via conic programming.
119    ///
120    /// # Example
121    /// ```rust, no_run
122    #[doc = include_str!("../examples/copp3_socp.rs")]
123    /// ```
124    pub mod copp3_socp {
125        pub use crate::copp::clarabel_backend::{
126            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp3_solution,
127        };
128        pub use crate::copp::copp3::stable::copp3_socp::*;
129        pub use crate::copp3_basic::*;
130    }
131
132    /// TOPP3 LP backend (Clarabel).
133    ///
134    /// Input: TOPP3 problem + LP/Clarabel options.
135    /// Output: LP-based `Topp3Profile` in third-order setting.
136    /// Scenario: linear-programming formulation for TOPP3.
137    ///
138    /// # Example
139    /// ```rust, no_run
140    #[doc = include_str!("../examples/topp3_lp.rs")]
141    /// ```
142    pub mod topp3_lp {
143        pub use crate::copp::clarabel_backend::{
144            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp3_solution,
145        };
146        pub use crate::copp::copp3::stable::topp3_lp::*;
147        pub use crate::topp3_basic::*;
148    }
149
150    /// TOPP3 SOCP backend (Clarabel).
151    ///
152    /// Input: TOPP3 problem + SOCP/Clarabel options.
153    /// Output: SOCP-based `Topp3Profile`.
154    /// Scenario: conic alternative to LP for TOPP3.
155    ///
156    /// # Example
157    /// ```rust, no_run
158    #[doc = include_str!("../examples/topp3_socp.rs")]
159    /// ```
160    pub mod topp3_socp {
161        pub use crate::copp::clarabel_backend::{
162            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp3_solution,
163        };
164        pub use crate::copp::copp3::stable::topp3_socp::*;
165        pub use crate::topp3_basic::*;
166    }
167}
168
169/// Time-grid interpolation policy used when converting trajectory profiles to time-domain samples.
170///
171/// Import via `use copp::InterpolationMode;`; this is the single canonical path.
172/// All solver submodules (`solver::topp2_ra`, `solver::topp3_lp`, etc.) accept this type
173/// in their interpolation helpers ([`t_to_s_topp2`](crate::solver::topp2_ra::t_to_s_topp2),
174/// [`t_to_s_topp3`](crate::solver::topp3_lp::t_to_s_topp3), etc.).
175pub use crate::copp::general::InterpolationMode;
176
177mod topp2_basic {
178    pub use crate::copp::copp2::stable::basic::{
179        Topp2Problem, Topp2ProblemBuilder, a_to_b_topp2, s_to_t_topp2, t_to_s_topp2,
180    };
181}
182
183mod copp2_basic {
184    pub use crate::copp::copp2::stable::basic::{
185        Copp2Problem, Copp2ProblemBuilder, a_to_b_topp2, s_to_t_topp2, t_to_s_topp2,
186    };
187    pub use crate::copp::objectives::CoppObjective;
188}
189
190mod topp3_basic {
191    pub use crate::copp::copp3::stable::basic::{
192        Topp3Problem, Topp3ProblemBuilder, Topp3Profile, Topp3ProfileMut, Topp3ProfileRef,
193        s_to_t_topp3, t_to_s_topp3,
194    };
195}
196
197mod copp3_basic {
198    pub use crate::copp::copp3::stable::basic::{
199        Copp3Problem, Copp3ProblemBuilder, Topp3Profile, Topp3ProfileMut, Topp3ProfileRef,
200        s_to_t_topp3, t_to_s_topp3,
201    };
202    pub use crate::copp::objectives::CoppObjective;
203}
204
205/// Commonly used public imports for application code.
206///
207/// Input: none (import-only convenience module).
208/// Output: unified symbols for robot, constraints, solvers, and utility types.
209/// Scenario: rapid prototyping and application-layer code with minimal import boilerplate.
210///
211/// Typical usage: `use copp::prelude::*;`
212///
213/// # Import ordering (mirrors recommended onboarding path)
214/// 1. **Robot & constraints**: [`robot::Robot`], [`robot::RobotBasic`], [`robot::RobotTorque`], [`constraints::Constraints`].
215/// 2. **Solver builders**: Problem/options builders for each solver family.
216/// 3. **Utility types**: [`InterpolationMode`], [`CoppObjective`](crate::prelude::CoppObjective), [`diag::CoppError`], [`diag::Verbosity`].
217/// 4. **Path & AD**: [`path::Path`], [`path::Jet3`], math helpers.
218/// 5. **Solver submodules**: for calling solver entry functions directly.
219pub mod prelude {
220    // 1. Robot model traits and constraint container
221    pub use crate::constraints::Constraints;
222    pub use crate::robot::*;
223
224    // 2. Solver builders (Problem builders and options builders)
225    pub use crate::solver::copp2_socp::{
226        ClarabelOptions, ClarabelOptionsBuilder, Copp2Problem, Copp2ProblemBuilder,
227    };
228    pub use crate::solver::copp3_socp::{Copp3Problem, Copp3ProblemBuilder};
229    pub use crate::solver::topp2_ra::{ReachSet2OptionsBuilder, Topp2Problem, Topp2ProblemBuilder};
230    pub use crate::solver::topp3_lp::{Topp3Problem, Topp3ProblemBuilder};
231
232    // 3. Shared utility types
233    pub use crate::InterpolationMode;
234    pub use crate::copp::objectives::CoppObjective;
235    pub use crate::diag::{
236        CoppError, Verbosity, VerbosityOutput, set_verbosity_log_file, set_verbosity_output,
237        verbosity_output,
238    };
239
240    // 4. Path building and automatic differentiation
241    pub use crate::path::{
242        Jet3, Parametrization, Path, PathDerivatives, PathEvaluator, PathEvaluator2nd,
243        PathEvaluator3rd, SplineConfig, cos, exp, ln, powi, sin, sqrt,
244    };
245
246    // 5. Solver submodule namespaces (for calling solver entry functions)
247    pub use crate::solver::{copp2_socp, copp3_socp, reach_set2, topp2_ra, topp3_lp, topp3_socp};
248}
copp/lib.rs

copp/
lib.rs
