Combine formulation and API skills into numerical-optimization skill family

.claude-plugin/marketplace.json

@@ -45,28 +45,28 @@
       "description": "Developer installation — build cuOpt from source, run tests. Use when the user wants to set up a dev environment to contribute or modify cuOpt."
     },
     {
-      "name": "lp-milp-formulation",
-      "source": "./skills/lp-milp-formulation",
+      "name": "numerical-optimization-formulation",
+      "source": "./skills/numerical-optimization-formulation",
       "skills": "./",
-      "description": "LP/MILP concepts and going from problem text to formulation. What LP/MILP are, required formulation questions, typical modeling elements, and how to parse problem statements."
+      "description": "Numerical optimization (LP, MILP, QP) — concepts, problem-text parsing, and formulation patterns. What LP, MILP, and QP are, required formulation questions, modeling elements, common patterns, and how to parse problem statements (parameters, constraints, decisions, objective). Domain concepts; no API or interface."
     },
     {
-      "name": "cuopt-lp-milp-api-python",
-      "source": "./skills/cuopt-lp-milp-api-python",
+      "name": "cuopt-numerical-optimization-api-python",
+      "source": "./skills/cuopt-numerical-optimization-api-python",
       "skills": "./",
-      "description": "Solve LP and MILP with the Python API. Use when the user asks about optimization with linear constraints, integer variables, scheduling, resource allocation, facility location, or production planning."
+      "description": "Solve LP, MILP, and QP (beta) with the Python API. Use when the user asks about optimization with linear or quadratic objectives, linear constraints, integer variables, scheduling, resource allocation, facility location, production planning, portfolio optimization, or least squares."
     },
     {
-      "name": "cuopt-lp-milp-api-c",
-      "source": "./skills/cuopt-lp-milp-api-c",
+      "name": "cuopt-numerical-optimization-api-c",
+      "source": "./skills/cuopt-numerical-optimization-api-c",
       "skills": "./",
-      "description": "LP and MILP with cuOpt — C API only. Use when the user is embedding LP/MILP in C/C++."
+      "description": "LP, MILP, and QP (beta) with cuOpt — C API only. Use when the user is embedding LP, MILP, or QP in C/C++."
     },
     {
-      "name": "cuopt-lp-milp-api-cli",
-      "source": "./skills/cuopt-lp-milp-api-cli",
+      "name": "cuopt-numerical-optimization-api-cli",
+      "source": "./skills/cuopt-numerical-optimization-api-cli",
       "skills": "./",
-      "description": "LP and MILP with cuOpt — CLI only (MPS files, cuopt_cli). Use when the user is solving from MPS via command line."
+      "description": "LP, MILP, and QP (beta) with cuOpt — CLI only (MPS files, cuopt_cli). Use when the user is solving LP, MILP, or QP from MPS via command line."
     },
     {
       "name": "routing-formulation",
@@ -80,30 +80,6 @@
       "skills": "./",
       "description": "Vehicle routing (VRP, TSP, PDP) with cuOpt — Python API only. Use when the user is building or solving routing in Python."
     },
-    {
-      "name": "qp-formulation",
-      "source": "./skills/qp-formulation",
-      "skills": "./",
-      "description": "Quadratic Programming (QP) — problem form and constraints. Domain concepts; no API or interface. QP is beta."
-    },
-    {
-      "name": "cuopt-qp-api-python",
-      "source": "./skills/cuopt-qp-api-python",
-      "skills": "./",
-      "description": "Quadratic Programming (QP) with cuOpt — Python API only (beta). Use when the user is building or solving QP in Python."
-    },
-    {
-      "name": "cuopt-qp-api-c",
-      "source": "./skills/cuopt-qp-api-c",
-      "skills": "./",
-      "description": "Quadratic Programming (QP) with cuOpt — C API. Use when the user is embedding QP in C/C++."
-    },
-    {
-      "name": "cuopt-qp-api-cli",
-      "source": "./skills/cuopt-qp-api-cli",
-      "skills": "./",
-      "description": "QP with cuOpt — CLI (e.g. cuopt_cli with QP-capable input). Use when the user is solving QP from the command line."
-    },
     {
       "name": "cuopt-server-common",
       "source": "./skills/cuopt-server-common",

AGENTS.md

@@ -15,22 +15,18 @@ AI agent skills for NVIDIA cuOpt optimization engine. Skills live in **`skills/`
 
 ### Common (concepts only; no API code)
 - `skills/cuopt-installation-common/` — Install: system and environment requirements (concepts only; no install commands or interface)
-- `skills/lp-milp-formulation/` — LP/MILP: concepts + problem parsing (parameters, constraints, decisions, objective)
+- `skills/numerical-optimization-formulation/` — LP / MILP / QP: concepts + problem parsing + common formulation patterns
 - `skills/routing-formulation/` — Routing: VRP, TSP, PDP (problem types, data)
-- `skills/qp-formulation/` — QP: minimize-only, escalate (beta)
 - `skills/cuopt-server-common/` — Server: capabilities, workflow
 
 ### API (implementation; one interface per skill)
 - `skills/cuopt-installation-api-python/`
 - `skills/cuopt-installation-api-c/`
 - `skills/cuopt-installation-developer/` (build from source)
-- `skills/cuopt-lp-milp-api-python/`
-- `skills/cuopt-lp-milp-api-c/`
-- `skills/cuopt-lp-milp-api-cli/`
+- `skills/cuopt-numerical-optimization-api-python/` (LP, MILP, QP)
+- `skills/cuopt-numerical-optimization-api-c/` (LP, MILP, QP)
+- `skills/cuopt-numerical-optimization-api-cli/` (LP, MILP, QP)
 - `skills/cuopt-routing-api-python/`
-- `skills/cuopt-qp-api-python/`
-- `skills/cuopt-qp-api-c/`
-- `skills/cuopt-qp-api-cli/`
 - `skills/cuopt-server-api-python/` (deploy + client)
 
 ## Skill evolution

skills/cuopt-lp-milp-api-c/SKILL.md → skills/cuopt-numerical-optimization-api-c/SKILL.md

@@ -1,10 +1,12 @@
 ---
-name: cuopt-lp-milp-api-c
+name: cuopt-numerical-optimization-api-c
 version: "26.06.00"
-description: LP and MILP with cuOpt — C API only. Use when the user is embedding LP/MILP in C/C++.
+description: LP, MILP, and QP (beta) with cuOpt — C API only. Use when the user is embedding LP, MILP, or QP in C/C++.
 ---
 
-# cuOpt LP/MILP — C API
+# cuOpt Numerical Optimization — C API
+
+Solve LP, MILP, and QP problems via the cuOpt C API. The same library, headers, build pattern, and core calls (`cuOptCreate*Problem`, `cuOptSolve`, `cuOptGetObjectiveValue`) apply across all three; QP extends the API with quadratic-objective creation calls.
 
 Confirm problem type and formulation (variables, objective, constraints, variable types) before coding.
 
@@ -33,6 +35,15 @@ cuOptSolve(problem, settings, &solution);
 cuOptGetObjectiveValue(solution, &obj_value);
 ```
 
+## QP via C API (beta)
+
+QP uses the same library, include/lib paths, and build pattern as LP/MILP — only the problem-creation call differs (it accepts a quadratic objective). See the cuOpt C headers (`cpp/include/cuopt/linear_programming/`) for the QP-specific creation/solve calls and the repo docs at `docs/cuopt/source/cuopt-c/lp-qp-milp/` for end-to-end QP examples.
+
+**QP rules:**
+- **MINIMIZE only** (`CUOPT_MINIMIZE`). To maximize `f(x)`, negate objective coefficients and Q entries.
+- **Continuous variables only** — set `CUOPT_CONTINUOUS` for every variable; integer QP is not supported.
+- **Q should be PSD** for a convex problem.
+
 ## Debugging (MPS / C)
 
 **MPS parsing:** Required sections in order: NAME, ROWS, COLUMNS, RHS, (optional) BOUNDS, ENDATA. Integer markers: `'MARKER'`, `'INTORG'`, `'INTEND'`.
@@ -54,4 +65,4 @@ For **CLI** (MPS files), use `cuopt_cli` and product docs.
 
 ## Escalate
 
-If the problem is quadratic (squared or cross terms in the objective), use QP. For contribution or build-from-source, use product or repo documentation.
+For contribution or build-from-source, use product or repo documentation.

skills/cuopt-lp-milp-api-cli/SKILL.md → skills/cuopt-numerical-optimization-api-cli/SKILL.md

@@ -1,10 +1,12 @@
 ---
-name: cuopt-lp-milp-api-cli
+name: cuopt-numerical-optimization-api-cli
 version: "26.06.00"
-description: LP and MILP with cuOpt — CLI only (MPS files, cuopt_cli). Use when the user is solving from MPS via command line.
+description: LP, MILP, and QP (beta) with cuOpt — CLI only (MPS files, cuopt_cli). Use when the user is solving LP, MILP, or QP from MPS via command line.
 ---
 
-# cuOpt LP/MILP — CLI
+# cuOpt Numerical Optimization — CLI
+
+Solve LP, MILP, and QP problems from MPS files via `cuopt_cli`. The same command, options, and MPS workflow apply across all three; QP uses the standard MPS quadratic-objective extension.
 
 Confirm problem type and formulation (variables, objective, constraints, variable types) before coding.
 
@@ -49,6 +51,14 @@ cuopt_cli problem.mps --presolve --iteration-limit 10000 --method 1
 
 Integer variables: use `'MARKER' 'INTORG'` before and `'MARKER' 'INTEND'` after the integer columns.
 
+## QP via CLI (beta)
+
+Quadratic objectives extend the standard MPS workflow — same `cuopt_cli` command, same options. Check `cuopt_cli --help` for QP-specific flags and the repo docs at `docs/cuopt/source/cuopt-cli/` for the quadratic-objective MPS format.
+
+**QP rules:**
+- **MINIMIZE only.** For maximization, negate the objective coefficients (and Q entries) in the MPS file.
+- **Continuous variables only** — do not mix integer markers with quadratic objectives.
+
 ## Troubleshooting
 
 - **Failed to parse MPS** — Check ENDATA, section order (NAME, ROWS, COLUMNS, RHS, [BOUNDS], ENDATA), integer markers.

skills/cuopt-lp-milp-api-python/SKILL.md → skills/cuopt-numerical-optimization-api-python/SKILL.md

@@ -1,25 +1,34 @@
 ---
-name: cuopt-lp-milp-api-python
+name: cuopt-numerical-optimization-api-python
 version: "26.06.00"
-description: Solve Linear Programming (LP) and Mixed-Integer Linear Programming (MILP) with the Python API. Use when the user asks about optimization with linear constraints, integer variables, scheduling, resource allocation, facility location, or production planning.
+description: Solve Linear Programming (LP), Mixed-Integer Linear Programming (MILP), and Quadratic Programming (QP, beta) with the Python API. Use when the user asks about optimization with linear or quadratic objectives, linear constraints, integer variables, scheduling, resource allocation, facility location, production planning, portfolio optimization, or least squares.
 ---
 
-# cuOpt LP/MILP Skill
+# cuOpt Numerical Optimization Skill (Python)
 
-Model and solve linear and mixed-integer linear programs using NVIDIA cuOpt's GPU-accelerated solver.
+Model and solve LP, MILP, and QP problems using NVIDIA cuOpt's GPU-accelerated solver. The Python API surface (`Problem`, `SolverSettings`, `solve`) is shared across all three problem classes — only the objective form and a few rules change.
 
 ## Before You Start
 
-Use a formulation summary (parameters, constraints, decisions, objective) if available; otherwise ask for decision variables, objective, and constraints. Then confirm **variable types** (see below) and **interface** (Python API recommended).
+Use a formulation summary (parameters, constraints, decisions, objective) if available; otherwise ask for decision variables, objective, and constraints. Then confirm **problem type** (LP / MILP / QP — see below) and **variable types**.
 
-## Choosing LP vs MILP
+## Choosing LP vs MILP vs QP
 
-**Prefer LP (all continuous variables) when the problem allows it.** LP solves faster and has stronger optimality guarantees. Use **MILP** only when the problem logically requires whole numbers or yes/no decisions.
+**Decide from the objective and variables:**
+
+| If the objective is... | And variables are... | Use |
+|---|---|---|
+| Linear (sum of `c_i * x_i`) | All continuous | **LP** |
+| Linear | Some integer or binary | **MILP** |
+| Has squared (`x*x`) or cross (`x*y`) terms | Continuous (integer QP not supported) | **QP** (beta) |
+
+**Prefer LP when the problem allows it.** LP solves faster and has stronger optimality guarantees. Use MILP only when the problem logically requires whole numbers or yes/no decisions. Use QP only when the objective is genuinely quadratic (variance, squared error, kinetic energy).
 
 **Problem types that need extra care:** Multi-period planning and goal programming are easy to misinterpret. Double-check that rates and constraints apply to the right time period or priority level (AGENTS.md: verify understanding before code).
 
 - **Use LP** when every quantity can meaningfully be fractional: flows, proportions, rates, dollars, hours, tonnes of material, etc.
 - **Use MILP** when the problem mentions **counts** of discrete entities, **yes/no** choices, or **either/or** decisions (e.g. open a facility or not, assign a person to a shift, number of trucks).
+- **Use QP** when the objective minimizes variance, squared error, or any expression with `x*x` or `x*y` terms (portfolio optimization, least squares, regularized regression).
 
 ## Integer vs continuous from wording
 
@@ -101,6 +110,42 @@ if problem.Status.name in ["Optimal", "FeasibleFound"]:
     print(f"Production: {production.getValue()}")
 ```
 
+### QP Example (beta — MINIMIZE only)
+
+```python
+from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE
+from cuopt.linear_programming.solver_settings import SolverSettings
+
+# Portfolio variance minimization
+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")
+
+# Quadratic objective (variance) — MUST be MINIMIZE
+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,
+)
+
+# Linear constraints
+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}")
+```
+
+**QP rules:**
+- **MINIMIZE only** — solver rejects MAXIMIZE for quadratic objectives. To maximize `f(x)`, minimize `-f(x)`.
+- **Continuous variables only** — integer QP is not supported.
+- **Q should be PSD** (positive semi-definite) for a convex problem; otherwise the solver may return a non-optimal stationary point.
+- **Beta** — API may evolve; treat as production-capable for typical convex QP but expect occasional changes.
+
+See `resources/qp_examples.md` for least-squares, maximization-workaround, and matrix-form examples.
+
 ## CRITICAL: Status Checking
 
 **Status values use PascalCase, NOT ALL_CAPS:**
@@ -119,6 +164,8 @@ if problem.Status.name == "OPTIMAL":  # Never matches!
 
 **MILP Status Values:** `Optimal`, `FeasibleFound`, `Infeasible`, `Unbounded`, `TimeLimit`, `NoTermination`
 
+**QP Status Values:** Same set as LP. For QP debugging, print `f"Actual status: '{problem.Status.name}'"` and check that `Q` is PSD and variables are reasonably scaled.
+
 ## Common Modeling Patterns
 
 ### Binary Selection
@@ -189,6 +236,8 @@ settings.set_parameter("log_to_console", 1)
 | Unbounded | Missing bounds | Add variable bounds |
 | Slow solve | Large problem | Set time limit, increase gap tolerance |
 | Maximum recursion depth | Building big expr with chained `+` | Use `LinearExpression(vars_list, coeffs_list, constant)` |
+| QP rejected with MAXIMIZE | QP only supports MINIMIZE | Negate the objective: minimize `-f(x)` |
+| QP returns non-optimal | Q not PSD or variables badly scaled | Check Q is PSD; rescale variables to similar magnitudes |
 
 ## Getting Dual Values (LP only)
 
@@ -203,14 +252,17 @@ if problem.Status.name == "Optimal":
 
 All reference models live in this skill's **`assets/`** directory. Use them as reference when building new applications; do not edit them in place.
 
-### Minimal / canonical examples (LP & MILP)
+### Minimal / canonical examples (LP, MILP, QP)
 | Model | Type | Description |
 |-------|------|-------------|
 | [lp_basic](assets/lp_basic/) | LP | Minimal LP: variables, constraints, objective, solve |
 | [lp_duals](assets/lp_duals/) | LP | Dual values and reduced costs |
 | [lp_warmstart](assets/lp_warmstart/) | LP | PDLP warmstart for similar problems |
 | [milp_basic](assets/milp_basic/) | MILP | Minimal MIP; includes incumbent callback example |
 | [milp_production_planning](assets/milp_production_planning/) | MILP | Production planning with resource constraints |
+| [portfolio](assets/portfolio/) | QP | Minimize portfolio variance; budget and min-return constraints |
+| [least_squares](assets/least_squares/) | QP | Minimize (x-3)² + (y-4)² (closest point) |
+| [maximization_workaround](assets/maximization_workaround/) | QP | Maximize quadratic via minimize -f(x) |
 
 ### Other reference
 | Model | Type | Description |

skills/cuopt-numerical-optimization-api-python/assets/README.md

@@ -0,0 +1,17 @@
+# Assets — reference models
+
+LP, MILP, and QP reference implementations. Use as reference when building new applications; do not edit in place.
+
+| Model | Type |
+|-------|------|
+| lp_basic | LP |
+| lp_duals | LP |
+| lp_warmstart | LP |
+| milp_basic | MILP |
+| milp_production_planning | MILP |
+| mps_solver | LP/MILP |
+| portfolio | QP |
+| least_squares | QP |
+| maximization_workaround | QP |
+
+**Run:** From each subdir, `python model.py`. QP is **beta** and supports **MINIMIZE** only. See [resources/qp_examples.md](../resources/qp_examples.md) for additional QP examples.

skills/cuopt-lp-milp-api-python/evals/SOURCES.md → skills/cuopt-numerical-optimization-api-python/evals/SOURCES.md

@@ -1,6 +1,6 @@
 # Sources
 
-Eval prompts in `evals.json` for the `cuopt-lp-milp-api-python` skill are
+Eval prompts in `evals.json` for the `cuopt-numerical-optimization-api-python` skill are
 adapted from the **OptiGuide / OptiMind IndustryOR** dataset:
 
 - Repository: [microsoft/OptiGuide](https://github.com/microsoft/OptiGuide)