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

package/dist/{simanneal → src/simanneal}/simanneal.d.ts

@@ -14,7 +14,7 @@
  *
  * @packageDocumentation
  */
-import { StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType, BooleanType, FunctionType } from "@elaraai/east";
+import { StructType, VariantType, OptionType, IntegerType, FloatType, BooleanType, FunctionType, VectorType } from "@elaraai/east";
 /**
  * Discrete state type for simulated annealing.
  *
@@ -24,9 +24,9 @@ import { StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType,
  */
 export declare const DiscreteStateType: VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>;
 /**
  * Energy function type: state -> score.
@@ -36,9 +36,9 @@ export declare const DiscreteStateType: VariantType<{
  */
 export declare const EnergyFunctionType: FunctionType<[VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>], FloatType>;
 /**
  * Move function type: state -> neighbor state.
@@ -48,61 +48,61 @@ export declare const EnergyFunctionType: FunctionType<[VariantType<{
  */
 export declare const MoveFunctionType: FunctionType<[VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>], VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>>;
 /**
  * Permutation energy function type.
  *
  * Specialized for permutation-based optimization.
  */
-export declare const PermutationEnergyType: FunctionType<[ArrayType<IntegerType>], FloatType>;
+export declare const PermutationEnergyType: FunctionType<[VectorType<IntegerType>], FloatType>;
 /**
  * Subset energy function type.
  *
  * Specialized for subset selection optimization.
  */
-export declare const SubsetEnergyType: FunctionType<[ArrayType<BooleanType>], FloatType>;
+export declare const SubsetEnergyType: FunctionType<[VectorType<BooleanType>], FloatType>;
 /**
  * Simulated annealing configuration.
  */
 export declare const AnnealConfigType: StructType<{
     /** Starting temperature (default: 25000.0) */
-    t_max: OptionType<FloatType>;
+    readonly t_max: OptionType<FloatType>;
     /** Ending temperature (default: 2.5) */
-    t_min: OptionType<FloatType>;
+    readonly t_min: OptionType<FloatType>;
     /** Total iterations (default: 50000) */
-    steps: OptionType<IntegerType>;
+    readonly steps: OptionType<IntegerType>;
     /** Progress report frequency (default: 0 = silent) */
-    updates: OptionType<IntegerType>;
+    readonly updates: OptionType<IntegerType>;
     /** Minutes for auto-calibration (default: none) */
-    auto_schedule: OptionType<FloatType>;
+    readonly auto_schedule: OptionType<FloatType>;
     /** Random seed for reproducibility */
-    random_state: OptionType<IntegerType>;
+    readonly random_state: OptionType<IntegerType>;
 }>;
 /**
  * Simulated annealing result.
  */
 export declare const AnnealResultType: StructType<{
     /** Best state found */
-    best_state: VariantType<{
+    readonly best_state: VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>;
     /** Energy of best state */
-    best_energy: FloatType;
+    readonly best_energy: FloatType;
     /** Actual iterations performed */
-    steps_taken: IntegerType;
+    readonly steps_taken: IntegerType;
     /** Whether optimization completed successfully */
-    success: BooleanType;
+    readonly success: BooleanType;
 }>;
 /**
  * Run simulated annealing on a discrete state space.
@@ -117,51 +117,51 @@ export declare const AnnealResultType: StructType<{
  */
 export declare const simanneal_optimize: import("@elaraai/east").PlatformDefinition<[VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>, FunctionType<[VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>], FloatType>, FunctionType<[VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>], VariantType<{
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType<IntegerType>;
+    readonly int_array: VectorType<IntegerType>;
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType<BooleanType>;
+    readonly bool_array: VectorType<BooleanType>;
 }>>, StructType<{
     /** Starting temperature (default: 25000.0) */
-    t_max: OptionType<FloatType>;
+    readonly t_max: OptionType<FloatType>;
     /** Ending temperature (default: 2.5) */
-    t_min: OptionType<FloatType>;
+    readonly t_min: OptionType<FloatType>;
     /** Total iterations (default: 50000) */
-    steps: OptionType<IntegerType>;
+    readonly steps: OptionType<IntegerType>;
     /** Progress report frequency (default: 0 = silent) */
-    updates: OptionType<IntegerType>;
+    readonly updates: OptionType<IntegerType>;
     /** Minutes for auto-calibration (default: none) */
-    auto_schedule: OptionType<FloatType>;
+    readonly auto_schedule: OptionType<FloatType>;
     /** Random seed for reproducibility */
-    random_state: OptionType<IntegerType>;
+    readonly random_state: OptionType<IntegerType>;
 }>], StructType<{
     /** Best state found */
-    best_state: VariantType<{
+    readonly best_state: VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>;
     /** Energy of best state */
-    best_energy: FloatType;
+    readonly best_energy: FloatType;
     /** Actual iterations performed */
-    steps_taken: IntegerType;
+    readonly steps_taken: IntegerType;
     /** Whether optimization completed successfully */
-    success: BooleanType;
+    readonly success: BooleanType;
 }>>;
 /**
  * Run simulated annealing on a permutation with swap moves.
@@ -174,33 +174,33 @@ export declare const simanneal_optimize: import("@elaraai/east").PlatformDefinit
  * @param config - Annealing schedule configuration
  * @returns Result with best permutation and energy
  */
-export declare const simanneal_optimize_permutation: import("@elaraai/east").PlatformDefinition<[ArrayType<IntegerType>, FunctionType<[ArrayType<IntegerType>], FloatType>, StructType<{
+export declare const simanneal_optimize_permutation: import("@elaraai/east").PlatformDefinition<[VectorType<IntegerType>, FunctionType<[VectorType<IntegerType>], FloatType>, StructType<{
     /** Starting temperature (default: 25000.0) */
-    t_max: OptionType<FloatType>;
+    readonly t_max: OptionType<FloatType>;
     /** Ending temperature (default: 2.5) */
-    t_min: OptionType<FloatType>;
+    readonly t_min: OptionType<FloatType>;
     /** Total iterations (default: 50000) */
-    steps: OptionType<IntegerType>;
+    readonly steps: OptionType<IntegerType>;
     /** Progress report frequency (default: 0 = silent) */
-    updates: OptionType<IntegerType>;
+    readonly updates: OptionType<IntegerType>;
     /** Minutes for auto-calibration (default: none) */
-    auto_schedule: OptionType<FloatType>;
+    readonly auto_schedule: OptionType<FloatType>;
     /** Random seed for reproducibility */
-    random_state: OptionType<IntegerType>;
+    readonly random_state: OptionType<IntegerType>;
 }>], StructType<{
     /** Best state found */
-    best_state: VariantType<{
+    readonly best_state: VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>;
     /** Energy of best state */
-    best_energy: FloatType;
+    readonly best_energy: FloatType;
     /** Actual iterations performed */
-    steps_taken: IntegerType;
+    readonly steps_taken: IntegerType;
     /** Whether optimization completed successfully */
-    success: BooleanType;
+    readonly success: BooleanType;
 }>>;
 /**
  * Run simulated annealing on a subset selection with bit-flip moves.
@@ -213,33 +213,33 @@ export declare const simanneal_optimize_permutation: import("@elaraai/east").Pla
  * @param config - Annealing schedule configuration
  * @returns Result with best selection and energy
  */
-export declare const simanneal_optimize_subset: import("@elaraai/east").PlatformDefinition<[ArrayType<BooleanType>, FunctionType<[ArrayType<BooleanType>], FloatType>, StructType<{
+export declare const simanneal_optimize_subset: import("@elaraai/east").PlatformDefinition<[VectorType<BooleanType>, FunctionType<[VectorType<BooleanType>], FloatType>, StructType<{
     /** Starting temperature (default: 25000.0) */
-    t_max: OptionType<FloatType>;
+    readonly t_max: OptionType<FloatType>;
     /** Ending temperature (default: 2.5) */
-    t_min: OptionType<FloatType>;
+    readonly t_min: OptionType<FloatType>;
     /** Total iterations (default: 50000) */
-    steps: OptionType<IntegerType>;
+    readonly steps: OptionType<IntegerType>;
     /** Progress report frequency (default: 0 = silent) */
-    updates: OptionType<IntegerType>;
+    readonly updates: OptionType<IntegerType>;
     /** Minutes for auto-calibration (default: none) */
-    auto_schedule: OptionType<FloatType>;
+    readonly auto_schedule: OptionType<FloatType>;
     /** Random seed for reproducibility */
-    random_state: OptionType<IntegerType>;
+    readonly random_state: OptionType<IntegerType>;
 }>], StructType<{
     /** Best state found */
-    best_state: VariantType<{
+    readonly best_state: VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>;
     /** Energy of best state */
-    best_energy: FloatType;
+    readonly best_energy: FloatType;
     /** Actual iterations performed */
-    steps_taken: IntegerType;
+    readonly steps_taken: IntegerType;
     /** Whether optimization completed successfully */
-    success: BooleanType;
+    readonly success: BooleanType;
 }>>;
 /**
  * Type definitions for Simulated Annealing.
@@ -248,63 +248,63 @@ export declare const SimAnnealTypes: {
     /** Discrete state type */
     readonly DiscreteStateType: VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>;
     /** Energy function type */
     readonly EnergyFunctionType: FunctionType<[VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>], FloatType>;
     /** Move function type */
     readonly MoveFunctionType: FunctionType<[VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>], VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>>;
     /** Permutation energy function type */
-    readonly PermutationEnergyType: FunctionType<[ArrayType<IntegerType>], FloatType>;
+    readonly PermutationEnergyType: FunctionType<[VectorType<IntegerType>], FloatType>;
     /** Subset energy function type */
-    readonly SubsetEnergyType: FunctionType<[ArrayType<BooleanType>], FloatType>;
+    readonly SubsetEnergyType: FunctionType<[VectorType<BooleanType>], FloatType>;
     /** Configuration type */
     readonly ConfigType: StructType<{
         /** Starting temperature (default: 25000.0) */
-        t_max: OptionType<FloatType>;
+        readonly t_max: OptionType<FloatType>;
         /** Ending temperature (default: 2.5) */
-        t_min: OptionType<FloatType>;
+        readonly t_min: OptionType<FloatType>;
         /** Total iterations (default: 50000) */
-        steps: OptionType<IntegerType>;
+        readonly steps: OptionType<IntegerType>;
         /** Progress report frequency (default: 0 = silent) */
-        updates: OptionType<IntegerType>;
+        readonly updates: OptionType<IntegerType>;
         /** Minutes for auto-calibration (default: none) */
-        auto_schedule: OptionType<FloatType>;
+        readonly auto_schedule: OptionType<FloatType>;
         /** Random seed for reproducibility */
-        random_state: OptionType<IntegerType>;
+        readonly random_state: OptionType<IntegerType>;
     }>;
     /** Result type */
     readonly ResultType: StructType<{
         /** Best state found */
-        best_state: VariantType<{
+        readonly best_state: VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>;
         /** Energy of best state */
-        best_energy: FloatType;
+        readonly best_energy: FloatType;
         /** Actual iterations performed */
-        steps_taken: IntegerType;
+        readonly steps_taken: IntegerType;
         /** Whether optimization completed successfully */
-        success: BooleanType;
+        readonly success: BooleanType;
     }>;
 };
 /**
@@ -327,7 +327,7 @@ export declare const SimAnnealTypes: {
  *
  * // TSP: minimize total route distance
  * const energy = East.function(
- *     [ArrayType(IntegerType)],
+ *     [VectorType(IntegerType)],
  *     FloatType,
  *     ($, route) => {
  *         // Calculate total route distance
@@ -350,116 +350,213 @@ export declare const SimAnnealTypes: {
 export declare const SimAnneal: {
     /**
      * Run simulated annealing with custom energy and move functions.
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType, IntegerType, VectorType, variant } from "@elaraai/east";
+     * import { SimAnneal, AnnealConfigType, DiscreteStateType } from "@elaraai/east-py-datascience";
+     *
+     * const solve = East.function([], SimAnneal.Types.ResultType, ($) => {
+     *     const energy = East.function([DiscreteStateType], FloatType, ($, state) => {
+     *         const cost = $.let(0.0);
+     *         $.match(state, {
+     *             int_array: ($, arr) => {
+     *                 const a0 = $.let(arr.get(0n));
+     *                 $.if(East.equal(a0, 2n), $ => {}).else($ => { $.assign(cost, cost.add(1.0)); });
+     *             },
+     *             bool_array: ($) => { $.assign(cost, 999.0); },
+     *         });
+     *         return $.return(cost);
+     *     });
+     *     const move = East.function([DiscreteStateType], DiscreteStateType, ($, state) => {
+     *         const result = $.let(state);
+     *         $.match(state, {
+     *             int_array: ($, arr) => {
+     *                 const new_arr = $.let(East.Vector.fromArray([arr.get(0n).add(1n).remainder(3n), arr.get(1n), arr.get(2n)]));
+     *                 $.assign(result, variant("int_array", new_arr));
+     *             },
+     *             bool_array: ($, arr) => { $.assign(result, variant("bool_array", arr)); },
+     *         });
+     *         return $.return(result);
+     *     });
+     *     const initial = $.let(variant("int_array", new BigInt64Array([0n, 0n, 0n])), DiscreteStateType);
+     *     const config = $.let({
+     *         t_max: variant("some", 100.0), t_min: variant("some", 0.01),
+     *         steps: variant("some", 1000n), updates: variant("none", null),
+     *         auto_schedule: variant("none", null), random_state: variant("some", 42n),
+     *     }, AnnealConfigType);
+     *     return $.return(SimAnneal.optimize(initial, energy, move, config));
+     * });
+     * ```
      */
     readonly optimize: import("@elaraai/east").PlatformDefinition<[VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>, FunctionType<[VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>], FloatType>, FunctionType<[VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>], VariantType<{
         /** Integer array state (permutations, assignments) */
-        int_array: ArrayType<IntegerType>;
+        readonly int_array: VectorType<IntegerType>;
         /** Boolean array state (subset selection) */
-        bool_array: ArrayType<BooleanType>;
+        readonly bool_array: VectorType<BooleanType>;
     }>>, StructType<{
         /** Starting temperature (default: 25000.0) */
-        t_max: OptionType<FloatType>;
+        readonly t_max: OptionType<FloatType>;
         /** Ending temperature (default: 2.5) */
-        t_min: OptionType<FloatType>;
+        readonly t_min: OptionType<FloatType>;
         /** Total iterations (default: 50000) */
-        steps: OptionType<IntegerType>;
+        readonly steps: OptionType<IntegerType>;
         /** Progress report frequency (default: 0 = silent) */
-        updates: OptionType<IntegerType>;
+        readonly updates: OptionType<IntegerType>;
         /** Minutes for auto-calibration (default: none) */
-        auto_schedule: OptionType<FloatType>;
+        readonly auto_schedule: OptionType<FloatType>;
         /** Random seed for reproducibility */
-        random_state: OptionType<IntegerType>;
+        readonly random_state: OptionType<IntegerType>;
     }>], StructType<{
         /** Best state found */
-        best_state: VariantType<{
+        readonly best_state: VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>;
         /** Energy of best state */
-        best_energy: FloatType;
+        readonly best_energy: FloatType;
         /** Actual iterations performed */
-        steps_taken: IntegerType;
+        readonly steps_taken: IntegerType;
         /** Whether optimization completed successfully */
-        success: BooleanType;
+        readonly success: BooleanType;
     }>>;
     /**
      * Run simulated annealing on a permutation with swap moves.
+     *
+     * Convenience function for permutation-based problems (TSP, scheduling).
+     * Automatically uses swap moves to generate neighbors.
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType, IntegerType, VectorType, variant } from "@elaraai/east";
+     * import { SimAnneal, AnnealConfigType } from "@elaraai/east-py-datascience";
+     *
+     * const solve = East.function([], SimAnneal.Types.ResultType, ($) => {
+     *     const energy = East.function([VectorType(IntegerType)], FloatType, ($, route) => {
+     *         const total = $.let(0.0);
+     *         $.for(East.Array.range(0n, route.length()), ($, i) => {
+     *             const from = $.let(route.get(i));
+     *             const to = $.let(route.get(i.add(1n).remainder(route.length())));
+     *             const diff = $.let(from.subtract(to).abs());
+     *             $.if(East.equal(diff, 1n).or(() => East.equal(diff, 3n)), $ => {
+     *                 $.assign(total, total.add(1.0));
+     *             }).else($ => { $.assign(total, total.add(1.414)); });
+     *         });
+     *         return $.return(total);
+     *     });
+     *     const initial = $.let(new BigInt64Array([0n, 1n, 2n, 3n]));
+     *     const config = $.let({
+     *         t_max: variant("some", 1000.0), t_min: variant("some", 0.1),
+     *         steps: variant("some", 5000n), updates: variant("none", null),
+     *         auto_schedule: variant("none", null), random_state: variant("some", 42n),
+     *     }, AnnealConfigType);
+     *     return $.return(SimAnneal.optimizePermutation(initial, energy, config));
+     * });
+     * ```
      */
-    readonly optimizePermutation: import("@elaraai/east").PlatformDefinition<[ArrayType<IntegerType>, FunctionType<[ArrayType<IntegerType>], FloatType>, StructType<{
+    readonly optimizePermutation: import("@elaraai/east").PlatformDefinition<[VectorType<IntegerType>, FunctionType<[VectorType<IntegerType>], FloatType>, StructType<{
         /** Starting temperature (default: 25000.0) */
-        t_max: OptionType<FloatType>;
+        readonly t_max: OptionType<FloatType>;
         /** Ending temperature (default: 2.5) */
-        t_min: OptionType<FloatType>;
+        readonly t_min: OptionType<FloatType>;
         /** Total iterations (default: 50000) */
-        steps: OptionType<IntegerType>;
+        readonly steps: OptionType<IntegerType>;
         /** Progress report frequency (default: 0 = silent) */
-        updates: OptionType<IntegerType>;
+        readonly updates: OptionType<IntegerType>;
         /** Minutes for auto-calibration (default: none) */
-        auto_schedule: OptionType<FloatType>;
+        readonly auto_schedule: OptionType<FloatType>;
         /** Random seed for reproducibility */
-        random_state: OptionType<IntegerType>;
+        readonly random_state: OptionType<IntegerType>;
     }>], StructType<{
         /** Best state found */
-        best_state: VariantType<{
+        readonly best_state: VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>;
         /** Energy of best state */
-        best_energy: FloatType;
+        readonly best_energy: FloatType;
         /** Actual iterations performed */
-        steps_taken: IntegerType;
+        readonly steps_taken: IntegerType;
         /** Whether optimization completed successfully */
-        success: BooleanType;
+        readonly success: BooleanType;
     }>>;
     /**
      * Run simulated annealing on a subset selection with bit-flip moves.
+     *
+     * Convenience function for subset selection problems (feature selection, knapsack).
+     * Automatically uses bit-flip moves to generate neighbors.
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType, BooleanType, VectorType, variant } from "@elaraai/east";
+     * import { SimAnneal, AnnealConfigType } from "@elaraai/east-py-datascience";
+     *
+     * const solve = East.function([], SimAnneal.Types.ResultType, ($) => {
+     *     const items = $.let(new Float64Array([3.0, 7.0, 1.0, 8.0, 4.0]));
+     *     const target = $.let(12.0);
+     *     const energy = East.function([VectorType(BooleanType)], FloatType, ($, selection) => {
+     *         const sum = $.let(0.0);
+     *         $.for(East.Array.range(0n, selection.length()), ($, i) => {
+     *             $.if(selection.get(i), $ => { $.assign(sum, sum.add(items.get(i))); });
+     *         });
+     *         return $.return(sum.subtract(target).abs());
+     *     });
+     *     const initial = $.let(East.Vector.fromArray([true, true, true, true, true]));
+     *     const config = $.let({
+     *         t_max: variant("some", 500.0), t_min: variant("some", 0.1),
+     *         steps: variant("some", 2000n), updates: variant("none", null),
+     *         auto_schedule: variant("none", null), random_state: variant("some", 123n),
+     *     }, AnnealConfigType);
+     *     return $.return(SimAnneal.optimizeSubset(initial, energy, config));
+     * });
+     * ```
      */
-    readonly optimizeSubset: import("@elaraai/east").PlatformDefinition<[ArrayType<BooleanType>, FunctionType<[ArrayType<BooleanType>], FloatType>, StructType<{
+    readonly optimizeSubset: import("@elaraai/east").PlatformDefinition<[VectorType<BooleanType>, FunctionType<[VectorType<BooleanType>], FloatType>, StructType<{
         /** Starting temperature (default: 25000.0) */
-        t_max: OptionType<FloatType>;
+        readonly t_max: OptionType<FloatType>;
         /** Ending temperature (default: 2.5) */
-        t_min: OptionType<FloatType>;
+        readonly t_min: OptionType<FloatType>;
         /** Total iterations (default: 50000) */
-        steps: OptionType<IntegerType>;
+        readonly steps: OptionType<IntegerType>;
         /** Progress report frequency (default: 0 = silent) */
-        updates: OptionType<IntegerType>;
+        readonly updates: OptionType<IntegerType>;
         /** Minutes for auto-calibration (default: none) */
-        auto_schedule: OptionType<FloatType>;
+        readonly auto_schedule: OptionType<FloatType>;
         /** Random seed for reproducibility */
-        random_state: OptionType<IntegerType>;
+        readonly random_state: OptionType<IntegerType>;
     }>], StructType<{
         /** Best state found */
-        best_state: VariantType<{
+        readonly best_state: VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>;
         /** Energy of best state */
-        best_energy: FloatType;
+        readonly best_energy: FloatType;
         /** Actual iterations performed */
-        steps_taken: IntegerType;
+        readonly steps_taken: IntegerType;
         /** Whether optimization completed successfully */
-        success: BooleanType;
+        readonly success: BooleanType;
     }>>;
     /**
      * Type definitions for SimAnneal functions.
@@ -468,63 +565,63 @@ export declare const SimAnneal: {
         /** Discrete state type */
         readonly DiscreteStateType: VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>;
         /** Energy function type */
         readonly EnergyFunctionType: FunctionType<[VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>], FloatType>;
         /** Move function type */
         readonly MoveFunctionType: FunctionType<[VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>], VariantType<{
             /** Integer array state (permutations, assignments) */
-            int_array: ArrayType<IntegerType>;
+            readonly int_array: VectorType<IntegerType>;
             /** Boolean array state (subset selection) */
-            bool_array: ArrayType<BooleanType>;
+            readonly bool_array: VectorType<BooleanType>;
         }>>;
         /** Permutation energy function type */
-        readonly PermutationEnergyType: FunctionType<[ArrayType<IntegerType>], FloatType>;
+        readonly PermutationEnergyType: FunctionType<[VectorType<IntegerType>], FloatType>;
         /** Subset energy function type */
-        readonly SubsetEnergyType: FunctionType<[ArrayType<BooleanType>], FloatType>;
+        readonly SubsetEnergyType: FunctionType<[VectorType<BooleanType>], FloatType>;
         /** Configuration type */
         readonly ConfigType: StructType<{
             /** Starting temperature (default: 25000.0) */
-            t_max: OptionType<FloatType>;
+            readonly t_max: OptionType<FloatType>;
             /** Ending temperature (default: 2.5) */
-            t_min: OptionType<FloatType>;
+            readonly t_min: OptionType<FloatType>;
             /** Total iterations (default: 50000) */
-            steps: OptionType<IntegerType>;
+            readonly steps: OptionType<IntegerType>;
             /** Progress report frequency (default: 0 = silent) */
-            updates: OptionType<IntegerType>;
+            readonly updates: OptionType<IntegerType>;
             /** Minutes for auto-calibration (default: none) */
-            auto_schedule: OptionType<FloatType>;
+            readonly auto_schedule: OptionType<FloatType>;
             /** Random seed for reproducibility */
-            random_state: OptionType<IntegerType>;
+            readonly random_state: OptionType<IntegerType>;
         }>;
         /** Result type */
         readonly ResultType: StructType<{
             /** Best state found */
-            best_state: VariantType<{
+            readonly best_state: VariantType<{
                 /** Integer array state (permutations, assignments) */
-                int_array: ArrayType<IntegerType>;
+                readonly int_array: VectorType<IntegerType>;
                 /** Boolean array state (subset selection) */
-                bool_array: ArrayType<BooleanType>;
+                readonly bool_array: VectorType<BooleanType>;
             }>;
             /** Energy of best state */
-            best_energy: FloatType;
+            readonly best_energy: FloatType;
             /** Actual iterations performed */
-            steps_taken: IntegerType;
+            readonly steps_taken: IntegerType;
             /** Whether optimization completed successfully */
-            success: BooleanType;
+            readonly success: BooleanType;
         }>;
     };
 };