@elaraai/east-py-datascience 0.0.2-beta.84 → 1.0.0

package/dist/src/optimization/optimization.d.ts

@@ -19,6 +19,8 @@ import { StructType, VariantType, OptionType, ArrayType, VectorType, IntegerType
 export declare const ParameterVectorType: VectorType<IntegerType>;
 /** Objective function: Vector<Integer> -> Float */
 export declare const IterativeObjectiveType: FunctionType<[VectorType<IntegerType>], FloatType>;
+/** Per-element contribution function: (Vector<Integer>, Integer) -> Float */
+export declare const ElementObjectiveType: FunctionType<[VectorType<IntegerType>, IntegerType], FloatType>;
 /** Per-element candidate spaces: Array<Vector<Integer>> */
 export declare const ParameterSpacesType: ArrayType<VectorType<IntegerType>>;
 /**
@@ -168,6 +170,136 @@ export declare const optimization_iterative: import("@elaraai/east").PlatformDef
     /** Whether optimization succeeded */
     readonly success: BooleanType;
 }>>;
+/**
+ * Incremental iterative optimization over integer parameter vectors.
+ *
+ * Like {@link optimization_iterative}, but takes a **per-element contribution function**
+ * instead of a full objective. The optimizer maintains a running sum and only
+ * recomputes contributions for changed indices — dramatically faster when
+ * individual moves affect only a small part of the total cost.
+ *
+ * The total objective is `sum(elementObjective(vector, i) for all i)`.
+ *
+ * Two modes are available:
+ * - **coordinate** (default): When changing element `i`, recomputes 1 contribution.
+ * - **swap**: When swapping elements `i` and `j`, recomputes 2 contributions.
+ *
+ * @example Incremental rostering
+ * ```ts
+ * // Per-person cost: only recomputes the changed person
+ * const elementObjective = East.function(
+ *     [VectorType(IntegerType), IntegerType], FloatType,
+ *     ($, assignments, personIdx) => {
+ *         const role = $.let(assignments.get(personIdx));
+ *         return $.return(salaryLookup.get(personIdx).get(role).negate());
+ *     }
+ * );
+ * const result = $.let(Optimization.iterativeIncremental(
+ *     elementObjective, spaces, config
+ * ));
+ * ```
+ */
+export declare const optimization_iterative_incremental: import("@elaraai/east").PlatformDefinition<[FunctionType<[VectorType<IntegerType>, IntegerType], FloatType>, ArrayType<VectorType<IntegerType>>, StructType<{
+    /** Maximum coordinate descent iterations per sample (default: 100) */
+    readonly iterations: OptionType<IntegerType>;
+    /** Number of independent restarts (default: 1) */
+    readonly samples: OptionType<IntegerType>;
+    /** How to initialize parameter values (default: first) */
+    readonly initial: OptionType<VariantType<{
+        readonly first: NullType;
+        readonly random: NullType;
+    }>>;
+    /** Order to evaluate candidates (default: sequential) */
+    readonly order: OptionType<VariantType<{
+        readonly sequential: NullType;
+        readonly random: NullType;
+    }>>;
+    /** Random seed for reproducibility */
+    readonly random_state: OptionType<IntegerType>;
+    /** Optimization mode: coordinate (default) or swap for permutations */
+    readonly mode: OptionType<VariantType<{
+        readonly coordinate: NullType;
+        readonly swap: NullType;
+    }>>;
+}>], StructType<{
+    /** Best parameter values found */
+    readonly best_parameters: VectorType<IntegerType>;
+    /** Objective value at best parameters */
+    readonly best_objective: FloatType;
+    /** Total coordinate descent iterations across all samples */
+    readonly iterations: IntegerType;
+    /** Total number of objective evaluations */
+    readonly evaluations: IntegerType;
+    /** Whether optimization succeeded */
+    readonly success: BooleanType;
+}>>;
+/**
+ * Group-based incremental iterative optimization.
+ *
+ * Like {@link optimization_iterative_incremental}, but contributions are grouped
+ * by **value** rather than by index. The group objective receives the full vector
+ * and a group key (a value that appears in the vector), and returns the total
+ * contribution of all elements assigned to that group.
+ *
+ * When element `i` changes from value A to value B, only 2 groups are recomputed:
+ * `groupObjective(vector, A)` and `groupObjective(vector, B)`.
+ *
+ * Use this when cost is associated with values (e.g., employees, bins, vehicles)
+ * rather than positions (e.g., slots, items, stops).
+ *
+ * @example Rostering — slot → employee assignment
+ * ```ts
+ * const groupObjective = East.function(
+ *     [VectorType(IntegerType), IntegerType], FloatType,
+ *     ($, slotAssignments, employeeId) => {
+ *         const cost = $.let(0.0);
+ *         $.for(East.Array.range(0n, nSlots), ($, slot) => {
+ *             $.if(East.equal(slotAssignments.get(slot), employeeId), $ => {
+ *                 $.assign(cost, cost.add(shiftRates.get(slot)));
+ *             });
+ *         });
+ *         return $.return(cost.negate());
+ *     }
+ * );
+ * const result = $.let(Optimization.iterativeGrouped(
+ *     groupObjective, spaces, config
+ * ));
+ * ```
+ */
+export declare const optimization_iterative_grouped: import("@elaraai/east").PlatformDefinition<[FunctionType<[VectorType<IntegerType>, IntegerType], FloatType>, ArrayType<VectorType<IntegerType>>, StructType<{
+    /** Maximum coordinate descent iterations per sample (default: 100) */
+    readonly iterations: OptionType<IntegerType>;
+    /** Number of independent restarts (default: 1) */
+    readonly samples: OptionType<IntegerType>;
+    /** How to initialize parameter values (default: first) */
+    readonly initial: OptionType<VariantType<{
+        readonly first: NullType;
+        readonly random: NullType;
+    }>>;
+    /** Order to evaluate candidates (default: sequential) */
+    readonly order: OptionType<VariantType<{
+        readonly sequential: NullType;
+        readonly random: NullType;
+    }>>;
+    /** Random seed for reproducibility */
+    readonly random_state: OptionType<IntegerType>;
+    /** Optimization mode: coordinate (default) or swap for permutations */
+    readonly mode: OptionType<VariantType<{
+        readonly coordinate: NullType;
+        readonly swap: NullType;
+    }>>;
+}>], StructType<{
+    /** Best parameter values found */
+    readonly best_parameters: VectorType<IntegerType>;
+    /** Objective value at best parameters */
+    readonly best_objective: FloatType;
+    /** Total coordinate descent iterations across all samples */
+    readonly iterations: IntegerType;
+    /** Total number of objective evaluations */
+    readonly evaluations: IntegerType;
+    /** Whether optimization succeeded */
+    readonly success: BooleanType;
+}>>;
 /**
  * Type definitions for iterative optimization.
  */
@@ -176,6 +308,8 @@ export declare const OptimizationTypes: {
     readonly ParameterVectorType: VectorType<IntegerType>;
     /** Objective function type */
     readonly ObjectiveType: FunctionType<[VectorType<IntegerType>], FloatType>;
+    /** Per-element contribution function type */
+    readonly ElementObjectiveType: FunctionType<[VectorType<IntegerType>, IntegerType], FloatType>;
     /** Parameter spaces type */
     readonly SpacesType: ArrayType<VectorType<IntegerType>>;
     /** Initial value strategy variant */
@@ -353,6 +487,150 @@ export declare const Optimization: {
         /** Whether optimization succeeded */
         readonly success: BooleanType;
     }>>;
+    /**
+     * Incremental iterative optimization with per-element contributions.
+     *
+     * `Optimization.iterativeIncremental(elementObjective, spaces, config)`
+     *
+     * Takes a per-element contribution function `(Vector<Integer>, Integer) -> Float`
+     * instead of a full objective. The total objective is the sum of all element
+     * contributions. Only recomputes contributions for changed indices during search.
+     *
+     * Use this when individual moves (coordinate or swap) affect only a small
+     * part of the total cost — e.g., rostering where changing one person's
+     * allocation only changes that person's salary.
+     *
+     * @example Incremental task-worker assignment
+     * ```ts
+     * // Per-task skill score: only recomputes the changed task
+     * const skill = $.let([[3.0, 1.0], [1.0, 3.0], [2.0, 2.0]]);
+     * const elementObjective = East.function(
+     *     [VectorType(IntegerType), IntegerType], FloatType,
+     *     ($, assignments, taskIdx) => {
+     *         const worker = $.let(assignments.get(taskIdx));
+     *         return $.return(skill.get(taskIdx).get(worker));
+     *     }
+     * );
+     * 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.iterativeIncremental(
+     *     elementObjective, spaces, config
+     * ));
+     * // result.best_objective = 8.0 (same result, fewer evaluations)
+     * ```
+     */
+    readonly iterativeIncremental: import("@elaraai/east").PlatformDefinition<[FunctionType<[VectorType<IntegerType>, IntegerType], FloatType>, ArrayType<VectorType<IntegerType>>, StructType<{
+        /** Maximum coordinate descent iterations per sample (default: 100) */
+        readonly iterations: OptionType<IntegerType>;
+        /** Number of independent restarts (default: 1) */
+        readonly samples: OptionType<IntegerType>;
+        /** How to initialize parameter values (default: first) */
+        readonly initial: OptionType<VariantType<{
+            readonly first: NullType;
+            readonly random: NullType;
+        }>>;
+        /** Order to evaluate candidates (default: sequential) */
+        readonly order: OptionType<VariantType<{
+            readonly sequential: NullType;
+            readonly random: NullType;
+        }>>;
+        /** Random seed for reproducibility */
+        readonly random_state: OptionType<IntegerType>;
+        /** Optimization mode: coordinate (default) or swap for permutations */
+        readonly mode: OptionType<VariantType<{
+            readonly coordinate: NullType;
+            readonly swap: NullType;
+        }>>;
+    }>], StructType<{
+        /** Best parameter values found */
+        readonly best_parameters: VectorType<IntegerType>;
+        /** Objective value at best parameters */
+        readonly best_objective: FloatType;
+        /** Total coordinate descent iterations across all samples */
+        readonly iterations: IntegerType;
+        /** Total number of objective evaluations */
+        readonly evaluations: IntegerType;
+        /** Whether optimization succeeded */
+        readonly success: BooleanType;
+    }>>;
+    /**
+     * Group-based incremental optimization with per-value contributions.
+     *
+     * `Optimization.iterativeGrouped(groupObjective, spaces, config)`
+     *
+     * Takes a group objective `(Vector<Integer>, Integer) -> Float` where the
+     * second argument is a **value** (group key), not an index. Returns the total
+     * contribution of all elements assigned to that value.
+     *
+     * When element `i` changes from value A to B, recomputes only groups A and B.
+     * Use this when cost is per-value (employee, bin, vehicle) not per-position.
+     *
+     * @example Group-based task assignment
+     * ```ts
+     * // 6 tasks assigned to workers 0-2. Cost = per-worker total.
+     * const taskCosts = $.let([10.0, 20.0, 15.0, 25.0, 30.0, 5.0]);
+     * const groupObjective = East.function(
+     *     [VectorType(IntegerType), IntegerType], FloatType,
+     *     ($, assignments, workerId) => {
+     *         const total = $.let(0.0);
+     *         $.for(East.Array.range(0n, East.value(6n)), ($, task) => {
+     *             $.if(East.equal(assignments.get(task), workerId), $ => {
+     *                 $.assign(total, total.add(taskCosts.get(task)));
+     *             });
+     *         });
+     *         return $.return(total.negate());
+     *     }
+     * );
+     * const result = $.let(Optimization.iterativeGrouped(
+     *     groupObjective, spaces, config
+     * ));
+     * ```
+     */
+    readonly iterativeGrouped: import("@elaraai/east").PlatformDefinition<[FunctionType<[VectorType<IntegerType>, IntegerType], FloatType>, ArrayType<VectorType<IntegerType>>, StructType<{
+        /** Maximum coordinate descent iterations per sample (default: 100) */
+        readonly iterations: OptionType<IntegerType>;
+        /** Number of independent restarts (default: 1) */
+        readonly samples: OptionType<IntegerType>;
+        /** How to initialize parameter values (default: first) */
+        readonly initial: OptionType<VariantType<{
+            readonly first: NullType;
+            readonly random: NullType;
+        }>>;
+        /** Order to evaluate candidates (default: sequential) */
+        readonly order: OptionType<VariantType<{
+            readonly sequential: NullType;
+            readonly random: NullType;
+        }>>;
+        /** Random seed for reproducibility */
+        readonly random_state: OptionType<IntegerType>;
+        /** Optimization mode: coordinate (default) or swap for permutations */
+        readonly mode: OptionType<VariantType<{
+            readonly coordinate: NullType;
+            readonly swap: NullType;
+        }>>;
+    }>], StructType<{
+        /** Best parameter values found */
+        readonly best_parameters: VectorType<IntegerType>;
+        /** Objective value at best parameters */
+        readonly best_objective: FloatType;
+        /** Total coordinate descent iterations across all samples */
+        readonly iterations: IntegerType;
+        /** Total number of objective evaluations */
+        readonly evaluations: IntegerType;
+        /** Whether optimization succeeded */
+        readonly success: BooleanType;
+    }>>;
     /**
      * Type definitions for optimization functions.
      */
@@ -361,6 +639,8 @@ export declare const Optimization: {
         readonly ParameterVectorType: VectorType<IntegerType>;
         /** Objective function type */
         readonly ObjectiveType: FunctionType<[VectorType<IntegerType>], FloatType>;
+        /** Per-element contribution function type */
+        readonly ElementObjectiveType: FunctionType<[VectorType<IntegerType>, IntegerType], FloatType>;
         /** Parameter spaces type */
         readonly SpacesType: ArrayType<VectorType<IntegerType>>;
         /** Initial value strategy variant */

package/dist/src/optimization/optimization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimization.d.ts","sourceRoot":"","sources":["../../../src/optimization/optimization.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAEH,UAAU,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACR,YAAY,EACf,MAAM,eAAe,CAAC;AAMvB,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,yBAA0B,CAAC;AAE3D,mDAAmD;AACnD,eAAO,MAAM,sBAAsB,oDAAiD,CAAC;AAErF,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,oCAAiC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;EAG9B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;EAG9B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;;;EAGnB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC5B,sEAAsE;;IAEtE,kDAAkD;;IAElD,0DAA0D;;;;;IAE1D,yDAAyD;;;;;IAEzD,sCAAsC;;IAEtC,uEAAuE;;;;;EAEzE,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;IAC5B,kCAAkC;;IAElC,yCAAyC;;IAEzC,6DAA6D;;IAE7D,4CAA4C;;IAE5C,qCAAqC;;EAEvC,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,sBAAsB;IA1E/B,sEAAsE;;IAEtE,kDAAkD;;IAElD,0DAA0D;;;;;IAE1D,yDAAyD;;;;;IAEzD,sCAAsC;;IAEtC,uEAAuE;;;;;;IAQvE,kCAAkC;;IAElC,yCAAyC;;IAEzC,6DAA6D;;IAE7D,4CAA4C;;IAE5C,qCAAqC;;GAwDxC,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC1B,4BAA4B;;IAE5B,8BAA8B;;IAE9B,4BAA4B;;IAE5B,qCAAqC;;;;;IAErC,+BAA+B;;;;;IAE/B,gCAAgC;;;;;IAEhC,yBAAyB;;QAxGzB,sEAAsE;;QAEtE,kDAAkD;;QAElD,0DAA0D;;;;;QAE1D,yDAAyD;;;;;QAEzD,sCAAsC;;QAEtC,uEAAuE;;;;;;IAgGvE,kBAAkB;;QAxFlB,kCAAkC;;QAElC,yCAAyC;;QAEzC,6DAA6D;;QAE7D,4CAA4C;;QAE5C,qCAAqC;;;CAkF/B,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY;IACrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuEG;;QArMH,sEAAsE;;QAEtE,kDAAkD;;QAElD,0DAA0D;;;;;QAE1D,yDAAyD;;;;;QAEzD,sCAAsC;;QAEtC,uEAAuE;;;;;;QAQvE,kCAAkC;;QAElC,yCAAyC;;QAEzC,6DAA6D;;QAE7D,4CAA4C;;QAE5C,qCAAqC;;;IA8KrC;;OAEG;;QA9GH,4BAA4B;;QAE5B,8BAA8B;;QAE9B,4BAA4B;;QAE5B,qCAAqC;;;;;QAErC,+BAA+B;;;;;QAE/B,gCAAgC;;;;;QAEhC,yBAAyB;;YAxGzB,sEAAsE;;YAEtE,kDAAkD;;YAElD,0DAA0D;;;;;YAE1D,yDAAyD;;;;;YAEzD,sCAAsC;;YAEtC,uEAAuE;;;;;;QAgGvE,kBAAkB;;YAxFlB,kCAAkC;;YAElC,yCAAyC;;YAEzC,6DAA6D;;YAE7D,4CAA4C;;YAE5C,qCAAqC;;;;CAkL/B,CAAC"}
+{"version":3,"file":"optimization.d.ts","sourceRoot":"","sources":["../../../src/optimization/optimization.ts"],"names":[],"mappings":"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"}

package/dist/src/optimization/optimization.js

@@ -22,6 +22,8 @@ import { East, StructType, VariantType, OptionType, ArrayType, VectorType, Integ
 export const ParameterVectorType = VectorType(IntegerType);
 /** Objective function: Vector<Integer> -> Float */
 export const IterativeObjectiveType = FunctionType([ParameterVectorType], FloatType);
+/** Per-element contribution function: (Vector<Integer>, Integer) -> Float */
+export const ElementObjectiveType = FunctionType([ParameterVectorType, IntegerType], FloatType);
 /** Per-element candidate spaces: Array<Vector<Integer>> */
 export const ParameterSpacesType = ArrayType(ParameterVectorType);
 /**
@@ -136,6 +138,78 @@ export const optimization_iterative = East.platform("optimization_iterative", [
     ParameterSpacesType, // parameter_spaces: Array<Vector<Integer>>
     IterativeConfigType, // config
 ], IterativeResultType);
+/**
+ * Incremental iterative optimization over integer parameter vectors.
+ *
+ * Like {@link optimization_iterative}, but takes a **per-element contribution function**
+ * instead of a full objective. The optimizer maintains a running sum and only
+ * recomputes contributions for changed indices — dramatically faster when
+ * individual moves affect only a small part of the total cost.
+ *
+ * The total objective is `sum(elementObjective(vector, i) for all i)`.
+ *
+ * Two modes are available:
+ * - **coordinate** (default): When changing element `i`, recomputes 1 contribution.
+ * - **swap**: When swapping elements `i` and `j`, recomputes 2 contributions.
+ *
+ * @example Incremental rostering
+ * ```ts
+ * // Per-person cost: only recomputes the changed person
+ * const elementObjective = East.function(
+ *     [VectorType(IntegerType), IntegerType], FloatType,
+ *     ($, assignments, personIdx) => {
+ *         const role = $.let(assignments.get(personIdx));
+ *         return $.return(salaryLookup.get(personIdx).get(role).negate());
+ *     }
+ * );
+ * const result = $.let(Optimization.iterativeIncremental(
+ *     elementObjective, spaces, config
+ * ));
+ * ```
+ */
+export const optimization_iterative_incremental = East.platform("optimization_iterative_incremental", [
+    ElementObjectiveType, // elementObjective: (Vector<Integer>, Integer) -> Float
+    ParameterSpacesType, // parameter_spaces: Array<Vector<Integer>>
+    IterativeConfigType, // config
+], IterativeResultType);
+/**
+ * Group-based incremental iterative optimization.
+ *
+ * Like {@link optimization_iterative_incremental}, but contributions are grouped
+ * by **value** rather than by index. The group objective receives the full vector
+ * and a group key (a value that appears in the vector), and returns the total
+ * contribution of all elements assigned to that group.
+ *
+ * When element `i` changes from value A to value B, only 2 groups are recomputed:
+ * `groupObjective(vector, A)` and `groupObjective(vector, B)`.
+ *
+ * Use this when cost is associated with values (e.g., employees, bins, vehicles)
+ * rather than positions (e.g., slots, items, stops).
+ *
+ * @example Rostering — slot → employee assignment
+ * ```ts
+ * const groupObjective = East.function(
+ *     [VectorType(IntegerType), IntegerType], FloatType,
+ *     ($, slotAssignments, employeeId) => {
+ *         const cost = $.let(0.0);
+ *         $.for(East.Array.range(0n, nSlots), ($, slot) => {
+ *             $.if(East.equal(slotAssignments.get(slot), employeeId), $ => {
+ *                 $.assign(cost, cost.add(shiftRates.get(slot)));
+ *             });
+ *         });
+ *         return $.return(cost.negate());
+ *     }
+ * );
+ * const result = $.let(Optimization.iterativeGrouped(
+ *     groupObjective, spaces, config
+ * ));
+ * ```
+ */
+export const optimization_iterative_grouped = East.platform("optimization_iterative_grouped", [
+    ElementObjectiveType, // groupObjective: (Vector<Integer>, Integer) -> Float
+    ParameterSpacesType, // parameter_spaces: Array<Vector<Integer>>
+    IterativeConfigType, // config
+], IterativeResultType);
 // ============================================================================
 // Grouped Export
 // ============================================================================
@@ -147,6 +221,8 @@ export const OptimizationTypes = {
     ParameterVectorType,
     /** Objective function type */
     ObjectiveType: IterativeObjectiveType,
+    /** Per-element contribution function type */
+    ElementObjectiveType,
     /** Parameter spaces type */
     SpacesType: ParameterSpacesType,
     /** Initial value strategy variant */
@@ -249,6 +325,84 @@ export const Optimization = {
      * ```
      */
     iterative: optimization_iterative,
+    /**
+     * Incremental iterative optimization with per-element contributions.
+     *
+     * `Optimization.iterativeIncremental(elementObjective, spaces, config)`
+     *
+     * Takes a per-element contribution function `(Vector<Integer>, Integer) -> Float`
+     * instead of a full objective. The total objective is the sum of all element
+     * contributions. Only recomputes contributions for changed indices during search.
+     *
+     * Use this when individual moves (coordinate or swap) affect only a small
+     * part of the total cost — e.g., rostering where changing one person's
+     * allocation only changes that person's salary.
+     *
+     * @example Incremental task-worker assignment
+     * ```ts
+     * // Per-task skill score: only recomputes the changed task
+     * const skill = $.let([[3.0, 1.0], [1.0, 3.0], [2.0, 2.0]]);
+     * const elementObjective = East.function(
+     *     [VectorType(IntegerType), IntegerType], FloatType,
+     *     ($, assignments, taskIdx) => {
+     *         const worker = $.let(assignments.get(taskIdx));
+     *         return $.return(skill.get(taskIdx).get(worker));
+     *     }
+     * );
+     * 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.iterativeIncremental(
+     *     elementObjective, spaces, config
+     * ));
+     * // result.best_objective = 8.0 (same result, fewer evaluations)
+     * ```
+     */
+    iterativeIncremental: optimization_iterative_incremental,
+    /**
+     * Group-based incremental optimization with per-value contributions.
+     *
+     * `Optimization.iterativeGrouped(groupObjective, spaces, config)`
+     *
+     * Takes a group objective `(Vector<Integer>, Integer) -> Float` where the
+     * second argument is a **value** (group key), not an index. Returns the total
+     * contribution of all elements assigned to that value.
+     *
+     * When element `i` changes from value A to B, recomputes only groups A and B.
+     * Use this when cost is per-value (employee, bin, vehicle) not per-position.
+     *
+     * @example Group-based task assignment
+     * ```ts
+     * // 6 tasks assigned to workers 0-2. Cost = per-worker total.
+     * const taskCosts = $.let([10.0, 20.0, 15.0, 25.0, 30.0, 5.0]);
+     * const groupObjective = East.function(
+     *     [VectorType(IntegerType), IntegerType], FloatType,
+     *     ($, assignments, workerId) => {
+     *         const total = $.let(0.0);
+     *         $.for(East.Array.range(0n, East.value(6n)), ($, task) => {
+     *             $.if(East.equal(assignments.get(task), workerId), $ => {
+     *                 $.assign(total, total.add(taskCosts.get(task)));
+     *             });
+     *         });
+     *         return $.return(total.negate());
+     *     }
+     * );
+     * const result = $.let(Optimization.iterativeGrouped(
+     *     groupObjective, spaces, config
+     * ));
+     * ```
+     */
+    iterativeGrouped: optimization_iterative_grouped,
     /**
      * Type definitions for optimization functions.
      */

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

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