Narrative models
Pages that define a model in their own prose, then validate, test and plot it as they are built.
A narrative page is an .esm document written in the ESM Markdown format:
ordinary Markdown in which the model’s declarations and equations are written
where the prose introduces them. The EarthSciAST core reads the page (prose is
skipped), esm-narrative adds the tests and figures written with its own
esm- directives, validates the document, runs its inline tests, runs its
analyses and draws its figures — then writes the page you are reading, with the
mathematics, results and figures filled in. A model that does not validate, or
a test that fails, stops the build.
Source pages live in docs/narrative/; the built pages land in
docs/content/generated/narrative/ and are not checked in.
The model
The model is written in the ESM Markdown format, which the core reads:
| Written | Means |
|---|---|
front matter with esm: "2.2.0" and name: "decay" | the document; its other keys (title, weight, …) are the site’s |
::model[Decay] | starts a model; what follows belongs to it |
:var[$N$]{default=100 units="mol"} | a variable, shown as \(N\) |
:param[$\lambda$]{default=0.1 units="1/s"} | a parameter, shown as \(\lambda\) |
$$, \frac{\mathrm{d} N}{\mathrm{d} t} = -\lambda N, $$ {#eq-decay} on three lines | a display equation, with an anchor |
A declaration names its quantity in LaTeX math ($\lambda$ for lambda,
$k_{\mathrm{ab}}$ for k_ab) and may sit anywhere in a sentence. An equation
is a display: a line $$, the equation in LaTeX on the next line, and a line
$$, optionally followed by a label such as {#eq-decay}, which gives the
equation an anchor for links and changes nothing in the model. Everything else
— headings, paragraphs, inline math such as \(N_0\) — is prose, which the core
skips. A line may not start with $$ except to open a model equation, so
illustrative mathematics uses \(…\) or \[…\] instead. Front matter values
are written as the format’s YAML: every string double-quoted.
The format has more constructs (reactions, initialization equations,
expression templates, fenced esm:<field> blocks for any other field); a page
may use any of them.
The directives
Tests, figures and tables are narrative’s own directives:
| Written | Means |
|---|---|
:::esm-test{#id span="0..10"} … ::: | an esm-spec §6.6 inline test of the current model |
:::esm-plot{#id span="0..50" y=N} … ::: | one figure, with its own run |
:::esm-analysis{#id span="0..100"} … ::: | an esm-spec §6.7 analysis and its plots |
::esm-example[a + b*c] | one expression as text, mathematics and JSON |
::esm-variables{} | a table of what the current model declares |
::esm-download{} | a link to the page’s .esm file |
One colon is inline, two own a line, and three open a block that a line of
::: closes. A directive inside a code span or a fenced code block is left
alone, which is how this table shows them. A directive whose name is neither
part of the ESM Markdown format nor in the esm- namespace is passed through
untouched, so a page may use another tool’s directives alongside these. The
core reads these directives as prose, so the page stays a valid ESM Markdown
document; a test or analysis written in the format itself (an esm:tests
block, a ::plot{…} directive) is run and shown too.
Attributes and bodies
Attributes go in braces: {#id key=value key="value with spaces" flag}. A value
that reads as JSON keeps its type, so default=100 is a number and
y=["A","B"] is a list. #id sets a test’s, an analysis’s or a plot’s id.
A block directive’s body is YAML in the esm-spec shapes, so anything the format allows can be written even though the attributes cover only the common fields:
:::esm-plot{#rates span="0..50" y=N}
description: Faster decay constants empty the sample sooner.
parameter_sweep:
type: cartesian
dimensions:
- parameter: lambda
values: [0.05, 0.1, 0.2]
:::
Two attributes are shorthand for longer fields: span="0..50" is
time_span: {start: 0, end: 50}, and sliders="lambda=0.01..1 log" is the
interactive list that an interactive figure will read.
Building
cargo run --manifest-path pkg/earthsci-narrative/Cargo.toml --bin esm-narrative -- build
cargo run --manifest-path pkg/earthsci-narrative/Cargo.toml --bin esm-narrative -- build --watch
cargo run --manifest-path pkg/earthsci-narrative/Cargo.toml --bin esm-narrative -- build --check # CI
--check writes nothing and fails if the generated output is out of date.
Diagnostics are printed as file:line: error[code]: message, and every one
also appears on the page, next to the declaration, equation or directive that
caused it. A page the core cannot read at all is reported once, for the whole
page.
- Expressions, three ways
Every example on this page is parsed at build time: the text, the mathematics and the JSON are the same expression.
- Writing a model in prose
A tutorial: define, test and plot a model inside the page that explains it.