Merge branch 'update.docs' into update

doc/ja/source/acknowledgement.rst

@@ -1,7 +1,7 @@
-***************************
-謝辞
-***************************
-本ソフトウェアの開発は、科研費(2019-2021年度)「超並列マシンを用いた計算統計と測定技術の融合」および東京大学物性研究所 ソフトウェア高度化プロジェクト (2020, 2021 年度) の支援を受け開発されました。
-本ソフトウェアの設計・変数命名の一部は `abics <https://github.com/issp-center-dev/abICS>`_ を参考にしています。
-また、順問題ソルバーの実装にあたり、花田貴氏 (東北大学)、望月出海氏(KEK)、W. Voegeli氏(東京学芸大学)、白澤徹郎氏(AIST)、R. Ahmed氏(九州大学)、和田健氏(KEK)にお世話になりました。ソルバーの追加方法について、塚本恭平氏(物性研)にチュートリアルを追加していただきました。
-この場を借りて感謝します。
+***************************
+謝辞
+***************************
+本ソフトウェアの開発は、科研費(2019-2021年度)「超並列マシンを用いた計算統計と測定技術の融合」および東京大学物性研究所 ソフトウェア高度化プロジェクト (2020, 2021, 2024 年度) の支援を受け開発されました。
+本ソフトウェアの設計・変数命名の一部は `abics <https://github.com/issp-center-dev/abICS>`_ を参考にしています。
+また、順問題ソルバーの実装にあたり、花田貴氏 (東北大学)、望月出海氏(KEK)、W. Voegeli氏(東京学芸大学)、白澤徹郎氏(AIST)、R. Ahmed氏(九州大学)、和田健氏(KEK)にお世話になりました。ソルバーの追加方法について、塚本恭平氏(物性研)にチュートリアルを追加していただきました。
+この場を借りて感謝します。

doc/ja/source/algorithm/bayes.rst

@@ -4,17 +4,17 @@
 .. _PHYSBO: https://pasums.issp.u-tokyo.ac.jp/physbo
 
 ``bayes`` はベイズ最適化を用いてパラメータ探索を行う ``Algorithm`` です。
-
 実装には `PHYSBO`_ を用いています。
 
 前準備
 ~~~~~~
-あらかじめ `PHYSBO`_ をインストールしておく必要があります。::
+あらかじめ `PHYSBO`_ をインストールしておく必要があります。
+
+.. code-block:: bash
 
-  python3 -m pip install physbo
+    $ python3 -m pip install physbo
 
-`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ がインストールされている場合、
-MPI 並列計算が可能です。
+`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ がインストールされている場合、MPI 並列計算が可能です。
 
 入力パラメータ
 ~~~~~~~~~~~~~~~~~~~~~
@@ -77,7 +77,7 @@ MPI 並列計算が可能です。
   形式: string型 (default: ``TS`` )
 
   説明: スコア関数を指定するパラメータ。
-  ``EI``, ``PI``, ``TS`` より選択可能で、それぞれ "expected improvement", "probability of improvement", "Thompson sampling" を行う。
+  ``EI``, ``PI``, ``TS`` より選択可能で、それぞれ "expected improvement", "probability of improvement", "Thompson sampling" を行います。
 
 - ``interval``
 
@@ -143,8 +143,8 @@ MPI 並列計算が可能です。
 
 `ベイズ最適化 (Bayesian optimization, BO) <https://en.wikipedia.org/wiki/Bayesian_optimization>`_ は、機械学習を援用した最適化アルゴリズムであり、特に目的関数の評価に時間がかかるときに強力な手法です。
 
-BO では目的関数 :math:`f(\vec{x})` を、評価が早く最適化のしやすいモデル関数（多くの場合ガウス過程） :math:`g(\vec{x})` で近似します。
-:math:`g` は、あらかじめ適当に決められたいくつかの点（訓練データセット） :math:`\{\vec{x}_i\}_{i=1}^N` での目的関数の値 :math:`\{f(\vec{x}_i)\}_{i=1}^N` をよく再現するように訓練されます。
+BO では目的関数 :math:`f(\vec{x})` を、評価が早く最適化のしやすいモデル関数(多くの場合ガウス過程) :math:`g(\vec{x})` で近似します。
+:math:`g` は、あらかじめ適当に決められたいくつかの点(訓練データセット) :math:`\{\vec{x}_i\}_{i=1}^N` での目的関数の値 :math:`\{f(\vec{x}_i)\}_{i=1}^N` をよく再現するように訓練されます。
 パラメータ空間の各点において、訓練された :math:`g(\vec{x})` の値の期待値およびその誤差から求められる「スコア」 (acquition function) が最適になるような点 :math:`\vec{x}_{N+1}` を次の計算候補点として提案します。
 :math:`f(\vec{x}_{N+1})` を評価し、 訓練データセットに追加、 :math:`g` を再訓練します。
 こうした探索を適当な回数繰り返した後、目的関数の値が最も良かったものを最適解として返します。

doc/ja/source/algorithm/exchange.rst

@@ -6,9 +6,11 @@
 前準備
 ~~~~~~~~
 
-あらかじめ `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ をインストールしておく必要があります。::
+MPI並列を利用する場合は、あらかじめ `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ をインストールしておきます。
 
-  python3 -m pip install mpi4py
+.. code-block::
+
+    $ python3 -m pip install mpi4py
 
 入力パラメータ
 ~~~~~~~~~~~~~~~~~~~
@@ -130,7 +132,7 @@
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 本ファイルで探索するグリッド空間を定義します。
-1列目にメッシュのインデックス（実際には使用されません）、
+1列目にメッシュのインデックス (実際には使用されません)、
 2列目以降は探索空間の座標を指定します。
 
 以下、サンプルを記載します。
@@ -231,38 +233,39 @@
 
 
 アルゴリズム解説
-********************
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 マルコフ連鎖モンテカルロ法
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-モンテカルロ法（モンテカルロサンプリング）では、パラメータ空間中を動き回る walker :math:`\vec{x}` を重み :math:`W(\vec{x})` に従って確率的に動かすことで目的関数の最適化を行います。
-重み :math:`W(\vec{x})` として、「温度」 :math:`T > 0` を導入して :math:`W(\vec{x}) = e^{-f(\vec{x})/T}` とすることが一般的です（ボルツマン重み）。
+モンテカルロ法(モンテカルロサンプリング)では、パラメータ空間中を動き回る walker :math:`\vec{x}` を重み :math:`W(\vec{x})` に従って確率的に動かすことで目的関数の最適化を行います。
+重み :math:`W(\vec{x})` として、「温度」 :math:`T > 0` を導入して :math:`W(\vec{x}) = e^{-f(\vec{x})/T}` とすることが一般的です(ボルツマン重み)。
 ほとんどの場合において、 :math:`W` に基づいて直接サンプリングする (walker を生成する) のは不可能なので、 walker を確率的に少しずつ動かすことで、頻度分布が :math:`W` に従うように時系列 :math:`\{\vec{x}_t\}` を生成します (マルコフ連鎖モンテカルロ法, MCMC)。
 :math:`\vec{x}` から :math:`\vec{x}'` へ遷移する確率を :math:`p(\vec{x}' | \vec{x})` とすると、
 
 .. math::
 
   W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x})
 
-となるように :math:`p` を定めれば時系列 :math:`\{\vec{x}_t\}` の頻度分布が :math:`W(\vec{x})` に収束することが示されます（釣り合い条件） [#mcmc_condition]_ 。
+となるように :math:`p` を定めれば(釣り合い条件)、時系列 :math:`\{\vec{x}_t\}` の頻度分布が :math:`W(\vec{x})` に収束することが示されます。 [#mcmc_condition]_ 
 実際の計算では、より強い制約である詳細釣り合い条件
 
 .. math::
 
   p(\vec{x} | \vec{x}') W(\vec{x}') =  W(\vec{x})p(\vec{x}' | \vec{x})
 
-を課すことがほとんどです。 両辺で :math:`vec{x}` についての和を取ると釣り合い条件に帰着します。
+を課すことがほとんどです。 両辺で :math:`\vec{x}` についての和を取ると釣り合い条件に帰着します。
 
 :math:`p` を求めるアルゴリズムはいくつか提案されていますが、 2DMAT では Metropolis-Hasting 法 (MH法) を用います。
 MH 法では、遷移プロセスを提案プロセスと採択プロセスとに分割します。
 
 1. 提案確率 :math:`P(\vec{x} | \vec{x}_t)` で候補点 :math:`\vec{x}` を生成します
 
-   - 提案確率 :math:`P` としては :math:`\vec{x}_t` を中心とした一様分布やガウス関数などの扱いやすいものを利用します
+   提案確率 :math:`P` としては :math:`\vec{x}_t` を中心とした一様分布やガウス関数などの扱いやすいものを利用します
 
 2. 提案された候補点 :math:`\vec{x}` を採択確率 :math:`Q(\vec{x}, | \vec{x}_t)` で受け入れ、 :math:`\vec{x}_{t+1} = \vec{x}` とします
-   - 受け入れなかった場合は :math:`\vec{x}_{t+1} = \vec{x}_t` とします
+
+   受け入れなかった場合は :math:`\vec{x}_{t+1} = \vec{x}_t` とします
 
 採択確率 :math:`Q(\vec{x} | \vec{x}_t)` は
 
@@ -272,8 +275,7 @@ MH 法では、遷移プロセスを提案プロセスと採択プロセスと
 
 とします。
 この定義が詳細釣り合い条件を満たすことは、詳細釣り合いの式に代入することで簡単に確かめられます。
-特に、重みとしてボルツマン因子を、
-提案確率として対称なもの :math:`P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})` を用いたときには、
+特に、重みとしてボルツマン因子を、提案確率として対称なもの :math:`P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})` を用いたときには、
 
 .. math::
 
@@ -287,15 +289,15 @@ MH 法では、遷移プロセスを提案プロセスと採択プロセスと
 MH 法によるMCMC は次のようになります。
 
 1. 現在地点の近くからランダムに次の座標の候補を選び、目的関数 :math:`f` の値を調べる
-2. :math:`\Delta f \le 0` ならば（山を下る方向ならば）移動する
+2. :math:`\Delta f \le 0` ならば(山を下る方向ならば)移動する
 3. :math:`\Delta f > 0` ならば採択確率 :math:`Q = e^{-\Delta f / T}` で移動する
 4. 1-3 を適当な回数繰り返す
 
 得られた時系列のうち、目的関数の値が一番小さいものを最適解とします。
 3 番のプロセスのおかげで、 :math:`\Delta f \sim T` ぐらいの山を乗り越えられるので、局所最適解にトラップされた場合にも脱出可能です。
 
 レプリカ交換モンテカルロ法
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 モンテカルロ法による最適化では、温度 :math:`T` は非常に重要なハイパーパラメータとなっています。
 モンテカルロ法では、温度 :math:`T` 程度の山を乗り越えられますが、逆にそれ以上の深さの谷からは容易に脱出できません。
@@ -305,10 +307,10 @@ MH 法によるMCMC は次のようになります。
 
 この問題を解決する方法として、温度 :math:`T` を固定せずに更新していくというものがあります。
 たとえば、焼きなまし法 (simulated annealing) では、温度をステップごとに徐々に下げていきます。
-焼戻し法 (simulated tempering) は、温度をハイパーパラメータではなく、サンプリングすべきパラメータとして扱い、（詳細）釣り合い条件を満たすように更新することで、加熱と冷却を実現します。温度を下げることで谷の詳細を調べ、温度を上げることで谷から脱出します。
+焼戻し法 (simulated tempering) は、温度をハイパーパラメータではなく、サンプリングすべきパラメータとして扱い、(詳細)釣り合い条件を満たすように更新することで、加熱と冷却を実現します。温度を下げることで谷の詳細を調べ、温度を上げることで谷から脱出します。
 レプリカ交換モンテカルロ法 (replica exchange Monte Carlo) は焼戻し法を更に発展させた手法で、並列焼戻し法 (parallel tempering) とも呼ばれます。
 レプリカ交換モンテカルロ法では、レプリカと呼ばれる複数の系を、それぞれ異なる温度で並列にモンテカルロシミュレーションします。
-そして、ある一定間隔で、（詳細）釣り合い条件を満たすように他のレプリカと温度を交換します。
+そして、ある一定間隔で、(詳細)釣り合い条件を満たすように他のレプリカと温度を交換します。
 焼戻し法と同様に、温度を上下することで谷を調べたり脱出したりするのですが、各温度点について、かならずレプリカのどれかが対応しているため、全体として特定の温度に偏ることがなくなります。
 また、複数の MPI プロセスを用意してそれぞれレプリカを担当させることで簡単に並列化可能です。
 数多くのレプリカを用意することで温度間隔が狭まると、温度交換の採択率も上がるため、大規模並列計算に特に向いたアルゴリズムです。

doc/ja/source/algorithm/index.rst

@@ -7,7 +7,7 @@
 ====================
 
 探索アルゴリズム ``Algorithm`` は ``Solver`` の結果 :math:`f(x)` を用いて
-パラメータ空間 :math:`\mathbf{X} \ni x` を探索します。
+パラメータ空間 :math:`\mathbf{X} \ni x` を探索し、 :math:`f(x)` の最小化問題を解きます。
 
 .. toctree::
    :maxdepth: 1

doc/ja/source/algorithm/mapper_mpi.rst

@@ -1,4 +1,4 @@
-自明並列探索 ``mapper``
+グリッド型探索 ``mapper``
 ******************************
 
 ``mapper_mpi`` はパラメータ空間中の候補点をあらかじめ用意しておいて、そのすべてで :math:`f(x)` を計算することで最小値を探索するアルゴリズムです。
@@ -7,9 +7,11 @@ MPI 実行した場合、候補点の集合を等分割して各プロセスに
 前準備
 ~~~~~~~
 
-MPI 並列を行う場合は、 `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ をインストールしておく必要があります。::
+MPI 並列を行う場合は、 `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ をインストールしておく必要があります。
 
-  python3 -m pip install mpi4py
+.. code-block::
+
+    $ python3 -m pip install mpi4py
 
 入力パラメータ
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -86,10 +88,8 @@ MPI 並列を行う場合は、 `mpi4py <https://mpi4py.readthedocs.io/en/stable
 ``ColorMap.txt``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-各メッシュでの候補パラメータと、その時の ``R-factor`` が記載されたファイルです。
-入力ファイルの ``[solver]`` - ``[param]`` セクションにある、
-``string_list`` で定義された変数の順番でメッシュデータは記載され、
-最後に ``R-factor`` の値が記載されます。
+各メッシュでの候補パラメータと、その点での目的関数の値が記載されたファイルです。
+メッシュデータは、入力ファイルの ``[solver.param]`` セクションにある ``string_list`` で定義された変数の順番で記載され、最後に目的関数の値が記載されます。
 
 以下、出力例です。
 

doc/ja/source/algorithm/minsearch.rst

@@ -107,7 +107,7 @@ Nelder-Mead 法のハイパーパラメータを設定します。
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 最小値を求める途中経過に関する情報を出力します。
-1行目はヘッダー、2行目以降にstep, 入力ファイルの ``[solver]`` - ``[param]`` セクションにある、
+1行目はヘッダー、2行目以降にstep、入力ファイルの ``[solver.param]`` セクションにある
 ``string_list`` で定義された変数の値、最後に関数の値が出力されます。
 
 以下、出力例です。
@@ -126,9 +126,7 @@ Nelder-Mead 法のハイパーパラメータを設定します。
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 最終的に得られた目的関数の値とその時のパラメータの値を記載しています。
-最初に目的関数が、
-その後は入力ファイルの ``[solver]`` - ``[param]`` セクションにある、
-``string_list`` で定義された変数の値が順に記載されます。
+最初に目的関数、その後は入力ファイルの ``[solver.param]`` セクションにある ``string_list`` で定義された変数の値が順に記載されます。
 
 以下、出力例です。