Skip to content

Restore the documented modeling, solving, distribution and plotting reexports - #327

Merged
ChrisRackauckas merged 2 commits into
mainfrom
restore-documented-reexports
Aug 23, 2026
Merged

ChrisRackauckas merged 2 commits into
mainfrom
restore-documented-reexports

Conversation

@ChrisRackauckas

@ChrisRackauckas ChrisRackauckas commented Aug 23, 2026 •

Copy link
Copy Markdown
Member

What was stripped

d0061cd — "Remove dependency facade and enforce strict QA (#318)" — deleted 210 lines from src/EasyModelAnalysis.jl: the four bare

using DifferentialEquations
using ModelingToolkit
using Distributions
using Plots

lines and the four explicit export blocks that 713e02c (#317) had added to pin them.

using EasyModelAnalysis went from 1156 names to 26 — the package's own 25 query functions plus the module name. For a package whose entire premise is "one-liner queries over SciML-defined models", that removes the thing the package exists to provide.

Evidence that this was documented use

The stripping commit is its own counter-evidence: it had to rewrite the README quick demo from using EasyModelAnalysis to using DifferentialEquations, EasyModelAnalysis, ModelingToolkit, Plots. And 713e02c before it had already had to add the same imports to every docs page:

page was became
getting_started.md using EasyModelAnalysis, Plots using DifferentialEquations, EasyModelAnalysis, ModelingToolkit, Plots
tutorials/datafitting.md using EasyModelAnalysis + DifferentialEquations, Distributions, ModelingToolkit
examples/SEIRHD.md using EasyModelAnalysis + DifferentialEquations, Distributions, ModelingToolkit, Plots
examples/ASIR.md, examples/petri.md, examples/Carcione2020.md, scenarios/2–4, tutorials/{ensemble_modeling,sensitivity_analysis,threshold_interventions}.md same same

Every one of those pages previously ran on using EasyModelAnalysis alone.

How the list was chosen

Per "we should be reexporting what is normal documented use, but not whole dependencies", this is not a restored blanket @reexport and not the previous 1130-name full-surface restore. It is 393 names, chosen as:

  1. Every name used in docs/src/**/*.md code blocks, README.md, and test/ — extracted mechanically by matching each of the 1130 previously-exported names against the code fences (not prose, so fit/probs/alpha/color as local variables and keyword arguments do not count). That yields: ODEProblem, EnsembleProblem, OptimizationProblem, OptimizationFunction, remake, solve, SciMLBase, Tsit5; @independent_variables, @named, @parameters, @variables, @unpack, @mtkbuild, @mtkcompile, Differential, ODESystem, System, Num, structural_simplify, complete, equations, continuous_events, discrete_events, add_accumulations; Normal, Uniform, Truncated, truncated, var; plot, plot!, scatter!.
  2. The coherent API cluster around each, because these four are exactly the four capabilities the package advertises — build a model, solve it, sample a parameter distribution, plot the result. A user who can write ODEProblem/solve needs ODESolution, init, remake, the ensemble types, the callbacks, ReturnCode/successful_retcode and the default solver set; a user who can write Normal needs the other distributions and pdf/cdf/quantile/mean/std; a user who can write plot needs scatter, histogram, savefig, xlabel!, @layout.

Deliberately excluded (the ~740-name difference): SciMLBase's internal traits and function wrappers (has_*, is*, *_cache, WOperator, StaticWOperator) and problem/solution types for equation classes this package does not analyze; the SciMLOperators operator algebra; ModelingToolkit's structural-transformation internals (TearingState, BipartiteGraph, StructuralTransformations, Rewriters, RuleSet, pantelides_reassemble, alias_elimination) and the entire sympy_* / sympy_pythoncall_* bridge; the exotic tail of Distributions (WalleniusNoncentralHypergeometric, EdgeworthZ, KSOneSided, the ZeroMean*Canon family); and the ColorTypes color-space types Plots reexports (DIN99d, LCHuvA, AOklch, CIE1931JV_CMF, …) plus the backend-selection functions.

Per-package: DifferentialEquations 74/207, ModelingToolkit 93/327, Distributions 95/243, Plots 131/353.

Documentation

New page docs/src/api/reexports.md, wired into the API section of docs/make.jl. This is the part that matters most here: EasyModelAnalysis reexports across four unrelated packages, so without it a reader has no way to know that plot is documented by Plots, @variables by ModelingToolkit/Symbolics, ODEProblem by SciMLBase and Normal by Distributions.

The page states up front that EasyModelAnalysis owns and documents none of these names, gives an owner/documentation table for the four packages, then lists all 393 names grouped by owning package and by role within it — modeling / solving / distributions / plotting — each group linking to the owner's docs. Every section closes with an explicit boundary line naming what was deliberately excluded and why.

A script check confirms the page's bullet lists and the export blocks name exactly the same 393 symbols.

Drift protection

docs/src/api/reexports.md, the four export blocks in src/EasyModelAnalysis.jl and the REEXPORTS tuple in test/qa/qa.jl are the same list in three places. test/qa/qa.jl declares the same 393 symbols as REEXPORTS, passes them to reexports_allow, reuses them for api_docs_kwargs (ignore/rendered_ignore — these names are documented upstream) and for ei_kwargs.no_implicit_imports.ignore (they are reexported, not used), and adds a testset asserting each is in names(EasyModelAnalysis) and in scope.

Semver

Restoring names that used to be exported is not breaking — a patch/minor bump. No version bump here; a separate release pass handles versions.

Verified

Run locally on this branch (macOS aarch64, Julia 1.11.8):

  • Pkg.instantiate() + using EasyModelAnalysis — loads and precompiles clean.
  • All 393 approved names are in names(EasyModelAnalysis) and in scope from using EasyModelAnalysis; names(EasyModelAnalysis) is now 419 (26 own + 393 reexported). MISSING: Symbol[].
  • Runic v1 --check clean on the changed Julia files (src/EasyModelAnalysis.jl, test/qa/qa.jl, docs/make.jl); typos clean on all changed files.
  • All external documentation links in the new page return HTTP 200 (linkcheck = true in docs/make.jl).

Not run: Pkg.test() / the test/qa suite. This package's test environment pulls Turing, GlobalSensitivity, OptimizationBBO/NLopt and SciMLExpectations, and the machine is heavily loaded by other jobs; the full instantiate+precompile alone took ~11 minutes. The change is export-only plus QA declarations, and the reexport-surface property that CI's QA checks is exactly what was verified above.

Note on the docs

The explicit using DifferentialEquations, ModelingToolkit, … lines that #317/#318 added to the README and docs pages are left in place — they are harmless now, and reverting them across 13 files would be churn orthogonal to restoring the public surface. Worth a follow-up if you want the docs to demonstrate the facade again.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Rmh6B9eoW3N8oCbuuVPVxJ

ChrisRackauckas and others added 2 commits August 23, 2026 18:12
…eexports

#318 ("Remove dependency facade and enforce strict QA")
deleted the four bare `using DifferentialEquations / ModelingToolkit /
Distributions / Plots` lines and the explicit `export` blocks that #317 had added
to pin them. That took `using EasyModelAnalysis` from 1156 names down to 26 --
the package's own 25 query functions -- and removed exactly the thing the package
exists to provide. The same commit had to rewrite the README quick demo from
`using EasyModelAnalysis` to `using DifferentialEquations, EasyModelAnalysis,
ModelingToolkit, Plots`, and #317 had already had to add the same imports to
every tutorial, scenario and example page.

Restore the surface, but as the documented modeling/solving/distribution/plotting
API rather than whatever the four upstream packages happen to export: 393 names
instead of the previous 1130, following SciML/Sundials.jl#553.

The list is derived from the package's own docs, README and tests -- every name
used in an example, plus the coherent API cluster around it -- and drops
SciMLBase's internal traits and function wrappers, ModelingToolkit's structural
transformation and SymPy-bridge internals, the exotic tail of Distributions, and
the ColorTypes color-space types Plots reexports.

test/qa/qa.jl approves the same list via `reexports_allow`, reuses it for the
public-API docstring/rendering ignores (these names are documented upstream) and
for the implicit-import ignore (they are reexported, not used), and adds a drift
test that every approved name is actually reachable from the package.

Restoring names that used to be exported is not breaking.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rmh6B9eoW3N8oCbuuVPVxJ
Add `docs/src/api/reexports.md`, wired into the API section of docs/make.jl.
EasyModelAnalysis reexports across four unrelated packages, so without this page
a reader has no way to know that `plot` is documented by Plots, `@variables` by
ModelingToolkit/Symbolics, `ODEProblem` by SciMLBase and `Normal` by
Distributions.

The page opens by stating that EasyModelAnalysis owns and documents none of these
names, gives an owner/documentation table for the four packages, then lists all
393 reexported names grouped by owning package and by role within it -- modeling,
solving, distributions, plotting -- with a link to the owner's documentation for
each group. Each section closes with an explicit boundary line naming what was
deliberately left out and why (structural-transformation and SymPy internals,
SciMLBase traits and operator algebra, the exotic tail of Distributions, the
ColorTypes color-space types and backend selectors).

The page, the four `export` blocks in src/EasyModelAnalysis.jl and the `REEXPORTS`
tuple in test/qa/qa.jl are now the same list in three places; a script check
confirms the page's bullet lists and the export blocks name exactly the same 393
symbols.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rmh6B9eoW3N8oCbuuVPVxJ
@ChrisRackauckas
ChrisRackauckas merged commit 06718cc into main Aug 23, 2026
8 of 9 checks passed
@ChrisRackauckas
ChrisRackauckas deleted the restore-documented-reexports branch August 23, 2026 22:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant