[FEA] Expand cuopt_c.h with problem-model accessors for non-Python language bindings

[ramakrishnap-nv]

Is your feature request related to a problem? Please describe.

The Java bindings (#1524) cannot reach parts of the problem model through the C API, so java/cuopt/src/main/native/cuopt_jni.cpp includes the private pdlp/cuopt_c_internal.hpp and reaches into problem_and_stream_view_t directly. There are 18 such call sites.

That couples libcuopt_jni.so to a specific libcuopt build rather than to a stable ABI. It is fine while the module is built from the same source tree, but it blocks shipping the jar as a binary artifact: a cuOpt point release can break it in ways no version range expresses. Any other C-ABI binding (Go, Rust, C#) would hit the same wall, and a jextract-based binding could not work around it at all, since jextract can only bind the C header.

This is the problem-model counterpart to #1202, which covers solver statistics.

Describe the solution you'd like

Roughly 10 functions. Two of them are already acknowledged as TODO in cuopt_c.h:

 * TODO: there is no getter for the quadratic objective matrix (Q)
 * or the quadratic constraint rows.

Name setters — the C API reads names but cannot set them

• cuOptSetVariableNames(problem, const char* const* names, cuopt_int_t count)
• cuOptSetRowNames(problem, const char* const* names, cuopt_int_t count)
• cuOptSetProblemName(problem, const char* name)
• cuOptGetProblemName(problem, char* buf, cuopt_int_t size) — no getter exists either

Quadratic objective (Q is CSR, so this mirrors cuOptGetConstraintMatrix)

• a non-zero count attribute, plus cuOptGetQuadraticObjective(problem, offsets, indices, values)

Quadratic constraint rows — the awkward one

quadratic_constraint_t is a variable-length array of variable-length records: each row carries a name, sense, RHS, a linear part (values + indices), and a COO Q (rows/cols/vals). Copy-out cannot express nested ragged data in one call, so it needs a shape-query-then-fill pattern, roughly:

cuOptGetNumQuadraticConstraints(problem, &n);
cuOptGetQuadraticConstraintSizes(problem, i, &n_linear, &n_quad);
cuOptGetQuadraticConstraint(problem, i, /* arrays */);
cuOptGetQuadraticConstraintName(problem, i, buf, size);

Describe alternatives you've considered

1. Leave the bindings on private headers — current state. Works for a source build, blocks binary distribution.
2. Return a struct — heavier ABI footprint, and does not solve the ragged quadratic-constraint case.

Additional context

• The copy-out accessors that cannot report "no data" were split out as [BUG] Copy-out solution accessors cannot distinguish "no data" from "data is all zeros" #1706, since that is a behaviour bug rather than a missing accessor.
• CUOPT_ATTR_PROBLEM_CATEGORY already exists; that call site just needs rewiring and needs no new API.
• Sizing, based on the seven functions already moved in Java bindings for LP/MIP/QP #1524 (141 lines of implementation and 134 of header for 7): roughly 240 + 230 lines, plus tests. Everything except the quadratic-constraint accessors is mechanical.
• Suggested order: name setters and the problem-name getter first (trivial), then the quadratic objective getters (closes half the existing TODO), then the quadratic constraint accessors once the shape-query pattern is agreed.

[mlubin]

Why does the Java API need to expose these setters and properties?

Availability / length reporting

Sounds like a bug/behavior issue in the C API that we should resolve, not a reason to provide a special interface for Java.

[ramakrishnap-nv]

@mlubin good questions — the first one rests on a premise I should correct, and you're right about the second.

The Java API does not expose these as setters

setVariableNames, setRowNames, and setProblemName are package-private on the internal NativeProblem wrapper, not public API. Names enter the public surface the same way they do in Python — as arguments when you build the model:

problem.addVariable(0.0, 1.0, 1.0, VariableType.INTEGER, "take_item_3");
problem.addConstraint(expr.le(102.0), "capacity");
new Problem("burglar");

The binding collects those names in its own model and has to hand them to the native problem at solve or write time. That handoff is the only reason it touches the internal header — there is no C API call that accepts names.

This is a C API gap, not a Java one

cuOptCreateProblem takes no names, and nothing else can set them, so no C-ABI caller can attach names to a problem it built programmatically. The MPS writer falls back to synthesising them:

std::string col_name = var_id < problem_.get_variable_names().size()
                         ? problem_.get_variable_names()[var_id]
                         : "C" + std::to_string(var_id);

So a C user who builds a model and calls cuOptWriteProblem gets C0, C1, … regardless of what the variables mean. The file is well-formed, but the names are unrecoverable, and a read-modify-write round trip through the C API silently loses them. That seems worth fixing for its own sake; Java is just the consumer that noticed.

If you would rather names were an argument to problem creation than a separate setter, that works equally well for the bindings — the requirement is only that some C API path accepts them.

Agreed on the length reporting

You're right that this is a C API behaviour bug rather than a reason for a Java-specific interface, and it shouldn't have been bundled into a feature request. Split out as #1706.

For context on why it is not theoretical: moving the bindings onto cuOptGetReducedCosts in #1524 turned "no reduced costs" into "all reduced costs are zero" for an infeasible LP, because the accessor copies nothing and still returns CUOPT_SUCCESS. That change had to be reverted. The same shape affects cuOptGetProblemStringArrayAttribute in the other direction, so both are described there.

I have removed that section from this issue so it covers only the missing accessors.

[chris-maes]

This is a nice to have. But should only affect the output of .LP and .MPS files. For now, it's fine if the Java API does not provide a way to input a name. Or it can just ignore the name.