@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.
@@ -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
- /** Résout un PLNE/MIP par branch & bound (relaxation LP = simplexe). */
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
- // Un nœud = contraintes de branchement supplémentaires (lignes ajoutées à A/b).
27
- const explore = (addA, addB, addRel) => {
28
- if (unbounded || nodes >= maxNodes)
29
- return;
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
- return;
62
+ continue;
41
63
  if (sol.status === 'unbounded') {
42
64
  unbounded = true;
43
- return;
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
- return;
71
+ continue;
50
72
  if (sense === 'min' && sol.objective >= best.objective - EPS)
51
- return;
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
- return;
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
- explore([...addA, row.slice()], [...addB, Math.floor(v)], [...addRel, '<=']);
76
- explore([...addA, row.slice()], [...addB, Math.ceil(v)], [...addRel, '>=']);
77
- };
78
- explore([], [], []);
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: 'infeasible', x: [], objective: NaN };
83
- return { status: 'optimal', x: best.x, objective: best.objective };
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
  },
@@ -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
- const avgWait = avgQueue / lambda; // Wq
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
- capabilities: { exact: true, online: true },
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
- capabilities: { exact: false, online: true },
30
+ shape: { fields: ['sample', 'trials'] },
31
+ capabilities: { exact: false, online: true, maxSize: null },
31
32
  solve(problem) {
32
33
  return monteCarlo(problem);
33
34
  },
@@ -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
- capabilities: { exact: true, online: false },
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
@@ -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
  },
@@ -89,7 +89,8 @@ export function tabuSearch(problem) {
89
89
  export const tabuDialect = {
90
90
  name: 'tabu',
91
91
  kind: 'metaheuristic',
92
- capabilities: { exact: false, online: false },
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
@@ -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
- * Résout un problème : par dialecte nommé, sinon auto-sélection par `kind`
16
- * (analogue à `getDialect()` piloté par `DB_DIALECT` côté ORM).
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
- * Choisit le meilleur dialecte pour un `kind` : on préfère l'EXACT, puis le plus
28
- * petit `maxSize` couvrant (heuristique simple, extensible).
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 pickBest(kind) {
31
- const candidates = listSolvers(kind);
32
- if (candidates.length === 0) {
33
- throw new Error(`Aucun dialecte enregistré pour le type « ${kind} »`);
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 candidates.sort((a, b) => Number(b.capabilities.exact) - Number(a.capabilities.exact))[0];
123
+ return { cmp: 0, by: null };
36
124
  }
37
125
  /**
38
- * Résout un problème : par dialecte nommé, sinon auto-sélection par `kind`
39
- * (analogue à `getDialect()` piloté par `DB_DIALECT` côté ORM).
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 dialect = opts?.dialect ? getSolver(opts.dialect) : pickBest(problem.kind);
43
- return dialect.solve(problem, opts);
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
- /** Borne pratique de taille (ex. n d'une matrice). */
21
- maxSize?: number;
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
- /** Solution d'un PLNE — même structure qu'un LP (statut + x entiers + objectif). */
100
- export type MilpSolution = LpSolution;
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;