Skip to content

Restore the intentional MiscSystemData and generate_trajectory exports - #5009

Merged
ChrisRackauckas merged 2 commits into
SciML:masterfrom
ChrisRackauckas-Claude:restore-intentional-mtkbase-exports
Aug 22, 2026
Merged

Restore the intentional MiscSystemData and generate_trajectory exports#5009
ChrisRackauckas merged 2 commits into
SciML:masterfrom
ChrisRackauckas-Claude:restore-intentional-mtkbase-exports

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member

Ignore this PR until it has been reviewed by @ChrisRackauckas.

What changed and why

MiscSystemData and generate_trajectory were both deliberately exported by the contributors who added them; #4962 reclassified them as accidental internal reexports and removed both exports, which dropped public API in a minor release. This restores the exports, documents both names on the public API pages instead of the internals page, and removes the QA testset that asserted they were internal.

  • MiscSystemData — added and exported in b79914d by @AayushSabharwal as the user-facing key for one-off system metadata (setmetadata(sys, MiscSystemData, x)).
  • generate_trajectory — added and exported in 5be3f9e alongside the rest of the exported generate_* codegen family (generate_cost, generate_jacobian, generate_control_function, …).

#4979 then filed both docstrings under docs/src/internals/systems.md, whose page banner reads "These APIs may change without notice" — the wrong home for exported API. They move to the pages their siblings live on: MiscSystemData next to the system setmetadata/getmetadata entries in API/System_accessors.md, generate_trajectory into API/codegen.md. The collocation solve method that #4979 filed in the same internals section moves to API/dynamic_opt.md, the page that documents that exact workflow.

ModelingToolkitBase goes 1.67.0 → 1.68.0, in its own commit: widening the public API is a minor bump.

This is the upstream half of SciML/Catalyst.jl#1538, where @AayushSabharwal flagged that MiscSystemData is intentionally exported. No Catalyst follow-up is needed — its LEGACY_DEPENDENCY_REEXPORTS allowlist already carries both names.

Failing before / passing after

MWE run against the working tree, Julia 1.12.4:

using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D

for name in (:MiscSystemData, :generate_trajectory)
    println("$name exported from ModelingToolkit: ", Base.isexported(ModelingToolkit, name))
    println("$name public in ModelingToolkit:     ", Base.ispublic(ModelingToolkit, name))
end

@variables x(t)
@named sys = System([D(x) ~ -x], t)
sys = setmetadata(sys, MiscSystemData, "payload")
println("round-tripped metadata: ", getmetadata(sys, MiscSystemData, nothing))

On unmodified master (837ca4d):

$ julia --startup-file=no --project=. mwe.jl
MiscSystemData exported from ModelingToolkit: false
MiscSystemData public in ModelingToolkit:     false
generate_trajectory exported from ModelingToolkit: false
generate_trajectory public in ModelingToolkit:     false
ERROR: LoadError: UndefVarError: `MiscSystemData` not defined in `Main`

With this PR applied:

$ julia --startup-file=no --project=. mwe.jl
MiscSystemData exported from ModelingToolkit: true
MiscSystemData public in ModelingToolkit:     true
generate_trajectory exported from ModelingToolkit: true
generate_trajectory public in ModelingToolkit:     true
round-tripped metadata: payload

Verification

GROUP=QA on this branch, Julia 1.12.4 — the Aqua / ExplicitImports / public_reexports lane, which is what actually asserts that these two names are deliberate API rather than leaked internals:

$ GROUP=QA julia --startup-file=no --project=. -e 'using Pkg; Pkg.test()'
Test Summary: | Pass  Total     Time
QA            |   40     40  4m36.1s
     Testing ModelingToolkit tests passed

Same lane on unmodified master (837ca4d), for the baseline:

$ GROUP=QA julia --startup-file=no --project=. -e 'using Pkg; Pkg.test()'
Test Summary: | Pass  Total     Time
QA            |   52     52  4m26.7s
     Testing ModelingToolkit tests passed

Both are green. The 52 → 40 drop is exactly the deleted testset: 6 assertions (isdefined, !isexported, !ispublic, each against ModelingToolkitBase and ModelingToolkit) × 2 names. Nothing else was removed or loosened — in particular public_reexports still runs and now passes with both names back in REEXPORTED_API.

Docs build (checkdocs = :exports, doctest = true, linkcheck = true) — this is the check that gates the restored exports having rendered docs entries, since an exported name with no @docs entry fails CheckDocument:

$ julia --startup-file=no --project=docs -e 'using Pkg; Pkg.develop([PackageSpec(path="."), PackageSpec(path="lib/ModelingToolkitBase")]); Pkg.instantiate(); include("docs/make.jl")'
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Automatic `version="11.39.1"` for inventory from ../Project.toml
docs exit=0

The only warnings are the pre-existing ones on master: size_threshold_warn on three large API pages, the 60 @example text/html notice, and two linkcheck 301 redirects (claytex.com, codecov.io).

Runic (--check --diff, @runic env), typos over the added diff lines, and git diff --check all pass.

Not verified

  • Julia LTS (1.10) and prerelease. Everything above ran on 1.12.4. The deleted testset was the only VERSION >= v"1.11"-gated code touched here, so there is no version-specific branch left in the diff, but I did not run the LTS lane.
  • GPU, FMI, and downstream/ReleaseTest lanes.
  • The other test groups (InterfaceI, InterfaceII, Initialization, …). This diff adds two export lines, moves docs entries, and deletes a QA testset; it changes no solver or codegen behaviour, so I ran the lanes that can actually observe it (QA, docs) rather than the full matrix.

Anything a reviewer should push back on

  • Whether generate_trajectory should be exported at all, or only @public. It was exported by its author and every neighbouring generate_* entry point is exported, so this restores it as an export; if the intent was developer-only, @public plus a docs entry would be the alternative and that is a judgement call, not a mechanical one.
  • ModelingToolkit's [compat] floor on ModelingToolkitBase is left at "1.64". Only the 1.66/1.67 window lacks these exports, and MTK/MTKBase release in lockstep from this monorepo, so raising the floor to "1.68" seemed like more churn than the two-version gap warrants. Say the word if you would rather pin it.

Both names were deliberately exported by their authors: `MiscSystemData` in
b79914d as the user-facing key for one-off system metadata, and
`generate_trajectory` in 5be3f9e alongside the rest of the exported
`generate_*` codegen family. 735a4e0 reclassified them as accidental
internal reexports and dropped both, which removed public API in a minor
release and broke downstream use.

Restore the exports, document them on the public API pages rather than under
the internals "Internal API" banner, and drop the QA testset that asserted
they were internal. The collocation `solve` method moves from the same
internals section to the dynamic optimization page it belongs to.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Restoring two exports widens the public API, which is a minor bump.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
ChrisRackauckas marked this pull request as ready for review August 22, 2026 00:45
@ChrisRackauckas
ChrisRackauckas merged commit b7f579c into SciML:master Aug 22, 2026
79 of 93 checks passed
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.

2 participants