Next: GNU MPCの著作権 [Index]
このマニュアルは，GNU多倍長精度複素演算ライブラリ1.3.0のインストール方法と使い方を解説しています。
Next: GNU MPCの紹介, Previous: GNU MPC, Up: GNU MPC [Index]
GNU MPC はフリーソフトウェアです。フリーソフトウェア財団(FSF)によって公開されているGNU劣等一般公衆利用許諾契約書（GNU Lesser General Public License）の条件の下で，バージョン3または（あなたの選択により）それ以降の任意のバージョンに従って，再配布および/または改変することができます。
GNU MPC は有用であることを期待して配布されていますが，無保証です。商品として，もしくは，特定の目的に向いているかどうかの暗黙の保証すらありません。詳細については，GNU劣等一般公衆利用許諾契約書をご覧下さい。
このプログラムにはGNU劣等一般公衆利用許諾契約書のコピーが付属しているはずです(訳注：本文書最後に提示）。もし付属していない場合は，http://www.gnu.org/licenses/ をご覧下さい。
Next: GNU MPCのインストール, Previous: GNU MPCの著作権, Up: GNU MPC [Index]
GNU MPCはCで記述された，正確な丸めをサポートするポータブルな任意精度複素演算ライブラリで， C99標準に則った多倍長精度計算を実装しています。ライブラリ構築のためには， GNU MPとGNU MPFRライブラリが不可欠です。
まずはGNU MPCの基礎を読んで下さい。自分で本ライブラリをインストールするのであれば， GNU MPCのインストールも読むべきでしょう。
それ以外の部分は参照用ですが，ざっと目を通しておくことをお勧めしておきます。
Next: バグ報告, Previous: GNU MPCの紹介, Up: GNU MPC [Index]
GNU MPCをビルドするには，まずコンピュータにGNU MP（バージョン 5.0.0 以上）とGNU MPFR（バージョン 4.1.0 以上）をインストールしておく必要があります。また，Cコンパイラも必要です。GNU MPCのコンパイルのためには，古いバージョンのGCCではバグを引き起こす可能性があるため，GCCバージョン4.4以上を使うことが推奨されています。詳細は次のスレッドを参照して下さい： https://sympa.inria.fr/sympa/arc/mpc-discuss/2011-02/msg00024.html。
また，標準のUnix ‘make’ プログラムと，その他の標準的なUnixユーティリティプログラムが必要です。
Unixシステムにライブラリをインストールするために必要な手順は以下の通りです：
GMPとGNU MPFRが標準ディレクトリにインストールされている場合，つまりコンパイラとリンクツールがデフォルトでパスの通ったディレクトリにインストールされている場合は，このコマンドで設定を行います。
GMPが別の場所にインストールされている場合は，次のコマンドを使用してその場所を指定します： ‘./configure --with-gmp=<gmp_install_dir>’。
あるいは，GMPのインクルードディレクトリとライブラリディレクトリを直接指定することもできます： ‘./configure --with-gmp-lib=<gmp_lib_dir> --with-gmp-include=<gmp_include_dir>’。
同様に，GNU MPFRが別の場所にインストールされている場合は次のコマンドを使用します： ‘./configure --with-mpfr=<mpfr_install_dir>’。
あるいは，GNU MPFRのインクルードディレクトリとライブラリディレクトリを直接指定することもできます： ‘./configure --with-mpfr-lib=<mpfr_lib_dir> --with-mpfr-include=<mpfr_include_dir>’。
もう一つ便利なパラメータは ‘--prefix’ で，これを使用して /usr/local ではなく別のインストール場所を指定することができます。詳細は，以下の ‘make install’ を参照して下さい。
make check 中に valgrind を使用してメモリリークのチェックを行うには，--enable-valgrind-testsオプションを追加します。
デバッグ目的で，コード内からGNU MPC関数の呼び出しをログに記録したい場合は，‘--enable-logging’オプションを追加します。その場合，コード内で mpc.h の代わりに mpc-log.h をインクルードし，実行ファイルを動的にリンクします。すると，複素数引数のみを持つ関数のすべての呼び出しが次の形式で stderr に出力されます。最初に関数名が表示され，その後に ‘c_cc’ のようなタイプが続きます。これは，関数が2つの複素引数から計算された1つの複素数の結果（前の ‘_’ の前に1つの ‘c’）を持つことを意味します。次に，結果の実部と虚部の精度が順番に表示され，各引数についてその実部と虚部の精度桁数が指定され，引数自体が16進数で mpc_out_str 関数を介して出力されます（see 文字列と入出力ストリーム）。
このオプションは動的ライブラリが必要であるため，--disable-sharedオプションとは併用できません。
完全なオプションのリストは‘./configure --help’で見ることができます。
これにより，作業ディレクトリ内でGNU MPCがコンパイルされます。
これにより，GNU MPCが正しくビルドされたことを確認します。
エラーメッセージが表示された場合は，‘mpc-discuss@inria.fr’ に報告して下さい（有用なバグ報告に必要な情報については See バグ報告 を参照して下さい）。
これにより，mpc.h ファイルが /usr/local/include ディレクトリに，libmpc.a ファイルが /usr/local/lib ディレクトリに，mpc.info ファイルが /usr/local/share/info ディレクトリにコピーされます（または，‘--prefix’ オプションを configure に渡した場合は，/usr/local の代わりに指定したプレフィックスディレクトリにコピーされます）。注意：これらのディレクトリに書き込み権限が必要です。
他にもいくつか便利なmakeターゲットがあります：
マニュアルのinfoバージョンを mpc.info に作成します。
マニュアルのPDFバージョンを doc/mpc.pdf に作成します。
マニュアルのDVIバージョンを doc/mpc.dvi に作成します。
マニュアルのPostscriptバージョンを doc/mpc.ps に作成します。
マニュアルのHTMLバージョンを複数のページに分けて doc/mpc.html ディレクトリに作成します。1つのHTMLファイルにまとめたい場合は，代わりに ‘makeinfo --html --no-split mpc.texi’ を実行します。
すべてのオブジェクトファイルとアーカイブファイルを削除しますが，設定ファイルは削除しません。
配布ソースに含まれていないすべてのファイルを削除します。
‘make install’ でコピーされたすべてのファイルを削除します。
AIXでは，GMPが64ビットABIでビルドされている場合，GNU MPCをビルドおよびテストする前に，‘OBJECT_MODE’ 環境変数を64に設定する必要があるかもしれません。例えば，次のようにします：
‘export OBJECT_MODE=64’
これは，Cコンパイラ IBM XL C/C++ Enterprise Edition V8.0 for AIX バージョン 08.00.0000.0021，GMP 4.2.4，およびGNU MPFR 2.4.1でテストされています。
その他の問題が発生した場合は，‘mpc-discuss@inria.fr’ に報告して下さい。 See バグ報告.
Next: GNU MPCの基礎, Previous: GNU MPCのインストール, Up: GNU MPC [Index]
もしGNU MPCライブラリにバグを発見したと思ったら，調査の上，その報告を行って下さい。このライブラリはあなたが利用できるように提供したもので，あなたからの対価払いを要求するものではありませんが，バグを発見した際には報告をお願いしても罰は当たらんと考えます。
バグ報告を作成する際に考慮して欲しい，いくつかのポイントがあります。
私たちがバグを再現できるようにするためのテストケースを送って下さい。テストケースの実行方法についての指示も含めて下さい。
何が問題なのかも説明する必要があります。クラッシュが発生した場合や，出力結果が不正確な場合は，その不正確さの具体的な内容を説明して下さい。
バグ報告にはコンパイラのバージョン情報も含めて下さい。これは，‘gcc -v’ または，一部のマシンでは ‘cc -V’ を使用して取得できます。また，‘uname -a’ の出力も含めて下さい。
良いバグ報告であれば，ライブラリの修正版を提供するために最善を尽くしますが，報告内容が不十分であれば，それに対して何もしないか，より良いバグ報告を送るように促すだけです。
バグ報告は ‘mpc-discuss@inria.fr’に送って下さい。
このマニュアルの内容に不明確なところがある，あるいは誤りがある，または言語表現が改善されるべきだと感じた場合も，同じアドレスにご連絡をお願い致します。
GNU MPCを使うために必要となる修飾子は全てmpc.hにまとめてあり， CコンパイラでもC++コンパイラでも使用できるようになっています。 GNU MPCを利用するプログラムでは，
#include "mpc.h"
のように，このファイルをインクルードしておいて下さい。
複素数(Complex number)，もしくは複素(Complex)と略しますが，これは2つの任意精度浮動小数点数（実部と虚部）を一組
とするデータ型を意味します。
Cのデータ型としてはmpc_tとして定義されています。
計算精度(Precision)とは，実部と虚部を表現するために必要とする仮数部ビット長を意味します。
これを保持するCのデータ型はmpfr_prec_tです。
使用できる計算精度長範囲については
GNU MPFRマニュアルの「用語とデータ型」の節を参照して下さい。
丸めモード（rounding mode）は，複素演算の結果が格納先の仮数部長に収まらない場合に，その結果を丸める方法を指定するものです。
丸めモードはmpc_rnd_tというCデータ型を使用します。
複素演算の丸めモードは，実部と虚部それぞれの丸めモードの組として指定します。
GNU MPCライブラリの関数は，複素演算用の関数群一種類しかなく，全てmpc_から始まる名前が付けられています。
複素数のデータ型はmpc_tです。
GNU MPCの関数の引数は，出力用の引数が入力用の引数の前に来るように配置されます。 この流儀は，代入演算子の配置から頂いています。
GNU MPCでは，関数を使用する際， 入力用と出力用に同じ変数を引数として指定することができるようになっています。
例えば，乗算用としてmpc_mul関数を使う場合，mpc_mul (x, x, x, rnd_mode)と指定することができます。
このようにすることで，xの2乗を求め，rnd_modeで指定した方式で丸め，その結果をxに書き戻すことができます。
GNU MPCの変数は代入をする前に，特別な関数を用いて初期化しておく必要があります。 複素変数を使って処理を行う際には，初期化関数を使って変数領域をクリアしなくてはいけません。
変数は一度は初期化しておくべきもので，もう一度使う際には一度クリアしておく必要があります。 一度初期化しておけば代入は何度でも可能です。
性能を上げるためには，ループの中で変数を初期化したりクリアしたりの繰り返しを避けるべきです。 ループの前に初期化し，ループを抜けてからクリアするようにしましょう。
GNU MPCの変数に対して追加的なメモリ割り当てを考える必要はありません。なぜなら 実部，虚部はぞれぞれ独立した固定長の仮数部を持っているので，この仮数部長を変更したり，変数を クリアして再初期化したりしない限り，プロセスが生きているうちは複素変数は同じ初期化済みのメモリ 空間を保持し続けることになるからです。
複素浮動小数点演算の丸めモードはMPC_RNDxyという形式で指定します。ここで
xとyは，N (最近偶数丸め), Z (ゼロ方向丸め（切り捨て））
, U (正の無限大方向丸め), D (負の無限大方向丸め),
A (ゼロから遠ざかる丸め。つまり，丸められる数の符号に従って正負の無限大方向を決定する）が入ります。
最初のxは実部の丸めモード指定，2番目のyは虚部の丸めモード指定となります。
例えばMPC_RNDZUは，実部が切り捨て，虚部が正の無限大方向丸めを意味します。
最近偶数丸め(‘round to nearest’)モードは，IEEE P754規格が定めているものです。 対象となる数が表現可能な浮動小数点数間のちょうど真ん中である時は，最小桁がゼロになるように 丸められます。 例えば5の場合，2進数では(101)と表現されますが，これを2ビットに丸める場合は(100)=4になり， (110)=6とはなりません。
GNU MPCが提供する多くの関数はint型の返り値となっています。これは丸められた実部と虚部が，
丸め前の無限桁精度の値に対してどの位置になったのかということを示しています。
返り値の整数がiである時，MPC_INEX_RE(i)とMPC_INEX_IM(i)
というマクロ値が0であれば，丸められた両者の値が正しいことを意味します。
これらが負であれば，丸め前の無限精度の値より小さくなっていることを意味し，
正であれば，丸めによって大きくなっていることを意味しています。
mpfr_t型の値を求める（例:絶対値など）関数も同様に整数を返し，0, 正値，負値
のいずれかが，丸められた値が正しいか，大きくなっているか，小さくなっているかによって
決まります。
上記以外の，mpc_sin_cos等，二つの複素数値を求める関数の場合は，
MPC_INEX1(i)とMPC_INEX2(i)というマクロ値を返します。前者が最初の
計算値に対する丸めの結果を表し，後者が2つ目の計算値に対する丸めの結果をそれぞれ
表現しています。
複素関数には不連続となる分枝の扱いを考える必要のあるものがいくつか存在しています。 GNU MPCでは，ISO C99標準規格でこれらの扱いについて定めている関数については， この規格に準拠した分枝を実装しています。
同様に，実部か虚部が無限大，NaN(非数)，符号付ゼロになってしまう評価点では， ISO C99標準規格が定める値を返すように実装しています。
Next: 球演算(Ball Arithmetic), Previous: GNU MPCの基礎, Up: GNU MPC [Index]
複素演算関数は引数にmpc_t型の値を受け付けるようになっています。
GNU MPCの浮動小数点演算関数は，
GNU MPの整数関数と類似したインターフェースを備えており，複素演算用の演算関数はmpc_から始まる関数名になります。
演算精度は次のように決まります。まず要求された演算を正確に（つまり「無限精度で」）実行し，その結果を変数のビット長に収まるよう，指定された 方式で丸めて格納します。
GNU MPCの複素演算関数は，IEEE P754演算の自然な拡張になっています。一台のマシン上で計算された結果が ワードサイズの異なる別のマシン上で得られた結果と異なるようなことは基本ありません。
mpc_t型のオブジェクトは最初に値を代入する前に初期化しておく必要があります。
mpc_init2関数とmpc_init3関数はそのために使用されるものです。
複素変数zをprec bit長の精度で初期化し，実部と虚部にNaNを代入します。
通常，変数の初期化と，mpc_clear関数を用いたクリアは，再初期化前に一度だけ実行しておけば十分です。
複素変数zを，実部は prec_r bit長の精度で，虚部はprec_i bit長の精度で初期化し，実部と虚部にそれぞれNaNを代入します。
複素変数zが使用しているメモリ領域を解放（クリア）します。
mpc_t型の複素変数をクリアする際には必ずこの関数を使って下さい。
下記は，複素変数を初期化する方法を示したプログラム例です。
{
mpc_t x, y;
mpc_init2 (x, 256); /* 精度は確実に 256 bit長になる */
mpc_init3 (y, 100, 50); /* 実部/虚部は100/50 bit長 */
…
mpc_clear (x);
mpc_clear (y);
}
以下の関数は実行中に変数の精度を変更するためのものです。 例えば，Newton-Raphson法のような反復法の過程で，真の解と一致した桁数に近いところで調整したいとき，ジワジワと精度長を修正する際に使用できます。
複素変数xの精度長を正しく prec bit長に変更し，
実部/虚部にそれぞれNaNを代入します。
当然，xに入っていた値は上書きされます。動作的にはmpc_clear(x)関数の後に
mpc_init2(x, prec)関数を呼び出したものに相当しますが, リセット前のxの精度長が
十分長ければ，この2関数を呼び出すより高速に実行できます。
複素変数xの実部と虚部が同じ精度長である時はその精度長を返し，異なる時は0を返します。 (訳注: 不便だよねこの仕様。mpc_get_prec2関数を使うか，mpfr_get_prec関数で実部・虚部の精度長を取得しましょう。)
複素変数xの実部の精度長をprに，虚部の精度長をpiに格納します。
ここで述べる関数は初期化済みの複素変数に対して新しい値を代入するためのものです(see 初期化関数)。
intmax_t型もしくはuintmax_t型を使用する関数を使う場合は，mpc.hをインクルードする前に
<stdint.h>もしくは<inttypes.h>をインクルードしておき，これらの関数で使用できるようにしておく必要があります。
同様に，complex型もしくは
long complex型を使用する関数を使う場合は<complex.h>を
mpc.hのインクルード前に取り込んでおく必要があります。
現在のMPCのAPIで定義されていない関数はMPC_SET_X_Yマクロを使用している可能性があります（ (see 高度な関数群)。
opを，ropの精度桁に合わせて，rndで指定された丸め方式で丸めてropに代入します。
opを，ropの精度桁に合わせて，rndで指定された丸め方式で丸めてropに代入します。
opが実数と解釈されるものであれば，代入先のropの虚数部は正の符号を持つゼロが代入されます。
long int型であっても，代入先の精度がそれ以下であれば，丸められた値が格納されることをご承知おき下さい。
mpc_set_d関数の場合も,倍精度で正しく表現できないような入力値opである可能性があることをご注意下さい（例えば0.1の時など）。
この場合，Cコンパイラが倍精度の値として丸め，次に複素数に変換します。
op1をropの実部として， op2を虚部として，rndで指定された丸め方式で丸めて代入します。
mpc_set_fr_fr関数については， op1もしくは
op2がropの実部，もしくは虚部へのポインタになっている場合の動作は定義されていませんので
ご注意下さい。
複素数の実部と虚部を入れ替えるためには
mpfr_swap (mpc_realref (rop), mpc_imagref (rop))関数を使うことで，一時変数を介してそれぞれの精度桁数も含めて入れ替えを行ってくれます。
文字列や入力ストリームから複素変数に代入する関数については see 文字列と入出力ストリームの節を参照して下さい。
ropにNaN+i*NaNを代入します。
op1とop2を効率よく入れ替えます。注意：精度桁数が異なる場合はこれも併せて入れ替えられます。
つまり，mpc_swap関数は，一時変数を使ってmpc_set関数を3回呼び出したものと同じ動作にはなりません。
Next: 文字列と入出力ストリーム, Previous: 代入関数, Up: 複素演算関数 [Index]
下記の関数は<complex.h>がmpc.hより前にインクルードされている時のみ使用可能です。
opをrnd指定の丸め方式でCの標準複素数に変換します。
MPCの複素数を文字列もしくは出力ストリームに変換する関数については see 文字列と入出力ストリームを参照して下さい。
基数 base で文字列 nptr から複素数を読み取り，指定された丸めモード rnd で rop の精度に丸めます。
base は 0 または 2 から 36 の範囲内である必要があります（それ以外の場合は動作が未定義です）。
もし nptr が有効なデータで始まる場合，結果は rop に格納され，通常の不正確な値が返されます（see Return Value を参照）し，endptr がヌルポインタでない場合，*endptr は有効なデータの直後の文字を指します。
それ以外の場合，rop は NaN + i * NaN に設定され，-1 が返され，endptr がヌルポインタでない場合，nptr の値が endptr に格納されます。
複素数として表現される文字列の形式は，実数（先頭のホワイトスペースや符号も含めた浮動小数点数）か，括弧内の空白で区切られた実数のペアです。
実数が読み取られた場合，指定されていない虚部は +0 に設定されます。
浮動小数点数の形式は基数に依存し，詳細はmpfr_strtofr のドキュメントに記載されています。
例えば，"3.1415926"，"(1.25e+7 +.17)"，"(@nan@ 2)" および "(-0 -7)" は，base = 10 の場合の有効な文字列です。
base = 0 の場合，浮動小数点数の基数を示すためにプレフィックス（接頭語）を使用できます。2進数には ’0b’，16進数には ’0x’ のプレフィックスを使用し，10進数にはプレフィックスを使用しません。
実部と虚部は異なる基数で記述することができます。
例えば，"(1.024e+3 +2.05e+3)" と "(0b1p+10 +0x802)" は，base=0 の場合の有効な文字列で，同じ値を表します。
rop を，基数 base の文字列 s の値に設定し，指定された丸めモード rnd に従って rop の精度に丸めます。
有効な文字列形式の詳細については，mpc_strtoc のドキュメントを参照して下さい。
mpc_strtoc関数とは異なり，mpc_set_str では，全体の 文字列が有効な複素数を表している必要があります（追加の空白が続く場合もあります）。
この関数は，基数 base において，文字列全体が末尾のヌル文字まで有効な数値である場合，通常の不正確な値を返します（see Return Value を参照）。そうでない場合，-1 を返し，rop は NaN+i*NaN に設定されます。
op を，実部と虚部を含む文字列に変換します。これらは空白で区切られ，括弧で囲まれます。
数値は基数 b（2から36の範囲）で書かれ，rnd に従って丸められます。有効桁数は n によって指定され，少なくとも2桁になります。n を0にすることも可能で，その場合，再び同じ精度で値を読み取ったときに，出力と入力の両方が最近接への丸めを使用することを前提として，op の元の値が復元されるように，桁数が十分に大きく選ばれます。
なお，mpc_get_str は，使用可能であれば現在のロケールの小数点を使用し，そうでなければ ‘.’ を使用します。
この文字列は現在のメモリ割り当て関数（デフォルトでは malloc，ただし gmp のカスタムメモリ割り当てインターフェースで変更されている場合を除く）を使用して生成されます。不要になった場合は，mpc_free_str を呼び出して解放する必要があります。
文字列変数strを解放します。これはmpc_get_str関数で割りつけられた文字列に対して適用します。
下記の関数は入力ストリームから複素数値を読み取り，出力ストリームに複素数値を書き込む際に使用します。 これらの関数を使用する際には，mpc.hをインクルードする前にstdio.hもインクルードしておく必要があります。
標準入力ストリーム stream から，基数 base で mpc_strtoc と同じ形式の文字列を入力し，rnd に従って丸め，読み取った複素数を rop に格納します。
もし stream がヌルポインタである場合，rop は stdin から読み取られます。通常の不正確な値を返し，エラーが発生した場合は rop を NaN + i * NaN に設定し，-1 を返します。
read がヌルポインタでない場合，そのポインタには読み取った文字数が設定されます。
mpc_strtoc関数とは異なり，mpc_inp_str は変換する文字列を完全に把握しているわけではなく，一文字ずつ読み取る必要があるため，動作が若干異なります。複素数を表す文字列を読み取り，この文字列を mpc_set_str の呼び出しを通じて処理します。具体的には，任意の空白をスキップした後，正規表現 mpfr | '(' \s* mpfr \s+ mpfr \s* ')' に従って最小限の文字列が読み取られます。ここで，\s は空白を示し，mpfr は空白や括弧を含まない文字列，もしくは nan(n-char-sequence) または @nan@(n-char-sequence)（大文字・小文字を問わず）であり，n-char-sequence はASCII文字，数字，または '_' を含む文字列です。
例えば，"nan(13 1)" を入力した場合，関数 mpc_inp_str はNaNの値を認識し，開き括弧によってn-char-sequenceが続くと判断します。しかし，空白に達した時点で，括弧内の式がn-char-sequenceではないことが明らかになり，ストリームから6文字が消費された後にエラーフラグ -1 が返されます（空白自体はストリームに残ります）。
一方，関数 mpc_strtoc は空白に到達した時点で追跡を戻し，その文字列を2つの連続した複素数 NaN + i * 0 と 13 + i として処理します。
この問題を避けるためには，各浮動小数点数の後に空白を置くようにして下さい。
opをbase進数でrnd指定の丸め方式で標準ストリームstreamに出力します。出力形式はmpc_strtoc関数の説明の通りです。
streamがNULLポインタであればop(訳注:原著はropになってたが多分間違い）は標準出力（stdout）に表示されます。
返り値は出力した文字数になります。
Next: 射影関数と分離関数, Previous: 文字列と入出力ストリーム, Up: 複素演算関数 [Index]
op1 と op2 を比較します。mpc_cmp_si_si の場合，op2 は op2r + i op2i として扱われます。
返り値 c は x = MPC_INEX_RE(c) と y = MPC_INEX_IM(c) に分解でき，x は，op1 の実部が op2 の実部より大きい場合に正，両方の実部が等しい場合にゼロ，op1 の実部が op2 の実部より小さい場合に負になります。y も同様に虚部について判断します。
op1 と op2 の両方は，それぞれの完全な精度で比較されますが，これらの精度は異なる場合があります。
いずれかのオペランドが NaN（非数）を含むことは許されません。
返り値の格納方法により，mpc_cmp(op1, op2) == 0 を用いて単純に等しいかどうかを確認できます。
op1 と op2 の絶対値を比較します。
両者が同じ場合（無限大を含む）には返り値は 0 です。op1 の絶対値が op2 の絶対値より大きい場合には正の値が，より小さい場合には負の値が返されます。
もし op1 または op2 の実部または虚部が NaN である場合，この関数は少なくとも一方が NaN である2つの実数に対する mpfr_cmp の動作と同じように振る舞います。
opの実部を，rndで指定した方式で丸めてropに代入します。
opの虚部を，rndで指定した方式で丸めてropに代入します。
opの実部と虚部へのポインタをそれぞれ返す関数です。
これらのマクロが返すポインタを使ってmpfr関数が使用できるようになります(注意：mpfr_t型はポインタそのものです）。
ropにopの偏角(argument)を代入します。分枝は負の実軸になります。
opのリーマン球上の射影値を求めます。ropにはrndが指定する方式で丸めて格納されます。 op の少なくとも一方が無限大の場合（もう一方がNaNの場合でも）は ropの実部がプラス無限大に設定され，その虚部は opの虚数部と同じ符号のゼロに設定されます。
Next: べき乗関数と対数関数, Previous: 射影関数と分離関数, Up: 複素演算関数 [Index]
ここで述べる関数は，複素数の代わりに実数であった場合は，多少のオーバヘッドはありますが， GNU MPFRライブラリの関数と同じ計算量で実行されます。
整数を引数とする関数（mpc_add_ui関数など)では，引数がゼロの場合，
符号なしのゼロと解釈され，MPFRの方式同様，
(0) + (+0) = +0, (0) - (+0) = -0, (0) - (+0) = -0, (0) - (-0) = +0.
というように計算されます。
同様にmpfr_t型の変数を引数とする関数（mpc_add_fr関数など）でも実行され，
対応する虚部も符号なしのゼロとなります。
変数ropに，op1 + op2の結果を，rnd方向に丸めて格納します。
rop を，op1 から op2 を引いた値に設定し，rnd に従って丸めます。
mpc_ui_ui_sub の場合，op1 は re1 + i im1 として扱われます。 (訳注: 原文はiが抜けている。）
rop を，op の符号を反転させた値に設定し，rnd に従って丸めます。 rop と op が同じ変数である場合，単に符号が変更されます。
rop を，長さ n の配列 op の要素の合計値に設定し，rnd に従って丸めます。
rop を，op1 に op2 を掛けた値に設定し，rnd に従って丸めます。
注意: mpc_mul において，op1 と op2 が同じ値を持つ場合，効率を向上させるために mpc_sqr を使用して下さい。
rop を，sgn が非負の場合は op に虚数単位 i を掛けた値に，sgn が負の場合は -i を掛けた値に設定し，いずれの場合も rnd に従って丸めます。
rop を，op の二乗に設定し，rnd に従って丸めます。
rop を op1*op2+op3 に設定し，rnd に従って丸めますが，丸めは最終的に一度だけ行われます。
rop を，長さ n の配列 op1 と op2 のドット積に設定し，rnd に従って丸めます。
rop を op1/op2 に設定し，rnd に従って丸めます。
rop を，op の共役複素数に設定し，rnd に従って丸めます。 rop と op が同一の変数である場合，虚部の符号だけが変更されます。
浮動小数点数 rop を，op の絶対値に設定し，rnd の方向に丸めます。
浮動小数点数 rop を，op のノルム（つまりその絶対値の二乗）に設定し，rnd の方向に丸めます。
rop を，op1 に 2 を op2 乗したものを掛けた値に設定し，rnd に従って丸めます。 rop と op1 が同一である場合，実部と虚部の指数だけが op2 によって修正されます。
rop を，op1 を 2 を op2 乗したもので割った値に設定し，rnd に従って丸めます。 rop と op1 が同一である場合，実部と虚部の指数だけが op2 によって修正されます。
rop を，op の平方根に設定し，rnd に従って丸めます。 返される値 rop の実部は非負であり，もしその実部がゼロであれば，虚部も非負となります。
rop を，op1 を op2 乗した値に設定し，rnd に従って丸めます。
mpc_pow_d，mpc_pow_ld，mpc_pow_si，mpc_pow_ui，mpc_pow_z，および mpc_pow_fr の場合，op2 の虚部は +0 と見なされます。
op1 と op2 の両方がゼロの場合，結果は実部が 1，虚部が 0 で，符号は op2 の符号と反対になります。
opの指数関数の値を計算し， rnd方向にropの精度になるように丸め，変数ropに格納します。
rop を，op の自然対数および常用対数にそれぞれ設定し，rnd に従って rop の精度で丸めます。 主枝が選択され，負の実軸に分岐点があるため，結果の虚部は次の範囲に収まります：
]-Pi , Pi]
および
]-Pi/log(10) , Pi/log(10)]
rop を，標準的な原始 n 次単位根を k 乗したもの，すなわち に設定し，rnd に従って rop の精度で丸めます。
rop を，a と b の算術幾何平均（AGM）に設定し，rnd に従って rop の精度で丸めます。 分岐点に関しては，関数は均質性に基づいて計算され，|a| >= |b| の場合は a AGM(1,b0) （b0=b/a）として計算され，それ以外の場合は b AGM(1,b0) （b0=a/b）として計算されます。 そして，b0 が実数で負の場合，AGM(1,b0) は虚部が正の値となるように選ばれます。
Next: モジュラ関数, Previous: べき乗関数と対数関数, Up: 複素演算関数 [Index]
rop を，op の正弦，余弦，または正接に設定し，rnd に従って rop の精度で丸めます。
rop_sin を，op の正弦に設定し，rnd_sin に従って rop_sin の精度で丸め，rop_cos を，op の余弦に設定し，rnd_cos に従って rop_cos の精度で丸めます。
rop を，op の双曲線正弦，双曲線余弦，または双曲線正接に設定し，rnd に従って rop の精度で丸めます。
rop を，op の逆正弦，逆余弦，または逆正接に設定し，rnd に従って rop の精度で丸めます。
opを引数とする逆指数正接，逆指数余弦，逆指数正接の値を求め，
rndropの精度桁数になるようにrnd方向に丸めてropに格納します。
mpc_acosh関数の分枝は
(-Inf, 1)
です。
以下の関数は実験的なものであり，特に同様に実験的な球演算に依存しているため，球演算(Ball Arithmetic) を参照して下さい。そのため，今後のリリースでプロトタイプが変更される可能性があり，完全に削除されることもあります。
引数 op が Sl_2(Z) の基本領域内にあると仮定します。つまり，実部が -1/2 未満でもなく，+1/2 を超えず，絶対値が少なくとも 1 である場合，デデキントのエータ関数の値を rop に返します。 引数が基本領域外にある場合，この関数は無限ループに陥る可能性があります。
単位正方形 [0, 1] \times [0, 1] 内で一様に分布するランダムな複素数を生成します。実部または虚部の指数が現在の指数範囲内にない場合，その部分は NaN に設定され，ゼロ値が返されますが，通常は 0 が返されます。第2引数は，GMP の rand_init 関数で作成される gmp_randstate_t 構造体です。詳細は GMP マニュアルを参照して下さい。
Return the GNU MPC version, as a null-terminated string.
MPC_VERSION は，GNU MPC のバージョンを示すプリプロセッサ定数です。
MPC_VERSION_MAJOR，MPC_VERSION_MINOR，および MPC_VERSION_PATCHLEVEL は，それぞれ GNU MPC のバージョンのメジャー，マイナー，パッチレベルを示すプリプロセッサ定数です。
MPC_VERSION_STRING はバージョンを文字列定数として表したもので，ランタイム時に使用されるヘッダーファイルとライブラリが一致するかを確認するために，mpc_get_version の結果と比較できます：
if (strcmp (mpc_get_version (), MPC_VERSION_STRING)) fprintf (stderr, "Warning: header and library do not match\n");
注意: 異なる文字列が取得された場合，それが必ずしもエラーとは限りません。一般に，古いバージョンの GNU MPC でコンパイルされたプログラムが，新しいバージョンの GNU MPC ライブラリと動的にリンクされることが許容される場合があります（ライブラリのバージョン管理システムによる）。
指定された major，minor，および patchlevel から，MPC_VERSION で使用されるのと同じ形式の整数を作成します。
以下は，コンパイル時にGNU MPCのバージョンを確認する方法の例です：
#if (!defined(MPC_VERSION) || (MPC_VERSION<MPC_VERSION_NUM(2,1,0))) # error "Wrong GNU MPC version." #endif
マクロ MPC_SET_X_Y は，代入関数の本体として使用するために設計されており，それ自体で使用することはできません。
real_suffix と imag_suffix のパラメータは，実部と虚部の型を表しており，それぞれの部分を設定するために使用する mpfr_set_x 関数の x に相当します。mpfr 型の場合は，fr を使用します。
real（および imag）は，実部（および虚部）に代入したい値であり，その型は real_suffix（および imag_suffix）に従う必要があります。
rnd は mpc_rnd_t の丸めモードです。
返り値は通常の不正確な値です（see Return Value を参照）。
このマクロを使うと，例えばmpc_set_ui_fr関数は次のように定義できます。
int mpc_set_ui_fr (mpc_t rop, unsigned long int re, mpfr_t im, mpc_rnd_t rnd)
MPC_SET_X_Y (ui, fr, rop, re, im, rnd);
Next: References, Previous: 複素演算関数, Up: GNU MPC [Index]
バージョン1.3.0以降，GNU MPCは限定的ながら複素球演算(円演算とも呼ぶ）を実装しています。 とはいえ実験的な位置づけですので，将来のバージョンではガラリと変わるか，最悪，全削除 されるかもしれません。
複素球はmpcb_tというデータ型で新規に定義されており，非ゼロのmpc_t型の中心
cと，mpcr_tというこれも新しいデータ型で表現される相対半径rの組み合わせで
構成されています。この結果，全ての複素数は
z = c (1 + ϑ) ここで |ϑ| ≤ rとして表現でき，これは中心cの半径r |c|である閉円
(closed circle)を意味します。
絶対半径の代わりに相対半径を使うことで，加算類（加減算など）で面倒なことになる
乗算類(乗算，除算，平方根，AGM演算)の誤差解析が
楽にできるようになります。
また，球の中心をゼロに設定しない理由は，浮動小数点演算においてゼロが丸めによって得られる値ではなく，より高度なアプリケーションレベル
で制御される，正確な演算結果においてのみ
到達し得るものだからです。この詳細についてはalgorithms.tex(訳注: https://gitlab.inria.fr/mpfr/mpfr/-/blob/master/doc/algorithms.tex)を参照して下さい。
半径のデータ型は下記のように定義されています。
struct {
int64_t mant;
int64_t exp;
}
これらをGNU多倍長精度ライブラリのいつもの手段同様， mpcr_t型を上記の構造体の一次元配列として定義し，
ポインタとしてはmpcr_ptr型，定数ポインタとしてはmpcr_srcptr型と定義しています。
値としては，無限大，ゼロ，そして正の仮数部
mと任意の（通常は負値となる）指数部eから構成される通常の浮動小数点数m⋅2eとなります。
正規化された有限の半径は31ビットの仮数部，すなわち
230≤m≤231 - 1の範囲で定まります。
特殊値である無限大とゼロはmの符号付で表現されますが，使用する関数で確認され，設定されます。
いかなる場合であれ，下記の関数群では半径は正規化されているものとして扱い， 正規化された返り値を返すものとし，かつ，タイトな上限値を得るべく，不用意に最小の表現可能な数にならないよう， 演算結果を丸めます。つまり，出力値は真の値の上限になっていることを保証する訳です。 (計算効率を上げることと，タイトな結果を得ることとはトレードオフの関係にあります。 例えば，32ビットの仮数部を正規化する時，偶数の仮数部は2で割り切れますが，奇数の場合は2で割っても1を加える必要があり， どちらにしても指数部は1つ増えます。 毎回1を加える方が，仮数部の最下部ビットを確認するより効率的になります。)
それぞれ，r が無限大かゼロかをテストし，ブール値を返します。
r < 1/2 であれば true を返し，そうでなければ false を返します。
（このドキュメント全体で，true は任意の非ゼロ値を意味し，false はゼロを意味します。）
r が s より大きい，等しい，または小さい場合，それぞれ +1，0，-1 を返します。これは，0 を最小，無限大を任意の有限実数より大きいと見なす，コンパクト化された非負実軸上の自然な全順序に従います。
r を，それぞれ無限大，ゼロ，1，s，または mant⋅2exp に設定します。
r を，s と t の最大値に設定します。
r が無限大でもゼロでもないと仮定して，r = m⋅2e と書いたときの指数 e を返します（ここで，1/2 ≤ m < 1）。
（これは半径を表す構造体のフィールド exp とは異なり，実装に依存しないことに注意して下さい。）
それ以外の場合の動作は未定義です。
r を f（stdout でも可）に出力します。
注意：この関数は現在，主にデバッグ目的で使用されており，将来的に動作が変更される可能性があります。
r を，s と t の和，差，積，または商，もしくは s に 2t を掛けた値，または s を 2t で割った値，または s の二乗または平方根に設定します。 引数のいずれかが無限大である場合や，差が負の場合，結果は無限大になります。
r を，s と t の差を方向 rnd で丸めた値に設定します。この方向は，MPFR_RNDU または MPFR_RNDD のいずれかです。もし引数の一つが無限大であるか，差が負の場合，結果は無限大になります。MPFR_RNDU でこの関数を呼び出すことは，mpcr_sub を呼び出すことと同等です。
この関数は，丸めパラメータを取るいくつかの関数のうちの1つです。除算結果に対して上限を得たい場合，下方向への丸めが有用となることがあります。
Set r to the absolute value of the complex number z, rounded
in direction rnd, which may be one of MPFR_RNDU or
MPFR_RNDD.
rnd が MPFR_RNDN に等しい場合は r を r + (1 + r) 2-p に設定し，それ以外の場合は r + (1 + r) 21-p に設定します。
このアイデアは，半径 r の理想的な複素球の（表現不可能な可能性のある）中心を精度 p で表現可能な複素数に丸めた場合，中心が最大で1/2 ULP（最も近い値への丸めの場合）または1 ULP（実部または虚部の少なくとも一方を有向丸めする場合）だけずれ，これに応じて半径が増加する，というものです。
このため，この関数は通常，複素球に対する各操作の最後に内部的に呼び出され，中心を丸めることで生じる誤差を考慮します。
球のデータ型は下記のように定義されています。
typedef struct {
mpc_t c;
mpcr_t r;
}
もう少し正確に言うと，mpcb_t型は上記の構造体の1次元配列として定義されており，
変数（へのポインタ）mpcb_ptr 型，定数へのポインタは
mpcb_srcptr型としてそれぞれ定義されています。
通常，これらのコンポーネントは使用する関数を通じてのみアクセスするようにして下さい。
球データを扱う関数を理解するためには，複素数を扱う数学関数において，引数に球データが引き渡される ということを考慮しておく必要があります。MPCの球を扱う関数は「丸めて包含する」ように 動作します。つまり，どのような入力値に対しても，その関数の値が内包されるような球を返す必要があります。 それもなるべく小さい球になるようにします。とはいえ，もう一度繰り返しますが，返される球が最も半径の小さい ものになっているという保証はできません。 現時点での実装では，返される球の中心値は，入力値として渡される球の中心値を用いて関数値を求め，丸めたものと なっています。実装としては素直なものですが，それが妥当なものかどうかの保証はありません。とはいえ，通常の 複素引数を扱う関数に対しての誤差解析の見通しは良くなっているものと思われます。 球の中心が正負の無限大，もしく非数(NaN)の時は，半径も無限大に設定されます。つまり，中心の値が何であれ， 複素平面すべてを包含する球となり，「無意味な球」と解釈されるものになります。
複素データ型（mpc_t）は明示的に精度桁数を指定して初期化されますが，mpcb_t型の
変数の精度桁数は動的なものとして扱います。球の中心は実部と虚部が同じ精度桁数になっている複素
変数とします（もちろん実装では異なる精度桁数にすることもできますが，その際には
絶対値が小さい方の精度桁数に合わせることになり，半径の誤差に影響が強く出ます）。
異なるデータ型から変換されて与えられる球は，追加的に精度桁数が渡されて中心の精度桁数
として設定されます。球を扱う関数は入力値の精度桁数に合わせて返り値の球の精度桁数を決めます。
現在の実装では，入力値の精度桁数のうち最小のものを採用しており，全ての球がこの精度桁数に
設定されていれば，この精度桁数ですべての計算が実行されます。
(半径の指数部は，中心値の2進ビット数をエンコードしていますので，半径が大きくなる場合は
精度桁数も併せて減らすことになります)
複素球データを扱える関数を以下に示します。関数群がこのように制限されているのは，
球演算を通じて複素数の算術幾何平均を実装しようとしたからです。
他の複素関数同様，
mpcb_mul (z, z, z)というように，引数と演算結果に同じ球データ型の変数zを指定でき，
この場合はzの2乗がzに格納されます。
球データ型変数zの初期化と解放を行います。変数を使う前には必ずmpcb_init
関数を呼び出して一度初期化しておく必要があります。また，変数の使用をやめる前には
mpcb_clear関数で変数を解放しておかねばいけません。 複素変数mpc_tの初期化とは異なり，
mpcb_init関数はz変数の精度桁数は指定せず，半径は無限大に設定されますので，
初期化直後のzは複素平面すべてを包含した球となります。
球データ変数zの中心の実部と虚部の精度桁数（基本は同じ）を返します。
球データ変数zにz1の値を代入します。中心の精度桁数も代入されます。
z を複素平面全体に設定します。これは警告(assertion)のように使うことを想定しています。関数内で前提条件が満たされない場合，その結果をこの値に設定することで，後の計算にそのまま伝播させることができます。
z を精度 prec で中心が c の球に設定します。 prec が c の実部および虚部，ならびに err_re および err_im が0である場合の最大精度以上であれば，結果として得られる球は半径が0で正確です。 もし c が正確であり，結果に対してより大きな目標精度を望む場合，または作業精度に余裕を持たせたい場合には，prec により大きな値を使用するのが理にかなっています。 prec が c の精度よりも低い場合，通常は中心の設定時に丸め誤差が発生し，それが半径に反映されます。
err_re と err_im が0でない場合，引数 c は不正確な複素数と見なされ，実部の絶対誤差は c の実部の1/2 ULPの倍数として err_re によって与えられ，虚部の絶対誤差は c の虚部の1/2 ULPの倍数として err_im によって与えられます。（c の各部分が異なる精度または指数を持つ場合，各部分のULPの絶対値が異なることに注意して下さい。） その後，z は c を中心とし，これらの誤差と中心に対する追加の丸め誤差を考慮した半径を持つ球として作成されます。 もし c の実部が0である場合，err_re は0でなければなりません。なぜなら，0のULPは意味がないからです。そうでない場合，半径は無限大に設定されます。同様の注意が虚部にも適用されます。
err_re と err_im を0以外に設定することは，特に次の2つの状況で有用です。
もし c が，正確な入力と両部分を最も近い値に丸めるモード MPC_RNDNN を使用した mpc_ 関数の呼び出しの結果である場合，その部分は最大で1/2 ULPの誤差を持つことが知られており，err_re と err_im を1に設定することで，正確な結果を含むことが確実な球が得られます（これが1/2 ULPという奇妙な単位を採用している理由です）。もし有向丸めが使用された場合，err_re と err_im は2に設定できます。
さらに，もし c が mpc_ 関数の一連の呼び出しの結果であり，誤差解析が行われている場合（これは複素関数の実装時に内部で頻繁に行われます），適切な値の err_re と err_im を使用することで，結果として得られる球 z が正確な結果を含むことが再度保証されます。
球データ変数zに，中心がre+I*imで，精度桁数
prec，もしくはunsigned long intのサイズを代入します。
これらの球データに対する演算関数は，
mpc_neg, mpc_addといった複素関数と同等の計算を行うものですが，複素数の代わりに複素球データを求めます。
この関数が true（非ゼロの数値）を返す場合は，球内の複素数であれば，それぞれ実部の精度 prec_re と虚部の精度 prec_im で，丸めモード rnd に従って複素数に丸めたものが得られているということを示しています（return-value を参照）。
関数が false（つまり，0）を返す場合，このような結論を出せなかったか，または球内に異なる複素数や異なる方向に丸められる2つの数が含まれている可能性がある，ということを示しています。この関数はベストエフォートで動作し，安全策として丸め可能な球でも false を返す可能性があるため，計算関数が必ずしも最小の内包球を返さない，ということはご承知おき下さい。。
z が，正確な複素数，すなわち半径0の球から始まる一連の mpcb 関数の呼び出しを通じて，ある数学関数を評価した結果を含んでいる場合，true が返されると，球内の任意の値（中心が容易に利用可能です）を方向 rnd に丸めると，その関数の正確な結果と通常のMPCセマンティクスに従った正しい丸め方向の値が得られることを意味します。
z の精度が prec_re または prec_im よりも大きい場合，中心は希望する精度で表現できないかもしれず，実際には球が「丸め可能」であっても表現可能な数をまったく含まない可能性があります。さらに悪いことに，rnd が実部または虚部に対して有向丸めモードであり，非ゼロの半径を持つ球が表現可能な数を含む場合，返り値は必然的に false になります。さらに，ある部分の丸めモードが最も近い値への丸めで，その部分の中心が表現可能で，球が非ゼロの半径を持つ場合も，返り値は必然的に false になります。なぜなら，たとえ丸めが可能でも，丸め方向の値を決定できないからです。
球データ変数cにzの中心を代入し，rndで指定したモードで丸め，丸め方向の値を返します。
元の球データ変数zにmpcb_can_round関数が適用して，当該cと丸めモード
rndに対してtrueを返してくるようなら，この関数は予想されたように
「正しく球データを丸められる」ことになり，全ての球に対して有効な丸め方向値を返します。
すでに説明した通り，
この結果は（半径が0でない有向丸めが存在する場合）球の要素にはなりません。
Next: Concept Index, Previous: 球演算(Ball Arithmetic), Up: GNU MPC [Index]
GMP – GNU multiprecision library.
Version 6.2.0, http://gmplib.org.
MPFR – A library for multiple-precision floating-point computations with exact rounding.
Version 4.1.0, http://www.mpfr.org.
Next: Function Index, Previous: References, Up: GNU MPC [Index]
| Jump to: | A B C I L M P R S T U |
|---|
| Jump to: | A B C I L M P R S T U |
|---|
Next: Type Index, Previous: Concept Index, Up: GNU MPC [Index]
| Jump to: | _
M |
|---|
| Jump to: | _
M |
|---|
Next: GNU Free Documentation License, Previous: Function Index, Up: GNU MPC [Index]
| Jump to: | M |
|---|
| Jump to: | M |
|---|
Previous: Type Index, Up: GNU MPC [Index]
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.