Asymptote Guide
This was originally LaTeX FAQ L-8, but it became so long that I decided it deserved its own page.
Video screencast
Prerequisites
First, if you haven’t already, make sure you know everything in the File systems beginner page. If you don’t understand how files work, this page will not make much sense.
You should have a working local LaTeX installation working, as described in LaTeX FAQ. (Overleaf is not an acceptable substitute for this tutorial; see L-2 for why.)
You can verify you have LaTeX installed by typing
pdflatex --version
into a command line; this should give an output like
pdfTeX 3.141592653-2.6-1.40.25 (TeX Live 2023/Arch Linux)
kpathsea version 6.3.5
Copyright 2023 Han The Thanh (pdfTeX) et al.
(and so on...)
You should also have Asymptote installed. Check the installation instructions on the Asymptote website. If that’s working, you should be able to type
asy --version
into a command line and obtain a version number.
The main workflow
Once you have Asymptote installed, to integrate it with LaTeX, the compilation workflow requires three steps.
- Run PDFLaTeX on, say,
meow.tex
. This createsmeow-N.asy
for the N’th diagram. - You need to then run the Asymptote binary on
meow-N.asy
to generatemeow-N.pdf
. - The diagram
meow-N.pdf
then gets incorporated when you run PDFLaTeX again.
This is shown in detail in the video at the top of the page. Here’s the sample file if you want to copy and try it yourself.
\documentclass[11pt]{article}
\usepackage{asymptote}
\begin{document}
\title{Meow}
\author{Twitch Solves ISL}
\maketitle
\begin{center}
\begin{asy}
size(6cm);
draw(unitcircle);
draw( (0.3,0.3)--(0.3,0.4) );
draw( (-0.3,0.3)--(-0.3,0.4) );
draw( (0.6,-0.2)..(0,-0.4)..(-0.6,-0.2) );
\end{asy}
\end{center}
\end{document}
To reiterate, the 3 commands you should be running
(after cd
-ing to the directory with these files, of course) are:
pdflatex meow
asy meow-1.asy
pdflatex meow
Automating the workflow with latexmk
In principle, you can run this three-step process by hand each time you change the diagrams on your page. But this is super annoying.
Fortunately, there’s a program called latexmk
which,
among many other nice LaTeX features, can help run this entire process for you.
I didn’t show this setup in the video because it’s OS-dependent1
but here are some hints about how you might do this.
Of course, you should first install latexmk
.
Matthias Geier has installation instructions on mg.readthedocs.io.
As before, you can verify it’s installed by seeing if latexmk --version
produces a sensible output:
Latexmk, John Collins, 7 Jan. 2023. Version 4.79
Now, as explained on mg.readthedocs.io above about “crazy stuff”,
latexmk
has a configuration file called latexmkrc
that lets you define subroutines.
The Asymptote authors, recognizing the power of latexmk
, wrote such a
subroutine
for automatically compiling only changed Asymptote diagrams.
If you copy-paste these lines into latexmk’s configuration file,
it should automatically do the right thing.
See the LaTeX usage page
for further instructions on how to do this.
Advanced stuff
Olympiad geometry macros
If you’re using Asymptote to typeset diagrams,
chances are you’d appreciate having commands like circumcircle
.
Back in 2007, the Art of Problem-Solving community had this issue,
and they actually wrote their own packages called
olympiad.asy
and cse5.asy
with definitions for these commands.
However, this is probably not the solution you want to use2,
because it means you have to rely on some nonstandard packages written by
some math olympiad enthusiasts that you’d have to copy back and forth between
every computer you use. It would be a major nuisance, to say the least.
Instead, Asymptote has a built-in module called geometry
already,
that does almost everything you would want in practice.
You could read
the geometry manual
for instructions on how to use it,
or the page
on the Asymptote website,
but you could probably also just copy Evan’s code as a template
and that might be easier than reading the fairly long manual.
Read on to the next section to see how to do this.
Using asydef for geometry and other purposes
In practice, there are some setup commands I want to have automatically done for
every Asymptote picture that I draw.
For example, I like to import geometry;
and then define a
few extra commands3 that I often use, like foot
and orthocenter
.
I also like to make sure amsmath
and amssymb
are active,
and set a reasonable default size for the picture, etc.
If you happen to be using my LaTeX template evan.sty
,
as described in LaTeX FAQ L-3 and
LaTeX FAQ L-4,
then in fact all of my Asymptote shortcuts are already done for you.
Just \usepackage{evan}
and you should be good to go.
Otherwise, the way to do this is to stick an asydef
environment
right after \usepackage{asymptote}
but before \begin{document}
,
containing whatever extra definitions you want to use everywhere.
You can copy the one from
evan.sty on GitHub
if you like; look for the lines \begin{asydef}
and \end{asydef}
and copy
everything in between into your preamble. This is shown in the video.
Bonus: Using CJ Quine’s TSQX
If you really pay attention to Evan’s stream, you might notice that Evan actually generates olympiad geometry diagrams by writing what looks like pseudocode that magically transpiles to Asymptote.
The way this is done is that CJ Quines and I wrote a Asymptote preprocessor where you can write something like
~triangle A B C
D ;= foot A B C
E := midpoint A--B
F' N = (rotate -30 E)(extension A (foot A B C) C E)
circumcircle A B C / 0.2 lightgray /
A--B--C--cycle
A--D
B--F' / dashed blue
to get this figure! It’s a Python script, so this will only be useful to you if you know how to run a Python script.
Help
If you need help, in my public Discord, there’s a channel
called #latex-asy-help-!mwe
that you might drop by.4
Remember to provide minimal examples.
Emails to me may or may not work.
-
It may be a lost cause on Windows, for example. ↩
-
If you really want, though, you can download a copy of these two packages from my dotfiles. I have these because a bunch of legacy code sometimes uses them. ↩
-
For reasons I simply can’t understand, the
geometry
package does define an orthocenter routine — but the name isorthocentercenter
. Seriously. I can’t bring myself to use that, so I defineorthocenter
as an alias fororthocentercenter
. ↩ -
For OTIS students, the OTIS Discord has an analogous channel called
#latex-asy-linux-git-etc
. ↩