API reference

EarthSciAST has five bindings — Julia, TypeScript, Python, Rust and Go — that read, check, transform and (in three of them) simulate the same .esm documents. This reference has one page per stable operation, with a tab for each binding showing its spelling, signatures and documentation, taken from the binding’s own documentation tooling, along with runnable examples. The examples run in CI, so what is shown here is what the code does.

The surface has two tiers (see API_SPEC.md §3 ). Stable names are harmonized across bindings and break only at a major version. Extension names are a binding’s own documented seams; they may differ between bindings and may change in a minor release, and each binding lists them on one page.

Guides

• Getting started — Load a document, check it, look inside, print it, change it, flatten a coupled one, derive a reaction system’s equations, and simulate.

Capability profiles

Not every binding does everything. An operation missing from a binding outside its profile is by design, and the operation’s page says so.

Topics

• Document I/O (15) — Reading a document from a path, a string or a parsed value, and serializing it back to JSON.
• Versions and migration (9) — The format and library version constants, and migrating a document written for an older version of the format.
• Validation (11) — Checking a document against the schema and the structural rules of the specification, and reading the errors that result.
• Document types (45) — The in-memory types that mirror the sections of an .esm document: models, variables, equations, reaction systems, domains, events, data sources and more.
• Variable classification (20) — Which variables of a model are integrated states, algebraic unknowns, observed quantities or parameters of each kind (esm-spec section 6.3.1).
• Expressions (20) — Parsing, inspecting, substituting into, simplifying and evaluating expressions and equations.
• Display (4) — Rendering expressions, equations, models and whole documents for people, as plain text, Unicode or LaTeX.
• Editing (23) — Adding, removing and renaming the parts of a document, and composing, merging and extracting components.
• Flatten (20) — Turning a coupled document into a single system of variables and equations, and the errors coupling can raise.
• Load-time lowering and templates (20) — The passes a loader runs before a document is usable: enum lowering, subsystem references, expression templates and coupling imports.
• Graphs (22) — Component, expression and reference graphs of a document, and exporting them as DOT, Mermaid or JSON.
• Reactions (5) — Deriving ordinary differential equations from a reaction system, and its stoichiometric matrices.
• Units (15) — Parsing unit strings, converting between units and checking the dimensional consistency of equations.
• Simulation (24) — Building a problem from a document, integrating it, and reading states and observed quantities from the solution.
• Runtime I/O (14) — Refresh cadence, output planning and gridding: the protocol a host uses to feed data into and write results out of a running simulation.
• Relational keys and geometry (11) — Deterministic keys, ranking and grouping for relational index sets, and the polygon geometry used by regridding.
• Errors (4) — The base error type, the parse error, and the table of diagnostic codes shared by every binding. Errors specific to one operation are listed with it.
• Other (21) — Stable operations not yet placed in a topic.

Or browse all stable operations A–Z .

Bindings

Documentation coverage lists the stable names each binding has not documented yet.