COPP

Convex-Objective Path Parameterization (Rust)

This library targets Optimal Path Parameterization (OPP) for robotic trajectory generation. Typical application domains include robotic motion planning and CNC machining.

Given an $n$-dimensional geometric path parameterization

$$ \boldsymbol{q} = \boldsymbol{q}(s),\text{ }s\in[0,s_\text{f}],\text{ (}s_\text{f}\text{ is known)} $$

the objective is to schedule a dynamically feasible time parameterization

$$ s = s(t),\text{ }t\in[0,t_\text{f}],\text{ (}t_\text{f}\text{ is unknown)} $$

so that the specified system constraints are satisfied while an objective $J$ is optimized. In this way, the problem is transformed from geometry-space description to time-space scheduling along a fixed path.

At a high level, this project unifies two system orders and two objective families:

• 2nd-order models: constraints on velocity, acceleration, torque, etc. The constraint can be written as $\boldsymbol{f}(\boldsymbol{q}(s),\dot{\boldsymbol{q}}(s),\ddot{\boldsymbol{q}}(s);s)\leq\boldsymbol{0}$, and the objective is $\min J=\int_0^{t_\text{f}}L(\boldsymbol{q}(s),\dot{\boldsymbol{q}}(s),\ddot{\boldsymbol{q}}(s);s)\mathrm{d}t$.
• 3rd-order models: additionally include jerk-related effects. The constraint can be written as $\boldsymbol{f}(\boldsymbol{q}(s),\dot{\boldsymbol{q}}(s),\ddot{\boldsymbol{q}}(s),\dddot{\boldsymbol{q}}(s);s)\leq\boldsymbol{0}$, and the objective is $\min J=\int_0^{t_\text{f}}L(\boldsymbol{q}(s),\dot{\boldsymbol{q}}(s),\ddot{\boldsymbol{q}}(s),\dddot{\boldsymbol{q}}(s);s)\mathrm{d}t$.
• TOPP (Time-Optimal Path Parameterization): minimizes traversal time, i.e., $L\equiv1$ and the objective is $J=t_\text{f}$.
• COPP (Convex-Objective Path Parameterization): supports broader convex objectives. The objective $L$ should be convex with respect to the state and control: $(\dot{s}^2,\ddot{s})$ in 2nd-order models and $(\dot{s}^2,\ddot{s},\frac{\dddot{s}}{\dot{s}})$ in 3rd-order models.

The resulting taxonomy is summarized below.

Algorithm availability

This section focuses on open-source algorithms. If you need the best possible performance for difficult large-scale problems, please see Pro.

Algorithm Selection Guide

Benchmark

The tests are provided in test_random_spline.rs. Condition:

• release, --include-ignored
• CPU: Intel(R) Core(TM) Ultra 9 285K.
• Dataset: 100 random 7-DOF spline paths, each discretized into 1000 intervals.

All metrics are listed in the form of "mean ± std".

Time-Optimal

Convex-Objective

In this test, TOPP methods still use traversal time as the optimization objective.

Why use COPP instead of re-implementing from scratch?

Unless you are a specialist researcher in TOPP/COPP, we strongly recommend using this library directly. In practical deployment, many critical implementation details are easy to overlook, for example:

• strict constraint satisfaction rather than soft-constraint relaxation;
• guaranteed geometric consistency: the executed trajectory $\boldsymbol{q}=\boldsymbol{q}(s(t))$ remains exactly on the original geometric path $\boldsymbol{q}=\boldsymbol{q}(s)$, avoiding additional contour error introduced by the COPP stage;
• prevention of reverse motion and zero-velocity singularities (i.e., enforcing $\dot{s}>0$ strictly almost everywhere);
• certifiable feasibility guarantees, especially for long-path online planning, a challenge only recently addressed in the literature;
• boundary acceleration continuity handling, which is frequently problematic in existing methods. Some algorithms bypass this issue by ignoring boundary-acceleration constraints or by disallowing stationary boundary conditions $\dot{s}=0,\ddot{s}=0$, instead requiring $\dot{s}>\delta$.

Citing

If your work uses the open-source TOPP3/COPP3 functionalities, please cite:

@article{wang2026online,
  title={Online time-optimal trajectory planning along parametric toolpaths with strict constraint satisfaction and certifiable feasibility guarantee},
  author={Wang, Yunan and Hu, Chuxiong and Li, Yuanshenglong and Yu, Jichuan and Yan, Jizhou and Liang, Yixuan and Jin, Zhao},
  journal={International Journal of Machine Tools and Manufacture},
  volume={215},
  pages={104355},
  year={2026}
}

For other use cases, please cite:

@misc{thu2026copp,
  title = {COPP: Convex-Objective Path Parameterization},
  author = {Wang, Yunan and He, Suqin and Lin, Shize and Hu, Chuxiong},
  year = {2026},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/TOPP-THU/copp}}
}

Quick Start

General workflow

• Inputs
  • path grid $0=s_0<s_1<\dots<s_N=s_\text{f}$;
  • path information on the grid (via analytical expressions or sampled values of $\boldsymbol{q}$, $\frac{\mathrm{d}\boldsymbol{q}}{\mathrm{d}s}$, $\frac{\mathrm{d}^{2\boldsymbol{q}}{\mathrm{d}s}2}$, and for 3rd-order problems additionally $\frac{\mathrm{d}^{3\boldsymbol{q}}{\mathrm{d}s}3}$);
  • constraint forms and bounds, e.g., standard APIs such as with_axial_velocity, with_axial_acceleration, with_axial_torque (plus with_axial_jerk for 3rd-order), or more general custom forms. Asymmetric and non-constant limits are supported;
  • for COPP, an objective specification (standard terms or linear combinations, e.g., Time, ThermalEnergy, TotalVariationTorque, Linear). In COPP-Pro, user-defined objectives are also supported through trait-based interfaces (algorithm-dependent information such as values and derivatives).
• Outputs
  • the optimal timing map $t=t(s)$, including total traversal time $t_\text{f}$ and grid arrival times $t_k=t(s_k)$;
  • the inverse time parameterization $s=s(t)$, together with interpolation results for user-defined sampling times $\lbrace t_i\rbrace_{i=0}^{I}$, producing $s_i=s(t_i)$ and positions $\boldsymbol{q}(s(t_i))$. These interpolated position/velocity/acceleration references can be streamed to low-level servo controllers in practical deployment.

Rust

To use the Rust API, add the crate dependency in your Cargo manifest:

[dependencies]

copp = "*"

Complete runnable examples are available in the examples directory. A quick example is as follows:

use std::f64::consts::PI;
use copp::InterpolationMode;
use copp::diag::CoppError;
use copp::path::{Jet3, Path, sin};
use copp::robot::Robot;
use copp::solver::topp2_ra::{
    ReachSet2OptionsBuilder, Topp2ProblemBuilder, s_to_t_topp2, t_to_s_topp2, topp2_ra,
};

fn main() -> Result<(), CoppError> {
    // 1) Deterministic 3-axis Lissajous path q(s), s in [0, 1]
    let path = Path::from_parametric(
        |s: Jet3| {
            vec![
                sin(2.0 * PI * s + 0.0),
                sin(3.0 * PI * s + 0.3),
                sin(5.0 * PI * s + 0.7),
            ]
        },
        0.0,
        1.0,
    )?;

    // `n` is the number of path samples (s_i) to build robot constraints on.
    let n = 1001;
    let s: Vec<f64> = (0..n).map(|j| j as f64 / (n - 1) as f64).collect();
    let derivs = path.evaluate_up_to_2nd(&s)?;

    // 2) Build robot constraints (3-axis), then apply symmetric limits v/a = 1
    const DIM: usize = 3;
    let mut robot = Robot::with_capacity(DIM, n);
    robot.with_s(s.as_slice())?;
    robot.with_q(
        &derivs.q.as_view(),
        &derivs.dq.as_ref().unwrap().as_view(),
        &derivs.ddq.as_ref().unwrap().as_view(),
        None,
        0,
    )?;
    // The axial velocity is -1 <= v <= 1 for each axis in this example
    let vel_max = vec![1.0; DIM];
    let vel_min = vec![-1.0; DIM];
    robot.with_axial_velocity((vel_max.as_slice(), n), (vel_min.as_slice(), n), 0)?;
    // The axial acceleration is -1 <= a <= 1 for each axis in this example.
    let acc_max = vec![1.0; DIM];
    let acc_min = vec![-1.0; DIM];
    robot.with_axial_acceleration((acc_max.as_slice(), n), (acc_min.as_slice(), n), 0)?;

    // 3) Solve TOPP2-RA
    let idx_s_interval = (0, n - 1); // 0 <= k <= n-1
    let a_boundary = (0.0, 0.0); // a(0) = 0, a(1) = 0
    let problem = Topp2ProblemBuilder::new(&robot, idx_s_interval, a_boundary).build()?;
    let options = ReachSet2OptionsBuilder::new().build()?;

    let a_ra = topp2_ra(&problem, &options)?;

    // 4) Post-process TOPP2-RA results: a(s) -> -> t(s) -> s(t)
    // t_final is the traversal time of the path.
    // t_s[i] is the time at which the path parameter s_i is reached.
    let (t_final, t_s) = s_to_t_topp2(&s, &a_ra, 0.0);
    // s_t is a uniform time grid of s(t) with dt = 1e-3s. This is useful for plotting and downstream control.
    let dt = 1e-3;
    let s_t = t_to_s_topp2(
        &s,
        &a_ra,
        &t_s,
        InterpolationMode::UniformTimeGrid(0.0, dt, true),
    );

    // 5) Print some results. More detailed results and plots can be achieved by the user.
    println!("TOPP2-RA done.");
    println!("dim = {DIM}, N = {n}");
    println!("t_final = {t_final:.6} s");
    println!("a_profile.len() = {}", a_ra.len());
    println!("s(t) samples = {}", s_t.len());

    Ok(())
}

Comprehensive API documentation is also available. The generated docs include mathematical foundations, path/constraint construction methods, logging and output conventions, error definitions, and solver interfaces. You can generate and view the documentation locally with:

git clone https://github.com/TOPP-THU/copp.git
cd ./copp
cargo doc --no-deps

Other languages

Bindings for other languages are under active development. Planned targets include C, C++, Python, and MATLAB. If you have suggestions for these language interfaces, please feel free to contact us.

Pro

Open-source vs Pro

The open-source release and Pro release provide complementary solvers for the above problem classes. Performance evaluations for each method are documented in the corresponding Rust test/example source files and summarized below. For challenging third-order trajectory-planning tasks that require both high solution quality and robust numerical behavior, we recommend the Pro solvers. If you are interested in COPP-Pro licensing or collaboration, please see Contact Us.

Algorithm Selection Guide

Benchmark-Pro

All settings are the same as those in benchmark.

All metrics are listed in the form of "mean ± std".

Time-Optimal

Convex-Objective, 7-DOF, 100 Random Splines

In this test, TOPP methods still use traversal time as the optimization objective.

Contact Us

For COPP-Pro licensing, commercial collaboration, or technical consulting, please contact:

• Mr. Yunan Wang: wang-yn22@mails.tsinghua.edu.cn
• Dr. Suqin He: hsq_thu2012@163.com
• Dr. Shize Lin: linszthume@gmail.com
• Prof. Chuxiong Hu: cxhu@tsinghua.edu.cn