[pull] master from SciML:master

README.md

@@ -59,7 +59,7 @@ exported, so use qualified names such as `MATLABDiffEq.ode45()`.
 ## Example
 
 ```julia
-using MATLAB, MATLABDiffEq, ParameterizedFunctions, SciMLBase
+using MATLABDiffEq, ParameterizedFunctions
 
 f = @ode_def LotkaVolterra begin
     dx = 1.5x - x*y
@@ -105,7 +105,7 @@ MATLAB.show_msession()
 Generally, for long enough problems the overhead is minimal. Example:
 
 ```julia
-using MATLAB, MATLABDiffEq, ParameterizedFunctions, SciMLBase
+using MATLABDiffEq, ParameterizedFunctions
 f = @ode_def_bare RigidBodyBench begin
     dy1 = -2*y2*y3
     dy2 = 1.25*y1*y3

docs/make.jl

@@ -12,7 +12,7 @@ makedocs(;
         canonical = "https://docs.sciml.ai/MATLABDiffEq/stable/",
         prettyurls = get(ENV, "CI", "false") == "true",
     ),
-    pages = ["Home" => "index.md"],
+    pages = ["Home" => "index.md", "API" => "api.md"],
 )
 
 deploydocs(; repo = "github.com/SciML/MATLABDiffEq.jl.git", push_preview = true)

docs/src/api.md

@@ -0,0 +1,35 @@
+# API
+
+The MATLABDiffEq algorithm markers are documented under
+[Public API](index.md#Public-API) on the home page.
+
+## Reexported SciML common interface
+
+`using MATLABDiffEq` also brings in the parts of the SciML common interface needed to
+build an ODE problem, solve it, and inspect the result, so they do not have to be
+imported separately. MATLABDiffEq does not define these names -- they are owned and
+documented by [SciMLBase](https://docs.sciml.ai/SciMLBase/stable/), and that is where
+their documentation lives:
+
+  - Problems: `ODEProblem`, `EnsembleProblem`
+  - Functions: `ODEFunction`
+  - Solutions: `ODESolution`, `EnsembleSolution`, `EnsembleSummary`, `DEStats`
+  - Ensemble algorithms: `EnsembleSerial`, `EnsembleThreads`, `EnsembleDistributed`,
+    `EnsembleSplitThreads`, and the `EnsembleAnalysis` module
+  - Solving: `solve`, `remake`
+  - Return status: `ReturnCode`, `successful_retcode`
+  - `NullParameters`
+
+Note that the MATLAB algorithms themselves are public but *not* exported, so they are
+still written qualified: `MATLABDiffEq.ode45()`.
+
+Anything else from SciMLBase must be imported from SciMLBase directly. Three groups are
+deliberately absent:
+
+  - **DAE, SDE, DDE and every other non-ODE problem type.** `SciMLBase.__solve` is
+    defined here only for `AbstractODEProblem`. (`ode15i` names MATLAB's implicit solver,
+    but it is still reached through an `ODEProblem`.)
+  - **Callbacks.** `__solve` errors on a `callback` keyword ("Callbacks are not supported
+    in MATLABDiffEq.jl"), so `ContinuousCallback` and friends are not part of its surface.
+  - **The integrator interface** (`init`, `step!`, `solve!`, `reinit!`, ...).
+    MATLABDiffEq implements `SciMLBase.__solve` only; it has no integrator.

docs/src/index.md

@@ -10,11 +10,12 @@ models; native Julia solvers are the recommended choice for production workloads
 
 ## Basic Usage
 
-Load `SciMLBase` for the problem and solve interfaces, then pass a qualified MATLABDiffEq
+`using MATLABDiffEq` brings the SciML common interface -- `ODEProblem`, `solve` and the
+solution types -- into scope along with the algorithms, so pass a qualified MATLABDiffEq
 algorithm to `solve`:
 
 ```julia
-using MATLABDiffEq, SciMLBase
+using MATLABDiffEq
 
 function lorenz!(du, u, p, t)
     du[1] = 10.0 * (u[2] - u[1])
@@ -33,7 +34,9 @@ supported.
 ## Public API
 
 Algorithm types are public but not exported, which avoids collisions with similarly named
-algorithms from other solver packages. Use them through the `MATLABDiffEq` namespace.
+algorithms from other solver packages. Use them through the `MATLABDiffEq` namespace. The
+SciML common interface that `using MATLABDiffEq` reexports alongside them is listed on the
+[API page](api.md).
 
 ```@docs
 MATLABAlgorithm

src/MATLABDiffEq.jl

@@ -10,6 +10,22 @@ import SciMLBase: __solve
 using SciMLPublic: @public
 using Symbolics: MATLABTarget, build_function
 
+# The SciML common interface that MATLABDiffEq reexports (see the `export` block below),
+# so that `using MATLABDiffEq` on its own is enough to build an ODE problem, solve it,
+# and inspect the result -- the workflow the README and docs/src/index.md document. Every
+# name stays owned and documented upstream.
+using SciMLBase: EnsembleAnalysis, EnsembleDistributed, EnsembleProblem, EnsembleSerial,
+    EnsembleSolution, EnsembleSplitThreads, EnsembleSummary, EnsembleThreads,
+    NullParameters, ODEFunction, ODEProblem, ODESolution, ReturnCode, remake, solve,
+    successful_retcode
+
+# Reexported SciML common interface; approved via `reexports_allow` in test/qa/qa.jl.
+# `DEStats` is imported above.
+export DEStats, EnsembleAnalysis, EnsembleDistributed, EnsembleProblem, EnsembleSerial,
+    EnsembleSolution, EnsembleSplitThreads, EnsembleSummary, EnsembleThreads,
+    NullParameters, ODEFunction, ODEProblem, ODESolution, ReturnCode, remake, solve,
+    successful_retcode
+
 # MATLAB only supports Float64 arrays. Check if a type is MATLAB-compatible.
 # Note: We specifically accept standard Julia integer types that MATLAB can convert,
 # but NOT BigInt since MATLAB doesn't support arbitrary precision integers.

test/qa/qa.jl

@@ -1,3 +1,25 @@
-using MATLABDiffEq, SciMLTesting
+using MATLABDiffEq, SciMLTesting, Test
 
-run_qa(MATLABDiffEq)
+# The SciML common interface MATLABDiffEq deliberately reexports so that
+# `using MATLABDiffEq` is enough to build an ODE problem, solve it, and inspect the
+# result. Owned and documented upstream; kept in sync with the reexport `export` block
+# in src/MATLABDiffEq.jl and the API page in docs/src/api.md.
+const REEXPORTS = (
+    :DEStats, :EnsembleAnalysis, :EnsembleDistributed, :EnsembleProblem, :EnsembleSerial,
+    :EnsembleSolution, :EnsembleSplitThreads, :EnsembleSummary, :EnsembleThreads,
+    :NullParameters, :ODEFunction, :ODEProblem, :ODESolution, :ReturnCode, :remake,
+    :solve, :successful_retcode,
+)
+
+run_qa(MATLABDiffEq; reexports_allow = REEXPORTS)
+
+@testset "Reexport surface" begin
+    # Every approved reexport must actually be reachable from `using MATLABDiffEq`, so
+    # the allow-list cannot drift into approving names the package no longer provides.
+    # `isdefined(@__MODULE__, ...)` tests the property directly: this file's
+    # `using MATLABDiffEq` is what has to bring the name into scope.
+    @testset "$name" for name in REEXPORTS
+        @test name in names(MATLABDiffEq)
+        @test isdefined(@__MODULE__, name)
+    end
+end