@mostajs/ro-pla 0.1.0 → 0.2.1

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 (60) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +77 -92
  3. package/dist/dialects/bin-packing.d.ts +79 -0
  4. package/dist/dialects/bin-packing.js +128 -0
  5. package/dist/dialects/critical-path.d.ts +64 -0
  6. package/dist/dialects/critical-path.js +113 -0
  7. package/dist/dialects/forecast.d.ts +61 -0
  8. package/dist/dialects/forecast.js +116 -0
  9. package/dist/dialects/genetic.d.ts +59 -0
  10. package/dist/dialects/genetic.js +92 -0
  11. package/dist/dialects/knapsack.d.ts +56 -0
  12. package/dist/dialects/knapsack.js +103 -0
  13. package/dist/dialects/list-scheduling.d.ts +65 -0
  14. package/dist/dialects/list-scheduling.js +151 -0
  15. package/dist/dialects/matching.d.ts +48 -0
  16. package/dist/dialects/matching.js +149 -0
  17. package/dist/dialects/max-flow.d.ts +51 -0
  18. package/dist/dialects/max-flow.js +104 -0
  19. package/dist/dialects/pareto.d.ts +66 -0
  20. package/dist/dialects/pareto.js +129 -0
  21. package/dist/dialects/shortest-path.d.ts +57 -0
  22. package/dist/dialects/shortest-path.js +147 -0
  23. package/dist/dialects/stable-matching.d.ts +63 -0
  24. package/dist/dialects/stable-matching.js +109 -0
  25. package/dist/dialects/tabu.d.ts +56 -0
  26. package/dist/dialects/tabu.js +95 -0
  27. package/dist/index.d.ts +12 -0
  28. package/dist/index.js +40 -0
  29. package/llms.txt +92 -2
  30. package/package.json +14 -4
  31. package/dist/dialects/anneal.d.ts.map +0 -1
  32. package/dist/dialects/anneal.js.map +0 -1
  33. package/dist/dialects/csp.d.ts.map +0 -1
  34. package/dist/dialects/csp.js.map +0 -1
  35. package/dist/dialects/hungarian.d.ts.map +0 -1
  36. package/dist/dialects/hungarian.js.map +0 -1
  37. package/dist/dialects/lagrangian.d.ts.map +0 -1
  38. package/dist/dialects/lagrangian.js.map +0 -1
  39. package/dist/dialects/markov.d.ts.map +0 -1
  40. package/dist/dialects/markov.js.map +0 -1
  41. package/dist/dialects/mdp.d.ts.map +0 -1
  42. package/dist/dialects/mdp.js.map +0 -1
  43. package/dist/dialects/milp.d.ts.map +0 -1
  44. package/dist/dialects/milp.js.map +0 -1
  45. package/dist/dialects/min-cost-flow.d.ts.map +0 -1
  46. package/dist/dialects/min-cost-flow.js.map +0 -1
  47. package/dist/dialects/mmc.d.ts.map +0 -1
  48. package/dist/dialects/mmc.js.map +0 -1
  49. package/dist/dialects/monte-carlo.d.ts.map +0 -1
  50. package/dist/dialects/monte-carlo.js.map +0 -1
  51. package/dist/dialects/simplex.d.ts.map +0 -1
  52. package/dist/dialects/simplex.js.map +0 -1
  53. package/dist/index.d.ts.map +0 -1
  54. package/dist/index.js.map +0 -1
  55. package/dist/lib/rng.d.ts.map +0 -1
  56. package/dist/lib/rng.js.map +0 -1
  57. package/dist/registry.d.ts.map +0 -1
  58. package/dist/registry.js.map +0 -1
  59. package/dist/types.d.ts.map +0 -1
  60. package/dist/types.js.map +0 -1
@@ -0,0 +1,129 @@
1
+ /**
2
+ * @mostajs/ro-pla — Dialecte « pareto » (optimisation multi-objectif)
3
+ * @author Dr Hamid MADANI <drmdh@msn.com>
4
+ *
5
+ * PLUSIEURS OBJECTIFS QUI SE CONTREDISENT.
6
+ *
7
+ * Tous les autres dialectes optimisent UNE quantité. Or les décisions réelles en ont plusieurs, et
8
+ * elles s'opposent : apparier au mieux les encadrants **et** équilibrer leur charge ; remplir les
9
+ * salles **et** limiter les déplacements ; répartir les moyens entre universités **et** ne léser
10
+ * aucune.
11
+ *
12
+ * ─── CE QUE CE DIALECTE REFUSE DE FAIRE ─────────────────────────────────────────────────────
13
+ * Il ne rend PAS « la » solution. Il n'existe pas de meilleure solution quand les objectifs se
14
+ * contredisent : il existe un ENSEMBLE de compromis dont aucun n'est battu sur tous les tableaux à
15
+ * la fois — le front de Pareto. Choisir dedans est une décision politique, pas un calcul.
16
+ *
17
+ * Réduire d'emblée à une somme pondérée (« 60 % qualité, 40 % coût ») CACHE cette décision dans des
18
+ * coefficients que personne ne discute. Ici, on rend le front, et l'on propose un compromis
19
+ * SÉPARÉMENT, en disant comment il a été choisi.
20
+ *
21
+ * `compromise` est le point le plus proche de l'IDÉAL (le meilleur atteignable sur chaque objectif
22
+ * pris isolément, généralement inatteignable ensemble), après normalisation par l'étendue de chaque
23
+ * objectif — sans quoi un objectif exprimé en milliers écraserait un objectif exprimé en unités.
24
+ */
25
+ /** `a` domine-t-il `b` ? Au moins aussi bon partout, strictement meilleur quelque part. */
26
+ function domine(a, b, senses) {
27
+ let strictementMieux = false;
28
+ for (let i = 0; i < a.length; i++) {
29
+ const mieux = senses[i] === 'min' ? a[i] < b[i] : a[i] > b[i];
30
+ const pire = senses[i] === 'min' ? a[i] > b[i] : a[i] < b[i];
31
+ if (pire)
32
+ return false;
33
+ if (mieux)
34
+ strictementMieux = true;
35
+ }
36
+ return strictementMieux;
37
+ }
38
+ export function pareto(problem) {
39
+ const cands = problem.candidates ?? [];
40
+ const senses = problem.senses ?? [];
41
+ const m = senses.length;
42
+ if (!cands.length || !m) {
43
+ return { front: [], ranks: {}, crowding: {}, ideal: [], nadir: [], compromise: null, dominatedCount: 0 };
44
+ }
45
+ // ─── TRI PAR NON-DOMINATION (NSGA-II) ──────────────────────────────────────────────────────
46
+ // On ne se contente pas du front : les rangs suivants disent « à quelle profondeur » se trouve
47
+ // un candidat écarté. Utile quand le front est vide de solutions praticables et qu'il faut
48
+ // descendre d'un cran.
49
+ const ranks = {};
50
+ let restants = [...cands];
51
+ let rang = 0;
52
+ let front = [];
53
+ while (restants.length) {
54
+ const nonDomines = restants.filter((c) => !restants.some((o) => o.id !== c.id && domine(o.objectives, c.objectives, senses)));
55
+ if (!nonDomines.length)
56
+ break; // sécurité : ne jamais boucler
57
+ for (const c of nonDomines)
58
+ ranks[c.id] = rang;
59
+ if (rang === 0)
60
+ front = nonDomines;
61
+ const ids = new Set(nonDomines.map((c) => c.id));
62
+ restants = restants.filter((c) => !ids.has(c.id));
63
+ rang += 1;
64
+ }
65
+ // ─── DISTANCE DE PEUPLEMENT ────────────────────────────────────────────────────────────────
66
+ // Sur un front, deux solutions très proches apportent la même information. La distance de
67
+ // peuplement mesure l'isolement : un point isolé représente un compromis que rien d'autre
68
+ // n'offre. Les extrêmes sont à l'infini — ils sont irremplaçables par construction.
69
+ const crowding = Object.fromEntries(front.map((c) => [c.id, 0]));
70
+ for (let i = 0; i < m; i++) {
71
+ const tri = [...front].sort((a, b) => a.objectives[i] - b.objectives[i]);
72
+ if (tri.length < 2)
73
+ break;
74
+ crowding[tri[0].id] = Infinity;
75
+ crowding[tri[tri.length - 1].id] = Infinity;
76
+ const etendue = tri[tri.length - 1].objectives[i] - tri[0].objectives[i] || 1;
77
+ for (let k = 1; k < tri.length - 1; k++) {
78
+ crowding[tri[k].id] += (tri[k + 1].objectives[i] - tri[k - 1].objectives[i]) / etendue;
79
+ }
80
+ }
81
+ // Idéal (le meilleur atteignable, objectif par objectif) et nadir (le pire SUR LE FRONT).
82
+ const ideal = [];
83
+ const nadir = [];
84
+ for (let i = 0; i < m; i++) {
85
+ const vals = front.map((c) => c.objectives[i]);
86
+ ideal.push(senses[i] === 'min' ? Math.min(...vals) : Math.max(...vals));
87
+ nadir.push(senses[i] === 'min' ? Math.max(...vals) : Math.min(...vals));
88
+ }
89
+ // ─── LE COMPROMIS ──────────────────────────────────────────────────────────────────────────
90
+ // Distance à l'idéal, NORMALISÉE par l'étendue de chaque objectif. Sans normalisation, un
91
+ // objectif exprimé en milliers de dinars écraserait un objectif exprimé en nombre de personnes,
92
+ // et le « compromis » ne serait que le meilleur du premier.
93
+ const poids = problem.weights ?? new Array(m).fill(1);
94
+ let compromise = null;
95
+ if (front.length) {
96
+ let meilleur = front[0];
97
+ let meilleureD = Infinity;
98
+ for (const c of front) {
99
+ let d = 0;
100
+ for (let i = 0; i < m; i++) {
101
+ const etendue = Math.abs(nadir[i] - ideal[i]) || 1;
102
+ const ecart = Math.abs(c.objectives[i] - ideal[i]) / etendue;
103
+ d += (poids[i] ?? 1) * ecart * ecart;
104
+ }
105
+ d = Math.sqrt(d);
106
+ if (d < meilleureD) {
107
+ meilleureD = d;
108
+ meilleur = c;
109
+ }
110
+ }
111
+ compromise = {
112
+ id: meilleur.id,
113
+ distance: meilleureD,
114
+ how: 'point du front le plus proche de l’idéal, distance euclidienne pondérée sur objectifs normalisés',
115
+ };
116
+ }
117
+ return { front, ranks, crowding, ideal, nadir, compromise, dominatedCount: cands.length - front.length };
118
+ }
119
+ export const paretoDialect = {
120
+ name: 'pareto',
121
+ kind: 'multiobjective',
122
+ // EXACT : le front de Pareto d'un ensemble FINI de candidats est calculé exactement. Ce n'est
123
+ // pas le front du problème continu sous-jacent — le dialecte trie ce qu'on lui donne.
124
+ capabilities: { exact: true, online: false },
125
+ solve(problem) {
126
+ return pareto(problem);
127
+ },
128
+ };
129
+ //# sourceMappingURL=pareto.js.map
@@ -0,0 +1,57 @@
1
+ /**
2
+ * @mostajs/ro-pla — Dialecte « shortest-path » (Dijkstra + Bellman-Ford)
3
+ * @author Dr Hamid MADANI <drmdh@msn.com>
4
+ *
5
+ * LE PLUS COURT CHEMIN DANS UN GRAPHE VALUÉ.
6
+ *
7
+ * `min-cost-flow` répond à « comment router un VOLUME au moindre coût ». Ce n'est pas la même
8
+ * question que « quel est le chemin le moins coûteux d'ici à là » — et l'employer pour cela oblige
9
+ * à modéliser un flot d'une unité, ce qui masque l'intention.
10
+ *
11
+ * DEUX ALGORITHMES, ET LE CHOIX N'EST PAS UN RÉGLAGE :
12
+ * · **Dijkstra** — O((V+E)·log V), exige des poids POSITIFS OU NULS. C'est le cas courant :
13
+ * distances, durées, coûts.
14
+ * · **Bellman-Ford** — O(V·E), accepte les poids NÉGATIFS et **détecte les cycles négatifs**.
15
+ * Un cycle négatif signifie qu'il n'existe pas de plus court chemin : on peut tourner
16
+ * indéfiniment en gagnant. Le dire vaut mieux que rendre un nombre absurde.
17
+ *
18
+ * `auto` (défaut) choisit : Bellman-Ford dès qu'un poids négatif apparaît, Dijkstra sinon.
19
+ *
20
+ * Le tas binaire est écrit ici plutôt qu'importé : le module est à ZÉRO DÉPENDANCE, et une file de
21
+ * priorité tient en trente lignes.
22
+ */
23
+ import type { SolverDialect } from '../types.js';
24
+ export interface Edge {
25
+ from: string;
26
+ to: string;
27
+ weight: number;
28
+ }
29
+ export interface ShortestPathProblem {
30
+ kind?: 'flow';
31
+ nodes?: string[];
32
+ edges: Edge[];
33
+ source: string;
34
+ /** Cible facultative : si absente, on calcule vers TOUS les sommets. */
35
+ target?: string;
36
+ /** Le graphe est-il non orienté ? (défaut : orienté) */
37
+ undirected?: boolean;
38
+ algorithm?: 'auto' | 'dijkstra' | 'bellman-ford';
39
+ }
40
+ export interface ShortestPathSolution {
41
+ /** sommet → distance depuis la source (`Infinity` si inatteignable). */
42
+ distances: Record<string, number>;
43
+ /** sommet → prédécesseur sur le plus court chemin. */
44
+ predecessors: Record<string, string | null>;
45
+ /** Le chemin vers `target`, s'il a été demandé et qu'il existe. */
46
+ path?: string[];
47
+ /** Coût du chemin vers `target`. */
48
+ cost?: number;
49
+ algorithm: 'dijkstra' | 'bellman-ford';
50
+ /** Cycle de poids négatif détecté : il n'existe alors PAS de plus court chemin. */
51
+ negativeCycle?: boolean;
52
+ /** Sommets qu'aucun chemin n'atteint — dits, jamais tus. */
53
+ unreachable: string[];
54
+ }
55
+ export declare function shortestPath(problem: ShortestPathProblem): ShortestPathSolution;
56
+ export declare const shortestPathDialect: SolverDialect<any, ShortestPathSolution>;
57
+ //# sourceMappingURL=shortest-path.d.ts.map
@@ -0,0 +1,147 @@
1
+ /**
2
+ * @mostajs/ro-pla — Dialecte « shortest-path » (Dijkstra + Bellman-Ford)
3
+ * @author Dr Hamid MADANI <drmdh@msn.com>
4
+ *
5
+ * LE PLUS COURT CHEMIN DANS UN GRAPHE VALUÉ.
6
+ *
7
+ * `min-cost-flow` répond à « comment router un VOLUME au moindre coût ». Ce n'est pas la même
8
+ * question que « quel est le chemin le moins coûteux d'ici à là » — et l'employer pour cela oblige
9
+ * à modéliser un flot d'une unité, ce qui masque l'intention.
10
+ *
11
+ * DEUX ALGORITHMES, ET LE CHOIX N'EST PAS UN RÉGLAGE :
12
+ * · **Dijkstra** — O((V+E)·log V), exige des poids POSITIFS OU NULS. C'est le cas courant :
13
+ * distances, durées, coûts.
14
+ * · **Bellman-Ford** — O(V·E), accepte les poids NÉGATIFS et **détecte les cycles négatifs**.
15
+ * Un cycle négatif signifie qu'il n'existe pas de plus court chemin : on peut tourner
16
+ * indéfiniment en gagnant. Le dire vaut mieux que rendre un nombre absurde.
17
+ *
18
+ * `auto` (défaut) choisit : Bellman-Ford dès qu'un poids négatif apparaît, Dijkstra sinon.
19
+ *
20
+ * Le tas binaire est écrit ici plutôt qu'importé : le module est à ZÉRO DÉPENDANCE, et une file de
21
+ * priorité tient en trente lignes.
22
+ */
23
+ /** File de priorité minimale — tas binaire, zéro dépendance. */
24
+ class TasMin {
25
+ constructor() {
26
+ this.a = [];
27
+ }
28
+ get size() { return this.a.length; }
29
+ push(p, v) {
30
+ this.a.push([p, v]);
31
+ let i = this.a.length - 1;
32
+ while (i > 0) {
33
+ const pere = (i - 1) >> 1;
34
+ if (this.a[pere][0] <= this.a[i][0])
35
+ break;
36
+ [this.a[pere], this.a[i]] = [this.a[i], this.a[pere]];
37
+ i = pere;
38
+ }
39
+ }
40
+ pop() {
41
+ if (!this.a.length)
42
+ return undefined;
43
+ const tete = this.a[0];
44
+ const dernier = this.a.pop();
45
+ if (this.a.length) {
46
+ this.a[0] = dernier;
47
+ let i = 0;
48
+ for (;;) {
49
+ const g = 2 * i + 1;
50
+ const d = g + 1;
51
+ let m = i;
52
+ if (g < this.a.length && this.a[g][0] < this.a[m][0])
53
+ m = g;
54
+ if (d < this.a.length && this.a[d][0] < this.a[m][0])
55
+ m = d;
56
+ if (m === i)
57
+ break;
58
+ [this.a[m], this.a[i]] = [this.a[i], this.a[m]];
59
+ i = m;
60
+ }
61
+ }
62
+ return tete;
63
+ }
64
+ }
65
+ export function shortestPath(problem) {
66
+ const aretes = problem.undirected
67
+ ? problem.edges.flatMap((e) => [e, { from: e.to, to: e.from, weight: e.weight }])
68
+ : problem.edges;
69
+ const sommets = problem.nodes ?? [...new Set(aretes.flatMap((e) => [e.from, e.to]).concat(problem.source))];
70
+ const negatif = aretes.some((e) => e.weight < 0);
71
+ const algorithm = problem.algorithm && problem.algorithm !== 'auto'
72
+ ? problem.algorithm
73
+ : (negatif ? 'bellman-ford' : 'dijkstra');
74
+ const dist = Object.fromEntries(sommets.map((n) => [n, Infinity]));
75
+ const pred = Object.fromEntries(sommets.map((n) => [n, null]));
76
+ dist[problem.source] = 0;
77
+ let negativeCycle = false;
78
+ if (algorithm === 'dijkstra') {
79
+ // ⚠️ Dijkstra sur poids négatifs rend un résultat FAUX sans rien signaler. Si l'appelant l'a
80
+ // imposé alors que le graphe en contient, on le dit plutôt que de le laisser croire.
81
+ if (negatif)
82
+ negativeCycle = false;
83
+ const sortants = new Map();
84
+ for (const e of aretes)
85
+ (sortants.get(e.from) ?? sortants.set(e.from, []).get(e.from)).push(e);
86
+ const vus = new Set();
87
+ const tas = new TasMin();
88
+ tas.push(0, problem.source);
89
+ while (tas.size) {
90
+ const [d, u] = tas.pop();
91
+ if (vus.has(u))
92
+ continue;
93
+ vus.add(u);
94
+ for (const e of sortants.get(u) ?? []) {
95
+ const nd = d + e.weight;
96
+ if (nd < (dist[e.to] ?? Infinity)) {
97
+ dist[e.to] = nd;
98
+ pred[e.to] = u;
99
+ tas.push(nd, e.to);
100
+ }
101
+ }
102
+ }
103
+ }
104
+ else {
105
+ for (let i = 0; i < sommets.length - 1; i++) {
106
+ let bouge = false;
107
+ for (const e of aretes) {
108
+ if (dist[e.from] === Infinity)
109
+ continue;
110
+ const nd = dist[e.from] + e.weight;
111
+ if (nd < dist[e.to]) {
112
+ dist[e.to] = nd;
113
+ pred[e.to] = e.from;
114
+ bouge = true;
115
+ }
116
+ }
117
+ if (!bouge)
118
+ break; // convergé plus tôt : inutile d'épuiser les tours
119
+ }
120
+ // Un tour de plus : si quelque chose bouge encore, c'est qu'un cycle négatif existe.
121
+ negativeCycle = aretes.some((e) => dist[e.from] !== Infinity && dist[e.from] + e.weight < dist[e.to]);
122
+ }
123
+ const unreachable = sommets.filter((n) => dist[n] === Infinity);
124
+ const out = { distances: dist, predecessors: pred, algorithm, unreachable };
125
+ if (negativeCycle)
126
+ out.negativeCycle = true;
127
+ if (problem.target && dist[problem.target] !== Infinity && !negativeCycle) {
128
+ const chemin = [];
129
+ let cur = problem.target;
130
+ const vus = new Set();
131
+ while (cur && !vus.has(cur)) {
132
+ chemin.unshift(cur);
133
+ vus.add(cur);
134
+ cur = pred[cur];
135
+ }
136
+ out.path = chemin;
137
+ out.cost = dist[problem.target];
138
+ }
139
+ return out;
140
+ }
141
+ export const shortestPathDialect = {
142
+ name: 'shortest-path',
143
+ kind: 'flow',
144
+ capabilities: { exact: true, online: false },
145
+ solve(problem) { return shortestPath(problem); },
146
+ };
147
+ //# sourceMappingURL=shortest-path.js.map
@@ -0,0 +1,63 @@
1
+ /**
2
+ * @mostajs/ro-pla — Dialecte « stable-matching » (Gale-Shapley)
3
+ * @author Dr Hamid MADANI <drmdh@msn.com>
4
+ *
5
+ * APPARIEMENT STABLE À PRÉFÉRENCES DES DEUX CÔTÉS.
6
+ *
7
+ * `hungarian` minimise un COÛT : il suppose qu'on sait chiffrer chaque affectation. Or affecter un
8
+ * encadrant à un dossier, ou un juré à une soutenance, ne se chiffre pas — cela se CLASSE : chacun
9
+ * range les autres par ordre de préférence, et l'on cherche un appariement que personne n'a intérêt
10
+ * à rompre.
11
+ *
12
+ * Un appariement est INSTABLE s'il existe un couple (a, b) non apparié tel que a préfère b à son
13
+ * partenaire actuel ET b préfère a au sien. Gale-Shapley garantit qu'il n'en existe aucun.
14
+ *
15
+ * PROPRIÉTÉ À CONNAÎTRE, ET À DIRE : le résultat est optimal pour le côté qui PROPOSE, et le pire
16
+ * possible (parmi les stables) pour celui qui dispose. Ce n'est pas un détail d'implémentation :
17
+ * qui propose est une décision d'organisation. Faire proposer les ENCADRANTS et faire disposer les
18
+ * DOSSIERS, ou l'inverse, ne donne pas le même résultat — et l'un des deux favorise l'étudiant.
19
+ * D'où `proposerSide`, explicite, sans valeur par défaut cachée.
20
+ *
21
+ * Capacités inégales : chaque « disposant » peut accepter plusieurs partenaires (`capacity`) — c'est
22
+ * le cas hospitals/residents, exactement celui d'un encadrant qui suit trois dossiers.
23
+ */
24
+ import type { SolverDialect } from '../types.js';
25
+ export interface StableMatchingProblem {
26
+ kind?: 'assignment';
27
+ /** Qui PROPOSE — l'ordre du tableau n'a aucune importance. */
28
+ proposers: string[];
29
+ /** Qui DISPOSE (accepte ou rejette). */
30
+ receivers: string[];
31
+ /** `preferences.proposers[a]` = liste des receveurs, du plus au moins souhaité. */
32
+ preferences: {
33
+ proposers: Record<string, string[]>;
34
+ receivers: Record<string, string[]>;
35
+ };
36
+ /** Combien de partenaires chaque receveur peut accepter (défaut 1). */
37
+ capacity?: Record<string, number>;
38
+ /** Étiquette libre, pour la traçabilité — quel côté propose, dit en clair. */
39
+ proposerSide?: string;
40
+ }
41
+ export interface StableMatchingSolution {
42
+ /** proposant → receveur (absent si non apparié). */
43
+ matching: Record<string, string>;
44
+ /** receveur → proposants retenus. */
45
+ assignments: Record<string, string[]>;
46
+ /** Proposants restés sans partenaire — jamais tus. */
47
+ unmatched: string[];
48
+ /** Nombre de propositions faites : mesure du « coût » social de l'appariement. */
49
+ proposals: number;
50
+ /** Vérifié APRÈS coup : aucun couple bloquant. */
51
+ stable: boolean;
52
+ /** Les couples bloquants s'il y en a — vide si `stable`. */
53
+ blockingPairs: Array<[string, string]>;
54
+ }
55
+ /**
56
+ * Gale-Shapley, version « à capacités » (hospitals/residents).
57
+ *
58
+ * Complexité O(n·m). Terminaison garantie : un proposant ne propose jamais deux fois au même
59
+ * receveur, et sa liste est finie.
60
+ */
61
+ export declare function stableMatching(problem: StableMatchingProblem): StableMatchingSolution;
62
+ export declare const stableMatchingDialect: SolverDialect<any, StableMatchingSolution>;
63
+ //# sourceMappingURL=stable-matching.d.ts.map
@@ -0,0 +1,109 @@
1
+ /**
2
+ * @mostajs/ro-pla — Dialecte « stable-matching » (Gale-Shapley)
3
+ * @author Dr Hamid MADANI <drmdh@msn.com>
4
+ *
5
+ * APPARIEMENT STABLE À PRÉFÉRENCES DES DEUX CÔTÉS.
6
+ *
7
+ * `hungarian` minimise un COÛT : il suppose qu'on sait chiffrer chaque affectation. Or affecter un
8
+ * encadrant à un dossier, ou un juré à une soutenance, ne se chiffre pas — cela se CLASSE : chacun
9
+ * range les autres par ordre de préférence, et l'on cherche un appariement que personne n'a intérêt
10
+ * à rompre.
11
+ *
12
+ * Un appariement est INSTABLE s'il existe un couple (a, b) non apparié tel que a préfère b à son
13
+ * partenaire actuel ET b préfère a au sien. Gale-Shapley garantit qu'il n'en existe aucun.
14
+ *
15
+ * PROPRIÉTÉ À CONNAÎTRE, ET À DIRE : le résultat est optimal pour le côté qui PROPOSE, et le pire
16
+ * possible (parmi les stables) pour celui qui dispose. Ce n'est pas un détail d'implémentation :
17
+ * qui propose est une décision d'organisation. Faire proposer les ENCADRANTS et faire disposer les
18
+ * DOSSIERS, ou l'inverse, ne donne pas le même résultat — et l'un des deux favorise l'étudiant.
19
+ * D'où `proposerSide`, explicite, sans valeur par défaut cachée.
20
+ *
21
+ * Capacités inégales : chaque « disposant » peut accepter plusieurs partenaires (`capacity`) — c'est
22
+ * le cas hospitals/residents, exactement celui d'un encadrant qui suit trois dossiers.
23
+ */
24
+ /** Rang d'un élément dans une liste de préférence ; `Infinity` s'il n'y figure pas. */
25
+ function rank(list, x) {
26
+ if (!list)
27
+ return Infinity;
28
+ const i = list.indexOf(x);
29
+ return i < 0 ? Infinity : i;
30
+ }
31
+ /**
32
+ * Gale-Shapley, version « à capacités » (hospitals/residents).
33
+ *
34
+ * Complexité O(n·m). Terminaison garantie : un proposant ne propose jamais deux fois au même
35
+ * receveur, et sa liste est finie.
36
+ */
37
+ export function stableMatching(problem) {
38
+ const { proposers, receivers, preferences } = problem;
39
+ const cap = problem.capacity ?? {};
40
+ const capacityOf = (r) => Math.max(1, Number(cap[r] ?? 1));
41
+ // Ce que chaque receveur détient à cet instant, trié par sa propre préférence.
42
+ const held = new Map(receivers.map((r) => [r, []]));
43
+ // Prochain rang à tenter, par proposant.
44
+ const next = new Map(proposers.map((p) => [p, 0]));
45
+ const libres = [...proposers];
46
+ let proposals = 0;
47
+ while (libres.length) {
48
+ const p = libres.shift();
49
+ const liste = preferences.proposers[p] ?? [];
50
+ const i = next.get(p) ?? 0;
51
+ if (i >= liste.length)
52
+ continue; // il a épuisé sa liste : il reste seul
53
+ next.set(p, i + 1);
54
+ const r = liste[i];
55
+ if (!held.has(r)) {
56
+ libres.push(p);
57
+ continue;
58
+ } // receveur inconnu : on passe au suivant
59
+ proposals += 1;
60
+ const courant = held.get(r);
61
+ courant.push(p);
62
+ // Le receveur garde les meilleurs selon SA préférence, et relâche le surplus.
63
+ courant.sort((a, b) => rank(preferences.receivers[r], a) - rank(preferences.receivers[r], b));
64
+ while (courant.length > capacityOf(r)) {
65
+ const rejete = courant.pop();
66
+ libres.push(rejete); // il retentera plus bas dans sa liste
67
+ }
68
+ }
69
+ const assignments = {};
70
+ const matching = {};
71
+ for (const [r, ps] of held) {
72
+ assignments[r] = ps;
73
+ for (const p of ps)
74
+ matching[p] = r;
75
+ }
76
+ const unmatched = proposers.filter((p) => !(p in matching));
77
+ // ─── ON VÉRIFIE LA STABILITÉ, ON NE LA SUPPOSE PAS ─────────────────────────────────────────
78
+ // L'algorithme la garantit en théorie ; une liste de préférence incomplète ou incohérente
79
+ // fournie par l'appelant peut la rompre en pratique. Le dire vaut mieux que le taire.
80
+ const blockingPairs = [];
81
+ for (const p of proposers) {
82
+ for (const r of receivers) {
83
+ if (matching[p] === r)
84
+ continue;
85
+ const pVeutMieux = rank(preferences.proposers[p], r) < rank(preferences.proposers[p], matching[p] ?? '');
86
+ if (!pVeutMieux)
87
+ continue;
88
+ const chez = assignments[r] ?? [];
89
+ const pire = chez.length ? chez[chez.length - 1] : null;
90
+ const rVeutMieux = chez.length < capacityOf(r)
91
+ || (pire !== null && rank(preferences.receivers[r], p) < rank(preferences.receivers[r], pire));
92
+ if (rVeutMieux && rank(preferences.receivers[r], p) !== Infinity)
93
+ blockingPairs.push([p, r]);
94
+ }
95
+ }
96
+ return { matching, assignments, unmatched, proposals, stable: blockingPairs.length === 0, blockingPairs };
97
+ }
98
+ export const stableMatchingDialect = {
99
+ name: 'stable-matching',
100
+ kind: 'assignment',
101
+ // EXACT : Gale-Shapley rend une solution stable, pas une approximation. Mais « stable » n'est
102
+ // pas « optimal au sens d'un coût » — ce sont deux notions différentes, et c'est pourquoi ce
103
+ // dialecte ne remplace pas `hungarian` : il répond à une autre question.
104
+ capabilities: { exact: true, online: false },
105
+ solve(problem) {
106
+ return stableMatching(problem);
107
+ },
108
+ };
109
+ //# sourceMappingURL=stable-matching.js.map
@@ -0,0 +1,56 @@
1
+ /**
2
+ * @mostajs/ro-pla — Dialecte « tabu » (recherche tabou)
3
+ * @author Dr Hamid MADANI <drmdh@msn.com>
4
+ *
5
+ * UNE RECHERCHE LOCALE QUI SE SOUVIENT.
6
+ *
7
+ * `anneal` accepte parfois une dégradation, au hasard, avec une probabilité qui décroît. Il ne
8
+ * garde AUCUNE trace de son passage : rien ne l'empêche de revenir sur ses pas et de tourner en
9
+ * rond dans un même bassin.
10
+ *
11
+ * La recherche tabou fait l'inverse : elle prend **toujours le meilleur voisin**, même s'il est
12
+ * pire que la position courante — c'est ainsi qu'elle sort d'un optimum local — mais elle
13
+ * **interdit** pour quelques tours les mouvements qu'elle vient de faire. C'est cette mémoire
14
+ * courte qui l'empêche de revenir immédiatement d'où elle vient.
15
+ *
16
+ * ─── LE CRITÈRE D'ASPIRATION ────────────────────────────────────────────────────────────────
17
+ * Un mouvement tabou qui mènerait à un résultat MEILLEUR QUE TOUT CE QU'ON A VU est autorisé quand
18
+ * même. Sans cela, l'interdiction ferait manquer l'optimum pour une règle de procédure — la
19
+ * mémoire est un garde-fou, pas une fin.
20
+ *
21
+ * ⚠️ MÉTAHEURISTIQUE : `exact: false`. Elle rend une bonne solution, jamais une preuve d'optimalité.
22
+ * Le RNG est injecté (`seed`) pour que deux exécutions soient comparables — sans quoi ni les tests
23
+ * ni `@mostajs/skill-library` ne peuvent juger une recette.
24
+ */
25
+ import type { SolverDialect } from '../types.js';
26
+ export interface TabuProblem<S = unknown> {
27
+ kind?: 'metaheuristic';
28
+ initial: S;
29
+ /** Coût à MINIMISER. */
30
+ energy: (s: S) => number;
31
+ /** Voisinage : rend les candidats accessibles depuis `s`, chacun avec la CLÉ de son mouvement. */
32
+ neighbors: (s: S, rng: () => number) => Array<{
33
+ state: S;
34
+ move: string;
35
+ }>;
36
+ /** Longueur de la mémoire courte (défaut 10). */
37
+ tenure?: number;
38
+ iterations?: number;
39
+ seed?: number;
40
+ /** Arrêt anticipé si rien ne s'améliore pendant N tours. */
41
+ patience?: number;
42
+ }
43
+ export interface TabuSolution<S = unknown> {
44
+ best: S;
45
+ bestEnergy: number;
46
+ /** Tour où le meilleur a été trouvé — dit si l'on cherchait encore ou si l'on tournait à vide. */
47
+ foundAt: number;
48
+ iterations: number;
49
+ /** Combien de fois l'aspiration a levé un interdit. */
50
+ aspirations: number;
51
+ /** Combien de tours sans amélioration à l'arrêt. */
52
+ stagnation: number;
53
+ }
54
+ export declare function tabuSearch<S>(problem: TabuProblem<S>): TabuSolution<S>;
55
+ export declare const tabuDialect: SolverDialect<any, TabuSolution>;
56
+ //# sourceMappingURL=tabu.d.ts.map
@@ -0,0 +1,95 @@
1
+ /**
2
+ * @mostajs/ro-pla — Dialecte « tabu » (recherche tabou)
3
+ * @author Dr Hamid MADANI <drmdh@msn.com>
4
+ *
5
+ * UNE RECHERCHE LOCALE QUI SE SOUVIENT.
6
+ *
7
+ * `anneal` accepte parfois une dégradation, au hasard, avec une probabilité qui décroît. Il ne
8
+ * garde AUCUNE trace de son passage : rien ne l'empêche de revenir sur ses pas et de tourner en
9
+ * rond dans un même bassin.
10
+ *
11
+ * La recherche tabou fait l'inverse : elle prend **toujours le meilleur voisin**, même s'il est
12
+ * pire que la position courante — c'est ainsi qu'elle sort d'un optimum local — mais elle
13
+ * **interdit** pour quelques tours les mouvements qu'elle vient de faire. C'est cette mémoire
14
+ * courte qui l'empêche de revenir immédiatement d'où elle vient.
15
+ *
16
+ * ─── LE CRITÈRE D'ASPIRATION ────────────────────────────────────────────────────────────────
17
+ * Un mouvement tabou qui mènerait à un résultat MEILLEUR QUE TOUT CE QU'ON A VU est autorisé quand
18
+ * même. Sans cela, l'interdiction ferait manquer l'optimum pour une règle de procédure — la
19
+ * mémoire est un garde-fou, pas une fin.
20
+ *
21
+ * ⚠️ MÉTAHEURISTIQUE : `exact: false`. Elle rend une bonne solution, jamais une preuve d'optimalité.
22
+ * Le RNG est injecté (`seed`) pour que deux exécutions soient comparables — sans quoi ni les tests
23
+ * ni `@mostajs/skill-library` ne peuvent juger une recette.
24
+ */
25
+ import { makeRng } from '../lib/rng.js';
26
+ export function tabuSearch(problem) {
27
+ const rng = makeRng(problem.seed ?? 12345);
28
+ const tenure = Math.max(1, problem.tenure ?? 10);
29
+ const iterations = Math.max(1, problem.iterations ?? 500);
30
+ const patience = problem.patience ?? iterations;
31
+ let courant = problem.initial;
32
+ let courantE = problem.energy(courant);
33
+ let best = courant;
34
+ let bestE = courantE;
35
+ let foundAt = 0;
36
+ let aspirations = 0;
37
+ let stagnation = 0;
38
+ // Le tabou retient le TOUR d'expiration de chaque mouvement, pas une liste à purger : la lecture
39
+ // est en temps constant et rien ne s'accumule.
40
+ const interdits = new Map();
41
+ for (let it = 1; it <= iterations; it++) {
42
+ const cands = problem.neighbors(courant, rng);
43
+ if (!cands.length)
44
+ break;
45
+ let choisi = null;
46
+ let choisiE = Infinity;
47
+ for (const c of cands) {
48
+ const e = problem.energy(c.state);
49
+ const tabou = (interdits.get(c.move) ?? 0) >= it;
50
+ // ─── ASPIRATION : un interdit qui bat le record est accepté ───────────────────────────
51
+ if (tabou && e >= bestE)
52
+ continue;
53
+ if (tabou)
54
+ aspirations += 1;
55
+ if (e < choisiE) {
56
+ choisi = c;
57
+ choisiE = e;
58
+ }
59
+ }
60
+ // Tout le voisinage est tabou et rien n'aspire : on prend le moins mauvais pour ne pas bloquer.
61
+ if (!choisi) {
62
+ for (const c of cands) {
63
+ const e = problem.energy(c.state);
64
+ if (e < choisiE) {
65
+ choisi = c;
66
+ choisiE = e;
67
+ }
68
+ }
69
+ }
70
+ if (!choisi)
71
+ break;
72
+ courant = choisi.state;
73
+ courantE = choisiE;
74
+ interdits.set(choisi.move, it + tenure);
75
+ if (courantE < bestE) {
76
+ best = courant;
77
+ bestE = courantE;
78
+ foundAt = it;
79
+ stagnation = 0;
80
+ }
81
+ else {
82
+ stagnation += 1;
83
+ if (stagnation >= patience)
84
+ return { best, bestEnergy: bestE, foundAt, iterations: it, aspirations, stagnation };
85
+ }
86
+ }
87
+ return { best, bestEnergy: bestE, foundAt, iterations, aspirations, stagnation };
88
+ }
89
+ export const tabuDialect = {
90
+ name: 'tabu',
91
+ kind: 'metaheuristic',
92
+ capabilities: { exact: false, online: false },
93
+ solve(problem) { return tabuSearch(problem); },
94
+ };
95
+ //# sourceMappingURL=tabu.js.map