pmatrix inconsistently rendered to latex leading to errors

[dellaert]

In several sections of our book, pmatrix is now inconsistently rendered to pdf leading to errors in latex. This seems new in recent versions of mystmd.

Versions: I noticed it in v1.3.4 but not fixed by upgrading to v1.3.7.

Description

The following markdown (in a notebook cell)

Because we have three wheels, we can stack three instances of the above equation
to obtain a matrix equation
that maps a desired robot velocity $v=(v_x,v_y)$ to the appropriate commanded wheel velocities:

$$
\begin{pmatrix}\omega^1 \\ \omega^2 \\ \omega^3 \end{pmatrix} 
= \frac{1}{r} \begin{pmatrix}- \sin\theta^1 & \cos\theta^1 \\ - \sin\theta^2 & \cos\theta^2 \\ - \sin\theta^3 & \cos\theta^3 \end{pmatrix}
\begin{pmatrix}v_x \\ v_y \end{pmatrix}
$$

in which the $3\times2$ matrix is called the **Jacobian matrix**.

For the three regularly arranged omni wheels with $\theta^1=0$, $\theta^2=2\pi/3$, and $\theta^3=4\pi/3$ this becomes

$$
\begin{pmatrix}\omega^1 \\ \omega^2 \\ \omega^3 \end{pmatrix} 
= \frac{1}{r} \begin{pmatrix}0 & 1 \\ -0.866 & -0.5 \\ 0.866 & -0.5  \end{pmatrix}
\begin{pmatrix}v_x \\ v_y \end{pmatrix}.
$$

Is rendered inconsistently to latex. Below, note that the first display formula has no equation environment (incorrect), but the second one does (correct):

Because we have three wheels, we can stack three instances of the above equation
to obtain a matrix equation
that maps a desired robot velocity $v=(v_x,v_y)$ to the appropriate commanded wheel velocities:

\begin{pmatrix}\omega^1 \\ \omega^2 \\ \omega^3 \end{pmatrix} 
= \frac{1}{r} \begin{pmatrix}- \sin\theta^1 & \cos\theta^1 \\ - \sin\theta^2 & \cos\theta^2 \\ - \sin\theta^3 & \cos\theta^3 \end{pmatrix}
\begin{pmatrix}v_x \\ v_y \end{pmatrix}

in which the $3\times2$ matrix is called the \textbf{Jacobian matrix}.

For the three regularly arranged omni wheels with $\theta^1=0$, $\theta^2=2\pi/3$, and $\theta^3=4\pi/3$ this becomes

\begin{equation}
\begin{pmatrix}\omega^1 \\ \omega^2 \\ \omega^3 \end{pmatrix} 
= \frac{1}{r} \begin{pmatrix}0 & 1 \\ -0.866 & -0.5 \\ 0.866 & -0.5  \end{pmatrix}
\begin{pmatrix}v_x \\ v_y \end{pmatrix}.
\end{equation}

Proposed solution

I don't know how to fix it. I tried "coercing" it to behave, including adding \begin{equation}, but that did not work. I did find a workaround which was to use the begin{align} environment inside the $$.

Additional notes

The latex errors that occur are of the nature missing $ inserted. However, despite recovery efforts, the PDF does not render correctly:

instead of the correct:

[rowanc1]

Thanks @dellaert. This was brought in through:

• 🧮 Fix AMSMath environment for LaTeX #977

The difference is that the second equation ends in a . and that stops the removal of the equation environment.

It sounds like the pmatrix (maybe others) actually shouldn't be stand-alone in latex. In which case removing this line:

https://github.com/executablebooks/mystmd/blob/main/packages/myst-to-tex/src/math.ts#L13

[rowanc1]

I have put together a fix with yours as a test case in #1520.

[dellaert]

Awesome! You did not remove that line in math.ts though? I guess you found another way :-)
FYI Here is the PR with all my work-arounds: gtbook/robotics#89

[rowanc1]

My reading of the spec is that this actually is a top-level command, but only if it fully encompasses all of the math. The new code tests for that.

For example:

\begin{pmatrix}...\end{pmatrix}

is a valid AMS environment, whereas something that doesn't include all of the content:

\begin{pmatrix}...\end{pmatrix}
=
\begin{pmatrix}...\end{pmatrix}

is not valid, and needs the wrapper.

[rowanc1]

@dellaert -- planning a release later today that should get this fix out. Thanks again for the issue.

[dellaert]

Subtle! Thanks for the quick fix!

[dellaert]

@rowanc1 I think the PR did not solve all issues, assuming myst v1.3.8 has that PR included.

• My workaround to add align now gives "Erroneous nesting" which I think should not happen. It should just use align not equation when align is specified.
• I did not remove them in S54 as there removing them again yields the "missing $ inserted" error. The latex error recovery for the "Erroneous nesting" error is better so I just kept the aligns and it renders fine. But those 4 errors are still there. Here is an example:

$$
\begin{align}
\begin{bmatrix}
3 & \textbf{3} & \textbf{3} & \textbf{5} & 5 & 5 & 5 & 2 & 2 & 2 \\
3 & 0 & \textbf{2} & 2 & 0 & 0 & -3 & -3 & 0 & -2
\end{bmatrix}
\end{align}
$$

(erroneously) yields

\begin{equation}
\begin{align}
\begin{bmatrix}
3 & \textbf{3} & \textbf{3} & \textbf{5} & 5 & 5 & 5 & 2 & 2 & 2 \\
3 & 0 & \textbf{2} & 2 & 0 & 0 & -3 & -3 & 0 & -2
\end{bmatrix}
\end{align}
\end{equation}

rather than the (I think) correct:

\begin{align}
\begin{bmatrix}
3 & \textbf{3} & \textbf{3} & \textbf{5} & 5 & 5 & 5 & 2 & 2 & 2 \\
3 & 0 & \textbf{2} & 2 & 0 & 0 & -3 & -3 & 0 & -2
\end{bmatrix}
\end{align}

[dellaert]

PS the PR in the book to remove all problematic aligns (which I think all point to issues in mystmd) is here: gtbook/robotics#91

[rowanc1]

I have attempted to fix this in #1526 with a bit better logic for each environment. Your equations are now test cases! I have tested this in overleaf and done what they suggest for each of the environments to understand if it is top level or not.

Thanks for the feedback on getting this better, sorry it has taken a few iterations!

[dellaert]

Happy to stress-test this workflow :-) Thanks for fixing this quickly!