Skip to content

Fix docs build: update BVDAE tutorial to current Ascher API and fix SparseConnectivityTracer links - #919

Merged
ChrisRackauckas merged 2 commits into
SciML:masterfrom
ChrisRackauckas-Claude:fix-bvp-ascher-linkcheck
Nov 2, 2026
Merged

ChrisRackauckas merged 2 commits into
SciML:masterfrom
ChrisRackauckas-Claude:fix-bvp-ascher-linkcheck

Conversation

@ChrisRackauckas-Claude

@ChrisRackauckas-Claude ChrisRackauckas-Claude commented Oct 18, 2026 •

Copy link
Copy Markdown
Member

🚧 UNREVIEWED — awaiting review by @ChrisRackauckas. Filed by an AI agent running as @ChrisRackauckas; Chris has not seen this.

Summary

The Documentation job on master fails with makedocs encountered errors [:linkcheck, :example_block] (job 117444520459):

  1. BoundaryValueDiffEqAscher >= 1.18 removed the zeta side-condition keyword from the AscherN solvers (current signature: Ascher4(; nlsolve, optimize, jac_alg, platform, max_num_subintervals)). The BVDAE example is rewritten to the current API: multi-point boundary conditions are expressed by evaluating the solution inside bc!(res, u, p, t) (u(0.0)[1], u(1.0)[2], ...), the same convention the SecondOrderBVProblem example above it already uses. The demonstrated conditions (x1(0)=0, x3(0)=1, x2(1)=sin(1)) and the jac_alg argument are unchanged.
  2. The linkcheck fails on adrianhill.de/SparseConnectivityTracer.jl/... (404). The package moved to JuliaDiff and its docs are now at juliadiff.org; both SparseConnectivityTracer links in advanced_ode_example.md are updated accordingly.
  3. docs/Project.toml now requires BoundaryValueDiffEqAscher = "1.18": the rewritten bc! form only runs on Ascher >= 1.18 (on 1.17 it fails inside the solver with a BoundsError).

Verification

julia --project=docs docs/make.jl (Julia 1.13.1; resolved versions identical to the failing CI run: BoundaryValueDiffEqAscher 1.18.1, BoundaryValueDiffEqCore 2.8.5, Documenter 1.19.0, SciMLBase 3.58.0).

Before (master worktree):

┌ Error: failed to run `@example` block in docs/src/tutorials/bvp_example.md:176-196
│    MethodError: no method matching Ascher4(; zeta::Vector{Float64}, jac_alg=BVPJacobianAlgorithm{...})
┌ Error: linkcheck 'https://adrianhill.de/SparseConnectivityTracer.jl/stable/user/api/#SparseConnectivityTracer.TracerSparsityDetector' status: 404.
ERROR: LoadError: `makedocs` encountered errors [:linkcheck, :example_block] -- terminating build before rendering.
exit 1

After (this branch, exact committed tree):

(only pre-existing warnings: duplicate @docs entries, example-size and
search-index size thresholds)
[ Info: Automatic `version="7.21.0"` for inventory from ../Project.toml
┌ Warning: Documenter could not auto-detect the building environment. Skipping deployment.
exit 0

After the compat bump: Pkg.resolve() in the docs env succeeds and still selects BoundaryValueDiffEqAscher 1.18.1, and the rewritten BVDAE block still runs (retcode: Success, boundary residuals ~1e-15).

The rewritten example was also run standalone in the docs env: retcode: Success, x1(0) ≈ 0, x3(0) ≈ 1, x2(1) = sin(1). typos and Runic --check are clean on the changed files.

Two intermediate make.jl runs failed only on transient status: 429 linkcheck responses from github.com (rate limiting from repeated local linkcheck sweeps); all such URLs return 200 to curl, and the final run passed every check on the committed tree.

Not verified

  • Julia 1.13.2 (CI) vs 1.13.1 (local) — patch-level difference only; the resolved Manifest matches CI versions.
  • deploydocs is a no-op outside CI by design.
  • The CI log's UndefVarError: OrdinaryDiffEqCore not defined in OrdinaryDiffEqPRK lines are Debug-level noise from @refs inside OrdinaryDiffEqPRK's own KuttaPRK2p5 docstring (OrdinaryDiffEqPRK v2.4.0 imports OrdinaryDiffEqCore selectively, so the module name isn't bound there; Documenter resolves the refs in another module). They do not fail the build and are not fixable from DiffEqDocs.

Please ignore until reviewed by @ChrisRackauckas.

Risk assessment

  • Risk: low
  • Blast radius: two documentation markdown files; no code, no API changes
  • Evidence: full docs/make.jl built locally, fail-before (exit 1, same errors as CI) / pass-after (exit 0); rewritten example verified to satisfy the original boundary conditions; replacement links return 200
  • Independent review: pending
  • Merge: needs independent review first

🤖 Generated by an AI agent — harness: Devin CLI 3000.11.92 · model: swe-2-high
Conversation: local job diffeqdocs-ascher-devin (no session URL)

ChrisRackauckas and others added 2 commits October 18, 2026 13:11
BoundaryValueDiffEqAscher >= 1.18 dropped the `zeta` solver keyword;
side-condition points are now expressed by evaluating the solution
inside the multi-point `bc` callback, matching the convention already
used by the SecondOrderBVProblem example above it in this file.
Also point the SparseConnectivityTracer links at the JuliaDiff
organization, which now hosts the package and its docs; the old
adrianhill.de docs URL 404s and fails linkcheck.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Devin <noreply@cognition.ai>
Agent-Harness: Devin CLI 3000.11.92
Agent-Model: swe-2-high
Agent-Session: local Devin job /home/crackauc/sandbox/goals/ci-green/devin-jobs/diffeqdocs-ascher (transcript in /home/crackauc/sandbox/goals/ci-green/devin-jobs/diffeqdocs-ascher/log.txt)
The rewritten BVDAE example only runs against Ascher >= 1.18: on 1.17
the callable-`bc!` form without `zeta` fails with a BoundsError inside
the solver. The docs env compat previously admitted 1.15.3+.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Devin <noreply@cognition.ai>
Agent-Harness: Devin CLI 3000.11.92
Agent-Model: swe-2-high
Agent-Session: local Devin job /home/crackauc/sandbox/goals/ci-green/devin-jobs/diffeqdocs-ascher (transcript in /home/crackauc/sandbox/goals/ci-green/devin-jobs/diffeqdocs-ascher/log.txt)
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

🤖 Automated comment from an AI agent running as @ChrisRackauckas — not written or reviewed by Chris.

Independent review (Codex CLI 0.164.0 / gpt-6.1-sol), session 01a1965f-36a7-7ff1-8e61-78d9309eee3a, reviewed head 9f60ce1

  • Verdict: MERGE
  • Risk: medium-low (ML4: documentation environment now requires BoundaryValueDiffEqAscher 1.18; L1: documentation-only API migration and link repairs).
  • Round / slot: 1 / 1
  • Blocking priorities: none

Review written by the reviewer named above in a session other than the PR author's, and copied here by the posting agent without change to its findings. The posting agent did not re-run the reviewer's commands.

Summary: Updates the BVDAE tutorial to the callable boundary-condition API, requires Ascher 1.18, and repairs two SparseConnectivityTracer links. Independent execution reproduces the base failure and confirms the head example succeeds; no blocking defects were found.

Blast radius: Documentation dependency resolution, the semi-explicit BVDAE tutorial example, and two external links; no library implementation or solver default changes.

Evidence: Blind assessment frozen in INITIAL.md and INITIAL.sha256 before author context. The exact head example passed with Ascher 1.18.1 and AutoForwardDiff (exit 0); the merge-base example failed on its unsupported zeta keyword in the same environment (exit 1). Both replacement links returned HTTP 200 and the API anchor exists. Head formatting and spelling checks passed; Documentation was skipped because the PR is a draft.

Blocking findings

None.

Non-blocking findings

None.

What I ran

  • git -C src fetch origin '+refs/pull/919/head:refs/remotes/pr/919' master, git -C src checkout --detach pr/919, git -C src rev-parse HEAD origin/master, git -C src merge-base origin/master HEAD, and git -C src diff origin/master...HEAD: exit 0. Head matches the requested live head; merge-base equals Base above. Inspected all three changed files, surrounding examples, documentation configuration, and root instructions; no AGENTS.md or CLAUDE.md was present.
  • sha256sum INITIAL.md > INITIAL.sha256: exit 0, before reading the description or commit bodies. git -C src log -1 --no-merges --format=%B: exit 0; author identity below comes only from its trailers.
  • Exactly three Julia invocations, sequential, using Julia 1.13.2, JULIA_NUM_THREADS=4, OPENBLAS_NUM_THREADS=1, JULIA_PKG_PRECOMPILE_AUTO=0, an isolated TMPDIR, and the supplied shared depot followed by default depots. Machine-specific environment path values are omitted. The temporary minimal environment resolved BoundaryValueDiffEq 5.25.1, BoundaryValueDiffEqAscher 1.18.1, BoundaryValueDiffEqCore 2.8.5, SciMLBase 3.58.0, and ForwardDiff 1.4.6; registries were not updated.
  • timeout 3600 julia +1.13.2 --startup-file=no --project=env probes/run_head.jl: exit 0. It activates the isolated environment, calls Pkg.instantiate(; update_registry=false, allow_autoprecomp=false), and executes the exact final example block from head docs/src/tutorials/bvp_example.md:176, with the page's BVP import. Output: RETCODE=Success; start state approximately [0, 0, 1, 0], end state approximately [sin(1), sin(1), 1, 0]. This exercises the specified BVPJacobianAlgorithm(BVP.AutoForwardDiff()) path (G2).
  • timeout 3600 julia +1.13.2 --startup-file=no --project=env probes/base.jl: exit 1. The corresponding block extracted with git -C src show 2be200d2e925d9ddaa99cc9f38de808704d5c4b5:docs/src/tutorials/bvp_example.md fails with MethodError: no method matching BoundaryValueDiffEqAscher.Ascher4(; zeta::Vector{Float64}, jac_alg::...); closest constructor reports unsupported keyword zeta. The PR adds no separate regression test: its modified existing executable example fails before and passes after in my own runs against identical dependencies.
  • timeout 3600 julia +1.13.2 --startup-file=no --project=env probes/analytic.jl: exit 0, three assertions passed. This independent probe retains the changed definitions and zero initial guess, using dt=0.05, abstol=1e-8, and reltol=1e-8. Integrating the equations and imposing the boundary data gives analytic branches [sin(t), sin(t), 1, 0] and [sin(t)+exp(t)-1, sin(t), exp(t), exp(t)]; both satisfy the differential and algebraic equations directly. Across 41 equally spaced evaluation points, maximum error against the zero branch was 7.781982691862064e-10, below the independent 1e-6 interpolation allowance (100 times the requested solver tolerance). Boundary residual was 1.1102230246251565e-16, below 1e-8; return code was Success. No expected values were copied from the solver.
  • gh pr checks 919 --repo SciML/DiffEqDocs.jl: exit 0. Documentation skipped; Runic check, Runic suggestions, and spelling succeeded. gh run list --repo SciML/DiffEqDocs.jl --branch master --event push --limit 5 and gh run view 39049329410 --repo SciML/DiffEqDocs.jl --log-failed (with a writable cache): exit 0. The master documentation failure contains the same unsupported-zeta error and the old API link's HTTP 404, ending in makedocs encountered errors [:linkcheck, :example_block]. The first log-fetch attempt was blocked by a read-only default cache; redirecting the cache succeeded.
  • Python urllib.request.urlopen checks of both replacement URLs: exit 0, HTTP 200 for each; id="SparseConnectivityTracer.TracerSparsityDetector" exists on the API page.

What I did not verify

I did not build or deploy the full documentation site, resolve the full documentation dependency environment, test the exact Ascher 1.18.0 lower bound, or run other Julia versions/platforms. The standalone example does not execute earlier examples in the page's shared Documenter module. CPU ForwardDiff was exercised; no GPU, MPI, Reactant, or other AD backend was tested, and those implementations are unchanged. The PR's full documentation CI is skipped, so the author's claimed full-build success was not independently reproduced.

🤖 Posted by an AI agent — harness: Claude Code · model: claude-sonnet-5-5
Conversation: https://claude.ai/code/session_01379heiiB35TtywhR7uSU74

@ChrisRackauckas
ChrisRackauckas marked this pull request as ready for review November 2, 2026 01:55
@ChrisRackauckas
ChrisRackauckas merged commit 1d6a0ad into SciML:master Nov 2, 2026
4 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