epidsl 0.1.0__tar.gz

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.
epidsl-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 A. Yvan Guifo Fodjo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
epidsl-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,665 @@
1
+ Metadata-Version: 2.4
2
+ Name: epidsl
3
+ Version: 0.1.0
4
+ Summary: A domain-specific language for compositional epidemiological modelling
5
+ Keywords: epidemiology,modelling,dsl,compartmental models,simulation,calibration
6
+ Author: Yvan Guifo
7
+ Author-email: Yvan Guifo <yvanguifo@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Topic :: Scientific/Engineering
18
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
19
+ Classifier: Typing :: Typed
20
+ Requires-Dist: lark>=1.3.1
21
+ Requires-Dist: numpy>=2.0
22
+ Requires-Dist: pygls>=2.1.1
23
+ Requires-Dist: scipy>=1.13
24
+ Requires-Python: >=3.11
25
+ Project-URL: Homepage, https://github.com/YvanGuifo/epidsl
26
+ Project-URL: Repository, https://github.com/YvanGuifo/epidsl
27
+ Project-URL: Issues, https://github.com/YvanGuifo/epidsl/issues
28
+ Description-Content-Type: text/markdown
29
+
30
+ # EpiDSL
31
+
32
+ A domain-specific language for epidemiological modelling. A model is written once as
33
+ compartments and flows, checked statically, and compiled to a typed intermediate
34
+ representation that simulation backends consume.
35
+
36
+ **Status:** early development. Deterministic (ODE) and stochastic (Gillespie,
37
+ tau-leap) simulation, model composition, calibration and a visual workbench work
38
+ end to end (see [Roadmap](#roadmap)).
39
+
40
+ ## Install
41
+
42
+ EpiDSL is not published on PyPI yet. Work from a checkout: it requires Python 3.11
43
+ or later and [uv](https://docs.astral.sh/uv/).
44
+
45
+ ```bash
46
+ uv sync
47
+ ```
48
+
49
+ Supported and tested: Python 3.11 to 3.14, NumPy 2.0 or later, SciPy 1.13 or later.
50
+
51
+ ## Write a model
52
+
53
+ ```
54
+ model SIR {
55
+ semantics: [ODE]
56
+
57
+ compartment S = 990, I = 10, R = 0
58
+
59
+ parameter beta = 0.3 [1/day] -- transmission rate
60
+ rate gamma = 0.1 [1/day] -- recovery rate
61
+
62
+ flow S -> I : beta * S * I / N
63
+ flow I -> R : gamma * I
64
+ }
65
+ ```
66
+
67
+ ## Check and run it
68
+
69
+ ```bash
70
+ uv run epidsl check examples/sir.epidsl
71
+ ```
72
+
73
+ ```bash
74
+ uv run epidsl run examples/sir.epidsl --t-end 160 --out sir.csv
75
+ ```
76
+
77
+ `run` writes one CSV row per output time, with a column `t` and one column per
78
+ compartment. Without `--out` the CSV goes to standard output.
79
+
80
+ ## Open the studio
81
+
82
+ The studio shows a model, its simulations and its calibration in the browser. The
83
+ text file stays the model: the studio reads it, checks it as you type, and saves it
84
+ back.
85
+
86
+ ```bash
87
+ uv run epidsl studio examples/sir_age_structured.epidsl
88
+ ```
89
+
90
+ It prints a local address and opens it. Stop it with Ctrl+C. Started without a
91
+ file, it opens a small template that cannot be saved.
92
+
93
+ - **Source.** Edit the model on the left. Lines with a problem are marked, and the
94
+ list below explains each one; click an entry to jump to its line.
95
+ - **Model.** Compartments are laid out as a grid. For a composed model the first
96
+ model gives the columns and the others the rows, so each cell is one combination
97
+ of states. Arrows are the flows, coloured by the model they come from; a dashed
98
+ arrow is a synchronised transition. Select an arrow to read its rate and to
99
+ highlight the line of source that produced it. One line can produce several
100
+ arrows: that is composition made visible.
101
+ - **Simulation.** Choose a method the model declares, then **Run** (Ctrl+Enter).
102
+ ODE runs again by itself as you edit. With a stochastic method and several runs,
103
+ the chart shows the mean and a 95% band. Click a name under the chart to show or
104
+ hide it; observables are dashed and hidden at first.
105
+ - **Calibration.** Paste or load the observations, then **Calibrate**. Each
106
+ parameter is shown on a track that spans its prior, with its 95% interval and
107
+ median, and the chart shows the model at the estimated values with the data.
108
+
109
+ The studio listens on this computer only, loads nothing from the internet, and
110
+ answers only its own page. It uses port 8642, or a free one if that is taken;
111
+ `--port` chooses one and `--no-browser` does not open the browser.
112
+
113
+ ## Use your editor with the language server
114
+
115
+ `epidsl server` starts a Language Server Protocol server over stdio. Any
116
+ editor with LSP support (VS Code, Neovim, Emacs, Helix, …) can use it to get:
117
+
118
+ - **Diagnostics in real time** — all static checks (C1–C13) run on every save and
119
+ the results appear as squiggles or a problem list.
120
+ - **Completion** — keywords, math functions, and every compartment and constant
121
+ declared in the file.
122
+ - **Goto definition** — jump to where a compartment, rate, parameter or observable
123
+ is declared.
124
+
125
+ Configure your editor to run `epidsl server` as a language server for files
126
+ with extension `.epidsl`. For VS Code, add a launch entry like this in
127
+ `.vscode/settings.json`:
128
+
129
+ ```json
130
+ {
131
+ "languageServerExample.trace.server": "verbose",
132
+ "[epidsl]": {
133
+ "editor.defaultFormatter": null
134
+ }
135
+ }
136
+ ```
137
+
138
+ For Neovim with `nvim-lspconfig`, register it as a custom server:
139
+
140
+ ```lua
141
+ vim.api.nvim_create_autocmd("FileType", {
142
+ pattern = "epidsl",
143
+ callback = function()
144
+ vim.lsp.start({
145
+ name = "epidsl",
146
+ cmd = { "epidsl", "server" },
147
+ root_dir = vim.fn.getcwd(),
148
+ })
149
+ end,
150
+ })
151
+ ```
152
+
153
+ ## Run a stochastic simulation
154
+
155
+ Two methods simulate one random trajectory of whole individuals. The model must
156
+ list the method in its `semantics` (`Gillespie` or `TauLeap`).
157
+
158
+ | Method | What it does | Use it when |
159
+ |--------|--------------|-------------|
160
+ | `--method gillespie` | Exact: fires one individual event at a time. | The population is small, or you need the exact law. |
161
+ | `--method tau-leap` | Approximate: fires many events per time step. | The population is large and exact simulation is too slow. |
162
+
163
+ ```bash
164
+ uv run epidsl run examples/sir.epidsl --t-end 160 --method gillespie --seed 1
165
+ ```
166
+
167
+ `--seed` makes the run reproducible; without it each run differs.
168
+
169
+ To summarise many runs, add `--runs`. The CSV then holds, for each compartment, the
170
+ mean over the runs and the quantiles given by `--quantiles` (by default 0.025 and
171
+ 0.975, a 95% band), in columns such as `I_mean`, `I_q0.025` and `I_q0.975`:
172
+
173
+ ```bash
174
+ uv run epidsl run examples/sir.epidsl --t-end 160 --method gillespie --runs 200 --seed 1
175
+ ```
176
+
177
+ With `--runs`, `--seed` fixes the whole set of runs. `--runs` is refused with the
178
+ ODE method, which always gives the same trajectory.
179
+
180
+ Both methods require whole-number initial values. A flow never fires from an empty
181
+ compartment, and a rate that evaluates to a negative number stops the run with an
182
+ error.
183
+
184
+ A rate may use `t`, for a season or a dated change:
185
+
186
+ ```
187
+ flow S -> I : beta * (1 + swing * cos(6.283185307 * t / year)) * S * I / N
188
+ ```
189
+
190
+ ```bash
191
+ uv run epidsl run examples/sir_seasonal.epidsl --t-end 730 --method tau-leap --seed 1
192
+ ```
193
+
194
+ Gillespie stays exact with such a rate, by integrating it to find each waiting time,
195
+ but that costs far more per event: on the example above, 11 seconds for 30 000
196
+ events against 0.15 seconds for the same model without a season. Tau-leap handles it
197
+ at its usual speed (0.15 seconds here) and is the practical choice beyond a few
198
+ thousand individuals.
199
+
200
+ Tau-leap chooses its own step sizes, following Cao, Gillespie and Petzold (2006),
201
+ and switches to exact steps while few individuals are involved. Its error shrinks with its accuracy parameter `epsilon`
202
+ (default 0.03, set with `--epsilon`): on a 100 000
203
+ person SIR epidemic the mean trajectory is within about 0.6% of the population
204
+ of the ODE solution at 0.03, and 0.2% at 0.01.
205
+
206
+ ## Describe what is observed
207
+
208
+ Surveillance rarely sees compartments directly. It sees new cases per reporting
209
+ period, and only some of them. An `observe` statement defines such a quantity:
210
+
211
+ ```
212
+ parameter rho = 0.5 prior uniform(0.05, 1) [1] -- fraction of infections reported
213
+
214
+ observe cases = rho * incidence(S -> I)
215
+ observe prevalence = I / N
216
+ ```
217
+
218
+ `incidence(S -> I)` is the number of people who moved from `S` to `I` since the
219
+ previous output time, so with `--points` set for weekly output it is a weekly
220
+ count. It is zero at the first output time. `incidence(-> S)` counts arrivals and
221
+ `incidence(I ->)` departures. When several flows share the same endpoints, they
222
+ are counted together.
223
+
224
+ Observables are written after the compartments in the output of `epidsl run`,
225
+ are summarised by `--runs`, and can be used as columns of the data given to
226
+ `epidsl calibrate`. In a composed model, each model's observables are kept: a
227
+ compartment name stands for its total over the other models, and an incidence
228
+ counts every transition in which that model makes the move.
229
+
230
+ ```bash
231
+ uv run epidsl calibrate examples/sir_reporting.epidsl --data examples/sir_weekly_cases.csv --seed 1
232
+ ```
233
+
234
+ ```
235
+ parameter,mean,q0.025,q0.5,q0.975
236
+ beta,0.3038061462673391,0.252614404758703,0.3029811560539657,0.3620092080755828
237
+ rho,0.37209780074709964,0.16092360120134233,0.35308363011578686,0.6462532658218411
238
+ ```
239
+
240
+ The data are synthetic weekly counts produced with `beta = 0.3` and `rho = 0.4`.
241
+ The reporting fraction is less sharply determined than the transmission rate;
242
+ more `--populations` narrow both intervals.
243
+
244
+ An observable may declare a **noise distribution** with a tilde:
245
+
246
+ ```
247
+ observe cases = incidence(S -> I) ~ poisson()
248
+ observe prevalence = I ~ negbinomial(5.0)
249
+ observe signal = rho * I ~ normal(10.0)
250
+ ```
251
+
252
+ `poisson()` suits integer case counts; `negbinomial(phi)` suits overdispersed
253
+ counts (larger phi → less overdispersion); `normal(sd)` suits continuous
254
+ measurements. When calibrating, EpiDSL replaces the RMSE by the negative
255
+ log-likelihood of the declared distribution, which gives sharper posteriors for
256
+ count data. The stochastic backends (Gillespie, tau-leap) draw from the noise
257
+ distribution at each output time; the ODE backend always returns the
258
+ deterministic mean. See `examples/sir_noise.epidsl`.
259
+
260
+ ## Calibrate parameters from data
261
+
262
+ Calibration estimates the parameters you are unsure of from observed counts. Give
263
+ each such parameter a prior, the range of values you consider plausible:
264
+
265
+ ```
266
+ parameter beta = 0.3 prior uniform(0.05, 1) [1/day]
267
+ ```
268
+
269
+ Put the observations in a CSV file whose first column is `t` and whose other
270
+ columns are named after compartments or observables. Any subset will do:
271
+
272
+ ```
273
+ t,I
274
+ 0,10
275
+ 10,69
276
+ 20,200
277
+ ```
278
+
279
+ Then run:
280
+
281
+ ```bash
282
+ uv run epidsl calibrate examples/sir.epidsl --data examples/sir_observed.csv --seed 1
283
+ ```
284
+
285
+ The output has one row per parameter, with its estimated mean and the 2.5%, 50%
286
+ and 97.5% quantiles of its plausible values given the data:
287
+
288
+ ```
289
+ parameter,mean,q0.025,q0.5,q0.975
290
+ beta,0.2866752974896084,0.264269375017657,0.28701743058810203,0.31155539756701467
291
+ ```
292
+
293
+ The example data are synthetic: the model was run with `beta = 0.3` and noise was
294
+ added, so the estimate can be compared with the value that produced them.
295
+
296
+ A summary line on standard error reports the number of simulations, the final
297
+ tolerance and the effective sample size. `--out` writes the full weighted sample.
298
+
299
+ | Prior | Meaning |
300
+ |-------|---------|
301
+ | `uniform(a, b)` | Any value between `a` and `b`, equally likely. |
302
+ | `loguniform(a, b)` | Between `a` and `b`, with each order of magnitude equally likely. Both must be positive. |
303
+ | `normal(m, s)` | Centred on `m` with standard deviation `s`. |
304
+
305
+ The method is ABC-SMC (approximate Bayesian computation, sequential Monte Carlo;
306
+ Toni et al. 2009, with the adaptive kernel of Beaumont et al. 2009):
307
+ it repeatedly simulates the model with candidate values and keeps those whose
308
+ simulation is closest to the data, tightening the tolerance at each of
309
+ `--populations` rounds. It works with any `--method`. Each simulation starts at
310
+ time zero and reports exactly at the times in the data. The distance is the root
311
+ mean squared error, each series being divided by its largest observed value.
312
+
313
+ More populations or particles give a sharper estimate and take longer. A low
314
+ effective sample size relative to `--particles` means the estimate rests on few
315
+ particles: increase `--particles`.
316
+
317
+ ### Use several processors
318
+
319
+ A calibration runs thousands of independent simulations, and an ensemble runs many.
320
+ `--workers` spreads them over that many processes, and `--workers 0` uses one per
321
+ processor:
322
+
323
+ ```bash
324
+ uv run epidsl calibrate examples/sir_contact_matrix.epidsl --model ContactMatrix --data examples/contact_weekly_cases.csv --particles 300 --populations 12 --seed 1 --workers 0
325
+ ```
326
+
327
+ That calibration takes 406 seconds on one processor and 81 seconds on eight — five
328
+ times faster, for the same answer. The number of workers changes how long a run
329
+ takes and nothing else: the seeds and the order of the work are fixed before any of
330
+ it is handed out, so a seeded run gives the same particles, the same tolerances and
331
+ the same count of simulations whatever `--workers` is set to.
332
+
333
+ Workers only pay off when there is enough work for them: starting them costs about
334
+ a second, since each loads NumPy and SciPy afresh.
335
+
336
+ ## Compose models
337
+
338
+ A `compose` block builds the product of several models. Each model is read as an
339
+ automaton whose states are its compartments, in the manner of a stochastic automata
340
+ network; the result has one compartment per combination of states.
341
+
342
+ ```
343
+ model Age {
344
+ compartment young = 300, old = 700
345
+ rate aging = 0.002 [1/day]
346
+ flow young -> old : aging * young
347
+ }
348
+
349
+ compose AgeSIR {
350
+ models: [SIR, Age]
351
+ }
352
+ ```
353
+
354
+ `AgeSIR` has the compartments `S_young`, `S_old`, `I_young`, `I_old`, `R_young`
355
+ and `R_old`. Run it by name:
356
+
357
+ ```bash
358
+ uv run epidsl run examples/sir_age.epidsl --model AgeSIR --t-end 160
359
+ ```
360
+
361
+ The rules of composition:
362
+
363
+ - **Compartments** are named by joining the local names with `_`, in the order of
364
+ the `models` list. Initial values are the independent joint distribution: the
365
+ product of each model's initial values, divided by `N` for each extra model.
366
+ - **Flows** of each model are copied into every combination of the other models'
367
+ states.
368
+ - **Rates** keep their meaning. The name of a flow's source denotes the specific
369
+ source compartment (`S` becomes `S_young`); every other compartment name denotes
370
+ the total over the other models (`I` becomes `I_young + I_old`). Infection in
371
+ `AgeSIR` therefore mixes homogeneously across age groups.
372
+ - **Constants** of all models are merged. **Semantics** is the intersection.
373
+
374
+ A `sync` rule adds a transition that moves several models at once. Here a severe
375
+ infection changes a person's status and location in the same instant:
376
+
377
+ ```
378
+ compose Hospital {
379
+ models: [Disease, Place]
380
+ sync S -> I, home -> hospital : severe * beta * S_home * I / N
381
+ }
382
+ ```
383
+
384
+ In a `sync` rate, the source is named by joining the moves' sources (`S_home`).
385
+ With more than two models, a joined name that leaves some models out is a total
386
+ over them, and the rule is copied into each of their states.
387
+
388
+ ### Make a rate depend on another model
389
+
390
+ Inside `compose`, `by` gives a constant of one model a value for each state of
391
+ another:
392
+
393
+ ```
394
+ compose AgeStructured {
395
+ models: [Epidemic, Age]
396
+ parameter beta by Age = { young: 0.6, old: 0.3 }
397
+ }
398
+ ```
399
+
400
+ `beta` is replaced by the constants `beta_young` and `beta_old`, and each
401
+ transition uses the one of the compartment it leaves: infection of `S_young` runs
402
+ at `beta_young * S_young * I / N`. Every state of the `by` model needs a value. The
403
+ unit is kept from the original constant unless a new one is given.
404
+
405
+ This expresses a rate that depends on the state of the individual who moves, such
406
+ as susceptibility by age.
407
+
408
+ ### Say who meets whom
409
+
410
+ Naming the model twice gives one value per ordered pair of states — a contact
411
+ matrix. The row is the group being infected, the column the group it meets:
412
+
413
+ ```
414
+ compose ContactMatrix {
415
+ models: [Epidemic, Age]
416
+
417
+ parameter beta by Age, Age = {
418
+ young, young: 0.9,
419
+ young, old: 0.15,
420
+ old, young: 0.15,
421
+ old, old: 0.35
422
+ }
423
+ }
424
+ ```
425
+
426
+ The flow is still written once, in the component model, and is still
427
+ `flow S -> I : beta * S * I / N`. A rate that uses a matrix becomes the sum over the
428
+ states of `Age` of that rate, with the matrix on the pair (the state the flow
429
+ leaves, the state it meets) and each group of compartments restricted to that
430
+ state. The infection of the young is therefore generated as:
431
+
432
+ ```
433
+ beta_young_young * S_young * I_young / N + beta_young_old * S_young * I_old / N
434
+ ```
435
+
436
+ `N`, time and ordinary constants are untouched. A rate that uses a matrix must name
437
+ a group of compartments for the sum to range over, and one rate may use matrices of
438
+ one model only. A matrix is indexed by one model twice (`by Age, Age`); two
439
+ different models are not supported.
440
+
441
+ ```bash
442
+ uv run epidsl run examples/sir_contact_matrix.epidsl --model ContactMatrix --t-end 120
443
+ ```
444
+
445
+ Estimating the entries of a matrix from case data is possible but often weakly
446
+ determined: on the example above, four entries estimated from two weekly case
447
+ series give wide intervals, because very different matrices fit the data almost
448
+ equally well. Contact matrices are usually measured, not inferred.
449
+
450
+ ### Say where newcomers enter
451
+
452
+ A model with an inflow, such as births, can be composed once every other model
453
+ states which of its compartments newcomers enter:
454
+
455
+ ```
456
+ compose AgeStructured {
457
+ models: [Epidemic, Age]
458
+ enter Age at young
459
+ }
460
+ ```
461
+
462
+ The inflow `flow -> S : mu * N` of `Epidemic` becomes `flow -> S_young : mu * N`.
463
+
464
+ ### Model migration between patches
465
+
466
+ A metapopulation model couples a disease model with a "patch" model whose
467
+ compartments name the locations (cities, regions, age groups…). Migration between
468
+ patches is declared with a `migrate` statement and a matrix constant:
469
+
470
+ ```
471
+ model City { compartment Paris = 5000, Lyon = 3000, Marseille = 2000 }
472
+
473
+ compose MetaSIR {
474
+ models: [SIR, City]
475
+
476
+ rate travel by City, City = {
477
+ Paris, Paris: 0,
478
+ Paris, Lyon: 0.005,
479
+ Paris, Marseille: 0.002,
480
+ Lyon, Paris: 0.005,
481
+ Lyon, Lyon: 0,
482
+ Lyon, Marseille: 0.003,
483
+ Marseille, Paris: 0.002,
484
+ Marseille, Lyon: 0.003,
485
+ Marseille, Marseille: 0
486
+ } [1/day]
487
+
488
+ migrate S, I, R : travel
489
+ }
490
+ ```
491
+
492
+ `migrate S, I, R : travel` generates a cross-patch flow for every listed
493
+ compartment and every ordered pair of distinct patches. The entry `Paris, Lyon:
494
+ 0.005` creates the flow `S_Paris -> S_Lyon : travel_Paris_Lyon * S_Paris`
495
+ (and likewise for `I` and `R`). Migration conserves population.
496
+
497
+ The rate matrix is declared inline in the `compose` block; it does not need a
498
+ prior declaration in `SIR` or `City`. Initial populations must be equal across
499
+ all composed models. The full example is in
500
+ [examples/metapop_sir.epidsl](examples/metapop_sir.epidsl).
501
+
502
+ ### Observe and calibrate by stratum
503
+
504
+ A `compose` block can declare its own constants and observables. They are written
505
+ with the names of the composed model: a compartment such as `S_young`, a generated
506
+ constant such as `beta_young`, or a group name such as `I` or `young`, which stands
507
+ for a total.
508
+
509
+ ```
510
+ compose AgeStructured {
511
+ models: [Epidemic, Age]
512
+
513
+ parameter beta by Age = { young: 0.6, old: 0.3 }
514
+ rate rho_young = 0.8 [1]
515
+ rate rho_old = 0.4 [1]
516
+
517
+ observe cases_young = rho_young * incidence(S_young -> I_young)
518
+ observe cases_old = rho_old * incidence(S_old -> I_old)
519
+ }
520
+ ```
521
+
522
+ In `incidence`, a group name counts every transition between the two groups:
523
+ `incidence(S -> I)` is all new infections and `incidence(young -> old)` all ageing.
524
+
525
+ A parameter stratified with `by` keeps the prior of the original, or takes the one
526
+ written after its values (`... } prior uniform(0.1, 1)`). Each generated parameter
527
+ is then estimated separately:
528
+
529
+ ```bash
530
+ uv run epidsl calibrate examples/sir_age_structured.epidsl --model AgeStructured --data examples/age_weekly_cases.csv --seed 1
531
+ ```
532
+
533
+ ```
534
+ parameter,mean,q0.025,q0.5,q0.975
535
+ beta_young,0.5977532401017741,0.32833100358229744,0.6015675486652726,0.8736703893495928
536
+ beta_old,0.3064468147009518,0.19243156341367465,0.2976122185897274,0.43279312186920177
537
+ ```
538
+
539
+ The data are synthetic weekly cases by age group, produced with `beta_young = 0.6`
540
+ and `beta_old = 0.3`. With the default five populations the intervals are wide.
541
+
542
+ The full model is in
543
+ [examples/sir_age_structured.epidsl](examples/sir_age_structured.epidsl).
544
+
545
+ A composition is rejected when: a model is unknown or has errors; two models share
546
+ a compartment or constant name; the models' total populations differ or are zero;
547
+ they have no semantics in common; a joined or generated name is ambiguous or
548
+ already used; or a
549
+ model has an inflow (`flow -> A`) and another model has no `enter` statement.
550
+ Fewer than two models, and a malformed `sync`, `by` or `enter` statement, are
551
+ rejected too.
552
+
553
+ A composed model is an ordinary model: it can be listed in another `compose`
554
+ block, and `models: [A, B, C]` gives the same model as composing `A` and `B`
555
+ first.
556
+
557
+ ## Language reference
558
+
559
+ | Statement | Meaning |
560
+ |-----------|---------|
561
+ | `model Name { ... }` | Declares a model. A file may hold several. |
562
+ | `compartment A = 10, B` | Declares compartments with initial values (default 0). |
563
+ | `parameter p = 0.3 [1/day]` | A named constant intended for calibration. The unit is optional. |
564
+ | `parameter p = 0.3 prior uniform(0.1, 1) [1/day]` | The same, with the prior that `epidsl calibrate` uses. |
565
+ | `rate g = 0.1 [1/day]` | A fixed named constant. The unit is optional. |
566
+ | `flow A -> B : expr` | Moves population from `A` to `B` at rate `expr`. |
567
+ | `flow -> A : expr` | Inflow (for example births). |
568
+ | `flow A -> : expr` | Outflow (for example deaths). |
569
+ | `observe x = expr` | A quantity derived from the state, written with the output. May use `incidence(A -> B)`. |
570
+ | `compose Name { ... }` | Declares the product of several models. |
571
+ | `models: [A, B]` | Inside `compose`: the models to compose, two or more. |
572
+ | `sync a -> b, c -> d : expr` | Inside `compose`: a transition that moves two or more models at once, one move per model. |
573
+ | `rate c by B = { x: 1, y: 2 }` | Inside `compose`: gives constant `c` one value per compartment of model `B`. Also with `parameter`. |
574
+ | `rate c by B, B = { x, x: 1, x, y: 2, ... }` | The same with one value per ordered pair: a contact matrix. |
575
+ | `enter B at x` | Inside `compose`: newcomers from another model's inflow enter `B` in compartment `x`. |
576
+ | `rate`, `parameter`, `observe` | Inside `compose`: extra constants and observables of the composed model. |
577
+ | `semantics: [ODE]` | Backends the model is valid for: `ODE`, `Gillespie`, `TauLeap`, `ABM`. Default `[ODE]`. |
578
+
579
+ Expressions support `+ - * / ^`, parentheses, the built-in symbols `N` (total
580
+ population) and `t` (time), and the functions `exp`, `log`, `sqrt`, `sin`, `cos`,
581
+ `abs`, `min`, `max`. Comments are `-- to end of line` and `/* block */`. A
582
+ trailing `;` after a statement is optional. The keywords (`model`, `compose`,
583
+ `compartment`, `parameter`, `rate`, `flow`, `semantics`, `models`, `sync`, `enter`,
584
+ `by`, `at`, `prior`, `observe`, `incidence`) cannot be used as names.
585
+
586
+ ### Static checks
587
+
588
+ | Code | Severity | Condition |
589
+ |------|----------|-----------|
590
+ | C1 | error | A name is declared more than once. |
591
+ | C2 | error | A flow endpoint is not a compartment. |
592
+ | C3 | error | An expression uses an undefined symbol, an unknown function, or the wrong number of arguments. |
593
+ | C4 | error | A flow has the same compartment at both ends, or no endpoint at all. |
594
+ | C5 | warning | A `rate` or `parameter` has no unit. |
595
+ | C6 | error | An initial value is negative, or a declared value is not finite. |
596
+ | C7 | warning | A compartment, rate or parameter is never used. |
597
+ | C8 | error | A declaration reuses a reserved name (`N`, `t`, or a function name). |
598
+ | C9 | warning | A model has inflows but no outflows, or outflows but no inflows (unbounded population growth or decay). Demographic models with both are not warned. |
599
+ | C10 | error | The backend requested on the CLI (`--method`) is not listed in the model's `semantics`. |
600
+ | C11 | error | A prior is ill-defined (bounds in the wrong order, non-positive `loguniform` bound or standard deviation), or the parameter's value lies outside it. |
601
+ | C12 | error | `incidence` is used in a flow rate, or no flow has the endpoints it names. |
602
+
603
+ `--strict` turns warnings into errors.
604
+
605
+ ### Command reference
606
+
607
+ | Command | Options |
608
+ |---------|---------|
609
+ | `epidsl check FILE` | `--strict` |
610
+ | `epidsl studio [FILE]` | `--port N` (default 8642, or a free port), `--no-browser` |
611
+ | `epidsl calibrate FILE` | `--data CSV` (required), `--method ode\|gillespie\|tau-leap` (default `ode`), `--particles N` (default 200), `--populations N` (default 5), `--seed N`, `--workers N`, `--model NAME`, `--out PATH`, `--strict` |
612
+ | `epidsl server` | (none) — start the LSP language server over stdio |
613
+ | `epidsl run FILE` | `--t-end T` (required), `--points N` (default 201), `--method ode\|gillespie\|tau-leap` (default `ode`), `--seed N`, `--runs K`, `--workers N`, `--quantiles Q1,Q2,...` (default `0.025,0.975`), `--epsilon E` (tau-leap only, default 0.03), `--model NAME`, `--out PATH`, `--strict` |
614
+
615
+ All commands exit with status 0 on success and 1 on any error.
616
+
617
+ ## Develop
618
+
619
+ ```bash
620
+ uv run pytest
621
+ ```
622
+
623
+ ```bash
624
+ uv run ruff check . && uv run ruff format --check . && uv run mypy
625
+ ```
626
+
627
+ To run the tests against the oldest dependencies that `pyproject.toml` allows:
628
+
629
+ ```bash
630
+ uv run --isolated --resolution lowest-direct pytest
631
+ ```
632
+
633
+ To build the package and try it in a clean environment:
634
+
635
+ ```bash
636
+ uv build
637
+ ```
638
+
639
+ ```bash
640
+ uv run --isolated --no-project --with dist/*.whl epidsl check examples/sir.epidsl
641
+ ```
642
+
643
+ Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
644
+
645
+ ## Roadmap
646
+
647
+ 1. **Done:** grammar, typed IR, checks C1–C8, ODE backend, CLI.
648
+ 2. **Done:** `compose` blocks with `sync` rules, rates that depend on another model
649
+ (`by`) and entry states for inflows (`enter`).
650
+ 3. **Done:** Gillespie and tau-leap stochastic backends, ensembles of runs.
651
+ 4. **Done:** calibration by ABC-SMC, observables and incidence.
652
+ 5. **Done:** release preparation (package builds and installs cleanly; not published).
653
+ 6. **Done:** the studio, a visual workbench in the browser.
654
+ 7. **Done:** contact matrices.
655
+ 8. **Done:** running simulations over several processors; rates that depend on time
656
+ in the stochastic methods.
657
+ 9. Network-based agent backend, language server, first PyPI release.
658
+
659
+ Design rationale, and how each method differs from the paper it follows, are
660
+ recorded in [docs/DESIGN_DECISIONS.md](docs/DESIGN_DECISIONS.md). References are in
661
+ [docs/references.bib](docs/references.bib).
662
+
663
+ ## License
664
+
665
+ MIT