docs: auto-generated symbol → parameter-string reference page#5508
Draft
rtimms wants to merge 4 commits into
Draft
docs: auto-generated symbol → parameter-string reference page#5508rtimms wants to merge 4 commits into
rtimms wants to merge 4 commits into
Conversation
Adds a Sphinx extension that walks each parameter class in src/pybamm/parameters/ on every docs build and writes docs/source/api/parameters/symbol_reference.rst — a single page mapping every Python-side shorthand (e.g. param.kappa_e, param.n.prim.D) to its underlying ParameterValues string (e.g. "Electrolyte conductivity [S.m-1]"). The output is regenerated each build and gitignored, so new parameters and renames are picked up automatically with no manual step. Covers LithiumIonParameters, LeadAcidParameters, GeometricParameters, ElectricalParameters, ThermalParameters and EcmParameters, including nested domain (.n/.s/.p) and phase (.prim/.sec) sub-objects, plus FunctionParameter-returning methods called with placeholder Variables.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #5508 +/- ##
==========================================
+ Coverage 98.09% 98.18% +0.09%
==========================================
Files 338 338
Lines 31246 31246
==========================================
+ Hits 30650 30679 +29
+ Misses 596 567 -29 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Three follow-ups to the symbol-reference page:
- Derived rows now render the actual expression (e.g.
`param.A_cc → "Electrode width [m] * Electrode height [m] * Number of
electrodes connected in parallel to make a cell"`) instead of a flat
list of constituent parameter strings, which was useless on its own.
Long expressions (e.g. ocv_init) are shown in full since they are
still grep-able and the cells scroll.
- Float literals that are exact reciprocals of small integers are
rewritten symbolically (e.g. `0.0002777777777777778` →
`(1/3600)`), so seconds-to-hours conversions and similar unit
factors print as fractions rather than precomputed floats.
- The brittle placeholder dictionary mapping arg names to
pybamm.Variable instances is gone. `_call_method` now passes
`pybamm.Variable(arg_name)` for every positional arg and falls back
to defaults or 0 only if the call raises. New methods need no
maintenance.
- Added a "Domain and phase sub-objects" section explaining that
`.n` / `.s` / `.p` are electrode/separator sub-objects, `.prim` /
`.sec` are particle-phase sub-objects, and the underlying
parameter string gains a "Primary:" / "Secondary:" prefix when
used with a composite ("particle phases": "2") electrode.
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.
Summary
Adds a single page that maps every Python-side parameter shorthand (e.g.
param.kappa_e,param.n.prim.D,param.j0_Li_metal) to the underlying string used inpybamm.ParameterValues(e.g.\"Electrolyte conductivity [S.m-1]\"). Currently this mapping is only discoverable by readingsrc/pybamm/parameters/lithium_ion_parameters.py(and friends) directly, which is awkward when reading model code or implementing a new submodel.The page is regenerated on every Sphinx build by a new extension at
docs/sphinxext/generate_symbol_reference.py, so renaming a shorthand or adding a newFunctionParameterautomatically updates the docs — no manual step, no checked-in artefact.Covers:
LithiumIonParameters,LeadAcidParameters,GeometricParameters,ElectricalParameters,ThermalParameters,EcmParameters.n/.s/.p) and phase (.prim/.sec) sub-objectsFunctionParameter(called with placeholderVariables to discover the underlying string)param.A_cc,param.chi) — listed with the constituent parameter strings they depend onHow it works
generate_symbol_reference.pyis a Sphinx extension wired intodocs/conf.py. On thebuilder-initedevent it walks each parameter class's attribute graph, calls anyFunctionParameter-returning methods withpybamm.Variableplaceholders, and writesdocs/source/api/parameters/symbol_reference.rst. The output is added to.gitignoreand the existingdocs/source/api/parameters/index.rsttoctree.Test plan
cd docs && make htmlbuilds without warningsdocs/_build/html/api/parameters/symbol_reference.htmlrenders one section per parameter class with grouped tablesparam.kappa_e(c_e, T)→\"Electrolyte conductivity [S.m-1]\",param.n.prim.D(c_s, T)→\"Negative particle diffusivity [m2.s-1]\", etc.src/pybamm/parameters/*.py, the next docs build picks it up automatically.🤖 Generated with Claude Code