Repository navigation
Add updated maths and fitting tutorials to the documentation - #331
Open
markbujehein wants to merge 21 commits into
Open
markbujehein wants to merge 21 commits into
markbujehein wants to merge 21 commits into
Conversation
markbujehein
added this pull request to stack #332
October 14, 2026 12:55
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## add-maths-module #331 +/- ##
====================================================
+ Coverage 84.05% 84.07% +0.01%
====================================================
Files 64 64
Lines 5595 5595
====================================================
+ Hits 4703 4704 +1
+ Misses 892 891 -1
Flags with carried forward coverage won't be shown. Click here to find out more. |
Add docs/docs/tutorials/using-math.ipynb: a series of short examples of how maths with Parameter and DescriptorNumber works and how it is expected to behave. It covers the basic operators and the functions of es.math, together with the error cases, the limits of first-order propagation, and maths on the result of a fit.
Replace the single using-math tutorial with five short maths notebooks under tutorials/basics/ (arithmetic, exp/log, trigonometric, inverse trigonometric, hyperbolic) and add a small fitting introduction as a bridge to the fitting tutorials. As a trial, each notebook ends its parts with a few exercises whose hints and solutions are folded into <details> blocks, and charts use Plotly shown through an embedded iframe. Nothing is added to the dependencies or the shared docs configuration. Update the Tutorials nav (Basics > Maths, Fitting introduction) and the tutorials landing page.
Each Solution used to be a hand-pasted code block with a pasted "Expected result". It is now a small cell that runs the solution in a copy of the notebook namespace and shows the highlighted code and its output in a folded block, so the two cannot drift apart. The helper lives in the existing hidden cell, which now sits near the top so it is defined before the first exercise. Hints stay as folded markdown. Stored outputs are stripped from the six notebooks. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PHwoT3iPrULYWjTrLPuhan
Replay the six notebooks in-process and check that: - they hold no stored outputs, template delimiters or authoring leftovers, and that every exercise has givens, folded hints and a hidden solution cell; - the %%solution helper runs a solution in a copy of the namespace, escapes its output and raises its errors; - every solution prints the result of a closed-form reference (value, error, unit and bounds), including the fitted-line exercises. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PHwoT3iPrULYWjTrLPuhan
…certainty note - arithmetic: give variances as squared errors so code and text agree (0.2**2 + 0.02**2 = 0.0404 m**2), with units in every term - arithmetic: print results with f-strings, including variance and bounds - arithmetic: add a note that error and uncertainty are not always the same - other maths notebooks: write remaining raw variances as squared errors Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Hints use the `question` type and solutions the `example` type, so the two are visually distinct. They stay collapsible HTML `<details>` elements, which the Material theme styles by class. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Two special-edition maths notebooks: how the choice of formula changes the uncertainty of a result (the table-area example), and how correlation between measurements changes it. Includes exercises with executed solutions, tests, nav and index entries. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PHwoT3iPrULYWjTrLPuhan
Remove the Jupyter execution metadata and execution counts from the five older maths notebooks so test_no_execution_state_is_stored passes. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PHwoT3iPrULYWjTrLPuhan
…mples Add a "Good to know" section to the error-propagation notebook and a bullet to the correlation notebook. The cases are executed and print the exact result next to what the operators report: the same quantity reached by two routes, sin² + cos², the bounds of x - x, and the fit prediction without the covariance. Drop overly-strict test_no_execution_state_is_stored. Stored execution counts and timing metadata are written by normal local runs and do no harm, so the tutorial tests no longer require them to be stripped. Stored outputs are still rejected for specific tutorial paths.
The printouts of the limits of error propagation now label the two numbers "correct" and "EasyScience" instead of "exact" and "operators", and the surrounding text says "EasyScience" for the library's result. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…notebooks Add a Fitting group to the tutorials, with a hub page, the fitting introduction and three new notebooks that fit with model classes and units and derive quantities from the fit with es.math: SANS with a sphere, QENS with a Lorentzian, and a Bayesian QENS notebook that compares first-order uncertainties with the posterior. Add hub pages for Basics, Workshops & Schools and Advanced Topics, move the Bayesian analysis and Progress Callback notebooks into Advanced Topics, and list the categories on the tutorials page. The notebooks that download their data are read by the structure tests but are not replayed, so the unit tests need no network. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…s page The introduction now says who EasyScience is for, shows a first example with its output, and points to where to start. A new Concepts page in the user guide defines the numbers, uncertainties, bounds, units, models and fits that the tutorials rely on. The home page no longer promises terminology and workflow pages that the user guide does not have. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A group of two or more pages in the navigation should open with an index.md. The check warns about a group that does not, and never fails. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ing introduction into fitting/ The correlation and error propagation notebooks now say "standard uncertainty of ±0.02 m" instead of "known to 0.02 m", keep "error" for the `error` attribute and for the deviation of a reading from the true value, and say "EasyScience" instead of "the operators". The fitting introduction moves into the fitting/ folder with the other fitting notebooks; the navigation, the hubs and the tests follow. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Make the hints of the exercises less revealing, print the correlation of the posterior draws in the Bayesian notebook and refer to it from the QENS and SANS notes, ask the Bayesian exercise about a probability that is not 100 %, state when the convergence statistic is acceptable or strict, and call the resolution time the coherence time. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…have no uncertainty Bragg's law uses the Bragg angle, half the scattering angle, so the trigonometric notebooks now say so. "Known exactly" becomes "taken to have no uncertainty". Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ebooks The category headings of the tutorials page are now links to the hubs. The Fitting and Advanced Topics hubs point to each other's Bayesian notebook. The concepts page no longer calls a DescriptorNumber "named", and the introduction opens with the foundation role of EasyScience. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
markbujehein
force-pushed
the
add-maths-tutorials
branch
from
October 15, 2026 13:04
52f8aa5 to
fb4dc5e
Compare
rozyczko
requested changes
Oct 16, 2026
rozyczko
left a comment
Member
There was a problem hiding this comment.
- Putting tutorials in subdirectories broke the Google Colab button
The template builds the Colab URL frompage.nb_url.split('/')[-2]and[-1], i.e. it assumestutorials/<name>/<name>.ipynb. Withuse_directory_urlsthe new notebooks are published attutorials/basics/<name>/<name>.ipynb, so the generated link drops the basics/ or fitting/ segment.
Suggested fix (not tested): build the path from the page URL instead of from the last two path segments, e.g.
{% set filename = page.nb_url.split('/')[-1] %}
{% set colab_url =
base_colab_url ~ config.extra.vars.github_repository ~
"/blob/gh-pages/" ~ config.extra.vars.docs_version ~
"/" ~ page.url ~ filename
%}notebook-stripdoes not see the sub-folders
Inpixi.toml, tasknotebook-strip = 'nbstripout docs/docs/tutorials/*.ipynb'.
Thenotebook-preparestep that bothdocs.ymlandtutorial-tests.ymlrun before
executing notebooks only strips the top-level folder.notebook-exec,notebook-testsandnbqa ruffall take the directory and are recursive, so nothing currently breaks. But the first time someone commits a nested notebook with outputs, the docs build will render stale outputs instead of new ones. Make the glob recursive (e.g.nbstripout $(git ls-files 'docs/docs/tutorials/**/*.ipynb')or a
find … -exec), and consider the same for the commented-outnotebook-convert/-tweak.
This branch has not been deployed
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.
Summary
This PR adds a new, learner-friendly tutorial series to the EasyScience documentation, with a clearer path for new users:
It also updates the docs landing pages and introduction to direct users into the new tutorial structure.
Why
The current docs were missing a structured onboarding path for users who want to learn EasyScience, so while adding tutorial for the maths module, I'm trying out something that seems more user friendly. These notebooks provide:
What changed
Basicstutorial section:Fittingtutorial section:Advanced Topics: