Created optimizeMIP.ts (markdown)

optimizeMIP.ts.md

@@ -0,0 +1,152 @@
+# Documentation: `optimizeMIP.ts`
+
+This document provides a detailed explanation of the TypeScript file `optimizeMIP.ts`. The purpose of this file is to handle HTTP POST requests and process Mixed Integer Programming (MIP) optimization problems using the GLPK (GNU Linear Programming Kit) JavaScript library.
+
+## Index
+
+1. [Introduction](#introduction)
+2. [Dependencies](#dependencies)
+3. [Data Structures](#data-structures)
+4. [Functionality](#functionality)
+5. [Error Handling](#error-handling)
+6. [Handling HTTP Methods](#handling-http-methods)
+
+---
+
+## Introduction
+
+The `optimizeMIP.ts` file defines an API endpoint handler function which processes optimization problems using the GLPK library. It is designed to work with the Next.js framework's API routes feature, providing a way to solve mathematical optimization problems via HTTP requests.
+
+## Dependencies
+
+The file imports essential modules and libraries as follows:
+
+- `NextApiRequest` and `NextApiResponse` from `next`: These are types used to define the request and response objects in a Next.js API route.
+- `GLPK` from `glpk.js`: This is the JavaScript interface for the GLPK library, used for solving linear programming (LP) and mixed integer programming (MIP) problems.
+
+```typescript
+import { NextApiRequest, NextApiResponse } from 'next';
+import GLPK from 'glpk.js';
+```
+
+## Data Structures
+
+The file defines several interfaces to structure the input data for the optimization problem:
+
+- **Variable**: Represents a variable with a name and a coefficient.
+  
+  ```typescript
+  interface Variable {
+      name: string;
+      coef: number;
+  }
+  ```
+
+- **Constraint**: Defines a constraint with a name, an array of variables, and bounds (lower and upper).
+  
+  ```typescript
+  interface Constraint {
+      name: string;
+      vars: Variable[];
+      bnds: {
+          lb: number;
+          ub: number;
+      };
+  }
+  ```
+
+- **Objective**: Represents the objective of the optimization, specifying the direction (either 'max' or 'min') and an array of variables.
+  
+  ```typescript
+  interface Objective {
+      direction: 'max' | 'min';
+      vars: Variable[];
+  }
+  ```
+
+- **RequestBody**: Combines the objective, constraints, and optional bounds into a single interface to represent the structure of the request body.
+  
+  ```typescript
+  interface RequestBody {
+      objective: Objective;
+      constraints: Constraint[];
+      bounds?: any;
+  }
+  ```
+
+## Functionality
+
+The core functionality is encapsulated within the `handler` function, which processes POST requests to solve an optimization problem:
+
+1. **Request Method Check**: Ensures the handler only processes POST requests.
+   
+   ```typescript
+   if (req.method === 'POST') {
+   ```
+
+2. **Extracting and Validating Input**: The function extracts the `objective`, `constraints`, and `bounds` from the request body, validating the presence of `objective` and `constraints`.
+   
+   ```typescript
+   const { objective, constraints, bounds }: RequestBody = req.body;
+   if (!objective || !constraints) {
+       return res.status(400).json({ message: 'Invalid input data...' });
+   }
+   ```
+
+3. **GLPK Problem Setup**: Initializes the GLPK solver and sets up the optimization problem.
+   
+   ```typescript
+   const glpk = await GLPK();
+   const problem = {
+       name: 'MIP',
+       objective: { ... },
+       subjectTo: constraints.map((c: Constraint) => ({ ... })),
+       binaries: objective.vars.map((v: Variable) => v.name),
+       generals: objective.vars.map((v: Variable) => v.name)
+   };
+   ```
+
+4. **Solving the Problem**: Uses the `glpk.solve` method to solve the optimization problem with specified options.
+   
+   ```typescript
+   const result = glpk.solve(problem, options);
+   res.status(200).json({ result });
+   ```
+
+## Error Handling
+
+The function includes robust error handling to manage any issues during the optimization process:
+
+- **Try-Catch Block**: Wraps the GLPK operations to catch any errors that occur.
+  
+  ```typescript
+  try {
+      // GLPK operations
+  } catch (error: unknown) {
+      // Error handling
+  }
+  ```
+
+- **Type Assertion for Errors**: Uses type assertions to access properties of the error object for logging and response purposes.
+
+  ```typescript
+  if (error instanceof Error) {
+      console.error('Error processing optimization:', error);
+      res.status(500).json({ message: 'Error processing optimization', error: error.message });
+  } else {
+      console.error('Unknown error:', error);
+      res.status(500).json({ message: 'Error processing optimization', error: 'Unknown error' });
+  }
+  ```
+
+## Handling HTTP Methods
+
+The function is designed to handle only POST requests. If a different HTTP method is used, the function returns a 405 status code indicating that the method is not allowed.
+
+```typescript
+else {
+    res.status(405).json({ message: 'Only POST method is allowed' });
+}
+```
+
+