Frequently Asked Questions:
amsmath and related packages

This page lists some frequently asked questions about amsmath and related packages. These questions deal mainly with problems of installation, different versions, and the like. "How to" topics relevant to AMS authors are covered in the AMS Author FAQ.

Suggestions? Please send mail to tech-support@ams.org.

NOTE:  Several questions here deal with older versions of amsmath and friends. Although workarounds are given for problems arising with these older classes, if you are creating a new document, it is better to upgrade than to try to deal with the limitations of an old version. Only the most recent version of an AMS package is supported.

Where should I look for documentation?

• The primary user documentation is found in the "User's Guide for the amsmath Package" (amsldoc.pdf).   This and the other files listed here are included in the AMS-LaTeX distribution, and you should be able to find them on your system.
• These documentation files are best examined by looking at the source and output side-by-side:
  • Sample document illustrating use of the subequations environment and the effect of the fleqn option (subeqn.tex): source and output
  • Discussion of some technical issues (technote.tex): source and output
  • Samples of most of the math constructions provided by the amsmath package (testmath.tex): source and output
• These (ASCII) files contain more general documentation:
  • Differences between amsmath versions 1.1, 1.2, 2.0 (diffs-m.txt)
  • Overview of the distribution (00readme.txt)
  • Installation instructions (install.txt)

How do I get rid of the weird error that seems to be related to a section title or a figure caption?

• Check to see if you have used a "fragile" command inside a "moving" argument (article titles, section titles, figure captions, table captions, etc.).
• Not all math commands are robust, and a few that are robust in ordinary LaTeX become fragile when the amsmath package is added (e.g., \bigotimes). See Section C.1.3 of the LaTeX book.
• Most of the more common math commands have been made robust, but for each such command there is a hidden cost to users: making it robust uses up an extra control sequence name, which makes the following sort of error message more likely:

  TeX capacity exceeded [hash size=3500]

  Unlike the "require \protect" solution, the "capacity exceeded" problem can be very difficult for the average user to solve.
• Most TeX implementations since 2000 have increased the hash size so this should no longer be a problem, but it was a problem when amsmath was first developed.

Why can't I use an abbreviation for the "align" environment?

• It is a fairly common practice to use abbreviations such as \beq ... \eeq for \begin{equation} ... \end{equation}. This is not possible with most of the more complex amsmath equation structures, for technical reasons. See technote.tex for details.

Why can't I use \begin{align} ... \end{align} in the definition of another environment?

• If you want to make a more elaborate environment using align or one of the others as a base, it can be done as follows:

  \newenvironment{myalign}{%
    % extra material here
    \align
  }{%
    \endalign
    % extra material here
  } 

• See also technote.tex which contains a bit more detail.

Why did \matrix, \pmatrix, and \cases stop working when I added the amsmath package?

• Users of the amsmath package should follow standard LaTeX "environment" syntax and write

  \begin{matrix}.
  .. \\.
  .. \\.
  ..
  \end{matrix} 

  (and similarly for pmatrix and cases).
• The old form of those commands should be considered obsolete.
• When LaTeX was first written (1983-1985), those three commands were carried over directly from plain.tex, for lack of anything better. When the amsmath package was ported to LaTeX (its origin was in AMS-TeX), it came with commands of the same name but different syntax. Both the plain TeX and AMS-TeX syntax are ill-matched with the rest of LaTeX. The only tenable solution was to adopt the LaTeX environment syntax.

Why do \over, \atop, \above, ..., \overwithdelims give warnings when I add the amsmath package?

• If you use the amsmath package the commands \frac, \binom, and \genfrac provide all the same functionality with standard LaTeX syntax.
• \over and friends are primitive TeX commands whose unusual syntax is out of place in a LaTeX document. Using them at surface level in a document also makes it very difficult to achieve certain kinds of typesetting improvements that would otherwise be possible. Some additional details are given in the file technote.tex.
• If you are writing a LaTeX package that uses \over or another generalized fraction operator for internal purposes in building more complex commands, we recommend that you use \@@over, \@@atop, etc., after checking first to make sure that they are defined:

  \@ifundefined{@@over}{%
    \let\@@over\over % fallback if amsmath is not loaded
    \let\@@overwithdelims\overwithdelims
    \let\@@atop\atop \let\@@atopwithdelims\atopwithdelims
    \let\@@above\above \let\@@abovewithdelims\abovewithdelims
  }{} 

How do I get my equations and my theorems to share the same numbering sequence?

• \numberwithin{equation}{section}% [if desired]
  \newtheorem{thm}[equation]{Theorem}
  \newtheorem{prop}[equation]{Proposition}.
  .. 

• See the AMS Author FAQ for more information on theorem numbering.

How do I put a box around an entire equation, including the equation number?

• It depends. For a simple equation it can be done like this:

  \newcommand{\boxedeqn}[1]{%
    \[\fbox{%
        \addtolength{\linewidth}{-2\fboxsep}%
        \addtolength{\linewidth}{-2\fboxrule}%
        \begin{minipage}{\linewidth}%
        \begin{equation}#1\end{equation}%
        \end{minipage}%
      }\]%
  }
  
    ...
  
  Here is some text preceding the boxed equation.
  \boxedeqn{
    X_1(j\omega) = 
      \int\limits^{+\infty}_{-\infty} x_1(t) e^{-j\omega t} dt
  }
  And here is some text after it.

• If the equation number doesn't need to be included in the box, use \boxed{...}.

Why do I see no effect when I change \mathindent?

• If you upgrade to version 2.0 of the amsmath package you will probably get the results you want because there \mathindent is aliased to \@mathmargin.
• The amsmath package doesn't use \mathindent in the same way that basic LaTeX does. Instead, it uses an internal variable \@mathmargin that is a "glue" variable rather than a "dimen" variable.

Why doesn't \raisetag have any visible effect when there is plenty of room for the equation number on the last line of a multi-line equation?

• Try using instead the standard LaTeX commands for moving objects around (\makebox, \raisebox, picture environment, etc.).
• The adjustment specified with \raisetag is not applied unless the equation number has been shifted away from its normal position because LaTeX thinks there is not enough room for it to fit there. For a normal equation with plenty of room, the \raisetag adjustment is ignored.

Why are equation numbers sometimes misplaced or shifted to a separate line when there seems to be enough room to keep them on the same line?

• If you have an older version of the amsmath package, try upgrading. Some bugs of this type were cleared up in version 2.0.

How can I get something like the "cases" environment that permits a separate equation number for each line?

• Try the "cases" package of Donald Arseneau. It is available from CTAN if it isn't already on your system.

How can I get better vertical placement of symbols attached to a base symbol with \underset and/or \overset? The default placement is not good enough.

• Try the "accents" package of Javier Bezos. It is available from CTAN.

With \sideset the subscript is overlapping with neighboring material. How can this be fixed?

• This is a bug. As of amsmath version 2.0 it has not been fixed yet.
• Note that \sideset applies only to large operators, not to other kinds of expressions.

Lower limits on \iint\nolimits are positioned too far away from the integral symbol. How can this be fixed?

• This is a bug. It was fixed in version 2.0 of the amsmath package.

\ldots spacing differs from normal LaTeX values when I add the amsmath package. How can the original spacing be restored?

• This is a bug. It was fixed in version 2.0 of the amsmath package.

In "xalignat", how can I get rid of the error "Extra & on this line"?

• This is a bug. It was fixed in version 2.0 of the amsmath package.

Empty first cell in the "aligned" environment leads to a TeX error. How can this be avoided?

• A workaround was added in version 2.0 of the amsmath package.
• The LaTeX mechanism for scanning optional arguments does not work reliably in this context.

"align*" within "gather" is shifted to the right (for example in testmath.tex, p. 37).

• This is a bug. It was supposedly fixed in version 2.0, but has recurred. It is on our list to be fixed.

With fleqn + leqno options, the "align" environment nevertheless puts the numbers on the right. How can I force them to the left?

• This is a bug. It was fixed in version 2.0 of the amsmath package.

\numberwithin{equation}{chapter} with the "report" or "book" documentclass adds too many levels to the equation numbers: (1.1.x) instead of (1.x).

• This is a bug. It was fixed in version 2.0 of the amsmath package.
• If you have an older version, a workaround is to simplify the definition of \theequation before calling \numberwithin:

  \renewcommand{\theequation}{\arabic{equation}}
\numberwithin{equation}{chapter}

\accentedsymbol produces error message "Missing number, treated as zero."

• This is a bug. It was fixed in version 1.2c of the amsxtra package.

Why do I get this puzzling error message from using \ensuremath inside an alignment environment (aligned, array, etc)?
  ! Incomplete \ifmmode; all text was ignored after line 9.
  <inserted text>
                  \fi
  l.9 }

• This problem is not specific to amsmath but ultimately resolves to a deficiency in the definition of \ensuremath that was fixed in LaTeX as of 1996/06/01.
• If you can't upgrade your version of LaTeX to remedy this problem, the following patch should fix it:

  \DeclareRobustCommand\ensuremath[1]{\ifmmode#1\else{$#1$}\fi}

How can I show an example of a few lines to be typed into a computer, centered with an equation number? amsmath doesn't allow one to use \verb in the equation environment.

• This does not apply for simple equation environments as of amsmath version 2.0.
• For multi-line equation environments such as align, gather, split, multline, aligned, alignat, etc., store the text beforehand using an lrbox environment and then call it with \usebox (if you do not know how to use lrbox and \usebox, see the LaTeX book (2nd edition) and/or the documentation usrguide.tex that comes with LaTeX).

In amsmath.sty, the @! and @, from amstex.sty disappeared. How do I get the same effect using amsmath?

• For @, use \mspace{.3mu}. For @! use \mspace{-.3mu}.
• These very small spaces were normally used in multiples of three or more. It is better to replace @!@!@! with \mspace{-.9mu} than with three separate \mspace commands.