@elaraai/east-py-datascience 0.0.2-beta.1

package/dist/simanneal/simanneal.js

@@ -0,0 +1,231 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Discrete optimization using Simulated Annealing.
+ *
+ * Provides combinatorial optimization for discrete state spaces using the
+ * simanneal library. Ideal for:
+ * - Permutation problems (TSP, scheduling)
+ * - Subset selection (feature selection, knapsack)
+ * - Assignment problems
+ * - Any discrete optimization where gradient methods don't apply
+ *
+ * @packageDocumentation
+ */
+import { East, StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType, BooleanType, FunctionType, } from "@elaraai/east";
+// ===========================================
+// State Types
+// ===========================================
+/**
+ * Discrete state type for simulated annealing.
+ *
+ * Supports different representations for combinatorial problems:
+ * - int_array: Permutations, assignments, sequences of integers
+ * - bool_array: Subset selections, binary decisions
+ */
+export const DiscreteStateType = VariantType({
+    /** Integer array state (permutations, assignments) */
+    int_array: ArrayType(IntegerType),
+    /** Boolean array state (subset selection) */
+    bool_array: ArrayType(BooleanType),
+});
+// ===========================================
+// Function Types
+// ===========================================
+/**
+ * Energy function type: state -> score.
+ *
+ * Computes the objective value (energy) for a given state.
+ * Lower energy is better (minimization).
+ */
+export const EnergyFunctionType = FunctionType([DiscreteStateType], FloatType);
+/**
+ * Move function type: state -> neighbor state.
+ *
+ * Generates a random neighbor of the current state.
+ * Should make small, local changes (e.g., swap two elements).
+ */
+export const MoveFunctionType = FunctionType([DiscreteStateType], DiscreteStateType);
+/**
+ * Permutation energy function type.
+ *
+ * Specialized for permutation-based optimization.
+ */
+export const PermutationEnergyType = FunctionType([ArrayType(IntegerType)], FloatType);
+/**
+ * Subset energy function type.
+ *
+ * Specialized for subset selection optimization.
+ */
+export const SubsetEnergyType = FunctionType([ArrayType(BooleanType)], FloatType);
+// ===========================================
+// Configuration Types
+// ===========================================
+/**
+ * Simulated annealing configuration.
+ */
+export const AnnealConfigType = StructType({
+    /** Starting temperature (default: 25000.0) */
+    t_max: OptionType(FloatType),
+    /** Ending temperature (default: 2.5) */
+    t_min: OptionType(FloatType),
+    /** Total iterations (default: 50000) */
+    steps: OptionType(IntegerType),
+    /** Progress report frequency (default: 0 = silent) */
+    updates: OptionType(IntegerType),
+    /** Minutes for auto-calibration (default: none) */
+    auto_schedule: OptionType(FloatType),
+    /** Random seed for reproducibility */
+    random_state: OptionType(IntegerType),
+});
+// ===========================================
+// Result Types
+// ===========================================
+/**
+ * Simulated annealing result.
+ */
+export const AnnealResultType = StructType({
+    /** Best state found */
+    best_state: DiscreteStateType,
+    /** Energy of best state */
+    best_energy: FloatType,
+    /** Actual iterations performed */
+    steps_taken: IntegerType,
+    /** Whether optimization completed successfully */
+    success: BooleanType,
+});
+// ===========================================
+// Platform Functions
+// ===========================================
+/**
+ * Run simulated annealing on a discrete state space.
+ *
+ * Uses custom energy and move functions for flexible optimization.
+ *
+ * @param initial_state - Starting state
+ * @param energy_fn - Function to compute state energy (lower is better)
+ * @param move_fn - Function to generate neighbor states
+ * @param config - Annealing schedule configuration
+ * @returns Result with best state and energy
+ */
+export const simanneal_optimize = East.platform("simanneal_optimize", [
+    DiscreteStateType,
+    EnergyFunctionType,
+    MoveFunctionType,
+    AnnealConfigType,
+], AnnealResultType);
+/**
+ * Run simulated annealing on a permutation with swap moves.
+ *
+ * Convenience function for permutation-based problems (TSP, scheduling).
+ * Automatically uses swap moves to generate neighbors.
+ *
+ * @param initial_perm - Starting permutation
+ * @param energy_fn - Function to compute permutation energy
+ * @param config - Annealing schedule configuration
+ * @returns Result with best permutation and energy
+ */
+export const simanneal_optimize_permutation = East.platform("simanneal_optimize_permutation", [
+    ArrayType(IntegerType),
+    PermutationEnergyType,
+    AnnealConfigType,
+], AnnealResultType);
+/**
+ * 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.
+ *
+ * @param initial_selection - Starting selection (boolean array)
+ * @param energy_fn - Function to compute selection energy
+ * @param config - Annealing schedule configuration
+ * @returns Result with best selection and energy
+ */
+export const simanneal_optimize_subset = East.platform("simanneal_optimize_subset", [
+    ArrayType(BooleanType),
+    SubsetEnergyType,
+    AnnealConfigType,
+], AnnealResultType);
+// ===========================================
+// Grouped Export
+// ===========================================
+/**
+ * Type definitions for Simulated Annealing.
+ */
+export const SimAnnealTypes = {
+    /** Discrete state type */
+    DiscreteStateType,
+    /** Energy function type */
+    EnergyFunctionType,
+    /** Move function type */
+    MoveFunctionType,
+    /** Permutation energy function type */
+    PermutationEnergyType,
+    /** Subset energy function type */
+    SubsetEnergyType,
+    /** Configuration type */
+    ConfigType: AnnealConfigType,
+    /** Result type */
+    ResultType: AnnealResultType,
+};
+/**
+ * Discrete optimization using Simulated Annealing.
+ *
+ * Provides combinatorial optimization for discrete state spaces.
+ * Simulated annealing is a probabilistic technique that can escape
+ * local minima by occasionally accepting worse solutions.
+ *
+ * Ideal for:
+ * - Permutation problems (TSP, job scheduling)
+ * - Subset selection (feature selection, knapsack)
+ * - Assignment problems
+ * - Any discrete optimization with many local minima
+ *
+ * @example
+ * ```ts
+ * import { East, FloatType, variant } from "@elaraai/east";
+ * import { SimAnneal } from "@elaraai/east-py-datascience";
+ *
+ * // TSP: minimize total route distance
+ * const energy = East.function(
+ *     [ArrayType(IntegerType)],
+ *     FloatType,
+ *     ($, route) => {
+ *         // Calculate total route distance
+ *         return $.return(totalDistance);
+ *     }
+ * );
+ *
+ * const config = $.let({
+ *     t_max: variant("some", 10000.0),
+ *     t_min: variant("some", 1.0),
+ *     steps: variant("some", 50000n),
+ *     updates: variant("none", null),
+ *     auto_schedule: variant("none", null),
+ *     random_state: variant("some", 42n),
+ * });
+ *
+ * const result = SimAnneal.optimizePermutation(initial, energy, config);
+ * ```
+ */
+export const SimAnneal = {
+    /**
+     * Run simulated annealing with custom energy and move functions.
+     */
+    optimize: simanneal_optimize,
+    /**
+     * Run simulated annealing on a permutation with swap moves.
+     */
+    optimizePermutation: simanneal_optimize_permutation,
+    /**
+     * Run simulated annealing on a subset selection with bit-flip moves.
+     */
+    optimizeSubset: simanneal_optimize_subset,
+    /**
+     * Type definitions for SimAnneal functions.
+     */
+    Types: SimAnnealTypes,
+};
+//# sourceMappingURL=simanneal.js.map

package/dist/simanneal/simanneal.js.map

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