update manual

doc/ja/source/algorithm/bayes.rst

@@ -17,7 +17,7 @@
 `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ がインストールされている場合、MPI 並列計算が可能です。
 
 入力パラメータ
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 [``algorithmparam``] セクション
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -94,7 +94,7 @@
 
 
 アルゴリズム補助ファイル
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 メッシュ定義ファイル
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -120,7 +120,7 @@
     ...
 
 出力ファイル
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``BayesData.txt`` 
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -138,8 +138,42 @@
     ...
 
 
+リスタート
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``Algorithm.main()`` メソッドの引数 ``run_mode`` に実行モードを指定します。
+以下はそれぞれ ``py2dmat`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。
+各モードの動作は次のとおりです。
+
+- ``"initialize"`` (デフォルト)
+
+  初期化して実行します。
+  まず、ランダムサンプリングを ``random_max_num_probes`` に指定した回数だけ行います。
+  次に、ベイズ最適化を ``bayes_max_num_probes`` に指定した回数実行します。
+
+  チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。
+
+  #. ランダムサンプリングが終了したとき
+  #. ベイズ最適化の繰り返しの途中で、指定したステップ数または実行時間が経過したとき
+  #. 実行の終了時
+
+
+- ``"resume"``
+
+  実行が中断した際に、最も新しいチェックポイントから実行を再開します。
+  並列数などの計算条件は前と同じにする必要があります。
+
+  なお、並列実行の場合、実行を中断して resume した結果は、中断なしで実行した結果と完全には一致しません。
+
+- ``"continue"``
+
+  終了時の状態からベイズ最適化の繰り返しを継続して実行するモードです。
+  ``bayes_max_num_probes`` の値を増やして実行します。繰り返しステップカウントはそのまま引き継がれます。
+
+  resume と continue は実質的に同じです。
+
+
 アルゴリズム解説
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `ベイズ最適化 (Bayesian optimization, BO) <https://en.wikipedia.org/wiki/Bayesian_optimization>`_ は、機械学習を援用した最適化アルゴリズムであり、特に目的関数の評価に時間がかかるときに強力な手法です。
 

doc/ja/source/algorithm/exchange.rst

@@ -231,6 +231,33 @@ MPI並列を利用する場合は、あらかじめ `mpi4py <https://mpi4py.read
     2 15 28.70157662892569 3.3139009347685118 -4.20946994566609
     3 15 28.98676409223712 3.7442621319489637 -3.868754990884034
 
+リスタート
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``Algorithm.main()`` メソッドの引数 ``run_mode`` に実行モードを指定します。
+以下はそれぞれ ``py2dmat`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。
+各モードの動作は次のとおりです。
+
+- ``"initialize"`` (デフォルト)
+
+  初期化して実行します。
+  チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。
+
+  #. 指定したステップ数または実行時間が経過したとき
+  #. 実行の終了時
+
+
+- ``"resume"``
+
+  実行が中断した際に、最も新しいチェックポイントから実行を再開します。
+  並列数などの計算条件は前と同じにする必要があります。
+
+- ``"continue"``
+
+  終了時の状態からサンプリングの繰り返しを継続して実行するモードです。
+  ``numsteps`` の値を増やして実行します。繰り返しステップカウントはそのまま引き継がれます。
+
+  resume と continue は実質的に同じです。
+
 
 アルゴリズム解説
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/ja/source/algorithm/mapper_mpi.rst

@@ -106,3 +106,26 @@ MPI 並列を行う場合は、 `mpi4py <https://mpi4py.readthedocs.io/en/stable
     6.000000 4.000000 0.069351
     6.000000 3.750000 0.071868
     ...
+
+リスタート
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``Algorithm.main()`` メソッドの引数 ``run_mode`` に実行モードを指定します。
+以下はそれぞれ ``py2dmat`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。
+各モードの動作は次のとおりです。
+
+- ``"initialize"`` (デフォルト)
+
+  初期化して実行します。
+  チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。
+
+  #. 指定した数のグリッド点を評価したとき、または指定した実行時間が経過したとき
+  #. 実行の終了時
+
+- ``"resume"``
+
+  実行が中断した際に、最も新しいチェックポイントから実行を再開します。
+  並列数などの計算条件は前と同じにする必要があります。
+
+- ``"continue"``
+
+  continue には対応していません。

doc/ja/source/algorithm/minsearch.rst

@@ -136,3 +136,9 @@ Nelder-Mead 法のハイパーパラメータを設定します。
     z1 = 5.230524973874179
     z2 = 4.370622919269477
     z3 = 3.5961444501081647
+
+
+リスタート
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Nelder-Mead法による最適値探索はリスタートに対応していません。

doc/ja/source/algorithm/pamc.rst

@@ -287,6 +287,39 @@ MPI 並列をする場合にはあらかじめ `mpi4py <https://mpi4py.readthedo
     0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004
     ...
 
+
+リスタート
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``Algorithm.main()`` メソッドの引数 ``run_mode`` に実行モードを指定します。
+以下はそれぞれ ``py2dmat`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。
+各モードの動作は次のとおりです。
+
+- ``"initialize"`` (デフォルト)
+
+  初期化して実行します。
+  チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。
+
+  #. 各温度点の計算が終わった時点で、指定したステップ数または実行時間が経過したとき
+  #. 実行の終了時
+
+
+- ``"resume"``
+
+  実行が中断した際に、最も新しいチェックポイントから実行を再開します。
+  並列数などの計算条件は前と同じにする必要があります。
+
+- ``"continue"``
+
+  実行終了後の状態から継続して実行します。
+  温度点のリストを、前の計算から連続するように指定する必要があります。
+
+  前の計算で ``Tmax=`` :math:`T^{(1)}` から ``Tmin=`` :math:`T^{(2)}` に下げた場合、
+  次の計算では ``Tmax=`` :math:`T^{(2)}`, ``Tmin=`` :math:`T^{(3)}` のように指定します。
+  新たな計算では、 :math:`T^{(2)}` から :math:`T^{(3)}` までを ``Tnum`` に分割した温度点の列
+  :math:`T_0 = T^{(2)}`, :math:`T_1`,..., :math:`T_{\text{Tnum}-1}=T^{(3)}`
+  について計算を行います。(Tnum は前の計算から変更して構いません。)
+
+
 アルゴリズム解説
 ~~~~~~~~~~~~~~~~~~~
 

doc/ja/source/customize/algorithm.rst

@@ -56,6 +56,15 @@
 
             - 空の辞書が3つ、 ``"prepare"``, ``"run"``, ``"post"`` という名前で定義されます
 
+	- ``self.checkpoint`` : チェックポイント機能を有効/無効にする
+
+	    - ``self.checkpoint_steps``
+	    - ``self.checkpoint_interval``
+	    - ``self.checkpoint_file``
+
+	      チェックポイント機能に関するパラメータが設定されます
+
+
 - ``prepare(self) -> None``
 
     - 最適化アルゴリズムの前処理をします
@@ -73,16 +82,26 @@
       #. 元のディレクトリに戻る
     - ``self.prepare()`` の後に実行する必要があります
 
-- ``post(self) -> None``
+- ``post(self) -> Dict``
 
     - 最適化結果のファイル出力など、後処理を行います
     - ``self.output_dir`` に移動し、 ``self._post()`` を実行した後、元のディレクトリに戻ります
     - ``self.run()`` のあとに実行する必要があります
 
-- ``main(self) -> None``
+- ``main(self, run_mode) -> Dict``
 
     - ``prepare``, ``run``, ``post`` を順番に実行します
     - それぞれの関数でかかった時間を計測し、結果をファイル出力します
+    - 実行モードを文字列型の引数で受け取ります。デフォルト値は ``initialize`` です。
+
+      - ``"initialize"``: 最初から実行
+      - ``"resume"``: 中断した状態から再実行
+      - ``"continue"``: 終了時の状態から継続実行
+
+      乱数の初期化を指示する場合は、 ``"-resetrand"`` が追加されます。
+      ``"continue"`` の動作はアルゴリズムによって変わります。
+
+    - 探索の結果を辞書形式で返します
 
 
 
@@ -116,11 +135,11 @@
 	 args = (step, set)
          fx = self.runner.submit(x, args)
 
-- ``_post(self) -> None``
+- ``_post(self) -> Dict``
 
     - 最適化アルゴリズムの後処理を記述します
-
-
+    - 探索の結果を辞書形式で返します
+      
 
 ``Domain`` の定義
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/ja/source/customize/usage.rst

@@ -43,4 +43,4 @@
     algorithm = Algorithm(info, runner)
 
     # (4)
-    algorithm.main()
+    result = algorithm.main()

doc/ja/source/input.rst

@@ -106,12 +106,38 @@ py2dmat は入力ファイルの形式に `TOML <https://toml.io/ja/>`_ を採
 
 - ``seed_delta``
 
-  形式: 整数値。 (default: 314159)
+  形式: 整数値 (default: 314159)
 
   説明: 疑似乱数生成器の種について、MPI プロセスごとの値を計算する際に用いられます。
         詳しくは ``seed`` を参照してください。
 
+- ``checkpoint``
 
+  形式: bool値 (default: false)
+
+  説明: 実行中および終了時の状態を定期的にファイルに出力します。実行が中断した場合に、チェックポイントから実行を再開できます。
+
+- ``checkpoint_steps``
+
+  形式: 整数値 (default: 16,777,216)
+
+  説明: 次のチェックポイントまでの繰り返し回数を指定します。繰り返し回数は、mapper の場合はグリッド点の数、bayes の場合は探索点の評価回数、モンテカルロ法(exchange, pamc) の場合は local update の回数です。
+  デフォルト値は十分大きな数が設定されています。チェックポイント機能を有効にするには、 ``checkpoint_steps`` または ``checkpoint_interval`` の少なくとも一方を設定する必要があります。
+
+- ``checkpoint_interval``
+
+  形式: 実数値 (default: 31,104,000)
+
+  説明: 次のチェックポイントまでの経過時間を指定します。単位は秒です。
+  デフォルト値は十分大きな数(360日)が設定されています。チェックポイント機能を有効にするには、 ``checkpoint_steps`` または ``checkpoint_interval`` の少なくとも一方を設定する必要があります。
+
+- ``checkpoint_file``
+
+  形式: 文字列 (default: ``"status.pickle"``)
+
+  説明: 実行中の状態を書き出すファイル名を指定します。ファイルはプロセスごとの出力ディレクトリに書き出されます。過去3世代分のファイルが .1, .2, .3 の suffix を付けて保存されます。
+
+
 各種アルゴリズムの詳細および入出力ファイルは :doc:`algorithm/index` を参照してください。
 
 

doc/ja/source/output.rst

@@ -51,3 +51,11 @@ MPI のランクごとに、ソルバー呼び出しに関するログ情報を
     5 4.965899999997969e-05 0.0014163379999999615
     6 8.666900000003919e-05 0.0015030070000000006
        ...
+
+
+``status.pickle``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``algorithm.checkpoint`` が true の場合、MPI のランクごとに実行中の状態を出力します。
+各ランクのサブフォルダ以下に出力されます。実行を再開する場合に読み込まれます。
+ファイルの内容はアルゴリズムに依ります。
+