Copp_core

Files
file	bindings/c/include/copp/core.h
	Core status, memory, matrix, and shared solver option types.

Data Structures
struct	CoppClarabelLinearSolverInfo
	Linear solver metadata reported by Clarabel. More...
struct	CoppClarabelSettings
	Advanced raw Clarabel solver settings. More...
struct	CoppClarabelOptions
	Shared Clarabel options for COPP SOCP solvers. More...
struct	CoppMatrixViewF64
	Borrowed immutable f64 matrix passed from C to COPP. More...
struct	CoppSliceF64
	Borrowed immutable f64 slice passed from C to COPP. More...
struct	CoppSliceMutF64
	Borrowed mutable f64 slice passed from C to COPP. More...
struct	CoppVecF64
	Library-owned f64 vector returned to C. More...
struct	CoppVecUsize
	Library-owned usize vector returned to C. More...
struct	CoppMatrixF64
	Library-owned column-major f64 matrix returned to C. More...

Macros
#define	COPP_MATRIX_VIEW_F64_COLUMN_MAJOR(data_, rows_, cols_)
	Build a contiguous column-major matrix view.
#define	COPP_MATRIX_VIEW_F64_ROW_MAJOR(data_, rows_, cols_)
	Build a contiguous row-major matrix view.

Enumerations
enum	CoppStatus {   COPP_STATUS_OK = 0 , COPP_STATUS_NULL_POINTER = 1 , COPP_STATUS_INVALID_LENGTH = 2 , COPP_STATUS_INVALID_SHAPE = 3 ,   COPP_STATUS_INVALID_ARGUMENT = 4 , COPP_STATUS_PANIC = 5 , COPP_STATUS_ALLOCATION_FAILED = 6 , COPP_STATUS_IO_ERROR = 100 ,   COPP_STATUS_CONSTRAINT_NON_INCREASING_S = 200 , COPP_STATUS_CONSTRAINT_NO_MATCH_DIMENSIONS = 201 , COPP_STATUS_CONSTRAINT_NO_MATCH_ORDER = 202 , COPP_STATUS_CONSTRAINT_INVALID_SIGNED_BOUNDS = 203 ,   COPP_STATUS_CONSTRAINT_OUT_OF_S_BOUNDS = 204 , COPP_STATUS_CONSTRAINT_NON_POSITIVE_A = 205 , COPP_STATUS_CONSTRAINT_NON_POSITIVE_LINEARIZATION_FLOOR = 206 , COPP_STATUS_CONSTRAINT_NO_GIVEN_Q_INFO = 207 ,   COPP_STATUS_CONSTRAINT_LINEAR_JERK_NOT_AVAILABLE = 208 , COPP_STATUS_CONSTRAINT_NO_DYNAMIC = 209 , COPP_STATUS_CONSTRAINT_INFEASIBLE_REFERENCE = 210 , COPP_STATUS_CONSTRAINT_EMPTY_INTERVAL = 211 ,   COPP_STATUS_PATH_INVALID_DIMENSION = 300 , COPP_STATUS_PATH_INVALID_RANGE = 301 , COPP_STATUS_PATH_INVALID_ORDER = 302 , COPP_STATUS_PATH_DIMENSION_MISMATCH = 303 ,   COPP_STATUS_PATH_NOT_ENOUGH_WAYPOINTS = 304 , COPP_STATUS_PATH_OUT_OF_RANGE_S = 305 , COPP_STATUS_PATH_UNSUPPORTED_BOUNDARY = 306 , COPP_STATUS_PATH_SINGULAR_SYSTEM = 307 ,   COPP_STATUS_PATH_UNSUPPORTED_DERIVATIVE_ORDER = 308 , COPP_STATUS_SOLVER_INFEASIBLE = 400 , COPP_STATUS_SOLVER_UNBOUNDED = 401 , COPP_STATUS_SOLVER_INVALID_INPUT = 402 ,   COPP_STATUS_SOLVER_INVALID_OPTIONS = 403 , COPP_STATUS_CLARABEL_SOLVER_ERROR = 404 , COPP_STATUS_CLARABEL_SOLVER_STATUS = 405 , COPP_STATUS_SOLVER_OTHER = 499 ,   COPP_STATUS_ROBOT_DYNAMICS_ERROR = 500 }
	C ABI status code returned by COPP FFI functions. More...
enum	CoppVerbosity { COPP_VERBOSITY_SILENT = 0 , COPP_VERBOSITY_SUMMARY = 1 , COPP_VERBOSITY_DEBUG = 2 , COPP_VERBOSITY_TRACE = 3 }
	C ABI verbosity level for solver diagnostics. More...
enum	CoppClarabelDirectSolveMethod {   COPP_CLARABEL_DIRECT_SOLVE_METHOD_AUTO = 0 , COPP_CLARABEL_DIRECT_SOLVE_METHOD_QDLDL = 1 , COPP_CLARABEL_DIRECT_SOLVE_METHOD_FAER = 2 , COPP_CLARABEL_DIRECT_SOLVE_METHOD_MKL = 3 ,   COPP_CLARABEL_DIRECT_SOLVE_METHOD_PANUA = 4 }
	Direct linear solver method forwarded to Clarabel. More...
enum	CoppClarabelSolverStatus {   COPP_CLARABEL_SOLVER_STATUS_UNSOLVED = 0 , COPP_CLARABEL_SOLVER_STATUS_SOLVED = 1 , COPP_CLARABEL_SOLVER_STATUS_PRIMAL_INFEASIBLE = 2 , COPP_CLARABEL_SOLVER_STATUS_DUAL_INFEASIBLE = 3 ,   COPP_CLARABEL_SOLVER_STATUS_ALMOST_SOLVED = 4 , COPP_CLARABEL_SOLVER_STATUS_ALMOST_PRIMAL_INFEASIBLE = 5 , COPP_CLARABEL_SOLVER_STATUS_ALMOST_DUAL_INFEASIBLE = 6 , COPP_CLARABEL_SOLVER_STATUS_MAX_ITERATIONS = 7 ,   COPP_CLARABEL_SOLVER_STATUS_MAX_TIME = 8 , COPP_CLARABEL_SOLVER_STATUS_NUMERICAL_ERROR = 9 , COPP_CLARABEL_SOLVER_STATUS_INSUFFICIENT_PROGRESS = 10 , COPP_CLARABEL_SOLVER_STATUS_CALLBACK_TERMINATED = 11 }
	Clarabel solver status returned by SOCP expert results. More...
enum	CoppMatrixLayout { COPP_MATRIX_LAYOUT_COLUMN_MAJOR = 0 , COPP_MATRIX_LAYOUT_ROW_MAJOR = 1 }
	Matrix memory layout used by CoppMatrixViewF64. More...

Functions
const char *	copp_status_message (enum CoppStatus status)
	Return a short static message for a COPP status code.
enum CoppStatus	copp_last_error_code (void)
	Return the status code associated with the current thread's last error.
const char *	copp_last_error_message (void)
	Return the current thread's last detailed error message as UTF-8.
size_t	copp_last_error_message_len (void)
	Return the length in bytes of the current thread's last UTF-8 error message.
enum CoppStatus	copp_last_error_message_copy (char *buffer, size_t capacity, size_t *out_len)
	Copy the current thread's last UTF-8 error message into a caller buffer.
void	copp_clear_last_error (void)
	Clear the current thread's last detailed error message.
enum CoppStatus	copp_set_last_error_message (enum CoppStatus status, const char *message)
	Set the current thread's last detailed error message from a C string.
enum CoppStatus	copp_set_last_error_message_n (enum CoppStatus status, const char *message, size_t len)
	Set the current thread's last detailed error message from a byte slice.
const char *	copp_version (void)
	Return the COPP library version.
enum CoppStatus	copp_clarabel_default_options (struct CoppClarabelOptions *out_options)
	Write default shared Clarabel options into out_options.
void	copp_vec_f64_free (struct CoppVecF64 vec)
	Release a library-owned f64 vector returned by COPP.
void	copp_vec_usize_free (struct CoppVecUsize vec)
	Release a library-owned usize vector returned by COPP.
void	copp_matrix_f64_free (struct CoppMatrixF64 matrix)
	Release a library-owned f64 matrix returned by COPP.
enum CoppStatus	copp_clarabel_solution_to_profile_2nd (size_t s_len, struct CoppSliceF64 x, struct CoppVecF64 *out_a)
	Extract a second-order COPP profile from a Clarabel primal solution.
enum CoppStatus	copp_clarabel_solution_to_profile_3rd (struct CoppSliceF64 s, struct CoppSliceF64 x, size_t num_stationary_start, size_t num_stationary_end, struct CoppProfile3rd *out_profile)
	Extract a third-order COPP profile from a Clarabel primal solution.

Detailed Description

Macro Definition Documentation

COPP_MATRIX_VIEW_F64_COLUMN_MAJOR

#define COPP_MATRIX_VIEW_F64_COLUMN_MAJOR	(		data_,
			rows_,
			cols_ )

Value:

((struct CoppMatrixViewF64){(data_), (rows_), (cols_), COPP_MATRIX_LAYOUT_COLUMN_MAJOR, (rows_)})

Build a contiguous column-major matrix view.

This is the recommended zero-copy input layout for COPP C APIs.

Definition at line 757 of file core.h.

COPP_MATRIX_VIEW_F64_ROW_MAJOR

#define COPP_MATRIX_VIEW_F64_ROW_MAJOR	(		data_,
			rows_,
			cols_ )

Value:

((struct CoppMatrixViewF64){(data_), (rows_), (cols_), COPP_MATRIX_LAYOUT_ROW_MAJOR, (cols_)})

Build a contiguous row-major matrix view.

COPP accepts this layout, but it converts the input to column-major temporary storage before use.

Definition at line 771 of file core.h.

Enumeration Type Documentation

CoppStatus

enum CoppStatus

C ABI status code returned by COPP FFI functions.

The numeric ranges are grouped by subsystem so future bindings can preserve source compatibility while still reporting precise failure classes.

Enumerator
COPP_STATUS_OK	Operation completed successfully.
COPP_STATUS_NULL_POINTER	A required pointer argument was null.
COPP_STATUS_INVALID_LENGTH	A slice length or vector length was invalid.
COPP_STATUS_INVALID_SHAPE	A matrix/vector shape was invalid.
COPP_STATUS_INVALID_ARGUMENT	An unsupported enum value or option was provided through the C ABI.
COPP_STATUS_PANIC	COPP caught an internal panic at the C ABI boundary.
COPP_STATUS_ALLOCATION_FAILED	A memory allocation failed or an output buffer could not be created.
COPP_STATUS_IO_ERROR	Filesystem or OS I/O failure.
COPP_STATUS_CONSTRAINT_NON_INCREASING_S	Constraint input s is not strictly increasing.
COPP_STATUS_CONSTRAINT_NO_MATCH_DIMENSIONS	Constraint input dimensions do not match the expected shape.
COPP_STATUS_CONSTRAINT_NO_MATCH_ORDER	Constraint input ordering does not match the expected contract.
COPP_STATUS_CONSTRAINT_INVALID_SIGNED_BOUNDS	Signed upper/lower bounds do not satisfy strict feasibility rules.
COPP_STATUS_CONSTRAINT_OUT_OF_S_BOUNDS	Requested station interval is outside the stored constraint range.
COPP_STATUS_CONSTRAINT_NON_POSITIVE_A	Profile a violates positivity requirements.
COPP_STATUS_CONSTRAINT_NON_POSITIVE_LINEARIZATION_FLOOR	Linearization floor is not strictly positive.
COPP_STATUS_CONSTRAINT_NO_GIVEN_Q_INFO	Required path derivative data is missing.
COPP_STATUS_CONSTRAINT_LINEAR_JERK_NOT_AVAILABLE	Linearized jerk constraints are unavailable for the requested station.
COPP_STATUS_CONSTRAINT_NO_DYNAMIC	Required dynamic-model data is unavailable.
COPP_STATUS_CONSTRAINT_INFEASIBLE_REFERENCE	Reference profile is infeasible under current constraints.
COPP_STATUS_CONSTRAINT_EMPTY_INTERVAL	Requested constraint interval is empty.
COPP_STATUS_PATH_INVALID_DIMENSION	Path dimension is invalid.
COPP_STATUS_PATH_INVALID_RANGE	Path parameter range is invalid.
COPP_STATUS_PATH_INVALID_ORDER	Spline order is invalid.
COPP_STATUS_PATH_DIMENSION_MISMATCH	Path matrix/tensor dimensions are incompatible.
COPP_STATUS_PATH_NOT_ENOUGH_WAYPOINTS	Not enough waypoints were supplied to build a path.
COPP_STATUS_PATH_OUT_OF_RANGE_S	Query parameter is outside the configured path range.
COPP_STATUS_PATH_UNSUPPORTED_BOUNDARY	Requested spline boundary condition is unsupported.
COPP_STATUS_PATH_SINGULAR_SYSTEM	Internal spline/path linear system is singular.
COPP_STATUS_PATH_UNSUPPORTED_DERIVATIVE_ORDER	Requested path derivative order is not supported by this path.
COPP_STATUS_SOLVER_INFEASIBLE	Solver reported infeasibility.
COPP_STATUS_SOLVER_UNBOUNDED	Solver reported unboundedness.
COPP_STATUS_SOLVER_INVALID_INPUT	Solver rejected the input model or data.
COPP_STATUS_SOLVER_INVALID_OPTIONS	Solver rejected the provided options.
COPP_STATUS_CLARABEL_SOLVER_ERROR	Clarabel returned an internal solver error.
COPP_STATUS_CLARABEL_SOLVER_STATUS	Clarabel terminated with a non-success status.
COPP_STATUS_SOLVER_OTHER	Backend-specific or uncategorized solver/runtime error.
COPP_STATUS_ROBOT_DYNAMICS_ERROR	User-provided robot inverse dynamics failed.

Definition at line 34 of file core.h.

CoppVerbosity

enum CoppVerbosity

C ABI verbosity level for solver diagnostics.

Enumerator
COPP_VERBOSITY_SILENT	No log will be emitted.
COPP_VERBOSITY_SUMMARY	Only summary information will be emitted.
COPP_VERBOSITY_DEBUG	Detailed debug information will be emitted.
COPP_VERBOSITY_TRACE	Very detailed trace information will be emitted.

Definition at line 332 of file core.h.

CoppClarabelDirectSolveMethod

enum CoppClarabelDirectSolveMethod

Direct linear solver method forwarded to Clarabel.

Enumerator
COPP_CLARABEL_DIRECT_SOLVE_METHOD_AUTO	Let Clarabel choose the direct solver.
COPP_CLARABEL_DIRECT_SOLVE_METHOD_QDLDL	Use Clarabel's QDLDL backend.
COPP_CLARABEL_DIRECT_SOLVE_METHOD_FAER	Use the optional FAER sparse backend when compiled into Clarabel.
COPP_CLARABEL_DIRECT_SOLVE_METHOD_MKL	Use the optional MKL Pardiso backend when compiled into Clarabel.
COPP_CLARABEL_DIRECT_SOLVE_METHOD_PANUA	Use the optional Panua Pardiso backend when compiled into Clarabel.

Definition at line 354 of file core.h.

CoppClarabelSolverStatus

enum CoppClarabelSolverStatus

Clarabel solver status returned by SOCP expert results.

Enumerator
COPP_CLARABEL_SOLVER_STATUS_UNSOLVED	Solver has not run.
COPP_CLARABEL_SOLVER_STATUS_SOLVED	Solver terminated with a solution.
COPP_CLARABEL_SOLVER_STATUS_PRIMAL_INFEASIBLE	Problem is primal infeasible.
COPP_CLARABEL_SOLVER_STATUS_DUAL_INFEASIBLE	Problem is dual infeasible.
COPP_CLARABEL_SOLVER_STATUS_ALMOST_SOLVED	Solver terminated with a reduced-accuracy solution.
COPP_CLARABEL_SOLVER_STATUS_ALMOST_PRIMAL_INFEASIBLE	Problem is primal infeasible with reduced accuracy.
COPP_CLARABEL_SOLVER_STATUS_ALMOST_DUAL_INFEASIBLE	Problem is dual infeasible with reduced accuracy.
COPP_CLARABEL_SOLVER_STATUS_MAX_ITERATIONS	Iteration limit reached before an accepted solution or certificate.
COPP_CLARABEL_SOLVER_STATUS_MAX_TIME	Time limit reached before an accepted solution or certificate.
COPP_CLARABEL_SOLVER_STATUS_NUMERICAL_ERROR	Solver terminated with a numerical error.
COPP_CLARABEL_SOLVER_STATUS_INSUFFICIENT_PROGRESS	Solver terminated due to lack of progress.
COPP_CLARABEL_SOLVER_STATUS_CALLBACK_TERMINATED	Solver terminated by callback.

Definition at line 380 of file core.h.

CoppMatrixLayout

enum CoppMatrixLayout

Matrix memory layout used by CoppMatrixViewF64.

COPP recommends column-major input because it matches nalgebra. Strictly contiguous column-major input (leading_dim == rows) can be borrowed as a slice, and padded column-major input (leading_dim >= rows) can be borrowed as a strided matrix view. Row-major input is accepted, but COPP copies it into column-major storage before passing it to COPP internals.

Enumerator
COPP_MATRIX_LAYOUT_COLUMN_MAJOR	Column-major storage: element (row, col) is at data[row + col * leading_dim].
COPP_MATRIX_LAYOUT_ROW_MAJOR	Row-major storage: element (row, col) is at data[col + row * leading_dim].

Definition at line 678 of file core.h.

Function Documentation

copp_status_message()

const char * copp_status_message

(

enum CoppStatus

status

)

Return a short static message for a COPP status code.

The returned pointer is a static null-terminated string owned by the library.

copp_last_error_code()

enum CoppStatus copp_last_error_code

(

void

)

Return the status code associated with the current thread's last error.

A successful COPP C ABI call clears this slot back to COPP_STATUS_OK.

copp_last_error_message()

const char * copp_last_error_message

(

void

)

Return the current thread's last detailed error message as UTF-8.

The returned pointer is owned by COPP and remains valid until the next COPP C ABI call on the same thread updates or clears the last-error slot. When no error is stored, this returns an empty string.

copp_last_error_message_len()

size_t copp_last_error_message_len

(

void

)

Return the length in bytes of the current thread's last UTF-8 error message.

The terminating null byte is not included in the returned length.

copp_last_error_message_copy()

enum CoppStatus copp_last_error_message_copy	(	char *	buffer,
		size_t	capacity,
		size_t *	out_len )

Copy the current thread's last UTF-8 error message into a caller buffer.

out_len, when non-null, receives the full message length in bytes, excluding the terminating null byte, even when capacity is too small. If buffer is non-null and capacity > 0, COPP always writes a null-terminated, possibly truncated UTF-8 prefix.

Example

The example below reports both the portable status string and the thread-local detail, then copies the detail into caller-owned storage. Inline snippets elsewhere in this reference use check(...) as shorthand for this kind of status handling.

static int check(enum CoppStatus status)
{
    if (status == COPP_STATUS_OK) {
        return 0;
    }
 
    fprintf(stderr, "status: %s\n", copp_status_message(status));
    fprintf(stderr, "detail: %s\n", copp_last_error_message());
    return 1;
}
 
size_t robot_len = 0;
enum CoppStatus status = copp_robot_len(NULL, &robot_len);
if (check(status)) {
    return 1;
}
 
size_t message_len = 0;
copp_last_error_message_copy(NULL, 0, &message_len);
 
char *message = malloc(message_len + 1);
if (message != NULL) {
    copp_last_error_message_copy(message, message_len + 1, NULL);
    fprintf(stderr, "owned detail: %s\n", message);
    free(message);
}

Safety

buffer must be valid for capacity writable bytes when capacity > 0. out_len, when non-null, must be valid for one size_t write.

copp_clear_last_error()

void copp_clear_last_error

(

void

)

Clear the current thread's last detailed error message.

copp_set_last_error_message()

enum CoppStatus copp_set_last_error_message	(	enum CoppStatus	status,
		const char *	message )

Set the current thread's last detailed error message from a C string.

The message is interpreted as UTF-8 with lossy replacement for invalid byte sequences. Interior null bytes cannot appear in this C-string variant; use copp_set_last_error_message_n when the message length is known.

Example

The example below sets callback-specific detail before returning a non-OK status to COPP.

static enum CoppStatus my_inverse_dynamics(
    void *user_data,
    size_t dim,
    const double *q,
    const double *dq,
    const double *ddq,
    double *tau)
{
    if (dim > 0 && (q == NULL || dq == NULL || ddq == NULL || tau == NULL)) {
        copp_set_last_error_message(
            COPP_STATUS_ROBOT_DYNAMICS_ERROR,
            "inverse dynamics callback received a null vector");
        return COPP_STATUS_ROBOT_DYNAMICS_ERROR;
    }
 
    for (size_t i = 0; i < dim; ++i) {
        tau[i] = ddq[i];
    }
    return COPP_STATUS_OK;
}

Safety

message must point to a null-terminated byte string when non-null.

copp_set_last_error_message_n()

enum CoppStatus copp_set_last_error_message_n	(	enum CoppStatus	status,
		const char *	message,
		size_t	len )

Set the current thread's last detailed error message from a byte slice.

The message is interpreted as UTF-8 with lossy replacement for invalid byte sequences, interior null bytes are replaced, and the stored message is capped at 64 KiB.

Safety

message must be valid for len reads when len > 0.

copp_version()

const char * copp_version

(

void

)

Return the COPP library version.

The returned pointer is a static null-terminated string owned by the library.

copp_clarabel_default_options()

enum CoppStatus copp_clarabel_default_options

(

struct CoppClarabelOptions *

out_options

)

Write default shared Clarabel options into out_options.

Defaults use COPP's default Clarabel settings and accept Solved and AlmostSolved statuses.

Safety

out_options must be valid for one CoppClarabelOptions write.

copp_vec_f64_free()

void copp_vec_f64_free

(

struct CoppVecF64

vec

)

Release a library-owned f64 vector returned by COPP.

Safety

vec must either be empty/null or have been returned by a COPP C ABI function. Passing arbitrary pointers or modified capacity fields is invalid.

copp_vec_usize_free()

void copp_vec_usize_free

(

struct CoppVecUsize

vec

)

Release a library-owned usize vector returned by COPP.

Safety

vec must either be empty/null or have been returned by a COPP C ABI function. Passing arbitrary pointers or modified capacity fields is invalid.

copp_matrix_f64_free()

void copp_matrix_f64_free

(

struct CoppMatrixF64

matrix

)

Release a library-owned f64 matrix returned by COPP.

Safety

matrix must either be empty/null or have been returned by a COPP C ABI function. Passing arbitrary pointers or modified capacity fields is invalid.

copp_clarabel_solution_to_profile_2nd()

enum CoppStatus copp_clarabel_solution_to_profile_2nd	(	size_t	s_len,
		struct CoppSliceF64	x,
		struct CoppVecF64 *	out_a )

Extract a second-order COPP profile from a Clarabel primal solution.

Use this helper with an expert SOCP result when the raw primal x vector should be converted back into the accepted a(s) = dot{s}^2 profile. The output has length s_len; missing tail values are filled with zero and all entries are clamped to be non-negative.

Example

The example below converts an expert raw primal vector into a second-order a(s) profile.

struct CoppVecF64 a = {0};
check(copp_clarabel_solution_to_profile_2nd(
    n,
    (struct CoppSliceF64){expert.x.data, expert.x.len},
    &a));
copp_vec_f64_free(a);

Safety

x.data must be valid for x.len reads when x.len is non-zero. out_a must be valid for one CoppVecF64 write and must later be released with copp_vec_f64_free.

copp_clarabel_solution_to_profile_3rd()

enum CoppStatus copp_clarabel_solution_to_profile_3rd	(	struct CoppSliceF64	s,
		struct CoppSliceF64	x,
		size_t	num_stationary_start,
		size_t	num_stationary_end,
		struct CoppProfile3rd *	out_profile )

Extract a third-order COPP profile from a Clarabel primal solution.

Use this helper with a TOPP3/COPP3 expert SOCP result when the raw primal x vector should be converted back into the accepted (a, b, num_stationary) profile. The station vector s defines the profile length and interval spacing.

Example

The example below converts an expert raw primal vector into a third-order (a, b) profile.

struct CoppProfile3rd profile = {{0}, {0}, 0, 0};
check(copp_clarabel_solution_to_profile_3rd(
    (struct CoppSliceF64){s, n},
    (struct CoppSliceF64){expert.x.data, expert.x.len},
    expert.profile.num_stationary_start,
    expert.profile.num_stationary_end,
    &profile));
copp_profile_3rd_free(profile);

Safety

s.data and x.data must be valid for their declared lengths when those lengths are non-zero. out_profile must be valid for one CoppProfile3rd write and must later be released with copp_profile_3rd_free.