An inference can fail before an algorithm does: a residual can mix units, a derivative can belong to the wrong map, or a likelihood can omit the calibration that correlates two measurements. Foundations keeps those connections visible.
These are optional connected routes, not prerequisites to complete in order.
Researchers often encounter calculus, statistics, linear algebra, programming, physical modeling, and inference separately. The trouble appears when one measurement must carry all of them at once: a source produces an observable, an instrument calibrates and records it, an inference assigns responsibility for a discrepancy, and a program reports a derivative. Reconnecting those steps is part of the scientific work.
You may proceed linearly through the recommended route below or enter from any method page. Return when an audit exposes a conceptual gap, then rejoin the method or workflow that raised the question. Foundations connects mathematical objects, executable programs, and warranted scientific claims.
Connect functions, units, scales, vectors, derivatives, probability, and uncertainty before choosing a numerical representation.
Connect physical prediction, measurement, inference, sensitivity, conditioning, identifiability, and the finite JAX program.
Running case: a two-channel measurement¶
A source is measured in two channels. The channels share a calibration uncertainty, and two source parameters can produce nearly the same change in the recorded data. This small problem is enough to expose the decisions that usually become hidden inside a scientific program: units, covariance, rank, priors, model discrepancy, and derivative meaning.
Figure 1:Two channels see one source through different measurement paths. A shared calibration can correlate the recorded values, while a long uncertainty region marks a parameter combination the data weakly distinguish.
Run the companion calculation from the repository root:
env -u VIRTUAL_ENV uv run --no-sync python \
examples/onboarding/two_channel_measurement.py --calibration-sigma 0.2 --separation 0.01Change --calibration-sigma to alter the shared covariance and --separation
to bring the two Jacobian columns together. The calculation prints the
covariance, singular values, and the narrower claim each configuration supports.
| Family | Status | Primary role |
|---|---|---|
| Mathematical objects | Current guidance | Name domains, scales, structures, and uncertainty |
| Models and computation | Current guidance | Separate scientific relations from executable programs |
Recommended route through the foundations¶
For a first pass, follow the measurement from its physical relation to the claim made about it. This is a route through one argument, not a prerequisite chain.
| Step | Question answered | Page |
|---|---|---|
| 1 | What map, units, and scale are being represented? | Functions, units, and scales |
| 2 | Which directions of change are visible or hidden? | Linear algebra as the language of change |
| 3 | Which local change is meant by a derivative? | What is a derivative? |
| 4 | What variation and support does the uncertainty model admit? | Probability and distributions |
| 5 | Which kind of model is answering the question? | What is a model? |
| 6 | How do parameters become recorded data and a conditional conclusion? | Models, inference, and information |
| 7 | Is a sensitive or weakly constrained direction numerical, physical, or both? | Sensitivity, conditioning, and identifiability |
| 8 | Which map and derivative does the finite JAX program actually expose? | From mathematical relations to differentiable programs |
Mathematical objects¶
Begin with the objects that scientific programs represent and transform:
Functions, units, and scales treats a function as a unit-carrying map with a domain, scale, and limiting behavior.
Linear algebra as the language of change connects vectors and matrices to perturbations, maps, geometry, and conditioning.
What is a derivative? develops derivatives as local rates, linear maps, sensitivities, and evidence-bearing claims.
Probability and distributions introduces support, density, normalization, expectation, covariance, and uncertainty.
Models and computation¶
Then connect those objects to scientific reasoning and executable methods:
What is a model? separates conceptual, mathematical, computational, statistical, generative, and surrogate models.
Models, inference, and information follows the chain from a physical prediction through a measurement model to inference.
Sensitivity, conditioning, and identifiability distinguishes response, numerical stability, and learnable parameter combinations.
From mathematical relations to differentiable programs separates an ideal relation from the finite JAX program that executes it.
Why the documentation repeats one scientific cycle¶
Every substantial route uses the same sequence:
predict -> compute -> audit -> state the warranted claimPrediction records units, signs, scales, limiting cases, invariants, conditioning, expected failures, and the intended derivative before output can encourage post-hoc storytelling. Computation records the program that actually ran, including branches, finite precision, tolerances, traces, and provenance. Audit asks an independent question through an analytic identity, limit, finite-difference check, convergence study, conservation law, or source check.
The warranted claim is the scientific product. “The code ran” is weaker than “the value satisfies the stated numerical contract,” which is weaker than a claim that a physical model adequately describes an observation.
Connected routes, not duplicate explanations¶
Foundations asks what an idea means and how it connects to scientific reasoning. The Numerical methods chapters explain how numerical methods work and where their algorithmic boundaries lie. The API reference records exact public surfaces. The Validation links claims to executable evidence.
These routes are complementary. Use Choose your foundations path to locate a concept by the problem you are facing, or Ways to use these docs to choose a route through the site. After an audit, begin the cycle again with a better prediction, method, or claim.