@elaraai/east-py-datascience 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/dist/src/alns/alns.d.ts +528 -0
  2. package/dist/src/alns/alns.d.ts.map +1 -0
  3. package/dist/src/alns/alns.js +238 -0
  4. package/dist/src/alns/alns.js.map +1 -0
  5. package/dist/src/google_or/google_or.d.ts +2457 -0
  6. package/dist/src/google_or/google_or.d.ts.map +1 -0
  7. package/dist/src/google_or/google_or.js +547 -0
  8. package/dist/src/google_or/google_or.js.map +1 -0
  9. package/dist/src/gp/gp.d.ts +447 -0
  10. package/dist/src/gp/gp.d.ts.map +1 -0
  11. package/dist/src/gp/gp.js +222 -0
  12. package/dist/src/gp/gp.js.map +1 -0
  13. package/dist/src/index.d.ts +34 -0
  14. package/dist/src/index.d.ts.map +1 -0
  15. package/dist/src/index.js +57 -0
  16. package/dist/src/index.js.map +1 -0
  17. package/dist/src/lightgbm/lightgbm.d.ts +575 -0
  18. package/dist/src/lightgbm/lightgbm.d.ts.map +1 -0
  19. package/dist/src/lightgbm/lightgbm.js +241 -0
  20. package/dist/src/lightgbm/lightgbm.js.map +1 -0
  21. package/dist/src/lightning/lightning.d.ts +1594 -0
  22. package/dist/src/lightning/lightning.d.ts.map +1 -0
  23. package/dist/src/lightning/lightning.js +468 -0
  24. package/dist/src/lightning/lightning.js.map +1 -0
  25. package/dist/src/mads/mads.d.ts +410 -0
  26. package/dist/src/mads/mads.d.ts.map +1 -0
  27. package/dist/src/mads/mads.js +219 -0
  28. package/dist/src/mads/mads.js.map +1 -0
  29. package/dist/src/mapie/mapie.d.ts +3680 -0
  30. package/dist/src/mapie/mapie.d.ts.map +1 -0
  31. package/dist/src/mapie/mapie.js +616 -0
  32. package/dist/src/mapie/mapie.js.map +1 -0
  33. package/dist/src/ngboost/ngboost.d.ts +483 -0
  34. package/dist/src/ngboost/ngboost.d.ts.map +1 -0
  35. package/dist/src/ngboost/ngboost.js +231 -0
  36. package/dist/src/ngboost/ngboost.js.map +1 -0
  37. package/dist/src/optimization/optimization.d.ts +700 -0
  38. package/dist/src/optimization/optimization.d.ts.map +1 -0
  39. package/dist/src/optimization/optimization.js +411 -0
  40. package/dist/src/optimization/optimization.js.map +1 -0
  41. package/dist/src/optuna/optuna.d.ts +857 -0
  42. package/dist/src/optuna/optuna.d.ts.map +1 -0
  43. package/dist/src/optuna/optuna.js +270 -0
  44. package/dist/src/optuna/optuna.js.map +1 -0
  45. package/dist/src/pymc/pymc.d.ts +2932 -0
  46. package/dist/src/pymc/pymc.d.ts.map +1 -0
  47. package/dist/src/pymc/pymc.js +688 -0
  48. package/dist/src/pymc/pymc.js.map +1 -0
  49. package/dist/src/scipy/scipy.d.ts +2205 -0
  50. package/dist/src/scipy/scipy.d.ts.map +1 -0
  51. package/dist/src/scipy/scipy.js +884 -0
  52. package/dist/src/scipy/scipy.js.map +1 -0
  53. package/dist/src/shap/shap.d.ts +4611 -0
  54. package/dist/src/shap/shap.d.ts.map +1 -0
  55. package/dist/src/shap/shap.js +552 -0
  56. package/dist/src/shap/shap.js.map +1 -0
  57. package/dist/src/simanneal/simanneal.d.ts +628 -0
  58. package/dist/src/simanneal/simanneal.d.ts.map +1 -0
  59. package/dist/src/simanneal/simanneal.js +328 -0
  60. package/dist/src/simanneal/simanneal.js.map +1 -0
  61. package/dist/src/simulation/simulation.d.ts +224 -0
  62. package/dist/src/simulation/simulation.d.ts.map +1 -0
  63. package/dist/src/simulation/simulation.js +189 -0
  64. package/dist/src/simulation/simulation.js.map +1 -0
  65. package/dist/src/sklearn/sklearn.d.ts +6362 -0
  66. package/dist/src/sklearn/sklearn.d.ts.map +1 -0
  67. package/dist/src/sklearn/sklearn.js +1508 -0
  68. package/dist/src/sklearn/sklearn.js.map +1 -0
  69. package/dist/src/torch/torch.d.ts +1205 -0
  70. package/dist/src/torch/torch.d.ts.map +1 -0
  71. package/dist/src/torch/torch.js +440 -0
  72. package/dist/src/torch/torch.js.map +1 -0
  73. package/dist/src/types.d.ts +43 -0
  74. package/dist/src/types.d.ts.map +1 -0
  75. package/dist/src/types.js +44 -0
  76. package/dist/src/types.js.map +1 -0
  77. package/dist/src/xgboost/xgboost.d.ts +1424 -0
  78. package/dist/src/xgboost/xgboost.d.ts.map +1 -0
  79. package/dist/src/xgboost/xgboost.js +432 -0
  80. package/dist/src/xgboost/xgboost.js.map +1 -0
  81. package/package.json +3 -3
@@ -0,0 +1 @@
1
+ {"version":3,"file":"optimization.d.ts","sourceRoot":"","sources":["../../../src/optimization/optimization.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,411 @@
1
+ /**
2
+ * Copyright (c) 2025 Elara AI Pty Ltd
3
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
4
+ */
5
+ /**
6
+ * Iterative coordinate descent optimization for discrete combinatorial problems.
7
+ *
8
+ * Provides element-wise optimization over vectors of discrete integer values.
9
+ * Each element is independently optimized by trying all candidate values
10
+ * while holding other elements fixed. Multi-start sampling improves
11
+ * exploration of the search space.
12
+ *
13
+ * Ported from the Julia IterativeDecisionAlgorithm (ArrayParameterSpace branch).
14
+ *
15
+ * @packageDocumentation
16
+ */
17
+ import { East, StructType, VariantType, OptionType, ArrayType, VectorType, IntegerType, BooleanType, FloatType, NullType, FunctionType, } from "@elaraai/east";
18
+ // ============================================================================
19
+ // Type Definitions
20
+ // ============================================================================
21
+ /** Parameter vector: Vector<Integer> */
22
+ export const ParameterVectorType = VectorType(IntegerType);
23
+ /** Objective function: Vector<Integer> -> Float */
24
+ export const IterativeObjectiveType = FunctionType([ParameterVectorType], FloatType);
25
+ /** Per-element contribution function: (Vector<Integer>, Integer) -> Float */
26
+ export const ElementObjectiveType = FunctionType([ParameterVectorType, IntegerType], FloatType);
27
+ /** Per-element candidate spaces: Array<Vector<Integer>> */
28
+ export const ParameterSpacesType = ArrayType(ParameterVectorType);
29
+ /**
30
+ * Initial value strategy for parameters.
31
+ *
32
+ * - `first`: Use the first candidate value from each space
33
+ * - `random`: Randomly select from each space
34
+ */
35
+ export const InitialStrategyType = VariantType({
36
+ first: NullType,
37
+ random: NullType,
38
+ });
39
+ /**
40
+ * Evaluation order for candidate values within each element's space.
41
+ *
42
+ * - `sequential`: Try candidates in the order they appear
43
+ * - `random`: Shuffle candidates before trying
44
+ */
45
+ export const EvaluationOrderType = VariantType({
46
+ sequential: NullType,
47
+ random: NullType,
48
+ });
49
+ /**
50
+ * Optimization mode.
51
+ *
52
+ * - `coordinate`: Standard coordinate descent — optimize each element independently (default)
53
+ * - `swap`: Swap-based moves — swap pairs of elements, preserving valid permutations
54
+ */
55
+ export const ModeType = VariantType({
56
+ coordinate: NullType,
57
+ swap: NullType,
58
+ });
59
+ /**
60
+ * Configuration for iterative optimization.
61
+ *
62
+ * All fields are optional with sensible defaults.
63
+ */
64
+ export const IterativeConfigType = StructType({
65
+ /** Maximum coordinate descent iterations per sample (default: 100) */
66
+ iterations: OptionType(IntegerType),
67
+ /** Number of independent restarts (default: 1) */
68
+ samples: OptionType(IntegerType),
69
+ /** How to initialize parameter values (default: first) */
70
+ initial: OptionType(InitialStrategyType),
71
+ /** Order to evaluate candidates (default: sequential) */
72
+ order: OptionType(EvaluationOrderType),
73
+ /** Random seed for reproducibility */
74
+ random_state: OptionType(IntegerType),
75
+ /** Optimization mode: coordinate (default) or swap for permutations */
76
+ mode: OptionType(ModeType),
77
+ });
78
+ /**
79
+ * Result of iterative optimization.
80
+ */
81
+ export const IterativeResultType = StructType({
82
+ /** Best parameter values found */
83
+ best_parameters: ParameterVectorType,
84
+ /** Objective value at best parameters */
85
+ best_objective: FloatType,
86
+ /** Total coordinate descent iterations across all samples */
87
+ iterations: IntegerType,
88
+ /** Total number of objective evaluations */
89
+ evaluations: IntegerType,
90
+ /** Whether optimization succeeded */
91
+ success: BooleanType,
92
+ });
93
+ // ============================================================================
94
+ // Platform Functions
95
+ // ============================================================================
96
+ /**
97
+ * Iterative optimization over integer parameter vectors.
98
+ *
99
+ * Maximizes an objective function over a vector of discrete integer parameters.
100
+ * Each parameter position has its own set of candidate values (vector).
101
+ *
102
+ * Two modes are available:
103
+ * - **coordinate** (default): Coordinate descent — optimizes each element independently
104
+ * by trying all candidate values while holding others fixed. Best for assignment problems
105
+ * where each position can take any value independently.
106
+ * - **swap**: Swap-based moves — swaps pairs of elements, preserving valid permutations.
107
+ * Use this for permutation problems (scheduling, ordering) where each value must appear
108
+ * exactly once.
109
+ *
110
+ * @example Coordinate mode (assignment)
111
+ * ```ts
112
+ * const config = $.let({
113
+ * iterations: variant('some', 10n),
114
+ * samples: variant('some', 3n),
115
+ * initial: variant('some', variant('random', null)),
116
+ * order: variant('some', variant('sequential', null)),
117
+ * random_state: variant('some', 42n),
118
+ * mode: variant('none', null), // coordinate is the default
119
+ * });
120
+ * const result = $.let(Optimization.iterative(objective, spaces, config));
121
+ * ```
122
+ *
123
+ * @example Swap mode (permutation)
124
+ * ```ts
125
+ * const config = $.let({
126
+ * iterations: variant('some', 50n),
127
+ * samples: variant('some', 10n),
128
+ * initial: variant('some', variant('random', null)),
129
+ * order: variant('some', variant('random', null)),
130
+ * random_state: variant('some', 42n),
131
+ * mode: variant('some', variant('swap', null)),
132
+ * });
133
+ * const result = $.let(Optimization.iterative(objective, spaces, config));
134
+ * ```
135
+ */
136
+ export const optimization_iterative = East.platform("optimization_iterative", [
137
+ IterativeObjectiveType, // objective: Vector<Integer> -> Float
138
+ ParameterSpacesType, // parameter_spaces: Array<Vector<Integer>>
139
+ IterativeConfigType, // config
140
+ ], IterativeResultType);
141
+ /**
142
+ * Incremental iterative optimization over integer parameter vectors.
143
+ *
144
+ * Like {@link optimization_iterative}, but takes a **per-element contribution function**
145
+ * instead of a full objective. The optimizer maintains a running sum and only
146
+ * recomputes contributions for changed indices — dramatically faster when
147
+ * individual moves affect only a small part of the total cost.
148
+ *
149
+ * The total objective is `sum(elementObjective(vector, i) for all i)`.
150
+ *
151
+ * Two modes are available:
152
+ * - **coordinate** (default): When changing element `i`, recomputes 1 contribution.
153
+ * - **swap**: When swapping elements `i` and `j`, recomputes 2 contributions.
154
+ *
155
+ * @example Incremental rostering
156
+ * ```ts
157
+ * // Per-person cost: only recomputes the changed person
158
+ * const elementObjective = East.function(
159
+ * [VectorType(IntegerType), IntegerType], FloatType,
160
+ * ($, assignments, personIdx) => {
161
+ * const role = $.let(assignments.get(personIdx));
162
+ * return $.return(salaryLookup.get(personIdx).get(role).negate());
163
+ * }
164
+ * );
165
+ * const result = $.let(Optimization.iterativeIncremental(
166
+ * elementObjective, spaces, config
167
+ * ));
168
+ * ```
169
+ */
170
+ export const optimization_iterative_incremental = East.platform("optimization_iterative_incremental", [
171
+ ElementObjectiveType, // elementObjective: (Vector<Integer>, Integer) -> Float
172
+ ParameterSpacesType, // parameter_spaces: Array<Vector<Integer>>
173
+ IterativeConfigType, // config
174
+ ], IterativeResultType);
175
+ /**
176
+ * Group-based incremental iterative optimization.
177
+ *
178
+ * Like {@link optimization_iterative_incremental}, but contributions are grouped
179
+ * by **value** rather than by index. The group objective receives the full vector
180
+ * and a group key (a value that appears in the vector), and returns the total
181
+ * contribution of all elements assigned to that group.
182
+ *
183
+ * When element `i` changes from value A to value B, only 2 groups are recomputed:
184
+ * `groupObjective(vector, A)` and `groupObjective(vector, B)`.
185
+ *
186
+ * Use this when cost is associated with values (e.g., employees, bins, vehicles)
187
+ * rather than positions (e.g., slots, items, stops).
188
+ *
189
+ * @example Rostering — slot → employee assignment
190
+ * ```ts
191
+ * const groupObjective = East.function(
192
+ * [VectorType(IntegerType), IntegerType], FloatType,
193
+ * ($, slotAssignments, employeeId) => {
194
+ * const cost = $.let(0.0);
195
+ * $.for(East.Array.range(0n, nSlots), ($, slot) => {
196
+ * $.if(East.equal(slotAssignments.get(slot), employeeId), $ => {
197
+ * $.assign(cost, cost.add(shiftRates.get(slot)));
198
+ * });
199
+ * });
200
+ * return $.return(cost.negate());
201
+ * }
202
+ * );
203
+ * const result = $.let(Optimization.iterativeGrouped(
204
+ * groupObjective, spaces, config
205
+ * ));
206
+ * ```
207
+ */
208
+ export const optimization_iterative_grouped = East.platform("optimization_iterative_grouped", [
209
+ ElementObjectiveType, // groupObjective: (Vector<Integer>, Integer) -> Float
210
+ ParameterSpacesType, // parameter_spaces: Array<Vector<Integer>>
211
+ IterativeConfigType, // config
212
+ ], IterativeResultType);
213
+ // ============================================================================
214
+ // Grouped Export
215
+ // ============================================================================
216
+ /**
217
+ * Type definitions for iterative optimization.
218
+ */
219
+ export const OptimizationTypes = {
220
+ /** Parameter vector type */
221
+ ParameterVectorType,
222
+ /** Objective function type */
223
+ ObjectiveType: IterativeObjectiveType,
224
+ /** Per-element contribution function type */
225
+ ElementObjectiveType,
226
+ /** Parameter spaces type */
227
+ SpacesType: ParameterSpacesType,
228
+ /** Initial value strategy variant */
229
+ InitialStrategyType,
230
+ /** Evaluation order variant */
231
+ EvaluationOrderType,
232
+ /** Optimization mode variant */
233
+ ModeType,
234
+ /** Configuration type */
235
+ ConfigType: IterativeConfigType,
236
+ /** Result type */
237
+ ResultType: IterativeResultType,
238
+ };
239
+ /**
240
+ * Iterative optimization for discrete combinatorial problems.
241
+ *
242
+ * Supports two modes:
243
+ * - **coordinate** (default): Element-wise coordinate descent. Best for
244
+ * assignment problems where positions are independent.
245
+ * - **swap**: Pair-wise swap moves preserving permutations. Best for
246
+ * scheduling/ordering where each value must appear exactly once.
247
+ *
248
+ * Use cases:
249
+ * - Task-worker assignment (coordinate mode)
250
+ * - Scheduling and ordering (swap mode)
251
+ * - Combinatorial selection problems
252
+ * - Any discrete optimization with per-element candidate sets
253
+ */
254
+ export const Optimization = {
255
+ /**
256
+ * Iterative optimization over integer parameter vectors.
257
+ *
258
+ * `Optimization.iterative(objective, spaces, config)`
259
+ *
260
+ * @example Coordinate mode — task-worker assignment
261
+ * ```ts
262
+ * // 3 tasks, 2 workers. Maximize total skill match.
263
+ * const skill = $.let([[3.0, 1.0], [1.0, 3.0], [2.0, 2.0]]);
264
+ * const objective = East.function(
265
+ * [VectorType(IntegerType)], FloatType,
266
+ * ($, assignments) => {
267
+ * const total = $.let(0.0);
268
+ * $.for(East.Array.range(0n, East.value(3n)), ($, i) => {
269
+ * $.assign(total, total.add(skill.get(i).get(assignments.get(i))));
270
+ * });
271
+ * return $.return(total);
272
+ * }
273
+ * );
274
+ * const spaces = $.let([
275
+ * new BigInt64Array([0n, 1n]),
276
+ * new BigInt64Array([0n, 1n]),
277
+ * new BigInt64Array([0n, 1n]),
278
+ * ]);
279
+ * const config = $.let({
280
+ * iterations: variant('some', 10n),
281
+ * samples: variant('some', 3n),
282
+ * initial: variant('some', variant('random', null)),
283
+ * order: variant('some', variant('sequential', null)),
284
+ * random_state: variant('some', 42n),
285
+ * mode: variant('none', null),
286
+ * });
287
+ * const result = $.let(Optimization.iterative(objective, spaces, config));
288
+ * // result.best_objective = 8.0 (task 0→worker 0, task 1→worker 1, task 2→either)
289
+ * ```
290
+ *
291
+ * @example Swap mode — scheduling permutation
292
+ * ```ts
293
+ * // 4 jobs: find execution order minimizing weighted completion time.
294
+ * const durations = $.let([10.0, 5.0, 20.0, 3.0]);
295
+ * const values = $.let([1.0, 8.0, 2.0, 10.0]);
296
+ * const objective = East.function(
297
+ * [VectorType(IntegerType)], FloatType,
298
+ * ($, perm) => {
299
+ * const cum = $.let(0.0);
300
+ * const total = $.let(0.0);
301
+ * $.for(East.Array.range(0n, East.value(4n)), ($, i) => {
302
+ * const idx = $.let(perm.get(i));
303
+ * $.assign(cum, cum.add(durations.get(idx)));
304
+ * $.assign(total, total.add(values.get(idx).multiply(cum)));
305
+ * });
306
+ * return $.return(total.negate());
307
+ * }
308
+ * );
309
+ * const spaces = $.let([
310
+ * new BigInt64Array([0n, 1n, 2n, 3n]),
311
+ * new BigInt64Array([0n, 1n, 2n, 3n]),
312
+ * new BigInt64Array([0n, 1n, 2n, 3n]),
313
+ * new BigInt64Array([0n, 1n, 2n, 3n]),
314
+ * ]);
315
+ * const config = $.let({
316
+ * iterations: variant('some', 50n),
317
+ * samples: variant('some', 10n),
318
+ * initial: variant('some', variant('random', null)),
319
+ * order: variant('some', variant('random', null)),
320
+ * random_state: variant('some', 42n),
321
+ * mode: variant('some', variant('swap', null)),
322
+ * });
323
+ * const result = $.let(Optimization.iterative(objective, spaces, config));
324
+ * // result.best_objective = -188.0 (optimal WSPT order)
325
+ * ```
326
+ */
327
+ iterative: optimization_iterative,
328
+ /**
329
+ * Incremental iterative optimization with per-element contributions.
330
+ *
331
+ * `Optimization.iterativeIncremental(elementObjective, spaces, config)`
332
+ *
333
+ * Takes a per-element contribution function `(Vector<Integer>, Integer) -> Float`
334
+ * instead of a full objective. The total objective is the sum of all element
335
+ * contributions. Only recomputes contributions for changed indices during search.
336
+ *
337
+ * Use this when individual moves (coordinate or swap) affect only a small
338
+ * part of the total cost — e.g., rostering where changing one person's
339
+ * allocation only changes that person's salary.
340
+ *
341
+ * @example Incremental task-worker assignment
342
+ * ```ts
343
+ * // Per-task skill score: only recomputes the changed task
344
+ * const skill = $.let([[3.0, 1.0], [1.0, 3.0], [2.0, 2.0]]);
345
+ * const elementObjective = East.function(
346
+ * [VectorType(IntegerType), IntegerType], FloatType,
347
+ * ($, assignments, taskIdx) => {
348
+ * const worker = $.let(assignments.get(taskIdx));
349
+ * return $.return(skill.get(taskIdx).get(worker));
350
+ * }
351
+ * );
352
+ * const spaces = $.let([
353
+ * new BigInt64Array([0n, 1n]),
354
+ * new BigInt64Array([0n, 1n]),
355
+ * new BigInt64Array([0n, 1n]),
356
+ * ]);
357
+ * const config = $.let({
358
+ * iterations: variant('some', 10n),
359
+ * samples: variant('some', 3n),
360
+ * initial: variant('some', variant('random', null)),
361
+ * order: variant('some', variant('sequential', null)),
362
+ * random_state: variant('some', 42n),
363
+ * mode: variant('none', null),
364
+ * });
365
+ * const result = $.let(Optimization.iterativeIncremental(
366
+ * elementObjective, spaces, config
367
+ * ));
368
+ * // result.best_objective = 8.0 (same result, fewer evaluations)
369
+ * ```
370
+ */
371
+ iterativeIncremental: optimization_iterative_incremental,
372
+ /**
373
+ * Group-based incremental optimization with per-value contributions.
374
+ *
375
+ * `Optimization.iterativeGrouped(groupObjective, spaces, config)`
376
+ *
377
+ * Takes a group objective `(Vector<Integer>, Integer) -> Float` where the
378
+ * second argument is a **value** (group key), not an index. Returns the total
379
+ * contribution of all elements assigned to that value.
380
+ *
381
+ * When element `i` changes from value A to B, recomputes only groups A and B.
382
+ * Use this when cost is per-value (employee, bin, vehicle) not per-position.
383
+ *
384
+ * @example Group-based task assignment
385
+ * ```ts
386
+ * // 6 tasks assigned to workers 0-2. Cost = per-worker total.
387
+ * const taskCosts = $.let([10.0, 20.0, 15.0, 25.0, 30.0, 5.0]);
388
+ * const groupObjective = East.function(
389
+ * [VectorType(IntegerType), IntegerType], FloatType,
390
+ * ($, assignments, workerId) => {
391
+ * const total = $.let(0.0);
392
+ * $.for(East.Array.range(0n, East.value(6n)), ($, task) => {
393
+ * $.if(East.equal(assignments.get(task), workerId), $ => {
394
+ * $.assign(total, total.add(taskCosts.get(task)));
395
+ * });
396
+ * });
397
+ * return $.return(total.negate());
398
+ * }
399
+ * );
400
+ * const result = $.let(Optimization.iterativeGrouped(
401
+ * groupObjective, spaces, config
402
+ * ));
403
+ * ```
404
+ */
405
+ iterativeGrouped: optimization_iterative_grouped,
406
+ /**
407
+ * Type definitions for optimization functions.
408
+ */
409
+ Types: OptimizationTypes,
410
+ };
411
+ //# sourceMappingURL=optimization.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"optimization.js","sourceRoot":"","sources":["../../../src/optimization/optimization.ts"],"names":[],"mappings":"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"}