From e52016a4464f897b2631390a6013fbba8a5c4b2f Mon Sep 17 00:00:00 2001 From: "T.Aoyama" Date: Sat, 3 Aug 2024 17:12:37 +0900 Subject: [PATCH] add english manual --- extra/function/doc/en/Makefile | 20 ++ extra/function/doc/en/make.bat | 36 ++++ .../doc/en/source/acknowledgement.rst | 6 + extra/function/doc/en/source/conf.py | 190 +++++++++++++++++ extra/function/doc/en/source/contact.rst | 22 ++ extra/function/doc/en/source/index.rst | 26 +++ extra/function/doc/en/source/install.rst | 75 +++++++ extra/function/doc/en/source/introduction.rst | 91 ++++++++ extra/function/doc/en/source/solver.rst | 47 +++++ .../function/doc/en/source/tutorial/booth.rst | 196 ++++++++++++++++++ .../doc/en/source/tutorial/himmelblau.rst | 163 +++++++++++++++ .../function/doc/en/source/tutorial/index.rst | 18 ++ 12 files changed, 890 insertions(+) create mode 100644 extra/function/doc/en/Makefile create mode 100644 extra/function/doc/en/make.bat create mode 100644 extra/function/doc/en/source/acknowledgement.rst create mode 100644 extra/function/doc/en/source/conf.py create mode 100644 extra/function/doc/en/source/contact.rst create mode 100644 extra/function/doc/en/source/index.rst create mode 100644 extra/function/doc/en/source/install.rst create mode 100644 extra/function/doc/en/source/introduction.rst create mode 100644 extra/function/doc/en/source/solver.rst create mode 100644 extra/function/doc/en/source/tutorial/booth.rst create mode 100644 extra/function/doc/en/source/tutorial/himmelblau.rst create mode 100644 extra/function/doc/en/source/tutorial/index.rst diff --git a/extra/function/doc/en/Makefile b/extra/function/doc/en/Makefile new file mode 100644 index 00000000..ed7c6d24 --- /dev/null +++ b/extra/function/doc/en/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = pyMC +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/en/make.bat b/extra/function/doc/en/make.bat new file mode 100644 index 00000000..36108d30 --- /dev/null +++ b/extra/function/doc/en/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=python -msphinx +) +set SOURCEDIR=source +set BUILDDIR=build +set SPHINXPROJ=pyMC + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The Sphinx module was not found. Make sure you have Sphinx installed, + echo.then set the SPHINXBUILD environment variable to point to the full + echo.path of the 'sphinx-build' executable. Alternatively you may add the + echo.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% -W %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/extra/function/doc/en/source/acknowledgement.rst b/extra/function/doc/en/source/acknowledgement.rst new file mode 100644 index 00000000..5db6b52f --- /dev/null +++ b/extra/function/doc/en/source/acknowledgement.rst @@ -0,0 +1,6 @@ +*************************** +Acknowledgements +*************************** + +The development of 2DMAT was supported by JSPS KAKENHI Grant Number 19H04125 "Unification of computational statistics and measurement technology by massively parallel machine" +and "Project for advancement of software usability in materials science" (fiscal year 2020, 2021, 2024) of The Institute for Solid State Physics, The University of Tokyo. diff --git a/extra/function/doc/en/source/conf.py b/extra/function/doc/en/source/conf.py new file mode 100644 index 00000000..18a0da38 --- /dev/null +++ b/extra/function/doc/en/source/conf.py @@ -0,0 +1,190 @@ +# -*- coding: utf-8 -*- +# +# MateriApps-Installer documentation build configuration file, created by +# sphinx-quickstart on Sun May 1 14:29:22 2020. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# 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('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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 suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'2DMAT solver module: Functions' +copyright = u'2020, Institute for Solid State Physics, University of Tokyo' +author = u'2DMAT Developer team' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'1.0' +# The full version, including alpha/beta/rc tags. +release = u'1.0-dev' + +# 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 = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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' + +# 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 = { + # 'font_family': 'Helvetica', + # 'sidebar_search_button': 'pink_1' +} + +# 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 = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + + +# 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'] + +numfig = True + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = '2DMATdoc' + + +# -- 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.tex', u'2DMAT Functions Documentation', + author, 'manual', 'True'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, '2dmat-functions', u'2DMAT Documentation', + [author], 1) +] + +#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-functions', 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/en/source/contact.rst b/extra/function/doc/en/source/contact.rst new file mode 100644 index 00000000..b27117bf --- /dev/null +++ b/extra/function/doc/en/source/contact.rst @@ -0,0 +1,22 @@ +Contact +========================================= + +- Bug Reports + + Please report all problems and bugs on the github `Issues `_ page. + + To resolve bugs early, follow these guidelines when reporting: + + 1. Please specify the version of 2DMAT and 2DMAT-Functions you are using. + + 2. If there are problems for installation, please inform us about your operating system and the compiler. + + 3. If a problem occurs during execution, enter the input file used for execution and its output. + + Thank you for your cooperation. + +- Others + + If you have any questions about your research that are difficult to consult at Issues on GitHub, please send an e-mail to the following address: + + E-mail: ``2dmat-dev__at__issp.u-tokyo.ac.jp`` (replace _at_ by @) diff --git a/extra/function/doc/en/source/index.rst b/extra/function/doc/en/source/index.rst new file mode 100644 index 00000000..47a80e4c --- /dev/null +++ b/extra/function/doc/en/source/index.rst @@ -0,0 +1,26 @@ +.. 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 + +.. + input + output + algorithm/index + solver/index + tool + customize/index diff --git a/extra/function/doc/en/source/install.rst b/extra/function/doc/en/source/install.rst new file mode 100644 index 00000000..56ec6014 --- /dev/null +++ b/extra/function/doc/en/source/install.rst @@ -0,0 +1,75 @@ +Installation of 2DMAT-Functions +================================================================ + +Prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- Python3 (>=3.6.8) + + - The following Python packages are required. + + - tomli >= 1.2 + - numpy >= 1.14 + +- py2dmat version 3.0 and later + + +How to download and install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Install py2dmat + + - From source files: + + Download source files of py2dmat from the repository as follows: + + .. code-block:: bash + + $ git clone -b update https://github.com/issp-center-dev/2DMAT.git + + Install py2dmat using ``pip`` command: + + .. code-block:: bash + + $ cd 2DMAT + $ python3 -m pip install . + + You may add ``--user`` option to install py2dmat locally (in ``$HOME/.local``). + + If you run the following command instead, optional packages will also be installed at the same time. + + .. code-block:: bash + + $ python3 -m pip install .[all] + +2. Install py2dmat-function + + - From source files: + + At present, the source files of 2dmat-functions are placed in ``extra`` directory of py2dmat source package. After obtaining the source files following the step 1, install 2dmat-functions using ``pip`` command as follows: + + .. code-block:: bash + + $ cd 2DMAT/extra/function + $ python3 -m pip install . + + You may add ``--user`` option to install the package locally (in ``$HOME/.local``). + + Then, the library of 2DMAT-Functions wil be installed. + + +How to run +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In 2DMAT, the analysis is done by using a predefined optimization algorithm and a direct problem solver. +The ways to do analyses of Functions is to write a program for the analysis with 2DMAT-Functions library and 2DMAT framework. +The type of the inverse problem algorithms can be chosen by importing the appropriate module. +A flexible use would be possible, for example, to include data generation within the program. +The types of parameters and the instruction to use the library will be given in the subsequent sections. + + +How to uninstall +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In order to uninstall 2DMAT-Functions and 2DMAT modules, type the following commands: + +.. code-block:: bash + + $ python3 -m pip uninstall py2dmat-function py2dmat diff --git a/extra/function/doc/en/source/introduction.rst b/extra/function/doc/en/source/introduction.rst new file mode 100644 index 00000000..c5c6e564 --- /dev/null +++ b/extra/function/doc/en/source/introduction.rst @@ -0,0 +1,91 @@ +Introduction +================================ + +What is 2DMAT ? +-------------------------------- + +2DMAT is a framework for applying a search algorithm to a direct problem solver to find the optimal solution. +As the standard direct problem solver, the experimental data analysis software for two-dimensional material structure analysis is prepared. +The direct problem solver gives the deviation between the experimental data and the calculated data obtained under the given parameters such as atomic positions as a loss function used in the inverse problem. +The optimal parameters are estimated by minimizing the loss function using a search algorithm. For further use, the original direct problem solver or the search algorithm can be defined by users. +In the current version, for solving a direct problem, 2DMAT offers the wrapper of the solver for the total-reflection high-energy positron diffraction (TRHEPD), the surface X-ray diffraction (Functions), and the low-energy electron diffraction (LEED). +As algorithms, it offers the Nelder-Mead method, the grid search method, the Bayesian optimization method, the replica exchange Monte Carlo method, and the population annealing Monte Carlo method. + + +What is 2DMAT-Functions ? +-------------------------------- + +``2DMAT-Functions`` provides implementation of several analytical functions for the direct problems of 2DMAT. +The major use of this module is to test and benchmark the optimization algorithms of 2DMAT, while it may be useful as a template when the users write their own direct problem solvers. + +It was originally developed as a component of 2DMAT v2.x, and has been restructured as a separate module to be used with 2DMAT. + + + +License +-------------------------------- +| This package is distributed under GNU General Public License version 3 (GPL v3). + +Copyright (c) <2020-> The University of Tokyo. All rights reserved. + +This software was developed with the support of "Project for advancement of software usability in materials science" of The Institute for Solid State Physics, The University of Tokyo. +We hope that you cite the following reference when you publish the results using 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} +| } + + +Version Information +-------------------------------- + +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 + + +Main developers +-------------------------------- + +2DMAT has been developed by following members. + +- v3.0.0 - + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - T. Aoyama (The Institute for Solid State Physics, The University of Tokyo) + - T. Hoshi (National Institute for Fusion Science) + +- v2.0.0 - + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - H. Iwamoto (Department of Applied Mathematics and Physics, Tottori University) + - T. Hoshi (Department of Applied Mathematics and Physics, Tottori University) + +- v0.1.0 - v1.0.1 + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - T. Hoshi (Department of Applied Mathematics and Physics, Tottori University) diff --git a/extra/function/doc/en/source/solver.rst b/extra/function/doc/en/source/solver.rst new file mode 100644 index 00000000..aa764619 --- /dev/null +++ b/extra/function/doc/en/source/solver.rst @@ -0,0 +1,47 @@ +Predefined functions +================================ + +``2DMAT-Functions`` module provides ``Solver`` that computes a predefined benchmark function :math:`f(x)` for evaluating the performance of search algorithms. + +Each function is implemented as a class that can be used for a direct solver of 2DMAT. +The predefined functions are listed as follows. + +- ``Quadratics`` + + - Quadratic function + + .. math:: + + f(\vec{x}) = \sum_{i=1}^N x_i^2 + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Rosenbrock`` + + - `Rosenbrock function `_ + + .. math:: + + f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right] + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)` + +- ``Ackley`` + + - `Ackley function `_ + + .. 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] + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Himmerblau`` + + - `Himmerblau function `_ + + .. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + + - The optimized value :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/en/source/tutorial/booth.rst b/extra/function/doc/en/source/tutorial/booth.rst new file mode 100644 index 00000000..35f5dc10 --- /dev/null +++ b/extra/function/doc/en/source/tutorial/booth.rst @@ -0,0 +1,196 @@ +Adding functions +================================ + +In this tutorial, we describe the procedure how to define a new function and perform analyses. +As an example, we will introduce Booth function given below: + +.. math:: + + f(x,y) = (x + 2 y - 7) ^2 + (2 x + y - 5) ^2 + +The minimum value of this function is :math:`f(1,3) = 0`. + + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/booth``. +The following files are stored in the folder. + +- ``booth.py`` + + Source file of the direct problem solver that evaluates Booth function. + +- ``main.py`` + + Source file of the main program. This program reads ``input.toml`` for the parameters. + +- ``input.toml`` + + Input parameter file for ``main.py``. + +- ``do.sh`` + + Script file for running this tutorial. + +The following sections describe these files and then show the actual calculation results. + + +Description of main program +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ``booth.py``, a class for the direct problem solver is defined using 2DMAT-Functions module that evaluates Booth function. +The entire program is shown as follows: + +.. 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 + +First, the required modules are imported. +``py2dmat.extra.function`` corresponds to 2DMAT-Functions module. + +Next, ``Booth`` class is defined as derived from ``Solver`` class of 2DMAT-Functions. +The direct problem solver class must have a method called ``evaluate`` which have the form ``evaluate(self, xs, args) -> float``. +The arguments of this method are: +``xs`` of ``numpy.ndarray`` type for the parameter values, and ``args`` of ``Tuple`` type for the optional data that consists of the step count ``step`` and the iteration count ``set`` used in the class accordingly. + +``main.py`` is a simple program that performs analyses using the Booth class. + +.. 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() + + +In the program, the instances of the classes are created. + +- ``py2dmat.Info`` class + + This class is for storing the parameters. + An instance is created by calling a class method ``from_file`` with a path to TOML file as an argument. + +- ``Booth`` class + + Booth class is imported from ``booth.py`` as introduced above, and is instantiated. + +- ``py2dmat.Runner`` class + + This class is for connecting the direct problem solver and the inverse problem algorithm. + An instance is created by passing an instance of Solver class and an instance of Info class. + +- ``py2dmat.algorithm.min_search.Algorithm`` class + + This class is for the inverse problem algorithm. + In this tutorial, we use ``min_search`` module that implements the optimization by Nelder-Mead method. + An instance is created by passing an instance of Runner class. + +After creating the instances of Solver, Runner, and Algorithm in this order, we invoke ``main()`` method of the Algorithm class to start analyses. + + +Input files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An example of the input parameter file ``input.toml`` is shown below. + +.. 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 + + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample files are located. + +.. code-block:: + + $ cd sample/booth + +Run the main program. The computation time will take only a few seconds on a normal PC. + +.. code-block:: + + $ python3 main.py | tee log.txt + +The standard output will look as follows. + +.. 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`` and ``x2`` are the candidate parameters at each step. +The final estimated parameters will be written in ``output/res.dat``. +In the current case, the following result will be obtained: + +.. code-block:: + + fx = 1.2142360244883376e-09 + x1 = 0.9999764520155436 + x2 = 3.000012263854959 + +It is found that the minimum has been reproduced. + +Note that ``do.sh`` is available as a script for batch calculation. diff --git a/extra/function/doc/en/source/tutorial/himmelblau.rst b/extra/function/doc/en/source/tutorial/himmelblau.rst new file mode 100644 index 00000000..d44573d2 --- /dev/null +++ b/extra/function/doc/en/source/tutorial/himmelblau.rst @@ -0,0 +1,163 @@ +Minimization of Himmelblau function +================================================================ + +In this tutorial, we will write a user program using 2DMAT-Functions module and perform analyese. As an example, we adopt the Nelder-Mead method for the inverse problem algorithm. + + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/himmelblau``. +The following files are stored in the folder. + +- ``main.py`` + + Source file of the main program. This program reads ``input.toml`` for the parameters. + +- ``input.toml`` + + Input parameter file for ``main.py``. + +- ``do.sh`` + + Script file for running this tutorial. + +- ``plot_colormap_2d.py`` + + Program for visualizing the results. + +The following sections describe these files and then show the actual calculation results. + + +Description of main program +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``main.py`` is a simple program for the analyses using 2DMAT-Functions module. +The entire source file is shown as follows: + +.. 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() + + +At the beginning of the program, the required modules are imported as listed below. + +- ``py2dmat`` for the main module of 2DMAT. + +- ``py2dmat.algorithm.mapper_mpi`` for the module of the inverse problem algorithm. + +- ``Himmelblau`` class from ``py2dmat.extra.function`` module. + +Next, the instances of the classes are created. + +- ``py2dmat.Info`` class + + This class is for storing the parameters. + An instance is created by calling a class method ``from_file`` with a path to TOML file as an argument. + +- ``Himmelblau`` class + + This class is for the Himmelblau function defined in the 2DMAT-Functions module. + An instance is created by passing an instance of Info class. + +- ``py2dmat.Runner`` class + + This class is for connecting the direct problem solver and the inverse problem algorithm. + An instance is created by passing an instance of Solver class and an instance of Info class. + +- ``py2dmat.algorithm.min_search.Algorithm`` class + + This class is for the inverse problem algorithm. + In this tutorial, we use ``min_search`` module that implements the optimization by Nelder-Mead method. + An instance is created by passing an instance of Runner class. + +After creating the instances of Solver, Runner, and Algorithm in this order, we invoke ``main()`` method of the Algorithm class to start analyses. + + +Input files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An example of the input parameter file ``input.toml`` is shown below. +Except, ``algorithm.name`` parameter for specifying the algorithm type should be ignored. + +.. 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 + + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample files are located. (We assume that you are directly under the directory where you downloaded this software.) + +.. code-block:: + + $ cd sample/himmelblau + +Run the main program. The computation time will take only a few seconds on a normal PC. + +.. code-block:: + + $ mpiexec -np 4 python3 main.py + +In the above, the main program is executed with 4 MPI parallel processes. +The standard output will look as follows. + +.. 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 + ... + + +Visualization of results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By plotting ``output/ColorMap.txt``, you can identify the region of parameters in which the function yield small values. +A program to draw such a two-dimensional plot is prepared in ``plot_colormap_2d.py``. + +.. code-block:: + + $ python3 plot_colormap_2d.py + +By typing as above, ``ColorMapFig.png`` is generated in which a color map of the function values evaluated at the grid, on top of the contour of Himmelblau function. + +.. figure:: ../../../common/img/himmelblau_mapper.* + + A color map of the function values in the two-dimensional parameter space. diff --git a/extra/function/doc/en/source/tutorial/index.rst b/extra/function/doc/en/source/tutorial/index.rst new file mode 100644 index 00000000..dbdb9439 --- /dev/null +++ b/extra/function/doc/en/source/tutorial/index.rst @@ -0,0 +1,18 @@ +.. 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. + +Tutorials +================================ + +In this tutorial, we will instruct how to use 2DMAT and 2DMAT-Functions modules, considering the minimization problem of Himmelblau function as an example. + +For the inverse problem algorithm we adopt the grid search provided as ``mapper`` module. See the 2DMAT manual for other algorithms. + + +.. toctree:: + :maxdepth: 1 + + himmelblau + booth