COPP

Convex-Objective Path Parameterization (Rust/C)

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}
}

If your work uses RDDP methods from the PRO release, please cite:

@article{wang2026reachability,
  title={Reachability-augmented dual dynamic programming for optimal path parameterization},
  author={Wang, Yunan and Yan, Jizhou and Hu, Chuxiong and Li, Zeyang},
  journal={arXiv preprint arXiv:2605.19089},
  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: prepare a strictly increasing station grid $0=s_0<s_1<\dots<s_{n-1}=s_\text{f}$;
  • path data: provide path derivatives through Path evaluators or sampled matrices. 2nd-order problems use $\boldsymbol{q}$, $\frac{\mathrm{d}\boldsymbol{q}}{\mathrm{d}s}$, and $\frac{\mathrm{d}^{2\boldsymbol{q}}{\mathrm{d}s}2}$; 3rd-order problems additionally use $\frac{\mathrm{d}^{3\boldsymbol{q}}{\mathrm{d}s}3}$;
  • robot and constraints: create a Robot, attach the station grid with with_s, then fill path data with with_q_from_path_2nd or with_q_from_path_3rd. Standard constraint APIs include with_axial_velocity, with_axial_acceleration, with_axial_torque, and with_axial_jerk for 3rd-order problems. Asymmetric and station-dependent limits are supported;
  • objective: TOPP solvers use traversal time as the objective. COPP solvers take a list of built-in CoppObjective terms, such as CoppObjective::Time, CoppObjective::ThermalEnergy, CoppObjective::TotalVariationTorque, and CoppObjective::Linear.
• Problem construction
  • 2nd-order: build a Topp2Problem or Copp2Problem with Topp2ProblemBuilder or Copp2ProblemBuilder;
  • 3rd-order: first prepare a feasible linearization profile a_linearization, commonly from topp2_ra. Optionally use robot.constraints.amax_substitute(...) to tighten the first-order upper bound. Then build the problem with Topp3ProblemBuilder::build_with_linearization or Copp3ProblemBuilder::build_with_linearization.
• Solving
  • choose the solver namespace according to the problem class and algorithm, for example solver::topp2_ra, solver::copp2_socp, solver::topp3_lp, solver::topp3_socp, or solver::copp3_socp;
  • build solver options with the corresponding options builder, then call the solver function.
• Outputs and post-processing
  • 2nd-order solvers return an a profile, where $a(s)=\dot{s}^2$;
  • 3rd-order solvers return a Topp3Profile, containing a, b, and stationary-boundary metadata;
  • convert path-domain profiles to timing data with s_to_t_topp2 or s_to_t_topp3. For a Topp3Profile, pass profile.as_parts();
  • convert timing data to sampled inverse parameterization s(t) with t_to_s_topp2 or t_to_s_topp3;
  • evaluate the original path at s(t) to generate position, velocity, and acceleration references for downstream controllers.

Documentation

The latest documentation for the published crate is available at https://docs.rs/copp/latest/copp/. For unreleased updates on the main branch, we recommend generating the documentation locally:

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

The generated docs include mathematical foundations, path/constraint construction methods, logging and output conventions, error definitions, and solver interfaces.

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 (2nd-order) is as follows:

//! This example uses [`topp2_ra`] to convert an analytic path into a second-order
//! time-optimal trajectory whose axial velocity and acceleration both stay within
//! `[-1, 1]`.

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,
};
use std::f64::consts::PI;

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();

    // 2) Build robot constraints (3-axis), then apply symmetric limits vel/acc = 1
    const DIM: usize = 3;
    let mut robot = Robot::with_capacity(DIM, n);
    // The axial velocity is -1 <= vel <= 1 for each axis in this example
    let vel_max = vec![1.0; DIM];
    let vel_min = vec![-1.0; DIM];
    // The axial acceleration is -1 <= acc <= 1 for each axis in this example.
    let acc_max = vec![1.0; DIM];
    let acc_min = vec![-1.0; DIM];
    robot
        .with_s(s.as_slice())?
        .with_q_from_path_2nd(&path, 0, n)?
        .with_axial_velocity((vel_max.as_slice(), n), (vel_min.as_slice(), n), 0)?
        .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(())
}

API for Other languages

• C: Please refer to README.md for C.
• Bindings for other languages are under active development. Planned targets include 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 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

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

Furthermore, we thank Jizhou Yan for his expertise on Rust and robotics.