Errors and Diagnostics

Exception Model

Python wrapper argument errors use ordinary Python exceptions such as ValueError. Examples include invalid array dtype/shape, mutually exclusive keyword arguments, or unsupported string tokens.

Errors returned by the solver core use CoppError and its typed subclasses. These usually mean the path, constraints, solver options, or numerical backend rejected an otherwise well-formed Python call.

Verbosity

Most option objects accept verbosity. You may pass either an enum value or a string:

options = copp.solver.topp2_ra.Options(verbosity="summary")

The accepted strings are "silent", "summary", "debug", and "trace". Keep "silent" for batch runs and use "summary" or "debug" when investigating infeasibility.

Clarabel Strict vs Expert Calls

Strict Clarabel-backed calls return only an accepted high-level profile:

profile = copp.solver.copp3_socp.solve(problem, options)

Expert calls expose raw diagnostics:

result = copp.solver.copp3_socp.solve_expert(problem, options)
print(result.solver_status)
print(result.iterations)
print(result.r_prim, result.r_dual)

If result.profile is None, Clarabel did not produce a profile accepted by the configured status policy. The raw status and residuals are still useful for tuning tolerances or debugging scaling.

Reachability Debugging

For TOPP2, inspect ReachSet2.a_min and ReachSet2.a_max to find where the feasible interval collapses. For TOPP3/COPP3, use the Clarabel expert results to inspect solver status, residuals, and accepted-profile availability near the suspected failure.