revise english manual

issp-center-dev · Jul 31, 2024 · 66e0839 · 66e0839
1 parent 40cb55d
commit 66e0839
Show file tree

Hide file tree

Showing 44 changed files with 1,004 additions and 2,319 deletions.
diff --git a/doc/common/img/RC_double_minsearch.pdf b/doc/common/img/RC_double_minsearch.pdf
diff --git a/doc/common/img/RC_double_minsearch.png b/doc/common/img/RC_double_minsearch.png
diff --git a/doc/common/img/exchange.pdf b/doc/common/img/exchange.pdf
diff --git a/doc/common/img/exchange.png b/doc/common/img/exchange.png
diff --git a/doc/common/img/mapper.pdf b/doc/common/img/mapper.pdf
diff --git a/doc/common/img/mapper.png b/doc/common/img/mapper.png
diff --git a/doc/common/img/pamc_T.pdf b/doc/common/img/pamc_T.pdf
diff --git a/doc/common/img/pamc_T.png b/doc/common/img/pamc_T.png
diff --git a/doc/common/img/pamc_fx.pdf b/doc/common/img/pamc_fx.pdf
diff --git a/doc/common/img/pamc_fx.png b/doc/common/img/pamc_fx.png
diff --git a/doc/common/img/plot_bulkP.pdf b/doc/common/img/plot_bulkP.pdf
diff --git a/doc/common/img/plot_bulkP.png b/doc/common/img/plot_bulkP.png
diff --git a/doc/en/source/acknowledgement.rst b/doc/en/source/acknowledgement.rst
@@ -1,8 +1,8 @@
-***************************
-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" of The Institute for Solid State Physics, The University of Tokyo.
-A part of the design of and naming in software is inspired by `abics <https://github.com/issp-center-dev/abics>`_
-For the implementation of the forward problem solver,
-we thank to T. Hanada (Tohoku Univ.), I. Mochizuki (KEK), W. Voegeli (Tokyo Gakugei Univ.), T. Shirasawa(AIST), R. Ahmed (Kyushu Univ.), and K. Wada(KEK). For adding a tutorial for customizing solver, we thank to K. Tsukamoto (ISSP).
+***************************
+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" of The Institute for Solid State Physics, The University of Tokyo.
+A part of the design of and naming in software is inspired by `abics <https://github.com/issp-center-dev/abics>`_
+For the implementation of the forward problem solver,
+we thank to T. Hanada (Tohoku Univ.), I. Mochizuki (KEK), W. Voegeli (Tokyo Gakugei Univ.), T. Shirasawa(AIST), R. Ahmed (Kyushu Univ.), and K. Wada(KEK). For adding a tutorial for customizing solver, we thank to K. Tsukamoto (ISSP).
diff --git a/doc/en/source/algorithm/bayes.rst b/doc/en/source/algorithm/bayes.rst
@@ -1,4 +1,4 @@
-Bayse optimization ``bayes``
+Bayesian optimization ``bayes``
 *******************************
 
 .. _PHYSBO: https://www.pasums.issp.u-tokyo.ac.jp/physbo/en
@@ -8,9 +8,11 @@ The implementation is based on `PHYSBO`_.
 
 Preparation
 ~~~~~~~~~~~~
-You will need to install `PHYSBO`_ beforehand.::
+You will need to install `PHYSBO`_ beforehand.
 
-  python3 -m pip install physbo
+.. code-block:: bash
+
+   $ python3 -m pip install physbo
 
 If `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ is installed, MPI parallel computing is possible.
 
@@ -52,7 +54,8 @@ If ``mesh_path`` is not defined, ``min_list``, ``max_list``, and ``num_list`` ar
 
   Format: List of integer. The length should match the value of dimension.
 
-  Description:  The number of grids the parametar can take at each dimension.
+  Description: The number of grids the parametar can take at each dimension.
+
 
 [``algorithm.bayes``] section
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -122,9 +125,7 @@ Output files
 ``BayesData.txt`` 
 ^^^^^^^^^^^^^^^^^^^^^^
 
-At each step of the optimization process,
-the values of the parameters and the corresponding objective functions are listed in the order of the optimal parameters so far
-and the searched parameters at that step.
+At each step of the optimization process, the values of the parameters and the corresponding objective functions are listed in the order of the optimal parameters so far and the searched parameters at that step.
 
 .. code-block::
 

diff --git a/doc/en/source/algorithm/exchange.rst b/doc/en/source/algorithm/exchange.rst
@@ -6,9 +6,11 @@ Replica exchange Monte Carlo ``exchange``
 Preparation
 ~~~~~~~~~~~~~~~~
 
-`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ should be installed. ::
+`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ should be installed if MPI parallelization is used.
 
-  python3 -m pip install mpi4py
+.. code-block::
+
+   $ python3 -m pip install mpi4py
 
 Input parameters
 ~~~~~~~~~~~~~~~~~~~
@@ -35,26 +37,29 @@ Otherwise, continuous space is used.
 
     Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Unit length of each parameter.
+    Description:
+    Unit length of each parameter.
     ``Algorithm`` makes parameters dimensionless and normalized by dividing these by ``unit_list``.
     If not defined, each component will be 1.0.
 
   - ``min_list``
 
     Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Minimum value of each parameter.
-                 When a parameter falls below this value during the Monte Carlo search,
-                 the solver is not evaluated and the value is considered infinite.
+    Description:
+    Minimum value of each parameter.
+    When a parameter falls below this value during the Monte Carlo search,
+    the solver is not evaluated and the value is considered infinite.
 
 
   - ``max_list``
 
     Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Maximum value of each parameter.
-                 When a parameter exceeds this value during the Monte Carlo search,
-                 the solver is not evaluated and the value is considered infinite.
+    Description:
+    Maximum value of each parameter.
+    When a parameter exceeds this value during the Monte Carlo search,
+    the solver is not evaluated and the value is considered infinite.
 
 - Discrete space
 

diff --git a/doc/en/source/algorithm/mapper_mpi.rst b/doc/en/source/algorithm/mapper_mpi.rst
@@ -7,9 +7,11 @@ In the case of MPI execution, the set of candidate points is divided into equal
 Preparation
 ~~~~~~~~~~~~
 
-For MPI parallelism, you need to install `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_.::
+For MPI parallelism, you need to install `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_.
 
-  python3 -m pip install mpi4py
+.. code-block::
+
+   $ python3 -m pip install mpi4py
 
 Input parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -60,6 +62,7 @@ Mesh definition file
 Define the grid space to be explored in this file.
 1 + ``dimension`` columns are required.
 The first column is the index of the mesh, and the second and subsequent columns are the values of parameter.
+The lines starting from ``#`` are ignored as comments.
 
 A sample file for two dimensions is shown below.
 
@@ -82,8 +85,8 @@ Output file
 ``ColorMap.txt``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This file contains the candidate parameters for each mesh and the ``R-factor`` at that time.
-The mesh data is listed in the order of the variables defined in ``string_list`` in the ``[solver]`` - ``[param]`` sections of the input file, and the value of the ``R-factor`` is listed last.
+This file contains the candidate parameters for each mesh and the function value at that time.
+The mesh data is listed in the order of the variables defined in ``string_list`` in the ``[solver]`` - ``[param]`` sections of the input file, and the value of the function value is listed last.
 
 Below, output example is shown.
 

diff --git a/doc/en/source/algorithm/minsearch.rst b/doc/en/source/algorithm/minsearch.rst
@@ -3,7 +3,7 @@ Nelder-Mead method ``minsearch``
 
 .. _scipy.optimize.minimize: https://docs.scipy.org/doc/scipy/reference/optimize.minimize-neldermead.html
 
-When ``minsearch`` is selcted, the optimization by the `Nelder-Mead method <https://en.wikipedia.org/wiki/Nelder%E2%80%93Mead_method>`_ (a.k.a. downhill simplex method) will be done. In the Nelder-Mead method, the dimension of the parameter space is :math:`D`, and the optimal solution is searched by systematically moving pairs of :math:`D+1` coordinate points according to the value of the objective function at each point.
+When ``minsearch`` is selcted, the optimization by the `Nelder-Mead method <https://en.wikipedia.org/wiki/Nelder%E2%80%93Mead_method>`_ (a.k.a. downhill simplex method) will be done. In the Nelder-Mead method, assuming the dimension of the parameter space is :math:`D`, the optimal solution is searched by systematically moving pairs of :math:`D+1` coordinate points according to the value of the objective function at each point.
 
 An important hyperparameter is the initial value of the coordinates.
 Although it is more stable than the simple steepest descent method, it still has the problem of being trapped in the local optimum solution, so it is recommended to repeat the calculation with different initial values several times to check the results.
@@ -15,9 +15,11 @@ For details, see `the official document <https://docs.scipy.org/doc/scipy/refere
 Preparation
 ~~~~~~~~~~~
 
-You will need to install `scipy <https://docs.scipy.org/doc/scipy/reference>`_ .::
+You will need to install `scipy <https://docs.scipy.org/doc/scipy/reference>`_ .
 
-  python3 -m pip install scipy
+.. code-block::
+
+   $ python3 -m pip install scipy
 
 Input parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -39,26 +41,28 @@ It has subsections ``param`` and ``minimize``.
 
   Format: List of float. The length should match the value of dimension.
 
-  Description: Units for each parameter.
-        In the search algorithm, each parameter is divided by each of these values to perform a simple dimensionless and normalization.
-        If not defined, the value is 1.0 for all dimensions.
+  Description:
+  Units for each parameter.
+  In the search algorithm, each parameter is divided by each of these values to perform a simple dimensionless and normalization.
+  If not defined, the value is 1.0 for all dimensions.
 
-  - ``min_list``
-
-    Format: List of float. Length should be equal to ``dimension``.
+- ``min_list``
 
-    Description: Minimum value of each parameter.
-                 When a parameter falls below this value during the Nelson-Mead method,
-                 the solver is not evaluated and the value is considered infinite.
+  Format: List of float. Length should be equal to ``dimension``.
 
+  Description:
+  Minimum value of each parameter.
+  When a parameter falls below this value during the Nelson-Mead method,
+  the solver is not evaluated and the value is considered infinite.
 
-  - ``max_list``
+- ``max_list``
 
-    Format: List of float. Length should be equal to ``dimension``.
+  Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Maximum value of each parameter.
-                 When a parameter exceeds this value during the Nelson-Mead method,
-                 the solver is not evaluated and the value is considered infinite.
+  Description:
+  Maximum value of each parameter.
+  When a parameter exceeds this value during the Nelson-Mead method,
+  the solver is not evaluated and the value is considered infinite.
 
 [``minimize``] section
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -70,7 +74,8 @@ See the documentation of `scipy.optimize.minimize`_ for details.
 
   Format: List of float. The length should match the value of dimension. 
 
-  Description: The difference value that is shifted from the initial value in order to create the initial simplex for the Nelder-Mead method.
+  Description:
+  The difference value that is shifted from the initial value in order to create the initial simplex for the Nelder-Mead method.
   The ``initial_simplex`` is given by the sum of ``initial_list`` and the dimension of the ``initial_list`` plus one component of the ``initial_scale_list``.
   If not defined, scales at each dimension are set to 0.25.
 

diff --git a/doc/en/source/algorithm/pamc.rst b/doc/en/source/algorithm/pamc.rst
@@ -6,9 +6,11 @@ Population Annealing Monte Carlo ``pamc``
 Preparation
 ~~~~~~~~~~~~~~~~
 
-`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ should be installed for the MPI parallelization ::
+`mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ should be installed for the MPI parallelization.
 
-  python3 -m pip install mpi4py
+.. code-block::
+
+   $ python3 -m pip install mpi4py
 
 Input parameters
 ~~~~~~~~~~~~~~~~~~~
@@ -28,33 +30,36 @@ Otherwise, continuous space is used.
 
     Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Initial value of parameters.
+    Description:
+    Initial value of parameters.
     If not defined, these will be initialize randomly.
 
   - ``unit_list``
 
     Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Unit length of each parameter.
+    Description:
+    Unit length of each parameter.
     ``Algorithm`` makes parameters dimensionless and normalized by dividing these by ``unit_list``.
     If not defined, each component will be 1.0.
 
   - ``min_list``
 
     Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Minimum value of each parameter.
-                 When a parameter falls below this value during the Monte Carlo search,
-                 the solver is not evaluated and the value is considered infinite.
-
+    Description:
+    Minimum value of each parameter.
+    When a parameter falls below this value during the Monte Carlo search,
+    the solver is not evaluated and the value is considered infinite.
 
   - ``max_list``
 
     Format: List of float. Length should be equal to ``dimension``.
 
-    Description: Maximum value of each parameter.
-                 When a parameter exceeds this value during the Monte Carlo search,
-                 the solver is not evaluated and the value is considered infinite.
+    Description:
+    Maximum value of each parameter.
+    When a parameter exceeds this value during the Monte Carlo search,
+    the solver is not evaluated and the value is considered infinite.
 
 - Discrete space
 
@@ -473,4 +478,4 @@ References
 
 [2] K. Hukushima and Y. Iba, AIP Conf. Proc. **690**, 200 (2003).
 
-[3] J. Machta, PRE **82**, 026704 (2010).
+[3] J. Machta, Phys. Rev. E **82**, 026704 (2010).
diff --git a/doc/en/source/conf.py b/doc/en/source/conf.py
@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'2.3'
+version = u'3.0'
 # The full version, including alpha/beta/rc tags.
-release = u'2.3-dev'
+release = u'3.0-dev'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/doc/en/source/contact.rst b/doc/en/source/contact.rst
@@ -1,22 +1,22 @@
-Contact
-=========================================
-
-- Bug Reports
-
-  Please report all problems and bugs on the github `Issues <https://github.com/issp-center-dev/2DMAT/releases>`_ page.
-
-  To resolve bugs early, follow these guidelines when reporting:
-
-  1. Please specify the version of 2DMAT 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 @)
+Contact
+=========================================
+
+- Bug Reports
+
+  Please report all problems and bugs on the github `Issues <https://github.com/issp-center-dev/2DMAT/releases>`_ page.
+
+  To resolve bugs early, follow these guidelines when reporting:
+
+  1. Please specify the version of 2DMAT 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 @)