numodel-bundle

LuaLaTeX packages for numerical models in physics teaching material. You declare a model once — variables, rules, a stop condition — and the bundle computes it and typesets it in every form a lesson needs: the model as text, as a stock-and-flow diagram, and as graphs of the results. It can also hand the model to the modelling software pupils use.

The bundle is pre-1.0 (current release v0.12.0); breaking changes may still occur.

All modules ship together and carry the same version.

Installation

The bundle is part of TeX Live and MiKTeX after its CTAN release:

tlmgr install numodel-bundle

All packages need LuaLaTeX.

Documentation

Each package has its own manual: numodel-manual.pdf, numodel-plot-manual.pdf and numodel-coach-manual.pdf (texdoc numodel, texdoc numodel-plot, texdoc numodel-coach). What changed in each release is in CHANGELOG.md.

numodel

Declare the variables and rules of a numerical model; numodel iterates it in Lua and typesets it:

• \textmodel — the model as text, in the notation of the syllabus: English (XMILE-style) or Dutch (Coachtaal), with extra languages as drop-in numodel-<LANG>.def files;
• \graphicmodel — the Forrester stock-and-flow diagram, laid out automatically from the rules;
• \computemodel and \diagrammodel — the computed results as a graph, with units from siunitx.

Quantities, units and numbers come from one declaration, so text, diagram and graphs never disagree.

Minimum working example

\documentclass{article}
\usepackage[syntax=EN]{numodel}       % or syntax=NL for Coachtaal
\begin{document}

\newmodelprefix{ball}
\mvar{T}{t}{0}{\s}{2}{system}
\mvar{Dt}{dt}{0.1}{\s}{2}{system}
\mvar{Y}{y}{100}{\m}{2}{stock}
\mvar{V}{v}{0}{\m\per\s}{2}{stock}
\mvar{G}{g}{-9.81}{\m\per\s\squared}{2}{constant}

\mrule{V}{\ballV + \ballG * \ballDt}
\mrule{Y}{\ballY + \ballV * \ballDt}
\mrule{T}{\ballT + \ballDt}
\mstop{\ballY <= 0}

\textmodel
\graphicmodel
\computemodel
\diagrammodel{T}{Y}{ballfall}

\end{document}

Syntax options

\usepackage{numodel}                    % default: syntax=EN
\usepackage[syntax=EN]{numodel}         % XMILE-style ALL CAPS
\usepackage[syntax=NL]{numodel}         % Dutch Coachtaal
\usepackage[syntax=FPEVAL]{numodel}     % the rules as typed (l3fp)

syntax=XX loads the keyword table numodel-XX.def. To add a language, put your own numodel-XX.def where TeX finds it and select it with \usepackage[syntax=XX]{numodel}.

Requirements

LuaLaTeX, TeX Live 2024 or later. Depends on expl3, xparse, l3keys2e, amsmath, amssymb, xfrac, tikz, luacode, siunitx, float, tabularray and numodel-plot.

numodel-plot

A PGFPlots engine that sizes plots to a whole number of tick intervals, supports configurable axis-label formats (IEEE by default, ISO 80000-1 selectable), folds the power of ten of a scaled axis into an SI prefix (s (km)), and places labels for 1-, 2- and 4-quadrant graphs. numodel uses it for \diagrammodel; it also works on its own.

Minimum working example

\documentclass{article}
\usepackage{siunitx}
\usepackage{numodel-plot}
\begin{document}
\def\xmin{0}\def\xmax{10}
\def\ymin{0}\def\ymax{5}
\def\xlabelqty{t}\def\xlabelunit{\s}
\def\ylabelqty{v}\def\ylabelunit{\m\per\s}
\drawplot{\addplot[domain=\xmin:\xmax]{0.5*x};}
\end{document}

Configuration

\numodelplotsetup{
  axis-label-format = ieee,    % ieee | iso | brackets | qty-only | unit-only
  grid              = mm-dots, % mm-dots | none | <pgfplots-style-list>
  scale-format      = prefix,  % prefix | exponent | input
  halo-color        = auto,    % auto | <colour expression>
  xcmmax            = 12,      % max axis width  (cm)
  ycmmax            = 10       % max axis height (cm)
}

Requirements

LuaLaTeX, TeX Live 2024 or later. Depends on expl3, xparse, l3keys2e, siunitx (2023-11-06 / v3.3.8 or newer), pgfplots (compat=1.18) and pdfrender.

numodel-coach

Writes a numodel model as a modelling activity for CMA Coach 7 (.cma7), in Coach's text mode. Pupils open the file in Coach and get exactly the model of the text, without retyping it from the PDF:

• the model rules and initial values in Coachtaal, with units as comments;
• every variable in Coach's variable list, with the axis range of its graph in the document;
• the iteration count from numodel's maxiter;
• optionally an instruction text, written once in LaTeX and shown both in the PDF and in Coach's instruction window.

Minimum working example

\documentclass{article}
\usepackage[syntax=NL]{numodel}
\usepackage{numodel-coach}
\begin{document}
\newmodelprefix{ball}
\mvar{T}{t}{0}{\s}{2}{systeem}
\mvar{Dt}{dt}{0.05}{\s}{2}{systeem}
\mvar{V}{v}{0}{\m\per\s}{3}{voorraad}
\mvar{Y}{y}{100}{\m}{3}{voorraad}
\mvar{G}{g}{-9.81}{\m\per\s\squared}{3}{constante}
\mrule{V}{\ballV + \ballG * \ballDt}
\mrule{Y}{\ballY + \ballV * \ballDt}
\mrule{T}{\ballT + \ballDt}
\mstop{\ballY <= 2}

\begin{coachinstruction}
Een bal valt vanuit rust van \qty{100}{\m}. Wat is de eindsnelheid?
\end{coachinstruction}

\coachinstructiontext          % the instruction in the PDF
\textmodel
\coachmodel{vrije-val}         % writes vrije-val.cma7
\end{document}

Options (\coachmodel[...] or \coachsetup{...}): mode (text, the default, or graphic: Coach's stock-and-flow diagram, in which pupils can switch to the text view), dir (output directory), attach (also embed the file in the PDF), switch (let pupils switch between text and graphical view; by default on for a graphical model, off for a text model), prefix.

CMA does not document the .cma7 format; the package was developed against files saved by Coach 7.0 and tested with Coach 7 on Chromebooks. Please report problems with other Coach versions.

Requirements

LuaLaTeX; numodel (same version) and embedfile.

Source code and bug reports

https://github.com/paulzuurbier/numodel — issues welcome. For building and testing the bundle from source, see DEVELOPMENT.md in the repository.

License

LaTeX Project Public License 1.3c.

Author

Paul Zuurbier — mail@paulzuurbier.nl