Skip to content

docs: migrate ExaModels examples to the add_var/add_obj/add_con API - #645

Merged
sshin23 merged 1 commit into
masterfrom
docs/examodels-0.12-api
Aug 24, 2026
Merged

docs: migrate ExaModels examples to the add_var/add_obj/add_con API#645
sshin23 merged 1 commit into
masterfrom
docs/examodels-0.12-api

Conversation

@sshin23

@sshin23 sshin23 commented Aug 24, 2026

Copy link
Copy Markdown
Member

Problem

The docs build fails on master (example run).

ExaModels v0.12.0 removed the legacy variable, objective and constraint entry points, so every @example block that builds a model dies with:

UndefVarError: `variable` not defined in `ExaModels`

There are 6 such root failures, in docs/src/tutorials/{gpu,multiprecision,quasi_newton}.md. The remaining 19 reported failures are cascades from them (UndefVarError: nlp not defined, results not defined, ...), and makedocs then terminates with encountered an error [:example_block].

Fix

Replace the three removed entry points with the current macro API — @add_var, @add_obj, @add_con — which is what the ExaModels v0.12 guide uses. ExaCore(T; backend = ...) is unchanged.

One subtlety worth flagging for future migrations: the bounds have to be passed as keyword arguments after a semicolon. In a macro call, lvar = -10.0 following a comma parses as a positional argument rather than a keyword, so the model builds fine and the bound is silently dropped (lvar stays at -Inf). The first draft of this change had exactly that bug and it was caught only by asserting on get_lvar.

Verification

Since the change is a rewrite of model-building code, it was checked for semantic equivalence rather than just for compiling. The model functions were extracted programmatically from the markdown files (so the thing under test is the doc, not a transcription) and compared against the same functions running the legacy API on ExaModels v0.11.2, where variable still exists.

Compared: nvar, ncon, nnzj, nnzh, lvar/uvar/lcon/ucon, x0, and the objective, gradient, constraints, Jacobian and Hessian evaluated at a fixed deterministic point. Cases: airport_model in Float64 and Float32, and elec_model(10).

  • All fingerprints are identical before and after.
  • Controls: the same comparison run against unedited master fails at extraction; dropping lvar/uvar from one @add_var makes the comparison go red — so the check is capable of failing.
  • gpu.md was additionally run with a real CUDABackend(): x0 is a CuArray as the surrounding text claims, the bounds are applied on device, and the objective and constraint values agree with the CPU reference.

No prose changes were needed; the models are unchanged, so the iteration counts quoted in the tutorials still hold.

ExaModels v0.12.0 removed the legacy `variable`, `objective` and
`constraint` entry points, so every `@example` block that builds a model
failed with `UndefVarError: variable not defined in ExaModels`, and the
downstream blocks cascaded into `UndefVarError: nlp not defined`. This
broke the docs build.

Replace them with the current macro API (`@add_var`, `@add_obj`,
`@add_con`). The bounds and start values are passed as keyword arguments
after a semicolon: in a macro call `lvar = -10.0` after a comma parses as
a positional argument and the bound would be silently dropped.

The rewritten models were checked to be equivalent to the originals by
comparing problem dimensions, sparsity counts, bounds, and the objective,
gradient, constraint, Jacobian and Hessian values at a fixed point against
ExaModels v0.11.2, for both Float64 and Float32, and on a CUDA backend for
the GPU tutorial.
@codecov

codecov Bot commented Aug 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.87%. Comparing base (6e2d5d4) to head (d7c4376).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #645   +/-   ##
=======================================
  Coverage   88.87%   88.87%           
=======================================
  Files          55       55           
  Lines        5014     5014           
=======================================
  Hits         4456     4456           
  Misses        558      558           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@sshin23
sshin23 merged commit 20e07ce into master Aug 24, 2026
8 of 11 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.

1 participant