Skip to content

Add updated maths and fitting tutorials to the documentation - #331

Open
markbujehein wants to merge 21 commits into
add-maths-modulefrom
add-maths-tutorials
Open

markbujehein wants to merge 21 commits into
add-maths-modulefrom
add-maths-tutorials

Conversation

@markbujehein

Copy link
Copy Markdown
Collaborator

Summary

This PR adds a new, learner-friendly tutorial series to the EasyScience documentation, with a clearer path for new users:

  • Basics: working with numbers that carry units, uncertainties, and bounds
  • Maths functions: arithmetic, error propagation, trig and inverse trig, exp/log, hyperbolic functions, and correlation
  • Fitting: fitting workflows and derived quantities from fitted parameters
  • Advanced topics: Bayesian analysis and posterior-based workflows

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:

  • clear examples of EasyScience applied on various problems
  • inspired by the DMSC 2026 summer school notebooks, exercises with hints & solutions to reinforce learning
  • worked explanations of uncertainty propagation and parameter behaviour
  • a natural progression from basics to fitting and Bayesian analysis

What changed

  • Added a new Basics tutorial section:
    • arithmetic
    • error propagation (with edge cases)
    • trigonometric functions
    • inverse trigonometric functions
    • exponential/logarithm functions
    • hyperbolic functions
    • correlation (with edge cases)
  • Added a Fitting tutorial section:
    • fitting introduction
    • SANS sphere example (ported from Workshops & schools)
    • QENS Lorentzian example (ported from Workshops & schools)
  • Added Advanced Topics:
    • Bayesian analysis
    • Bayesian QENS
  • Updated the docs homepage and introduction page to point new users toward:
    • Installation & Setup
    • Basics tutorials
    • Fitting tutorials
    • Workshops & schools

@markbujehein
markbujehein added this pull request to stack #332 October 14, 2026 12:55
@markbujehein markbujehein added [scope] documentation Documentation only changes (major.minor.patch.POST) [priority] medium Normal/default priority labels Oct 14, 2026
@codecov

codecov Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.07%. Comparing base (db1f696) to head (fb4dc5e).

Additional details and impacted files

Impacted file tree graph

@@                 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     
Flag Coverage Δ
unittests 84.07% <ø> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

markbujehein and others added 21 commits October 15, 2026 15:03
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>

@rozyczko rozyczko left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Putting tutorials in subdirectories broke the Google Colab button
    The template builds the Colab URL from page.nb_url.split('/')[-2] and [-1], i.e. it assumes tutorials/<name>/<name>.ipynb. With use_directory_urls the new notebooks are published at tutorials/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
%}
  1. notebook-strip does not see the sub-folders
    In pixi.toml, task notebook-strip = 'nbstripout docs/docs/tutorials/*.ipynb'.
    The notebook-prepare step that both docs.yml and tutorial-tests.yml run before
    executing notebooks only strips the top-level folder. notebook-exec, notebook-tests and nbqa ruff all 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-out notebook-convert/-tweak.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[priority] medium Normal/default priority [scope] documentation Documentation only changes (major.minor.patch.POST)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants