docs(internals): a contributor walkthrough of the main operations - #101
Merged
Merged
Conversation
Nothing in docs/ explained how the package works internally — every page is written for a user of the API, and a new contributor asking what happens to field data across a regrid had nowhere to go but the source. Ten sections, one per main operation: apply!, adjoints and the five traits, the solver boundary, linearize, forest topology, block field layouts, the forest exchange, regrid!, multigrid, distributed. Each gives the entry point, a call diagram, a type trace naming the concrete type at every step, step commentary, and a table of what it throws and what it invalidates. Closes with the obligations the type system cannot enforce, each paired with the test that catches you. Split the issue's forest section into topology and regrid so neither carries two stories, and placed linearize next to adjoints since it is a single-grid operator wrapper, not part of the forest cluster. Every block is a static fence: rendering the book runs the full test suite via pages/coverage.qmd. Closes #98 Agent-Harness: claude-code 2.1.268 Agent-Model: claude-opus-5[1m] Agent-Review: unreviewed Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Benchmark ResultsTime
Memory and allocations
Benchmark PlotsA plot of the benchmark results have been uploaded as an artifact to the workflow run for this PR. |
Agent-Harness: codex-cli unknown Agent-Model: gpt-6-astra Agent-Review: unreviewed
|
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
1 participant
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.
Closes #98.
Adds
docs/pages/internals.qmd, the page a new contributor needs and the repo did not have. Every existing page is written for a user of the API —amr.qmdexplains whatregrid!means semantically but never mentionsLeafKey,forest.index, or the generation counter.DESIGN.mdis the record of decisions and rationale, and shouldn't become a walkthrough of control flow. There is noCONTRIBUTING.md, so this is now the contributor entry point.Ten sections, one per main operation. Each gives the entry point, an ASCII call diagram, a type trace naming the concrete type at every step with allocations and mutations marked, step-by-step commentary, and a table of what it throws and what it invalidates:
apply!on one grid · adjoints and the five traits · the solver boundary ·linearize· forest topology · block field layouts · the forest exchange ·regrid!· multigrid · distributed.Two departures from the issue's outline, both to cut forward references. The issue's forest section splits into topology (§5) and regrid (§8) so neither carries two unrelated stories, and so the flagship
regrid!walkthrough has zero forward references. Andlinearizemoves up to §4, next to adjoints:LinearizedOptakes aFieldand multigrid and distributed areCartesianGrid-only, so none of them depend on the forest cluster at all. Four forward references remain, each one sentence, each pointing into the forest cluster.The page closes with
## Rules for changing this code— eight obligations the type system cannot enforce, each paired with the test that catches you if you skip it.Conventions
quarto render docsruns the full test suite viapages/coverage.qmd, so nothing on this page executes. Verified the page renders standalone outside the project.api.qmdonce, on first mention; everything else is bare.api.qmditeratesnames(MatrixFreeOperators), so non-exported names —LeafKey,Forest,ExchangeSchedule,MGLevel,PreparedComposed,BlocksLayout— have no anchor to point at. All 31 links check out against the export block.grep.toc: true,toc-depth: 2— the second reference-shaped page on the site after the generatedapi.qmd, and the only one you jump into rather than read through.It is ~1400 lines against 134–312 for the narrative pages. That is deliberate for a reference page, and the TOC plus the uniform section template is what keeps it navigable.
Checks run
src/orext/(the two misses were the prose words "Pkg" and "grep").api.qmdlinks point at exported symbols; no duplicates.x̄/ȳ..qmdlink target exists,pages/api.qmdstill alone underpart: "API".regrid!sequence, the singlegenerationbump site,halo_update!being a literal identity off a forest, "Martin–Cartwright" as the real name inschedule.jl, and that_build_coarsestis the only matrix assembly insrc/.Also adds one sentence linking the page from
docs/index.qmd's Overview, and the sidebar entry last inpart: "Docs".🤖 Beep boop — Claude wrote this one after reading the same call graphs one time too many.
Agent-Harness: claude-code 2.1.268
Agent-Model: claude-opus-5[1m]
Agent-Review: unreviewed