Unable to locate 'pdflatex'

[epelofske-LANL]

Issue Description

While attempting to generate a visual of a circuit, I get the error FileNotFoundError: Unable to locate 'pdflatex'.

How to Reproduce

Code Snippet

from pyquil import Program, latex
STRING = "LARGE PROGRAM HERE"
prog = Program(STRING)
latex.display(prog)

Error Output

  File "/Users/user/file.py", line 4, in <module>
    latex.display(prog)
  File "//anaconda3/envs/env/lib/python3.9/site-packages/pyquil/latex/_ipython.py", line 54, in display
    raise FileNotFoundError("Unable to locate 'pdflatex'.")
FileNotFoundError: Unable to locate 'pdflatex'.

Environment Context

Operating System: macOS

Python Version (python -V): Python 3.9.7

Quilc Version (quilc --version): 1.23.0

QVM Version (qvm --version): 1.17.1

Python Environment Details:

conda list | grep pyquil: pyquil                    3.0.1                    pypi_0    pypi
pip freeze | grep pyquil : pyquil==3.0.1

[dbanty]

Hey @epelofske-LANL, calling latex.display requires that you have pdflatex and convert installed and accessible in your shell path (as documented in the docstring). Unfortunately, it doesn't look like that module is being documented on our docs page, we should definitely fix that!

I'm curious where you discovered this feature? It would be good to also include a link to the relevant documentation (once it exists) from there.

[epelofske-LANL]

@dbanty Ah that makes more sense; I do not think convert is installed on my machine. Thanks!

I originally found this feature here https://pyquil-docs.rigetti.com/en/v2.22.0/apidocs/visualization.html

[dbanty]

Hm, looks like we also left that page out when migrating to v3. @notmgsk any idea why we nixed that? Should we add it back in along with instructions for installing the necessary dependencies?

[epelofske-LANL]

Can you point me to where I can get the convert package?

I found pdflatex in basictex for macOS.

[dbanty]

convert is a CLI tool as part of Image Magick. For macOS that should be brew install imagemagick, but there is some configuration that needs to be done to work with PDFs, so you might still get some errors. I'm also not positive which versions of imagemagick are supported. Please let me know if you encounter any further errors along the way so we can document the eventual final solution for macOS users.

For Debian/Ubuntu users, these instructions should work, I believe we use this in some notebook setup:

sudo apt-get update 
sudo apt-get install -y texlive \
    texlive-latex-extra \
    texlive-pictures \
    imagemagick \
    ghostscript
sed -i 's/<policy domain="coder" rights="none" pattern="PDF" \/>/<policy domain="coder" rights="read | write" pattern="PDF" \/>/g' /etc/ImageMagick-6/policy.xml