@elaraai/east-py-datascience 1.0.1 → 1.0.3

package/dist/src/simanneal/simanneal.js

@@ -0,0 +1,328 @@
+/**
+ * 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, IntegerType, FloatType, BooleanType, FunctionType, VectorType, } 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: VectorType(IntegerType),
+    /** Boolean array state (subset selection) */
+    bool_array: VectorType(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([VectorType(IntegerType)], FloatType);
+/**
+ * Subset energy function type.
+ *
+ * Specialized for subset selection optimization.
+ */
+export const SubsetEnergyType = FunctionType([VectorType(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", [
+    VectorType(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", [
+    VectorType(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(
+ *     [VectorType(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.
+     *
+     * @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));
+     * });
+     * ```
+     */
+    optimize: simanneal_optimize,
+    /**
+     * 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));
+     * });
+     * ```
+     */
+    optimizePermutation: simanneal_optimize_permutation,
+    /**
+     * 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));
+     * });
+     * ```
+     */
+    optimizeSubset: simanneal_optimize_subset,
+    /**
+     * Type definitions for SimAnneal functions.
+     */
+    Types: SimAnnealTypes,
+};
+//# sourceMappingURL=simanneal.js.map

package/dist/src/simanneal/simanneal.js.map

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

package/dist/src/simulation/simulation.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Discrete Event Simulation (DES) — Economic Ontology.
+ *
+ * Provides a generic priority-queue DES engine grounded in an economic ontology:
+ * - R (Resources): user-defined struct representing business state
+ * - E (Events): user-defined variant where each case is an economic activity
+ * - Process handler: defines how events affect resources (match dispatch)
+ *
+ * Entry point:
+ * - `simulation_run`: single deterministic run
+ *
+ * @packageDocumentation
+ */
+import { StructType, OptionType, ArrayType, IntegerType, DateTimeType, FunctionType } from "@elaraai/east";
+/**
+ * Configuration for a single simulation run.
+ */
+export declare const SimulationConfigType: StructType<{
+    /** Safety limit on number of events processed (default: 100000) */
+    readonly max_events: OptionType<IntegerType>;
+    /** Stop processing events after this date */
+    readonly end_date: OptionType<DateTimeType>;
+}>;
+/**
+ * Result of a single simulation run.
+ */
+export declare const SimulationResultType: StructType<{
+    /** Final resource state after all events processed */
+    readonly final_state: "R";
+    /** Number of events processed */
+    readonly events_processed: IntegerType;
+    /** Date of the last event processed */
+    readonly final_date: DateTimeType;
+}>;
+/**
+ * Run a single deterministic discrete event simulation.
+ *
+ * Events are processed in chronological order from a priority queue.
+ * The handler function dispatches on event type (match) and can
+ * mutate state and schedule new events.
+ *
+ * @example
+ * ```ts
+ * import { East, StructType, VariantType, FloatType, DateTimeType, variant } from "@elaraai/east";
+ * import { Simulation } from "@elaraai/east-py-datascience";
+ *
+ * const Resources = StructType({ cash: FloatType });
+ * const Events = VariantType({ income: FloatType, expense: FloatType });
+ *
+ * const process = East.function(
+ *     [Resources, DateTimeType, Events],
+ *     StructType({ state: Resources, events: ArrayType(StructType({ date: DateTimeType, event: Events })) }),
+ *     ($, state, date, event) => {
+ *         return $.return(event.match({
+ *             income: ($, amount) => $.return({ state: state.spread({ cash: state.cash.add(amount) }), events: [] }),
+ *             expense: ($, amount) => $.return({ state: state.spread({ cash: state.cash.subtract(amount) }), events: [] }),
+ *         }));
+ *     }
+ * );
+ *
+ * const result = $.let(Simulation.run([Resources, Events], initialState, initialEvents, process, config));
+ * ```
+ */
+export declare const simulation_run: import("@elaraai/east").GenericPlatformDefinition<readonly ["R", "E"], readonly ["R", ArrayType<StructType<{
+    readonly date: DateTimeType;
+    readonly event: "E";
+}>>, FunctionType<["R", DateTimeType, "E"], StructType<{
+    readonly state: "R";
+    readonly events: ArrayType<StructType<{
+        readonly date: DateTimeType;
+        readonly event: "E";
+    }>>;
+}>>, StructType<{
+    /** Safety limit on number of events processed (default: 100000) */
+    readonly max_events: OptionType<IntegerType>;
+    /** Stop processing events after this date */
+    readonly end_date: OptionType<DateTimeType>;
+}>], StructType<{
+    /** Final resource state after all events processed */
+    readonly final_state: "R";
+    /** Number of events processed */
+    readonly events_processed: IntegerType;
+    /** Date of the last event processed */
+    readonly final_date: DateTimeType;
+}>>;
+/**
+ * Type definitions for simulation functions.
+ */
+export declare const SimulationTypes: {
+    /** Single run configuration */
+    readonly ConfigType: StructType<{
+        /** Safety limit on number of events processed (default: 100000) */
+        readonly max_events: OptionType<IntegerType>;
+        /** Stop processing events after this date */
+        readonly end_date: OptionType<DateTimeType>;
+    }>;
+    /** Single run result */
+    readonly ResultType: StructType<{
+        /** Final resource state after all events processed */
+        readonly final_state: "R";
+        /** Number of events processed */
+        readonly events_processed: IntegerType;
+        /** Date of the last event processed */
+        readonly final_date: DateTimeType;
+    }>;
+};
+/**
+ * Discrete Event Simulation (DES) — REA Economic Ontology.
+ *
+ * Generic over:
+ * - R: Resources (state struct — the economic resource ontology)
+ * - E: Events (variant type — the economic event ontology)
+ *
+ * The handler function uses match dispatch to define economic processes.
+ * Each match branch IS a separate economic process. Process-from-process
+ * triggering works by returning new events.
+ */
+export declare const Simulation: {
+    /**
+     * Run a single deterministic discrete event simulation.
+     *
+     * Events are processed chronologically from a priority queue.
+     * The handler function dispatches on event type via match and can
+     * mutate state and schedule new events (creating the directed
+     * cyclic economic graph).
+     *
+     * @example
+     * ```ts
+     * import { East, StructType, VariantType, ArrayType, FloatType, DateTimeType, variant } from "@elaraai/east";
+     * import { Simulation, SimulationConfigType } from "@elaraai/east-py-datascience";
+     *
+     * const Resources = StructType({ cash: FloatType });
+     * const Events = VariantType({ income: FloatType, expense: FloatType });
+     * const ScheduledEvent = StructType({ date: DateTimeType, event: Events });
+     * const ProcessResult = StructType({ state: Resources, events: ArrayType(ScheduledEvent) });
+     *
+     * const simulate = East.function([], Simulation.Types.ResultType, ($) => {
+     *     const process = East.function(
+     *         [Resources, DateTimeType, Events],
+     *         ProcessResult,
+     *         ($, state, date, event) => {
+     *             const empty = $.let([] as const, ArrayType(ScheduledEvent));
+     *             return $.return(event.match({
+     *                 income: ($, amount) => ({
+     *                     state: { cash: state.cash.add(amount) },
+     *                     events: empty,
+     *                 }),
+     *                 expense: ($, amount) => ({
+     *                     state: { cash: state.cash.subtract(amount) },
+     *                     events: empty,
+     *                 }),
+     *             }));
+     *         }
+     *     );
+     *
+     *     const initialState = $.let({ cash: 1000.0 });
+     *     const initialEvents = $.let([
+     *         { date: $.let(new Date("2025-01-01")), event: $.let(variant("income", 500.0), Events) },
+     *         { date: $.let(new Date("2025-01-15")), event: $.let(variant("expense", 200.0), Events) },
+     *     ], ArrayType(ScheduledEvent));
+     *     const config = $.let({
+     *         max_events: variant("none", null),
+     *         end_date: variant("none", null),
+     *     }, SimulationConfigType);
+     *
+     *     const result = $.let(Simulation.run(
+     *         [Resources, Events],
+     *         initialState, initialEvents, process, config,
+     *     ));
+     *     // result.final_state.cash => 1300.0
+     *     // result.events_processed => 2n
+     *     return $.return(result);
+     * });
+     * ```
+     */
+    readonly run: import("@elaraai/east").GenericPlatformDefinition<readonly ["R", "E"], readonly ["R", ArrayType<StructType<{
+        readonly date: DateTimeType;
+        readonly event: "E";
+    }>>, FunctionType<["R", DateTimeType, "E"], StructType<{
+        readonly state: "R";
+        readonly events: ArrayType<StructType<{
+            readonly date: DateTimeType;
+            readonly event: "E";
+        }>>;
+    }>>, StructType<{
+        /** Safety limit on number of events processed (default: 100000) */
+        readonly max_events: OptionType<IntegerType>;
+        /** Stop processing events after this date */
+        readonly end_date: OptionType<DateTimeType>;
+    }>], StructType<{
+        /** Final resource state after all events processed */
+        readonly final_state: "R";
+        /** Number of events processed */
+        readonly events_processed: IntegerType;
+        /** Date of the last event processed */
+        readonly final_date: DateTimeType;
+    }>>;
+    /**
+     * Type definitions for simulation functions.
+     */
+    readonly Types: {
+        /** Single run configuration */
+        readonly ConfigType: StructType<{
+            /** Safety limit on number of events processed (default: 100000) */
+            readonly max_events: OptionType<IntegerType>;
+            /** Stop processing events after this date */
+            readonly end_date: OptionType<DateTimeType>;
+        }>;
+        /** Single run result */
+        readonly ResultType: StructType<{
+            /** Final resource state after all events processed */
+            readonly final_state: "R";
+            /** Number of events processed */
+            readonly events_processed: IntegerType;
+            /** Date of the last event processed */
+            readonly final_date: DateTimeType;
+        }>;
+    };
+};
+//# sourceMappingURL=simulation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../../src/simulation/simulation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAEH,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACf,MAAM,eAAe,CAAC;AAmCvB;;GAEG;AACH,eAAO,MAAM,oBAAoB;IAC7B,mEAAmE;;IAEnE,6CAA6C;;EAE/C,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;IAC7B,sDAAsD;;IAEtD,iCAAiC;;IAEjC,uCAAuC;;EAEzC,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;IAnDvB,mEAAmE;;IAEnE,6CAA6C;;;IAQ7C,sDAAsD;;IAEtD,iCAAiC;;IAEjC,uCAAuC;;GA+C1C,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,eAAe;IACxB,+BAA+B;;QAvE/B,mEAAmE;;QAEnE,6CAA6C;;;IAuE7C,wBAAwB;;QA/DxB,sDAAsD;;QAEtD,iCAAiC;;QAEjC,uCAAuC;;;CA6DjC,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;;;;;;;;;;;QAjJH,mEAAmE;;QAEnE,6CAA6C;;;QAQ7C,sDAAsD;;QAEtD,iCAAiC;;QAEjC,uCAAuC;;;IAsIvC;;OAEG;;QA/EH,+BAA+B;;YAvE/B,mEAAmE;;YAEnE,6CAA6C;;;QAuE7C,wBAAwB;;YA/DxB,sDAAsD;;YAEtD,iCAAiC;;YAEjC,uCAAuC;;;;CA0IjC,CAAC"}