optimization-test-functions 1.0.0 → 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 (5) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +45 -10
  3. package/package.json +28 -28
  4. package/src/index.d.ts +93 -81
  5. package/src/index.js +660 -386
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Mark Colley
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Colley
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,8 +1,14 @@
1
1
  # optimization-test-functions
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/optimization-test-functions.svg)](https://www.npmjs.com/package/optimization-test-functions)
4
+ [![CI](https://github.com/M-Colley/optimization-test-functions/actions/workflows/ci.yml/badge.svg)](https://github.com/M-Colley/optimization-test-functions/actions/workflows/ci.yml)
5
+ [![license](https://img.shields.io/npm/l/optimization-test-functions.svg)](./LICENSE)
6
+
3
7
  Standard global-optimization benchmarks and classical psychophysical laws, in
4
8
  JavaScript. No dependencies, no build step, ESM.
5
9
 
10
+ **On npm:** <https://www.npmjs.com/package/optimization-test-functions>
11
+
6
12
  Every function ships with the metadata you need to use it correctly: the domain
7
13
  it is actually defined on, its known optimum, and which direction is the
8
14
  interesting one.
@@ -58,7 +64,7 @@ law states — Hick–Hyman returns a reaction time, so lower is better, and
58
64
  | `branin` | 2 | `[-5, 10] × [0, 15]` | `0.397887`, three times |
59
65
  | `rosenbrock` | ≥ 2 | `[-5, 10]ᵈ` | `0` at all-ones |
60
66
  | `rastrigin` | any | `[-5.12, 5.12]ᵈ` | `0` at the origin |
61
- | `michalewicz` | any | `[0, π]ᵈ` | d-dependent |
67
+ | `michalewicz` | any | `[0, π]ᵈ` | d-dependent; exact for d ≤ 10 |
62
68
 
63
69
  ### Classical psychophysical laws
64
70
 
@@ -84,8 +90,8 @@ shekel.meta;
84
90
  // name: 'Shekel', dims: 4, sense: 'min',
85
91
  // domain: d => [[0, 10], [0, 10], [0, 10], [0, 10]],
86
92
  // optimum: {
87
- // value: -10.53644315348353,
88
- // at: () => [4.0007468671, 3.9995094806, 4.00074687, 3.9995094776],
93
+ // value: -10.536443153483528,
94
+ // at: () => [4.000746868270634, 3.9995094800857736, 4.000746868270634, 3.9995094800857736],
89
95
  // approx: [4, 4, 4, 4],
90
96
  // note: 'for m = 10',
91
97
  // },
@@ -95,9 +101,27 @@ shekel.meta;
95
101
 
96
102
  Shekel is a good example of why the metadata is worth having. Its minimum is
97
103
  almost always quoted at `(4, 4, 4, 4)`, but that is only approximate — the
98
- neighbouring wells pull it slightly off, and `f(4,4,4,4) = -10.536283`, not
104
+ neighbouring wells pull it slightly off, and `f(4,4,4,4) = -10.536284`, not
99
105
  `-10.536443`. Both the quoted and the refined location are recorded.
100
106
 
107
+ Every stated optimum is re-derived at 50 significant digits rather than copied,
108
+ which matters more than it sounds. Some widely circulated values are wrong:
109
+
110
+ | function | commonly quoted | true minimum, these constants |
111
+ |---|---|---|
112
+ | `hartmann3` | `-3.86278214782076` at `(0.114614, 0.555649, 0.852547)` | `-3.8627797873326624` at `(0.1145889, 0.5556489, 0.8525470)` |
113
+ | `hartmann6` | `-3.322368011391339` | `-3.3223680114155147` |
114
+
115
+ The quoted Hartmann-3 value is 2.4e-6 *below* the true minimum, so no point
116
+ attains it, and simple regret measured against it can never reach zero. The
117
+ quoted Hartmann-6 value is the function at the rounded six-digit location, not
118
+ the minimum. Where a commonly quoted location differs from the true one, it is
119
+ kept as `optimum.approx`.
120
+
121
+ Michalewicz is separable, so its d-dimensional minimum is exactly the sum of
122
+ one-dimensional minima. `michalewicz.meta.optimum.known` gives it for every
123
+ `d` from 1 to 10, not only the usual three.
124
+
101
125
  ## Optional parameters
102
126
 
103
127
  ```js
@@ -127,20 +151,30 @@ evaluated on the wrong box.
127
151
 
128
152
  ## Correctness
129
153
 
130
- Two independent checks, both run in CI:
154
+ Three independent checks, all run in CI:
131
155
 
132
- - `npm test` — 11 suites. Verifies that every stated optimum is actually
133
- attained at its stated location, and that 200 000 random samples inside each
134
- domain fail to beat it. Also covers dimension validation, `negate`, and the
156
+ - `npm test` — 13 tests. Verifies that every stated optimum is attained at its
157
+ stated location to within a few ulps, that compass search started there
158
+ finds nothing better, and that 200 000 random points inside each domain fail
159
+ to beat it. Checks every tabulated Michalewicz optimum by solving the
160
+ separable problem directly. Also covers dimension validation, `negate`
161
+ (which flips the optimum and monotonicity along with the sense), and the
135
162
  per-axis domain mapping.
163
+ - `python test/crosscheck_optima.py` — re-derives every stated optimum and its
164
+ location at 50 significant digits with [mpmath](https://mpmath.org), from the
165
+ exact decimal constants, and fails if the library disagrees by more than a
166
+ few ulps in value or 1e-9 in location.
136
167
  - `python test/crosscheck_botorch.py` — compares **308 values across 11
137
168
  functions** against [BoTorch](https://botorch.org)'s `test_functions.synthetic`,
138
169
  the reference implementation most of the Bayesian-optimization field uses.
139
170
 
140
171
  | function | max relative difference |
141
172
  |---|---|
142
- | `ackley`, `eggholder`, `powell`, `rosenbrock`, `rastrigin` | `0` exactly |
173
+ | `eggholder`, `rosenbrock` | `0` exactly |
174
+ | `rastrigin` | `1.9e-16` |
175
+ | `powell` | `2.3e-16` |
143
176
  | `griewank` | `3.5e-16` |
177
+ | `ackley` | `4.4e-16` |
144
178
  | `branin` | `5.5e-16` |
145
179
  | `michalewicz` | `2.2e-15` |
146
180
  | `shekel` | `5.8e-09` |
@@ -154,7 +188,8 @@ Two independent checks, both run in CI:
154
188
  fails on BoTorch's precision, not on ours.
155
189
 
156
190
  Schwefel is not in BoTorch, and the psychophysical laws are not optimization
157
- benchmarks, so those five are checked by the JS suite only.
191
+ benchmarks, so those five are not in the BoTorch comparison. Schwefel's optimum
192
+ is in the mpmath check; the psychophysical laws are checked by the JS suite.
158
193
 
159
194
  ## Notes
160
195
 
package/package.json CHANGED
@@ -1,28 +1,28 @@
1
- {
2
- "name": "optimization-test-functions",
3
- "version": "1.0.0",
4
- "description": "Canonical global-optimization benchmarks and classical psychophysical laws, with per-axis domains and known optima. Zero dependencies.",
5
- "keywords": [
6
- "optimization", "benchmark", "test-functions", "global-optimization",
7
- "ackley", "rastrigin", "rosenbrock", "griewank", "hartmann", "branin",
8
- "schwefel", "shekel", "michalewicz", "eggholder", "powell",
9
- "bayesian-optimization", "psychophysics", "hci", "fitts", "hick", "stevens"
10
- ],
11
- "type": "module",
12
- "main": "./src/index.js",
13
- "exports": {
14
- ".": { "types": "./src/index.d.ts", "default": "./src/index.js" }
15
- },
16
- "types": "./src/index.d.ts",
17
- "files": ["src/"],
18
- "sideEffects": false,
19
- "engines": { "node": ">=18" },
20
- "scripts": {
21
- "test": "node --test"
22
- },
23
- "license": "MIT",
24
- "author": "Mark Colley",
25
- "repository": { "type": "git", "url": "git+https://github.com/M-Colley/optimization-test-functions.git" },
26
- "bugs": { "url": "https://github.com/M-Colley/optimization-test-functions/issues" },
27
- "homepage": "https://github.com/M-Colley/optimization-test-functions#readme"
28
- }
1
+ {
2
+ "name": "optimization-test-functions",
3
+ "version": "1.0.2",
4
+ "description": "Canonical global-optimization benchmarks and classical psychophysical laws, with per-axis domains and known optima. Zero dependencies.",
5
+ "keywords": [
6
+ "optimization", "benchmark", "test-functions", "global-optimization",
7
+ "ackley", "rastrigin", "rosenbrock", "griewank", "hartmann", "branin",
8
+ "schwefel", "shekel", "michalewicz", "eggholder", "powell",
9
+ "bayesian-optimization", "psychophysics", "hci", "hick", "stevens"
10
+ ],
11
+ "type": "module",
12
+ "main": "./src/index.js",
13
+ "exports": {
14
+ ".": { "types": "./src/index.d.ts", "default": "./src/index.js" }
15
+ },
16
+ "types": "./src/index.d.ts",
17
+ "files": ["src/"],
18
+ "sideEffects": false,
19
+ "engines": { "node": ">=18" },
20
+ "scripts": {
21
+ "test": "node --test"
22
+ },
23
+ "license": "MIT",
24
+ "author": "Mark Colley",
25
+ "repository": { "type": "git", "url": "git+https://github.com/M-Colley/optimization-test-functions.git" },
26
+ "bugs": { "url": "https://github.com/M-Colley/optimization-test-functions/issues" },
27
+ "homepage": "https://github.com/M-Colley/optimization-test-functions#readme"
28
+ }
package/src/index.d.ts CHANGED
@@ -1,81 +1,93 @@
1
- export type Vec = readonly number[] | Float64Array | Float32Array;
2
-
3
- /** One [lo, hi] pair per axis. */
4
- export type Box = [number, number][];
5
-
6
- export interface Optimum {
7
- /** The optimal value, or null when it depends on the dimension. */
8
- value: number | null;
9
- /** The location, given the dimension. Absent when `value` is null. */
10
- at?: (d: number) => number[];
11
- /** A commonly quoted but only approximate location, where one exists. */
12
- approx?: number[];
13
- /** Every global optimum, for functions that have more than one. */
14
- all?: number[][];
15
- /** Published values keyed by dimension, when the optimum is d-dependent. */
16
- known?: Record<number, number>;
17
- note?: string;
18
- }
19
-
20
- export interface Meta {
21
- name: string;
22
- /** 'any', a fixed number, or a description such as 'multiple of 4'. */
23
- dims: number | string;
24
- /** Which direction is interesting. Nothing here is silently negated. */
25
- sense: 'min' | 'max';
26
- /** The function's own domain, per axis, at dimension d. */
27
- domain: (d: number) => Box;
28
- optimum: Optimum;
29
- /** Present on the psychophysical laws; false or a direction. */
30
- monotone?: false | 'increasing' | 'decreasing';
31
- note?: string;
32
- reference: string;
33
- }
34
-
35
- export interface TestFunction<O = Record<string, never>> {
36
- (x: Vec, options?: O): number;
37
- meta: Meta;
38
- }
39
-
40
- /* classical optimization benchmarks -- minimized */
41
- export const ackley: TestFunction<{ a?: number; b?: number; c?: number }>;
42
- export const griewank: TestFunction;
43
- export const schwefel: TestFunction;
44
- export const eggholder: TestFunction;
45
- export const powell: TestFunction;
46
- export const shekel: TestFunction<{ m?: number }>;
47
- export const hartmann3: TestFunction;
48
- export const hartmann6: TestFunction;
49
- export const branin: TestFunction<{
50
- a?: number; b?: number; c?: number; r?: number; s?: number; t?: number;
51
- }>;
52
- export const rosenbrock: TestFunction;
53
- export const rastrigin: TestFunction;
54
- export const michalewicz: TestFunction<{ m?: number }>;
55
-
56
- /* classical psychophysical laws */
57
- export const yerkesDodson: TestFunction<{ peak?: number; width?: number }>;
58
- export const stevens: TestFunction<{ a?: number }>;
59
- export const hickHyman: TestFunction<{ a?: number; b?: number }>;
60
- export const weberFechner: TestFunction<{ i0?: number }>;
61
-
62
- export type FunctionName =
63
- | 'ackley' | 'griewank' | 'schwefel' | 'eggholder' | 'powell' | 'shekel'
64
- | 'hartmann3' | 'hartmann6' | 'branin' | 'rosenbrock' | 'rastrigin'
65
- | 'michalewicz' | 'yerkesDodson' | 'stevens' | 'hickHyman' | 'weberFechner';
66
-
67
- export const functions: Record<FunctionName, TestFunction<any>>;
68
- export const optimizationBenchmarks: FunctionName[];
69
- export const psychophysicalLaws: FunctionName[];
70
-
71
- /** Wrap a function so a minimizer can be used as a maximizer, or vice versa. */
72
- export function negate<O>(f: TestFunction<O>): TestFunction<O>;
73
-
74
- /** The per-axis domain of `name` at dimension `d`. */
75
- export function domain(name: FunctionName, d?: number): Box;
76
-
77
- /** Map a point from the unit cube onto `name`'s own domain. */
78
- export function fromUnitCube(name: FunctionName, u: Vec): number[];
79
-
80
- declare const _default: Record<FunctionName, TestFunction<any>>;
81
- export default _default;
1
+ export type TypedNumberArray =
2
+ | Float64Array | Float32Array
3
+ | Int32Array | Int16Array | Int8Array
4
+ | Uint32Array | Uint16Array | Uint8Array | Uint8ClampedArray;
5
+
6
+ export type Vec = readonly number[] | TypedNumberArray;
7
+
8
+ /** One [lo, hi] pair per axis. */
9
+ export type Box = [number, number][];
10
+
11
+ export interface Optimum {
12
+ /** The optimal value, or null when it depends on the dimension. */
13
+ value: number | null;
14
+ /** The location, given the dimension (optional on fixed-dimension functions). Absent when `value` is null. */
15
+ at?: (d?: number) => number[];
16
+ /** A commonly quoted but only approximate location, where one exists. */
17
+ approx?: number[];
18
+ /** Every global optimum, for functions that have more than one. */
19
+ all?: number[][];
20
+ /** Optimal values keyed by dimension, when the optimum is d-dependent. */
21
+ known?: Record<number, number>;
22
+ note?: string;
23
+ }
24
+
25
+ export interface Meta {
26
+ name: string;
27
+ /** 'any', a fixed number, or a description such as 'multiple of 4'. */
28
+ dims: number | string;
29
+ /** Which direction is interesting. Nothing here is silently negated. */
30
+ sense: 'min' | 'max';
31
+ /** The function's own domain, per axis, at dimension d (optional on fixed-dimension functions). */
32
+ domain: (d?: number) => Box;
33
+ optimum: Optimum;
34
+ /** Present on the psychophysical laws; false or a direction. */
35
+ monotone?: false | 'increasing' | 'decreasing';
36
+ note?: string;
37
+ reference: string;
38
+ }
39
+
40
+ export interface TestFunction<O = Record<string, never>> {
41
+ (x: Vec, options?: O): number;
42
+ meta: Meta;
43
+ }
44
+
45
+ /* classical optimization benchmarks -- minimized */
46
+ export const ackley: TestFunction<{ a?: number; b?: number; c?: number }>;
47
+ export const griewank: TestFunction;
48
+ export const schwefel: TestFunction;
49
+ export const eggholder: TestFunction;
50
+ export const powell: TestFunction;
51
+ export const shekel: TestFunction<{ m?: number }>;
52
+ export const hartmann3: TestFunction;
53
+ export const hartmann6: TestFunction;
54
+ export const branin: TestFunction<{
55
+ a?: number; b?: number; c?: number; r?: number; s?: number; t?: number;
56
+ }>;
57
+ export const rosenbrock: TestFunction;
58
+ export const rastrigin: TestFunction;
59
+ export const michalewicz: TestFunction<{ m?: number }>;
60
+
61
+ /* classical psychophysical laws */
62
+ export const yerkesDodson: TestFunction<{ peak?: number; width?: number }>;
63
+ export const stevens: TestFunction<{ a?: number }>;
64
+ export const hickHyman: TestFunction<{ a?: number; b?: number }>;
65
+ export const weberFechner: TestFunction<{ i0?: number }>;
66
+
67
+ export type FunctionName =
68
+ | 'ackley' | 'griewank' | 'schwefel' | 'eggholder' | 'powell' | 'shekel'
69
+ | 'hartmann3' | 'hartmann6' | 'branin' | 'rosenbrock' | 'rastrigin'
70
+ | 'michalewicz' | 'yerkesDodson' | 'stevens' | 'hickHyman' | 'weberFechner';
71
+
72
+ export const functions: Record<FunctionName, TestFunction<any>>;
73
+ export const optimizationBenchmarks: FunctionName[];
74
+ export const psychophysicalLaws: FunctionName[];
75
+
76
+ /**
77
+ * Wrap a function so a minimizer can be used as a maximizer, or vice versa.
78
+ * `meta.sense`, `meta.optimum.value`, `meta.optimum.known` and
79
+ * `meta.monotone` all flip with the sign.
80
+ */
81
+ export function negate<O>(f: TestFunction<O>): TestFunction<O>;
82
+
83
+ /**
84
+ * The per-axis domain of `name` at dimension `d`. `d` is optional for
85
+ * fixed-dimension functions and must match their dimension if given.
86
+ */
87
+ export function domain(name: FunctionName, d?: number): Box;
88
+
89
+ /** Map a point from the unit cube onto `name`'s own domain. */
90
+ export function fromUnitCube(name: FunctionName, u: Vec): number[];
91
+
92
+ declare const _default: Record<FunctionName, TestFunction<any>>;
93
+ export default _default;