Sage, LaTeX and Friends#

Sage and the LaTeX dialect of TeX have an intensely synergistic relationship. This section aims to introduce the variety of interactions, beginning with the most basic and proceeding to the more unusual.

Overview#

It may be easiest to understand the various uses of LaTeX with a brief overview of the mechanics of the three principal methods employed by Sage.

Every “object” in Sage is required to have a LaTeX representation. You can access this representation by executing latex(foo) where foo is some object in Sage. The output is a string that should render a reasonably accurate representation of foo when used in TeX’s math-mode (for example, when enclosed between a pair of single dollar signs). Some examples of this follow below.

In this way, Sage can be used effectively for constructing portions of a LaTeX document: create or compute an object in Sage, print latex() of the object and cut/paste it into your document.

The Jupyter notebook interface uses MathJax to render mathematics cleanly in a web browser. You can start this automatic rendering by executing %display latex (and stop by executing %display plain).

MathJax is an open source JavaScript display engine for mathematics that works in all modern browsers. It is able to render a large, but not totally complete, subset of TeX. It has no support for things like complicated tables, sectioning or document management, as it is oriented towards accurately rendering “snippets” of TeX. Seemingly automatic rendering of math in the notebook is provided by converting the latex() representation of an object (as described above) into a form of HTML palatable to MathJax.

A system-wide installation of LaTeX can be employed. Sage includes almost everything you need to build and use Sage, but a significant exception is TeX itself. So in these situations you need to have TeX installed, along with some associated conversion utilities, to utilize the full power.

Here we demonstrate some basic uses of the latex() function.

sage: var('z')
z
sage: latex(z^12)
z^{12}
sage: latex(integrate(z^4, z))
\frac{1}{5} \, z^{5}
sage: latex('a string')
\text{\texttt{a{ }string}}
sage: latex(QQ)
\Bold{Q}
sage: latex(matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]))
\left(\begin{array}{rrr}
2 & 4 & 6 \\
-1 & -1 & -1
\end{array}\right)

Basic MathJax functionality is largely automatic in the notebook, but we can partially demonstrate this support with the MathJax class. The object of this class converts a Sage object to its LaTeX representation and then wraps it in HTML.

sage: from sage.misc.html import MathJax
sage: mj = MathJax()
sage: var('z')
z
sage: mj(z^12)
<html>\[z^{12}\]</html>
sage: mj(QQ)
<html>\[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Q}\]</html>
sage: mj(ZZ['x'])
<html>\[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Z}[x]\]</html>
sage: mj(integrate(z^4, z))
<html>\[\frac{1}{5} \, z^{5}\]</html>

Basic Use#

As indicated in the overview, the simplest way to exploit Sage’s support of LaTeX is to use the latex() function to create legitimate LaTeX code to represent mathematical objects. These strings can then be incorporated into standalone LaTeX documents.

At the other extreme is the view() command. The command view(foo) will create the LaTeX representation of foo, incorporate this into a simple LaTeX document, and then process that document with your system-wide TeX installation. Finally, the appropriate viewer will be called to display the output from the TeX command. Which version of TeX is used, and therefore the nature of the output and associated viewer, can be customized (see Customizing LaTeX Processing).

Customizing LaTeX Generation#

There are several ways to customize the actual LaTeX code generated by the latex() command. There is a pre-defined object named latex which has several methods, which you can list by typing latex., followed by the Tab key (note the period).

A good example is the latex.matrix_delimiters method. It can be used to change the notation surrounding a matrix – large parentheses, brackets, braces, vertical bars. No notion of style is enforced, you can mix and match as you please. Notice how the backslashes needed in LaTeX require an extra slash so they are escaped properly within the Python string.

sage: A = matrix(ZZ, 2, 2, range(4))
sage: latex(A)
\left(\begin{array}{rr}
0 & 1 \\
2 & 3
\end{array}\right)
sage: latex.matrix_delimiters(left='[', right=']')
sage: latex(A)
\left[\begin{array}{rr}
0 & 1 \\
2 & 3
\end{array}\right]
sage: latex.matrix_delimiters(left='\\{', right='\\}')
sage: latex(A)
\left\{\begin{array}{rr}
0 & 1 \\
2 & 3
\end{array}\right\}

The latex.vector_delimiters method works similarly.

The way common rings and fields (integers, rational, reals, etc.) are typeset can be controlled by the latex.blackboard_bold method. These sets are by default typeset in bold, but may optionally be written in a double-struck fashion as sometimes done in written work. This is accomplished by redefining the \Bold{} macro which is built-in to Sage.

sage: latex(QQ)
\Bold{Q}
sage: from sage.misc.html import MathJax
sage: mj = MathJax()
sage: mj(QQ)
<html>\[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Q}\]</html>
sage: latex.blackboard_bold(True)
sage: mj(QQ)
<html>\[\newcommand{\Bold}[1]{\mathbb{#1}}\Bold{Q}\]</html>
sage: latex.blackboard_bold(False)

It is possible to take advantage of the extensible nature of TeX by adding in new macros and new packages. First, individual macros can be added so that they are used when MathJax interprets a snippet of TeX in the notebook.

sage: latex.extra_macros()
''
sage: latex.add_macro("\\newcommand{\\foo}{bar}")
sage: latex.extra_macros()
'\\newcommand{\\foo}{bar}'
sage: var('x y')
(x, y)
sage: latex(x+y)
x + y
sage: from sage.misc.html import MathJax
sage: mj = MathJax()
sage: mj(x+y)
<html>\[\newcommand{\foo}{bar}x + y\]</html>

Additional macros added this way will also be used in the event that the system-wide version of TeX is called on something larger than MathJax can handle. The command latex_extra_preamble is used to build the preamble of a complete LaTeX document, so the following illustrates how this is accomplished. As usual note the need for the double-backslashes in the Python strings.

sage: latex.extra_macros('')
sage: latex.extra_preamble('')
sage: from sage.misc.latex import latex_extra_preamble
sage: print(latex_extra_preamble())
\newcommand{\ZZ}{\Bold{Z}}
...
\newcommand{\Bold}[1]{\mathbf{#1}}
sage: latex.add_macro("\\newcommand{\\foo}{bar}")
sage: print(latex_extra_preamble())
\newcommand{\ZZ}{\Bold{Z}}
...
\newcommand{\Bold}[1]{\mathbf{#1}}
\newcommand{\foo}{bar}

Again, for larger or more complicated LaTeX expressions, it is possible to add packages (or anything else) to the preamble of the LaTeX file. Anything may be incorporated into the preamble with the latex.add_to_preamble command, and the specialized command latex.add_package_to_preamble_if_available will first check if a certain package is actually available before trying to add it to the preamble.

Here we add the geometry package to the preamble and use it to set the size of the region on the page that TeX will use (effectively setting the margins). As usual, note the need for the double-backslashes in the Python strings.

sage: from sage.misc.latex import latex_extra_preamble
sage: latex.extra_macros('')
sage: latex.extra_preamble('')
sage: latex.add_to_preamble('\\usepackage{geometry}')
sage: latex.add_to_preamble('\\geometry{letterpaper,total={8in,10in}}')
sage: latex.extra_preamble()
'\\usepackage{geometry}\\geometry{letterpaper,total={8in,10in}}'
sage: print(latex_extra_preamble())
\usepackage{geometry}\geometry{letterpaper,total={8in,10in}}
\newcommand{\ZZ}{\Bold{Z}}
...
\newcommand{\Bold}[1]{\mathbf{#1}}

A particular package may be added along with a check on its existence, as follows. As an example, we just illustrate an attempt to add to the preamble a package that presumably does not exist.

sage: latex.extra_preamble('')
sage: latex.extra_preamble()
''
sage: latex.add_to_preamble('\\usepackage{foo-bar-unchecked}')
sage: latex.extra_preamble()
'\\usepackage{foo-bar-unchecked}'
sage: latex.add_package_to_preamble_if_available('foo-bar-checked')
sage: latex.extra_preamble()
'\\usepackage{foo-bar-unchecked}'

Customizing LaTeX Processing#

It is also possible to control which variant of TeX is used for system-wide invocations, thus also influencing the nature of the output.

The latex.engine() command can be used to control if the system-wide executables latex, pdflatex or xelatex are employed for more complicated LaTeX expressions. When view() is called and the engine is set to latex, a dvi file is produced and Sage will use a dvi viewer (like xdvi) to display the result. In contrast, using view() when the engine is set to pdflatex will produce a PDF as the result and Sage will call your system’s utility for displaying PDF files (acrobat, okular, evince, etc.).

For a concrete example of how complicated LaTeX expressions can be processed, see the example in the next section (An Example: Combinatorial Graphs with tkz-graph) for using the LaTeX tkz-graph package to produce high-quality renderings of combinatorial graphs. For other examples, there are some pre-packaged test cases. To use these, it is necessary to import the sage.misc.latex.latex_examples object, which is an instance of the sage.misc.latex.LatexExamples class, as illustrated below. This class currently has examples of commutative diagrams, combinatorial graphs, knot theory and pstricks, which respectively exercise the following packages: xy, tkz-graph, xypic, pstricks. After the import, use tab-completion on latex_examples to see the pre-packaged examples. Calling each example will give you back some explanation about what is required to make the example render properly. To actually see the examples, it is necessary to use view() (once the preamble, engine, etc are all set properly).

sage: from sage.misc.latex import latex_examples
sage: latex_examples.diagram()
LaTeX example for testing display of a commutative diagram produced
by xypic.

To use, try to view this object -- it will not work.  Now try
'latex.add_to_preamble("\\usepackage[matrix,arrow,curve,cmtip]{xy}")',
and try viewing again. You should get a picture (a part of the diagram arising
from a filtered chain complex).

An Example: Combinatorial Graphs with tkz-graph#

High-quality illustrations of combinatorial graphs (henceforth just “graphs”) are possible with the tkz-graph package. This package is built on top of the tikz front-end to the pgf library. So all of these components need to be part of a system-wide TeX installation, and it may be possible that these components may not be at their most current versions as packaged in some TeX implementations. So for best results, it could be necessary or advisable to install these as part of your personal texmf tree. Creating, maintaining and customizing a system-wide or personal TeX installation is beyond the scope of this document, but it should be easy to find instructions. The necessary files are listed in A Fully Capable TeX Installation.

Thus, to start we need to insure that the relevant packages are included by adding them to the preamble of the eventual LaTeX document. The images of graphs do not form properly when a dvi file is used as an intermediate format, so it is best to set the latex engine to the pdflatex executable. At this point a command like view(graphs.CompleteGraph(4)) should produce a PDF with an appropriate image of the complete graph \(K_4\).

Note that there is a variety of options to affect how a graph is rendered in LaTeX via tkz-graph, which is again outside the scope of this section, see the section of the Reference manual titled “LaTeX Options for Graphs” for instructions and details.

A Fully Capable TeX Installation#

Many of the more advanced features of the integration of TeX with Sage requires a system-wide installation of TeX. Many versions of Linux have base TeX packages based on TeX Live, for macOS there is TeXShop and for Windows there is MiKTeX. The convert utility is part of the ImageMagick suite (which should be a package or an easy download), and the three programs dvipng, ps2pdf, and dvips may be included with your TeX distribution. The first two may also be obtained, respectively, from http://sourceforge.net/projects/dvipng/ and as part of Ghostscript.

Rendering combinatorial graphs requires a recent version of the PGF library, the file tkz-graph.sty from https://www.ctan.org/pkg/tkz-graph, and the files tkz-arith.sty and perhaps tkz-berge.sty from https://www.ctan.org/pkg/tkz-berge.

SageTeX#

SageTeX is a program available to further integrate TeX and Sage. A concise description of SageTeX is that it is a collection of TeX macros that allow a LaTeX document to include instructions to have Sage compute various objects and/or format objects using the latex() support built into Sage. So as an intermediate step of compiling a LaTeX document, all of the computational and LaTeX-formatting features of Sage can be handled automatically. As an example, a mathematics examination can maintain a correct correspondence between questions and answers by using SageTeX to have Sage compute one from the other. See Using SageTeX for more information.