@mostajs/ro-pla 0.2.2 → 0.4.0
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.
- package/CHANGELOG.md +129 -33
- package/LICENSE +21 -0
- package/README.md +73 -30
- package/dist/dialects/anneal.js +2 -1
- package/dist/dialects/bin-packing.js +2 -1
- package/dist/dialects/critical-path.js +2 -1
- package/dist/dialects/csp.js +2 -1
- package/dist/dialects/forecast.js +2 -1
- package/dist/dialects/genetic.js +2 -1
- package/dist/dialects/hungarian.js +4 -0
- package/dist/dialects/knapsack.js +2 -1
- package/dist/dialects/lagrangian.js +2 -1
- package/dist/dialects/list-scheduling.js +2 -1
- package/dist/dialects/markov.js +4 -0
- package/dist/dialects/matching.js +2 -1
- package/dist/dialects/max-flow.js +2 -1
- package/dist/dialects/mdp.js +3 -0
- package/dist/dialects/milp.d.ts +14 -5
- package/dist/dialects/milp.js +77 -22
- package/dist/dialects/min-cost-flow.js +3 -0
- package/dist/dialects/mmc.js +14 -2
- package/dist/dialects/monte-carlo.js +2 -1
- package/dist/dialects/pareto.js +2 -1
- package/dist/dialects/shortest-path.js +2 -1
- package/dist/dialects/simplex.js +4 -0
- package/dist/dialects/stable-matching.js +2 -1
- package/dist/dialects/tabu.js +2 -1
- package/dist/registry.d.ts +18 -3
- package/dist/registry.js +151 -11
- package/dist/types.d.ts +119 -4
- package/llms.txt +103 -88
- package/package.json +2 -2
package/dist/dialects/milp.js
CHANGED
|
@@ -5,50 +5,72 @@
|
|
|
5
5
|
* Programmation linéaire en nombres entiers (mixte) par SÉPARATION & ÉVALUATION :
|
|
6
6
|
* on résout la relaxation continue via le dialecte `simplex`, puis on BRANCHE sur
|
|
7
7
|
* une variable fractionnaire (x ≤ ⌊v⌋ | x ≥ ⌈v⌉) en élaguant les nœuds dont la
|
|
8
|
-
* borne ne peut battre l'incumbent. Exact ; bornable par `maxNodes` (anti-explosion)
|
|
8
|
+
* borne ne peut battre l'incumbent. Exact ; bornable par `maxNodes` (anti-explosion) et, depuis la
|
|
9
|
+
* 0.4.0, par un délai `timeoutMs` qui rend la meilleure solution trouvée et l'écart à la borne.
|
|
9
10
|
*/
|
|
10
11
|
import { simplex } from './simplex.js';
|
|
11
12
|
const EPS = 1e-6;
|
|
12
13
|
const isInt = (v) => Math.abs(v - Math.round(v)) <= EPS;
|
|
13
|
-
/**
|
|
14
|
+
/**
|
|
15
|
+
* Résout un PLNE/MIP par branch & bound (relaxation LP = simplexe), en profondeur d'abord
|
|
16
|
+
* (branche `x ≤ ⌊v⌋` avant `x ≥ ⌈v⌉`).
|
|
17
|
+
*
|
|
18
|
+
* Mode « au fil de l'eau » (0.4.0), dès que `opts.timeoutMs` est donné ou `opts.anytime` vrai :
|
|
19
|
+
* arrêt au délai ou au budget de nœuds avec la MEILLEURE solution trouvée, statut honnête
|
|
20
|
+
* (`optimal` prouvé, `feasible`, `unknown`, `infeasible`, `unbounded`) et compte rendu `search`
|
|
21
|
+
* (nœuds, durée, borne, écart). Sinon : le résultat de la 0.3.0, au champ près.
|
|
22
|
+
*/
|
|
14
23
|
export function branchAndBound(problem, opts) {
|
|
15
24
|
const sense = problem.objective ?? 'max';
|
|
16
25
|
const n = problem.c.length;
|
|
17
26
|
const intIdx = problem.integers ?? Array.from({ length: n }, (_, j) => j);
|
|
18
27
|
const baseRel = problem.relations ?? problem.A.map(() => '<=');
|
|
19
28
|
const maxNodes = opts?.maxNodes ?? 100_000;
|
|
29
|
+
const timeoutMs = typeof opts?.timeoutMs === 'number' ? opts.timeoutMs : null;
|
|
30
|
+
const anytime = timeoutMs !== null || opts?.anytime === true;
|
|
31
|
+
const now = opts?.now ?? Date.now;
|
|
32
|
+
const t0 = anytime ? now() : 0;
|
|
20
33
|
// Incumbent : initialisé à une borne « pire que tout » ; `found` distingue
|
|
21
34
|
// l'absence de solution entière de la valeur sentinelle (évite un type `| null`).
|
|
22
35
|
let best = { x: [], objective: sense === 'max' ? -Infinity : Infinity };
|
|
23
36
|
let found = false;
|
|
24
37
|
let unbounded = false;
|
|
25
38
|
let nodes = 0;
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
39
|
+
let stoppedBy = null;
|
|
40
|
+
// Pile explicite : même ordre que la récursion de la 0.3.0 (le fils gauche est dépilé d'abord).
|
|
41
|
+
const open = [{ addA: [], addB: [], addRel: [], parentBound: sense === 'max' ? Infinity : -Infinity }];
|
|
42
|
+
while (open.length > 0) {
|
|
43
|
+
if (nodes >= maxNodes) {
|
|
44
|
+
stoppedBy = 'nodes';
|
|
45
|
+
break;
|
|
46
|
+
}
|
|
47
|
+
if (timeoutMs !== null && now() - t0 >= timeoutMs) {
|
|
48
|
+
stoppedBy = 'time';
|
|
49
|
+
break;
|
|
50
|
+
}
|
|
51
|
+
const node = open.pop();
|
|
30
52
|
nodes++;
|
|
31
53
|
const sol = simplex({
|
|
32
54
|
kind: 'lp',
|
|
33
55
|
c: problem.c,
|
|
34
|
-
A: [...problem.A, ...addA],
|
|
35
|
-
b: [...problem.b, ...addB],
|
|
36
|
-
relations: [...baseRel, ...addRel],
|
|
56
|
+
A: [...problem.A, ...node.addA],
|
|
57
|
+
b: [...problem.b, ...node.addB],
|
|
58
|
+
relations: [...baseRel, ...node.addRel],
|
|
37
59
|
objective: sense,
|
|
38
60
|
});
|
|
39
61
|
if (sol.status === 'infeasible')
|
|
40
|
-
|
|
62
|
+
continue;
|
|
41
63
|
if (sol.status === 'unbounded') {
|
|
42
64
|
unbounded = true;
|
|
43
|
-
|
|
65
|
+
break;
|
|
44
66
|
}
|
|
45
67
|
// Élagage par borne : la relaxation borne le sous-arbre ; si elle ne peut
|
|
46
68
|
// pas dépasser l'incumbent, inutile de descendre.
|
|
47
69
|
if (found) {
|
|
48
70
|
if (sense === 'max' && sol.objective <= best.objective + EPS)
|
|
49
|
-
|
|
71
|
+
continue;
|
|
50
72
|
if (sense === 'min' && sol.objective >= best.objective - EPS)
|
|
51
|
-
|
|
73
|
+
continue;
|
|
52
74
|
}
|
|
53
75
|
// Première variable entière encore fractionnaire ?
|
|
54
76
|
let frac = -1;
|
|
@@ -66,27 +88,60 @@ export function branchAndBound(problem, opts) {
|
|
|
66
88
|
best = { x, objective: sol.objective };
|
|
67
89
|
found = true;
|
|
68
90
|
}
|
|
69
|
-
|
|
91
|
+
continue;
|
|
70
92
|
}
|
|
71
|
-
// Branchement : x_frac ≤ ⌊v⌋ puis x_frac ≥ ⌈v
|
|
93
|
+
// Branchement : x_frac ≤ ⌊v⌋ puis x_frac ≥ ⌈v⌉ (empilé en second, dépilé en premier).
|
|
72
94
|
const v = sol.x[frac];
|
|
73
95
|
const row = new Array(n).fill(0);
|
|
74
96
|
row[frac] = 1;
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
}
|
|
78
|
-
|
|
97
|
+
open.push({ addA: [...node.addA, row.slice()], addB: [...node.addB, Math.ceil(v)], addRel: [...node.addRel, '>='], parentBound: sol.objective });
|
|
98
|
+
open.push({ addA: [...node.addA, row.slice()], addB: [...node.addB, Math.floor(v)], addRel: [...node.addRel, '<='], parentBound: sol.objective });
|
|
99
|
+
}
|
|
100
|
+
if (!anytime) {
|
|
101
|
+
// Contrat 0.3.0 : budget de nœuds atteint ⇒ `optimal` si un entier a été trouvé (sans preuve).
|
|
102
|
+
if (unbounded)
|
|
103
|
+
return { status: 'unbounded', x: [], objective: NaN };
|
|
104
|
+
if (!found)
|
|
105
|
+
return { status: 'infeasible', x: [], objective: NaN };
|
|
106
|
+
return { status: 'optimal', x: best.x, objective: best.objective };
|
|
107
|
+
}
|
|
108
|
+
const complete = stoppedBy === null;
|
|
109
|
+
const search = (bound, gap) => ({ complete, stoppedBy, nodes, elapsedMs: now() - t0, bound, gap });
|
|
79
110
|
if (unbounded)
|
|
80
|
-
return { status: 'unbounded', x: [], objective: NaN };
|
|
111
|
+
return { status: 'unbounded', x: [], objective: NaN, search: search(null, null) };
|
|
112
|
+
if (complete) {
|
|
113
|
+
if (!found)
|
|
114
|
+
return { status: 'infeasible', x: [], objective: NaN, search: search(null, null) };
|
|
115
|
+
return { status: 'optimal', x: best.x, objective: best.objective, search: search(best.objective, 0) };
|
|
116
|
+
}
|
|
117
|
+
// Arrêt avant la fin : la borne est la meilleure des relaxations parentes encore ouvertes,
|
|
118
|
+
// et l'incumbent (un nœud ouvert qui ne peut le battre serait élagué).
|
|
119
|
+
let bound = found ? best.objective : null;
|
|
120
|
+
for (const o of open) {
|
|
121
|
+
if (bound === null)
|
|
122
|
+
bound = o.parentBound;
|
|
123
|
+
else
|
|
124
|
+
bound = sense === 'max' ? Math.max(bound, o.parentBound) : Math.min(bound, o.parentBound);
|
|
125
|
+
}
|
|
126
|
+
if (bound !== null && !Number.isFinite(bound))
|
|
127
|
+
bound = null;
|
|
81
128
|
if (!found)
|
|
82
|
-
return { status: '
|
|
83
|
-
|
|
129
|
+
return { status: 'unknown', x: [], objective: NaN, search: search(bound, null) };
|
|
130
|
+
const gap = bound === null ? null
|
|
131
|
+
: Math.abs(bound - best.objective) <= EPS ? 0
|
|
132
|
+
: Math.abs(best.objective) <= EPS ? Infinity
|
|
133
|
+
: Math.abs(bound - best.objective) / Math.abs(best.objective);
|
|
134
|
+
return { status: 'feasible', x: best.x, objective: best.objective, search: search(bound, gap) };
|
|
84
135
|
}
|
|
85
136
|
/** Dialecte de solveur exposant le branch & bound (PLNE/MIP). */
|
|
86
137
|
export const milpDialect = {
|
|
87
138
|
name: 'branch-and-bound',
|
|
88
139
|
kind: 'milp',
|
|
140
|
+
shape: { fields: ['c', 'A', 'b'] },
|
|
89
141
|
capabilities: { exact: true, online: false, maxSize: 50 },
|
|
142
|
+
// Taille : nombre de variables ENTIÈRES (défaut : toutes), unité de `maxSize`.
|
|
143
|
+
size: (p) => (Array.isArray(p?.integers) ? p.integers.length : Array.isArray(p?.c) ? p.c.length : null),
|
|
144
|
+
sizeUnit: "nombre de variables entières",
|
|
90
145
|
solve(problem, opts) {
|
|
91
146
|
return branchAndBound(problem, opts);
|
|
92
147
|
},
|
|
@@ -86,7 +86,10 @@ export function minCostFlow(problem) {
|
|
|
86
86
|
export const minCostFlowDialect = {
|
|
87
87
|
name: 'min-cost-flow',
|
|
88
88
|
kind: 'flow',
|
|
89
|
+
shape: { fields: ['arcs', 'source', 'sink'] },
|
|
89
90
|
capabilities: { exact: true, online: true, maxSize: 5000 },
|
|
91
|
+
// Mesure de taille « à établir » (nœuds ou arcs ?) : la borne reste déclarée, son dépassement
|
|
92
|
+
// n'est pas jugé tant que l'unité n'est pas fixée.
|
|
90
93
|
solve(problem) {
|
|
91
94
|
return minCostFlow(problem);
|
|
92
95
|
},
|
package/dist/dialects/mmc.js
CHANGED
|
@@ -9,6 +9,11 @@
|
|
|
9
9
|
*/
|
|
10
10
|
/** Métriques M/M/c pour λ, μ et c serveurs (formules d'Erlang). */
|
|
11
11
|
export function mmc(lambda, mu, c) {
|
|
12
|
+
// Un nombre de serveurs non entier n'a pas de sens pour M/M/c : refus explicite (0.3.0),
|
|
13
|
+
// au lieu de métriques calculées sans avertissement.
|
|
14
|
+
if (!Number.isInteger(c)) {
|
|
15
|
+
throw new RangeError(`mmc : le nombre de serveurs c doit être un entier (reçu ${c}).`);
|
|
16
|
+
}
|
|
12
17
|
const offered = lambda / mu; // a = λ/μ (Erlangs)
|
|
13
18
|
const rho = offered / c; // taux d'occupation
|
|
14
19
|
const base = { c, offered, rho };
|
|
@@ -27,7 +32,8 @@ export function mmc(lambda, mu, c) {
|
|
|
27
32
|
const p0 = 1 / (sum + erlangCnum);
|
|
28
33
|
const probWait = erlangCnum * p0; // C(c, a) = P(attente)
|
|
29
34
|
const avgQueue = (probWait * rho) / (1 - rho); // Lq
|
|
30
|
-
|
|
35
|
+
// Wq = Lq / λ ; sans arrivée (λ = 0), personne n'attend : 0, et non 0/0 = NaN (0.3.0).
|
|
36
|
+
const avgWait = lambda > 0 ? avgQueue / lambda : 0; // Wq
|
|
31
37
|
const avgSystem = avgQueue + offered; // L
|
|
32
38
|
const avgTime = avgWait + 1 / mu; // W
|
|
33
39
|
return { ...base, stable: true, probWait, avgQueue, avgWait, avgSystem, avgTime };
|
|
@@ -52,7 +58,13 @@ export function mmcSizing(lambda, mu, target) {
|
|
|
52
58
|
export const mmcDialect = {
|
|
53
59
|
name: 'mmc',
|
|
54
60
|
kind: 'queue',
|
|
55
|
-
|
|
61
|
+
shape: { fields: ['lambda', 'mu'] },
|
|
62
|
+
capabilities: { exact: true, online: true, maxSize: null },
|
|
63
|
+
notes(problem) {
|
|
64
|
+
return problem?.c == null && !problem?.target
|
|
65
|
+
? ['mmc : ni `c` ni `target` fournis — évaluation avec c = 1 serveur par défaut.']
|
|
66
|
+
: [];
|
|
67
|
+
},
|
|
56
68
|
solve(problem) {
|
|
57
69
|
if (problem.target && problem.c == null)
|
|
58
70
|
return mmcSizing(problem.lambda, problem.mu, problem.target);
|
|
@@ -27,7 +27,8 @@ export function monteCarlo(problem) {
|
|
|
27
27
|
export const monteCarloDialect = {
|
|
28
28
|
name: 'monte-carlo',
|
|
29
29
|
kind: 'simulation',
|
|
30
|
-
|
|
30
|
+
shape: { fields: ['sample', 'trials'] },
|
|
31
|
+
capabilities: { exact: false, online: true, maxSize: null },
|
|
31
32
|
solve(problem) {
|
|
32
33
|
return monteCarlo(problem);
|
|
33
34
|
},
|
package/dist/dialects/pareto.js
CHANGED
|
@@ -119,9 +119,10 @@ export function pareto(problem) {
|
|
|
119
119
|
export const paretoDialect = {
|
|
120
120
|
name: 'pareto',
|
|
121
121
|
kind: 'multiobjective',
|
|
122
|
+
shape: { fields: ['candidates', 'senses'] },
|
|
122
123
|
// EXACT : le front de Pareto d'un ensemble FINI de candidats est calculé exactement. Ce n'est
|
|
123
124
|
// pas le front du problème continu sous-jacent — le dialecte trie ce qu'on lui donne.
|
|
124
|
-
capabilities: { exact: true, online: false },
|
|
125
|
+
capabilities: { exact: true, online: false, maxSize: null },
|
|
125
126
|
solve(problem) {
|
|
126
127
|
return pareto(problem);
|
|
127
128
|
},
|
|
@@ -141,7 +141,8 @@ export function shortestPath(problem) {
|
|
|
141
141
|
export const shortestPathDialect = {
|
|
142
142
|
name: 'shortest-path',
|
|
143
143
|
kind: 'flow',
|
|
144
|
-
|
|
144
|
+
shape: { fields: ['edges', 'source'], test: (p) => Array.isArray(p.edges) && p.edges.every((e) => e != null && typeof e.weight === 'number'), testLabel: 'chaque arête porte un `weight` numérique' },
|
|
145
|
+
capabilities: { exact: true, online: false, maxSize: null },
|
|
145
146
|
solve(problem) { return shortestPath(problem); },
|
|
146
147
|
};
|
|
147
148
|
//# sourceMappingURL=shortest-path.js.map
|
package/dist/dialects/simplex.js
CHANGED
|
@@ -197,7 +197,11 @@ export function simplex(problem) {
|
|
|
197
197
|
export const simplexDialect = {
|
|
198
198
|
name: 'simplex',
|
|
199
199
|
kind: 'lp',
|
|
200
|
+
shape: { fields: ['c', 'A', 'b'] },
|
|
200
201
|
capabilities: { exact: true, online: true, maxSize: 200 },
|
|
202
|
+
// Taille : nombre de variables (unité de `maxSize`, celle que l'audit a mesurée).
|
|
203
|
+
size: (p) => (Array.isArray(p?.c) ? p.c.length : null),
|
|
204
|
+
sizeUnit: "nombre de variables",
|
|
201
205
|
solve(problem) {
|
|
202
206
|
return simplex(problem);
|
|
203
207
|
},
|
|
@@ -98,10 +98,11 @@ export function stableMatching(problem) {
|
|
|
98
98
|
export const stableMatchingDialect = {
|
|
99
99
|
name: 'stable-matching',
|
|
100
100
|
kind: 'assignment',
|
|
101
|
+
shape: { fields: ['proposers', 'receivers', 'preferences'] },
|
|
101
102
|
// EXACT : Gale-Shapley rend une solution stable, pas une approximation. Mais « stable » n'est
|
|
102
103
|
// pas « optimal au sens d'un coût » — ce sont deux notions différentes, et c'est pourquoi ce
|
|
103
104
|
// dialecte ne remplace pas `hungarian` : il répond à une autre question.
|
|
104
|
-
capabilities: { exact: true, online: false },
|
|
105
|
+
capabilities: { exact: true, online: false, maxSize: null },
|
|
105
106
|
solve(problem) {
|
|
106
107
|
return stableMatching(problem);
|
|
107
108
|
},
|
package/dist/dialects/tabu.js
CHANGED
|
@@ -89,7 +89,8 @@ export function tabuSearch(problem) {
|
|
|
89
89
|
export const tabuDialect = {
|
|
90
90
|
name: 'tabu',
|
|
91
91
|
kind: 'metaheuristic',
|
|
92
|
-
|
|
92
|
+
shape: { fields: ['initial', 'energy', 'neighbors'] },
|
|
93
|
+
capabilities: { exact: false, online: false, maxSize: null },
|
|
93
94
|
solve(problem) { return tabuSearch(problem); },
|
|
94
95
|
};
|
|
95
96
|
//# sourceMappingURL=tabu.js.map
|
package/dist/registry.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* @mostajs/ro-pla — Registre de dialectes + sélection (façon ORM)
|
|
3
3
|
* @author Dr Hamid MADANI <drmdh@msn.com>
|
|
4
4
|
*/
|
|
5
|
-
import type { Problem, ProblemKind, SolveOptions, SolverDialect } from './types.js';
|
|
5
|
+
import type { Problem, ProblemKind, SizeCheck, SolveOptions, SolverDialect } from './types.js';
|
|
6
6
|
/** Enregistre un dialecte de solveur (un par algorithme). */
|
|
7
7
|
export declare function registerSolver(dialect: SolverDialect<any, any>): void;
|
|
8
8
|
/** Récupère un dialecte par nom (lève s'il est absent). */
|
|
@@ -11,9 +11,24 @@ export declare function getSolver(name: string): SolverDialect<any, any>;
|
|
|
11
11
|
export declare function listSolvers(kind?: ProblemKind): SolverDialect<any, any>[];
|
|
12
12
|
/** Vide le registre (tests). */
|
|
13
13
|
export declare function clearSolvers(): void;
|
|
14
|
+
/** Erreur de sélection de dialecte, avec un `code` stable lisible par une machine. */
|
|
15
|
+
export declare class SolverSelectionError extends Error {
|
|
16
|
+
readonly code: 'RO_PLA_NO_KIND' | 'RO_PLA_NO_DIALECT' | 'RO_PLA_NO_SHAPE' | 'RO_PLA_AMBIGUOUS_SHAPE';
|
|
17
|
+
constructor(code: SolverSelectionError['code'], message: string);
|
|
18
|
+
}
|
|
19
|
+
/** Le dialecte accepte-t-il la forme du problème ? (sans forme déclarée : oui, toute la famille) */
|
|
20
|
+
export declare function acceptsShape(dialect: SolverDialect<any, any>, problem: unknown): boolean;
|
|
14
21
|
/**
|
|
15
|
-
*
|
|
16
|
-
* (
|
|
22
|
+
* Dit si un problème dépasse la borne déclarée d'un dialecte, sans le résoudre (0.3.0).
|
|
23
|
+
* `beyondDeclaredSize` : vrai, faux, ou `null` (« à établir ») si la borne ou la mesure manque.
|
|
24
|
+
* La borne est déclarative : un dépassement n'empêche jamais `solve` de répondre.
|
|
25
|
+
*/
|
|
26
|
+
export declare function checkSize(dialect: string | SolverDialect<any, any>, problem: unknown): SizeCheck;
|
|
27
|
+
/**
|
|
28
|
+
* Résout un problème : par dialecte nommé (sans contrôle de forme), sinon sélection dans la
|
|
29
|
+
* famille `problem.kind` par la forme du problème, puis par l'ordre de `pickBest`.
|
|
30
|
+
* Le résultat est une copie de la solution, plus le champ `solvedBy` (qui a répondu, pourquoi).
|
|
31
|
+
* Un dialecte synchrone reste synchrone ; un dialecte asynchrone reçoit le champ après résolution.
|
|
17
32
|
*/
|
|
18
33
|
export declare function solve<P extends Problem, S>(problem: P, opts?: SolveOptions & {
|
|
19
34
|
dialect?: string;
|
package/dist/registry.js
CHANGED
|
@@ -23,23 +23,163 @@ export function listSolvers(kind) {
|
|
|
23
23
|
export function clearSolvers() {
|
|
24
24
|
registry.clear();
|
|
25
25
|
}
|
|
26
|
+
/** Erreur de sélection de dialecte, avec un `code` stable lisible par une machine. */
|
|
27
|
+
export class SolverSelectionError extends Error {
|
|
28
|
+
constructor(code, message) {
|
|
29
|
+
super(message);
|
|
30
|
+
this.name = 'SolverSelectionError';
|
|
31
|
+
this.code = code;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** Le dialecte accepte-t-il la forme du problème ? (sans forme déclarée : oui, toute la famille) */
|
|
35
|
+
export function acceptsShape(dialect, problem) {
|
|
36
|
+
const shape = dialect.shape;
|
|
37
|
+
if (!shape)
|
|
38
|
+
return true;
|
|
39
|
+
if (problem == null || typeof problem !== 'object')
|
|
40
|
+
return false;
|
|
41
|
+
const p = problem;
|
|
42
|
+
if (!shape.fields.every((f) => p[f] !== undefined))
|
|
43
|
+
return false;
|
|
44
|
+
return shape.test ? Boolean(shape.test(p)) : true;
|
|
45
|
+
}
|
|
46
|
+
const describeShape = (d) => d.shape
|
|
47
|
+
? `${d.name} { ${d.shape.fields.join(', ')} }${d.shape.testLabel ? ` (${d.shape.testLabel})` : ''}`
|
|
48
|
+
: `${d.name} (forme non déclarée)`;
|
|
49
|
+
/**
|
|
50
|
+
* Garde, dans la famille, les dialectes qui acceptent la forme du problème. Famille d'un seul
|
|
51
|
+
* dialecte : il est retenu tel quel (comportement 0.2.x). Lève, avec un message qui nomme les
|
|
52
|
+
* candidats et les champs attendus, si aucune forme ne correspond ou si plusieurs formes
|
|
53
|
+
* DIFFÉRENTES correspondent (il faut alors nommer le dialecte).
|
|
54
|
+
*/
|
|
55
|
+
function candidatesFor(problem) {
|
|
56
|
+
const kind = problem?.kind;
|
|
57
|
+
if (kind == null) {
|
|
58
|
+
throw new SolverSelectionError('RO_PLA_NO_KIND', 'Problème sans `kind` et sans dialecte nommé : indiquez la famille (`kind`) ou nommez le dialecte (`solve(problème, { dialect })`).');
|
|
59
|
+
}
|
|
60
|
+
const family = listSolvers(kind);
|
|
61
|
+
if (family.length === 0) {
|
|
62
|
+
throw new SolverSelectionError('RO_PLA_NO_DIALECT', `Aucun dialecte enregistré pour le type « ${kind} »`);
|
|
63
|
+
}
|
|
64
|
+
if (family.length === 1)
|
|
65
|
+
return family;
|
|
66
|
+
const accepted = family.filter((d) => acceptsShape(d, problem));
|
|
67
|
+
if (accepted.length === 0) {
|
|
68
|
+
throw new SolverSelectionError('RO_PLA_NO_SHAPE', `Aucun dialecte de la famille « ${kind} » ne reconnaît la forme du problème. Candidats et champs attendus : ` +
|
|
69
|
+
family.map(describeShape).join(' ; ') + '.');
|
|
70
|
+
}
|
|
71
|
+
const signatures = new Set(accepted.filter((d) => d.shape).map((d) => [...d.shape.fields].sort().join(',')));
|
|
72
|
+
if (signatures.size > 1) {
|
|
73
|
+
throw new SolverSelectionError('RO_PLA_AMBIGUOUS_SHAPE', `Forme ambiguë dans la famille « ${kind} » : elle correspond à ${accepted.map((d) => d.name).join(', ')}. ` +
|
|
74
|
+
`Nommez le dialecte : solve(problème, { dialect: '${accepted[0].name}' }). Formes : ` +
|
|
75
|
+
accepted.map(describeShape).join(' ; ') + '.');
|
|
76
|
+
}
|
|
77
|
+
return accepted;
|
|
78
|
+
}
|
|
79
|
+
/** Taille mesurée par le dialecte, ou `null` (« à établir ») s'il ne sait pas la mesurer. */
|
|
80
|
+
function measure(dialect, problem) {
|
|
81
|
+
if (!dialect.size)
|
|
82
|
+
return null;
|
|
83
|
+
const n = dialect.size(problem);
|
|
84
|
+
return typeof n === 'number' && Number.isFinite(n) ? n : null;
|
|
85
|
+
}
|
|
26
86
|
/**
|
|
27
|
-
*
|
|
28
|
-
*
|
|
87
|
+
* Dit si un problème dépasse la borne déclarée d'un dialecte, sans le résoudre (0.3.0).
|
|
88
|
+
* `beyondDeclaredSize` : vrai, faux, ou `null` (« à établir ») si la borne ou la mesure manque.
|
|
89
|
+
* La borne est déclarative : un dépassement n'empêche jamais `solve` de répondre.
|
|
29
90
|
*/
|
|
30
|
-
function
|
|
31
|
-
const
|
|
32
|
-
|
|
33
|
-
|
|
91
|
+
export function checkSize(dialect, problem) {
|
|
92
|
+
const d = typeof dialect === 'string' ? getSolver(dialect) : dialect;
|
|
93
|
+
const maxSize = d.capabilities.maxSize ?? null;
|
|
94
|
+
const size = measure(d, problem);
|
|
95
|
+
return { dialect: d.name, size, maxSize, beyondDeclaredSize: maxSize == null || size == null ? null : size > maxSize };
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Palier de taille : 0 = la borne déclarée couvre la taille ; 1 = « à établir » (borne ou taille
|
|
99
|
+
* inconnue) ; 2 = borne dépassée.
|
|
100
|
+
*/
|
|
101
|
+
function sizeTier(dialect, problem) {
|
|
102
|
+
const bound = dialect.capabilities.maxSize ?? null;
|
|
103
|
+
const size = measure(dialect, problem);
|
|
104
|
+
if (bound == null || size == null)
|
|
105
|
+
return 1;
|
|
106
|
+
return size <= bound ? 0 : 2;
|
|
107
|
+
}
|
|
108
|
+
function compareDialects(a, b, problem) {
|
|
109
|
+
const ea = Number(Boolean(a.capabilities.exact));
|
|
110
|
+
const eb = Number(Boolean(b.capabilities.exact));
|
|
111
|
+
if (ea !== eb)
|
|
112
|
+
return { cmp: eb - ea, by: 'exact' };
|
|
113
|
+
const ta = sizeTier(a, problem);
|
|
114
|
+
const tb = sizeTier(b, problem);
|
|
115
|
+
if (ta !== tb)
|
|
116
|
+
return { cmp: ta - tb, by: 'size' };
|
|
117
|
+
if (ta === 0) {
|
|
118
|
+
const ba = a.capabilities.maxSize;
|
|
119
|
+
const bb = b.capabilities.maxSize;
|
|
120
|
+
if (ba !== bb)
|
|
121
|
+
return { cmp: ba - bb, by: 'size' };
|
|
34
122
|
}
|
|
35
|
-
return
|
|
123
|
+
return { cmp: 0, by: null };
|
|
36
124
|
}
|
|
37
125
|
/**
|
|
38
|
-
*
|
|
39
|
-
*
|
|
126
|
+
* Choisit le meilleur dialecte pour un problème, dans cet ordre :
|
|
127
|
+
* 1. forme acceptée (voir `candidatesFor`) ;
|
|
128
|
+
* 2. EXACT d'abord ;
|
|
129
|
+
* 3. puis la plus petite `maxSize` qui COUVRE la taille mesurée, puis les bornes « à établir »
|
|
130
|
+
* (borne ou mesure inconnue), puis les bornes dépassées ;
|
|
131
|
+
* 4. l'ordre d'enregistrement départage le reste (tri stable).
|
|
132
|
+
*/
|
|
133
|
+
function pickBest(problem) {
|
|
134
|
+
const kind = problem?.kind;
|
|
135
|
+
const familySize = kind == null ? 0 : listSolvers(kind).length;
|
|
136
|
+
const candidates = candidatesFor(problem);
|
|
137
|
+
if (candidates.length === 1) {
|
|
138
|
+
return { dialect: candidates[0], reason: familySize === 1 ? 'only-in-kind' : 'only-shape-match', criterion: null };
|
|
139
|
+
}
|
|
140
|
+
const sorted = [...candidates].sort((a, b) => compareDialects(a, b, problem).cmp);
|
|
141
|
+
const decisive = compareDialects(sorted[0], sorted[1], problem).by ?? 'registration-order';
|
|
142
|
+
return { dialect: sorted[0], reason: 'ranked', criterion: decisive };
|
|
143
|
+
}
|
|
144
|
+
function explain(sel, problem) {
|
|
145
|
+
const d = sel.dialect;
|
|
146
|
+
const sc = checkSize(d, problem);
|
|
147
|
+
return {
|
|
148
|
+
dialect: d.name,
|
|
149
|
+
kind: d.kind,
|
|
150
|
+
exact: Boolean(d.capabilities.exact),
|
|
151
|
+
online: Boolean(d.capabilities.online),
|
|
152
|
+
reason: sel.reason,
|
|
153
|
+
criterion: sel.criterion,
|
|
154
|
+
size: sc.size,
|
|
155
|
+
maxSize: sc.maxSize,
|
|
156
|
+
beyondDeclaredSize: sc.beyondDeclaredSize,
|
|
157
|
+
notes: d.notes ? d.notes(problem) : [],
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
/** Copie de la solution plus `solvedBy` ; la solution du dialecte n'est pas modifiée en place. */
|
|
161
|
+
function attach(solution, solvedBy) {
|
|
162
|
+
if (solution == null || typeof solution !== 'object')
|
|
163
|
+
return solution;
|
|
164
|
+
if (Array.isArray(solution))
|
|
165
|
+
return Object.assign([...solution], { solvedBy });
|
|
166
|
+
return { ...solution, solvedBy };
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* Résout un problème : par dialecte nommé (sans contrôle de forme), sinon sélection dans la
|
|
170
|
+
* famille `problem.kind` par la forme du problème, puis par l'ordre de `pickBest`.
|
|
171
|
+
* Le résultat est une copie de la solution, plus le champ `solvedBy` (qui a répondu, pourquoi).
|
|
172
|
+
* Un dialecte synchrone reste synchrone ; un dialecte asynchrone reçoit le champ après résolution.
|
|
40
173
|
*/
|
|
41
174
|
export function solve(problem, opts) {
|
|
42
|
-
const
|
|
43
|
-
|
|
175
|
+
const sel = opts?.dialect
|
|
176
|
+
? { dialect: getSolver(opts.dialect), reason: 'named', criterion: null }
|
|
177
|
+
: pickBest(problem);
|
|
178
|
+
const out = sel.dialect.solve(problem, opts);
|
|
179
|
+
const solvedBy = explain(sel, problem);
|
|
180
|
+
if (out != null && typeof out.then === 'function') {
|
|
181
|
+
return out.then((s) => attach(s, solvedBy));
|
|
182
|
+
}
|
|
183
|
+
return attach(out, solvedBy);
|
|
44
184
|
}
|
|
45
185
|
//# sourceMappingURL=registry.js.map
|
package/dist/types.d.ts
CHANGED
|
@@ -17,20 +17,88 @@ export interface SolverCapabilities {
|
|
|
17
17
|
exact: boolean;
|
|
18
18
|
/** Utilisable en « réflexe » temps réel (ms) ? */
|
|
19
19
|
online: boolean;
|
|
20
|
-
/**
|
|
21
|
-
|
|
20
|
+
/**
|
|
21
|
+
* Borne pratique de taille, dans l'unité de `SolverDialect.size` (ex. ordre d'une matrice).
|
|
22
|
+
* `null` = « à établir » : déclarée explicitement comme non connue. Absente : traitée de même.
|
|
23
|
+
* Déclarative : jamais mesurée, jamais appliquée ; `solve` signale son dépassement.
|
|
24
|
+
*/
|
|
25
|
+
maxSize?: number | null;
|
|
22
26
|
/** Sait gérer plusieurs objectifs (Pareto) ? */
|
|
23
27
|
multiObjective?: boolean;
|
|
24
28
|
}
|
|
25
29
|
/** Options communes à `solve`. */
|
|
26
30
|
export interface SolveOptions {
|
|
31
|
+
/**
|
|
32
|
+
* Délai de calcul en millisecondes (0.4.0 : honoré par `branch-and-bound`). Contrôlé entre deux
|
|
33
|
+
* nœuds : le dépassement réel vaut au plus une relaxation. Active le mode « au fil de l'eau ».
|
|
34
|
+
*/
|
|
27
35
|
timeoutMs?: number;
|
|
36
|
+
/** Budget de nœuds (`branch-and-bound`, défaut 100 000). */
|
|
28
37
|
maxNodes?: number;
|
|
38
|
+
/**
|
|
39
|
+
* Mode « au fil de l'eau » (0.4.0, `branch-and-bound`) : statut honnête à la limite (`feasible`,
|
|
40
|
+
* `unknown`) et champ `search`. Implicite dès que `timeoutMs` est donné. Absent : comportement 0.3.0.
|
|
41
|
+
*/
|
|
42
|
+
anytime?: boolean;
|
|
43
|
+
/** Horloge en millisecondes (défaut `Date.now`) — injectable pour des essais déterministes. */
|
|
44
|
+
now?: () => number;
|
|
29
45
|
}
|
|
30
46
|
/** Un problème porte son `kind` (sert à choisir le dialecte). */
|
|
31
47
|
export interface Problem {
|
|
32
48
|
kind: ProblemKind;
|
|
33
49
|
}
|
|
50
|
+
/**
|
|
51
|
+
* Forme du problème qu'un dialecte sait résoudre (0.3.0). Dans une famille servie par plusieurs
|
|
52
|
+
* dialectes, `solve` sans dialecte nommé ne retient que ceux dont la forme correspond.
|
|
53
|
+
*/
|
|
54
|
+
export interface ProblemShape {
|
|
55
|
+
/** Champs obligatoires qui caractérisent la forme (présents et définis). */
|
|
56
|
+
fields: string[];
|
|
57
|
+
/** Contrôle complémentaire facultatif (ex. nature des arêtes : `weight` ou `capacity`). */
|
|
58
|
+
test?: (problem: any) => boolean;
|
|
59
|
+
/** Ce que `test` vérifie, dit en clair (repris dans les messages d'erreur). */
|
|
60
|
+
testLabel?: string;
|
|
61
|
+
}
|
|
62
|
+
/** Réponse de `checkSize` : taille mesurée, borne déclarée, dépassement. */
|
|
63
|
+
export interface SizeCheck {
|
|
64
|
+
dialect: string;
|
|
65
|
+
size: number | null;
|
|
66
|
+
maxSize: number | null;
|
|
67
|
+
beyondDeclaredSize: boolean | null;
|
|
68
|
+
}
|
|
69
|
+
/** Pourquoi `solve` a retenu ce dialecte. */
|
|
70
|
+
export type SolvedByReason =
|
|
71
|
+
/** nommé par l'appelant (`opts.dialect`) */
|
|
72
|
+
'named'
|
|
73
|
+
/** seul dialecte de sa famille */
|
|
74
|
+
| 'only-in-kind'
|
|
75
|
+
/** seul de sa famille à accepter la forme du problème */
|
|
76
|
+
| 'only-shape-match'
|
|
77
|
+
/** choisi au tri parmi plusieurs (voir `criterion`) */
|
|
78
|
+
| 'ranked';
|
|
79
|
+
/** Critère décisif du tri, quand `reason` vaut `'ranked'`. */
|
|
80
|
+
export type SolvedByCriterion = 'exact' | 'size' | 'registration-order';
|
|
81
|
+
/**
|
|
82
|
+
* Ce que `solve` ajoute à la solution (0.3.0) : qui a répondu, et pourquoi. Absent d'une
|
|
83
|
+
* solution produite avant la 0.3.0 (rejouée depuis une mémoire, par exemple) : ne pas le supposer.
|
|
84
|
+
*/
|
|
85
|
+
export interface SolvedBy {
|
|
86
|
+
dialect: string;
|
|
87
|
+
kind: ProblemKind;
|
|
88
|
+
exact: boolean;
|
|
89
|
+
online: boolean;
|
|
90
|
+
reason: SolvedByReason;
|
|
91
|
+
/** Critère décisif du tri (`reason === 'ranked'`), sinon `null`. */
|
|
92
|
+
criterion: SolvedByCriterion | null;
|
|
93
|
+
/** Taille mesurée par le dialecte (unité de `maxSize`), `null` si « à établir ». */
|
|
94
|
+
size: number | null;
|
|
95
|
+
/** Borne déclarée, `null` si « à établir ». */
|
|
96
|
+
maxSize: number | null;
|
|
97
|
+
/** La taille dépasse-t-elle la borne ? `null` : « à établir » (borne ou mesure manquante). */
|
|
98
|
+
beyondDeclaredSize: boolean | null;
|
|
99
|
+
/** Remarques du dialecte sur ce problème (hypothèse par défaut appliquée, etc.). */
|
|
100
|
+
notes: string[];
|
|
101
|
+
}
|
|
34
102
|
/** Contrat d'un dialecte de solveur — une implémentation par algorithme. */
|
|
35
103
|
export interface SolverDialect<P extends Problem = Problem, S = unknown> {
|
|
36
104
|
/** Nom unique du dialecte (ex. 'hungarian', 'highs', 'mdp'). */
|
|
@@ -39,6 +107,20 @@ export interface SolverDialect<P extends Problem = Problem, S = unknown> {
|
|
|
39
107
|
kind: ProblemKind;
|
|
40
108
|
/** Capacités (auto-sélection). */
|
|
41
109
|
capabilities: SolverCapabilities;
|
|
110
|
+
/**
|
|
111
|
+
* Forme acceptée (0.3.0). Absente : le dialecte est réputé accepter toute sa famille
|
|
112
|
+
* (comportement de la 0.2.x, conservé pour les dialectes tiers).
|
|
113
|
+
*/
|
|
114
|
+
shape?: ProblemShape;
|
|
115
|
+
/**
|
|
116
|
+
* Mesure de taille du problème, dans l'unité de `capabilities.maxSize` (0.3.0). Absente, ou
|
|
117
|
+
* rendant `null` : taille « à établir », le dépassement ne peut pas être jugé.
|
|
118
|
+
*/
|
|
119
|
+
size?: (problem: any) => number | null;
|
|
120
|
+
/** Ce que mesure `size`, dit en clair (catalogue, messages). */
|
|
121
|
+
sizeUnit?: string;
|
|
122
|
+
/** Remarques sur ce problème, reprises dans `solvedBy.notes` (facultatif). */
|
|
123
|
+
notes?: (problem: any) => string[];
|
|
42
124
|
/** Résout le problème. */
|
|
43
125
|
solve(problem: P, opts?: SolveOptions): S | Promise<S>;
|
|
44
126
|
}
|
|
@@ -96,8 +178,41 @@ export interface MilpProblem extends Problem {
|
|
|
96
178
|
/** Indices des variables devant être entières (défaut : toutes). */
|
|
97
179
|
integers?: number[];
|
|
98
180
|
}
|
|
99
|
-
/**
|
|
100
|
-
|
|
181
|
+
/**
|
|
182
|
+
* Statut d'un PLNE. En mode « au fil de l'eau » (`timeoutMs` ou `anytime`) s'ajoutent :
|
|
183
|
+
* `feasible` — meilleure solution trouvée à la limite, non prouvée optimale ;
|
|
184
|
+
* `unknown` — limite atteinte sans solution entière, et rien de prouvé (ni optimum, ni infaisabilité).
|
|
185
|
+
* `optimal`, `infeasible`, `unbounded` restent des PREUVES (exploration complète).
|
|
186
|
+
*/
|
|
187
|
+
export type MilpStatus = LpStatus | 'feasible' | 'unknown';
|
|
188
|
+
/** Compte rendu de la recherche d'un PLNE en mode « au fil de l'eau » (0.4.0). */
|
|
189
|
+
export interface MilpSearch {
|
|
190
|
+
/** Exploration complète : le statut est prouvé. */
|
|
191
|
+
complete: boolean;
|
|
192
|
+
/** Cause de l'arrêt avant la fin : délai (`time`), budget de nœuds (`nodes`) ; `null` si complète. */
|
|
193
|
+
stoppedBy: 'time' | 'nodes' | null;
|
|
194
|
+
/** Nœuds explorés (relaxations résolues). */
|
|
195
|
+
nodes: number;
|
|
196
|
+
/** Durée mesurée par l'horloge (ms). */
|
|
197
|
+
elapsedMs: number;
|
|
198
|
+
/**
|
|
199
|
+
* Meilleure borne de l'objectif encore possible (borne duale) : ≥ objectif en max, ≤ en min.
|
|
200
|
+
* `null` si inconnue (aucune relaxation résolue, infaisable, non borné).
|
|
201
|
+
*/
|
|
202
|
+
bound: number | null;
|
|
203
|
+
/** Écart relatif |bound − objective| / |objective| (formule Gurobi/HiGHS) ; 0 si prouvé ; `null` sans solution. */
|
|
204
|
+
gap: number | null;
|
|
205
|
+
}
|
|
206
|
+
/** Solution d'un PLNE — un LP (statut + x entiers + objectif), plus `search` en mode « au fil de l'eau ». */
|
|
207
|
+
export interface MilpSolution {
|
|
208
|
+
status: MilpStatus;
|
|
209
|
+
/** Valeurs des variables ; `[]` sans solution. En `feasible` : la meilleure trouvée. */
|
|
210
|
+
x: number[];
|
|
211
|
+
/** Valeur de l'objectif ; `NaN` sans solution. */
|
|
212
|
+
objective: number;
|
|
213
|
+
/** Présent seulement si `timeoutMs` ou `anytime` a été donné. */
|
|
214
|
+
search?: MilpSearch;
|
|
215
|
+
}
|
|
101
216
|
/** Arc orienté capacité/coût d'un réseau de flot. */
|
|
102
217
|
export interface FlowArc {
|
|
103
218
|
from: number;
|