Review fixes for driven solver documentation#762
Merged
hughcars merged 3 commits intoJun 16, 2026
Conversation
* docs/src/examples/tutorial_driven_uniform_v_adaptive.md
- Quick-start: rephrase the adaptive-solver introduction to flag it as
a source of approximation error rather than just a setup cost.
- Quick-start: switch the tolerance bullet to the standard
`["Solver"]["Linear"]["Tol"]` nested-config notation, both in the
bullet list and again in the 'Numerical problems' challenge.
- Quick-start: re-target the broken
`cpw_lumped_uniform_convergence.json` link to the file that is
actually used by the tutorial, `cpw_tutorial_lumped_uniform.json`.
- Quick-start: 'examples (CPWs and the single transmon)' for clarity.
- Uniform solver: drop the redundant 'very' before 'poorly conditioned',
and link to the `Samples` anchor with the right pluralisation.
- Adaptive solver: change "internal" frequency grid to *internal* so
it reads as emphasis (consistent with the rest of the page).
- Projective construction: render `Re(x*)`, `Im(x*)` with explicit
parentheses, and italicise *internal* in the same paragraph.
- Choosing internal samples: 'does not explain how' (was 'tell us'),
and soften 'is familiar' to 'may be familiar'.
- Adaptive solver problems: re-flow 'Early termination' and
'Numerical problems' as a numbered list so the bold labels render and
the structure is obvious. (Previously the bolds collapsed into prose
on the rendered preview, see PR704 preview build.)
- User guidance: 'efficiently choose samples based on the observed
approximation error', drop the now-unused 'computer' before 'memory',
and call out 'linear solver tolerance' alongside adaptive tolerance
in the validation paragraph.
- Transmon set-up: switch all `\\textrm` units to `\\mathrm` for
consistency with the rest of the docs (`nH`, `fF`, two `GHz`).
- Transmon set-up: typo `\\Ohm` -> `\\Omega`.
- Transmon Part II: 'behavior' (was 'behaviour'), to keep with US
spelling already used elsewhere.
- References: hyperlink the four DOIs.
- Add a maintainer note (HTML comment, invisible to readers) at the top
of the file documenting that the SVGs are committed snapshots, not
auto-generated, and giving the regeneration recipe. Auto-generation is
not feasible: each Palace run takes hours, so neither CI long-tests
nor docs build-time hooks can absorb the cost. We accept that the
plots may drift relative to the current solver; refresh by hand if a
change meaningfully alters the qualitative shape of these curves.
* examples/cpw/cpw_tutorial_lumped_driven.jl
- Replace the commented-out uniform-sweep block with a kwarg-style
extension: `adaptive_tols` now starts with `0.0`, which Palace
treats as the uniform driven solver, and is written to
`postpro/tutorial_driven_rom/driven_uniform_reference`. This is
the directory the plotting scripts already expect, so the script
now generates the full set of tutorial data in a single invocation.
* CHANGELOG.md
- Add an 'In progress' entry under 'New Features' announcing the new
'Driven Solver: Uniform vs Adaptive' tutorial.
The Python plot scripts are not touched in this commit; they will be
replaced by the Julia/Makie ports in a follow-up PR.
Signed-off-by: Hugh Carson <hughcars@amazon.com>
Replaces the two Python plotting scripts with Julia/CairoMakie ports so
the data generation (`*_tutorial_driven.jl`) and the result plots are
both in the same language, dropping the language split flagged in the
PR review.
* examples/cpw/cpw_tutorial_lumped_driven_plots.jl (new)
* examples/transmon/transmon_tutorial_driven_plots.jl (new)
- Reproduce the matplotlib plots: matplotlib `plasma` palette sampled
over [0.1, 0.9], serif (Times) typography, two-line titles, dashed
tolerance bands, dotted 1e-12 reference floor, diamond markers for
the adaptive sample frequencies, and the gray-star initialization
points on the convergence curve.
- Use CairoMakie + ColorSchemes + CSV + DataFrames; no native deps
beyond what `Plots` already pulled in.
- Equation labels in titles and the per-axis `S_{ij}` annotations are
rendered as `LaTeXString`s via MathTeXEngine. The descriptive
line of two-line titles uses a plain string in a separate Label
(LaTeX line breaks `\\\\` are not supported by MathTeXEngine).
- Both scripts accept `--out <dir>` to override the default
`docs/src/assets/examples` output, useful for previewing.
* examples/cpw/cpw_tutorial_lumped_driven_plots.py (deleted)
* examples/transmon/transmon_tutorial_driven_plots.py (deleted)
* examples/Project.toml
- Add ColorSchemes (used directly by the new plotting scripts; was
already an indirect dependency through CairoMakie).
* docs/src/assets/examples/driven_ua_*.svg
- Regenerate all 11 SVGs from the same simulation outputs using the
new Julia plotters. The files in this commit are visually equivalent
to the matplotlib originals (same data, same palette, same axis
limits and tick spacings).
* docs/src/examples/tutorial_driven_uniform_v_adaptive.md
- Update the maintainer note and the in-page `!!! note` block to
reference the `.jl` plot scripts instead of the now-deleted
`.py` scripts.
Signed-off-by: Hugh Carson <hughcars@amazon.com>
hughcars
force-pushed
the
phdum/driven_solver_docs
branch
from
15a6d45 to
236fe0a
Compare
hughcars
force-pushed
the
hughcars/driven_solver_docs_review_fixes
branch
from
b1419bf to
8ee73df
Compare
hughcars
force-pushed
the
hughcars/driven_solver_docs_review_fixes
branch
from
8ee73df to
85bc89f
Compare
hughcars
added
the
no-long-tests
Sbozzolo
approved these changes
Jun 15, 2026
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
2 participants
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.
Builds on #702 and addresses the review feedback there without changing the original PR branch directly.
Summary:
docs/src/features/adaptive_driven_solver.md.docs/src/reference.md.Validation:
julia --project=docs docs/make.jlIf this looks good, I plan to merge this into
phdum/driven_solver_docs, then continue with the original PR #702.