Repository navigation
Restore the documented modeling, solving, distribution and plotting reexports - #327
Merged
Merged
Conversation
…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
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was stripped
d0061cd— "Remove dependency facade and enforce strict QA (#318)" — deleted 210 lines fromsrc/EasyModelAnalysis.jl: the four barelines and the four explicit
exportblocks that713e02c(#317) had added to pin them.using EasyModelAnalysiswent 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 EasyModelAnalysistousing DifferentialEquations, EasyModelAnalysis, ModelingToolkit, Plots. And713e02cbefore it had already had to add the same imports to every docs page:getting_started.mdusing EasyModelAnalysis, Plotsusing DifferentialEquations, EasyModelAnalysis, ModelingToolkit, Plotstutorials/datafitting.mdusing EasyModelAnalysis+ DifferentialEquations, Distributions, ModelingToolkitexamples/SEIRHD.mdusing EasyModelAnalysis+ DifferentialEquations, Distributions, ModelingToolkit, Plotsexamples/ASIR.md,examples/petri.md,examples/Carcione2020.md,scenarios/2–4,tutorials/{ensemble_modeling,sensitivity_analysis,threshold_interventions}.mdEvery one of those pages previously ran on
using EasyModelAnalysisalone.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
@reexportand not the previous 1130-name full-surface restore. It is 393 names, chosen as:docs/src/**/*.mdcode blocks,README.md, andtest/— extracted mechanically by matching each of the 1130 previously-exported names against the code fences (not prose, sofit/probs/alpha/coloras 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!.ODEProblem/solveneedsODESolution,init,remake, the ensemble types, the callbacks,ReturnCode/successful_retcodeand the default solver set; a user who can writeNormalneeds the other distributions andpdf/cdf/quantile/mean/std; a user who can writeplotneedsscatter,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 entiresympy_*/sympy_pythoncall_*bridge; the exotic tail of Distributions (WalleniusNoncentralHypergeometric,EdgeworthZ,KSOneSided, theZeroMean*Canonfamily); 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 ofdocs/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 thatplotis documented by Plots,@variablesby ModelingToolkit/Symbolics,ODEProblemby SciMLBase andNormalby 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
exportblocks name exactly the same 393 symbols.Drift protection
docs/src/api/reexports.md, the fourexportblocks insrc/EasyModelAnalysis.jland theREEXPORTStuple intest/qa/qa.jlare the same list in three places.test/qa/qa.jldeclares the same 393 symbols asREEXPORTS, passes them toreexports_allow, reuses them forapi_docs_kwargs(ignore/rendered_ignore— these names are documented upstream) and forei_kwargs.no_implicit_imports.ignore(they are reexported, not used), and adds a testset asserting each is innames(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.names(EasyModelAnalysis)and in scope fromusing EasyModelAnalysis;names(EasyModelAnalysis)is now 419 (26 own + 393 reexported).MISSING: Symbol[].--checkclean on the changed Julia files (src/EasyModelAnalysis.jl,test/qa/qa.jl,docs/make.jl);typosclean on all changed files.linkcheck = trueindocs/make.jl).Not run:
Pkg.test()/ thetest/qasuite. 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