docs: migrate ExaModels examples to the add_var/add_obj/add_con API - #645
Merged
Conversation
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 Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
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.
Problem
The docs build fails on
master(example run).ExaModels v0.12.0 removed the legacy
variable,objectiveandconstraintentry points, so every@exampleblock that builds a model dies with: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, ...), andmakedocsthen terminates withencountered 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.0following a comma parses as a positional argument rather than a keyword, so the model builds fine and the bound is silently dropped (lvarstays at-Inf). The first draft of this change had exactly that bug and it was caught only by asserting onget_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
variablestill 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_modelinFloat64andFloat32, andelec_model(10).masterfails at extraction; droppinglvar/uvarfrom one@add_varmakes the comparison go red — so the check is capable of failing.gpu.mdwas additionally run with a realCUDABackend():x0is aCuArrayas 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.