This was originally LaTeX FAQ L-8, but it became so long that I decided it deserved its own page.

Video screencast#

Gallery#

Here are some examples of pictures you can make with Asymptote. You can view the source code on GitHub.

---

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, as described in LaTeX FAQ. (Overleaf is not sufficient for this tutorial; see FAQ 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. (If you’re using Windows with MikTeX, this might pull a really old version of asy that’s bundled into MikTeX, which has been known to cause issues. You may have to instead type the long string "C:/Program Files/Asymptote/asy.exe" instead of asy in what follows.)

---

The main workflow#

Once you have Asymptote installed, to integrate it with LaTeX, the compilation workflow requires three steps.

1. Run PDFLaTeX on, say, meow.tex. This creates meow-N.asy for the N’th diagram.
2. You need to then run the Asymptote binary on meow-N.asy to generate meow-N.pdf.
3. 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-dependent¹ 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 use², 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 commands that I often use, like foot. 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.

Exporting from GeoGebra#

GeoGebra Classic 5 supports exporting GeoGebra figures to Asymptote code directly that you can include in your file.

However, the source code generated by this is in my opinion not easy to read. I ended up writing my own Python script to make the source code output a little more presentable; you can pipe the copied Asymptote code to standard input to this program.

As an example, you can watch me export a diagram for IMO 2023/2 at 1:08:20 of this video from my Twitch stream.

Using CJ Quine’s TSQX#

If you really pay attention to Evan’s stream, you might notice that Evan often generates olympiad geometry diagrams by writing what looks like pseudocode that magically transpiles to Asymptote. (One example is 14:30 of this video.)

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.³ Remember to provide minimal examples.

Emails to me may or may not work.