Troubleshooting

Validation fails before solving

Call problem.validate() directly instead of relying only on problem.is_dblp(). The former preserves the detailed exception. Common causes are a non-DPP lower expression, an objective with curvature incompatible with its sense (such as maximizing a convex expression), an unsupported cone, an approximate or unaudited atom, an unset ordinary CVXPY parameter, or a lifted expression that CVXPY does not recognize as DNLP.

blvpy.ValidationError and its subclasses identify structural model issues. blvpy.CanonicalizationError indicates that CVXPY did not expose the exact canonical form BLVPY expected.

A lower model is rejected

BLVPY validates the source expression and its canonical cone program as two separate layers. The exception identifies which layer failed.

Source-expression checks

  • blvpy.UnsupportedModelError means a source atom is outside the audited set. Supported atoms lists every directly audited nonlinear atom.

  • blvpy.ApproximateCanonicalizationError means an atom has nonzero or nonfinite approximation error, or a constraint uses a quadrature approximation. Accepted rational representations must report finite approx_error equal to zero. PowCone3DApprox is rejected because it uses an SOC approximation; use the native cp.PowCone3D constraint when the model requires an exact three-dimensional power cone.

Canonical-form checks

At the cone level, BLVPY supports zero, nonnegative, second-order, exponential, and three-dimensional power-cone blocks. PSD and N-dimensional power-cone blocks are unsupported.

IPOPT cannot be loaded

blvpy.SolverUnavailableError means CVXPY could not load the requested backend. For IPOPT, verify both the native library and cyipopt in the same Python environment that runs BLVPY. See Installation; calling cp.installed_solvers() is not BLVPY’s availability test because native loading can still fail at solve time.

Automatic initialization fails

In deterministic mode, assign .value to every variable named by the blvpy.InitializationError, then solve again. For explicit best-of searches, each named upper variable needs finite sample_bounds, an existing .value, or finite two-sided native bounds. See Best-of search for local solutions for the precedence rules.

An initialized upper point can still lead to an infeasible or unbounded fixed lower problem. Read exception notes and the BLVPY progress transcript for the conic status or restoration reason.

Continuation does not reach the target

A returned continuation_failed result contains the best partial run: smallest attained epsilon, then best finite objective in the modeled sense (lowest for cp.Minimize, highest for cp.Maximize), then lowest run index. A missing or nonfinite objective ranks after a finite objective at the same epsilon. Inspect result.runs, attempted_epsilon_history, and each iteration’s message and residuals. Possible responses include a looser target, gentler contraction, more retries, better scaling, explicit initialization, or a best-of search.

Nonlinear cone residuals are unexpectedly large

Exponential- and 3D power-cone residual distances are numerical estimates. Scale a cone triple to a moderate common magnitude and, when an equivalent formulation permits it, avoid extreme ratios between its components. BLVPY attempts an exact shared power-of-two normalization. Uncertain solver results may be retried or replaced by a conservative upper bound rather than reported as zero.

If BLVPY cannot obtain a usable positive estimate, it reports the distance to the cone’s zero element as a conservative upper bound. This fail-closed result can cause an otherwise acceptable iterate to fail its residual check. See Cone distance diagnostics for the numerical contract.

Diagnostics fail

gap_diagnostics() requires complete source and canonical snapshots and a successful or continuation_failed result. Its reference lower solve can fail independently of the DNLP solve. Choose another compatible conic solver or pass solver-specific options when appropriate.