@elaraai/east-py-datascience 0.0.2-beta.8 → 0.0.2-beta.80

package/dist/src/optimization/optimization.js

@@ -0,0 +1,257 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Iterative coordinate descent optimization for discrete combinatorial problems.
+ *
+ * Provides element-wise optimization over vectors of discrete integer values.
+ * Each element is independently optimized by trying all candidate values
+ * while holding other elements fixed. Multi-start sampling improves
+ * exploration of the search space.
+ *
+ * Ported from the Julia IterativeDecisionAlgorithm (ArrayParameterSpace branch).
+ *
+ * @packageDocumentation
+ */
+import { East, StructType, VariantType, OptionType, ArrayType, VectorType, IntegerType, BooleanType, FloatType, NullType, FunctionType, } from "@elaraai/east";
+// ============================================================================
+// Type Definitions
+// ============================================================================
+/** Parameter vector: Vector<Integer> */
+export const ParameterVectorType = VectorType(IntegerType);
+/** Objective function: Vector<Integer> -> Float */
+export const IterativeObjectiveType = FunctionType([ParameterVectorType], FloatType);
+/** Per-element candidate spaces: Array<Vector<Integer>> */
+export const ParameterSpacesType = ArrayType(ParameterVectorType);
+/**
+ * Initial value strategy for parameters.
+ *
+ * - `first`: Use the first candidate value from each space
+ * - `random`: Randomly select from each space
+ */
+export const InitialStrategyType = VariantType({
+    first: NullType,
+    random: NullType,
+});
+/**
+ * Evaluation order for candidate values within each element's space.
+ *
+ * - `sequential`: Try candidates in the order they appear
+ * - `random`: Shuffle candidates before trying
+ */
+export const EvaluationOrderType = VariantType({
+    sequential: NullType,
+    random: NullType,
+});
+/**
+ * Optimization mode.
+ *
+ * - `coordinate`: Standard coordinate descent — optimize each element independently (default)
+ * - `swap`: Swap-based moves — swap pairs of elements, preserving valid permutations
+ */
+export const ModeType = VariantType({
+    coordinate: NullType,
+    swap: NullType,
+});
+/**
+ * Configuration for iterative optimization.
+ *
+ * All fields are optional with sensible defaults.
+ */
+export const IterativeConfigType = StructType({
+    /** Maximum coordinate descent iterations per sample (default: 100) */
+    iterations: OptionType(IntegerType),
+    /** Number of independent restarts (default: 1) */
+    samples: OptionType(IntegerType),
+    /** How to initialize parameter values (default: first) */
+    initial: OptionType(InitialStrategyType),
+    /** Order to evaluate candidates (default: sequential) */
+    order: OptionType(EvaluationOrderType),
+    /** Random seed for reproducibility */
+    random_state: OptionType(IntegerType),
+    /** Optimization mode: coordinate (default) or swap for permutations */
+    mode: OptionType(ModeType),
+});
+/**
+ * Result of iterative optimization.
+ */
+export const IterativeResultType = StructType({
+    /** Best parameter values found */
+    best_parameters: ParameterVectorType,
+    /** Objective value at best parameters */
+    best_objective: FloatType,
+    /** Total coordinate descent iterations across all samples */
+    iterations: IntegerType,
+    /** Total number of objective evaluations */
+    evaluations: IntegerType,
+    /** Whether optimization succeeded */
+    success: BooleanType,
+});
+// ============================================================================
+// Platform Functions
+// ============================================================================
+/**
+ * Iterative optimization over integer parameter vectors.
+ *
+ * Maximizes an objective function over a vector of discrete integer parameters.
+ * Each parameter position has its own set of candidate values (vector).
+ *
+ * Two modes are available:
+ * - **coordinate** (default): Coordinate descent — optimizes each element independently
+ *   by trying all candidate values while holding others fixed. Best for assignment problems
+ *   where each position can take any value independently.
+ * - **swap**: Swap-based moves — swaps pairs of elements, preserving valid permutations.
+ *   Use this for permutation problems (scheduling, ordering) where each value must appear
+ *   exactly once.
+ *
+ * @example Coordinate mode (assignment)
+ * ```ts
+ * const config = $.let({
+ *     iterations: variant('some', 10n),
+ *     samples: variant('some', 3n),
+ *     initial: variant('some', variant('random', null)),
+ *     order: variant('some', variant('sequential', null)),
+ *     random_state: variant('some', 42n),
+ *     mode: variant('none', null), // coordinate is the default
+ * });
+ * const result = $.let(Optimization.iterative(objective, spaces, config));
+ * ```
+ *
+ * @example Swap mode (permutation)
+ * ```ts
+ * const config = $.let({
+ *     iterations: variant('some', 50n),
+ *     samples: variant('some', 10n),
+ *     initial: variant('some', variant('random', null)),
+ *     order: variant('some', variant('random', null)),
+ *     random_state: variant('some', 42n),
+ *     mode: variant('some', variant('swap', null)),
+ * });
+ * const result = $.let(Optimization.iterative(objective, spaces, config));
+ * ```
+ */
+export const optimization_iterative = East.platform("optimization_iterative", [
+    IterativeObjectiveType, // objective: Vector<Integer> -> Float
+    ParameterSpacesType, // parameter_spaces: Array<Vector<Integer>>
+    IterativeConfigType, // config
+], IterativeResultType);
+// ============================================================================
+// Grouped Export
+// ============================================================================
+/**
+ * Type definitions for iterative optimization.
+ */
+export const OptimizationTypes = {
+    /** Parameter vector type */
+    ParameterVectorType,
+    /** Objective function type */
+    ObjectiveType: IterativeObjectiveType,
+    /** Parameter spaces type */
+    SpacesType: ParameterSpacesType,
+    /** Initial value strategy variant */
+    InitialStrategyType,
+    /** Evaluation order variant */
+    EvaluationOrderType,
+    /** Optimization mode variant */
+    ModeType,
+    /** Configuration type */
+    ConfigType: IterativeConfigType,
+    /** Result type */
+    ResultType: IterativeResultType,
+};
+/**
+ * Iterative optimization for discrete combinatorial problems.
+ *
+ * Supports two modes:
+ * - **coordinate** (default): Element-wise coordinate descent. Best for
+ *   assignment problems where positions are independent.
+ * - **swap**: Pair-wise swap moves preserving permutations. Best for
+ *   scheduling/ordering where each value must appear exactly once.
+ *
+ * Use cases:
+ * - Task-worker assignment (coordinate mode)
+ * - Scheduling and ordering (swap mode)
+ * - Combinatorial selection problems
+ * - Any discrete optimization with per-element candidate sets
+ */
+export const Optimization = {
+    /**
+     * Iterative optimization over integer parameter vectors.
+     *
+     * `Optimization.iterative(objective, spaces, config)`
+     *
+     * @example Coordinate mode — task-worker assignment
+     * ```ts
+     * // 3 tasks, 2 workers. Maximize total skill match.
+     * const skill = $.let([[3.0, 1.0], [1.0, 3.0], [2.0, 2.0]]);
+     * const objective = East.function(
+     *     [VectorType(IntegerType)], FloatType,
+     *     ($, assignments) => {
+     *         const total = $.let(0.0);
+     *         $.for(East.Array.range(0n, East.value(3n)), ($, i) => {
+     *             $.assign(total, total.add(skill.get(i).get(assignments.get(i))));
+     *         });
+     *         return $.return(total);
+     *     }
+     * );
+     * const spaces = $.let([
+     *     new BigInt64Array([0n, 1n]),
+     *     new BigInt64Array([0n, 1n]),
+     *     new BigInt64Array([0n, 1n]),
+     * ]);
+     * const config = $.let({
+     *     iterations: variant('some', 10n),
+     *     samples: variant('some', 3n),
+     *     initial: variant('some', variant('random', null)),
+     *     order: variant('some', variant('sequential', null)),
+     *     random_state: variant('some', 42n),
+     *     mode: variant('none', null),
+     * });
+     * const result = $.let(Optimization.iterative(objective, spaces, config));
+     * // result.best_objective = 8.0 (task 0→worker 0, task 1→worker 1, task 2→either)
+     * ```
+     *
+     * @example Swap mode — scheduling permutation
+     * ```ts
+     * // 4 jobs: find execution order minimizing weighted completion time.
+     * const durations = $.let([10.0, 5.0, 20.0, 3.0]);
+     * const values = $.let([1.0, 8.0, 2.0, 10.0]);
+     * const objective = East.function(
+     *     [VectorType(IntegerType)], FloatType,
+     *     ($, perm) => {
+     *         const cum = $.let(0.0);
+     *         const total = $.let(0.0);
+     *         $.for(East.Array.range(0n, East.value(4n)), ($, i) => {
+     *             const idx = $.let(perm.get(i));
+     *             $.assign(cum, cum.add(durations.get(idx)));
+     *             $.assign(total, total.add(values.get(idx).multiply(cum)));
+     *         });
+     *         return $.return(total.negate());
+     *     }
+     * );
+     * const spaces = $.let([
+     *     new BigInt64Array([0n, 1n, 2n, 3n]),
+     *     new BigInt64Array([0n, 1n, 2n, 3n]),
+     *     new BigInt64Array([0n, 1n, 2n, 3n]),
+     *     new BigInt64Array([0n, 1n, 2n, 3n]),
+     * ]);
+     * const config = $.let({
+     *     iterations: variant('some', 50n),
+     *     samples: variant('some', 10n),
+     *     initial: variant('some', variant('random', null)),
+     *     order: variant('some', variant('random', null)),
+     *     random_state: variant('some', 42n),
+     *     mode: variant('some', variant('swap', null)),
+     * });
+     * const result = $.let(Optimization.iterative(objective, spaces, config));
+     * // result.best_objective = -188.0 (optimal WSPT order)
+     * ```
+     */
+    iterative: optimization_iterative,
+    /**
+     * Type definitions for optimization functions.
+     */
+    Types: OptimizationTypes,
+};
+//# sourceMappingURL=optimization.js.map

package/dist/src/optimization/optimization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimization.js","sourceRoot":"","sources":["../../../src/optimization/optimization.ts"],"names":[],"mappings":"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"}