@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/llms.txt CHANGED
@@ -1,32 +1,83 @@
1
1
  # @mostajs/ro-pla — fiche LLM
2
2
 
3
- > Programmation linéaire & recherche opérationnelle : 23 dialectes sélectionnés par FAMILLE de
4
- > problème (`kind`), pas par nom d'algorithme. Simplexe, PLNE (branch & bound), flots, CSP, chaînes
5
- > de Markov, MDP, files M/M/c, ordonnancement, Pareto, trois métaheuristiques, prévision.
6
- > API en service depuis la 0.1.0 ; 0.2.1 en production. Zéro dépendance, aucune E/S.
3
+ > Programmation linéaire & recherche opérationnelle : 23 dialectes sous un REGISTRE. Simplexe, PLNE
4
+ > (branch & bound), flots, CSP, chaînes de Markov, MDP, files M/M/c, ordonnancement, Pareto, trois
5
+ > métaheuristiques, prévision. Zéro dépendance, aucune E/S. ESM seul (condition `import`) : pas de
6
+ > chargement CommonJS (require).
7
7
  >
8
- > NE CONTIENT PAS, malgré ce qu'annonçaient les versions antérieures de cette fiche :
9
- > Dantzig-Wolfe, Benders, réseaux de neurones, PSO, ACO, GRASP, NSGA-II en propre (seul son tri par
10
- > non-domination est repris dans `pareto`), simulation à événements discrets, contraintes globales
11
- > cumulative, dualité / analyse de sensibilité.
8
+ > NE CONTIENT PAS : Dantzig-Wolfe, Benders, réseaux de neurones, PSO, ACO, GRASP, NSGA-II en propre
9
+ > (seul son tri par non-domination est repris dans `pareto`), simulation à événements discrets,
10
+ > contraintes globales cumulative, dualité / analyse de sensibilité.
12
11
 
13
- - Version: 0.2.1 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
14
- - Chemin: mostajs/mosta-ro-pla · Statut: 23 dialectes, 12 familles, 15 exacts / 8 approches, 111 essais verts.
15
- - ATTENTION maxSize est DECLARATIVE et n'est PAS appliquee. Six dialectes en portent une (hungarian
16
- 1000, simplex 200, branch-and-bound 50, min-cost-flow 5000, markov 500, mdp 10000) ; un appel
17
- au-dela rend un resultat SANS AVERTISSEMENT (mesure : simplex rend `optimal` a 200, 300 et 600
18
- variables). Les 17 autres n'en declarent aucune, ce qui ne veut dire NI « pas de limite » NI
19
- « limite inconnue ». Ne traitez maxSize que comme une indication d'auteur : jamais mesuree.
20
- - ATTENTION solve({kind}) ne dit PAS quel dialecte a ete retenu. Pour savoir si un resultat est
21
- prouve, lire getSolver(nom).capabilities.exact — le registre ne le rend pas encore (jalon 0.3.0).
22
- - Renommé depuis « mosta-constraints » ; périmètre élargi PL + RO + stochastique.
12
+ - Version: 0.4.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
13
+ - Statut: 23 dialectes, 12 familles, 15 exacts / 8 approches.
14
+
15
+ ## SÉLECTION (0.3.0) — À LIRE AVANT D'APPELER `solve`
16
+ - NOMMER LE DIALECTE RESTE LA VOIE SÛRE : `solve(problème, { dialect: 'shortest-path' })` — aucun
17
+ contrôle de forme, résultat de l'algorithme nommé.
18
+ - Sans dialecte nommé, `solve` choisit dans la famille `problem.kind` PAR LA FORME du problème : chaque
19
+ dialecte déclare `shape.fields` (champs obligatoires) et parfois `shape.test` (ex. arêtes à `weight`
20
+ → shortest-path, à `capacity` → max-flow). `acceptsShape(dialecte, problème)` rend ce verdict.
21
+ - Puis, s'il reste plusieurs candidats : exact d'abord ; plus petite `maxSize` qui couvre la taille ;
22
+ bornes « à établir » ; bornes dépassées ; ordre d'enregistrement.
23
+ - Erreurs explicites, `SolverSelectionError` avec `code` : `RO_PLA_NO_KIND` (ni `kind` ni dialecte),
24
+ `RO_PLA_NO_DIALECT` (famille sans dialecte), `RO_PLA_NO_SHAPE` (aucune forme reconnue ; le message
25
+ nomme famille, candidats et champs attendus), `RO_PLA_AMBIGUOUS_SHAPE` (plusieurs formes : nommer le
26
+ dialecte). En 0.2.x ces cas plantaient — ou, pour `forecast` et `bin-packing`/`list-scheduling`,
27
+ rendaient une réponse fausse sans le dire.
28
+ - Le résultat de `solve` est une COPIE de la solution plus `solvedBy` :
29
+ `{ dialect, kind, exact, online, reason, criterion, size, maxSize, beyondDeclaredSize, notes }`.
30
+ reason ∈ 'named' | 'only-in-kind' | 'only-shape-match' | 'ranked' ; criterion ∈ 'exact' | 'size' |
31
+ 'registration-order' | null. Les fonctions directes (`hungarian`, `simplex`, `mmc`…) ne portent PAS
32
+ `solvedBy` et n'ont pas changé de forme.
33
+ - ATTENTION `solvedBy` peut MANQUER sur une solution produite avant la 0.3.0 et rejouée depuis une
34
+ mémoire (cache de recettes, par exemple) : ne pas en supposer la présence.
35
+ - ATTENTION `maxSize` est DÉCLARATIVE et JAMAIS MESURÉE. Elle n'est pas appliquée : un problème
36
+ au-delà est résolu quand même, et `solvedBy.beyondDeclaredSize` vaut `true`. `null` = « à établir »
37
+ (borne ou mesure de taille inconnue) : ni « pas de limite » ni « limite respectée ».
38
+ `checkSize(dialecte | nom, problème) → { dialect, size, maxSize, beyondDeclaredSize }` le dit sans
39
+ résoudre. Bornes : hungarian 1000 (ordre de la matrice), simplex 200 (variables), branch-and-bound
40
+ 50 (variables entières), markov 500 (états), min-cost-flow 5000 et mdp 10000 (mesure à établir :
41
+ dépassement jamais jugé) ; les 17 autres : `maxSize: null`.
42
+
43
+ <!-- engendre:dialectes:debut -->
44
+ Dialectes (23, 12 familles, 15 exacts / 8 approches) — nom | kind | exact | maxSize | champs de forme :
45
+ - hungarian | assignment | exact | 1000 (ordre de la matrice des coûts) | cost
46
+ - simplex | lp | exact | 200 (nombre de variables) | c, A, b
47
+ - branch-and-bound | milp | exact | 50 (nombre de variables entières) | c, A, b
48
+ - min-cost-flow | flow | exact | 5000 | arcs, source, sink
49
+ - mmc | queue | exact | à établir | lambda, mu
50
+ - markov | markov | exact | 500 (nombre d'états) | P
51
+ - mdp | decision | exact | 10000 | transition, reward, gamma
52
+ - backtrack-csp | csp | exact | à établir | variables, domains, constraints
53
+ - anneal | metaheuristic | approche | à établir | initial, energy, neighbor
54
+ - monte-carlo | simulation | approche | à établir | sample, trials
55
+ - lagrangian | lp | approche | à établir | c, linkingA, linkingB, subA, subB
56
+ - stable-matching | assignment | exact | à établir | proposers, receivers, preferences
57
+ - critical-path | scheduling | exact | à établir | activities
58
+ - bin-packing | scheduling | approche | à établir | items, bins
59
+ - pareto | multiobjective | exact | à établir | candidates, senses
60
+ - list-scheduling | scheduling | approche | à établir | tasks, capacities
61
+ - shortest-path | flow | exact | à établir | edges, source
62
+ - max-flow | flow | exact | à établir | edges, source, sink
63
+ - matching | assignment | exact | à établir | edges
64
+ - knapsack | milp | exact | à établir | items, capacity
65
+ - tabu | metaheuristic | approche | à établir | initial, energy, neighbors
66
+ - genetic | metaheuristic | approche | à établir | population, fitness, crossover, mutate
67
+ - forecast | simulation | approche | à établir | series, horizon
68
+ <!-- engendre:dialectes:fin -->
69
+
70
+ ## IMPLÉMENTÉ — architecture « un dialecte par algorithme » (façon ORM)
71
+ Le module n'expose PAS un builder fluide mais un REGISTRE de dialectes, sélectionnés par nom ou par
72
+ famille et forme (comme `DB_DIALECT` pour un ORM).
73
+ - Contrat `SolverDialect<P,S> { name, kind, capabilities{exact,online,maxSize?:number|null,multiObjective?},
74
+ shape?{fields,test?,testLabel?}, size?(problem), sizeUnit?, notes?(problem), solve(problem,opts?) }`.
75
+ - Registre : `registerSolver(d)`, `getSolver(name)`, `listSolvers(kind?)`, `clearSolvers()`,
76
+ `registerBuiltinSolvers()`, `solve(problem, opts?)`, `checkSize(d, problem)`, `acceptsShape(d, problem)`.
77
+ La fonction interne de tri n'est PAS exportée.
78
+ - Un dialecte tiers sans `shape` est réputé accepter toute sa famille ; sans `maxSize`, il est traité
79
+ « à établir ». Aucun refus à l'enregistrement.
23
80
 
24
- ## IMPLÉMENTÉ (réel, à jour) — architecture « un dialecte par algorithme » (façon ORM)
25
- Le module n'expose PAS un builder fluide mais un REGISTRE de dialectes, sélectionnés
26
- par nom ou auto par `kind` (comme `DB_DIALECT`). C'est l'architecture retenue (cf. IDEE).
27
- - Contrat `SolverDialect<P,S> { name, kind, capabilities{exact,online,maxSize?,multiObjective?}, solve(problem,opts?) }`.
28
- - Registre : `registerSolver(d)`, `getSolver(name)`, `listSolvers(kind?)`, `pickBest(kind)`,
29
- `clearSolvers()`, et `solve(problem, opts?)` (nom explicite OU auto par `problem.kind`).
30
81
  - Dialecte `hungarian` (kind 'assignment') : `hungarian(cost: number[][]) → { assignment, total }`
31
82
  (Kuhn-Munkres O(n³), exact). Problème `AssignmentProblem { kind:'assignment', cost }`.
32
83
  - Dialecte `simplex` (kind 'lp') : `simplex(problem: LpProblem) → LpSolution`
@@ -39,6 +90,18 @@ par nom ou auto par `kind` (comme `DB_DIALECT`). C'est l'architecture retenue (c
39
90
  (séparation & évaluation ; relaxation LP = `simplex` ; branche x≤⌊v⌋ | x≥⌈v⌉ ; élague par borne ;
40
91
  bornable par `opts.maxNodes`). `MilpProblem` = LpProblem + `kind:'milp'` + `integers?:number[]`
41
92
  (indices entiers, défaut toutes). Capacités `online:false` (combinatoire).
93
+ DÉLAI (0.4.0) — mode « au fil de l'eau », activé par `opts.timeoutMs` (ms) ou `opts.anytime: true` :
94
+ arrêt entre deux nœuds au délai ou au budget `maxNodes`, la MEILLEURE solution trouvée est rendue.
95
+ `status` : 'optimal' (PROUVÉ, exploration complète) | 'feasible' (meilleure trouvée, NON prouvée) |
96
+ 'unknown' (limite atteinte sans solution entière, rien de prouvé) | 'infeasible' | 'unbounded' (prouvés).
97
+ + `search { complete, stoppedBy:'time'|'nodes'|null, nodes, elapsedMs, bound, gap }` :
98
+ `bound` = meilleure borne encore possible (≥ objectif en max, ≤ en min ; null si inconnue),
99
+ `gap` = |bound − objective| / |objective| (0 si prouvé, null sans solution). `opts.now` : horloge
100
+ injectable (ms, défaut Date.now) pour des essais déterministes.
101
+ SANS `timeoutMs` ni `anytime` : résultat 0.3.0 au champ près (pas de `search`) — y compris le défaut
102
+ historique : budget `maxNodes` atteint ⇒ 'optimal' (ou 'infeasible') SANS preuve.
103
+ Exemple : `solve(p, { dialect:'branch-and-bound', timeoutMs: 20000 })` → accepter 'optimal' OU
104
+ 'feasible' (lire `search.gap`), traiter 'unknown' comme « pas de réponse » (repli de l'appelant).
42
105
  - Dialecte `min-cost-flow` (kind 'flow') : `minCostFlow(problem: FlowProblem) → FlowSolution`
43
106
  (plus courts chemins successifs / Bellman-Ford-SPFA ; sans `value` → flot MAXIMAL au moindre
44
107
  coût ; généralise le hongrois). `FlowProblem { kind:'flow', arcs:{from,to,capacity,cost}[],
@@ -47,6 +110,9 @@ par nom ou auto par `kind` (comme `DB_DIALECT`). C'est l'architecture retenue (c
47
110
  occupation, attente Wq/Lq) ; `mmcSizing(lambda, mu, target) → QueueSolution` (plus petit c stable
48
111
  satisfaisant `{maxWait?, maxProbWait?}`). `QueueProblem { kind:'queue', lambda, mu, c?, target? }` :
49
112
  `c` → évaluation ; `target` (sans `c`) → dimensionnement. Usage : estimer l'attente / dimensionner des guichets.
113
+ 0.3.0 : λ = 0 → attente 0 (plus de NaN) ; `c` non entier → RangeError ; sans `c` ni `target`, c = 1
114
+ est évalué ET signalé dans `solvedBy.notes`. ATTENTION Erlang C n'est PAS encore confrontée à une
115
+ table publiée : seulement à la récurrence d'Erlang B et à la loi de Little (cohérence, pas conformité).
50
116
  - Dialecte `markov` (kind 'markov') : chaînes de Markov à temps discret. `markovStationary(P)` (π exact par
51
117
  système linéaire), `markovStep(P, initial, steps)` (π₀Pᵏ), `markovAbsorbing(P)` (matrice fondamentale
52
118
  N=(I−Q)⁻¹ : espérance du temps avant absorption + probas d'absorption). `MarkovProblem { kind:'markov',
@@ -149,70 +215,19 @@ par nom ou auto par `kind` (comme `DB_DIALECT`). C'est l'architecture retenue (c
149
215
  rendrait un chiffre d'apparence sérieuse pour une question non traitée.
150
216
  ⚠️ L'erreur (MAE/MAPE) est TOUJOURS rendue : une prévision sans son erreur laisse croire à une
151
217
  précision qu'elle n'a pas. Mesurée APRÈS la première saison (les premiers points initialisent).
152
- - `registerBuiltinSolvers()` enregistre les 23 dialectes (hungarian, simplex, branch-and-bound, min-cost-flow,
153
- mmc, markov, mdp, backtrack-csp, anneal, monte-carlo, lagrangian + stable-matching, critical-path,
154
- bin-packing, pareto, list-scheduling, shortest-path, max-flow, matching, knapsack, tabu, genetic, forecast).
155
- Les kinds 'scheduling' et 'multiobjective' étaient DÉCLARÉS et VIDES : les DEUX sont désormais servis
156
- ('scheduling' → critical-path, bin-packing, list-scheduling ; 'multiobjective' → pareto).
157
- - Preuve de test : `npm run report` → `test-report.html` via le flag `--report` de @mostajs/mjs-unit 0.3.0.
158
- - Diagnostic manuel : `npm run dbg` (test-scripts/dbg.mjs) — sondes à l'œil hors suite, dont la régression ≥.
159
-
160
- ## RÔLE
161
- Modéliser et résoudre des problèmes d'optimisation, de satisfaction de contraintes
162
- et de modélisation stochastique :
163
- - PL : optimisation linéaire sous contraintes (simplexe).
164
- - PLNE/MIP : variables entières/mixtes (branch & bound).
165
- - Dantzig-Wolfe : PL structurées à grande échelle (blocs + contraintes liantes,
166
- génération de colonnes).
167
- - CSP : variables à domaines finis, contraintes, propagation AC-3 + backtracking.
168
- - Chaînes de Markov : matrices de transition, distribution stationnaire, régime
169
- transitoire → théorie des files (M/M/c, Erlang) pour estimer attente / dimensionner.
170
- - Métaheuristiques : algorithme génétique, recuit simulé, tabou, PSO, ACO, NSGA-II
171
- (multi-objectif) → gros problèmes combinatoires non linéaires, solutions « assez bonnes ».
172
- - Apprentissage : réseaux de neurones (MLP), apprentissage par renforcement,
173
- optimisation bayésienne → prévision d'affluence, politiques d'affectation apprises.
174
- Usages : affectation (tickets↔guichets, agents↔tâches), ordonnancement/planning,
175
- allocation de ressources, prévision d'attente et dimensionnement de guichets.
176
-
177
- FAMILLES : (1) Exact PL/PLNE — simplexe, branch&bound/cut, Dantzig-Wolfe, Benders,
178
- relaxation lagrangienne ; (2) Exact combinatoire — CSP, prog. dynamique, flots de
179
- réseau (max-flow, min-cost flow), Hongrois (affectation), plus courts chemins ;
180
- (3) Métaheuristiques — génétique, recuit simulé, tabou, PSO, ACO, NSGA-II ;
181
- (4) Stochastique — Markov, MDP, M/M/c, simulation à événements discrets, Monte-Carlo ;
182
- (5) Apprentissage — réseaux de neurones, RL, optimisation bayésienne.
183
- NOTE : le ML (réseaux/RL) pourrait être extrait dans un module frère @mostajs/ml (à trancher avant 1.0).
184
-
185
- NE FAIT PAS : évaluer des gardes/conditions (→ @mostajs/rules, inférence Prolog),
186
- états/transitions applicatifs (→ @mostajs/statemachine), événements/actions (→ trigger).
187
- Distinction : rules « est-ce vrai ? » ; ro-pla « quelle solution optimise / quel état stationnaire ? ».
188
-
189
- ## EXPORTS — FEUILLE DE ROUTE (prévus ; hungarian + lp DÉJÀ livrés, voir IMPLÉMENTÉ)
190
- - lp() → LpBuilder { maximize(coeffs)/minimize(coeffs), subjectTo(constraints), solve() }
191
- - model() → Model (CSP) : intVar, boolVar, allDifferent, linear, table, constraint, solve, solveAll, optimize
192
- - markov(matrix) → Chain { stationary(), step(dist, n?), absorbingTimes() }
193
- - mmc({ lambda, mu, c }) → { rho, pWait, avgWait, avgQueue } (file M/M/c, ≥ 0.2)
194
- - genetic({ fitness, genome, popSize, generations, mutationRate }) → BestSolution (≥ 0.2)
195
- - anneal({ energy, neighbor, schedule }) → BestSolution (recuit simulé, ≥ 0.2)
196
- - neuralNet({ layers, activation }) → { predict(x), train(data, opts) } (MLP, ≥ 0.3)
197
- - hungarian(costMatrix) → assignment (affectation optimale, ≥ 0.3)
198
- - dantzigWolfe(blocks, linking) → Solution (≥ 0.4)
199
-
200
- ## API — SIGNATURES (prévues, à figer)
201
- - lp().maximize(coeffs: Record<string,number>).subjectTo(rows).solve(): { vars, objective } | null
202
- - model().intVar(name, domain:number[]): Var ; allDifferent(vars): void ; solve(opts?): Solution|null
203
- - markov(P: number[][]).stationary(): number[] // vecteur π tel que πP = π
204
- - Bornage obligatoire (timeoutMs/maxNodes) comme @mostajs/rules.
205
218
 
206
- ## TYPES CLÉS (prévus)
207
- - LpBuilder, LpSolution, Model, Var, Constraint, Solution, Chain, MMCResult, SolveOptions
219
+ - Preuve de test : `npm run report` → `test-report.html`.
208
220
 
209
- ## PIÈGES (anticipés)
210
- - Explosion combinatoire (CSP/MIP) → timeouts/maxNodes obligatoires.
211
- - Simplexe : dégénérescence/cyclage → règle de Bland ; précision flottante.
212
- - Markov : vérifier irréductibilité/apériodicité avant distribution stationnaire.
213
- - Zéro-dépendance visé (solveurs maison) ; sinon backend (javascript-lp-solver) en peer optionnelle.
221
+ ## NE FAIT PAS
222
+ Évaluer des gardes/conditions (→ @mostajs/rules), états/transitions applicatifs
223
+ (→ @mostajs/statemachine), événements/actions. Distinction : rules « est-ce vrai ? » ;
224
+ ro-pla « quelle solution optimise / quel état stationnaire ? ».
214
225
 
215
- ## À PRODUIRE (DEVRULES §4/§14)
216
- État de l'art (simplex.js, javascript-lp-solver, MiniZinc, OR-Tools, Choco ; files/Erlang),
217
- audit (vs rules/statemachine/workflow), plan dev/test, CHANGELOG, doc technique, slides,
218
- chapitre de livre. Pas de publication avant les 14 livrables + tests verts.
226
+ ## PIÈGES
227
+ - Explosion combinatoire (CSP, MILP) : borner par `opts.maxNodes` ; MILP : `opts.timeoutMs` (0.4.0).
228
+ - MILP sous délai : exiger `status === 'optimal'` refuse une bonne solution `feasible` ; et sans
229
+ `timeoutMs`/`anytime`, un 'optimal' au budget `maxNodes` atteint n'est PAS prouvé (passer `anytime: true`).
230
+ - MILP sous délai : le temps est contrôlé ENTRE deux nœuds ; dépassement ≤ une relaxation (simplexe).
231
+ - Simplexe : règle de Bland contre le cyclage ; précision flottante.
232
+ - Markov : vérifier irréductibilité et apériodicité avant la distribution stationnaire.
233
+ - Métaheuristiques : déterministes à graine égale (`seed`) ; `exact: false`.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mostajs/ro-pla",
3
- "version": "0.2.2",
4
- "description": "Programmation linéaire & recherche opérationnelle pour l'écosystème @mostajs/* : programmation linéaire (simplexe), variables entières/mixtes (branch & bound), contraintes (CSP : alldifferent, linéaires, table), optimisation min/max. Affectation, ordonnancement, planning, allocation de ressources. STADE PROPOSITION (0.0.1).",
3
+ "version": "0.4.0",
4
+ "description": "Recherche opérationnelle pour l'écosystème @mostajs/* : 23 dialectes (simplexe, branch & bound, flots, affectation, CSP, Markov, MDP, files M/M/c, ordonnancement, Pareto, métaheuristiques, prévision) sous un registre qui choisit par famille et forme du problème et dit qui a répondu (solvedBy) ; branch & bound à délai de calcul (meilleure solution, statut prouvé ou non, écart à la borne). Zéro dépendance.",
5
5
  "author": "Dr Hamid MADANI <drmdh@msn.com>",
6
6
  "license": "AGPL-3.0-or-later",
7
7
  "type": "module",