Something interesting

We are what we repeatedly do. Excellence, therefore, is not an act, but a habit.

HOWTO: Asymptote on Ubuntu – quick and dirty way

Posted by yuzhou on December 31, 2006

Asymptote, inspired by Metapost but with a much readable (C++-like) syntax, has evolved rapidly (1.20 as of the end of 2006). However, in Ubuntu 6.10, the included version is still 1.03 (released in March 2006) with very limited functionality in Flowcharting and in some other advanced features. After a brief reading on the Asymptote online document, I think, it is time to assemble a quickstart tutorial or guide. Let’s get started now.

Install latest version on Ubuntu (or Debian) (source)

To install the latest version of Asymptote on a Debian-based distribution (e.g. Ubuntu, Mepis, Linspire) you can either compile from UNIX source or use the Alien program to convert the Linux RPM asymptote-x.xx-1.i386.rpm available on the Asymptote download page into a deb file suitable for installation via Dpkg:

1. Install Alien (if not installed already):

sudo apt-get install alien

2. Convert the rpm into a deb:

sudo alien –to-deb –scripts –keep-version asymptote-x.xx-1.i386.rpm

3. Use Dpkg to install (or upgrade) the generated deb file into your system:

sudo dpkg -i asymptote_x.xx-1_i386.deb

Hello world!

The easiest way to experience Asymptote is the interactive mode.

  • open a terminal;
  • type asy;
  • type draw((0,0)--(100,0)--(100,100)--cycle);

What happens then? See the gv window with a triangle? Now what? Keep going.

  • type draw((0,0)--(100,0)--(0,100)--cycle);
  • if you have xpdf install, type help, you will get the pdf version of manual – same as the online manual;
  • if you want more information, you shall finish this quickstart tutorial, study the online manual, and then study some examples (please see the bottom of this post).

WYSIWYG – Vim way

1. prepare vim editing mode by following the customization instructions (note: for Ubuntu, the default directory is /usr/share/asymptote, not /usr/local/share/asmptote.)

cp /usr/local/share/asymptote/asy.vim ~/.vim/syntax/asy.vim

and add the following to their ~/.vimrc file:

augroup filetypedetect
au BufNewFile,BufRead *.asy setf asy
augroup END
filetype plugin on

If any of these directories or files don’t exist, just create them. To set vim up to run the current asymptote script using :make just add to ~/.vim/ftplugin/asy.vim:

setlocal makeprg=asy\ %
setlocal errorformat=%f:\ %l.%c:\ %m

2. wysiwyg way: make an empty .asy file (e.g. ex,asy) and compile to a dummy .eps file (e.g. ex.eps), then open the eps file in gv. you can use a line of commands: echo "draw((0,0));" >ex.asy; asy ex.asy; gv ex.eps &; vi ex.asy
or make a shell script:

echo "draw((0,0));" >$1.asy
asy $1.asy
gv $1.eps &
vi $1.asy

then here we go:

  • keep editing the file until you wanna see the effect;
  • use :w and :make to save and build the eps file;
  • reload in gv to see the result.

WYSIWYG – Emacs way

First, customize emacs editing mode (brief explanation) as below:

Users of emacs can edit Asymptote code with the mode asy-mode, after enabling it by putting the following lines in their .emacs initialization file, replacing ASYDIR with the location of the Asymptote system directory (by default, /usr/local/share/asymptote or /usr/share/asymptote (on Ubuntu) or c:\Program Files\Asymptote under MSDOS):

(add-to-list 'load-path "ASYDIR")
(autoload 'asy-mode "asy-mode.el" "Asymptote major mode." t)
(autoload 'lasy-mode "asy-mode.el" "hybrid Asymptote/Latex major mode." t)
(autoload 'asy-insinuate-latex "asy-mode.el" "Asymptote insinuate LaTeX." t)
(add-to-list 'auto-mode-alist '("\\.asy$" . asy-mode))

Particularly useful key bindings in this mode are C-c C-c, which compiles and displays the current buffer, and the key binding C-c ?, which shows the available function prototypes for the command at the cursor. For full functionality you should also install the Apache Software Foundation package two-mode-mode.

Then you are off to go.

  • emacs ex.asy to start editing;
  • ife[F3] to apply a if () {} else {} template – use M-Left/Right (Alt-Left/Right) to jump among the hotspots;
  • C-c C-c to compile and view (but you have to close the gv to return back to editing mode);
  • C-c ? for a quick reference for the command .

LaTeX way (LaTeX usage)
Similar to PGF/TikZ, you can embed Asymptote codes inside your LaTeX documents. Please follow the below quota (borrowed from here). By this way, you can use above WYSIWYG ways (Vim or Emacs) to work on individual figures. Then you can simply copy and paste the Asymptote codes into your LaTeX documents without worrying about making up a whole bunch of filenames for them.

Asymptote comes with a convenient LaTeX style file asymptote.sty that makes LaTeX Asymptote-aware. Entering Asymptote code directly into the LaTeX source file, at the point where it is needed, keeps figures organized and avoids the need to invent new file names for each figure. Simply add the line \usepackage{asymptote} at the beginning of your file and enclose your Asymptote code within a \begin{asy}\end{asy} environment. As with the LaTeX comment environment, the \end{asy} command must appear on a line by itself, with no leading spaces or trailing commands/comments.

The sample LaTeX file below, named latexusage.tex, can be run as follows:

latex latexusage
asy latexusage
latex latexusage


pdflatex latexusage
asy latexusage
pdflatex latexusage

If the inline option is given to the asymptote.sty package, inline LaTeX code is generated instead of EPS files. This makes LaTeX symbols visible to the \begin{asy}…\end{asy} environment. In this mode, Asymptote correctly aligns LaTeX symbols defined outside of \begin{asy}…\end{asy}, but treats their size as zero; an optional second string can be given to Label to provide an estimate of the unknown label size.

Note that if latex is used with the inline option, the labels might not show up in DVI viewers that cannot handle raw PostScript code. One can use dvips/dvipdf to produce PostScript/PDF output (we recommend using the modified version of dvipdf in the Asymptote patches directory, which accepts the dvips -z hyperdvi option).

An excellent tutorial by Dario Teixeira on integrating Asymptote and LaTeX is available at here.

Still missing Quick Reference

Comparing to Metapost, Asymptote is still lack of a quickstart tutorial and a handy cheatsheet or a quick reference card. Maybe this blog entry can serve the first purpose. And maybe this Wikibook, when completed, can serve the second purpose. A incomplete Chinese tutorial can be found here or here (Unfortunately, he won’t be able to finish it.). And if I find a cheatsheet from the Internet, or if I happen to have some time and make one, I will update here.

Meanwhile, learning by examples is still the most effective way. Please find some examples here, and here. Also, after you install the Asymptote, you can find tons of examples at /usr/(local)/share/doc/asymptote/examples/.


4 Responses to “HOWTO: Asymptote on Ubuntu – quick and dirty way”

  1. Andrea said

    I followed the guide, but I get the following error:

    asy: error while loading shared libraries: cannot open shared object file: No such file or directory

    What does this mean?

  2. yuzhou said

    Most likely, you are using a prebuilt package, maybe converted from RPM, aren’t you?

    If that’s the case, it uses gsl, The GNU Scientific Library, by default. Then, you have to install gsl by using sudo apt-get install gsl, or more directly sudo apt-get install libgsl0 gsl-bin. Then you are off to go.

  3. Andrea said

    Thank you. This fixes my issue.

  4. Ben said

    For ubuntu 8.04, just “sudo apt-get install asymptote python-imaging-tk” The extra python package only matters if you want to run xasy. It is there since it was left off as a dependency for 8.04, but newer ubuntu releases have it properly listed as a dependency.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: