HowToFit

Start Here on Colab | Installation Guide | PyAutoFit readthedocs | Browse Chapter 1 With Images | autofit_workspace

Welcome to HowToFit, the tutorial lecture series for PyAutoFit, an open-source framework for scientific inference.

PyAutoFit is designed so scientists can bring their models, data and likelihood code, then fit models, explore results and develop analyses using natural language with an AI coding agent. HowToFit teaches the core principles behind this workflow, so you understand the inference being performed rather than treating it as a black box.

The tutorials assume minimal prior knowledge of statistics and begin from first principles: models, priors, likelihood functions and non-linear searches. They then progress to model comparison, graphical models and hierarchical inference across large datasets.

With these foundations in place, PyAutoFit can be used through its natural-language workflow to compose models, choose searches, perform inference and interpret results conversationally.

For experienced scientists who already know these concepts, the natural-language inference page may be the better starting point: it walks a complete fit through PyAutoFit as a conversation with an AI coding agent, assuming the principles taught in HowToFit as background.

Chapters

• chapter_1_introduction — Models, likelihoods, non-linear searches, why modeling is hard, and how to interpret the results of a fit, ending with a short guide to building a scientific workflow.
• chapter_advanced — Fitting many datasets simultaneously with graphical models, hierarchical models, and Expectation Propagation.

Each chapter is a folder of numbered tutorial files — tutorial_<M>_<topic>.py (Python script) or the matching .ipynb in notebooks/. Tutorials build on each other within a chapter and assume you have completed the earlier ones.

Getting Started

Study with the assistant

Use the Jupyter notebooks if you want to run the code (recommended), or read the available Markdown lectures directly on GitHub.

For help alongside the lectures, open the autofit_assistant repository in your AI coding agent, following its setup instructions, and paste:

Enter HowToFit mode.

I want to work through the HowToFit lectures. Show me where to find them
and how to use Jupyter Notebook or Markdown, then help me with questions
as I go.

The assistant will answer questions about concepts, equations, code and results as you study, and help with notebook errors. Share the lecture link and section or the cell you are working on; you choose when to move on.

Run in Google Colab (nothing to install)

Every tutorial opens in Google Colab in one click. There is nothing to install and no local Python environment to set up — PyAutoFit installs itself in the notebook's first cell. In Colab you run the tutorial: edit the code, change the model, and see the output for yourself.

Whilst in Colab, we recommend opening Gemini — the button at the bottom of the notebook — and using it as a study assistant alongside the lecture. It can see the notebook you have open, so you can ask it to explain an equation, unpack what a cell is doing, or interpret the output of a fit, without leaving the tutorial.

The markdown links are the same tutorial already executed and rendered on GitHub, with its real output figures inline. Nothing runs and nothing installs — you just read it. They are good for skimming a tutorial before running it, or for reading on a phone. Markdown pages currently exist only for the chapter 1 tutorials listed with a markdown link below; every other tutorial is Colab-only.

Start Here — a one-page overview of the whole series.

• Chapter 1: Introduction — Models, likelihoods, non-linear searches, why modeling is hard, and how to interpret the results of a fit, ending with a short guide to building a scientific workflow.
  • Start Here: HowToFit Lectures — (Colab / markdown)
  • Tutorial 1: Models — (Colab / markdown)
  • Tutorial 2: Fitting Data — (Colab / markdown)
  • Tutorial 3: Non Linear Search — (Colab / markdown)
  • Tutorial 4: Why Modeling Is Hard — (Colab / markdown)
  • Tutorial 5: Results and Samples — (Colab / markdown)
  • Tutorial 6: Gradients — (Colab)
  • Tutorial 7: The Details — (Colab)
  • Tutorial 8: Scientific Workflow — (Colab / markdown)
  • Tutorial Optional: Bayesian Formalism — (Colab)
• Advanced Chapter: Graphical & Hierarchical Models — Fitting many datasets simultaneously with graphical models, hierarchical models, and Expectation Propagation.
  • Tutorial 1: Individual Models — (Colab)
  • Tutorial 2: Graphical Model — (Colab)
  • Tutorial 3: Graphical Benefits — (Colab)
  • Tutorial 4: Hierarchical Models — (Colab)
  • Tutorial 5: Expectation Propagation — (Colab)
  • Tutorial Optional: Hierarchical Expectation Propagation — (Colab)
  • Tutorial Optional: Hierarchical Individual — (Colab)

Model-fits run considerably faster on a GPU. In Colab, enable one via Runtime → Change runtime type → Hardware accelerator before running a notebook.

Run on your own machine

Follow the PyAutoFit installation guide, then clone this repository:

git clone https://github.com/PyAutoLabs/HowToFit.git
cd HowToFit

The tutorials are distributed as both Jupyter notebooks (notebooks/) and Python scripts (scripts/). We recommend the notebooks for reading — figures render inline, and you can step through small code blocks interactively. Use the Python scripts for actual PyAutoFit use.

Before Chapter 1

Before starting chapter 1, open start_here.py for a one-page overview of the series, then begin scripts/chapter_1_introduction/tutorial_1_models.py.

Repository Structure

• scripts/ — Runnable Python tutorial scripts, one subfolder per chapter.
• notebooks/ — Jupyter notebook versions of the scripts (auto-generated; see below).
• config/ — PyAutoFit configuration YAML files used by the tutorials.
• dataset/ — Tutorial 1D datasets are generated at runtime by scripts/simulators/simulators.py — no data files are committed.
• output/ — Model-fit results (generated at runtime, not committed).

Notebooks vs Scripts

Notebooks in notebooks/ are generated from the Python files in scripts/. Always edit the .py scripts, never the notebooks directly. The # %% markers in each script alternate between code and markdown cells, which PyAutoHands uses to produce the .ipynb files.

Relationship to autofit_workspace

autofit_workspace is the main user-facing workspace for PyAutoFit — concise examples, cookbooks, and search templates aimed at users who already understand probabilistic modeling. HowToFit is the teaching companion. Tutorials in chapters 1 and 3 reference autofit_workspace scripts as the next place to go after the relevant concept has been introduced.

Citations

If you use HowToFit or PyAutoFit in your research, please cite the references listed in CITATIONS.rst.

Community & Support

Support for PyAutoFit is available via our Slack workspace. Slack is invitation-only; send an email if you'd like an invite.

For installation issues, bug reports, or feature requests, raise an issue on the PyAutoFit GitHub issues page (for library issues) or the HowToFit GitHub issues page (for tutorial content issues).