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

package/dist/src/simulation/simulation.js

@@ -0,0 +1,306 @@
+/**
+ * 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)
+ *
+ * Two entry points:
+ * - `simulation_run`: single deterministic run
+ * - `simulation_run_trajectories`: Monte Carlo with multiple seeds
+ *
+ * @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,
+});
+// ============================================================================
+// Monte Carlo Types
+// ============================================================================
+/**
+ * Configuration for Monte Carlo simulation trajectories.
+ */
+export const SimulationTrajectoriesConfigType = StructType({
+    /** Number of trajectories to run (required) */
+    trajectories: IntegerType,
+    /** Base RNG seed — trajectory i uses seed + i */
+    seed: OptionType(IntegerType),
+    /** Safety limit on events per trajectory (default: 100000) */
+    max_events: OptionType(IntegerType),
+    /** Stop processing events after this date */
+    end_date: OptionType(DateTimeType),
+});
+/**
+ * Result of Monte Carlo simulation trajectories.
+ */
+export const SimulationTrajectoriesResultType = StructType({
+    /** Array of per-trajectory results */
+    trajectories: ArrayType(StructType({
+        /** Final resource state */
+        final_state: "R",
+        /** Number of events processed */
+        events_processed: IntegerType,
+        /** Date of 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);
+/**
+ * Run Monte Carlo simulation trajectories.
+ *
+ * Each trajectory runs the same DES engine with a different RNG seed
+ * (base_seed + trajectory_index), enabling stochastic scenario analysis.
+ *
+ * @example
+ * ```ts
+ * const result = $.let(Simulation.runTrajectories(
+ *     [Resources, Events],
+ *     initialState, initialEvents, stochasticProcess,
+ *     { trajectories: 100n, seed: variant('some', 42n), max_events: variant('none', null), end_date: variant('none', null) },
+ * ));
+ * result.trajectories.get(0n).final_state.cash
+ * ```
+ */
+export const simulation_run_trajectories = East.genericPlatform("simulation_run_trajectories", ["R", "E"], [
+    "R", // initial_state
+    ArrayType(ScheduledEventType), // initial_events
+    ProcessFnType, // process handler
+    SimulationTrajectoriesConfigType, // config
+], SimulationTrajectoriesResultType);
+// ============================================================================
+// Grouped Export
+// ============================================================================
+/**
+ * Type definitions for simulation functions.
+ */
+export const SimulationTypes = {
+    /** Single run configuration */
+    ConfigType: SimulationConfigType,
+    /** Single run result */
+    ResultType: SimulationResultType,
+    /** Monte Carlo configuration */
+    TrajectoriesConfigType: SimulationTrajectoriesConfigType,
+    /** Monte Carlo result */
+    TrajectoriesResultType: SimulationTrajectoriesResultType,
+};
+/**
+ * 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,
+    /**
+     * Run Monte Carlo simulation trajectories.
+     *
+     * Each trajectory runs the same DES engine with a different RNG seed
+     * (base_seed + trajectory_index), enabling stochastic scenario analysis.
+     * Use this when the process handler uses Random functions — each trajectory
+     * gets a deterministic but distinct seed.
+     *
+     * @example
+     * ```ts
+     * import { East, StructType, VariantType, ArrayType, FloatType, DateTimeType, variant } from "@elaraai/east";
+     * import { Simulation, SimulationTrajectoriesConfigType } 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.TrajectoriesResultType, ($) => {
+     *     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({
+     *         trajectories: 100n,
+     *         seed: variant("some", 42n),
+     *         max_events: variant("none", null),
+     *         end_date: variant("some", new Date("2025-12-31")),
+     *     }, SimulationTrajectoriesConfigType);
+     *
+     *     const result = $.let(Simulation.runTrajectories(
+     *         [Resources, Events],
+     *         initialState, initialEvents, process, config,
+     *     ));
+     *     // result.trajectories.length() => 100n
+     *     // result.trajectories.get(0n).final_state.cash
+     *     return $.return(result);
+     * });
+     * ```
+     */
+    runTrajectories: simulation_run_trajectories,
+    /**
+     * 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":"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"}