[
  {
    "id": "numopt-py-eval-001-lp-api-call-sequence",
    "question": "I want to solve a small LP (continuous variables only, maximize a linear objective with linear constraints) using the cuOpt Python API. List the API calls in order \u2014 name each method, one line per method, no full runnable script.",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The agent produces an ordered list of API calls without a runnable script. The list, in order: (1) Import Problem, CONTINUOUS, and MAXIMIZE from cuopt.linear_programming.problem, and SolverSettings from cuopt.linear_programming.solver_settings. (2) Construct Problem('name'). (3) For each decision variable, call problem.addVariable(lb=..., vtype=CONTINUOUS, name=...). (4) For each constraint, call problem.addConstraint(<linear expression> <= or >= or == <rhs>, name=...). (5) Call problem.setObjective(<linear expression>, sense=MAXIMIZE). (6) Construct SolverSettings(); call set_parameter('time_limit', ...) for time budget. (7) Call problem.solve(settings). (8) Check problem.Status.name in ['Optimal', 'PrimalFeasible'] (PascalCase status names \u2014 case-sensitive). (9) Read problem.ObjValue for the objective, and each variable's .getValue() for its optimal value. The agent uses LP (not MILP / QP) because all variables are continuous and the objective is linear. Mentions that status names are PascalCase (Optimal, not OPTIMAL or optimal) \u2014 case sensitivity matters.",
    "expected_behavior": [
      "Selects LP (not MILP or QP) given continuous variables and a linear objective",
      "Lists the API calls in order without producing a full runnable script",
      "Names Problem, addVariable (with vtype=CONTINUOUS), addConstraint, setObjective (sense=MAXIMIZE)",
      "Names SolverSettings, set_parameter('time_limit', ...), and problem.solve(settings)",
      "Names problem.Status.name and the PascalCase status values (Optimal / PrimalFeasible / FeasibleFound)",
      "Names problem.ObjValue and variable.getValue() for reading results",
      "Mentions that status names are case-sensitive (PascalCase)",
      "Does not invent method names that are not in the skill"
    ]
  },
  {
    "id": "numopt-py-eval-002-status-case-sensitivity",
    "question": "My cuOpt Python LP solve runs without error but the result block never executes. Here is the check I wrote: if problem.Status.name == 'OPTIMAL': print(problem.ObjValue). What is wrong and how do I fix it?",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The check silently fails because cuOpt status names use PascalCase, not ALL_CAPS. The string 'OPTIMAL' never matches. The correct LP status values to check are 'Optimal' and 'PrimalFeasible'. The fixed check is: if problem.Status.name in ['Optimal', 'PrimalFeasible']: print(problem.ObjValue). For MILP the correct values are 'Optimal' and 'FeasibleFound'. This is a common silent bug \u2014 the solve completes successfully but the code path that reads results is skipped because the string comparison always returns False.",
    "expected_behavior": [
      "Identifies the bug as a case mismatch \u2014 'OPTIMAL' is wrong, 'Optimal' is correct",
      "States that cuOpt status names are PascalCase, not ALL_CAPS",
      "Gives the correct LP check: problem.Status.name in ['Optimal', 'PrimalFeasible']",
      "Notes that for MILP the passing status is 'FeasibleFound' not 'FEASIBLE_FOUND' or 'FEASIBLEFOUND'",
      "Explains why this is a silent failure \u2014 no exception is raised, the block just never executes"
    ]
  },
  {
    "id": "numopt-py-eval-003-integer-vs-continuous-workers",
    "question": "I am modeling a staffing problem where I need to decide how many nurses to assign to each ward. Should the nurse count variables be INTEGER or CONTINUOUS in the cuOpt Python API, and what vtype constant do I use for each?",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "Nurse counts should be INTEGER because nurses are discrete countable entities \u2014 you cannot assign 2.7 nurses to a ward. The vtype constant is INTEGER (imported from cuopt.linear_programming.problem). The addVariable call would be: problem.addVariable(lb=0, vtype=INTEGER, name='ward_a_nurses'). This makes the problem a MILP, not an LP. CONTINUOUS would be wrong here because it allows fractional values, which are meaningless for headcounts. The rule is: 'how many things' (people, vehicles, machines) \u2192 INTEGER; 'how much of something' (hours, tonnes, dollars) \u2192 CONTINUOUS.",
    "expected_behavior": [
      "States nurse counts must be INTEGER because nurses are discrete countable entities",
      "Names the correct vtype constant: INTEGER (imported from cuopt.linear_programming.problem)",
      "Shows or describes the addVariable call with vtype=INTEGER",
      "States this makes the problem MILP, not LP",
      "Explains why CONTINUOUS is wrong \u2014 it allows fractional nurse counts",
      "States the rule: countable things \u2192 INTEGER, measurable amounts \u2192 CONTINUOUS"
    ]
  },
  {
    "id": "numopt-py-eval-004-qp-maximize-workaround",
    "question": "I want to maximize a quadratic objective using the cuOpt Python QP API. When I pass sense=MAXIMIZE to setObjective, I get an error. What is the correct approach?",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The cuOpt QP solver only supports MINIMIZE \u2014 MAXIMIZE is rejected for quadratic objectives. The correct workaround is to negate all coefficients in the objective and minimize the negated expression. For example, to maximize -0.04*x1*x1 - 0.02*x2*x2 (a concave quadratic with NSD Q), minimize 0.04*x1*x1 + 0.02*x2*x2 with sense=MINIMIZE. The resulting problem.ObjValue will be the negated maximum; multiply by -1 to recover the true maximum. All variables must remain CONTINUOUS \u2014 integer QP is not supported. The Q matrix of the original maximization problem must be negative semi-definite (NSD) for the problem to be concave and have a finite maximum; after negation it becomes PSD, which is what the solver expects. Maximizing a convex quadratic (positive coefficients) is unbounded and not a meaningful use case.",
    "expected_behavior": [
      "States QP only supports MINIMIZE \u2014 MAXIMIZE is rejected",
      "Gives the correct workaround: negate all objective coefficients and use sense=MINIMIZE",
      "Notes that problem.ObjValue will be negated and must be multiplied by -1 to get the true maximum",
      "Reminds that all variables must be CONTINUOUS \u2014 integer QP is not supported",
      "Does not suggest a non-existent MAXIMIZE_QP or similar invented API"
    ]
  },
  {
    "id": "numopt-c-eval-001-milp-api-call-sequence",
    "question": "I want to solve a small MILP (some integer variables, linear objective, linear constraints) with the cuOpt C API. List the C functions and structs I need in order \u2014 names only, one line each, no full source.",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The agent produces an ordered list of C API entry points without writing a full source file: include cuopt/mathematical_optimization/cuopt_c.h, then call cuOptCreateRangedProblem with sense CUOPT_MINIMIZE or CUOPT_MAXIMIZE, then cuOptSolve(problem, settings, &solution), then cuOptGetObjectiveValue.",
    "expected_behavior": [
      "Lists C API call sequence without writing a complete source file",
      "Names cuOptCreateRangedProblem, cuOptSolve, cuOptGetObjectiveValue in order"
    ]
  },
  {
    "id": "numopt-c-eval-002-parameter-function-wrong-name",
    "question": "I am setting a time limit on my cuOpt C API solver with this call: cuOptSetIntParameter(settings, CUOPT_TIME_LIMIT, 60.0). My colleague says the function name is wrong. What is the correct function, and what other parameter-setting functions does the C API provide?",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The function name cuOptSetIntParameter does not exist in the cuOpt C API \u2014 it is a common mistake. The correct function for float parameters (including CUOPT_TIME_LIMIT, tolerances) is cuOptSetFloatParameter. The C API provides three parameter-setting functions: cuOptSetFloatParameter for float params such as time limits and tolerances, cuOptSetIntegerParameter (not cuOptSetIntParameter) for integer params such as CUOPT_LOG_TO_CONSOLE and method selection, and cuOptSetParameter for string params. CUOPT_TIME_LIMIT is a float parameter so the correct call is cuOptSetFloatParameter(settings, CUOPT_TIME_LIMIT, 60.0).",
    "expected_behavior": [
      "Identifies cuOptSetIntParameter as a non-existent function \u2014 the correct name is cuOptSetIntegerParameter",
      "States CUOPT_TIME_LIMIT is a float parameter requiring cuOptSetFloatParameter, not cuOptSetIntegerParameter",
      "Names all three parameter functions: cuOptSetFloatParameter, cuOptSetIntegerParameter, cuOptSetParameter",
      "Does not produce a full source file \u2014 answers the question about function names only"
    ]
  },
  {
    "id": "numopt-c-eval-003-csr-constraint-matrix",
    "question": "I am building the constraint matrix for a cuOpt C LP. The problem has 2 constraints and 2 variables. Constraint 1: 3x1 + 4x2 <= 5.4. Constraint 2: 2.7x1 + 10.1x2 <= 4.9. Show me the row_offsets, col_indices, and values arrays for the CSR representation, and explain what each array means.",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The CSR (Compressed Sparse Row) format uses three arrays. row_offsets has length num_constraints+1 = 3: {0, 2, 4}. Element i gives the starting index in col_indices/values for row i; the last element is the total number of nonzeros (4 here). col_indices = {0, 1, 0, 1}: the column index of each nonzero, ordered by row. values = {3.0, 4.0, 2.7, 10.1}: the nonzero values in the same order. Constraint upper bounds are {5.4, 4.9} and lower bounds are {-CUOPT_INFINITY, -CUOPT_INFINITY} since both constraints are <=. These arrays are passed to cuOptCreateRangedProblem.",
    "expected_behavior": [
      "Gives row_offsets = {0, 2, 4} and explains it as start indices per row plus total nnz at the end",
      "Gives col_indices = {0, 1, 0, 1} matching the column of each nonzero by row",
      "Gives values = {3.0, 4.0, 2.7, 10.1} in row-major order",
      "Explains that constraint_lower_bounds should be -CUOPT_INFINITY for <= constraints",
      "Names cuOptCreateRangedProblem as the function that receives these arrays"
    ]
  },
  {
    "id": "numopt-c-eval-004-qp-restrictions",
    "question": "I want to solve a QP with integer variables using the cuOpt C API. A colleague says this is not supported. Is that correct, and what are the restrictions for QP in the cuOpt C API?",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The colleague is correct \u2014 integer QP is not supported in the cuOpt C API. The QP restrictions are: (1) minimization only \u2014 CUOPT_MINIMIZE is required; to maximize a quadratic objective, negate all objective coefficients and Q matrix entries; (2) continuous variables only \u2014 all variables must use CUOPT_CONTINUOUS, integer variables are not supported for QP; (3) the Q matrix should be positive semi-definite (PSD) for a convex, well-posed problem. The same library, include paths, and build pattern as LP/MILP are used; only the problem-creation call differs for QP.",
    "expected_behavior": [
      "Confirms integer QP is not supported \u2014 all QP variables must be CUOPT_CONTINUOUS",
      "States QP only supports CUOPT_MINIMIZE, not CUOPT_MAXIMIZE",
      "Explains how to maximize: negate objective coefficients and Q entries",
      "Mentions Q should be positive semi-definite (PSD) for a convex problem",
      "Notes the same library/headers/build pattern as LP/MILP \u2014 only the problem creation call differs"
    ]
  },
  {
    "id": "numopt-cli-eval-001-mps-sections-and-cli-command",
    "question": "I have an LP problem I want to solve with cuopt_cli from an MPS file, with a 60-second time limit and 1% MIP gap (in case I add integers later). List the MPS sections in required order, and the cuopt_cli command line.",
    "expected_skill": "cuopt-numerical-optimization-api",
    "expected_script": null,
    "ground_truth": "The agent lists the MPS sections in the required order: NAME, ROWS (N row for the objective, L/G/E rows for constraints), COLUMNS (variable-name, row-name, coefficient triples), RHS (right-hand-side values), BOUNDS (optional \u2014 LO/UP/FX/BV/LI/UI), ENDATA. For integer variables, integer markers are 'MARKER' 'INTORG' before and 'MARKER' 'INTEND' after the integer columns. The cuopt_cli invocation is: cuopt_cli problem.mps --time-limit 60 --mip-relative-tolerance 0.01. The agent mentions cuopt_cli --help as the canonical source for all flags. Does not invent flags like --max-time or --gap that are not in the skill. Notes that cuopt_cli ships with the cuopt Python package (install via pip or conda first if not present).",
    "expected_behavior": [
      "Lists MPS sections in required order: NAME, ROWS, COLUMNS, RHS, [BOUNDS], ENDATA",
      "Mentions N row for objective and L/G/E for constraint types",
      "Mentions integer markers ('MARKER' 'INTORG' / 'INTEND') for integer columns",
      "Gives the cuopt_cli command with --time-limit 60 and --mip-relative-tolerance 0.01",
      "References cuopt_cli --help as the canonical flag source",
      "Does not invent flag names that are not in the skill (e.g. --max-time, --gap)",
      "Mentions that cuopt_cli ships with the cuopt Python package"
    ]
  }
]

# cuOpt Numerical Optimization — CLI

Solve LP, MILP, and QP problems from MPS or LP files via `cuopt_cli`. The same command and options apply across all three; QP is supported in both MPS (QPS) and LP files.

Confirm problem type and formulation (variables, objective, constraints, variable types) before coding.

The CLI is included with the `cuopt` Python package — install via pip or conda, then verify with `cuopt_cli --help`.

## Basic Usage

```bash
cuopt_cli <problem-file> [options]
```

The first positional argument is the input file. The format is chosen automatically from the extension — MPS, QPS, and LP files are all accepted (including `.gz` / `.bz2` compressed variants); run `cuopt_cli --help` for the exact list of supported extensions.

## Options

**`cuopt_cli --help` is the authoritative list — don't work from a hard-coded subset.** The CLI exposes every solver setting as a flag, generated from the parameter list at runtime: take any parameter documented in the cuOpt settings reference and replace underscores with hyphens (`time_limit` → `--time-limit`, `mip_relative_gap` → `--mip-relative-gap`). So if a parameter is documented, the flag exists; `--help` and the [solver-settings docs](https://docs.nvidia.com/cuopt/user-guide/latest/) are the sources of truth for names, meanings, and defaults.

A few options are CLI-specific (not solver parameters) and worth knowing because you wouldn't derive them from a parameter name:

- `--params-file <file>` — supply many parameters from a `key = value` config file instead of repeating flags.
- `--relaxation` — solve the continuous relaxation of a MILP (drop integrality).
- `--initial-solution <file>` — warm-start from a solution file.

Run `cuopt_cli --help` for the complete, current set.

## Authoring input files

MPS, QPS, and LP are precise, externally-specified file formats. Don't hand-author them from memory or from a partial recollection of the layout — column-position rules, marker conventions, the quadratic-objective encoding, and sign/scaling conventions are easy to get subtly wrong, and a malformed file either fails to parse or **silently encodes a different model than intended**.

If you're building a model from data (rather than solving a file you already have), **define the problem through the cuOpt Python API or your preferred modeling interface — don't generate an MPS or LP file by hand to feed the CLI.** These interfaces take coefficients, bounds, and variable types as native data structures, so there's no text format to get wrong. The cuOpt Python API solves and returns the solution in the same program (see [python_api.md](python_api.md)); a separate modeling library (e.g. PuLP, Pyomo, JuMP) can export a valid file for the CLI or call its own solver. Reach for `cuopt_cli` when you *already* have a model file — e.g. a benchmark instance or a file exported by one of these tools.

When a file is genuinely the right artifact, still generate it programmatically rather than by hand:

- **From cuOpt's Python API** — build the model, then export it with `model.writeMPS("problem.mps")` (emits a valid MPS file, including the quadratic objective for QP) and solve with `cuopt_cli problem.mps`.
- **From another modeling tool** — most LP/MILP modeling libraries and solvers can export standard MPS or LP files; pass the exported file straight to `cuopt_cli`.

If you must read or write these formats by hand anyway, work from the format's full specification (and the cuOpt repo docs at `docs/cuopt/source/cuopt-cli/` for cuOpt-specific conventions such as the quadratic-objective encoding) — not from an example alone.

Either way, **validate before trusting the result**: `cuopt_cli` logs `Read file ...` on a successful parse, and reports the variable/constraint counts and objective — sanity-check those against your intended model.

## MPS Format (required sections, in order)

1. **NAME** — problem name
2. **ROWS** — `N` (objective), `L`/`G`/`E` (constraints)
3. **COLUMNS** — variable names, row names, coefficients
4. **RHS** — right-hand side values
5. **BOUNDS** (optional) — `LO`, `UP`, `FX`, `BV`, `LI`, `UI`
6. **ENDATA**

Integer variables: wrap columns with `'MARKER' 'INTORG'` before and `'MARKER' 'INTEND'` after.

## QP via CLI (beta)

Quadratic objectives are **MINIMIZE only** (for maximization, negate the objective, including the quadratic terms) and require **continuous variables only** (no integer variables mixed with a quadratic objective). Quadratic objectives use the standard MPS quadratic-objective (QPS) extension and are also supported in LP files. Check `cuopt_cli --help` for QP-specific flags; see `docs/cuopt/source/cuopt-cli/` for the format.

## Troubleshooting

- **Parsing input file failed** — Confirm the extension matches the format (`.lp` vs `.mps`/`.qps`); an unrecognized extension is rejected before parsing. The parser error names the offending line — fix it against the format spec, or (more reliably) regenerate the file from a modeling tool rather than patching it by hand. Also check `ENDATA`, section order, and integer markers.
- **Infeasible** — Re-check the model against your intended formulation: constraint directions (`L`/`G`/`E`), right-hand sides, and variable bounds.

## Reference Models

| Model | Type | Location |
|-------|------|----------|
| Minimal LP | LP | [assets/cli/lp_simple/](../assets/cli/lp_simple/) |
| Production planning | LP | [assets/cli/lp_production/](../assets/cli/lp_production/) |
| Facility location | MILP | [assets/cli/milp_facility/](../assets/cli/milp_facility/) |

# cuOpt Numerical Optimization — C API

## Required Headers

```c
#include <cuopt/mathematical_optimization/cuopt_c.h>   // Core API
#include <cuopt/mathematical_optimization/constants.h> // Parameter name macros
```

## API Call Sequence

```
cuOptCreateRangedProblem(...)   // build CSR constraint matrix + variable types
cuOptCreateSolverSettings(...)
cuOptSetFloatParameter(...)     // time_limit, tolerances
cuOptSetIntegerParameter(...)   // log_to_console, method
cuOptSolve(problem, settings, &solution)
cuOptGetObjectiveValue(solution, &obj)
cuOptGetPrimalSolution(solution, values)
cuOptGetDualSolution(...)       // LP/QP only
// cleanup
cuOptDestroyProblem(...)
cuOptDestroySolverSettings(...)
cuOptDestroySolution(...)
```

## Parameter Setting Functions

| Function | Use for |
|----------|---------|
| `cuOptSetFloatParameter` | `time_limit`, tolerances |
| `cuOptSetIntegerParameter` | `log_to_console`, `method`, `presolve` |

**Common mistake:** `cuOptSetIntParameter` does not exist — use `cuOptSetIntegerParameter`.

## LP Example

```c
#include <cuopt/mathematical_optimization/cuopt_c.h>
#include <cuopt/mathematical_optimization/constants.h>
#include <stdio.h>
#include <stdlib.h>

int main() {
    cuOptOptimizationProblem problem = NULL;
    cuOptSolverSettings settings = NULL;
    cuOptSolution solution = NULL;

    cuopt_int_t num_variables = 2, num_constraints = 2;

    // Constraint matrix in CSR format
    cuopt_int_t row_offsets[] = {0, 2, 4};
    cuopt_int_t col_indices[] = {0, 1, 0, 1};
    cuopt_float_t values[] = {3.0, 4.0, 2.7, 10.1};

    cuopt_float_t obj_coeffs[] = {-0.2, 0.1};
    cuopt_float_t con_lb[] = {-CUOPT_INFINITY, -CUOPT_INFINITY};
    cuopt_float_t con_ub[] = {5.4, 4.9};
    cuopt_float_t var_lb[] = {0.0, 0.0};
    cuopt_float_t var_ub[] = {CUOPT_INFINITY, CUOPT_INFINITY};
    char var_types[] = {CUOPT_CONTINUOUS, CUOPT_CONTINUOUS};

    cuopt_int_t status = cuOptCreateRangedProblem(
        num_constraints, num_variables, CUOPT_MINIMIZE, 0.0,
        obj_coeffs, row_offsets, col_indices, values,
        con_lb, con_ub, var_lb, var_ub, var_types, &problem
    );
    if (status != CUOPT_SUCCESS) { return 1; }

    cuOptCreateSolverSettings(&settings);
    cuOptSetFloatParameter(settings, CUOPT_TIME_LIMIT, 60.0);

    status = cuOptSolve(problem, settings, &solution);

    cuopt_float_t obj;
    cuOptGetObjectiveValue(solution, &obj);
    printf("Objective: %f\n", obj);

    cuopt_float_t* sol = malloc(num_variables * sizeof(cuopt_float_t));
    cuOptGetPrimalSolution(solution, sol);
    printf("x1=%f x2=%f\n", sol[0], sol[1]);
    free(sol);

    cuOptDestroyProblem(&problem);
    cuOptDestroySolverSettings(&settings);
    cuOptDestroySolution(&solution);
    return 0;
}
```

For MILP, set `var_types[i] = CUOPT_INTEGER` for integer variables and use `CUOPT_MIP_RELATIVE_GAP` / `CUOPT_MIP_ABSOLUTE_TOLERANCE` settings.

## QP via C API (beta)

QP uses the same library, headers, and build pattern — only the problem-creation call differs (it accepts a quadratic objective). See `cpp/include/cuopt/mathematical_optimization/` for QP-specific creation calls and `docs/cuopt/source/cuopt-c/lp-qp-milp/` for end-to-end QP examples.

**QP rules:** MINIMIZE only (`CUOPT_MINIMIZE`); continuous variables only (`CUOPT_CONTINUOUS`); Q should be PSD.

## Dual Values (LP / QP)

`cuOptGetDualSolution` and `cuOptGetReducedCosts` return duals for LP and QP. They return `NaN` arrays when the model has quadratic constraints. Not available for MILP.

See [assets/c/lp_duals/](../assets/c/lp_duals/) for the call sequence.

## Constants Reference

```c
CUOPT_MINIMIZE / CUOPT_MAXIMIZE
CUOPT_CONTINUOUS / CUOPT_INTEGER
CUOPT_INFINITY / -CUOPT_INFINITY
CUOPT_SUCCESS  // 0

// Float parameters
CUOPT_TIME_LIMIT
CUOPT_ABSOLUTE_PRIMAL_TOLERANCE
CUOPT_MIP_RELATIVE_GAP
CUOPT_MIP_ABSOLUTE_TOLERANCE
CUOPT_MIP_RELATIVE_TOLERANCE

// Integer parameters
CUOPT_LOG_TO_CONSOLE
CUOPT_METHOD        // CUOPT_METHOD_CONCURRENT(0), PDLP(1), DUAL_SIMPLEX(2), BARRIER(3)
CUOPT_PRESOLVE
```

Full list: `cpp/include/cuopt/mathematical_optimization/constants.h`

## Build

See [assets/c/README.md](../assets/c/README.md) for the conda-env include/library/`LD_LIBRARY_PATH` setup and `gcc` build command.

## Reference Models

| Model | Type | Location |
|-------|------|----------|
| Simple LP | LP | [assets/c/lp_basic/](../assets/c/lp_basic/) |
| Dual values | LP | [assets/c/lp_duals/](../assets/c/lp_duals/) |
| PDLP warmstart | LP | [assets/c/lp_warmstart/](../assets/c/lp_warmstart/) |
| Integer variable | MILP | [assets/c/milp_basic/](../assets/c/milp_basic/) |
| Production planning | MILP | [assets/c/milp_production_planning/](../assets/c/milp_production_planning/) |
| MPS file solver | LP/MILP | [assets/c/mps_solver/](../assets/c/mps_solver/) |

# cuOpt Numerical Optimization — Python API

## Quick Reference

```python
from cuopt.linear_programming.problem import Problem, CONTINUOUS, INTEGER, MINIMIZE, MAXIMIZE
from cuopt.linear_programming.solver_settings import SolverSettings
```

## LP Example

```python
problem = Problem("MyLP")

x = problem.addVariable(lb=0, vtype=CONTINUOUS, name="x")
y = problem.addVariable(lb=0, vtype=CONTINUOUS, name="y")

problem.addConstraint(2*x + 3*y <= 120, name="resource_a")
problem.addConstraint(4*x + 2*y <= 100, name="resource_b")
problem.setObjective(40*x + 30*y, sense=MAXIMIZE)

settings = SolverSettings()
settings.set_parameter("time_limit", 60)
problem.solve(settings)

if problem.Status.name in ["Optimal", "PrimalFeasible"]:
    print(f"Objective: {problem.ObjValue}")
    print(f"x = {x.getValue()}, y = {y.getValue()}")
```

## MILP Example

```python
problem = Problem("FacilityLocation")

open_facility = problem.addVariable(lb=0, ub=1, vtype=INTEGER, name="open")
production = problem.addVariable(lb=0, vtype=CONTINUOUS, name="production")

problem.addConstraint(production <= 1000 * open_facility, name="link")
problem.setObjective(500*open_facility + 2*production, sense=MINIMIZE)

settings = SolverSettings()
settings.set_parameter("time_limit", 120)
settings.set_parameter("mip_relative_gap", 0.01)
problem.solve(settings)

if problem.Status.name in ["Optimal", "FeasibleFound"]:
    print(f"Open: {open_facility.getValue() > 0.5}, Production: {production.getValue()}")
```

## QP Example (beta — MINIMIZE only)

```python
problem = Problem("Portfolio")
x1 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_a")
x2 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_b")
x3 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_c")

problem.setObjective(
    0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3
    + 0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3,
    sense=MINIMIZE,
)
problem.addConstraint(x1 + x2 + x3 == 1, name="budget")
problem.addConstraint(0.12*x1 + 0.08*x2 + 0.05*x3 >= 0.08, name="min_return")

problem.solve(SolverSettings())
if problem.Status.name in ["Optimal", "PrimalFeasible"]:
    print(f"Variance: {problem.ObjValue}")
```

See [qp_examples.md](qp_examples.md) for least-squares, maximization workaround, and covariance matrix expansion.

## CRITICAL: Status Values Use PascalCase

```python
# ✅ CORRECT
if problem.Status.name in ["Optimal", "FeasibleFound"]:
    print(problem.ObjValue)

# ❌ WRONG — silently never matches
if problem.Status.name == "OPTIMAL":
    ...
```

**LP:** `Optimal`, `NoTermination`, `NumericalError`, `PrimalInfeasible`, `DualInfeasible`, `IterationLimit`, `TimeLimit`, `PrimalFeasible`

**MILP:** `Optimal`, `FeasibleFound`, `Infeasible`, `Unbounded`, `TimeLimit`, `NoTermination`

**QP:** same set as LP.

## Solver Settings

```python
settings = SolverSettings()
settings.set_parameter("time_limit", 60)
settings.set_parameter("mip_relative_gap", 0.01)  # MILP: stop within 1% of optimal
settings.set_parameter("log_to_console", 1)
```

## Dual Values (LP / QP)

```python
if problem.Status.name == "Optimal":
    constraint = problem.getConstraint("resource_a")
    print(f"Dual value: {constraint.DualValue}")  # NaN if model has quadratic constraints
```

## Common Modeling Patterns

### Binary Selection
```python
items = [problem.addVariable(lb=0, ub=1, vtype=INTEGER) for _ in range(n)]
problem.addConstraint(sum(items) == k)
```

### Big-M Linking
```python
M = 10000
problem.addConstraint(x <= 100 + M*(1 - y))
```

### If-then "must also produce"
```python
problem.addConstraint(y_X <= y_Y)
problem.addConstraint(production_Y >= 1 * y_Y)
```

### Large Expressions (avoid recursion limit)
```python
from cuopt.linear_programming.problem import LinearExpression

expr = LinearExpression([x, y, z], [1.0, 2.0, 3.0], constant=0.0)
problem.addConstraint(expr <= 100)
```

## Reference Models

| Model | Type | Location |
|-------|------|----------|
| Minimal LP | LP | [assets/python/lp_basic/](../assets/python/lp_basic/) |
| Dual values | LP | [assets/python/lp_duals/](../assets/python/lp_duals/) |
| PDLP warmstart | LP | [assets/python/lp_warmstart/](../assets/python/lp_warmstart/) |
| Integer variables | MILP | [assets/python/milp_basic/](../assets/python/milp_basic/) |
| Production planning | MILP | [assets/python/milp_production_planning/](../assets/python/milp_production_planning/) |
| Portfolio variance | QP | [assets/python/portfolio/](../assets/python/portfolio/) |
| Least squares | QP | [assets/python/least_squares/](../assets/python/least_squares/) |
| Maximization workaround | QP | [assets/python/maximization_workaround/](../assets/python/maximization_workaround/) |
| MPS file solver | LP/MILP | [assets/python/mps_solver/](../assets/python/mps_solver/) |

# QP: Python API Examples

## Portfolio Optimization

```python
"""
Minimize portfolio variance (risk):
    minimize    x^T * Q * x
    subject to  sum(x) = 1         (fully invested)
                r^T * x >= target  (minimum return)
                x >= 0             (no short selling)

Note: QP is beta and MUST use MINIMIZE (not MAXIMIZE)
"""
from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE
from cuopt.linear_programming.solver_settings import SolverSettings

problem = Problem("Portfolio")

# Portfolio weights (decision variables)
x1 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_a")
x2 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_b")
x3 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_c")

# Expected returns
r1, r2, r3 = 0.12, 0.08, 0.05  # 12%, 8%, 5%
target_return = 0.08

# Covariance matrix Q:
# [[0.04, 0.01, 0.005],
#  [0.01, 0.02, 0.008],
#  [0.005, 0.008, 0.01]]
#
# Quadratic objective: x^T * Q * x
# Expanded: 0.04*x1² + 0.02*x2² + 0.01*x3² + 2*0.01*x1*x2 + 2*0.005*x1*x3 + 2*0.008*x2*x3

problem.setObjective(
    0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3 +
    0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3,
    sense=MINIMIZE  # MUST be MINIMIZE for QP!
)

# Linear constraints
problem.addConstraint(x1 + x2 + x3 == 1, name="budget")
problem.addConstraint(r1*x1 + r2*x2 + r3*x3 >= target_return, name="min_return")

# Solve
settings = SolverSettings()
settings.set_parameter("time_limit", 60)
problem.solve(settings)

# Results
if problem.Status.name in ["Optimal", "PrimalFeasible"]:
    print(f"Portfolio variance: {problem.ObjValue:.6f}")
    print(f"Portfolio std dev: {problem.ObjValue**0.5:.4f}")
    print(f"\nAllocation:")
    print(f"  Stock A: {x1.getValue()*100:.2f}%")
    print(f"  Stock B: {x2.getValue()*100:.2f}%")
    print(f"  Stock C: {x3.getValue()*100:.2f}%")

    actual_return = r1*x1.getValue() + r2*x2.getValue() + r3*x3.getValue()
    print(f"\nExpected return: {actual_return*100:.2f}%")
```

## Least Squares

```python
"""
Minimize ||Ax - b||² = (Ax-b)^T(Ax-b)

Example: Find point closest to (3, 4)
minimize (x-3)² + (y-4)² = x² - 6x + 9 + y² - 8y + 16
"""
from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE
from cuopt.linear_programming.solver_settings import SolverSettings

problem = Problem("LeastSquares")

x = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="x")
y = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="y")

# Quadratic objective: (x-3)² + (y-4)²
# Expanded: x² + y² - 6x - 8y + 25
problem.setObjective(
    x*x + y*y - 6*x - 8*y + 25,
    sense=MINIMIZE
)

result = problem.solve(SolverSettings())

if problem.Status.name in ["Optimal", "PrimalFeasible"]:
    print(f"x = {x.getValue():.4f}")  # Should be ~3
    print(f"y = {y.getValue():.4f}")  # Should be ~4
else:
    raise RuntimeError(f"Solver failed with status: {problem.Status.name}")
```

## Quadratic with Linear Constraints

```python
"""
minimize    x² + y² + z²
subject to  x + y + z = 10
            x >= 0, y >= 0, z >= 0
"""
from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE

problem = Problem("QuadraticConstrained")

x = problem.addVariable(lb=0, vtype=CONTINUOUS, name="x")
y = problem.addVariable(lb=0, vtype=CONTINUOUS, name="y")
z = problem.addVariable(lb=0, vtype=CONTINUOUS, name="z")

problem.setObjective(x*x + y*y + z*z, sense=MINIMIZE)
problem.addConstraint(x + y + z == 10)

problem.solve()

if problem.Status.name == "Optimal":
    print(f"x = {x.getValue():.4f}")
    print(f"y = {y.getValue():.4f}")
    print(f"z = {z.getValue():.4f}")
    print(f"Objective = {problem.ObjValue:.4f}")
```

## Maximization Workaround

```python
"""
QP only supports MINIMIZE.
To maximize f(x), minimize -f(x).

Example: maximize -x² + 4x  (parabola with max at x=2)
"""
from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE

problem = Problem("MaxWorkaround")

x = problem.addVariable(lb=0, ub=10, vtype=CONTINUOUS, name="x")

# Want to maximize: -x² + 4x
# Instead minimize: -(-x² + 4x) = x² - 4x
problem.setObjective(x*x - 4*x, sense=MINIMIZE)

problem.solve()

if problem.Status.name in ["Optimal", "PrimalFeasible"]:
    print(f"x = {x.getValue():.4f}")  # Should be 2
    print(f"Minimized value = {problem.ObjValue:.4f}")  # Should be -4
    print(f"Original maximum = {-problem.ObjValue:.4f}")  # Should be 4
else:
    print(f"Solver did not find optimal solution. Status: {problem.Status.name}")
```

## Expanding Covariance Matrix

Given covariance matrix Q and weight vector x:

```python
# Covariance matrix
Q = [
    [0.04, 0.01, 0.005],
    [0.01, 0.02, 0.008],
    [0.005, 0.008, 0.01]
]

# Expansion: x^T * Q * x
# = Q[0,0]*x1² + Q[1,1]*x2² + Q[2,2]*x3²
#   + 2*Q[0,1]*x1*x2 + 2*Q[0,2]*x1*x3 + 2*Q[1,2]*x2*x3
#
# = 0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3
#   + 0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3

objective = (
    Q[0][0]*x1*x1 + Q[1][1]*x2*x2 + Q[2][2]*x3*x3 +
    2*Q[0][1]*x1*x2 + 2*Q[0][2]*x1*x3 + 2*Q[1][2]*x2*x3
)
```

## Critical Reminders

1. **MINIMIZE only** - solver rejects MAXIMIZE for QP
2. **Convexity** - Q should be positive semi-definite
3. **Beta status** - API may change in future versions
4. **Status checking** - use PascalCase: `"Optimal"` not `"OPTIMAL"`

---

## Additional References (tested in CI)

For more complete examples, read these files:

| Example | File | Description |
|---------|------|-------------|
| Simple QP | `docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py` | Basic QP setup |
| QP with Matrix | `docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py` | CSR matrix format for Q |

These examples are tested by CI (`ci/test_doc_examples.sh`) and represent canonical usage.