From be90e40f34ef3d564c2d588514c37b3d6ca544b5 Mon Sep 17 00:00:00 2001 From: "T.Aoyama" Date: Wed, 28 Aug 2024 09:30:59 +0900 Subject: [PATCH] update manual --- doc/ja/source/algorithm/bayes.rst | 42 +++++++++++++++++++++++--- doc/ja/source/algorithm/exchange.rst | 27 +++++++++++++++++ doc/ja/source/algorithm/mapper_mpi.rst | 23 ++++++++++++++ doc/ja/source/algorithm/minsearch.rst | 6 ++++ doc/ja/source/algorithm/pamc.rst | 33 ++++++++++++++++++++ doc/ja/source/customize/algorithm.rst | 29 +++++++++++++++--- doc/ja/source/customize/usage.rst | 2 +- doc/ja/source/input.rst | 28 ++++++++++++++++- doc/ja/source/output.rst | 8 +++++ 9 files changed, 187 insertions(+), 11 deletions(-) diff --git a/doc/ja/source/algorithm/bayes.rst b/doc/ja/source/algorithm/bayes.rst index 6d474379..0f1db403 100644 --- a/doc/ja/source/algorithm/bayes.rst +++ b/doc/ja/source/algorithm/bayes.rst @@ -17,7 +17,7 @@ `mpi4py `_ がインストールされている場合、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) `_ は、機械学習を援用した最適化アルゴリズムであり、特に目的関数の評価に時間がかかるときに強力な手法です。 diff --git a/doc/ja/source/algorithm/exchange.rst b/doc/ja/source/algorithm/exchange.rst index 5980fb17..fa11b135 100644 --- a/doc/ja/source/algorithm/exchange.rst +++ b/doc/ja/source/algorithm/exchange.rst @@ -231,6 +231,33 @@ MPI並列を利用する場合は、あらかじめ `mpi4py 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`` の定義 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/ja/source/customize/usage.rst b/doc/ja/source/customize/usage.rst index e0be549e..31ca2008 100644 --- a/doc/ja/source/customize/usage.rst +++ b/doc/ja/source/customize/usage.rst @@ -43,4 +43,4 @@ algorithm = Algorithm(info, runner) # (4) - algorithm.main() + result = algorithm.main() diff --git a/doc/ja/source/input.rst b/doc/ja/source/input.rst index 714cd290..e7a7e9da 100644 --- a/doc/ja/source/input.rst +++ b/doc/ja/source/input.rst @@ -106,12 +106,38 @@ py2dmat は入力ファイルの形式に `TOML `_ を採 - ``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` を参照してください。 diff --git a/doc/ja/source/output.rst b/doc/ja/source/output.rst index f5adc27e..ab798cae 100644 --- a/doc/ja/source/output.rst +++ b/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 のランクごとに実行中の状態を出力します。 +各ランクのサブフォルダ以下に出力されます。実行を再開する場合に読み込まれます。 +ファイルの内容はアルゴリズムに依ります。 +