Copp_topp3

Files
file	bindings/c/include/copp/topp3.h
	TOPP3-LP and TOPP3-SOCP APIs.

Functions
enum CoppStatus	topp3_lp (struct Topp3Problem problem, struct CoppClarabelOptions options, struct CoppProfile3rd *out_profile)
	Solve a TOPP3-LP problem.
enum CoppStatus	topp3_lp_expert (struct Topp3Problem problem, struct CoppClarabelOptions options, struct Copp3SocpResult *out_result)
	Solve a TOPP3-LP problem and always return Clarabel diagnostics.
enum CoppStatus	topp3_socp (struct Topp3Problem problem, struct CoppClarabelOptions options, struct CoppProfile3rd *out_profile)
	Solve a TOPP3-SOCP problem.
enum CoppStatus	topp3_socp_expert (struct Topp3Problem problem, struct CoppClarabelOptions options, struct Copp3SocpResult *out_result)
	Solve a TOPP3-SOCP problem and always return Clarabel diagnostics.

Detailed Description

Function Documentation

topp3_lp()

enum CoppStatus topp3_lp	(	struct Topp3Problem	problem,
		struct CoppClarabelOptions	options,
		struct CoppProfile3rd *	out_profile )

Solve a TOPP3-LP problem.

This C ABI builds an internal TOPP3 problem from the borrowed Topp3Problem, forwards options to the Clarabel backend, and returns only the accepted third-order profile.

On success, out_profile owns COPP-allocated a and b vectors and must be released with copp_profile_3rd_free.

Example

The example below solves TOPP3-LP and releases the accepted third-order profile.

struct CoppClarabelOptions options;
struct CoppProfile3rd profile = {{0}, {0}, 0, 0};
 
check(copp_clarabel_default_options(&options));
check(topp3_lp(problem, options, &profile));
copp_profile_3rd_free(profile);

Warning

Safety problem.robot must be a non-null mutable handle returned by copp_robot_create and must remain valid for the duration of this call. The solver builds the internal problem by linearizing third-order constraints, which mutates the robot's internal constraint cache. out_profile must be valid for one CoppProfile3rd write.

topp3_lp_expert()

enum CoppStatus topp3_lp_expert	(	struct Topp3Problem	problem,
		struct CoppClarabelOptions	options,
		struct Copp3SocpResult *	out_result )

Solve a TOPP3-LP problem and always return Clarabel diagnostics.

This expert entry follows the advanced-diagnostics convention: true runtime failures still return a non-OK CoppStatus, but non-accepted Clarabel statuses are reported inside out_result with has_profile == false and the function returns COPP_STATUS_OK.

TOPP3-LP has no user-provided COPP objective list, so out_result.objective_value is NaN and out_result.objective_terms is an empty vector. Raw Clarabel objective values and solver diagnostics are still populated.

Use the same advanced-diagnostics pattern as copp2_socp_expert. The result type is Copp3SocpResult, and has_profile replaces has_a.

Warning

Safety Same safety requirements as topp3_lp. out_result must be valid for one Copp3SocpResult write and must later be released with copp3_socp_result_free.

topp3_socp()

enum CoppStatus topp3_socp	(	struct Topp3Problem	problem,
		struct CoppClarabelOptions	options,
		struct CoppProfile3rd *	out_profile )

Solve a TOPP3-SOCP problem.

This C ABI builds an internal TOPP3 problem from the borrowed Topp3Problem, forwards options to the Clarabel backend, and returns only the accepted third-order profile.

On success, out_profile owns COPP-allocated a and b vectors and must be released with copp_profile_3rd_free.

Example

The example below solves TOPP3-SOCP and releases the accepted third-order profile.

struct CoppClarabelOptions options;
struct CoppProfile3rd profile = {{0}, {0}, 0, 0};
 
check(copp_clarabel_default_options(&options));
check(topp3_socp(problem, options, &profile));
copp_profile_3rd_free(profile);

Warning

Safety problem.robot must be a non-null mutable handle returned by copp_robot_create and must remain valid for the duration of this call. The solver builds the internal problem by linearizing third-order constraints, which mutates the robot's internal constraint cache. out_profile must be valid for one CoppProfile3rd write.

topp3_socp_expert()

enum CoppStatus topp3_socp_expert	(	struct Topp3Problem	problem,
		struct CoppClarabelOptions	options,
		struct Copp3SocpResult *	out_result )

Solve a TOPP3-SOCP problem and always return Clarabel diagnostics.

This expert entry follows the advanced-diagnostics convention: true runtime failures still return a non-OK CoppStatus, but non-accepted Clarabel statuses are reported inside out_result with has_profile == false and the function returns COPP_STATUS_OK.

TOPP3-SOCP has no user-provided COPP objective list, so out_result.objective_value is NaN and out_result.objective_terms is an empty vector. Raw Clarabel objective values and solver diagnostics are still populated.

Use the same advanced-diagnostics pattern as copp2_socp_expert. The result type is Copp3SocpResult, and has_profile replaces has_a.

Warning

Safety Same safety requirements as topp3_socp. out_result must be valid for one Copp3SocpResult write and must later be released with copp3_socp_result_free.