@iyulab/u-metaheur 0.12.1 → 0.14.0

package/README.md

@@ -78,10 +78,10 @@ assert!((result.best - 3.0).abs() < 0.1);
 
 ```toml
 [dependencies]
-u-metaheur = "0.12"
+u-metaheur = "0.14"
 
 # with serde support
-u-metaheur = { version = "0.12", features = ["serde"] }
+u-metaheur = { version = "0.14", features = ["serde"] }
 ```
 
 ## Build & Test
@@ -123,8 +123,9 @@ re-bundling services fail on the same import. Use a bundler or Node.
 
 ### Quick Start
 
-Both functions solve a travelling-salesman tour over `nodes` (`[x, y]` pairs)
-and return the best tour found and its closed length:
+Both functions run this crate's own runners — `GaRunner` and `SaRunner` — on a
+travelling-salesman tour over `nodes` (`[x, y]` pairs), and return the best tour
+found, its closed length, and why the run stopped:
 
 ```js
 import { run_ga, run_sa } from '@iyulab/u-metaheur';
@@ -132,15 +133,24 @@ import { run_ga, run_sa } from '@iyulab/u-metaheur';
 // The corners of a unit square: the shortest closed tour is its perimeter, 4.
 const nodes = [[0, 0], [1, 0], [1, 1], [0, 1]];
 
-const ga = run_ga({ nodes, population_size: 30, generations: 50 });
-const sa = run_sa({ nodes, iterations: 2000 });
-console.log(ga.best_distance, ga.best_tour); // 4 [ ... ]
+const ga = run_ga({ nodes, population_size: 30, generations: 50, seed: 7 });
+const sa = run_sa({ nodes, iterations: 2000, seed: 7 });
+console.log(ga.best_distance, ga.best_tour, ga.stop_reason); // 4 [ ... ] iteration_limit
 console.log(sa.best_distance, sa.iterations_run);
+
+// The same seed gives the same tour.
+console.log(run_ga({ nodes, population_size: 30, generations: 50, seed: 7 }).best_tour.join() === ga.best_tour.join()); // true
 ```
 
 `run_ga` also takes `mutation_rate`; `run_sa` takes `initial_temp` and
-`cooling_rate`. Every setting is optional except `nodes`, and a setting the
-function does not have is rejected rather than ignored.
+`cooling_rate`. Both take `seed` (a whole number from 0 to 2^64 − 1 — a run that
+ends on its own budget is reproduced exactly) and `time_limit_ms` (at least 1 —
+the run returns the best tour found by then). `stop_reason` is
+`"iteration_limit"` when the run spent its `generations` / `iterations`,
+`"time_limit"` when the clock ran out first, and for `run_sa` `"completed"` when
+the temperature cooled to nothing first. Every setting is optional except
+`nodes`, and a setting the function does not have is rejected rather than
+ignored.
 
 `codes()` returns every refusal `code` the functions throw, with the fields that
 can come with it — `{ refusals: [{ code, fields }], violations: [] }` — built from
@@ -164,7 +174,7 @@ try {
 | `code` | Fields | Meaning |
 |---|---|---|
 | `insufficient_data` | `parameter` (`"nodes"`), `min`, `got` | Fewer than 2 nodes |
-| `parameter_out_of_range` | `parameter`, `min`, `max`, `exclusive_min`, `exclusive_max`, `got` | `population_size < 2`, `generations` or `iterations` below 1 (a negative count included: `population_size: -1` is `{ min: 2, max: null, got: -1 }`, the same as `1`), `initial_temp ≤ 0`, or `cooling_rate` outside (0, 1). `min` / `max` are the closed (included) bounds and are always present — `null` on a side that is open or unbounded; `exclusive_min` / `exclusive_max` are the open (excluded) bounds, present only when that end is open: `initial_temp` (> 0) is refused with `min: null, exclusive_min: 0`, `cooling_rate` with `exclusive_min: 0, exclusive_max: 1` |
+| `parameter_out_of_range` | `parameter`, `min`, `max`, `exclusive_min`, `exclusive_max`, `got` | `population_size < 2`, `generations`, `iterations` or `time_limit_ms` below 1, a `seed` outside 0 to 2^64 − 1 (a negative count included: `population_size: -1` is `{ min: 2, max: null, got: -1 }`, the same as `1`), `initial_temp ≤ 0`, or `cooling_rate` outside (0, 1). `min` / `max` are the closed (included) bounds and are always present — `null` on a side that is open or unbounded; `exclusive_min` / `exclusive_max` are the open (excluded) bounds, present only when that end is open: `initial_temp` (> 0) is refused with `min: null, exclusive_min: 0`, `cooling_rate` with `exclusive_min: 0, exclusive_max: 1` |
 | `value_not_finite` | `parameter`, `index` | A NaN or ±Infinity anywhere in an argument — `parameter` is the path to it (`config.nodes[1]`), `index` its position in that array, or `null` |
 | `malformed_input` | `parameter`, `index` (inside an array) | An argument of the wrong shape or type (a missing or unknown key), a count that is not a whole number (`population_size: 2.5` — `parameter` is the field), or a JSON string |
 | `internal` | — | A result the package could not hand back — a fault in the package, not in the input; please report it |

package/node/u_metaheur.cjs

@@ -18,17 +18,22 @@ function codes() {
 exports.codes = codes;
 
 /**
- * Runs a Genetic Algorithm for TSP.
+ * Runs the crate's genetic algorithm ([`crate::ga::GaRunner`]) on the
+ * travelling-salesman tour over `nodes`: order crossover, swap mutation,
+ * tournament selection, a nearest-neighbour tour in the first population.
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `population_size`: integer (default 100)
- * - `generations`: integer (default 200)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `population_size`: integer (default 100, at least 2)
+ * - `generations`: integer (default 200, at least 1) — run as given
  * - `mutation_rate`: float 0–1 (default 0.05)
+ * - `seed`: whole number 0 to 2^64 − 1 (optional) — reproducible runs
+ * - `time_limit_ms`: whole number, at least 1 (optional)
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `generations_run`.
+ * JS object with `best_distance`, `best_tour`, `generations_run`,
+ * `stop_reason`.
  * @param {GaConfig} config
  * @returns {GaResult}
  */
@@ -42,20 +47,21 @@ function run_ga(config) {
 exports.run_ga = run_ga;
 
 /**
- * Runs Simulated Annealing for TSP.
- *
- * Uses geometric cooling (`T *= cooling_rate` per iteration).
- * Neighbour move: 2-opt segment reversal between two random positions.
+ * Runs the crate's simulated annealing ([`crate::sa::SaRunner`]) on the
+ * travelling-salesman tour over `nodes`, from the nearest-neighbour tour,
+ * with 2-opt moves and geometric cooling (`T *= cooling_rate` per move).
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `initial_temp`: float (default 1000.0)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `initial_temp`: float (default 1000.0, > 0)
  * - `cooling_rate`: float in (0, 1) (default 0.995)
- * - `iterations`: integer (default 5000)
+ * - `iterations`: integer (default 5000, at least 1)
+ * - `seed`, `time_limit_ms`: as `run_ga`'s
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `iterations_run`.
+ * JS object with `best_distance`, `best_tour`, `iterations_run`,
+ * `stop_reason`.
  * @param {SaConfig} config
  * @returns {SaResult}
  */
@@ -120,6 +126,10 @@ function __wbg_get_imports() {
             const ret = typeof(arg0) === 'string';
             return ret;
         },
+        __wbg___wbindgen_is_undefined_8865fb403f8fe9d8: function(arg0) {
+            const ret = arg0 === undefined;
+            return ret;
+        },
         __wbg___wbindgen_jsval_eq_02babf21faa37971: function(arg0, arg1) {
             const ret = arg0 === arg1;
             return ret;
@@ -254,6 +264,14 @@ function __wbg_get_imports() {
             const ret = arg0.next();
             return ret;
         }, arguments); },
+        __wbg_now_e7c6795a7f81e10f: function(arg0) {
+            const ret = arg0.now();
+            return ret;
+        },
+        __wbg_performance_3fcf6e32a7e1ed0a: function(arg0) {
+            const ret = arg0.performance;
+            return ret;
+        },
         __wbg_prototypesetcall_bc27214492979395: function(arg0, arg1, arg2) {
             Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
         },
@@ -267,6 +285,22 @@ function __wbg_get_imports() {
         __wbg_set_bea140a88be9b277: function(arg0, arg1, arg2) {
             arg0[arg1 >>> 0] = arg2;
         },
+        __wbg_static_accessor_GLOBAL_266715b9d96ba635: function() {
+            const ret = typeof global === 'undefined' ? null : global;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_GLOBAL_THIS_10fb7dc1ae063179: function() {
+            const ret = typeof globalThis === 'undefined' ? null : globalThis;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_SELF_0b583911f537483a: function() {
+            const ret = typeof self === 'undefined' ? null : self;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_WINDOW_d7f903d1508cbdc4: function() {
+            const ret = typeof window === 'undefined' ? null : window;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
         __wbg_value_f3c585ee8f5ba40c: function(arg0) {
             const ret = arg0.value;
             return ret;

package/node/u_metaheur.d.cts

@@ -39,12 +39,27 @@ export interface GaConfig {
      */
     generations?: number;
     mutation_rate?: number;
+    /**
+     * RNG seed, a whole number from 0 to 2^64 - 1: the same request and seed
+     * give the same tour when the run ends on its own budget.
+     */
+    seed?: number | null;
+    /**
+     * Wall-clock budget in milliseconds, at least 1: the run returns the best
+     * tour found by then (`stop_reason: "time_limit"`).
+     */
+    time_limit_ms?: number | null;
 }
 
 export interface GaResult {
     best_distance: number;
     best_tour: number[];
     generations_run: number;
+    /**
+     * Why the run stopped: `"iteration_limit"` (it ran its `generations`) or
+     * `"time_limit"`.
+     */
+    stop_reason: "iteration_limit" | "time_limit";
 }
 
 export interface SaConfig {
@@ -55,12 +70,26 @@ export interface SaConfig {
      * At least 1 (`run_sa` checks it; see [`Whole`] for why it is signed).
      */
     iterations?: number;
+    /**
+     * RNG seed, a whole number from 0 to 2^64 - 1 (as `run_ga`'s).
+     */
+    seed?: number | null;
+    /**
+     * Wall-clock budget in milliseconds, at least 1 (as `run_ga`'s).
+     */
+    time_limit_ms?: number | null;
 }
 
 export interface SaResult {
     best_distance: number;
     best_tour: number[];
     iterations_run: number;
+    /**
+     * Why the run stopped: `"iteration_limit"` (it ran its `iterations`),
+     * `"completed"` (the temperature cooled to nothing first) or
+     * `"time_limit"`.
+     */
+    stop_reason: "iteration_limit" | "completed" | "time_limit";
 }
 
 
@@ -74,34 +103,40 @@ export interface SaResult {
 export function codes(): Codes;
 
 /**
- * Runs a Genetic Algorithm for TSP.
+ * Runs the crate's genetic algorithm ([`crate::ga::GaRunner`]) on the
+ * travelling-salesman tour over `nodes`: order crossover, swap mutation,
+ * tournament selection, a nearest-neighbour tour in the first population.
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `population_size`: integer (default 100)
- * - `generations`: integer (default 200)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `population_size`: integer (default 100, at least 2)
+ * - `generations`: integer (default 200, at least 1) — run as given
  * - `mutation_rate`: float 0–1 (default 0.05)
+ * - `seed`: whole number 0 to 2^64 − 1 (optional) — reproducible runs
+ * - `time_limit_ms`: whole number, at least 1 (optional)
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `generations_run`.
+ * JS object with `best_distance`, `best_tour`, `generations_run`,
+ * `stop_reason`.
  */
 export function run_ga(config: GaConfig): GaResult;
 
 /**
- * Runs Simulated Annealing for TSP.
- *
- * Uses geometric cooling (`T *= cooling_rate` per iteration).
- * Neighbour move: 2-opt segment reversal between two random positions.
+ * Runs the crate's simulated annealing ([`crate::sa::SaRunner`]) on the
+ * travelling-salesman tour over `nodes`, from the nearest-neighbour tour,
+ * with 2-opt moves and geometric cooling (`T *= cooling_rate` per move).
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `initial_temp`: float (default 1000.0)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `initial_temp`: float (default 1000.0, > 0)
  * - `cooling_rate`: float in (0, 1) (default 0.995)
- * - `iterations`: integer (default 5000)
+ * - `iterations`: integer (default 5000, at least 1)
+ * - `seed`, `time_limit_ms`: as `run_ga`'s
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `iterations_run`.
+ * JS object with `best_distance`, `best_tour`, `iterations_run`,
+ * `stop_reason`.
  */
 export function run_sa(config: SaConfig): SaResult;

package/package.json

@@ -5,7 +5,7 @@
     "iyulab"
   ],
   "description": "Domain-agnostic metaheuristic optimization framework: GA, BRKGA, SA, ALNS.",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_metaheur.d.ts

@@ -39,12 +39,27 @@ export interface GaConfig {
      */
     generations?: number;
     mutation_rate?: number;
+    /**
+     * RNG seed, a whole number from 0 to 2^64 - 1: the same request and seed
+     * give the same tour when the run ends on its own budget.
+     */
+    seed?: number | null;
+    /**
+     * Wall-clock budget in milliseconds, at least 1: the run returns the best
+     * tour found by then (`stop_reason: "time_limit"`).
+     */
+    time_limit_ms?: number | null;
 }
 
 export interface GaResult {
     best_distance: number;
     best_tour: number[];
     generations_run: number;
+    /**
+     * Why the run stopped: `"iteration_limit"` (it ran its `generations`) or
+     * `"time_limit"`.
+     */
+    stop_reason: "iteration_limit" | "time_limit";
 }
 
 export interface SaConfig {
@@ -55,12 +70,26 @@ export interface SaConfig {
      * At least 1 (`run_sa` checks it; see [`Whole`] for why it is signed).
      */
     iterations?: number;
+    /**
+     * RNG seed, a whole number from 0 to 2^64 - 1 (as `run_ga`'s).
+     */
+    seed?: number | null;
+    /**
+     * Wall-clock budget in milliseconds, at least 1 (as `run_ga`'s).
+     */
+    time_limit_ms?: number | null;
 }
 
 export interface SaResult {
     best_distance: number;
     best_tour: number[];
     iterations_run: number;
+    /**
+     * Why the run stopped: `"iteration_limit"` (it ran its `iterations`),
+     * `"completed"` (the temperature cooled to nothing first) or
+     * `"time_limit"`.
+     */
+    stop_reason: "iteration_limit" | "completed" | "time_limit";
 }
 
 
@@ -74,34 +103,40 @@ export interface SaResult {
 export function codes(): Codes;
 
 /**
- * Runs a Genetic Algorithm for TSP.
+ * Runs the crate's genetic algorithm ([`crate::ga::GaRunner`]) on the
+ * travelling-salesman tour over `nodes`: order crossover, swap mutation,
+ * tournament selection, a nearest-neighbour tour in the first population.
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `population_size`: integer (default 100)
- * - `generations`: integer (default 200)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `population_size`: integer (default 100, at least 2)
+ * - `generations`: integer (default 200, at least 1) — run as given
  * - `mutation_rate`: float 0–1 (default 0.05)
+ * - `seed`: whole number 0 to 2^64 − 1 (optional) — reproducible runs
+ * - `time_limit_ms`: whole number, at least 1 (optional)
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `generations_run`.
+ * JS object with `best_distance`, `best_tour`, `generations_run`,
+ * `stop_reason`.
  */
 export function run_ga(config: GaConfig): GaResult;
 
 /**
- * Runs Simulated Annealing for TSP.
- *
- * Uses geometric cooling (`T *= cooling_rate` per iteration).
- * Neighbour move: 2-opt segment reversal between two random positions.
+ * Runs the crate's simulated annealing ([`crate::sa::SaRunner`]) on the
+ * travelling-salesman tour over `nodes`, from the nearest-neighbour tour,
+ * with 2-opt moves and geometric cooling (`T *= cooling_rate` per move).
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `initial_temp`: float (default 1000.0)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `initial_temp`: float (default 1000.0, > 0)
  * - `cooling_rate`: float in (0, 1) (default 0.995)
- * - `iterations`: integer (default 5000)
+ * - `iterations`: integer (default 5000, at least 1)
+ * - `seed`, `time_limit_ms`: as `run_ga`'s
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `iterations_run`.
+ * JS object with `best_distance`, `best_tour`, `iterations_run`,
+ * `stop_reason`.
  */
 export function run_sa(config: SaConfig): SaResult;

package/u_metaheur_bg.js

@@ -15,17 +15,22 @@ export function codes() {
 }
 
 /**
- * Runs a Genetic Algorithm for TSP.
+ * Runs the crate's genetic algorithm ([`crate::ga::GaRunner`]) on the
+ * travelling-salesman tour over `nodes`: order crossover, swap mutation,
+ * tournament selection, a nearest-neighbour tour in the first population.
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `population_size`: integer (default 100)
- * - `generations`: integer (default 200)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `population_size`: integer (default 100, at least 2)
+ * - `generations`: integer (default 200, at least 1) — run as given
  * - `mutation_rate`: float 0–1 (default 0.05)
+ * - `seed`: whole number 0 to 2^64 − 1 (optional) — reproducible runs
+ * - `time_limit_ms`: whole number, at least 1 (optional)
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `generations_run`.
+ * JS object with `best_distance`, `best_tour`, `generations_run`,
+ * `stop_reason`.
  * @param {GaConfig} config
  * @returns {GaResult}
  */
@@ -38,20 +43,21 @@ export function run_ga(config) {
 }
 
 /**
- * Runs Simulated Annealing for TSP.
- *
- * Uses geometric cooling (`T *= cooling_rate` per iteration).
- * Neighbour move: 2-opt segment reversal between two random positions.
+ * Runs the crate's simulated annealing ([`crate::sa::SaRunner`]) on the
+ * travelling-salesman tour over `nodes`, from the nearest-neighbour tour,
+ * with 2-opt moves and geometric cooling (`T *= cooling_rate` per move).
  *
  * # Arguments
  * `config` — native JS object with fields:
- * - `nodes`: `[[x, y], ...]` (required)
- * - `initial_temp`: float (default 1000.0)
+ * - `nodes`: `[[x, y], ...]` (required, at least 2)
+ * - `initial_temp`: float (default 1000.0, > 0)
  * - `cooling_rate`: float in (0, 1) (default 0.995)
- * - `iterations`: integer (default 5000)
+ * - `iterations`: integer (default 5000, at least 1)
+ * - `seed`, `time_limit_ms`: as `run_ga`'s
  *
  * # Returns
- * JS object with `best_distance`, `best_tour`, `iterations_run`.
+ * JS object with `best_distance`, `best_tour`, `iterations_run`,
+ * `stop_reason`.
  * @param {SaConfig} config
  * @returns {SaResult}
  */
@@ -112,6 +118,10 @@ export function __wbg___wbindgen_is_string_90b56bc79aad6f6c(arg0) {
     const ret = typeof(arg0) === 'string';
     return ret;
 }
+export function __wbg___wbindgen_is_undefined_8865fb403f8fe9d8(arg0) {
+    const ret = arg0 === undefined;
+    return ret;
+}
 export function __wbg___wbindgen_jsval_eq_02babf21faa37971(arg0, arg1) {
     const ret = arg0 === arg1;
     return ret;
@@ -246,6 +256,14 @@ export function __wbg_next_f4aac29c42af995c() { return handleError(function (arg
     const ret = arg0.next();
     return ret;
 }, arguments); }
+export function __wbg_now_e7c6795a7f81e10f(arg0) {
+    const ret = arg0.now();
+    return ret;
+}
+export function __wbg_performance_3fcf6e32a7e1ed0a(arg0) {
+    const ret = arg0.performance;
+    return ret;
+}
 export function __wbg_prototypesetcall_bc27214492979395(arg0, arg1, arg2) {
     Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
 }
@@ -259,6 +277,22 @@ export function __wbg_set_6be42768c690e380(arg0, arg1, arg2) {
 export function __wbg_set_bea140a88be9b277(arg0, arg1, arg2) {
     arg0[arg1 >>> 0] = arg2;
 }
+export function __wbg_static_accessor_GLOBAL_266715b9d96ba635() {
+    const ret = typeof global === 'undefined' ? null : global;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+}
+export function __wbg_static_accessor_GLOBAL_THIS_10fb7dc1ae063179() {
+    const ret = typeof globalThis === 'undefined' ? null : globalThis;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+}
+export function __wbg_static_accessor_SELF_0b583911f537483a() {
+    const ret = typeof self === 'undefined' ? null : self;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+}
+export function __wbg_static_accessor_WINDOW_d7f903d1508cbdc4() {
+    const ret = typeof window === 'undefined' ? null : window;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+}
 export function __wbg_value_f3c585ee8f5ba40c(arg0) {
     const ret = arg0.value;
     return ret;