Troubleshooting

Livebook cannot find the local package

The notebook setup cell uses:

Mix.install([
  {:micrograd_ex, path: ".."}
])

That assumes the notebook is at notebooks/micrograd_demo.livemd. If you move the notebook, update the path.

Dependency installation fails

Restart the Livebook runtime and run the setup cell again. The visualization dependencies are notebook-local. Do not add Kino or Vega-Lite to the core application unless you intentionally need them outside notebooks.

If you update dependency versions, run the notebook top-to-bottom afterward.

The notebook is slow

MicrogradEx is scalar educational autodiff. It is intentionally much slower than tensor libraries. For faster experiments:

reduce n_samples;
reduce hidden width;
reduce steps;
increase decision-boundary h.

In notebooks/micrograd_extras.livemd, prefer [8, 8, 1] while experimenting. Move to [32, 32, 1] only after the smaller runs behave as expected.

The decision boundary is slow

The decision boundary evaluates the trained scalar model at every grid point. Smaller h values create many more forward passes.

Use a coarser grid:

PlotData.decision_boundary(model, dataset, h: 0.35)

Avoid very small h values in the extras notebook unless you are ready to wait for many scalar forward passes.

Parameter count is not 337

The official demo count requires exactly:

MLP.new(2, [16, 16, 1])

The count is:

First layer: 16 * (2 + 1) = 48
Second layer: 16 * (16 + 1) = 272
Output layer: 1 * (16 + 1) = 17
Total: 337

Changing input count, hidden widths, or output count changes the total.

Loss does not decrease

Common causes:

high dataset noise;
too few training steps;
too large or too small learning rate;
changed seed;
different architecture;
notebook cells run out of order.

Start from a clean runtime and run all cells top-to-bottom.

Notebook cells were run out of order

Use Livebook's run-all command from a clean runtime. Later cells expect values such as dataset, model, initial_loss, and run to come from earlier cells.

`mix docs` fails

Run:

mix deps.get
mix docs

If it still fails, check that every guide listed in mix.exs exists.

Tests fail after changing examples