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

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

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

package/dist/{simanneal → src/simanneal}/simanneal.js

@@ -14,7 +14,7 @@
  *
  * @packageDocumentation
  */
-import { East, StructType, VariantType, OptionType, ArrayType, IntegerType, FloatType, BooleanType, FunctionType, } from "@elaraai/east";
+import { East, StructType, VariantType, OptionType, IntegerType, FloatType, BooleanType, FunctionType, VectorType, } from "@elaraai/east";
 // ===========================================
 // State Types
 // ===========================================
@@ -27,9 +27,9 @@ import { East, StructType, VariantType, OptionType, ArrayType, IntegerType, Floa
  */
 export const DiscreteStateType = VariantType({
     /** Integer array state (permutations, assignments) */
-    int_array: ArrayType(IntegerType),
+    int_array: VectorType(IntegerType),
     /** Boolean array state (subset selection) */
-    bool_array: ArrayType(BooleanType),
+    bool_array: VectorType(BooleanType),
 });
 // ===========================================
 // Function Types
@@ -53,13 +53,13 @@ export const MoveFunctionType = FunctionType([DiscreteStateType], DiscreteStateT
  *
  * Specialized for permutation-based optimization.
  */
-export const PermutationEnergyType = FunctionType([ArrayType(IntegerType)], FloatType);
+export const PermutationEnergyType = FunctionType([VectorType(IntegerType)], FloatType);
 /**
  * Subset energy function type.
  *
  * Specialized for subset selection optimization.
  */
-export const SubsetEnergyType = FunctionType([ArrayType(BooleanType)], FloatType);
+export const SubsetEnergyType = FunctionType([VectorType(BooleanType)], FloatType);
 // ===========================================
 // Configuration Types
 // ===========================================
@@ -128,7 +128,7 @@ export const simanneal_optimize = East.platform("simanneal_optimize", [
  * @returns Result with best permutation and energy
  */
 export const simanneal_optimize_permutation = East.platform("simanneal_optimize_permutation", [
-    ArrayType(IntegerType),
+    VectorType(IntegerType),
     PermutationEnergyType,
     AnnealConfigType,
 ], AnnealResultType);
@@ -144,7 +144,7 @@ export const simanneal_optimize_permutation = East.platform("simanneal_optimize_
  * @returns Result with best selection and energy
  */
 export const simanneal_optimize_subset = East.platform("simanneal_optimize_subset", [
-    ArrayType(BooleanType),
+    VectorType(BooleanType),
     SubsetEnergyType,
     AnnealConfigType,
 ], AnnealResultType);
@@ -190,7 +190,7 @@ export const SimAnnealTypes = {
  *
  * // TSP: minimize total route distance
  * const energy = East.function(
- *     [ArrayType(IntegerType)],
+ *     [VectorType(IntegerType)],
  *     FloatType,
  *     ($, route) => {
  *         // Calculate total route distance
@@ -213,14 +213,111 @@ export const SimAnnealTypes = {
 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,
     /**

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"}

package/dist/src/simulation/simulation.js

@@ -0,0 +1,189 @@
+/**
+ * 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 { East, StructType, OptionType, ArrayType, IntegerType, DateTimeType, FunctionType, } from "@elaraai/east";
+// ============================================================================
+// Internal Helper Types
+// ============================================================================
+/**
+ * Scheduled event — a date + event pair.
+ * Not exported; users construct these inline.
+ */
+const ScheduledEventType = StructType({
+    date: DateTimeType,
+    event: "E",
+});
+/**
+ * Handler return type — new state + new events to schedule.
+ */
+const ProcessResultType = StructType({
+    state: "R",
+    events: ArrayType(ScheduledEventType),
+});
+/**
+ * Handler function type — (state, date, event) -> ProcessResult.
+ */
+const ProcessFnType = FunctionType(["R", DateTimeType, "E"], ProcessResultType);
+// ============================================================================
+// Single Run Types
+// ============================================================================
+/**
+ * Configuration for a single simulation run.
+ */
+export const SimulationConfigType = StructType({
+    /** Safety limit on number of events processed (default: 100000) */
+    max_events: OptionType(IntegerType),
+    /** Stop processing events after this date */
+    end_date: OptionType(DateTimeType),
+});
+/**
+ * Result of a single simulation run.
+ */
+export const SimulationResultType = StructType({
+    /** Final resource state after all events processed */
+    final_state: "R",
+    /** Number of events processed */
+    events_processed: IntegerType,
+    /** Date of the last event processed */
+    final_date: DateTimeType,
+});
+// ============================================================================
+// Platform Functions
+// ============================================================================
+/**
+ * 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 const simulation_run = East.genericPlatform("simulation_run", ["R", "E"], [
+    "R", // initial_state
+    ArrayType(ScheduledEventType), // initial_events
+    ProcessFnType, // process handler
+    SimulationConfigType, // config
+], SimulationResultType);
+// ============================================================================
+// Grouped Export
+// ============================================================================
+/**
+ * Type definitions for simulation functions.
+ */
+export const SimulationTypes = {
+    /** Single run configuration */
+    ConfigType: SimulationConfigType,
+    /** Single run result */
+    ResultType: SimulationResultType,
+};
+/**
+ * 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 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);
+     * });
+     * ```
+     */
+    run: simulation_run,
+    /**
+     * Type definitions for simulation functions.
+     */
+    Types: SimulationTypes,
+};
+//# sourceMappingURL=simulation.js.map

package/dist/src/simulation/simulation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation.js","sourceRoot":"","sources":["../../../src/simulation/simulation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EACH,IAAI,EACJ,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,GACf,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,kBAAkB,GAAG,UAAU,CAAC;IAClC,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,GAAG;CACb,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,iBAAiB,GAAG,UAAU,CAAC;IACjC,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,SAAS,CAAC,kBAAkB,CAAC;CACxC,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,aAAa,GAAG,YAAY,CAC9B,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,EACxB,iBAAiB,CACpB,CAAC;AAEF,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;IAC3C,mEAAmE;IACnE,UAAU,EAAE,UAAU,CAAC,WAAW,CAAC;IACnC,6CAA6C;IAC7C,QAAQ,EAAE,UAAU,CAAC,YAAY,CAAC;CACrC,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;IAC3C,sDAAsD;IACtD,WAAW,EAAE,GAAG;IAChB,iCAAiC;IACjC,gBAAgB,EAAE,WAAW;IAC7B,uCAAuC;IACvC,UAAU,EAAE,YAAY;CAC3B,CAAC,CAAC;AAEH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,eAAe,CAC9C,gBAAgB,EAChB,CAAC,GAAG,EAAE,GAAG,CAAC,EACV;IACI,GAAG,EAA6B,gBAAgB;IAChD,SAAS,CAAC,kBAAkB,CAAC,EAAG,iBAAiB;IACjD,aAAa,EAAmB,kBAAkB;IAClD,oBAAoB,EAAY,SAAS;CAC5C,EACD,oBAAoB,CACvB,CAAC;AAEF,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,+BAA+B;IAC/B,UAAU,EAAE,oBAAoB;IAChC,wBAAwB;IACxB,UAAU,EAAE,oBAAoB;CAC1B,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACH,GAAG,EAAE,cAAc;IAEnB;;OAEG;IACH,KAAK,EAAE,eAAe;CAChB,CAAC"}