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.

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

Emails to me may or may not work.