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#[cfg(any(feature = "c", feature = "python"))]
57#[doc(hidden)]
58pub mod ffi;
59
60pub use crate::copp::constraints;
61
62/// Solver entry namespace (TOPP2/TOPP3/COPP2/COPP3).
63///
64/// Each submodule exposes a solver family with stable public paths.
65/// Read the submodule summary first, then choose by objective and runtime budget.
66pub mod solver {
67    /// TOPP2 reachable-set construction.
68    ///
69    /// Input: TOPP2 problem + reach-set options.
70    /// Output: feasible acceleration range representation along the path.
71    /// Scenario: feasibility analysis or as a precursor for TOPP2/TOPP3 pipelines.
72    ///
73    /// # Example
74    /// ```rust, no_run
75    #[doc = include_str!("../examples/reach_set2.rs")]
76    /// ```
77    pub mod reach_set2 {
78        pub use crate::copp::copp2::stable::reach_set2::*;
79        pub use crate::topp2_basic::*;
80    }
81
82    /// TOPP2 reachability-analysis solver.
83    ///
84    /// Input: TOPP2 problem + RA options.
85    /// Output: time-optimal feasible `a` profile under second-order constraints.
86    /// Scenario: fast and reliable TOPP2 baseline for production pipelines.
87    ///
88    /// # Example
89    /// ```rust, no_run
90    #[doc = include_str!("../examples/topp2_ra.rs")]
91    /// ```
92    pub mod topp2_ra {
93        pub use crate::copp::copp2::stable::topp2_ra::*;
94        pub use crate::topp2_basic::*;
95    }
96
97    /// COPP2 SOCP backend (Clarabel).
98    ///
99    /// Input: COPP2 problem + convex objective + SOCP/Clarabel options.
100    /// Output: conic-optimization based solution and conversion helpers.
101    /// Scenario: when conic formulation is preferred over DP-style solvers.
102    ///
103    /// # Example
104    /// ```rust, no_run
105    #[doc = include_str!("../examples/copp2_socp.rs")]
106    /// ```
107    pub mod copp2_socp {
108        pub use crate::copp::clarabel_backend::{
109            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp2_solution,
110        };
111        pub use crate::copp::copp2::stable::copp2_socp::*;
112        pub use crate::copp2_basic::*;
113    }
114
115    /// COPP3 SOCP backend (Clarabel).
116    ///
117    /// Input: COPP3 problem + convex objective + SOCP/Clarabel options.
118    /// Output: `Topp3Profile` and expert conic-program diagnostics.
119    /// Scenario: third-order convex optimization via conic programming.
120    ///
121    /// # Example
122    /// ```rust, no_run
123    #[doc = include_str!("../examples/copp3_socp.rs")]
124    /// ```
125    pub mod copp3_socp {
126        pub use crate::copp::clarabel_backend::{
127            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp3_solution,
128        };
129        pub use crate::copp::copp3::stable::copp3_socp::*;
130        pub use crate::copp3_basic::*;
131    }
132
133    /// TOPP3 LP backend (Clarabel).
134    ///
135    /// Input: TOPP3 problem + LP/Clarabel options.
136    /// Output: LP-based `Topp3Profile` in third-order setting.
137    /// Scenario: linear-programming formulation for TOPP3.
138    ///
139    /// # Example
140    /// ```rust, no_run
141    #[doc = include_str!("../examples/topp3_lp.rs")]
142    /// ```
143    pub mod topp3_lp {
144        pub use crate::copp::clarabel_backend::{
145            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp3_solution,
146        };
147        pub use crate::copp::copp3::stable::topp3_lp::*;
148        pub use crate::topp3_basic::*;
149    }
150
151    /// TOPP3 SOCP backend (Clarabel).
152    ///
153    /// Input: TOPP3 problem + SOCP/Clarabel options.
154    /// Output: SOCP-based `Topp3Profile`.
155    /// Scenario: conic alternative to LP for TOPP3.
156    ///
157    /// # Example
158    /// ```rust, no_run
159    #[doc = include_str!("../examples/topp3_socp.rs")]
160    /// ```
161    pub mod topp3_socp {
162        pub use crate::copp::clarabel_backend::{
163            ClarabelOptions, ClarabelOptionsBuilder, clarabel_to_copp3_solution,
164        };
165        pub use crate::copp::copp3::stable::topp3_socp::*;
166        pub use crate::topp3_basic::*;
167    }
168}
169
170/// Time-grid interpolation policy used when converting trajectory profiles to time-domain samples.
171///
172/// Import via `use copp::InterpolationMode;`; this is the single canonical path.
173/// All solver submodules (`solver::topp2_ra`, `solver::topp3_lp`, etc.) accept this type
174/// in their interpolation helpers ([`t_to_s_topp2`](crate::solver::topp2_ra::t_to_s_topp2),
175/// [`t_to_s_topp3`](crate::solver::topp3_lp::t_to_s_topp3), etc.).
176pub use crate::copp::general::InterpolationMode;
177
178mod topp2_basic {
179    pub use crate::copp::copp2::stable::basic::{
180        Topp2Problem, Topp2ProblemBuilder, a_to_b_topp2, s_to_t_topp2, t_to_s_topp2,
181    };
182}
183
184mod copp2_basic {
185    pub use crate::copp::copp2::stable::basic::{
186        Copp2Problem, Copp2ProblemBuilder, a_to_b_topp2, s_to_t_topp2, t_to_s_topp2,
187    };
188    pub use crate::copp::objectives::CoppObjective;
189}
190
191mod topp3_basic {
192    pub use crate::copp::copp3::stable::basic::{
193        Topp3Problem, Topp3ProblemBuilder, Topp3Profile, Topp3ProfileMut, Topp3ProfileRef,
194        s_to_t_topp3, t_to_s_topp3,
195    };
196}
197
198mod copp3_basic {
199    pub use crate::copp::copp3::stable::basic::{
200        Copp3Problem, Copp3ProblemBuilder, Topp3Profile, Topp3ProfileMut, Topp3ProfileRef,
201        s_to_t_topp3, t_to_s_topp3,
202    };
203    pub use crate::copp::objectives::CoppObjective;
204}
205
206/// Commonly used public imports for application code.
207///
208/// Input: none (import-only convenience module).
209/// Output: unified symbols for robot, constraints, solvers, and utility types.
210/// Scenario: rapid prototyping and application-layer code with minimal import boilerplate.
211///
212/// Typical usage: `use copp::prelude::*;`
213///
214/// # Import ordering (mirrors recommended onboarding path)
215/// 1. **Robot & constraints**: [`robot::Robot`], [`robot::RobotBasic`], [`robot::RobotTorque`], [`constraints::Constraints`].
216/// 2. **Solver builders**: Problem/options builders for each solver family.
217/// 3. **Utility types**: [`InterpolationMode`], [`CoppObjective`](crate::prelude::CoppObjective), [`diag::CoppError`], [`diag::Verbosity`].
218/// 4. **Path & AD**: [`path::Path`], [`path::Jet3`], math helpers.
219/// 5. **Solver submodules**: for calling solver entry functions directly.
220pub mod prelude {
221    // 1. Robot model traits and constraint container
222    pub use crate::constraints::Constraints;
223    pub use crate::robot::*;
224
225    // 2. Solver builders (Problem builders and options builders)
226    pub use crate::solver::copp2_socp::{
227        ClarabelOptions, ClarabelOptionsBuilder, Copp2Problem, Copp2ProblemBuilder,
228    };
229    pub use crate::solver::copp3_socp::{Copp3Problem, Copp3ProblemBuilder};
230    pub use crate::solver::topp2_ra::{ReachSet2OptionsBuilder, Topp2Problem, Topp2ProblemBuilder};
231    pub use crate::solver::topp3_lp::{Topp3Problem, Topp3ProblemBuilder};
232
233    // 3. Shared utility types
234    pub use crate::InterpolationMode;
235    pub use crate::copp::objectives::CoppObjective;
236    pub use crate::diag::{
237        CoppError, Verbosity, VerbosityOutput, set_verbosity_log_file, set_verbosity_output,
238        verbosity_output,
239    };
240
241    // 4. Path building and automatic differentiation
242    pub use crate::path::{
243        Jet3, Parametrization, Path, PathDerivatives, PathEvaluator, PathEvaluator2nd,
244        PathEvaluator3rd, SplineConfig, cos, exp, ln, powi, sin, sqrt,
245    };
246
247    // 5. Solver submodule namespaces (for calling solver entry functions)
248    pub use crate::solver::{copp2_socp, copp3_socp, reach_set2, topp2_ra, topp3_lp, topp3_socp};
249}
copp/lib.rs

copp/
lib.rs
