% File: numodel-coach-manual.tex
% Standalone manual for the numodel-coach package.

\documentclass{ltxdoc}
\usepackage[left=3.5cm, right=2cm, top=2cm, bottom=2cm,
            marginparwidth=3.5cm, marginparsep=0.3cm]{geometry}
\usepackage[syntax=NL]{numodel}
\usepackage{numodel-coach}
\usepackage{booktabs}

% Fonts.  fontspec + unicode-math require LuaLaTeX.
\usepackage{fontspec}
\setmainfont{Arial}
\usepackage{unicode-math}
\setmathfont{Lete Sans Math}
\setmonofont{Fira Mono}

% Breakable inline verbatim (see numodel-manual.tex for rationale).
\usepackage{fvextra}
\AtBeginDocument{%
  \MakeShortVerb{\|}%
  \DeleteShortVerb{\|}%
  \DefineShortVerb[breaklines,breakanywhere]{\|}%
}

\begin{document}

\GetFileInfo{numodel-coach.sty}

\title{The \textsf{numodel-coach} package\\[0.5ex]
  \large Export \textsf{numodel} models to CMA Coach~7}
\author{Paul Zuurbier\\\texttt{mail@paulzuurbier.nl}}
\date{\fileversion\ (\filedate)}
\maketitle

\begin{abstract}
\noindent
\textsf{numodel-coach} writes a model declared with \textsf{numodel}
as a modelling activity for CMA Coach~7 (a \texttt{.cma7} file), 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 are \textsf{numodel}'s Coachtaal rendering
(\texttt{numodel.plaintext}); the file can also be embedded in the PDF.
\end{abstract}

\section{Usage}

Load the package after \textsf{numodel} (LuaLaTeX only):
\begin{verbatim}
\usepackage[syntax=NL]{numodel}
\usepackage{numodel-coach}
\end{verbatim}
After the model is declared, \cs{coachmodel} writes it:
\begin{verbatim}
\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}
\textmodel
\coachmodel{vrije-val}
\end{verbatim}
This writes \texttt{vrije-val.cma7} with the model rules
\begin{verbatim}
v := v + g*dt
y := y + v*dt
t := t + dt
Als y <= 2 Dan Stop EindAls
\end{verbatim}
and the initial values
\begin{verbatim}
t := 0      's
dt := 0,05  's
v := 0      'm/s
y := 100    'm
g := -9,81  'm/s^2
\end{verbatim}
All variables are listed in Coach's variable list (for tables and
graphs) with their units.

\DescribeMacro{\coachmodel}
\cs{coachmodel}\oarg{options}\marg{name} writes the model with the
current prefix to \meta{name}\texttt{.cma7} (no extension is added
when \meta{name} has one). Options: \texttt{prefix=}\meta{prefix} for
another model, and \texttt{dir}, \texttt{attach}, \texttt{switch},
\texttt{mode} and \texttt{blanks} as below.

\DescribeMacro{\coachsetup}
\cs{coachsetup}\marg{options} sets defaults for all following
\cs{coachmodel} calls:
\begin{description}
  \item[\texttt{dir=}\meta{directory}] Directory for the files,
    relative to the working directory; created when missing. Default:
    the working directory.
  \item[\texttt{attach=true/false}] Also embed the file in the PDF
    (with \textsf{embedfile}). Default \texttt{false}. Whether readers
    can open embedded files depends on the PDF viewer.
  \item[\texttt{blanks=open/filled}] (\cs{coachmodel} only) Write the
    pupil's version, in which every rule, stop condition and start
    value declared with \textsf{numodel}'s |blank| key becomes a
    comment |' F_z := ...| to complete in Coach, or the answer version
    in full. Default: \textsf{numodel}'s |blanks| setting (|open|).
  \item[\texttt{mode=text/graphic}] Write the model as a text model
    (default) or as a graphical model, in which pupils can switch to
    the text view; see Section~\ref{sec:graphic}.
  \item[\texttt{graphic-style=edu/tight}] The look of a graphical
    model, as \textsf{numodel}'s |diagram-style| |edu| and |tight|:
    |edu| (default) draws every variable as an object of its own,
    |tight| lets a flow that is a single variable carry its name and
    formula; see Section~\ref{sec:graphic}.
  \item[\texttt{switch=true/false/auto}] Whether pupils may switch
    between Coach's text and graphical view. Default |auto|: on for a
    graphical model, off for a text model. Coach derives the text view
    from the graphical model, which a text model leaves empty, so
    switching would lose a text model.
\end{description}

\section{Graphical model}\label{sec:graphic}

With |\coachmodel[mode=graphic]{...}| the file holds Coach's
graphical model: the stock-and-flow diagram, with a formula in every
object. Coach opens it in the graphical view, and pupils can switch to
the text view, which Coach derives from the diagram (in its own order
of the rules). The model is translated as follows:
\begin{itemize}
  \item The time rule |t := t + dt| becomes Coach's time; the start
    value of $t$ and $\Delta t$ go to the model settings, together
    with the stop condition.
  \item A stock rule $X := X + \dots$ in which every other term has
    a factor $\Delta t$ becomes a stock (\emph{voorraadgrootheid}) with
    one flow per term; the factor $\Delta t$ goes, as Coach multiplies
    by it itself. A term $-Q\,\Delta t$ in one stock and $+Q\,\Delta t$
    in another is one flow between them.
  \item With |graphic-style=edu| (the default) the flows are called
    \texttt{Stroom\_1}, \dots; a flow $+a\,\Delta t$ has the formula
    $a$, and $a$ stays an object of its own with an arrow to the flow,
    as \cs{graphicmodel} draws it in its |edu| style. With
    |graphic-style=tight| a flow that is a single variable used
    nowhere else -- an auxiliary variable, also a conditional one, or a
    constant -- \emph{is} that variable: it gets its name (shown in the
    diagram), unit and formula or value, as \cs{graphicmodel} draws it
    as the valve in its default |tight| style. Other flows are still
    \texttt{Stroom\_1}, \dots
  \item Other rules become auxiliary variables; a conditional rule
    |c ? a : b| uses Coach's condition. Variables without a rule are
    constants. A start value of an auxiliary variable becomes its
    initial value.
  \item Every variable a formula uses gets an arrow (relation) to it.
  \item The positions follow \cs{graphicmodel}'s layout in the
    matching style; Coach lets pupils move everything.
\end{itemize}
A model that cannot be drawn this way -- a stock rule with a term
without $\Delta t$ (|n := n + 1|), a conditional rule using $\Delta t$,
two rules for one variable -- is written as a text model, with a
warning naming the reason. In a graphical model Coach computes the
auxiliary variables from the stocks of the same step; a text model in
which an auxiliary rule comes \emph{after} the stock it uses computes
it from the new value, so the two can differ slightly.

\section{Instruction text}

\DescribeEnv{coachinstruction}
The environment \texttt{coachinstruction}\oarg{prefix=\meta{prefix}}
defines the instruction text of a model (by default the current one).
It typesets nothing.

\DescribeMacro{\coachinstructiontext}
\cs{coachinstructiontext}\oarg{prefix=\meta{prefix}} typesets that text
in the PDF, wherever you want it and as often as you like (or not at
all), and \cs{coachmodel} writes it to Coach's instruction window. The
PDF and Coach thus share one source:
\begin{verbatim}
\begin{coachinstruction}
Een bal valt vanuit rust van \qty{100}{\m}. Neem
$g = \qty{9.81}{\m\per\s\squared}$.

Opdrachten:
\begin{enumerate}
  \item Bereken de \textbf{eindsnelheid} $v_{\text{eind}}$.
\end{enumerate}
\end{coachinstruction}

\coachinstructiontext   % the text in the PDF
\coachmodel{vrije-val}  % the same text in Coach
\end{verbatim}
A model has one instruction text: a second \texttt{coachinstruction}
for the same model replaces the first, with a warning. The text is
typeset where \cs{coachinstructiontext} stands, so anything in it that
depends on its position (a counter, say) takes its value there.

Coach shows HTML in its instruction window; the body is converted
from the following LaTeX:
\begin{itemize}
  \item paragraphs (blank lines), |\\|, |\newline|;
  \item |\textbf|, |\emph|, |\textit|, |\underline|,
    |\textsuperscript|, |\textsubscript|; |\text| and similar
    wrappers keep their text;
  \item |itemize| and |enumerate| with |\item|;
  \item inline math (|$...$|, |\(...\)|): letters in italics,
    |_| and |^| as sub- and superscript, Greek letters, |\frac|,
    |\sqrt|, |\cdot|, relations such as |\leq|;
  \item |\qty|, |\num|, |\unit| (and |\SI|, |\si|): numbers with
    a decimal comma, units in Coach's notation;
  \item |~|, |--|, |---|, quotes, and a handful of symbols
    (|\ldots|, |\times|, |\degree|, \dots).
\end{itemize}
Any other command gives a warning; its braced argument is kept as
text. Display math, tables and pictures are not converted.

\section{What is exported}

\begin{itemize}
  \item \emph{Model rules} in the order of \cs{textmodel}: \cs{mrule}
    as an assignment, conditional rules as
    \texttt{Als \dots\ Dan \dots\ Anders \dots\ EindAls} (on several
    lines for \cs{mrule*}), \cs{mstop} as
    \texttt{Als \dots\ Dan Stop EindAls}. A \cs{mruletext} row becomes a
    comment, with a warning. The display keys \texttt{alias},
    \texttt{aliasleft} and \texttt{aliasright} do not apply: Coach gets
    the calculation.
  \item \emph{Initial values} of all variables with a start value,
    with the unit as a comment.
  \item \emph{Variable list}: every variable, with its unit, so it can
    be put in Coach's table and graphs. The axis range Coach uses for
    a new graph or meter is the range of the variable's graph in the
    document: the axis limits \cs{diagrammodel} drew (the union, when
    the variable appears in several diagrams). A variable that is not
    drawn gets the range a diagram of its computed series would have
    (the same rounding to whole ticks); only a model that was never
    computed keeps Coach's default 0 to 10. Call \cs{coachmodel} after
    \cs{computemodel} and the diagrams. Coach shows two decimals.
  \item \emph{Names}: the display name without formatting
    (|F_{\text{res}}| becomes \texttt{F\_res}, |\Delta t|
    becomes \texttt{Δt}, |\lambda| \texttt{λ}). Names Coach does not
    accept bare (with a space or a slash), and its reserved words, are
    put in brackets: \texttt{[t\_1/2]}, \texttt{[Max]}.
  \item \emph{Units}: siunitx units in Coach's notation:
    |\m\per\s\squared| becomes \texttt{m/s\^{}2},
    |\mole\per\litre\per\second| becomes \texttt{mol/(L*s)}.
    A unit of your own (|\DeclareSIUnit{\animals}{animals}|) is
    exported as its symbol: |\animals\per\day| becomes
    \texttt{animals/d}.
  \item \emph{Angle unit}: Coach's ``hoekeenheid'' follows
    \textsf{numodel}'s |angles| setting (|\numodelsetup{angles=degrees}|
    in the preamble; default radians), and so do the trigonometric
    functions: with degrees |sind(\alpha)| is exported as
    \texttt{Sin(alfa)}, |sin(x)| as \texttt{Sin(180/Pi*x)}, |asind(x)|
    as \texttt{Arcsin(x)} and |asin(x)| as \texttt{Pi/180*Arcsin(x)}
    (Coach's inverse functions answer in the angle unit too).
    |\textmodel| shows the same.
  \item \emph{Iterations}: the number of iterations in Coach's model
    settings is \textsf{numodel}'s \texttt{maxiter}
    (|\numodelsetup{maxiter=...}|, default 20000). The
    \texttt{Stop} rule ends the run; \texttt{maxiter} is only the upper
    limit.
\end{itemize}

Expressions are translated with care for the differences between
\textsf{l3fp} and Coachtaal: Coach gives unary minus and |^| the
same priority, so |-x^2| is exported as |-(x^2)|; comparisons
combined with \texttt{EN}/\texttt{OF} get the parentheses Coachtaal
requires. Whatever cannot be exported exactly (a two-argument
\texttt{atan}, a nested conditional, an unknown unit macro) is reported
as a package warning naming the model and the file.

\section{The file format}

CMA does not document the \texttt{.cma7} format. \textsf{numodel-coach}
starts from an empty modelling activity saved by Coach~7.0 in text
mode (stored as Lua data in \texttt{numodel-coach-template.lua}) and
fills in the model rules, initial values, variable list and iteration
count. Files written this way were tested with Coach~7 on Chromebooks.
A later Coach version may change the format; please report problems.

\end{document}