Rewrite tutorial chapter introductions for clarity and pedagogy - #17
Merged
Merged
Conversation
Rewrite the discretization chapter to match the revised chapters 00-01: numbered sections, gentler one-idea-per-cell prose, short commented code cells in place of long multi-step blocks, inline and end-of-chapter checkpoints, and a new hands-on condition-number section. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the least-squares chapter to match chapters 00-01: numbered sections, gentler derivations with every symbol explained, and the shared megathrust scenario built in short narrated steps instead of one 49-line setup cell. The synthetic data now come from fault.greens_matrix directly rather than a placeholder dataset, with identical numerical results. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the regularization chapter to match chapters 00-01: numbered sections building from 'what to penalize' through the three strength- selection criteria, gentler intuition for ABIC and the L-curve, and the shared scenario built in short narrated cells. The strength sweep and the three-criteria comparison are split into paired slip/error figures rather than one 30-plus-line cell. The damping-versus-smoothing demo now runs at a strength where the two priors visibly disagree, with prose matched to the actual numbers. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the joint-inversion chapter to match chapters 00-01: numbered sections, a plain-language contrast of GNSS and InSAR sampling, and the line-of-sight projection built by hand from an explicit dot product instead of a hidden greens.matrix call, so the beginner sees where the single radar number comes from. Split the four-panel comparison into paired slip/error figures. Fix the per-dataset diagnostic print, which multiplied the dimensionless weighted RMS by 1000 and mislabeled it as millimeters; it now reports the RMS residual in meters converted to mm. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the correlated-noise chapter to match chapters 00-01: numbered sections, plain-language motivation for spatial correlation, and short narrated cells that build the covariance, draw one correlated noise field, and compute the effective number of independent pixels. Reframe the uncertainty comparison around the over-confidence ratio and note explicitly that the large absolute uncertainties come from a single InSAR look direction (per chapter 05), so the diagonal-versus-full contrast is the actual lesson. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the bounds-and-constraints chapter to match chapters 00-01: numbered sections contrasting hard constraints with soft penalties, short narrated cells for NNLS, a deliberately-wrong upper bound, and the fixed-rake basis, and prose that ties each result to the reduced chi-squared so the beginner sees when a constraint helps and when it biases. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the uncertainty-and-resolution chapter to match chapters 00-01: numbered sections separating the repeatability and fidelity questions, short narrated cells, and a new section that pulls out one full row of the resolution matrix and maps it as an averaging kernel, making spatial leakage concrete beyond the diagonal. Prose flags throughout that these uncertainties are conditional on the model setup. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the nonlinear-geometry chapter to match the earlier chapters: narrative intro with 'by the end' objectives, numbered sections that build the linear-versus-nonlinear distinction and variable projection in plain language, and the shared scenario in short narrated cells (dropping the autoreload magic and the placeholder-dataset greens call in favor of fault.greens_matrix). Adds an inline checkpoint on grid-search cost and expands the trade-off-valley discussion. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the gradient-geometry chapter to match the earlier chapters: narrative intro, a plain-language account of what automatic differentiation does and does not remove, and the shared scenario in short narrated cells. Fixes the draft's copy-paste self-references (prose that pointed at 'notebook 10' when it meant chapter 09) and expands the Gauss-Newton error-bar caveats into their own section. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the triangular-fault chapter to match the earlier chapters: narrative intro, numbered sections motivating triangles and stressing that only the dislocation kernel changes, and the mesh construction split into separate nodes, connectivity, build, and plot cells with comments on the depth-sign convention. The slip setup and solve are likewise narrated step by step. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the interseismic-coupling chapter to match the earlier chapters: narrative intro, numbered sections that build the arctangent profile, the backslip trick, and the sign convention in plain language, and the former 42-line cell split into narrated steps for the fault, the true coupling, the synthetic velocities, the solve, and the coupling/moment-deficit outputs. Adds a reference-frame section and an inline checkpoint on area-weighting. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the model-misspecification chapter to match the earlier chapters: narrative intro, a precision-versus-accuracy framing with a dartboard analogy, and the former 41-line setup split into narrated cells for the two faults, the true slip, the data, and the two solves. Replaces the fragile 'ax is not axes[2]' plotting conditional with an explicit (fault, field, title) loop. Changes the demonstration dip error from 45 to 30 degrees so the reduced chi-squared rises only modestly (about 1 to 3.6) instead of blowing up to 44; that makes the teaching point honest, a wrong model that stays merely mediocre in fit while biasing slip roughly four formal sigma, and every number and residual-pattern description now matches the executed output. Exercises keep the same tasks so the worked solutions still apply.
Rewrite the Bayesian chapter to match the earlier chapters: narrative intro, numbered sections that build the likelihood/prior/posterior picture, explain why sampling is needed, and connect back to regularization. The former 80-line sampling monolith is split into seven short, commented cells, setup, deterministic baseline, posterior construction, warmup, chain running, diagnostics, and the two result plots, each narrated so R-hat, ESS, and divergences have visible origins. Adds an inline checkpoint on why multiple chains are required. Exercises keep the same tasks so the worked solutions still apply.
blackjax's window_adaptation forwards unknown keyword arguments to the algorithm kernel via **extra_parameters. Passing progress_bar=False therefore reached blackjax.nuts.build_kernel, which does not accept it, raising a TypeError at sampling time. Progress bars are off by default, so the argument was redundant; removing it restores geodef.bayes.sample under the resolved blackjax while leaving behavior unchanged on versions that did accept it.
…ooks-expansion-yutuo4
Remove the transitional top-level aliases (lcurve, abic_curve, model_covariance, LinearSystem, stack_obs, spatial_covariance, moment_to_magnitude, and friends) from geodef/__init__.py so the public top level matches the documented beginner vocabulary. Every expert name is now reached only through its module path. The tutorial notebooks and their solutions already use the module paths; this migrates the remaining code and docs (tests/test_conventions.py, docs/data.md, docs/fault.md) and flips tests/test_public_api.py from asserting the aliases are importable to asserting they are no longer top-level. Drops the now-empty 'Transitional top-level aliases' section from docs/api_stability.md and its consistency test. Marks A8 shipped in PLAN.md and plans/ARCHITECTURE.md and updates the tutorials/OUTLINE.md API-policy note. Lands as one commit so the tutorial suite and the public-API contract stay green together, per the roadmap 2.2 gate for a public v0.2 tag.
ericlindsey
force-pushed
the
claude/tutorial-notebooks-expansion-yutuo4
branch
from
July 20, 2026 16:24
626dc5d to
5e22d2a
Compare
The A8 export-trim migration lengthened geodef.LinearSystem to geodef.invert.LinearSystem, pushing the call past the 88-column limit. Wrap the invert(...) call across lines so ruff check and ruff format pass.
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.
Summary
This PR rewrites the introductory sections of all fourteen tutorial chapters to improve clarity, pedagogical flow, and consistency. The changes focus on the opening narrative, learning objectives, and prerequisites—the parts that set reader expectations and frame the material.
Key Changes
Narrative and motivation:
Learning objectives:
Prerequisites and conventions:
Specific chapter improvements:
Implementation Details
This rewrite improves the tutorial's usability as a teaching resource while maintaining technical accuracy and depth.
https://claude.ai/code/session_01GUa9C14nu8TEuX75v57Cai