Merge pull request #43 from wspringer/feature/quadratic-objectives-26

Add support for quadratic objectives in convex QP problems

Author: wspringer

.changeset/add_quadratic_objective_support.md

@@ -0,0 +1,7 @@
+---
+default: minor
+---
+
+# Add quadratic objective support for convex QP problems
+
+Added support for quadratic programming (QP) problems, allowing optimization of quadratic objectives of the form `minimize c^T x + 0.5 x^T Q x`. The quadratic matrix Q can be specified in either dense or sparse format, and must be positive semidefinite for convexity. This enhancement enables solving portfolio optimization, least squares, and other convex QP problems. Note that mixed-integer quadratic programming (MIQP) is not supported - only continuous variables are allowed with quadratic objectives.

README.md

@@ -12,6 +12,7 @@ This MCP server exposes the HiGHS optimization solver through a standardized int
 
 - Linear Programming (LP) problems
 - Mixed-Integer Programming (MIP) problems
+- Quadratic Programming (QP) problems for convex objectives
 - Binary and integer variable constraints
 - Multi-objective optimization
 
@@ -91,7 +92,19 @@ The server provides a single tool: `optimize-mip-lp-tool`
   problem: {
     sense: 'minimize' | 'maximize',
     objective: {
-      linear: number[]  // Coefficients for each variable
+      linear?: number[],  // Linear coefficients (optional if quadratic is provided)
+      quadratic?: {       // Quadratic terms for convex QP (optional)
+        // Dense format:
+        dense?: number[][]  // Symmetric positive semidefinite matrix Q
+        
+        // OR Sparse format:
+        sparse?: {
+          rows: number[],     // Row indices (0-indexed)
+          cols: number[],     // Column indices (0-indexed)
+          values: number[],   // Values of Q matrix
+          shape: [number, number]  // [num_variables, num_variables]
+        }
+      }
     },
     variables: Array<{
       name?: string,        // Variable name (optional, defaults to x1, x2, etc.)
@@ -174,6 +187,13 @@ The server provides a single tool: `optimize-mip-lp-tool`
 }
 ```
 
+### Notes on Quadratic Programming (QP)
+
+- **Convex QP only**: The quadratic matrix Q must be positive semidefinite
+- **Continuous variables only**: Integer/binary variables are not supported with quadratic objectives (no MIQP)
+- **Format**: Objective function is: minimize c^T x + 0.5 x^T Q x
+- **Matrix specification**: When specifying Q, values should be doubled to account for the 0.5 factor
+
 ## Use Cases
 
 ### 1. Production Planning
@@ -266,7 +286,42 @@ Optimize investment allocation with risk constraints:
 }
 ```
 
-### 4. Resource Allocation
+### 4. Portfolio Optimization with Risk (Quadratic Programming)
+
+Minimize portfolio risk (variance) while achieving target return:
+
+```javascript
+{
+  problem: {
+    sense: 'minimize',
+    objective: {
+      // Quadratic: minimize portfolio variance (risk)
+      quadratic: {
+        dense: [  // Covariance matrix (×2 for 0.5 factor)
+          [0.2, 0.04, 0.02],
+          [0.04, 0.1, 0.04], 
+          [0.02, 0.04, 0.16]
+        ]
+      }
+    },
+    variables: [
+      { name: 'Stock_A', lb: 0 },
+      { name: 'Stock_B', lb: 0 },
+      { name: 'Stock_C', lb: 0 }
+    ],
+    constraints: {
+      dense: [
+        [1, 1, 1],              // Sum of weights = 1
+        [0.1, 0.12, 0.08]       // Expected return >= target
+      ],
+      sense: ['=', '>='],
+      rhs: [1, 0.1]  // 100% allocation, min 10% return
+    }
+  }
+}
+```
+
+### 5. Resource Allocation
 
 Optimize resource allocation across projects with integer constraints:
 

src/decode.ts

@@ -81,8 +81,11 @@ export function decode(
     const solutionValues: number[] = [];
     const dualValues: number[] = [];
 
+    // Determine number of variables
+    const numVars = problem.variables.length;
+
     // Iterate through variables in the same order as defined in the problem
-    for (let i = 0; i < problem.objective.linear.length; i++) {
+    for (let i = 0; i < numVars; i++) {
       // Use custom name if provided, otherwise default to x1, x2, etc.
       const varName = problem.variables[i].name || `x${i + 1}`;
       const column = result.Columns[varName];

src/encode.ts

@@ -119,16 +119,84 @@ function formatObjective(
   const terms: string[] = [];
   let hasTerms = false;
 
-  for (let i = 0; i < objective.linear.length; i++) {
-    const coeff = objective.linear[i];
-    const varName = variables[i].name || `x${i + 1}`;
-    const term = formatCoefficient(coeff, varName, !hasTerms);
-    if (term) {
-      terms.push(term);
-      hasTerms = true;
+  // Add linear terms
+  if (objective.linear) {
+    for (let i = 0; i < objective.linear.length; i++) {
+      const coeff = objective.linear[i];
+      const varName = variables[i].name || `x${i + 1}`;
+      const term = formatCoefficient(coeff, varName, !hasTerms);
+      if (term) {
+        terms.push(term);
+        hasTerms = true;
+      }
+    }
+  }
+
+  // Add quadratic terms if present
+  if (objective.quadratic) {
+    const quadTerms: string[] = [];
+
+    if ("sparse" in objective.quadratic) {
+      // Process sparse format
+      const { rows, cols, values } = objective.quadratic.sparse;
+      for (let idx = 0; idx < values.length; idx++) {
+        const i = rows[idx];
+        const j = cols[idx];
+        const value = values[idx];
+
+        if (value !== 0) {
+          const varI = variables[i].name || `x${i + 1}`;
+          const varJ = variables[j].name || `x${j + 1}`;
+
+          if (i === j) {
+            // Diagonal term: value * xi^2
+            quadTerms.push(value === 1 ? `${varI}^2` : `${value} ${varI}^2`);
+          } else {
+            // Off-diagonal term: value * xi * xj
+            // Note: HiGHS expects symmetric matrix, so we only include each term once
+            quadTerms.push(value === 1 ? `${varI} * ${varJ}` : `${value} ${varI} * ${varJ}`);
+          }
+        }
+      }
+    } else if ("dense" in objective.quadratic) {
+      // Process dense format
+      const matrix = objective.quadratic.dense;
+      for (let i = 0; i < matrix.length; i++) {
+        for (let j = i; j < matrix[i].length; j++) {
+          const value = i === j ? matrix[i][j] : matrix[i][j] + matrix[j][i]; // Sum symmetric entries
+
+          if (value !== 0) {
+            const varI = variables[i].name || `x${i + 1}`;
+            const varJ = variables[j].name || `x${j + 1}`;
+
+            if (i === j) {
+              // Diagonal term: value * xi^2
+              quadTerms.push(value === 1 ? `${varI}^2` : `${value} ${varI}^2`);
+            } else {
+              // Off-diagonal term: value * xi * xj
+              quadTerms.push(value === 1 ? `${varI} * ${varJ}` : `${value} ${varI} * ${varJ}`);
+            }
+          }
+        }
+      }
+    }
+
+    // Add quadratic terms in HiGHS format: [ quadratic_terms ] / 2
+    if (quadTerms.length > 0) {
+      if (hasTerms) {
+        terms.push("+ [ " + quadTerms.join(" + ") + " ] / 2");
+      } else {
+        terms.push("[ " + quadTerms.join(" + ") + " ] / 2");
+        hasTerms = true;
+      }
     }
   }
 
+  // If no terms at all, add a zero
+  if (!hasTerms) {
+    terms.push("0");
+  }
+
   result += terms.join(" ") + "\n";
   return result;
 }

src/index.test.ts

@@ -152,6 +152,9 @@ describe("HiGHS MCP Server", () => {
       expect(response.result.tools).toHaveLength(1);
       expect(response.result.tools[0].name).toBe("optimize-mip-lp-tool");
       expect(response.result.tools[0].description).toContain("HiGHS solver");
+      expect(response.result.tools[0].description).toContain("quadratic programming (QP)");
+      expect(response.result.tools[0].description).toContain("convex quadratic objectives");
+      expect(response.result.tools[0].description).toContain("continuous variables (no MIQP)");
     });
 
     it("should include comprehensive schema documentation", async () => {
@@ -178,10 +181,10 @@ describe("HiGHS MCP Server", () => {
       expect(constraintsSchema.anyOf).toBeDefined();
       expect(constraintsSchema.anyOf).toHaveLength(2);
 
-      // Check that minimum constraints are properly exposed
-      expect(
-        tool.inputSchema.properties.problem.properties.objective.properties.linear.minItems,
-      ).toBe(1);
+      // Check that objective supports both linear and quadratic
+      const objectiveSchema = tool.inputSchema.properties.problem.properties.objective;
+      expect(objectiveSchema.properties.linear).toBeDefined();
+      expect(objectiveSchema.properties.quadratic).toBeDefined();
     });
   });
 

src/index.ts

@@ -34,7 +34,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: TOOL_NAME,
       description:
-        "Solve linear programming (LP) or mixed-integer programming (MIP) problems using HiGHS solver",
+        "Solve linear programming (LP), mixed-integer programming (MIP), or quadratic programming (QP) problems using HiGHS solver. " +
+        "QP support includes convex quadratic objectives (minimize c^T x + 0.5 x^T Q x) where Q must be positive semidefinite. " +
+        "Limitations: QP only supports continuous variables (no MIQP), and when specifying Q matrix values should be doubled to account for the 0.5 factor.",
       inputSchema: zodToJsonSchema(OptimizationArgsSchema, {
         $refStrategy: "none",
       }),

src/schemas.ts

@@ -22,15 +22,88 @@ export const CompactVariableSchema = z.object({
   ),
 });
 
-export const ObjectiveSchema = z.object({
-  linear: z
-    .array(z.number())
-    .min(1, "At least one objective coefficient is required")
-    .describe(
-      "Linear coefficients for each variable. The length of this array defines the number of variables in the problem. All other arrays (constraint matrix rows, variable bounds, types, and names) must match this length.",
-    ),
+// Quadratic matrix schema (reusing SparseMatrixSchema pattern)
+const QuadraticMatrixSchema = z.object({
+  rows: z
+    .array(z.number().int().nonnegative())
+    .describe("Row indices of quadratic matrix (0-indexed)"),
+  cols: z
+    .array(z.number().int().nonnegative())
+    .describe("Column indices of quadratic matrix (0-indexed)"),
+  values: z.array(z.number()).describe("Values of quadratic matrix Q"),
+  shape: z
+    .tuple([z.number().int().positive(), z.number().int().positive()])
+    .describe("[num_variables, num_variables] dimensions of Q matrix"),
 });
 
+// Dense quadratic schema
+const DenseQuadraticSchema = z.object({
+  dense: z.array(z.array(z.number())).describe("Dense symmetric matrix Q for quadratic objective"),
+});
+
+// Sparse quadratic schema
+const SparseQuadraticSchema = z.object({
+  sparse: QuadraticMatrixSchema.describe(
+    "Sparse matrix Q in COO (Coordinate) format - only specify non-zero values with their positions",
+  ),
+});
+
+// Union of dense and sparse quadratic formats
+const QuadraticObjectiveSchema = z
+  .union([DenseQuadraticSchema, SparseQuadraticSchema])
+  .refine((data) => {
+    if ("dense" in data) {
+      const matrix = data.dense;
+      return (
+        matrix.length > 0 && // Non-empty
+        matrix.length === matrix[0].length && // Square matrix
+        matrix.every((row) => row.length === matrix.length)
+      ); // All rows same length
+    } else {
+      const sparse = data.sparse;
+      return (
+        sparse.shape[0] === sparse.shape[1] && // Must be square
+        sparse.rows.length === sparse.cols.length && // Array lengths match
+        sparse.rows.length === sparse.values.length && // Array lengths match
+        sparse.rows.every((r) => r < sparse.shape[0]) && // Row indices in bounds
+        sparse.cols.every((c) => c < sparse.shape[1])
+      ); // Col indices in bounds
+    }
+  }, "Quadratic matrix must be square with valid dimensions");
+
+export const ObjectiveSchema = z
+  .object({
+    linear: z
+      .array(z.number())
+      .optional()
+      .describe(
+        "Linear coefficients for each variable (c in: minimize c^T x + 0.5 x^T Q x). If not provided but quadratic is present, defaults to zeros. The length defines the number of variables when quadratic is not present.",
+      ),
+    quadratic: QuadraticObjectiveSchema.optional().describe(
+      "Quadratic terms Q for convex QP (minimize 0.5 x^T Q x + c^T x). Q must be positive semidefinite. Supports both sparse and dense formats.",
+    ),
+  })
+  .refine(
+    (data) => {
+      // At least one of linear or quadratic must be present
+      if (!data.linear && !data.quadratic) {
+        return false;
+      }
+      // If both are present, check dimensions match
+      if (data.linear && data.quadratic) {
+        const numVars = data.linear.length;
+        const qSize =
+          "dense" in data.quadratic ? data.quadratic.dense.length : data.quadratic.sparse.shape[0];
+        return numVars === qSize;
+      }
+      return true;
+    },
+    {
+      message:
+        "At least one of 'linear' or 'quadratic' must be provided. When both are present, dimensions must match.",
+    },
+  );
+
 // Sparse matrix schema
 export const SparseMatrixSchema = z.object({
   rows: z
@@ -131,8 +204,35 @@ export const ProblemSchema = z
     ),
   })
   .superRefine((data, ctx) => {
-    // Ensure matrix dimensions are consistent
-    const numVars = data.objective.linear.length;
+    // Determine number of variables from objective
+    let numVars: number;
+    if (data.objective.linear) {
+      numVars = data.objective.linear.length;
+    } else if (data.objective.quadratic) {
+      numVars =
+        "dense" in data.objective.quadratic
+          ? data.objective.quadratic.dense.length
+          : data.objective.quadratic.sparse.shape[0];
+    } else {
+      // This should be caught by ObjectiveSchema refinement, but just in case
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Cannot determine number of variables from objective",
+        path: ["objective"],
+      });
+      return;
+    }
+
+    // Check for QP with integer variables
+    if (data.objective.quadratic && data.variables.some((v) => v.type && v.type !== "cont")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "Quadratic objectives are not supported with integer or binary variables (MIQP not supported by HiGHS)",
+        path: ["objective", "quadratic"],
+      });
+    }
+
     let numConstraints: number;
 
     // Handle both dense and sparse formats