SageTeXを使う

SageTeXパッケージを使うと,Sageによる処理結果をLaTeX文書に埋め込むことができるようになる. 利用するためには,まずSageTeXを「インストール」しておかなければならない(TeXにSageTeXの存在を教える 節を参照).

具体例

ここでは,ごく簡単な例題を通してSageTeXの利用手順を紹介する. 完全な解説ドキュメントと例題ファイルは,ディレクトリ SAGE_ROOT/local/share/doc/sagetex に置いてある. SAGE_ROOT/local/share/texmf/tex/latex/sagetex にあるPythonスクリプトは何か役に立つ場面があるはずだ. 以上の SAGE_ROOT は,Sageをインストールしたディレクトリである.

SageTeXの動作を体験するために,まずSageTeXのインストール手続き(TeXにSageTeXの存在を教える 節)を実行し, 以下のテキストを st_example.tex などという名前で保存しておいてほしい:

警告

このテキストを “live”ヘルプから表示すると命令未定義エラーになる. 正常に表示するためには “static”ヘルプで表示すること.

\documentclass{article}
\usepackage{sagetex}

\begin{document}

Using Sage\TeX, one can use Sage to compute things and put them into
your \LaTeX{} document. For example, there are
$\sage{number_of_partitions(1269)}$ integer partitions of $1269$.
You don't need to compute the number yourself, or even cut and paste
it from somewhere.

Here's some Sage code:

\begin{sageblock}
    f(x) = exp(x) * sin(2*x)
\end{sageblock}

The second derivative of $f$ is

\[
  \frac{\mathrm{d}^{2}}{\mathrm{d}x^{2}} \sage{f(x)} =
  \sage{diff(f, x, 2)(x)}.
\]

Here's a plot of $f$ from $-1$ to $1$:

\sageplot{plot(f, -1, 1)}

\end{document}

この st_example.tex をいつも通りにLaTeXで処理する. するとLaTeXは以下のような文句をつけてくるだろう:

Package sagetex Warning: Graphics file
sage-plots-for-st_example.tex/plot-0.eps on page 1 does not exist. Plot
command is on input line 25.

Package sagetex Warning: There were undefined Sage formulas and/or
plots. Run Sage on st_example.sagetex.sage, and then run LaTeX on
st_example.tex again.

注目してほしいのは,LaTeXが通常の処理で生成するファイル群に加えて, st_example.sage というファイルが出来ていることだ. これは st_example.tex の処理畤に生成されたSageスクリプトで,上で見たLaTeX処理時のメッセージは,この st_example.sage をSageで実行せよという内容である. その通り実行すると st_example.tex を再びLaTeXで処理せよと告げられるが,その前に新しいファイル st_example.sout が生成されていることに注意. このファイルにはSageの演算結果がLaTeXテキストに挿入して利用可能な形式で保存されている. プロット画像のEPSファイルを含むディレクトリも新規作成されている. ここでLaTeX処理を実行すると,Sageの演算結果とプロットの全てがLaTeX文書に収められることになる.

上の処理に用いられた各マクロの内容はごく簡単に理解できる. sageblock 環境はSageコードを入力通りに組版し,ユーザーがSageを動かすとそのコードを実行する. \sage{foo} とすると, Sage上で latex(foo) を実行したのと同じ結果がLaTeX文書に挿入される. プロット命令はやや複雑だが,もっとも単純な場合である \sageplot{foo}foo.save('filename.eps') を実行して得られた画像を文書へ挿入する役割を果たす.

要するに,必要な作業は以下の三段階になる:

  • LaTeXで .texファイルを処理
  • 生成された .sageファイルをSageで実行
  • LaTeXで .texファイルを再処理

作業中にLaTeX文書内のSageコマンドを変更しない場合,Sageによる処理は省略することができる.

SageTeXは到底以上で語り尽せるものでなく,SageとLaTeXは共に複雑で強力なツールだ. SAGE_ROOT/local/share/doc/sagetex にあるSageTeXのドキュメントを読むことを強くお勧めする.

TeXにSageTeXの存在を教える

Sageはおおむね自己完結的なシステムなのだが,正しく機能するために外部ツールの介入を要する部分があることも確かだ. SageTeXもそうした部分の一つである.

SageTeXパッケージを使えばSageによる演算やプロットをLaTeX文書に埋め込むことが可能になる. SageTeXはデフォルトでSageにインストールされるが,LaTeX文書で利用する前に,運用しているTeXシステムへSageTeXの存在を教えておかねばならない.

鍵になるのは, TeXが sagetex.sty を発見できるかどうかである. この sagetex.sty は, SAGE_ROOT をSageがビルトあるいはインストールされたディレクトリとすると, SAGE_ROOT/local/share/texmf/tex/latex/sagetex/ に置かれているはずだ. TeXが sagetex.sty を読めるようにしてやらなければ,SageTeXも動作できないのである. これを実現するには何通りかのやり方がある.

  • 第一の,かつ一番簡単な方法は, sagetex.sty を作成すべきLaTeX文書と同じディレクトリ内にコピーしておくことである. TeXは組版処理の際に現ディレクトリを必ずサーチするから,この方法は常に有効だ.

    ただし,このやり方には二つのちょっとした問題点がある. 一つ目は,このやり方では使用しているシステムが重複した sagetex.sty だらけになってしまうこと. 二つ目の,もっと厄介な問題は,この状態でSageが更新されてSageTeXも新しいバージョンになった場合,SageTeXを構成するPythonコードやLaTeXコードとの食い違いが生じて実行時にエラーが発生しかねない点である.

  • 第二の方法は,環境変数 TEXINPUTS を利用することである. bashシェルを使っているなら

    export TEXINPUTS="SAGE_ROOT/local/share/texmf//:"
    

    と実行すればよい.ただし SAGE_ROOT はSageのインストール先ディレクトリである. 上の実行例では,行末にスラッシュ2個とコロンを付け忘れないでいただきたい. 実行後は,TeXと関連ツールがSageTeXスタイルファイルを見つけられるようになる. 上のコマンド行を .bashrc に付加して保存しておけば設定を永続させることができる. bash以外のシェルを使っている場合, TEXINPUTS 変数を設定するためのコマンドも異なる可能性がある. 設定法については,自分の使っているシェルのドキュメントを参照のこと.

    この方法にも瑕はある. ユーザがTeXShopやKile,あるいはEmacs/AucTeXなどを使っている場合,必ずしも環境変数を認識してくれるとは限らないのである. これらのアプリケーションが常にシェル環境を通してLaTeXを起動するわけではないからだ.

    インストール済みのSageを移動したり,新バージョンを旧版とは違う場所にインストールした場合, 先に紹介したコマンドも新しい SAGE_ROOT を反映させるように変更する必要がある.

  • TeXに sagetex.sty の在処を教える第三の(かつ最善の)方法は,このスタイルファイルを自分のホームディレクトリのどこか都合のよい所にコピーしておくことだ. TeXディストリビューションの多くは,パッケージを求めてホームディレクトリにある texmf ディレクトリを自動的に探索するようになっている. このディレクトリを正確に特定するには,コマンド

    kpsewhich -var-value=TEXMFHOME
    

    を実行する.すると /home/drake/texmf/Users/drake/Library/texmf などと表示されるはずだから, SAGE_ROOT/local/share/texmf/ 内の tex/ ディレクトリをホームディレクトリの texmf にコピーするには

    cp -R SAGE_ROOT/local/share/texmf/tex TEXMFHOME
    

    などとする. もちろん, SAGE_ROOT を実際にSageをインストールしたディレクトリとするのはこれまでと同じことで, TEXMFHOME は上で見た kpsewhich コマンドの結果で置き換える.

    SageをアップグレードしたらSageTeXがうまく動かなくなったという場合は,上記の手順をもう一度繰り返すだけでSageTeXのSageとTeX関連部分が同期する.

  • 複数ユーザに対応するシステムでは,以上の手続きを変更して sagetex.sty を公開運用中のTeXディレクトリにコピーすればよい. おそらく一番賢いコピー先は TEXMFHOME ディレクトリではなく,コマンド

    kpsewhich -var-value=TEXMFLOCAL
    

    の実行結果に従うことだろう.出力は /usr/local/share/texmf のようになるはずで, 上と同じように tex ディレクトリを TEXMFLOCAL ディレクトリ内にコピーする. ついでTeXのパッケージデータベースを更新しなければならないが,これは簡単で,ルート権限で

    texhash TEXMFLOCAL
    

    と実行すればよい.ただし TEXMFLOCAL を現実に合わせて変更するのは先と同じだ. これでシステムの全ユーザはSageTeXパッケージへアクセス可能になり,Sageが利用できればSageTeXも使えるようになる.

警告

肝心なのは,LaTeXが組版処理時に使う sagetex.sty ファイルと,Sageが援用するSageTeXのバージョンが一致していることである. Sageを更新したら,あちこちに散らばった古いバージョンの sagetex.sty を面倒でも全て削除してやらなければいけない.

SageTeX関連ファイルをホームディレクトリの texmf ディレクトリ内にコピーしてしまうこと(先に紹介した第三の方法)をお勧めするのは,この面倒があるからである. 第三の方法にしておけば,Sage更新後もSageTeXを正常に動作させるために必要な作業はディレクトリを一つコピーするだけになる.

SageTeXドキュメント

厳密にはSageのインストール一式には含まれないものの,ここで SageTeXのドキュメントが SAGE_ROOT/local/share/doc/sagetex/sagetex.pdf に配置されていることに触れておきたい. 同じディレクトリには例題ファイルと,これをLaTeXとSageTeXによってすでに組版処理した結果も用意されている(example.texexample.pdf を参照). これらのファイルは SageTeX bitbucket ページ からダンロードすることもできる.

SageTeXとTeXLive

混乱を招きかねない問題点の一つとして,人気あるTeXディストリビューション TeXLive 2009 にSageTeXが含まれている現実があげられる. これは有り難い感じがするかもしれないが,SageTeXに関して重要なのはSageとLaTeXの各要素が同期していることだ. SageとSageTeXは共に頻繁にアップデートされるがTeXLiveはそうではないから,その「同期」のところで問題が生じる. この文の執筆時点(2013年3月)では,多くのLinuxディストリビューションが新しいTeXLiveリリースに移行しつつある. しかし2009リリースもしぶとく生き残っていて,実はこれがSageTeXに関するバグレポートの主要な発生源になっているのだ.

このため 強く推奨 させていただきたいのは,SageTeXのLaTeX関連部分は以上で説明したやり方で常にSageからインストールすることである. 上記の手順に従えば,SageTeXのSageおよびLaTeX対応部分の互換性が保証されるから,動作も正常に保たれる. SageTeXのLaTeX対応部分をTeXLiveから援用することはサポート対象外になる.