Skip to main content

earthsci_ast/
lib.rs

1//! # earthsci-ast - Rust Implementation
2//!
3//! This crate provides Rust types and utilities for the EarthSciML Abstract Syntax Tree Format (ESM).
4//!
5//! ## Features
6//!
7//! - **Core**: Parse, serialize, Markdown and Typst source text, substitute, validate schema
8//! - **Analysis**: Unit checking, equation counting, structural validation
9//! - **CLI Tool**: Command-line interface for validation and conversion
10//! - **WASM**: WebAssembly compilation for web use
11//!
12//! ## Example
13//!
14//! ```rust
15//! use earthsci_ast::{EsmFile, load_string, to_json};
16//!
17//! // Load an ESM file
18//! let esm_data = r#"
19//! {
20//!   "esm": "2.0.0",
21//!   "metadata": {
22//!     "name": "test_model"
23//!   },
24//!   "models": {
25//!     "simple": {
26//!       "variables": {},
27//!       "equations": []
28//!     }
29//!   }
30//! }
31//! "#;
32//! let esm_file: EsmFile = load_string(esm_data)?;
33//!
34//! // Save back to JSON
35//! let json = to_json(&esm_file)?;
36//! # Ok::<(), Box<dyn std::error::Error>>(())
37//! ```
38
39// Without the `solve` feature the crate keeps the whole build half —
40// parse, validate, flatten, classify, `esm_problem` — but every item that
41// only the solver reaches is compiled out. The pieces those items were the
42// sole callers of are then unreachable BY CONSTRUCTION, which is the point of
43// the feature, not a defect to chase per-item.
44#![cfg_attr(not(feature = "solve"), allow(dead_code, unused_imports))]
45// H-3 demoted ~45 modules to `pub(crate)`, so a doc link from a PUBLIC item to
46// an item that is now crate-private is expected and pervasive (74 sites). The
47// links are still correct — they resolve under `cargo doc
48// --document-private-items` and when reading the source, which is who reads
49// them now. Rewriting them all as inert code spans would delete working
50// navigation to buy silence, so the lint is turned off instead.
51#![allow(rustdoc::private_intra_doc_links)]
52
53// Conformance-harness argument parsing; callable by the conformance binaries but
54// hidden from the published rustdoc API surface.
55#[doc(hidden)]
56pub mod adapter_support;
57/// Pure, I/O-free structural and expression analysis helpers for the `esm` CLI.
58pub(crate) mod analysis;
59/// Planar spatial-index broad phase (rstar R*-tree + brute-force oracle) for the
60/// projection-pushdown overlap join-gate.
61pub(crate) mod broad_phase;
62pub(crate) mod cadence;
63pub(crate) mod canonicalize;
64pub(crate) mod classification;
65/// Core of the `compiled_rhs` conformance adapter. In the library, not in
66/// `src/bin/`, so the integration test drives the binary's exact code path
67/// without spawning a process. Hidden from the published rustdoc surface.
68#[doc(hidden)]
69pub mod compiled_rhs_adapter;
70/// Core of the `compiler_agreement` conformance adapter (CONFORMANCE_SPEC
71/// §5.44), on the same terms as [`compiled_rhs_adapter`]: in the library so a
72/// test drives the binary's exact code path, and hidden from the published
73/// rustdoc surface.
74///
75/// Behind `solve`: it integrates trajectories (`problem::solve`,
76/// `problem::observed_trajectories`), so a `--no-default-features` build that
77/// leaves the solver out must leave this adapter out too.
78#[cfg(feature = "solve")]
79#[doc(hidden)]
80pub mod compiler_agreement_adapter;
81pub(crate) mod coupling;
82pub(crate) mod coupling_imports;
83pub(crate) mod dae;
84/// esm-spec §9.6.6 `data_source_unbound`: what binds a DATA-FED parameter, and
85/// the refusal when nothing does (CONFORMANCE_SPEC §5.46).
86#[cfg(not(target_arch = "wasm32"))]
87pub(crate) mod data_fed;
88/// Flat→gridded simulation-output derivation (streaming-output-sinks RFC
89/// §7–§9): the Rust mirror of `EarthSciAST.jl`'s `src/data_output.jl`. Pure and
90/// wasm32-clean — it plans a dataset, it never writes one.
91pub(crate) mod data_output;
92/// esm-spec §8.2.1: load-time resolution of a data source's
93/// `source.url_template` against the referencing document's own directory.
94pub(crate) mod data_source_urls;
95pub(crate) mod diagnostic;
96pub(crate) mod display;
97/// ESM documents as Markdown and Typst source text, ported from the Lean model
98/// in `formal/Esm/Document/`.
99pub(crate) mod document;
100pub(crate) mod edit;
101pub(crate) mod elementwise_lift;
102pub(crate) mod error;
103pub(crate) mod faq;
104// The tier-2 EXTENSION SEAM (API_SPEC.md §3): the one deliberately-named place
105// where a Rust-only internal is handed to a caller. Everything reachable from
106// outside this crate is either a root `pub use` above/below (the stable tier,
107// pinned symbol-by-symbol by api-surface.json) or a member of this module.
108pub(crate) mod expression;
109pub mod extension;
110pub(crate) mod flatten;
111pub(crate) mod graph;
112pub(crate) mod inline_test_checks;
113pub mod intern;
114pub(crate) mod join;
115pub(crate) mod json_visit;
116pub(crate) mod lower_enums;
117pub(crate) mod lower_expression_templates;
118pub(crate) mod migration;
119pub(crate) mod observed_cone;
120pub(crate) mod op_registry;
121pub(crate) mod parse;
122/// The evaluator's working precision — `domain.element_type` (esm-spec
123/// §11.3). Public because the contract it implements (`"Float32"` means
124/// per-operation binary32 rounding) is observable, and a host embedding the
125/// evaluator needs to be able to name it.
126pub mod precision;
127pub mod precision_infer;
128pub mod provider;
129pub(crate) mod reactions;
130pub(crate) mod ref_loading;
131pub(crate) mod reference_resolution;
132pub(crate) mod relational;
133pub(crate) mod serialize;
134pub(crate) mod solver;
135pub(crate) mod stdlib;
136pub(crate) mod structural;
137pub(crate) mod substitute;
138pub(crate) mod template_imports;
139#[cfg(test)]
140pub(crate) mod test_support;
141pub(crate) mod types;
142pub(crate) mod unit_conversion;
143pub(crate) mod units;
144pub(crate) mod validate;
145pub(crate) mod variable_bounds;
146
147#[cfg(feature = "wasm")]
148pub mod wasm;
149
150pub mod performance;
151
152// Non-gated: the `CompileError` type is also named by the WASM-compiled
153// `faq` / `join` passes, so it cannot live inside the gated solver module.
154pub(crate) mod compile_error;
155
156// The solver plumbing and run vocabulary (gt-5ws). Compiled for wasm too: its
157// diffsol/Faer path is pure Rust (spike S1).
158pub(crate) mod simulate;
159
160// Compiled for wasm too (EarthSciAST-akz): the array/PDE runtime is
161// wasm-clean, so PDEs run client-side.
162pub mod simulate_array;
163
164// §6.6.5 inline PDE tests over the array simulation pathway (field
165// reductions, analytic references, coordinate-expression evaluation).
166// Compiled for wasm too, like the `simulate_array` runtime it drives; only
167// data-source providers, which need the native build pipeline, are refused
168// there.
169#[cfg(feature = "solve")]
170pub(crate) mod inline_tests;
171/// Core of the INLINE-TEST conformance adapter (CONFORMANCE_SPEC §5.45), on
172/// the same terms as [`compiler_agreement_adapter`]: in the library so a test
173/// drives the binary's exact code path, and hidden from the published rustdoc
174/// surface.
175///
176/// Gated exactly like the `inline_tests` module it drives. Unlike the
177/// agreement adapter it is also native-only: it imports the runner directly,
178/// so without the wasm32 gate that build fails on an unresolved import rather
179/// than simply omitting the adapter.
180#[cfg(all(not(target_arch = "wasm32"), feature = "solve"))]
181#[doc(hidden)]
182pub mod inline_tests_adapter;
183
184#[cfg(not(target_arch = "wasm32"))]
185mod determinism_adapter;
186pub(crate) mod row_dedup;
187
188// Build-time value-invention front-door — derived index-sets (`distinct`
189// producers) resolved via the relational engine, ONCE at setup (RFC §6.1 / §5.5).
190pub(crate) mod value_invention;
191
192// Automatic projection-pushdown desugar (the Julia/Python `desugar_pushdown`
193// port): a raw-document → raw-document transform + the record-derived provider
194// gate helpers the `prepare` entry point consumes. Raw-JSON side by design —
195// see the module docs.
196pub(crate) mod pushdown_rewrite;
197
198// The deterministic-per-document BUILD PIPELINE — rewrite → value-invention →
199// member-factor feedback → gated fetch → observed-graph evaluation, all
200// engine-side. It used to be the public `prepare`/`Prepared` entry point;
201// `esm-libraries-spec.md` §2.5.1 folds it into EsmProblem construction, so what is
202// public here is the provider contract and the build-observability seam.
203// Native-only (drives `simulate_array`).
204#[cfg(not(target_arch = "wasm32"))]
205pub(crate) mod prepare;
206
207// The EsmProblem / `solve` surface (`esm-libraries-spec.md` §2.5): one noun and
208// one verb. Construction does NOT require the solver — only `solve` / `init` /
209// `solve_to_completion` do, and those are behind the `solve` feature.
210pub(crate) mod problem;
211// Strip and expose (API_SPEC §5.8, RFC U6).
212pub(crate) mod strip;
213
214// OPT-IN EarthSciIO bridge: a `CadenceProvider` backed by a real EarthSciIO
215// `Provider`. Behind the `esio` feature so the default build does not link
216// EarthSciIO — the two rigs stay decoupled, exactly as on the Python side
217// (`earthsci_ast.data_sources.esio_provider`), and a caller opts in.
218#[cfg(feature = "esio")]
219pub mod esio_provider;
220
221/// PJRT runtime for the compiled right-hand side (feature `xla`, OFF by
222/// default). See `simulate_array::tape::xla_emit` for the emitter it runs.
223#[cfg(feature = "xla")]
224pub mod xla_runtime;
225
226// Re-export main types
227pub use cadence::{
228    Cadence, CadenceError, ClassSummary, MaterializationPoint, Partition, classify, compute_fold,
229    partition_model,
230};
231pub use canonicalize::{
232    CanonicalizeError, canonical_json, canonicalize, canonicalize_document, format_canonical_float,
233};
234// The document source formats (esm-spec, CONFORMANCE §5.58): Markdown and Typst
235// spellings of a whole `.esm` document, printed and read losslessly.
236pub use document::{
237    ConstructSource, DocumentFormat, MathError, expression_names, parse_document,
238    parse_document_with_sources, parse_markdown, parse_math, parse_typst, print_document,
239    print_markdown, print_math, print_typst,
240};
241// The esm-spec §6.3.1 classification API. esm 1.0.0 declares two variable
242// types and DERIVES the rest, so these are the only sanctioned way to ask
243// which unknowns are ODE states, which are observed, and which parameters are
244// Brownian / discrete / sampled / constant.
245pub use classification::{
246    Classification, LhsForm, SystemKind, algebraic_unknowns, brownian_parameters,
247    constant_parameters, discrete_parameters, is_ode_state, observed_definition_json,
248    observed_definitions, observed_unknowns, ode_states, sampled_parameters, system_kind,
249};
250pub use coupling_imports::{
251    CouplingImportOptions, expand_coupling_imports, has_coupling_import, is_coupling_library_doc,
252};
253pub use dae::{DaeError, DiscretizeOptions, apply_dae_contract, default_dae_support, discretize};
254pub use data_output::{
255    CoordPlan, GridPlan, OutputError, OutputMeta, OutputPlan, VarGridding, VarPlan,
256    derive_output_gridding, derive_output_meta, derive_output_plan, group_gridding_by_grid,
257    parse_cell_key, plan_dimension_coordinates,
258};
259#[cfg(not(target_arch = "wasm32"))]
260pub use expression::evaluate;
261pub use expression::{contains, free_parameters, free_variables, simplify};
262pub use flatten::{
263    Contribution, DimensionPromotionRecord, FlattenError, FlattenMetadata, FlattenedSystem,
264    LoaderField, TermOrigin, capture_coupling_diagnostics, flatten, flatten_model,
265    flatten_with_options,
266};
267pub use graph::{
268    ComponentGraph, ComponentMetadata, ComponentNode, ComponentType, CouplingEdge, DependencyEdge,
269    DependencyRelationship, ExpressionGraph, ExpressionGraphInput, ExpressionGraphOptions, Graph,
270    VariableKind, VariableNode, component_exists, component_graph, expression_graph,
271    expression_graph_with_options, get_component_type, to_dot, to_json_graph, to_mermaid,
272};
273pub use parse::{
274    LoadOptions, load_document, load_document_with_options, load_path, load_path_with_options,
275    load_string, load_string_with_options,
276};
277pub use reactions::{
278    DeriveError, derive_odes, lower_reactions_to_equations, stoichiometric_matrix,
279};
280pub use ref_loading::{
281    resolve_subsystem_refs, resolve_subsystem_refs_raw, resolve_subsystem_refs_with_metaparameters,
282};
283pub use reference_resolution::{
284    EdgeKind, ReferenceEdge, ReferenceGraph, ReferenceResolutionError, ReferenceVertex, VertexKind,
285    build_reference_graph, resolve_references,
286};
287// Deprecated alias of `build_reference_graph`, kept for one minor per
288// API_SPEC.md §10 (§8 item 17 folded the registry into a trailing argument).
289#[allow(deprecated)]
290pub use reference_resolution::build_reference_graph_with_index_sets;
291// Deprecated alias of `ReferenceResolutionError`, kept for one minor per
292// API_SPEC.md §10 (§8 item 10 renamed it). Re-exported behind
293// `allow(deprecated)` so the re-export itself does not warn.
294#[allow(deprecated)]
295pub use reference_resolution::ReferenceError;
296pub use relational::{
297    FloatKeyError, Key, Num, SemiringOp, canonical_index_set_json, distinct, group_aggregate,
298    serialize_keys, serialize_pairs,
299};
300pub use serialize::{to_json, to_json_compact, write_path};
301// Where a loaded document writes the deprecated `records_per_sample`
302// (esm-spec §8.5.1), the sites the `deprecated_records_per_sample` load
303// warning names.
304pub use structural::deprecated_records_per_sample_sites;
305pub use substitute::{
306    ScopedContext, substitute, substitute_in_model, substitute_in_model_with_context,
307    substitute_in_reaction_system, substitute_in_reaction_system_with_context,
308    substitute_with_context,
309};
310pub use template_imports::{
311    apply_scope_injections, is_template_library_doc, reject_template_imports_pre_v08,
312    resolve_template_machinery,
313};
314// Document-scoped solver hints (esm-spec §2.2): the spec-version gates, the
315// §2.2.2 tolerance resolution order, the §2.2.6 `solver.external` location and
316// the §2.2.7 `solver.time_span` interval — the parts of the block that are NOT
317// advisory.
318pub use solver::{
319    TimeOriginSource, reject_solver_external_pre_v13, reject_solver_pre_v11,
320    reject_solver_time_span_pre_v13, resolve_time_span, resolve_tolerances,
321    solver_external_location, time_origin, timestamp_to_seconds,
322};
323pub use types::{
324    AffectEquation, AutoRecords, ContinuousEvent, Coordinate, CouplingEntry, CouplingRole,
325    CovarianceMatrix, DaeInfo, DataSource, DataSourceBinding, DataSourceDeterminism,
326    DataSourceKind, DataSourceLocation, DataSourceMetadata, DataSourceTemporal, DiscreteEvent,
327    DiscreteEventTrigger, DiscretizedFrom, Distribution, DistributionParam, Domain, Equation,
328    EsmFile, Expr, ExpressionNode, FunctionalUpdate, InlineValue, Metadata, Model, ModelAnalysis,
329    ModelTest, ModelTestAssertion, ModelVariable, Operator, ParameterSweep, ParameterUpdate,
330    ParameterUpdateSpec, Plot, PlotAxis, PlotSeries, PlotValue, PlotY, Reaction, ReactionSystem,
331    RecordsPerFile, RegionBound, Solver, SolverTimeSpan, Species, StoichiometricEntry,
332    SweepDimension, SweepRange, TimePoint, TimeSpan, Tolerance, UnitConversion, UpdateValue,
333    VariableBound, VariableMapTransform, VariableType,
334};
335pub use validate::{
336    SchemaError, StructuralError, StructuralErrorCode, UnitWarning, ValidationResult, validate,
337    validate_text,
338};
339// Deprecated alias of `validate_text`, kept for one minor per API_SPEC.md §10
340// (§8 item 13 named the text convenience `validate_text`).
341#[allow(deprecated)]
342pub use validate::validate_complete;
343pub use value_invention::{
344    BoundaryKind, ValueInventionError, ValueInventionResult, apply_value_invention,
345    materialize_value_invention,
346};
347
348pub use pushdown_rewrite::{
349    GateAxis, ProviderGate, PushdownRewriteError, desugar_pushdown, pushdown_coupling_pairs,
350    pushdown_provider_gates, pushdown_record,
351};
352// `Flow` is deliberately absent: the build pipeline re-exports the SAME `Flow`
353// the solver uses, and the crate root already carries it from `simulate`.
354// `prepare` / `Prepared` / `PrepareOptions` are GONE (esm-libraries-spec §2.5.1
355// — replaced by `esm_problem` / `EsmProblem` / `ProblemOptions`); what remains is
356// the build-time provider contract and the build-observability seam.
357#[cfg(not(target_arch = "wasm32"))]
358pub use prepare::{
359    AxisSel, PrepareError, PreparePhase, PrepareProgress, PrepareProgressFn, PrepareProvider,
360};
361
362pub use edit::{
363    EditError, add_coupling, add_equation, add_model, add_reaction, add_reaction_system,
364    add_species, add_variable, remove_coupling, remove_equation, remove_model, remove_reaction,
365    remove_species, remove_variable, replace_coupling, replace_equation, update_model_metadata,
366};
367pub use error::EsmError;
368// The central diagnostic-code registry (phase-6 H-2). `diagnostic::codes` is
369// the per-code constant form that raise sites reference; `ERROR_CODES` is its
370// enumerable `(name, value)` table, the Rust twin of Julia's `ERROR_CODES`
371// NamedTuple, TypeScript's `ERROR_CODES` object and Go's `codes.go`.
372pub use diagnostic::{ERROR_CODES, error_code_names};
373pub use lower_enums::{EnumLoweringError, lower_enums, lower_enums_mut, lower_enums_raw};
374pub use migration::{MigrationError, can_migrate, migrate, supported_migration_targets};
375// Deprecated alias of `supported_migration_targets`, kept for one minor per
376// API_SPEC.md §10 (phase-6 G-2 dropped the `get_` prefix).
377#[allow(deprecated)]
378pub use migration::get_supported_migration_targets;
379
380pub use compile_error::CompileError;
381
382#[cfg(feature = "solve")]
383pub use inline_tests::{
384    AssertionResult, BuildProviderFactory, InlineTestOptions, check_assertion,
385    ephemeral_injected_file, evaluate_cellwise, field_reduce, resolve_tolerance, run_inline_tests,
386    run_inline_tests_filtered, run_inline_tests_paths, run_inline_tests_with_base_dir,
387    run_inline_tests_with_options, run_inline_tests_with_providers, state_cells,
388};
389pub use performance::{CompactExpr, PerformanceError};
390#[cfg(feature = "parallel")]
391pub use reactions::stoichiometric_matrix_parallel;
392pub use simulate::{
393    Alg, DEFAULT_ABSTOL, DEFAULT_RELTOL, Flow, Progress, ProgressFn, ReturnCode, SimulateError,
394    Solution, SolutionMetadata, SolveOptions, compile_array,
395};
396
397// The EsmProblem / `solve` surface. `simulate` is deleted in all its forms.
398#[allow(deprecated)]
399pub use problem::Compile;
400pub use problem::{
401    CallbackFn, CallbackSet, Compiler, CompilerReport, CompilerRuleReport, EnsembleProblem,
402    EsmProblem, ProblemInput, ProblemOptions, Remake, Rhs, callbacks, compose, esm_problem,
403    observed_field, remake,
404};
405#[cfg(feature = "solve")]
406pub use problem::{
407    Integrator, StepStatus, init, initial_state, observed_trajectories, observed_trajectory, solve,
408    solve_ensemble, solve_to_completion, step,
409};
410// Range-restricted and operator-restricted right-hand sides (API_SPEC §5.8).
411pub use simulate_array::range::{
412    AxisCut, Decomposition, ForcingSet, ForcingSlot, HaloReport, LaneBlock, LaneInputs, LaneKind,
413    LaneLayout, LaneProgram, ParamSlot, RhsError, RhsProgram, RhsSelection, RhsWorkspace, SlotKind,
414    StateBlock, TileBlock, TileBox, TileLayout, TileProgram, forcing_from_sample, rhs_program,
415};
416// Strip and expose (API_SPEC §5.8): stripped constructs and standalone kernels.
417pub use problem::stripped;
418pub use simulate_array::range::{
419    Kernel, KernelBlock, KernelOutput, KernelSet, KernelSpec, KernelWorkspace, compile_kernels,
420};
421pub use strip::{
422    EventKind, StripSet, StrippedConstructs, StrippedEvent, StrippedResidual, StrippedUpdate,
423    ZBlock,
424};
425pub use units::{
426    Dimension, EquationDimensionVerdict, ExactScale, Rational, ScaleFactor, UNIT_FINDING_ANALYSIS,
427    UNIT_FINDING_DIMENSIONAL_MISMATCH, UNIT_FINDING_DIMENSIONLESS_LITERAL,
428    UNIT_FINDING_UNPARSEABLE, Unit, UnitError, UnitFinding, UnitParseFailure, UnitSeverity,
429    build_unit_env, check_dimensional_consistency, check_equation_dimensions,
430    check_expression_dimensions, convert_units, equation_dimension_verdict, model_unit_env,
431    parse_unit, validate_equation_dimensions,
432};
433
434#[cfg(feature = "parallel")]
435pub use performance::ParallelEvaluator;
436
437#[cfg(feature = "custom_alloc")]
438pub use performance::ModelAllocator;
439
440/// This crate's OWN version — NOT the `.esm` format version, which is
441/// [`SCHEMA_VERSION`]. The two are unrelated numbers. Every binding exposes
442/// both, under these two names.
443pub const LIBRARY_VERSION: &str = env!("CARGO_PKG_VERSION");
444/// ESM schema version supported by this implementation. Must track the
445/// version in `esm-schema.json`'s `$id` / esm-spec.md; the
446/// `schema_version_matches_bundled_schema` test enforces it, and
447/// `parse::library_version()` (major-compat gating) derives from it.
448pub const SCHEMA_VERSION: &str = "2.3.0";
449
450#[cfg(test)]
451mod version_tests {
452    /// SCHEMA_VERSION must track the version embedded in the bundled schema's
453    /// `$id` (and therefore esm-spec.md).
454    #[test]
455    fn schema_version_matches_bundled_schema() {
456        let schema: serde_json::Value =
457            serde_json::from_str(include_str!("esm-schema.json")).expect("bundled schema parses");
458        let id = schema["$id"].as_str().expect("schema has an $id");
459        assert!(
460            id.contains(&format!("/{}/", crate::SCHEMA_VERSION)),
461            "SCHEMA_VERSION {} does not match schema $id {}",
462            crate::SCHEMA_VERSION,
463            id
464        );
465    }
466}