diff --git a/extra/function/doc/.gitignore b/extra/function/doc/.gitignore new file mode 100644 index 00000000..c795b054 --- /dev/null +++ b/extra/function/doc/.gitignore @@ -0,0 +1 @@ +build \ No newline at end of file diff --git a/extra/function/doc/common/img/himmelblau_mapper.pdf b/extra/function/doc/common/img/himmelblau_mapper.pdf new file mode 100644 index 00000000..a950d0b9 Binary files /dev/null and b/extra/function/doc/common/img/himmelblau_mapper.pdf differ diff --git a/extra/function/doc/common/img/himmelblau_mapper.png b/extra/function/doc/common/img/himmelblau_mapper.png new file mode 100644 index 00000000..461c6cd3 Binary files /dev/null and b/extra/function/doc/common/img/himmelblau_mapper.png differ diff --git a/extra/function/doc/ja/Makefile b/extra/function/doc/ja/Makefile new file mode 100644 index 00000000..f86728d9 --- /dev/null +++ b/extra/function/doc/ja/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W $(SPHINXOPTS) $(O) diff --git a/extra/function/doc/ja/make.bat b/extra/function/doc/ja/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/extra/function/doc/ja/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/extra/function/doc/ja/source/acknowledgement.rst b/extra/function/doc/ja/source/acknowledgement.rst new file mode 100644 index 00000000..9be001c2 --- /dev/null +++ b/extra/function/doc/ja/source/acknowledgement.rst @@ -0,0 +1,4 @@ +謝辞 +========================================= + +本ソフトウェアは、科研費(2019-2021年度)「超並列マシンを用いた計算統計と測定技術の融合」および東京大学物性研究所 ソフトウェア高度化プロジェクト (2020, 2021, 2024 年度) の支援を受け開発されました。 diff --git a/extra/function/doc/ja/source/conf.py b/extra/function/doc/ja/source/conf.py new file mode 100644 index 00000000..a9aae86c --- /dev/null +++ b/extra/function/doc/ja/source/conf.py @@ -0,0 +1,141 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = '2DMAT solver module: functions' +copyright = '2020-, 2DMAT developers' +author = '2DMAT developers' + +version = '1.0' +# The full version, including alpha/beta/rc tags +release = '1.0-dev' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.mathjax' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The master toctree document. +master_doc = 'index' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'haiku' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { +} + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'ja' + +# -- Options for LaTeX output --------------------------------------------- + +latex_engine = 'uplatex' + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'userguide_functions_ja.tex', u'2DMAT Function Module Documentation', + u'University of Tokyo', 'manual', 'True'), +] + +# latex_docclass = {'manual': 'jsbook'} + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, '2dmat', u'2DMAT Documentation', + author, '2DMAT', 'One line description of project.', + 'Miscellaneous'), +] + + +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + diff --git a/extra/function/doc/ja/source/contact.rst b/extra/function/doc/ja/source/contact.rst new file mode 100644 index 00000000..0c714e18 --- /dev/null +++ b/extra/function/doc/ja/source/contact.rst @@ -0,0 +1,22 @@ +お問い合わせ +========================================= + +2DMAT-Functions に関するお問い合わせはこちらにお寄せください。 + +- バグ報告 + + 2DMAT-Functions のバグ関連の報告は `GitHubのIssues `_ で受け付けています。 + + バグを早期に解決するため、報告時には次のガイドラインに従ってください。 + + - 使用している 2DMAT-Functions のバージョンを指定してください。 + + - インストールに問題がある場合には、使用しているオペレーティングシステムとコンパイラの情報についてお知らせください。 + + - 実行に問題が生じた場合は、実行に使用した入力ファイルとその出力を記載してください。 + +- その他 + + 研究に関連するトピックなどGitHubのIssuesで相談しづらいことを問い合わせる際には、以下の連絡先にコンタクトをしてください。 + + E-mail: ``2dmat-dev__at__issp.u-tokyo.ac.jp`` (_at_を@に変更してください) diff --git a/extra/function/doc/ja/source/index.rst b/extra/function/doc/ja/source/index.rst new file mode 100644 index 00000000..7beaecce --- /dev/null +++ b/extra/function/doc/ja/source/index.rst @@ -0,0 +1,23 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to 2DMAT's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + introduction + install + tutorial/index + solver + acknowledgement + contact +.. + usage + input + output + examples diff --git a/extra/function/doc/ja/source/install.rst b/extra/function/doc/ja/source/install.rst new file mode 100644 index 00000000..db98d362 --- /dev/null +++ b/extra/function/doc/ja/source/install.rst @@ -0,0 +1,72 @@ +インストール +================================================================ + +実行環境・必要なパッケージ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- python 3.6.8 以上 + + - 必要なpythonパッケージ + + - tomli (>= 1.2) + - numpy (>= 1.14) + +- py2dmat version 3.0 以降 + + +ダウンロード・インストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. py2dmat をインストールする + + - ソースコードからのインストール + + リポジトリから py2dmat のソースファイルを取得します。 + + .. code-block:: bash + + $ git clone -b update https://github.com/issp-center-dev/2DMAT.git + + pip コマンドを実行してインストールします。 + + .. code-block:: bash + + $ cd 2DMAT + $ python3 -m pip install . + + + ``--user`` オプションを付けるとローカル (``$HOME/.local``) にインストールできます。 + + ``python3 -m pip install .[all]`` を実行するとオプションのパッケージも同時にインストールします。 + +2. py2dmat-functions をインストールする + + - ソースコードからのインストール + + py2dmat-functions のソースファイルは、現在は py2dmat のソースパッケージの extra ディレクトリ内に配置されています。1. に記述した手順に従って py2dmat のソースファイルを取得した後、 ``extra/function`` ディレクトリ内で pip コマンドを実行してインストールします。 + + .. code-block:: bash + + $ cd 2DMAT/extra/function + $ python3 -m pip install . + + ``--user`` オプションを付けるとローカル (``$HOME/.local``) にインストールできます。 + + 2DMAT-Functions のライブラリがインストールされます。 + + +実行方法 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +2DMAT では順問題ソルバと逆問題解析アルゴリズムを組み合わせて解析を行います。 +2DMAT-Functions に用意された関数の最適化問題の解析を行うには、2DMAT-Functions ライブラリと 2DMAT フレームワークを用いてプログラムを作成し、解析を行います。逆問題解析アルゴリズムは import するモジュールで選択します。プログラム中に入力データの生成を組み込むなど、柔軟な使い方ができます。 +ライブラリの利用方法については以降の章で説明します。 + + +アンインストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +2DMAT-Functions モジュールおよび 2DMAT モジュールをアンインストールするには、以下のコマンドを実行します。 + +.. code-block:: bash + + $ python3 -m pip uninstall py2dmat-function py2dmat diff --git a/extra/function/doc/ja/source/introduction.rst b/extra/function/doc/ja/source/introduction.rst new file mode 100644 index 00000000..6f7bf6d9 --- /dev/null +++ b/extra/function/doc/ja/source/introduction.rst @@ -0,0 +1,90 @@ +はじめに +================================ + +2DMATとは +-------------------------------- + +2DMATは、順問題ソルバーに対して探索アルゴリズムを適用して最適解を探すためのフレームワークです。 +順問題ソルバーはユーザー自身で定義できるほか、標準的な順問題ソルバーとして2次元物質構造解析向け実験データ解析ソフトウェアが用意されています。 +順問題ソルバーでは、原子位置などをパラメータとして得られたデータと実験データとのずれを損失関数として与えます。 +探索アルゴリズムによりこの損失関数を最小化する最適なパラメータを推定します。 +現バージョンでは、順問題ソルバーとして量子ビーム回折実験の全反射高速陽電子回折法(Total-Reflection High-Energy Positron Diffraction: TRHEPD), 表面X線回折法(Surface X-ray Diffraction: SXRD), 低速電子線回折法(Low Energy Electron Diffraction: LEED)に対応しており、 +探索アルゴリズムはNelder-Mead法, グリッド型探索法, ベイズ最適化, レプリカ交換モンテカルロ法, ポピュレーションアニーリングモンテカルロ法が実装されています。 + + +2DMAT-Functionsとは +-------------------------------- + +2DMAT-Functions は 2DMAT 向けの順問題として解析関数を提供するものです。主な用途は 2DMAT のテストとベンチマークですが、ユーザが独自の順問題ソルバーを作成する上で雛形としても利用できます。 + +このモジュールは 2DMAT v2.x の順問題ソルバーの一つとして開発されたコンポーネントを、独立なモジュールとして再構成したものです。2DMAT と組み合わせて使用します。 + +ライセンス +-------------------------------- +| 本ソフトウェアのプログラムパッケージおよびソースコード一式はGNU + General Public License version 3 (GPL v3) に準じて配布されています。 + +Copyright (c) <2020-> The University of Tokyo. All rights reserved. + +本ソフトウェアは2020年度および2024年度 東京大学物性研究所 ソフトウェア高度化プロジェクトの支援を受け開発されました。 +2DMATを引用する際には以下の文献を引用してください。 + +"Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures", +Y. Motoyama, K. Yoshimi, I. Mochizuki, H. Iwamoto, H. Ichinose, and T. Hoshi, Computer Physics Communications 280, 108465 (2022). + +Bibtex: + +| @article{MOTOYAMA2022108465, +| title = {Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures}, +| journal = {Computer Physics Communications}, +| volume = {280}, +| pages = {108465}, +| year = {2022}, +| issn = {0010-4655}, +| doi = {https://doi.org/10.1016/j.cpc.2022.108465}, +| url = {https://www.sciencedirect.com/science/article/pii/S0010465522001849}, +| author = {Yuichi Motoyama and Kazuyoshi Yoshimi and Izumi Mochizuki and Harumichi Iwamoto and Hayato Ichinose and Takeo Hoshi} +| } + + + +バージョン履歴 +-------------------------------- + +2DMAT-Functions + +- v1.0.0 : 2024-XX-XX + +2DMAT + +- v3.0.0 : 2024-XX-XX +- v2.1.0 : 2022-04-08 +- v2.0.0 : 2022-01-17 +- v1.0.1 : 2021-04-15 +- v1.0.0 : 2021-03-12 +- v0.1.0 : 2021-02-08 + +主な開発者 +-------------------------------- + +2DMATは以下のメンバーで開発しています. + +- v3.0.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 青山 龍美 (東京大学 物性研究所) + - 星 健夫 (核融合科学研究所) + +- v2.0.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 岩本 晴道 (鳥取大学 大学院工学研究科) + - 星 健夫 (鳥取大学 大学院工学研究科) + +- v0.1.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 星 健夫 (鳥取大学 大学院工学研究科) diff --git a/extra/function/doc/ja/source/solver.rst b/extra/function/doc/ja/source/solver.rst new file mode 100644 index 00000000..68c9d6c5 --- /dev/null +++ b/extra/function/doc/ja/source/solver.rst @@ -0,0 +1,47 @@ +定義済み関数 +================================================================ + +``2DMAT-Functions`` モジュールは、探索アルゴリズムの性能評価を目的とした定義済みのベンチマーク関数 :math:`f(x)` を計算する ``Solver`` です。 + +それぞれの関数は 2DMAT の順問題ソルバーとして利用可能なクラスとして実装されています。 +定義済みの関数は以下のとおりです。 + +- ``Quadratics`` + + - 二次形式 + + .. math:: + + f(\vec{x}) = \sum_{i=1}^N x_i^2 + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Rosenbrock`` + + - `Rosenbrock 関数 `_ + + .. math:: + + f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right] + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)` + +- ``Ackley`` + + - `Ackley 関数 `_ + + .. math:: + + f(\vec{x}) = 20 + e - 20\exp\left[-0.2\sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}\right] - \exp\left[\frac{1}{N}\cos\left(2\pi x_i\right)\right] + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Himmelblau`` + + - `Himmelblau 関数 `_ + + .. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + + - 最適値は :math:`f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0` diff --git a/extra/function/doc/ja/source/tutorial/booth.rst b/extra/function/doc/ja/source/tutorial/booth.rst new file mode 100644 index 00000000..a589b941 --- /dev/null +++ b/extra/function/doc/ja/source/tutorial/booth.rst @@ -0,0 +1,186 @@ +関数の追加 +================================ + +ここでは、2DMAT-Functions モジュールを用いて、ユーザが新しい関数を作成して解析を行う手順を説明します。例として次の Booth 関数 + +.. math:: + + f(x,y) = (x + 2 y - 7) ^2 + (2 x + y - 5) ^2 + +を追加してみます。この関数の最小値は :math:`f(1,3) = 0` です。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +サンプルファイルは ``sample/booth`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``booth.py`` + + Booth関数を計算する順問題ソルバーを定義する + +- ``main.py`` + + メインプログラム。パラメータを ``input.toml`` ファイルから読み込んで解析を行う + +- ``input.toml`` + + ``simple.py`` で利用する入力パラメータファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したのち、実際の計算結果を紹介します。 + + +プログラムの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``booth.py`` では、2DMAT-Functions を利用して Booth 関数を計算する順問題ソルバークラスを定義します。プログラムの全体を以下に示します。 + +.. code-block:: python + + import numpy as np + import py2dmat.extra.function + + class Booth(py2dmat.extra.function.Solver): + def evaluate(self, xs: np.ndarray, args=()): + assert xs.shape[0] == 2 + x, y = xs + fx = (x + 2 * y - 7)**2 + (2 * x + y - 5)**2 + return fx + +プログラムでは、まず必要なモジュールを import します。 +``py2dmat.extra.function`` は 2DMAT-Functions モジュールです。 + +次に、2DMAT-Functions の ``Solver`` クラスを基底クラスとして ``Booth`` クラスを作成します。 +関数値を評価するメソッドを ``evaluate(self, xs, args) -> float`` として定義します。 +``evaluate`` の引数は、パラメータ値を表す ``numpy.ndarray`` 型の引数 ``xs`` と、 ``Tuple`` 型のオプションパラメータ ``args`` です。 +``args`` はステップ数 ``step`` と n巡目を表す ``set`` からなり、必要に応じてクラス内で使用します。 + + +``main.py`` は Booth クラスを用いて解析を行うシンプルなプログラムです。 + +.. code-block:: python + + import numpy as np + + import py2dmat + import py2dmat.algorithm.min_search as min_search + from booth import Booth + + info = py2dmat.Info.from_file("input.toml") + solver = Booth(info) + runner = py2dmat.Runner(solver, info) + + alg = min_search.Algorithm(info, runner) + alg.main() + +プログラム中ではまず、解析で利用するクラスのインスタンスを作成します。 + +- ``py2dmat.Info`` クラス + + パラメータを格納するクラスです。 ``from_file`` クラスメソッドに TOML ファイルのパスを渡して作成することができます。 + +- ``Booth`` クラス + + 上記で作成した booth.py から Booth クラスを import してインスタンスを作成します。 + +- ``py2dmat.Runner`` クラス + + 順問題ソルバーと逆問題解析アルゴリズムを繋ぐクラスです。Solver クラスのインスタンスおよび Info クラスのパラメータを渡して作成します。 + +- ``py2dmat.algorithm.min_search.Algorithm`` クラス + + 逆問題解析アルゴリズムのクラスです。ここでは Nelder-Mead法による最適化アルゴリズムのクラスモジュール ``min_search`` を利用します。Runner のインスタンスを渡して作成します。 + +Solver, Runner, Algorithm の順にインスタンスを作成した後、Algorithm クラスの ``main()`` メソッドを呼んで解析を行います。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` の例を以下に示します。 + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + + [solver] + + [runner] + [runner.log] + interval = 20 + + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。 + +.. code-block:: + + $ cd sample/booth + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ python3 main.py | tee log.txt + +実行すると、以下の様な出力がされます。 + +.. code-block:: + + Optimization terminated successfully. + Current function value: 0.000000 + Iterations: 44 + Function evaluations: 82 + iteration: 44 + len(allvecs): 45 + step: 0 + allvecs[step]: [ 5.15539311 -2.20349335] + step: 1 + allvecs[step]: [ 4.65539311 -1.82849335] + step: 2 + allvecs[step]: [ 4.40539311 -1.26599335] + step: 3 + allvecs[step]: [ 3.28039311 -0.73474335] + step: 4 + allvecs[step]: [2.21789311 0.65588165] + step: 5 + allvecs[step]: [2.21789311 0.65588165] + ... + step: 42 + allvecs[step]: [0.99997645 3.00001226] + step: 43 + allvecs[step]: [0.99997645 3.00001226] + end of run + Current function value: 1.2142360244883376e-09 + Iterations: 44 + Function evaluations: 82 + Solution: + x1 = 0.9999764520155436 + x2 = 3.000012263854959 + + +``x1``, ``x2`` に各ステップでの候補パラメータと、その時の目的関数の値が出力されます。 +最終的に推定されたパラメータは、 ``output/res.dat`` に出力されます。今の場合、 + +.. code-block:: + + fx = 1.2142360244883376e-09 + x1 = 0.9999764520155436 + x2 = 3.000012263854959 + +となり、最小値が再現されていることがわかります。 +なお、一連の計算を行う ``do.sh`` スクリプトが用意されています。 diff --git a/extra/function/doc/ja/source/tutorial/himmelblau.rst b/extra/function/doc/ja/source/tutorial/himmelblau.rst new file mode 100644 index 00000000..51969509 --- /dev/null +++ b/extra/function/doc/ja/source/tutorial/himmelblau.rst @@ -0,0 +1,153 @@ +Himmelblau関数の最小化 +================================ + +ここでは、2DMAT-Functions モジュールを用いたユーザプログラムを作成し、解析を行う方法を説明します。逆問題アルゴリズムは例としてNelder-Mead法を用います。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +サンプルファイルは ``sample/himmelblau`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``main.py`` + + メインプログラム。パラメータを ``input.toml`` ファイルから読み込んで解析を行う。 + +- ``input.toml`` + + ``main.py`` で利用する入力パラメータファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +- ``plot_colormap_2d.py`` + + 可視化ツール + +以下、これらのファイルについて説明したのち、実際の計算結果を紹介します。 + + +プログラムの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``main.py`` は 2DMAT-Functions モジュールを用いて解析を行うシンプルなプログラムです。 +プログラムの全体を以下に示します。 + +.. code-block:: python + + import numpy as np + + import py2dmat + import py2dmat.algorithm.mapper_mpi as mapper + from py2dmat.extra.function import Himmelblau + + info = py2dmat.Info.from_file("input.toml") + solver = Himmelblau(info) + runner = py2dmat.Runner(solver, info) + + alg = mapper.Algorithm(info, runner) + alg.main() + +プログラムではまず、必要なモジュールを import します。 + +- 2DMAT のメインモジュール ``py2dmat`` + +- 今回利用する逆問題解析アルゴリズム ``py2dmat.algorithm.mapper_mpi`` + +- 順問題ソルバーモジュール ``py2dmat.extra.function`` から Himmelblau クラス + +次に、解析で利用するクラスのインスタンスを作成します。 + +- ``py2dmat.Info`` クラス + + パラメータを格納するクラスです。 ``from_file`` クラスメソッドに TOML ファイルのパスを渡して作成することができます。 + +- ``Himmelblau`` クラス + + 2DMAT-Functions に用意されている Himmelblau関数のクラスです。Info クラスのインスタンスを渡して作成します。 + +- ``py2dmat.Runner`` クラス + + 順問題ソルバーと逆問題解析アルゴリズムを繋ぐクラスです。Solver クラスのインスタンスおよび Info クラスのパラメータを渡して作成します。 + +- ``py2dmat.algorithm.mapper_mpi.Algorithm`` クラス + + 逆問題解析アルゴリズムのクラスです。ここではグリッド全探索のクラスモジュール ``mapper_mpi`` を利用します。Runner のインスタンスを渡して作成します。 + +Solver, Runner, Algorithm の順にインスタンスを作成した後、Algorithm クラスの ``main()`` メソッドを呼んで解析を行います。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` の例を以下に示します。 +なお、アルゴリズムの種類を指定する ``algorithm.name`` パラメータの値は無視されます。 + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + + [solver] + + [runner] + [runner.log] + interval = 20 + + +計算実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します) + +.. code-block:: + + $ cd sample/himmelblau + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ mpiexec -np 4 python3 main.py + +ここではMPIを利用して4プロセスで計算を行っています。実行すると以下の様な出力がされます。 + +.. code-block:: + + Make ColorMap + Iteration : 1/240 + Iteration : 2/240 + Iteration : 3/240 + Iteration : 4/240 + Iteration : 5/240 + Iteration : 6/240 + Iteration : 7/240 + Iteration : 8/240 + Iteration : 9/240 + Iteration : 10/240 + ... + +結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ColorMap.txt`` を図示することで、関数の値が小さいパラメータがどこにあるかを推定することができます。そのような 2次元パラメータ空間のプロットを作成するプログラムが ``plot_colormap_2d.py`` に用意されています。 + +.. code-block:: + + $ python3 plot_colormap_2d.py + +上記を実行すると ``ColorMapFig.png`` が作成され、Himmelblau関数の関数値を表す等高線の上に、各グリッド点で評価した関数値がカラーマップとしてプロットされます。 + +.. figure:: ../../../common/img/himmelblau_mapper.* + + 2次元パラメータ空間上での関数値のカラーマップ。 + diff --git a/extra/function/doc/ja/source/tutorial/index.rst b/extra/function/doc/ja/source/tutorial/index.rst new file mode 100644 index 00000000..8f24690c --- /dev/null +++ b/extra/function/doc/ja/source/tutorial/index.rst @@ -0,0 +1,17 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +チュートリアル +================================== + +このチュートリアルでは、Himmelblau関数の最小化問題を例として 2DMAT および 2DMAT-Functions ライブラリの使い方を解説します。あわせて、ユーザが独自の関数を定義して解析を行う方法を説明します。 + +逆問題解析アルゴリズムはグリッド探索の ``mapper`` モジュールを使います。その他のアルゴリズムについては 2DMAT のマニュアルを参照してください。 + +.. toctree:: + :maxdepth: 1 + + himmelblau + booth