@areb0s/scip.js 1.2.3 → 1.2.5

package/dist/types.d.ts

@@ -45,6 +45,12 @@ export interface SolveOptions extends InitOptions {
   verbose?: boolean;
   /** Additional SCIP parameters */
   parameters?: Record<string, string | number | boolean>;
+  /** 
+   * Initial solution hint for warm start
+   * Object mapping variable names to values
+   * @example { "x$sun#0": 1, "x$moon#5": 1 }
+   */
+  initialSolution?: Record<string, number> | null;
 }
 
 /**
@@ -166,6 +172,170 @@ export interface SCIPModule {
 declare const SCIP: SCIPModule;
 export default SCIP;
 
+// ============================================
+// Callback API Types
+// ============================================
+
+/**
+ * Callback API solution status (same values, different export)
+ */
+export const ApiStatus: typeof Status;
+
+/**
+ * Callback API solver options (extends base options with callback features)
+ */
+export interface CallbackSolveOptions extends SolveOptions {
+  /** Initial solution hint for warm start */
+  initialSolution?: Record<string, number>;
+  /** Cutoff bound - prune nodes with worse objective */
+  cutoff?: number;
+}
+
+/**
+ * Node callback data
+ */
+export interface NodeCallbackData {
+  /** Current dual (lower) bound */
+  dualBound: number;
+  /** Current primal (upper) bound */
+  primalBound: number;
+  /** Number of nodes processed */
+  nodes: number;
+}
+
+/**
+ * Callback API statistics (extended)
+ */
+export interface CallbackStatistics {
+  /** Solving time in seconds */
+  solvingTime: number;
+  /** Number of branch-and-bound nodes */
+  nodes: number;
+  /** Final optimality gap */
+  gap: number;
+  /** Final dual bound */
+  dualBound: number;
+  /** Final primal bound */
+  primalBound: number;
+}
+
+/**
+ * Callback API solution result
+ */
+export interface CallbackSolution {
+  /** Solution status */
+  status: StatusType;
+  /** Objective function value */
+  objective: number;
+  /** Variable values */
+  variables: Record<string, number>;
+  /** Solver statistics */
+  statistics: CallbackStatistics;
+  /** Error message (if status is ERROR) */
+  error?: string;
+}
+
+/**
+ * Incumbent callback function type
+ * Called when a new best solution is found during solving
+ */
+export type IncumbentCallback = (objectiveValue: number) => void;
+
+/**
+ * Node callback function type
+ * Called when a node is selected for processing
+ */
+export type NodeCallback = (data: NodeCallbackData) => void;
+
+/**
+ * SCIP API class with callback support
+ * 
+ * @example
+ * ```typescript
+ * import { SCIPApi } from 'scip.js';
+ * 
+ * const scip = new SCIPApi();
+ * await scip.init();
+ * 
+ * // Set callback for new incumbent solutions
+ * scip.onIncumbent((objValue) => {
+ *   console.log('New solution found:', objValue);
+ *   // Could update cutoff here for custom pruning
+ * });
+ * 
+ * const result = await scip.solve(problemZPL, {
+ *   format: 'zpl',
+ *   initialSolution: { x: 1, y: 0 },
+ *   cutoff: 100
+ * });
+ * 
+ * scip.destroy();
+ * ```
+ */
+export class SCIPApi {
+  constructor();
+  
+  /**
+   * Initialize SCIP API module
+   * @param options - Initialization options
+   */
+  init(options?: InitOptions): Promise<void>;
+  
+  /**
+   * Set callback for new incumbent solutions
+   * Called whenever SCIP finds a new best solution
+   * @param callback - Function receiving the objective value
+   */
+  onIncumbent(callback: IncumbentCallback | null): void;
+  
+  /**
+   * Set callback for node processing (progress tracking)
+   * @param callback - Function receiving dual/primal bounds and node count
+   */
+  onNode(callback: NodeCallback | null): void;
+  
+  /**
+   * Solve an optimization problem
+   * @param problem - Problem definition string
+   * @param options - Solver options including callbacks
+   * @returns Solution with statistics
+   */
+  solve(problem: string, options?: CallbackSolveOptions): Promise<CallbackSolution>;
+  
+  /**
+   * Free SCIP resources
+   * Call this when done to release memory
+   */
+  destroy(): void;
+}
+
+/**
+ * Convenience function to solve with callbacks
+ * Creates SCIPApi, solves, and destroys automatically
+ * 
+ * @example
+ * ```typescript
+ * const result = await solveWithCallbacks(problem, {
+ *   format: 'zpl',
+ *   onIncumbent: (obj) => console.log('New best:', obj),
+ *   onNode: (data) => console.log('Progress:', data.nodes)
+ * });
+ * ```
+ */
+export function solveWithCallbacks(
+  problem: string, 
+  options?: CallbackSolveOptions & {
+    onIncumbent?: IncumbentCallback;
+    onNode?: NodeCallback;
+  }
+): Promise<CallbackSolution>;
+
+/**
+ * Create a callback-enabled solver instance
+ * Use when you need incumbent callbacks for custom pruning logic
+ */
+export function createCallbackSolver(options?: InitOptions): Promise<SCIPApi>;
+
 // Global declaration for CDN usage
 declare global {
   interface Window {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@areb0s/scip.js",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "SCIP Optimization Solver compiled to WebAssembly - LP, MIP, and MINLP support",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",