diff --git a/manual/v2.2.0/en/.buildinfo b/manual/v2.2.0/en/.buildinfo new file mode 100644 index 00000000..3d5001ca --- /dev/null +++ b/manual/v2.2.0/en/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 7db9c0de70591c87eb4384e8612421f7 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/manual/v2.2.0/en/_images/RC_double_minsearch.png b/manual/v2.2.0/en/_images/RC_double_minsearch.png new file mode 100644 index 00000000..ac258e46 Binary files /dev/null and b/manual/v2.2.0/en/_images/RC_double_minsearch.png differ diff --git a/manual/v2.2.0/en/_images/exchange.png b/manual/v2.2.0/en/_images/exchange.png new file mode 100644 index 00000000..615df198 Binary files /dev/null and b/manual/v2.2.0/en/_images/exchange.png differ diff --git a/manual/v2.2.0/en/_images/limitation_beta_max.png b/manual/v2.2.0/en/_images/limitation_beta_max.png new file mode 100644 index 00000000..4446b42d Binary files /dev/null and b/manual/v2.2.0/en/_images/limitation_beta_max.png differ diff --git a/manual/v2.2.0/en/_images/limitation_beta_min.png b/manual/v2.2.0/en/_images/limitation_beta_min.png new file mode 100644 index 00000000..7360c798 Binary files /dev/null and b/manual/v2.2.0/en/_images/limitation_beta_min.png differ diff --git a/manual/v2.2.0/en/_images/mapper.png b/manual/v2.2.0/en/_images/mapper.png new file mode 100644 index 00000000..ef4faa25 Binary files /dev/null and b/manual/v2.2.0/en/_images/mapper.png differ diff --git a/manual/v2.2.0/en/_images/pamc_T.png b/manual/v2.2.0/en/_images/pamc_T.png new file mode 100644 index 00000000..331bb662 Binary files /dev/null and b/manual/v2.2.0/en/_images/pamc_T.png differ diff --git a/manual/v2.2.0/en/_images/pamc_fx.png b/manual/v2.2.0/en/_images/pamc_fx.png new file mode 100644 index 00000000..8d58285b Binary files /dev/null and b/manual/v2.2.0/en/_images/pamc_fx.png differ diff --git a/manual/v2.2.0/en/_images/plot_bulkP.png b/manual/v2.2.0/en/_images/plot_bulkP.png new file mode 100644 index 00000000..293325a1 Binary files /dev/null and b/manual/v2.2.0/en/_images/plot_bulkP.png differ diff --git a/manual/v2.2.0/en/_sources/acknowledgement.rst.txt b/manual/v2.2.0/en/_sources/acknowledgement.rst.txt new file mode 100644 index 00000000..02d16ccb --- /dev/null +++ b/manual/v2.2.0/en/_sources/acknowledgement.rst.txt @@ -0,0 +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 `_ +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/manual/v2.2.0/en/_sources/algorithm/bayes.rst.txt b/manual/v2.2.0/en/_sources/algorithm/bayes.rst.txt new file mode 100644 index 00000000..5c9a73f5 --- /dev/null +++ b/manual/v2.2.0/en/_sources/algorithm/bayes.rst.txt @@ -0,0 +1,163 @@ +Bayse optimization ``bayes`` +******************************* + +.. _PHYSBO: https://www.pasums.issp.u-tokyo.ac.jp/physbo/en + +``bayes`` is an ``Algorithm`` that uses Bayesian optimization to perform parameter search. +The implementation is based on `PHYSBO`_. + +Preparation +~~~~~~~~~~~~ +You will need to install `PHYSBO`_ beforehand.:: + + python3 -m pip install physbo + +If `mpi4py `_ is installed, MPI parallel computing is possible. + +.. _bayes_input: + +Input parameters +~~~~~~~~~~~~~~~~~~~~~ + +[``algorithm.param``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section, the search parameter space is defined. + +If ``mesh_path`` is defined, it will be read from a mesh file. +In a mesh file, one line gives one point in the parameter space, +the first column is the data number, and the second and subsequent columns are the coordinates of each dimension. + +If ``mesh_path`` is not defined, ``min_list``, ``max_list``, and ``num_list`` are used to create an evenly spaced grid for each parameter. + +- ``mesh_path`` + + Format: String + + Description: The path to a reference file that contains information about the mesh data. + +- ``min_list`` + + Format: List of float. The length should match the value of dimension. + + Description: The minimum value the parameter can take. + +- ``max_list`` + + Format: List of float.The length should match the value of dimension. + + Description: The maximum value the parameter can take. + +- ``num_list`` + + Format: List of integer. The length should match the value of dimension. + + Description: The number of grids the parametar can take at each dimension. + +[``algorithm.bayes``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The hyper parameters are defined. + +- ``random_max_num_probes`` + + Format: Integer (default: 20) + + Description: Number of random samples to be taken before Bayesian optimization (random sampling is needed if parameters and scores are not available at the beginning). + +- ``bayes_max_num_probes`` + + Format: Integer (default: 40) + + Description: Number of times to perform Bayesian optimization. + +- ``score`` + + Format: String (default: ``TS`` ) + + Description: Parameter to specify the score function. + ``EI`` (expected improvement), ``PI`` (probability of improvement), and ``TS`` (Thompson sampling) can be chosen. + +- ``interval`` + + Format: Integer (default: 5) + + Description: The hyperparameters are learned at each specified interval. If a negative value is specified, no hyperparameter learning will be performed. + If a value of 0 is specified, hyperparameter learning will be performed only in the first step. + +- ``num_rand_basis`` + + Format: Integer (default: 5000) + + Description: Number of basis functions; if 0 is specified, the normal Gaussian process is performed without using the Bayesian linear model. + + +Reference file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mesh definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables defined in ``string_list`` in the ``[solver.param]`` section. + +Below, a sample file is shown. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +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. + +.. code-block:: + + #step z1 z2 R-factor z1_action z2_action R-factor_action + 0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885 + 1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033 + 2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189 + 3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794 + ... + + +Algorithm Description +~~~~~~~~~~~~~~~~~~~~~~ + +`Bayesian optimization (BO) `_ is an optimization algorithm that uses machine learning as an aid, and is particularly powerful when it takes a long time to evaluate the objective function. + +In BO, the objective function :math:`f(\vec{x})` is approximated by a model function (often a Gaussian process) :math:`g(\vec{x})` that is quick to evaluate and easy to optimize. +The :math:`g` is trained to reproduce well the value of the objective function :math:`\{\vec{x}_i\}_{i=1}^N` at some suitably predetermined points (training data set) :math:`\{f(\vec{x}_i)\}_{i=1}^N`. + +At each point in the parameter space, we propose the following candidate points for computation :math:`\vec{x}_{N+1}`, where the expected value of the trained :math:`g(\vec{x})` value and the "score" (acquition function) obtained from the error are optimal. +The training is done by evaluating :math:`f(\vec{x}_{N+1})`, adding it to the training dataset, and retraining :math:`g`. +After repeating these searches, the best value of the objective function as the optimal solution will be returned. + +A point that gives a better expected value with a smaller error is likely to be the correct answer, +but it does not contribute much to improving the accuracy of the model function because it is considered to already have enough information. +On the other hand, a point with a large error may not be the correct answer, +but it is a place with little information and is considered to be beneficial for updating the model function. +Selecting the former is called "exploition," while selecting the latter is called "exploration," and it is important to balance both. +The definition of "score" defines how to choose between them. + +In 2DMAT, we use `PHYSBO`_ as a library for Bayesian optimization. +PHYSBO, like ``mapper_mpi``, computes a "score" for a predetermined set of candidate points, and proposes an optimal solution. +MPI parallel execution is possible by dividing the set of candidate points. +In addition, we use a kernel that allows us to evaluate the model function and thus calculate the "score" with a linear amount of computation with respect to the number of training data points :math:`N`. +In PHYSBO, "expected improvement (EI)", "probability of improvement (PI)", and "Thompson sampling (TS)" are available as "score" functions. + diff --git a/manual/v2.2.0/en/_sources/algorithm/exchange.rst.txt b/manual/v2.2.0/en/_sources/algorithm/exchange.rst.txt new file mode 100644 index 00000000..3a32acce --- /dev/null +++ b/manual/v2.2.0/en/_sources/algorithm/exchange.rst.txt @@ -0,0 +1,336 @@ +Replica exchange Monte Carlo ``exchange`` +============================================= + +``exchange`` explores the parameter space by using the replica exchange Monte Carlo (RXMC) method. + +Preparation +~~~~~~~~~~~~~~~~ + +`mpi4py `_ should be installed. :: + + python3 -m pip install mpi4py + +Input parameters +~~~~~~~~~~~~~~~~~~~ + +This has two subsections ``algorithm.param`` and ``algorithm.exchange`` . + +[``algorithm.param``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This defines a space to be explored. +When ``mesh_path`` key is defined the discrete space is used. +Otherwise, continuous space is used. + +- Continuous space + + - ``initial_list`` + + Format: List of float. Length should be equal to ``dimension``. + + 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. + ``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. + + + - ``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. + +- Discrete space + + - ``mesh_path`` + + Format: string + + Description: Path to the mesh definition file. + + - ``neighborlist_path`` + + Format: string + + Description: Path to the neighborhood-list file. + +[``algorithm.exchange``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + Format: Integer + + Description: The number of Monte Carlo steps. + +- ``numsteps_exchange`` + + Format: Integer + + Description: The number of interval Monte Carlo steps between replica exchange. + +- ``Tmin`` + + Format: Float + + Description: The minimum value of the "temperature" (:math:`T`). + +- ``Tmax`` + + Format: Float + + Description: The maximum value of the "temperature" (:math:`T`). + +- ``bmin`` + + Format: Float + + Description: The minimum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``bmax`` + + Format: Float + + Description: The maximum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``Tlogspace`` + + Format: Boolean (default: true) + + Description: Whether to assign "temperature" to replicas equally spaced in the logarithmic space or not. + +- ``nreplica_per_proc`` + + Format: Integer (default: 1) + + Description: The number of replicas in a MPI process. + +Reference file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mesh definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this "algorithm". + +Below, a sample file is shown. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +Neighborhood-list file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define "neighborhoods" for each point :math:`i`, which are points that a walker can move from :math:`i` +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point :math:`i` is specified by the first column, +and the indices of final points :math:`j` are specified by the second and successive columns. + +An utility tool, ``py2dmat_neighborlist`` is available for generating a neighborhood-list file from a mesh file. For details, please see :doc:`../tool`. + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +Output files +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ +This file stores the suggested parameters and the corresponding value returned from the solver for each replica. +The first column is the index of the MC step. +The second column is the index of the walker in the process. +The third column is the temperature of the replica. +The fourth column is the value of the solver. +The remaining columns are the coordinates. + +Example:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861 + 2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ +This file stores the sampled parameters and the corresponding value returned from the solver for each replica. +This has the same format as ``trial.txt``. + +.. code-block:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ +The optimal value of the solver and the corresponding parameter among the all samples. + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + + +``result_T#.txt`` +^^^^^^^^^^^^^^^^^^^ +This file stores samples for each temperature ( ``#`` is replaced with the index of temperature ). +The first column is the index of the MC step. +The second column is the index of the walker. +The third column is the value of the solver. +The remaining columns are the coordinates. + +.. code-block:: + + # T = 1.0 + 0 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 1 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 2 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 3 15 28.98676409223712 3.7442621319489637 -3.868754990884034 + + +Algorithm +******************** + +Markov chain Monte Carlo +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Markov chain Monte Carlo (MCMC) sampling explores the parameter space by moving walkers :math:`\vec{x}` stochastically according to the weight function :math:`W(\vec{x})`. +For the weight function, the Boltzmann factor :math:`W(\vec{x}) = e^{-f(\vec{x})/T}` is generally adopted, where :math:`T>0` is the "temperature." +It is impossible in the many cases, unfortunately, to sample walkers according to :math:`W` directly. +Insteadly, the MCMC method moves walkers slightly and generates a time series :math:`\{\vec{x}_t\}` such that the distribution of the walkers obeys :math:`W` . +Let us call the transision probability from :math:`\vec{x}` to :math:`\vec{x}'` as :math:`p(\vec{x}' | \vec{x})`. +When :math:`p` is determined by the following condition ("the balance condition") + +.. math:: + + W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x}), + +the distribution of the generated time series :math:`\{\vec{x}_t\}` will converges to :math:`W(\vec{x})` [#mcmc_condition]_. +Practically, the stronger condition ("the detailed balance condition") + +.. math:: + + p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x}) + + +is usually imposed. +The detailed balance condition returns to the balance condition by taking the summation of :math:`\vec{x}`. + +2DMAT adopts the Metropolis-Hasting (MH) method for solving the detailed balance condition. +The MH method splits the transition process into the suggestion process and the acceptance process. + +1. Generate a candidate :math:`\vec{x}` with the suggestion probability :math:`P(\vec{x} | \vec{x}_t)`. + + - As :math:`P`, use a simple distribution such as the normal distribution with centered at x. + +2. Accept the candidate :math:`\vec{x}` with the acceptance probability :math:`Q(\vec{x} | \vec{x}_t)`. + + - If accepted, let :math:`\vec{x}_{t+1}` be `\vec{x}`. + - Otherwise, let :math:`\vec{x}_{t+1}` be `\vec{x}_t`. + +The whole transision probability is the product of these two ones, :math:`p(\vec{x} | \vec{x_t}) = P(\vec{x} | \vec{x}_t) Q(\vec{x} | \vec{x}_t)`. +The acceptance probability :math:`Q(\vec{x} | \vec{x}_t)` is defined as + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right]. + +It is easy to verify that the detailed balance condition is satisfied by substituting it into the detailed balance condition equation. + +When adopting the Boltzmann factor for the weight and a symmetry distribution +:math:`P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})` for the suggestion probability, +the acceptance probability :math:`Q` will be the following simple form: + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right]. + +By saying :math:`\Delta f = f(\vec{x}) - f(\vec{x}_t)` and using the fact :math:`Q=1` for :math:`\Delta f \le 0`, +the procedure of MCMC with the MH algorithm is the following: + +1. Choose a candidate from near the current position and calculate :math:`f` and :math:`\Delta f`. +2. If :math:`\Delta f \le 0`, that is, the walker is descending, accept it. +3. Otherwise, accept it with the probability :math:`Q=e^{-\Delta f/T}`. +4. Repeat 1-3. + +The solution is given as the point giving the minimum value of :math:`f(\vec{x})`. +The third process of the above procedure endures that walkers can climb over the hill with a height of :math:`\Delta f \sim T`, the MCMC sampling can escape from local minima. + +Replica exchange Monte Carlo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The "temperature" :math:`T` is one of the most important hyper parameters in the MCMC sampling. +The MCMC sampling can climb over the hill with a height of :math:`T` but cannot easily escape from the deeper valley than :math:`T`. +It is why we should increase the temperature in order to avoid stuck to local minima. +On the other hand, since walkers cannot see the smaller valleys than :math:`T`, the precision of the obtained result :math:`\min f(\vec{x})` becomes about :math:`T`, and it is necessary to decrease the temperature in order to achieve more precise result. +This dilemma leads us that we should tune the temperature carefully. + +One of the ways to overcome this problem is to update temperature too. +For example, simulated annealing decreases temperature as the iteration goes. +Another algorithm, simulated tempering, treats temperature as another parameter to be sampled, not a fixed hyper parameter, +and update temperature after some iterations according to the (detailed) balance condition. +Simulated tempering studies the details of a valley by cooling and escapes from a valley by heating. +Replica exchange Monte Carlo (RXMC), also known as parallel tempering, is a parallelized version of the simulated tempering. +In this algorithm, several copies of a system with different temperature, called as replicas, will be simulated in parallel. +Then, with some interval of steps, each replica exchanges temperature with another one according to the (detailed) balance condition. +As the simulated tempering does, RXMC can observe the details of a valley and escape from it by cooling and heating. +Moreover, because each temperature is assigned to just one replica, the temperature distribution will not be biased. +Using more replicas narrows the temperature interval, and increases the acceptance ratio of the temperature exchange. +This is why this algorithm suits for the massively parallel calculation. + +It is recommended that users perform ``minsearch`` optimization starting from the result of ``exchange``, because the RXMC result has uncertainty due to temperature. + +.. only:: html + + .. rubric:: footnote + +.. [#mcmc_condition] To be precisely, the non-periodicality and the ergodicity are necessary for convergence. diff --git a/manual/v2.2.0/en/_sources/algorithm/index.rst.txt b/manual/v2.2.0/en/_sources/algorithm/index.rst.txt new file mode 100644 index 00000000..6e7b8c3d --- /dev/null +++ b/manual/v2.2.0/en/_sources/algorithm/index.rst.txt @@ -0,0 +1,19 @@ +.. 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. + +Search algorithms +==================== + +``py2dmat`` searches the parameter space :math:`\mathbf{X}\ni x` by using the search algorithm ``Algorithm`` and the result of ``Solver`` :math:`f(x)`. +In this section, the search algorithms implemented in ``py2dmat`` are described. + +.. toctree:: + :maxdepth: 1 + + minsearch + mapper_mpi + exchange + pamc + bayes diff --git a/manual/v2.2.0/en/_sources/algorithm/mapper_mpi.rst.txt b/manual/v2.2.0/en/_sources/algorithm/mapper_mpi.rst.txt new file mode 100644 index 00000000..021f0b17 --- /dev/null +++ b/manual/v2.2.0/en/_sources/algorithm/mapper_mpi.rst.txt @@ -0,0 +1,102 @@ +Direct parallel search ``mapper`` +********************************** + +``mapper_mpi`` is an algorithm to search for the minimum value by computing :math:`f(x)` on all the candidate points in the parameter space prepared in advance. +In the case of MPI execution, the set of candidate points is divided into equal parts and automatically assigned to each process to perform trivial parallel computation. + +Preparation +~~~~~~~~~~~~ + +For MPI parallelism, you need to install `mpi4py `_.:: + + python3 -m pip install mpi4py + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _mapper_input_param: + +[``param``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section, the search parameter space is defined. + +If ``mesh_path`` is defined, it is read from a mesh file. +In the mesh file, one line defines one point in the parameter space, the first column is the data number, and the second and subsequent columns are the coordinates of each dimension. + +If ``mesh_path`` is not defined, ``min_list``, ``max_list``, and ``num_list`` are used to create an evenly spaced grid for each parameter. + +- ``mesh_path`` + + Format: String + + Description: Path to the mesh definition file. + +- ``min_list`` + + Format: List of float. The length should match the value of dimension. + + Description: The minimum value the parameter can take. + +- ``max_list`` + + Format: List of float.The length should match the value of dimension. + + Description: The maximum value the parameter can take. + +- ``num_list`` + + Format: List of integer. The length should match the value of dimension. + + Description: The number of grids the parametar can take at each dimension. + + +Refernce file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +A sample file for two dimensions is shown below. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +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. + +Below, output example is shown. + +.. code-block:: + + 6.000000 6.000000 0.047852 + 6.000000 5.750000 0.055011 + 6.000000 5.500000 0.053190 + 6.000000 5.250000 0.038905 + 6.000000 5.000000 0.047674 + 6.000000 4.750000 0.065919 + 6.000000 4.500000 0.053675 + 6.000000 4.250000 0.061261 + 6.000000 4.000000 0.069351 + 6.000000 3.750000 0.071868 + ... diff --git a/manual/v2.2.0/en/_sources/algorithm/minsearch.rst.txt b/manual/v2.2.0/en/_sources/algorithm/minsearch.rst.txt new file mode 100644 index 00000000..c002f84b --- /dev/null +++ b/manual/v2.2.0/en/_sources/algorithm/minsearch.rst.txt @@ -0,0 +1,138 @@ +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 `_ (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. + +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. + +In 2DMAT, the Scipy's function ``scipy.optimize.minimize(method="Nelder-Mead")`` is used. +For details, see `the official document `_ . + + +Preparation +~~~~~~~~~~~ + +You will need to install `scipy `_ .:: + + python3 -m pip install scipy + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It has subsections ``param`` and ``minimize``. + +.. _minsearch_input_param: + +[``param``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``initial_list`` + + Format: List of float. The length should match the value of dimension. + + Description: Initial value of the parameter. If not defined, it will be initialized uniformly and randomly. + +- ``unit_list`` + + 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. + + - ``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 Nelson-Mead method, + 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 Nelson-Mead method, + the solver is not evaluated and the value is considered infinite. + +[``minimize``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set the hyperparameters for the Nelder-Mead method. +See the documentation of `scipy.optimize.minimize`_ for details. + +- ``initial_scale_list`` + + 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. + 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. + +- ``xatol`` + + Format: Float (default: 1e-4) + + Description: Parameters used to determine convergence of the Nelder-Mead method. + +- ``fatol`` + + Format: Float (default: 1e-4) + + Description: Parameters used to determine convergence of the Nelder-Mead method. + +- ``maxiter`` + + Format: Integer (default: 10000) + + Description: Maximum number of iterations for the Nelder-Mead method. + +- ``maxfev`` + + Format: Integer (default: 100000) + + Description: Maximum number of times to evaluate the objective function. + + +Output files +~~~~~~~~~~~~~~~~~ + +``SimplexData.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Outputs information about the process of finding the minimum value. +The first line is a header, the second and subsequent lines are step, +the values of variables defined in ``string_list`` in the ``[solver]`` - ``[param]`` sections of the input file, +and finally the value of the function. + +The following is an example of the output. + +.. code-block:: + + #step z1 z2 z3 R-factor + 0 5.25 4.25 3.5 0.015199251773721183 + 1 5.25 4.25 3.5 0.015199251773721183 + 2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375 + 3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261 + 4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + 5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + +``res.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value of the final objective function and the value of the parameters at that time are described. +The objective function is listed first, followed by the values of the variables defined in ``string_list`` in the ``[solver]`` - ``[param]`` sections of the input file, in that order. + +The following is an example of the output. + +.. code-block:: + + fx = 7.382680568652868e-06 + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 diff --git a/manual/v2.2.0/en/_sources/algorithm/pamc.rst.txt b/manual/v2.2.0/en/_sources/algorithm/pamc.rst.txt new file mode 100644 index 00000000..41cc20d3 --- /dev/null +++ b/manual/v2.2.0/en/_sources/algorithm/pamc.rst.txt @@ -0,0 +1,476 @@ +Population Annealing Monte Carlo ``pamc`` +=============================================== + +``pamc`` explores the parameter space by using the Population Annealing Monte Carlo (PAMC) method. + +Preparation +~~~~~~~~~~~~~~~~ + +`mpi4py `_ should be installed for the MPI parallelization :: + + python3 -m pip install mpi4py + +Input parameters +~~~~~~~~~~~~~~~~~~~ + +This has two subsections ``algorithm.param`` and ``algorithm.pamc`` . + +[``algorithm.param``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This defines a space to be explored. +When ``mesh_path`` key is defined the discrete space is used. +Otherwise, continuous space is used. + +- Continuous space + + - ``initial_list`` + + Format: List of float. Length should be equal to ``dimension``. + + 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. + ``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. + + + - ``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. + +- Discrete space + + - ``mesh_path`` + + Format: string + + Description: Path to the mesh definition file. + + - ``neighborlist_path`` + + Format: string + + Description: Path to the neighborhood-list file. + +[``algorithm.pamc``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + Format: Integer + + Description: The number of Monte Carlo steps. + +- ``numsteps_annealing`` + + Format: Integer + + Description: The number of interval Monte Carlo steps between lowering "temperature". + +- ``numT`` + + Format: Integer + + Description: The number of "temperature" points. + +- ``Tmin`` + + Format: Float + + Description: The minimum value of the "temperature" (:math:`T`). + +- ``Tmax`` + + Format: Float + + Description: The maximum value of the "temperature" (:math:`T`). + +- ``bmin`` + + Format: Float + + Description: The minimum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``bmax`` + + Format: Float + + Description: The maximum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``Tlogspace`` + + Format: Boolean (default: true) + + Description: Whether to assign "temperature" to replicas equally spaced in the logarithmic space or not. + +- ``nreplica_per_proc`` + + Format: Integer (default: 1) + + Description: The number of replicas in a MPI process. + +- ``resampling_interval`` + + Format: Integer (default: 1) + + Description: The number of annealing processes between resampling of the replicas. + +- ``fix_num_replicas`` + + Format: Boolean (default: true) + + Description: Whether to fix the number of replicas or not on resampling. + + +About the number of steps +******************************** + +Specify just two of ``numstep``, ``numsteps_annealing``, and ``numT``. +The value of the remaining one will be determined automatically. + +Reference file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mesh definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this "algorithm". + +Below, a sample file is shown. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +Neighborhood-list file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define "neighborhoods" for each point :math:`i`, which are points that a walker can move from :math:`i` +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point :math:`i` is specified by the first column, +and the indices of final points :math:`j` are specified by the second and successive columns. + +An utility tool, ``py2dmat_neighborlist`` is available for generating a neighborhood-list file from a mesh file. For details, please see :doc:`../tool`. + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +Output files +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^ +This file stores the suggested parameters and the corresponding value returned from the solver for each temperature point (specified by ``#``). +The first column (``step``) is the index of the MC step. +The second column (``walker``) is the index of the walker in the process. +The third column (``beta``) is the inverse temperature of the replica. +The fourth column (``fx``) is the value of the solver. +The fifth - (4+dimension)-th columns are the coordinates. +The last two columns (``weight`` and ``ancestor``) are the Neal-Jarzynsky weight and the grand-ancestor of the replica. + +Example:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +This is a combination of all the ``trial_T#.txt`` in one. + +``RANK/result_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ +This file stores the sampled parameters and the corresponding value returned from the solver for each replica and each temperature. +This has the same format as ``trial.txt``. + +.. code-block:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +This is a combination of all the ``result_T#.txt`` in one. + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ +The optimal value of the solver and the corresponding parameter among the all samples. + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + + +``fx.txt`` +^^^^^^^^^^^^^^ + +This file stores statistical metrics over the all replicas for each temperature. +The first column is inverse temperature. +The second and third column are the expectation value and the standard error of the solver's output (:math:`f(x)`), respectively. +The fourth column is the number of replicas. +The fifth column is the logarithmic of the ratio between the normalization factors (partition functions) + +.. math:: + + \log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)}, + +where :math:`\beta_0` is the minimum value of :math:`\beta` used in the calculation. +The sixth column is the acceptance ratio of MC updates. + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804 + 0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058 + 0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004 + ... + + +Algorithm +~~~~~~~~~~ + +Goal +^^^^^ + +When the weight of the configuration :math:`x` under some parameter :math:`\beta_i` is given as :math:`f_i(x)` +(e.g., the Bolzmann factor :math:`f_i(x) = \exp[-\beta_i E(x)]` ), +the expectation value of :math:`A` is defined as + +.. math:: + + \langle A\rangle_i + = \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} + = \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) + = \int \mathrm{d}xA(x)\tilde{f}_i(x), + +where :math:`Z = \int \mathrm{d} x f_i(x)` is the normalization factor (partition function) +and :math:`\tilde{f}(x) = f(x)/Z` is the probability of :math:`x`. + +Our goal is to numerically calculate the expectation value for each :math:`\beta_i` and the (ratio of) the normalization factor. + +Annealed Importance Sampling (AIS) [1] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First, we introduce a series of configurations :math:`\{x_i\}` obeying the following joint probability + +.. math:: + + \tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0), + +with + +.. math:: + + \tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)}, + +where :math:`T_i(x, x')` is a transition probability from :math:`x` to :math:`x'` under :math:`\beta_i` +holding the balance condition, + +.. math:: + + + \int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x'). + +It turns out that :math:`\tilde{f}_n(x_n)` is the marginal distribution of :math:`\tilde{f}(x_0, x_1, \dots, x_n)`, that is, + +.. math:: + + + \tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n), + +from + +.. math:: + + \int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) + = \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) + = 1. + +Consequently, +:math:`\langle A \rangle_n` is represented by using the extended configuration :math:`\{x_i\}` as + +.. math:: + + + \begin{split} + \langle A \rangle_n + &\equiv + \int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n). + \end{split} + + +Unfortunately, it is difficult to generate directly a series of configurations :math:`\{x_i\}` +following the distribution :math:`\tilde{f}(x_0, x_1, \dots, x_n)`. +Then, instead of :math:`\tilde{f}(x_0, x_1, \dots, x_n)`, we consider :math:`\{x_i\}` obeying the joint distribution + +.. math:: + + \tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n), + + +by using the following the following scheme: + +1. Generete :math:`x_0` from the initial distribution :math:`\tilde{f}_0(x)` + +2. Generate :math:`x_{i+1}` from :math:`x_i` through :math:`T_{i+1}(x_i, x_{i+1})` + + +By using the reweighting method (or importance sampling method), +:math:`\langle A \rangle_n` is rewritten as + +.. math:: + + + \begin{split} + \langle A \rangle_n + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ + &= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + \end{split}. + +Because the ratio between :math:`\tilde{f}` and :math:`\tilde{g}` is + +.. math:: + + + \begin{split} + \frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \frac{f_n(x_n)}{f_0(x_0)} + \prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ + &\equiv + \frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n), + \end{split} + +the form of the expectation value will be + +.. math:: + + \langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + = \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n}. + + +Finally, the ratio between the normalization factors :math:`Z_n/Z_0` can be evaluated as + +.. math:: + + \frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n}, + +and therefore the expectation value of :math:`A` can be evaluated as a weighted arithmetic mean: + +.. math:: + + \langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}}. + +This weight :math:`w_n` is called as the Neal-Jarzynski weight. + +population annealing (PA) [2] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Although the AIS method can estimate the expectation values of :math:`A` for each parameter :math:`\beta` as the form of weighted arithmetic mean, +the variance of weights :math:`w` is generally large and then the accuracy of the result gets worse. +In order to overcome this problem, the population annealing Monte Carlo (PAMC) method resamples all the replicas according to the probability +:math:`p^{(k)} = w^{(k)} / \sum_k w^{(k)}` at some periods and resets all the weights to unity. + +The following pseudo code describes the scheme of PAMC: + +.. code-block:: python + + for k in range(K): + w[0, k] = 1.0 + x[0, k] = draw_from(β[0]) + for i in range(1, N): + for k in range(K): + w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) ) + if i % interval == 0: + x[i, :] = resample(x[i, :], w[i, :]) + w[i, :] = 1.0 + for k in range(K): + x[i, k] = transfer(x[i-1, k], β[i]) + a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:]) + +There are two resampling methods: one with a fixed number of replicas[2] and one without[3]. + +References +^^^^^^^^^^^^^ + +[1] R. M. Neal, Statistics and Computing **11**, 125-139 (2001). + +[2] K. Hukushima and Y. Iba, AIP Conf. Proc. **690**, 200 (2003). + +[3] J. Machta, PRE **82**, 026704 (2010). diff --git a/manual/v2.2.0/en/_sources/contact.rst.txt b/manual/v2.2.0/en/_sources/contact.rst.txt new file mode 100644 index 00000000..523847e1 --- /dev/null +++ b/manual/v2.2.0/en/_sources/contact.rst.txt @@ -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 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/manual/v2.2.0/en/_sources/customize/algorithm.rst.txt b/manual/v2.2.0/en/_sources/customize/algorithm.rst.txt new file mode 100644 index 00000000..acd90410 --- /dev/null +++ b/manual/v2.2.0/en/_sources/customize/algorithm.rst.txt @@ -0,0 +1,129 @@ +``Algorithm`` +====================== + +``Algorithm`` is defined as a subclass of ``py2dmat.algorithm.AlgorithmBase`` :: + + import py2dmat + + class Algorithm(py2dmat.algorithm.AlgorithmBase): + ... + +``AlgorithmBase`` +~~~~~~~~~~~~~~~~~~~ + +``AlgorithmBase`` class offers the following methods :: + +- ``__init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)`` + + - Reads the common parameters from ``info`` and sets the following instance variables: + + - ``self.mpicomm: Optional[MPI.Comm]`` : ``MPI.COMM_WORLD`` + + - When ``import mpi4py`` fails, this will be ``None``. + + - ``self.mpisize: int`` : the number of MPI processes + + - When ``import mpi4py`` fails, this will be ``1``. + + - ``self.mpirank: int`` : the rank of this process + + - When ``import mpi4py`` fails, this will be ``0``. + + - ``self.rng: np.random.Generator`` : pseudo random number generator + + - For details of the seed, please see :ref:`the [algorithm] section of the input parameter ` + + - ``self.dimension: int`` : the dimension of the parameter space + - ``self.label_list: List[str]`` : the name of each axes of the parameter space + - ``self.root_dir: pathlib.Path`` : root directory + + - ``info.base["root_dir"]`` + + - ``self.output_dir: pathlib.Path`` : output directory + + - ``info.base["root_dir"]`` + + - ``self.proc_dir: pathlib.Path`` : working directory of each process + + - ``self.output_dir / str(self.mpirank)`` + - Directory will be made automatically + - Each process performs an optimization algorithm in this directory + + - ``self.timer: dict[str, dict]`` : dictionary storing elapsed time + + - Three empty dictinaries, ``"prepare"``, ``"run"``, and ``"post"`` will be defined + +- ``prepare(self) -> None`` + + - Prepares the algorithm + - It should be called before ``self.run()`` is called + - It calls ``self._prepare()`` + +- ``run(self) -> None`` + + - Performs the algorithm + - Enters into ``self.proc_dir``, calls ``self._run()``, and returns to the original directory. + +- ``post(self) -> None`` + + - Runs a post process of the algorithm, for example, write the result into files + - It should be called after ``self.run()`` is called + - Enters into ``self.output_dir``, calls ``self._post()``, and returns to the original directory. + +- ``main(self) -> None`` + + - Calls ``prepare``, ``run``, and ``post`` + - Measures the elapsed times for calling each function, and write them into file + +- ``_read_param(self, info: py2dmat.Info) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]`` + + - Helper method for initializing defining the continuous parameter space + - Reads ``info.algorithm["param"]`` and returns the followings: + + - Initial value + - Lower bound + - Upper bound + - Unit + + - For details, see :ref:`[algorithm.param] subsection for minsearch ` + +- ``_meshgrid(self, info: py2dmat.Info, split: bool = False) -> Tuple[np.ndarray, np.ndarray]`` + + - Helper method for initializing defining the discrete parameter space + - Reads ``info.algorithm["param"]`` and returns the followings: + + - ``N`` points in the ``D`` dimensinal space as a ``NxD`` matrix + - IDs of points as a ``N`` dimensional vector + + - If ``split`` is ``True``, the set of points is scatterred to MPI processes + + - For details, see :ref:`[algorithm.param] subsection for mapper ` + +``Algorithm`` +~~~~~~~~~~~~~~~~ + +In ``Algorithm``, the following methods should be defined: + +- ``__init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)`` + + - Please transfer the arguments to the constructor of the base class: + + - ``super().__init__(info=info, runner=runner)`` + + - Reads ``info`` and sets information + +- ``_prepare(self) -> None`` + + - Pre process + +- ``_run(self) -> None`` + + - The algorithm itself + - In this method, you can calculate ``f(x)`` from a parameter ``x`` as the following:: + + message = py2dmat.Message(x, step, set) + fx = self.runner.submit(message) + +- ``_post(self) -> None`` + + - Post process diff --git a/manual/v2.2.0/en/_sources/customize/common.rst.txt b/manual/v2.2.0/en/_sources/customize/common.rst.txt new file mode 100644 index 00000000..0b1bae7e --- /dev/null +++ b/manual/v2.2.0/en/_sources/customize/common.rst.txt @@ -0,0 +1,90 @@ +Commons +========= + +``py2dmat.Info`` +~~~~~~~~~~~~~~~~~~ + +This class treats the input parameters. +This has the following four instance variables. + +- ``base : dict[str, Any]`` + + - Parameters for whole program such as the directory where the output will be written. + +- ``solver : dict[str, Any]`` + + - Parameters for ``Solver`` + +- ``algorithm : dict[str, Any]`` + + - Parameters for ``Algorithm`` + +- ``runner : dict[str, Any]`` + + - Parameters for ``Runner`` + + +An instance of ``Info`` is initialized by passing a ``dict`` which has the following four sub dictionaries, ``base``, ``solver``, ``algorithm``, and ``"runner"``. +Each value will be set to the corresponding field of ``Info``. + +- About ``base`` + + - Root directory ``root_dir`` + + - The default value is ``"."`` (the current directory). + - Value of ``root_dir`` will be converted to an absolute path. + - The leading ``~`` will be expanded to the user's home directory. + - Specifically, the following code is executed :: + + p = pathlib.Path(base.get("root_dir", ".")) + base["root_dir"] = p.expanduser().absolute() + + - Output directory ``output_dir`` + + - The default value is ``"."``, that is, the same to ``root_dir`` + - The leading ``~`` will be expanded to the user's home directory. + - If a relative path is given, its origin is ``root_dir``. + - Specifically, the following code is executed :: + + p = pathlib.Path(base.get("work_dir", ".")) + p = p.expanduser() + base["work_dir"] = base["root_dir"] / p + + +``py2dmat.Message`` +~~~~~~~~~~~~~~~~~~~~~~ + +When ``Algorithm`` tries to invoke ``Solver``, an instance of this class is passed from ``Algorithm`` to ``Solver`` via ``Runner``. + +This has the following three instance variables. + +- ``x: np.ndarray`` + + - Coordinates of a point :math:`x` to calculate :math:`f(x)` + +- ``step: int`` + + - The index of parameters + - For example, the index of steps in ``exchange`` and the ID of parameter in ``mapper``. + +- ``set: int`` + + - Which lap it is + - For example, ``min_search`` has two laps, the first one is optimization and the second one is recalculation the optimal values for each step. + +``py2dmat.Runner`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Runner`` connects ``Algorithm`` and ``Solver``. +The constructor of ``Runner`` takes ``solver: Solver``, ``info: Info``, and ``mapping: Callable[[np.ndarray], np.ndarray]``. + +``submit(self, message: py2dmat.Message) -> float`` method invokes the solver and returns the result. +To evaluate ``fx = f(x)``, use the following code snippet:: + + message = py2dmat.Message(x, step, set) + fx = runner.submit(message) + +``submit`` internally uses ``mapping`` for generating a parameter used in ``Solver``, :math:`y`, from a parameter searched by ``Algorithm``, :math:`x`, as ``y = mapping(x)``. +When ``mapping`` is omitted in the constructor (or ``None`` is passed), an affine mapping (``py2dmat.util.mapping.Affine(A,b)``) :math:`y=Ax+b` is used as ``mapping``. +The elements of ``A`` and ``b`` are defined in ``info``. +See :doc:`../input` for details how/which components of ``info`` ``Runner`` uses. diff --git a/manual/v2.2.0/en/_sources/customize/index.rst.txt b/manual/v2.2.0/en/_sources/customize/index.rst.txt new file mode 100644 index 00000000..11cb7dc0 --- /dev/null +++ b/manual/v2.2.0/en/_sources/customize/index.rst.txt @@ -0,0 +1,19 @@ +.. 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. + +(For developers) User-defined algorithm and solver +==================================================== + +``py2dmat`` solves the reverse problem by combination of ``Solver`` for the direct problem and ``Algorithm`` for the optimization problem. +Instead of some ``Solver`` and ``Algorithm`` which are served by ``py2dmat``, users can define and use their own components. +In this chapter, how to define ``Solver`` and ``Algorithm`` and to use them will be described. + +.. toctree:: + :maxdepth: 1 + + common + solver + algorithm + usage diff --git a/manual/v2.2.0/en/_sources/customize/solver.rst.txt b/manual/v2.2.0/en/_sources/customize/solver.rst.txt new file mode 100644 index 00000000..40fc46db --- /dev/null +++ b/manual/v2.2.0/en/_sources/customize/solver.rst.txt @@ -0,0 +1,58 @@ +``Solver`` +========================= + +``Solver`` is defined as a subclass of ``py2dmat.solver.SolverBase`` :: + + import py2dmat + + class Solver(py2dmat.solver.SolverBase): + ... + +The following methods should be defined. + +- ``__init__(self, info: py2dmat.Info)`` + + - It is required to call the constructor of the base class. + + - ``super().__init__(info)`` + + - The constructor of ``SolverBase`` defines the following instance variables. + + - ``self.root_dir: pathlib.Path`` : Root directory + + - use ``info.base["root_dir"]`` + + - ``self.output_dir: pathlib.Path`` : Output directory + + - use ``info.base["output_dir"]`` + + - ``self.proc_dir: pathlib.Path`` : Working directory for each MPI process + + - as ``self.output_dir / str(mpirank)`` + + - ``self.work_dir: pathlib.Path`` : Directory where the solver is invoked + + - same to ``self.proc_dir`` + + - Read the input parameter ``info`` and save as instance variables. + +- ``prepare(self, message: py2dmat.Message) -> None`` + + - This is called before the solver starts + - ``message`` includes an input parameter ``x``, convert it to something to be used by the solver + + - e.g., to generate an input file of the solver + +- ``run(self, nprocs: int = 1, nthreads: int = 1) -> None`` + + - Run the solver + - Result should be saved to somewhere in order to be read by ``get_results`` later + + - e.g., save f(x) as an instance variable + +- ``get_results(self) -> float`` + + - This is called after the solver finishes + - Returns the result of the solver + + - e.g., to retrieve the result from the output file of the solver diff --git a/manual/v2.2.0/en/_sources/customize/usage.rst.txt b/manual/v2.2.0/en/_sources/customize/usage.rst.txt new file mode 100644 index 00000000..2f11156c --- /dev/null +++ b/manual/v2.2.0/en/_sources/customize/usage.rst.txt @@ -0,0 +1,51 @@ +Usage +=========== + +The following flow solves the optimization problem. +The number of flow corresponds the comment in the program example. + +1. Define your ``Algorithm`` and/or ``Solver`` + + - Of course, classes that ``py2dmat`` defines are available + +2. Prepare the input parameter, ``info: py2dmat.Info`` + + - Make a dictionary as your favorite way + + - The below example uses a TOML formatted input file for generating a dictionary + +3. Instantiate ``solver: Solver``, ``runner: py2dmat.Runner``, and ``algorithm: Algorithm`` + +4. Invoke ``algorithm.main()`` + + +Example + +.. code-block:: python + + import sys + import tomli + import py2dmat + + # (1) + class Solver(py2dmat.solver.SolverBase): + # Define your solver + ... + + class Algorithm(py2dmat.algorithm.AlgorithmBase): + # Define your algorithm + ... + + + # (2) + with open(sys.argv[1]) as f: + inp = tomli.load(f) + info = py2dmat.Info(inp) + + # (3) + solver = Solver(info) + runner = py2dmat.Runner(solver, info) + algorithm = Algorithm(info, runner) + + # (4) + algorithm.main() diff --git a/manual/v2.2.0/en/_sources/index.rst.txt b/manual/v2.2.0/en/_sources/index.rst.txt new file mode 100644 index 00000000..d0758145 --- /dev/null +++ b/manual/v2.2.0/en/_sources/index.rst.txt @@ -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 + start + tutorial/index + input + output + algorithm/index + solver/index + tool + customize/index + acknowledgement + contact diff --git a/manual/v2.2.0/en/_sources/input.rst.txt b/manual/v2.2.0/en/_sources/input.rst.txt new file mode 100644 index 00000000..f28d61e9 --- /dev/null +++ b/manual/v2.2.0/en/_sources/input.rst.txt @@ -0,0 +1,238 @@ +Input file +=========================== + +As the input file format, `TOML `_ format is used. +The input file consists of the following six sections. + +- ``base`` + + - Specify the basic parameters about ``py2dmat`` . + +- ``solver`` + + - Specify the parameters about ``Solver`` . + +- ``algorithm`` + + - Specify the parameters about ``Algorithm`` . + +- ``runner`` + + - Specify the parameters about ``Runner`` . + +- ``mapping`` + + - Define the mapping from a parameter searched by ``Algorithm`` . + +- ``limitation`` + + - Define the limitation (constration) of parameter searched by ``Algorithm`` . + +- ``log`` + + - Specify parameters related to logging of solver calls. + +[``base``] section +************************ + +- ``dimension`` + + Format: Integer + + Description: Dimension of the search space (number of parameters to search) + +- ``root_dir`` + + Format: string (default: The directory where the program was executed) + + Description: Name of the root directory. The origin of the relative paths to input files. + +- ``output_dir`` + + Format: string (default: The directory where the program was executed) + + Description: Name of the directory to output the results. + +[``solver``] section +************************ + +The ``name`` determines the type of solver. Each parameter is defined for each solver. + + +- ``name`` + + Format: String + + Description: Name of the solver. The following solvers are available. + + - ``sim-trhepd-rheed`` : Solver to calculate Total-reflection high energy positron diffraction (TRHEPD) or Reflection High Energy Electron Diffraction (RHEED) intensities. + + - ``analytical`` : Solver to provide analytical solutions (mainly used for testing). + +See :doc:`solver/index` for details of the various solvers and their input/output files. + +.. _input_parameter_algorithm: + +[``algorithm``] section +******************************* + +The ``name`` determines the type of algorithm. Each parameter is defined for each algorithm. + +- ``name`` + + Format: String + + Description: Algorithm name. The following algorithms are available. + + - ``minsearch`` : Minimum value search using Nelder-Mead method + + - ``mapper`` : Grid search + + - ``exchange`` : Replica Exchange Monte Carlo + + - ``bayes`` : Bayesian optimization + +- ``seed`` + + Format: Integer + + Description: A parameter to specify seeds of the pseudo-random number generator used for random generation of initial values, Monte Carlo updates, etc. + For each MPI process, the value of ``seed + mpi_rank * seed_delta`` is given as seeds. + If omitted, the initialization is done by `the Numpy's prescribed method `_. + + +- ``seed_delta`` + + Format: Integer (default: 314159) + + Description: A parameter to calculate the seed of the pseudo-random number generator for each MPI process. + For details, see the description of ``seed``. + +See :doc:`algorithm/index` for details of the various algorithms and their input/output files. + +[``runner``] section +************************ + +This section sets the configuration of ``Runner``, which bridges ``Algorithm`` and ``Solver``. +It has two subsections, ``mapping`` and ``log`` . + +[``mapping``] section +************************ + +This section defines the mapping from an :math:`N` dimensional parameter searched by ``Algorithm``, :math:`x`, to an :math:`M` dimensional parameter used in ``Solver``, :math:`y` . +In the case of :math:`N \ne M`, the parameter ``dimension`` in ``[solver]`` section should be specified. + +In the current version, the affine mapping (linear mapping + translation) :math:`y = Ax+b` is available. + +- ``A`` + + Format: List of list of float, or a string (default: ``[]``) + + Description: :math:`N \times M` matrix :math:`A`. An empty list ``[]`` is a shorthand of an identity matrix. + If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example). + + +- ``b`` + + Format: List of float, or a string (default: ``[]``) + + Description: :math:`M` dimensional vector :math:`b`. An empty list ``[]`` is a shorthand of a zero vector. + If you want to set it by a string, arrange the elements of the vector separated with spaces. + +For example, both :: + + A = [[1,1], [0,1]] + +and :: + + A = """ + 1 1 + 0 1 + """ + +mean + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right). + + +[``limitation``] section +************************* + +This section defines the limitation (constraint) in an :math:`N` dimensional parameter searched by ``Algorithm``, :math:`x`, in addition of ``min_list`` and ``max_list``. + +In the current version, a linear inequation with the form :math:`Ax+b>0` is available. + +- ``co_a`` + + Format: List of list of float, or a string (default: ``[]``) + + Description: :math:`N \times M` matrix :math:`A`. An empty list ``[]`` is a shorthand of an identity matrix. + If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example). + + +- ``co_b`` + + Format: List of float, or a string (default: ``[]``) + + Description: :math:`M` dimensional vector :math:`b`. An empty list ``[]`` is a shorthand of a zero vector. + If you want to set it by a string, arrange the elements of the vector separated with spaces. + +For example, both :: + + A = [[1,1], [0,1]] + +and :: + + A = """ + 1 1 + 0 1 + """ + +mean + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right). + + +[``log``] section +************************ + +Setting parametrs related to logging of solver calls. + +- ``filename`` + + Format: String (default: "runner.log") + + Description: Name of log file. + +- ``interval`` + + Format: Integer (default: 0) + + Description: The log will be written out every time solver is called ``interval`` times. + If the value is less than or equal to 0, no log will be written. + +- ``write_result`` + + Format: Boolean (default: false) + + Description: Whether to record the output from solver. + +- ``write_input`` + + Format: Boolean (default: false) + + Description: Whether to record the input to solver. diff --git a/manual/v2.2.0/en/_sources/introduction.rst.txt b/manual/v2.2.0/en/_sources/introduction.rst.txt new file mode 100644 index 00000000..5b73a75d --- /dev/null +++ b/manual/v2.2.0/en/_sources/introduction.rst.txt @@ -0,0 +1,85 @@ +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) experiment[1, 2], sxrd[3], and leed[4]. +As algorithms, it offers the Nelder-Mead method[5], the grid search method[6], the Bayesian optimization method[7], the replica exchange Monte Carlo method[8], and the population annealing Monte Carlo method[9-11]. +In the future, we plan to add other direct problem solvers and search algorithms in 2DMAT. + +[1] As a review, see `Y. Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019) `_. + +[2] `T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022). `_ + +[3] W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252 (2006) 5259. + +[4] `M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). `_ + +[5] `K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020) `_. + +[6] `K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series, `_. + +[7] `Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022) `_ + +[8] `K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996) `_, `R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986) `_. + +[9] `R. M. Neal, Statistics and Computing 11, 125-139 (2001). `_ + +[10] `K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003). `_ + +[11] `J. Machta, Phys. Rev. E 82, 026704 (2010). `_ + +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 +---------------------- + +- 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. + +- 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/manual/v2.2.0/en/_sources/output.rst.txt b/manual/v2.2.0/en/_sources/output.rst.txt new file mode 100644 index 00000000..0fcd4382 --- /dev/null +++ b/manual/v2.2.0/en/_sources/output.rst.txt @@ -0,0 +1,53 @@ +Output files +===================== + +See :doc:`solver/index` and :doc:`algorithm/index` for the output files of each ``Solver`` and ``Algorithm``. + +Common file +~~~~~~~~~~~~~~~~~~ + +``time.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The total time taken for the calculation for each MPI rank is outputted. +These files will be output under the subfolders of each rank respectively. +The time taken to pre-process the calculation, the time taken to compute, and the time taken to post-process the calculation are listed in the ``prepare`` , ``run`` , and ``post`` sections. + +The following is an example of the output. + +.. code-block:: + + #prepare + total = 0.007259890999989693 + #run + total = 1.3493346729999303 + - file_CM = 0.0009563499997966574 + - submit = 1.3224223930001244 + #post + total = 0.000595873999941432 + + +``runner.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The log information about solver calls for each MPI rank is outputted. +These files will be output under the subfolder of each rank. +The output is only available when the ``runner.log.interval`` parameter is a positive integer in the input. + +- The first column is the serial number of the solver call. +- The second column is the time elapsed since the last solver call. +- The third column is the time elapsed since the start of the calculation. + +The following is an example of the output. + +.. code-block:: + + # $1: num_calls + # $2: elapsed_time_from_last_call + # $3: elapsed_time_from_start + + 1 0.0010826379999999691 0.0010826379999999691 + 2 6.96760000000185e-05 0.0011523139999999876 + 3 9.67080000000009e-05 0.0012490219999999885 + 4 0.00011765699999999324 0.0013666789999999818 + 5 4.965899999997969e-05 0.0014163379999999615 + 6 8.666900000003919e-05 0.0015030070000000006 + ... diff --git a/manual/v2.2.0/en/_sources/solver/analytical.rst.txt b/manual/v2.2.0/en/_sources/solver/analytical.rst.txt new file mode 100644 index 00000000..1ab84fdc --- /dev/null +++ b/manual/v2.2.0/en/_sources/solver/analytical.rst.txt @@ -0,0 +1,55 @@ +``analytical`` solver +************************ + +``analytical`` is a ``Solver`` that computes a predefined benchmark function :math:`f(x)` for evaluating the performance of search algorithms. + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``funtion_name`` parameter in the ``solver`` section specifies the function to use. + +- ``function_name`` + + Format: string + + Description: Function name. The following functions are available. + + - ``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/manual/v2.2.0/en/_sources/solver/index.rst.txt b/manual/v2.2.0/en/_sources/solver/index.rst.txt new file mode 100644 index 00000000..e3b964bf --- /dev/null +++ b/manual/v2.2.0/en/_sources/solver/index.rst.txt @@ -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. + +Direct Problem Solver +====================== + +Direct problem solver ``Solver`` calculates the function to be optimized :math:`f(x)` at the search parameter :math:`x`. + +.. toctree:: + :maxdepth: 1 + + analytical + sim-trhepd-rheed + sxrd + leed diff --git a/manual/v2.2.0/en/_sources/solver/leed.rst.txt b/manual/v2.2.0/en/_sources/solver/leed.rst.txt new file mode 100644 index 00000000..a428fc4b --- /dev/null +++ b/manual/v2.2.0/en/_sources/solver/leed.rst.txt @@ -0,0 +1,95 @@ +``leed`` solver +*********************************************** + +``leed`` is a ``Solver`` made by M.A. Van Hove, which calculates the Rocking curve from atomic positions etc., using ``SATLEED``, and returns the error from the experimental Rocking curve as :math:`f(x)`. +For more information on ``SATLEED``, see [SATLEED]_. + +.. [SATLEED] M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). https://doi.org/10.1016/0167-5729(93)90011-D + +Preparation +~~~~~~~~~~~~ +First, install ``SATLEED`` . +Access to the following URL +http://www.icts.hkbu.edu.hk/VanHove_files/leed/leedsatl.zip +and download a zip file. +Depending on the details of the system you want to calculate, it is necessary to change the parameters in the source code for ``SATLEED``. +After changing parameters, compile programs to generate the executable files such as ``stal1.exe``, ``satl2.exe`` . + +For trying the example at ``sample/py2dmat/leed``, a utility script file ``setup.sh`` for downloading ``SATLEED``, rewriting source codes, and compiling the program is available.:: + + $ cd sample/py2dmat/leed + $ sh ./setup.sh + +After running ``setup.sh``, executable files ``satl1.exe`` and ``satl2.exe`` are generated in ``leedsatl`` directory. + +Note that it is assumed that you have already executed ``satl1.exe`` before using ``py2dmat`` . +Therefore, the following files must be generated. + +- Input files of ``satl1.exe`` : ``exp.d``, ``rfac.d``, ``tleed4.i``, ``tleed5.i`` + +- Output files of ``satl1.exe`` : ``tleed.o`` , ``short.t`` + +``py2dmat`` will run ``satl2.exe`` based on the above files. + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Input parameters are specified in subsections in the ``solver`` section (``config`` and ``reference``). + +[``config``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``path_to_solver`` + + Format: string + + Description: Path to the solver ``satl2.exe`` . + + +[``reference``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``path_to_base_dir`` + + Format: string + + Description: Path to the directory which stores ``exp.d``, ``rfac.d``, ``tleed4.i``, ``tleed5.i`` , ``tleed.o`` , ``short.t`` . + + +Reference file for Solver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Target reference file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The file containing the data to be targeted to fit. Edit ``tleed4.i`` in ``path_to_base_dir`` in the [``reference``] section. +Add the number you want to optimize to ``optxxx`` (where xxx is a three-digit number in the format 000, 001, 002, ...). (where xxx is a three-digit integer in the form 000, 001, 002, ...). +Note that the number of xxx must match the order and number of variables in the list of ``py2dmat`` variables to be optimized. +Note that if IFLAG and LSFLAG are not set to 0, the satleed side is also optimized. + +An example file is shown below. + +.. code-block:: + + 1 0 0 IPR ISTART LRFLAG + 1 10 0.02 0.2 NSYM NSYMS ASTEP VSTEP + 5 1 2 2 NT0 NSET LSMAX LLCUT + 5 NINSET + 1.0000 0.0000 1 PQEX + 1.0000 2.0000 2 PQEX + 1.0000 1.0000 3 PQEX + 2.0000 2.0000 4 PQEX + 2.0000 0.0000 5 PQEX + 3 NDIM + opt000 0.0000 0.0000 0 DISP(1,j) j=1,3 + 0.0000 opt001 0.0000 0 DISP(2,j) j=1,3 + 0.0000 0.0000 0.0000 1 DISP(3,j) j=1,3 + 0.0000 0.0000 0.0000 0 DISP(4,j) j=1,3 + 0.0000 0 DVOPT LSFLAG + 3 0 0 MFLAG NGRID NIV + ... + +Output file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ``leed``, the output files are stored in the folder with the rank number. diff --git a/manual/v2.2.0/en/_sources/solver/sim-trhepd-rheed.rst.txt b/manual/v2.2.0/en/_sources/solver/sim-trhepd-rheed.rst.txt new file mode 100644 index 00000000..7fed33c9 --- /dev/null +++ b/manual/v2.2.0/en/_sources/solver/sim-trhepd-rheed.rst.txt @@ -0,0 +1,328 @@ +``sim-trhepd-rheed`` solver +*********************************************** + +.. _sim-trhepd-rheed: https://github.com/sim-trhepd-rheed/sim-trhepd-rheed + +``sim-trhepd-rheed`` is a ``Solver`` that uses sim-trhepd-rheed_ to calculate the diffraction rocking curve from the atomic position :math:`x` and returns the deviation from the experimental rocking curve as :math:`f(x)`. + +Preparation +~~~~~~~~~~~~ + +You will need to install sim-trhepd-rheed_ beforehand. + +1. Download the source code from the official ``sim-trhepd-rheed`` website. +2. Move to ``sim-trhepd-rheed/src`` folder and make ``bulk.exe`` and ``surf.exe`` by using ``make``. + +Before running ``py2dmat``, run ``bulk.exe`` to create the bulk data. +The ``surf.exe`` is called from ``py2dmat``. + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Input parameters can be specified in subsections ``config``, ``post``, ``param``, ``reference`` in ``solver`` section. + +[``solver``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- ``generate_rocking_curve`` + + Format: boolean (default: false) + + Description: Whether to generate ``RockingCurve_calculated.txt``. + If ``true``, ``RockingCurve_calculated.txt`` will be generated in the working directory ``Log%%%_###``. + Note that if ``remove_work_dir`` (in [``post``] subsection) is ``true``, ``Log%%%_###`` will be removed. + +[``solver.config``] subsection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``surface_exec_file`` + + Format: string (default: "surf.exe") + + Description: Path to ``sim-trhepd-rheed`` surface reflection solver ``surf.exe``. + +- ``surface_input_file`` + + Format: string (default: "surf.txt") + + Description: Input file for surface structure. + +- ``bulk_output_file`` + + Format: string (default: "bulkP.b") + + Description: Output file for bulk structure. + +- ``surface_output_file`` + + Format: string (default: "surf-bulkP.s") + + Description: Output file for surface structure. + +- ``calculated_first_line`` + + Format: integer (default: 5) + + Description: In the output file, the first line to be read as D(x). + The last line is automatically calculated from the number of the reference data. + +- ``calculated_info_line`` + + Format: integer (default: 2) + + Description: In the output file, the line contains the information of the calculated data -- the number of glancing angles (second column) and the number of beams (third column). + +- ``cal_number`` + + Format: Integer or List of integers + + Description: In the output file, the columns to be read as D(x). Multiple columns can be specified (many-beam condition). + + +[``solver.post``] subsection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This subsection is used to the postprocess -- to specify how to calculate the objective function, that is, the deviation between the experimental and computational data, and to draw the rocking curve. + +- ``Rfactor_type`` + + Format: string ("A" or "B", default: "A") + + Description: This parameter specifies how to calculate the R-factor to be minimized. + Let :math:`n` be the number of dataset, :math:`m` be the number of glancing angles, and :math:`v^{(n)} = (v^{(n)}_{1}, v^{(n)}_{2}, \dots ,v^{(n)}_{m})` be the calculated data. + With the weights of the beams, :math:`w^{(j)}`, R-factors is defined as follows: + + - "A" type: + + .. math:: + + R = \sqrt{ \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2} } + + - "A2" type: + + .. math:: + + R^{2} = \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2} + + - "B" type: + + .. math:: + + R = \frac{\sum_{i}^{m} \left(u^{(1)}_{i}-v^{(1)}_{i}\right)^{2}}{\sum_{i}^{m} \left(u^{(1)}_{i}\right)^{2} + \sum_{i}^{m} (v^{(1)}_{i})^2} + + - "B" type is available only for the single dataset (:math:`n=1`). + + +- ``normalization`` + + Format: string ("TOTAL" or "MANY_BEAM") + + Description: This parameter specifies how to normalize the experimental and computational data vectors. + + - "TOTAL" + + - To normalize the data as the summation is 1. + - The number of dataset should be one (the number of ``cal_number`` should be one). + + - "MANY_BEAM" + + - To normalize with weights as specified by ``weight_type``. + + **NOTE: "MAX" is no longer available** + +- ``weight_type`` + + Format: string or ``None``. "calc" or "manual" (default: ``None``) + + Description: The weights of the datasets for the "MANY_BEAM" normalization. + + - "calc" + + .. math:: + + w^{(n)} = \left(\frac{\sum_i^m v^{(n)}_{i}}{\sum_j^n \sum_i^m v^{(j)}_i} \right)^2 + + - "manual" + + :math:`w^{(n)}` is specified by ``spot_weight``. + +- ``spot_weight`` + + Format: list of float (mandatory when ``weight_type`` is "manual") + + Description: The weights of the beams in the calculation of R-factor. + The weights are automatically normalized as the sum be 1. + For example, [3,2,1] means :math:`w^{(1)}=1/2, w^{(2)}=1/3, w^{(3)}=1/6`. + +- ``omega`` + + Format: float (default: 0.5) + + Description: This parameter specifies the half-width of convolution. + +- ``remove_work_dir`` + + Format: boolean (default: false) + + Description: Whether to remove working directories ``Log%%%_###`` after reading R-factor or not + +[``solver.param``] subsection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``string_list`` + + Format: list of string. The length should match the value of dimension (default: ["value_01", "value_02"]). + + Description: List of placeholders to be used in the reference template file to create the input file for the solver. These strings will be replaced with the values of the parameters being searched for. + + +[``solver.reference``] subsection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``path`` + + Format: string (default: ``experiment.txt``) + + Description: Path to the reference data file. + +- ``reference_first_line`` + + Format: integer + + Description: In the reference data file, the first line to be read as Dexp. The default value is 1, that is, the first line of the file. + +- ``reference_last_line`` + + Format: integer + + Description: In the reference data file, the last line to be read as Dexp. If omitted, all lines from the first line to the end of the file will be read. + +- ``exp_number`` + + Format: Integer or List of integers + + Description: In the reference data file, the column numbers to be read. Multiple columns can be specified (many-beam condition). + + +Reference file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Input template file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The input template file ``template.txt`` is a template for creating an input file for ``surf.exe``. +The parameters to be moved in ``py2dmat`` (such as the atomic coordinates you want to find) should be replaced with the appropriate string, such as ``value_*``. +The strings to be used are specified by ``string_list`` in the ``[solver]`` - ``[param]`` section of the input file for the solver. +An example template is shown below. + +.. code-block:: + + 2 ,NELMS, -------- Ge(001)-c4x2 + 32,1.0,0.1 ,Ge Z,da1,sap + 0.6,0.6,0.6 ,BH(I),BK(I),BZ(I) + 32,1.0,0.1 ,Ge Z,da1,sap + 0.4,0.4,0.4 ,BH(I),BK(I),BZ(I) + 9,4,0,0,2, 2.0,-0.5,0.5 ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS + 8 ,NATM + 1, 1.0, 1.34502591 1 value_01 ,IELM(I),ocr(I),X(I),Y(I),Z(I) + 1, 1.0, 0.752457792 1 value_02 + 2, 1.0, 1.480003343 1.465005851 value_03 + 2, 1.0, 2 1.497500418 2.281675 + 2, 1.0, 1 1.5 1.991675 + 2, 1.0, 0 1 0.847225 + 2, 1.0, 2 1 0.807225 + 2, 1.0, 1.009998328 1 0.597225 + 1,1 ,(WDOM,I=1,NDOM) + +In this case, ``value_01``, ``value_02``, and ``value_03`` are the parameters to be moved in ``py2dmat``. + + +Target file +^^^^^^^^^^^^^^ +This file (``experiment.txt``) contains the data to be targeted. +The first column contains the angle, and the second and following columns contain the calculated value of the reflection intensity multiplied by the weight. +An example of the file is shown below. + +.. code-block:: + + 3.00000e-01 8.17149e-03 1.03057e-05 8.88164e-15 ... + 4.00000e-01 1.13871e-02 4.01611e-05 2.23952e-13 ... + 5.00000e-01 1.44044e-02 1.29668e-04 4.53633e-12 ... + 6.00000e-01 1.68659e-02 3.49471e-04 7.38656e-11 ... + 7.00000e-01 1.85375e-02 7.93037e-04 9.67719e-10 ... + 8.00000e-01 1.93113e-02 1.52987e-03 1.02117e-08 ... + 9.00000e-01 1.92590e-02 2.53448e-03 8.69136e-08 ... + 1.00000e+00 1.86780e-02 3.64176e-03 5.97661e-07 ... + 1.10000e+00 1.80255e-02 4.57932e-03 3.32760e-06 ... + 1.20000e+00 1.77339e-02 5.07634e-03 1.50410e-05 ... + 1.30000e+00 1.80264e-02 4.99008e-03 5.53791e-05 ... + ... + + +Output file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +For ``sim-trhepd-rheed``, the files output by ``surf.exe`` will be output in the ``Log%%%%%_#####`` folder under the folder with the rank number. +``%%%%%`` means an index of iteration in ``Algorithm`` (e.g., steps in Monte Carlo), +and ``#####`` means an index of group (e.g., replica index in Monte Carlo). +In large calculation, the number of these folders becomes too large to be written in the storage of the system. +For such a case, let ``solver.post.remove_work_dir`` parameter be ``true`` in order to remove these folders. +This section describes the own files that are output by this solver. + +``stdout`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +It contains the standard output of ``surf.exe``. +An example is shown below. + +.. code-block:: + + bulk-filename (end=e) ? : + bulkP.b + structure-filename (end=e) ? : + surf.txt + output-filename : + surf-bulkP.s + +``RockingCurve_calculated.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This file is located in the ``Log%%%%%_#####`` folder. +At the beginning of the file, the lines beginning with ``#`` are headers. +The header contains the values of the input variables, the objective function value ``f(x)``, the parameters ``Rfactor_type``, ``normalization``, ``weight_type``, ``cal_number``, ``spot_weight``, and what is marked in the data portion columns (e.g. ``# #0 glancing_angle``). + +The header is followed by the data. +The first column shows the glancing angle, and the second and subsequent columns show the intensity of each data column. +You can see which data columns are marked in the header. For example, + +.. code-block:: + + # #0 glancing_angle + # #1 cal_number=1 + # #2 cal_number=2 + # #3 cal_number=4 + +shows that the first column is the glancing angle, and the second, third, and fourth columns are the calculated data corresponding to the first, second, and fourth columns of the calculated data file, respectively. + +Intencities in each column are normalized so that the sum of the intensity is 1. +To calculate the objective function value (R-factor and R-factor squared), the data columns are weighted by ``spot_weight`` and normalized by ``normalization``. + +.. code-block:: + + #value_01 = 0.00000 value_02 = 0.00000 + #Rfactor_type = A + #normalization = MANY_BEAM + #weight_type = manual + #fx(x) = 0.03686180462340505 + #cal_number = [1, 2, 4, 6, 8] + #spot_weight = [0.933 0.026 0.036 0.003 0.002] + #NOTICE : Intensities are NOT multiplied by spot_weight. + #The intensity I_(spot) for each spot is normalized as in the following equation. + #sum( I_(spot) ) = 1 + # + # #0 glancing_angle + # #1 cal_number=1 + # #2 cal_number=2 + # #3 cal_number=4 + # #4 cal_number=6 + # #5 cal_number=8 + 0.30000 1.278160358686800e-02 1.378767858296659e-04 8.396046839668212e-14 1.342648818357391e-30 6.697979700048016e-53 + 0.40000 1.778953628930054e-02 5.281839702773564e-04 2.108814173486245e-12 2.467220122612354e-28 7.252675318478533e-50 + 0.50000 2.247181148723425e-02 1.671115124520428e-03 4.250758278908295e-11 3.632860054842994e-26 6.291667506376419e-47 + ... + diff --git a/manual/v2.2.0/en/_sources/solver/sxrd.rst.txt b/manual/v2.2.0/en/_sources/solver/sxrd.rst.txt new file mode 100644 index 00000000..881fe1ef --- /dev/null +++ b/manual/v2.2.0/en/_sources/solver/sxrd.rst.txt @@ -0,0 +1,263 @@ +``sxrd`` solver +*********************************************** + +``sxrd`` is a ``Solver`` that uses ``sxrdcalc`` to calculate the Rocking curve by giving atomic positions :math:`x` , atomic occupancies, and Debye-Waller factor and finally returnes the error :math:`f(x)` from the experimental Rocking curve. + +Preparation +~~~~~~~~~~~~ + +The ``sxrdcalc`` is called from ``py2dmat``. +You will need to install ``sxrdcalc`` beforehand. +``sxrdcalc`` is available on GitHub at the following URL: + +https://github.com/sxrdcalc/sxrdcalc + +Access the site and download the source code from "Code" - "Download zip". +After unzipping the zip file, edit the Makefile to fit your computing environment, and then type ``make`` to create the ``sxrdcalc`` executable. + +It is noted that the bulk data must be prepared in advance before running ``py2dmat`` (see the auxiliary file for solvers below for the format). + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Input parameters are specified in subsections in the ``solver`` section (``config``, ``post``, ``param``, and ``reference``). + +[``config``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``sxrd_exec_file`` + + Format: string + + Description: Path to the solver ``sxrdcalc``. + +- ``bulk_struc_in_file`` + + Format: string + + Description: Input file name of the bulk structure. + + An example of the input input is given as follows: + +.. code-block:: + + [config] + sxrd_exec_file = "../../sxrdcalc" + bulk_struc_in_file = "sic111-r3xr3.blk" + +[``param``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``scale_factor`` + + Format: float (default: 1.0) + + Description: The value of the target Rocking Curve and the scale of the Rocking Curve obtained from the simulation. + +- ``opt_scale_factor`` + + Format: bool (default: false) + + Description: Flag whether ``scale_factor`` should be optimized or not. + +- ``type_vector`` + + Format: list + + Description: A list of positive numbers which specifies the type of variables to be optimized. + This list corresponds to the types specified in the [``param.atom``] subsection. + If the type is the same, they are treated as the same variable. + +[``param.domain``] subsection +----------------------------------- +In this section, parameters to create domains are specified. +You will need to define the domains you want to create. +In the [``param.domain.atom``] sub-subsection, paramters of the information in the domain are specified. + +- ``domain_occupancy`` + + Format: float + + Description: Occupancy of the whole domain. + +[``param.domain.atom``] subsection +--------------------------------------------- +This section needs to be defined as many times as the number of atoms you want to optimize belonging to the domain. +Note that the type, which represents the type of variable, must be a positive number. + +- ``name`` + + Format: string (can be duplicated) + + Description: The name of the atom to be optimized. + +- ``pos_center`` + + Format: list + + Description: Center coordinates of the atom. Describe in format of [:math:`x_0, y_0, z_0`](:math:`x_0, y_0, z_0` はfloat). + +- ``DWfactor`` + + Format: float + + Description: Debye-Waller factor (in the unit of :math:`\text{Å}^{2}` ). + +- ``occupancy`` + + Format: float (default: 1.0) + + Description: Atom occupancy. + +- ``displace_vector`` (can be omitted) + + Format: list of lists + + Description: A vector that defines the direction in which the atoms are moved. A maximum of three directions can be specified. + Define displacement vectors and initial values in each list as [type, :math:`D_{i1}, D_{i2}, D_{i3}` ](type is int, :math:`D_{i1}, D_{i2}, D_{i3}` is float type). + Follwing the specified information, :math:`l_{type}` is varied as + :math:`dr_i = (D_{i1} \vec{a} + D_{i2} \vec{b} + D_{i3} \vec{c}) * l_{type}` + ( :math:`\vec{a}, \vec{b}, \vec{c}` is a unit lattice vector defined in ``bulk_struc_in_file`` or ``struc_in_file``). + +- ``opt_DW`` (can be omitted) + + Format: list + + Description: Sets the scale at which the Debye-Waller coefficient is varied. + It is defined as [type, scale]. + +- ``opt_occupancy`` + + Format: int + + Description: If defined, the occupancy changes. The specified variable represents the type. + + +An example of an input file is given as follows: + +.. code-block:: + + [param] + scale_factor = 1.0 + type_vector = [1, 2] + + [[param.domain]] + domain_occupancy = 1.0 + [[param.domain.atom]] + name = "Si" + pos_center = [0.00000000, 0.00000000, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[1, 0.0, 0.0, 1.0]] + [[param.domain.atom]] + name = "Si" + pos_center = [0.33333333, 0.66666667, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[1, 0.0, 0.0, 1.0]] + [[param.domain.atom]] + name = "Si" + pos_center = [0.66666667, 0.33333333, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[1, 0.0, 0.0, 1.0]] + [[param.domain.atom]] + name = "Si" + pos_center = [0.33333333, 0.33333333, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[2, 0.0, 0.0, 1.0]] + + +[``reference``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``f_in_file`` + + Format: string + + Description: Path to the input file for the target locking curve. + + +Reference file for Solver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Target reference file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The file containing the data to be targeted to fit. The path is specified by ``f_in_file`` in the [``reference``] section. +For each line, ``h k l F sigma`` is written. Here, ``h, k, l`` are the wavenumbers, ``F`` is the intensity, and ``sigma`` is the uncertainty of ``F``. +An example file is shown below. + +.. code-block:: + + 0.000000 0.000000 0.050000 572.805262 0.1 + 0.000000 0.000000 0.150000 190.712559 0.1 + 0.000000 0.000000 0.250000 114.163340 0.1 + 0.000000 0.000000 0.350000 81.267319 0.1 + 0.000000 0.000000 0.450000 62.927325 0.1 + ... + +Bulk structure file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The file containing the bulk structure data. The path is specified by ``bulk_struc_in_file`` in the [``config``] section. +The first line is a comment, the second line is ``a b c alpha beta gamma``. +Here, ``a`` , ``b``, and ``c`` are the lattice constants of the unit cells, and ``alpha``, ``beta`` , and ``gamma`` are their angles. +The third and subsequent lines specify the ``atomsymbol r1 r2 r3 DWfactor occupancy``. +Here, ``atomsymbol`` is the atom species, ``r1``, ``r2``, and ``r3`` are the position coordinates of the atom, ``DWfactor`` is the Debye-Waller factor, and ``occupancy`` is the occupancy rate. +An example file is given below. + +.. code-block:: + + # SiC(111) bulk + 5.33940 5.33940 7.5510487 90.000000 90.000000 120.000000 + Si 0.00000000 0.00000000 0.00000000 0.0 1.0 + Si 0.33333333 0.66666667 0.00000000 0.0 1.0 + Si 0.66666667 0.33333333 0.00000000 0.0 1.0 + C 0.00000000 0.00000000 0.25000000 0.0 1.0 + ... + +Output files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ``sxrd``, the output files are stored in the folder with the rank number. +Here is a description of the files that are output by ``py2dmat``. + +``stdout`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The standard output by ``sxrd`` is described. +For sxrd's Least square fitting, we give variables as initial parameters and calculate the Rfactor for a 1-shot calculation (number of iterations = 0). +The Rfactor is written in R under Fit results. +Here is an example of the output. + +.. code-block:: + + --------------------------------------- + Program py2dmat/mapper_sxrd/sxrdcalc for surface x-ray diffraction calculations. + Version 3.3.3 - August 2019 + + + Inputfile: lsfit.in + Least-squares fit of model to experimental structure factors. + + ... + + Fit results: + Fit not converged after 0 iterations. + Consider increasing the maximum number of iterations or find better starting values. + chi^2 = 10493110.323318, chi^2 / (degree of freedom) = 223257.666454 (Intensities) + chi^2 = 3707027.897897, chi^2 / (degree of freedom) = 78872.933998 (Structure factors) + R = 0.378801 + + Scale factor: 1.00000000000000 +/- 0.000196 + Parameter Nr. 1: 3.500000 +/- 299467640982.406067 + Parameter Nr. 2: 3.500000 +/- 898402922947.218384 + + Covariance matrix: + 0 1 2 + 0 0.0000000383 20107160.3315223120 -60321480.9945669472 + 1 20107160.3315223120 89680867995567253356544.0000000000 -269042603986701827178496.0000000000 + 2 -60321480.9945669472 -269042603986701827178496.0000000000 807127811960105615753216.0000000000 + diff --git a/manual/v2.2.0/en/_sources/start.rst.txt b/manual/v2.2.0/en/_sources/start.rst.txt new file mode 100644 index 00000000..fe4df306 --- /dev/null +++ b/manual/v2.2.0/en/_sources/start.rst.txt @@ -0,0 +1,68 @@ +Install of py2dmat +============================= + +Prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- Python3 (>=3.6.8) + + - The following Python packages are required. + - tomli >= 1.2 + - numpy >= 1.14 + + - Optional packages + + - mpi4py (required for grid search) + - scipy (required for Nelder-Mead method) + - physbo (>=0.3, required for Baysian optimization) + +How to download and install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can install the ``py2dmat`` python package and the ``py2dmat`` command using the method shown below. + +- Installation using PyPI (recommended) + + - ``python3 -m pip install py2dmat`` + + - ``--user`` option to install locally (``$HOME/.local``) + + - If you use ``py2dmat[all]``, optional packages will be installed at the same time. + +- Installation from source code + + #. ``git clone https://github.com/issp-center-dev/2DMAT`` + #. ``python3 -m pip install ./2DMAT`` + + - The ``pip`` version must be 19 or higher (can be updated with ``python3 -m pip install -U pip``). + +- Download the sample files + + - Sample files are included in the source code. + - ``git clone https://github.com/issp-center-dev/2DMAT`` + +Note that among the direct problem solvers used in ``py2dmat``, +the following solver must be installed separately: + +- TRHEPD forward problem solver (``sim-trhepd-rheed``) +- SXRD forward problem solver (``sxrdcalc``) +- LEED forward problem solver (``satleed``) + +Please refer to the tutorials of each solver for installation details. + +How to run +~~~~~~~~~~~~~ +In ``py2dmat`` , the analysis is done by using a predefined optimization algorithm ``Algorithm`` and a direct problem solver ``Solver`` :: + + $ py2dmat input.toml + +See :doc:`algorithm/index` for the predefined ``Algorithm`` and :doc:`solver/index` for the ``Solver``. + +If you want to prepare the ``Algorithm`` or ``Solver`` by yourself, use the ``py2dmat`` package. +See :doc:`customize/index` for details. + +How to uninstall +~~~~~~~~~~~~~~~~~~~~~~~~ +Please type the following command: + +.. code-block:: bash + + $ python3 -m pip uninstall py2dmat diff --git a/manual/v2.2.0/en/_sources/tool.rst.txt b/manual/v2.2.0/en/_sources/tool.rst.txt new file mode 100644 index 00000000..ebb8179a --- /dev/null +++ b/manual/v2.2.0/en/_sources/tool.rst.txt @@ -0,0 +1,271 @@ +Related Tools +===================== + +``py2dmat_neighborlist`` +***************************** + +This tool generates a neighborhood-list file from the mesh file. + +When you install py2dmat via ``pip`` command, ``py2dmat_neighborlist`` is also installed under the ``bin``. +A python script ``src/py2dmat_neighborlist.py`` is also available. + +Usage +~~~~~~~~~~~~~~~~ + +Pass a path to the mesh file as an argument. +The filename of the generated neighborhood-list file is specified by ``-o`` option. + +.. code-block:: bash + + $ py2dmat_neighborlist -o neighborlist.txt MeshData.txt + + Or + + $ python3 src/py2dmat_neighborlist.py -o MeshData.txt + + +The following command-line options are available. + +- ``-o output`` or ``--output output`` + + - The filename of output (default: ``neighborlist.txt``) + +- ``-u "unit1 unit2..."`` or ``--unit "unit1 unit2..."`` + + - Length scale for each dimension of coordinate (default: 1.0 for all dims) + + - Put values splitted by whitespaces and quote the whole + + - e.g.) ``-u "1.0 0.5"`` + + - Each dimension of coordinate is divided by the corresponding ``unit``. + +- ``-r radius`` or ``--radius radius`` + + - A pair of nodes where the Euclidean distance is less than ``radius`` is considered a neighborhood (default: 1.0) + - Distances are calculated in the space after coordinates are divided by ``-u`` + +- ``-q`` or ``--quiet`` + + - Do not show a progress bar + - Showing a progress bar requires ``tqdm`` python package + +- ``--allow-selfloop`` + + - Include :math:`i` in the neighborhoods of :math:`i` itself + +- ``--check-allpairs`` + + - Calculate distances of all pairs + - This is for debug + + +MPI parallelization is available. + +``tool/to_dft/to_dft.py`` +****************************** + +This tool generates input data for `Quantum Espresso (QE) `_ , a first-principles electronic structure calculation software, from the atomic structures of (001) and (111) surface models of systems with Si isotetrahedral bond networks. This is used to validate the obtained structure and to obtain microscopic information such as the electronic state. In order to eliminate the influence of dangling bond-derived electrons from the opposite surface of interest, we use a technique called hydrogen termination, in which a hydrogen atom is placed at the position of the lowest dangling bond. + +Prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- Python3 >= 3.6 + +The following packages are required: + +- `Atomic Simulation Environment(ASE) `_ (>= 3.21.1) +- Numpy +- Scipy +- Matplotlib + +Overview of this tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The input file including the information such as the name of the structure file (XYZ format) and the lattice vector information to represent the two-dimensional periodic structure is read in, and the coordinates of the lowest layer and the next layer of atoms are extracted from the obtained coordinate data. +The bottom layer atoms are removed, and H atoms are placed at the corresponding positions to create a model with the distance to the next layer atoms adjusted to a tetrahedral structure (for example, the distance to a silane molecule in the case of Si). +The hydrogen-terminated model is saved in XYZ format, and a cif file and an input file for Quantum Espresso (QE) are also created. +If you have QE installed, you can also run the calculation as is. + +Tutorial +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Prepare an XYZ file for reference. + +In the following, we will use the file ``surf_bulk_new111.xyz`` in the folder ``tool/todft/sample/111``. The contents of the file are as follows. + +.. code-block:: + + 12 + surf.txt / bulk.txt + Si 1.219476 0.000000 4.264930 + Si 6.459844 0.000000 4.987850 + Si 1.800417 1.919830 3.404650 + Si 5.878903 1.919830 3.404650 + Si 3.839660 1.919830 2.155740 + Si 0.000000 1.919830 1.900440 + Si 3.839660 0.000000 0.743910 + Si 0.000000 0.000000 0.597210 + Si 1.919830 0.000000 -0.678750 + Si 5.759490 0.000000 -0.678750 + Si 1.919830 1.919830 -2.036250 + Si 5.759490 1.919830 -2.036250 + +2. Next, create an input file for setting the various parameters. + +The file format of the input file is ``toml``. The following section describes the contents of the input file using ``input.toml`` in the ``tool/todft/sample/111`` folder. The contents of the file are as follows. + +.. code-block:: + + [Main] + input_xyz_file = "surf_bulk_new111.xyz" + output_file_head = "surf_bulk_new111_ext" + [Main.param] + z_margin = 0.001 + slab_margin = 10.0 + r_SiH = 1.48 #angstrom + theta = 109.5 #H-Si-H angle in degree + [Main.lattice] + unit_vec = [[7.67932, 0.00000, 0.00000], [0.00000, 3.83966, 0.00000]] + [ASE] + solver_name = "qe" + kpts = [3,3,1] # sampling k points (Monkhorst-Pack grid) + command = "mpirun -np 4 ./pw.x -in espresso.pwi > espresso.pwo" + [Solver] + [Solver.control] + calculation='bands' # 'scf','realx','bands',... + pseudo_dir='./' # Pseudopotential directory + [Solver.system] + ecutwfc = 20.0 # Cut-off energy in Ry + nbands=33 # # of bands (only used in band structure calc + [Solver.pseudo] + Si = 'Si.pbe-mt_fhi.UPF' + H = 'H.pbe-mt_fhi.UPF' + +The input file consists of three sections: ``Main``, ``ASE``, and ``Solver``. +Below is a brief description of the variables for each section. + +``Main`` section +------------------------ +This section contains settings related to the parameters required for hydrogen termination. + +- ``input_xyz_file`` + + Format: string + + Description: Name of the xyz file to input + +- ``output_file_head`` + + Format: string + + Description: Header for output files (xyz and cif files) + +``Main.Param`` section +----------------------------- + +- ``z_margin`` + + Format: float + + Description: Margin used to extract the lowest and second-to-last atoms. For example, if the z-coordinate of the atom in the bottom layer is ``z_min``, the atoms in ``z_min - z_margin <= z <= z_min + z_margin`` will be extracted. + +- ``slab_margin`` + + Format: float + + Description: Margin for tuning the size of the slab. If the z-coordinates of the atoms in the bottom and top layers are ``z_min`` , ``z_max``, then the slab size is given by ``z_max-z_min+slab_margin``. + +- ``r_SiH`` + + Format: float + + Description: The distance (in :math:`\mathrm{\mathring{A}}`) between a vertex (e.g. Si) and H of a tetrahedral structure. + +- ``theta`` + + Format: float + + Description: The angle between the vertex and H of the tetrahedral structure (e.g. Si-H-Si). + +``Main.lattice`` section +----------------------------- + +- ``unit_vec`` + + Format: list + + Description: Specify a unit vector that forms a 2D plane (ex. ``unit_vec = [[7.67932, 0.00000, 0.00000], [0.00000, 3.83966, 0.00000]]``). + + +``ASE`` section +------------------------ +This section specifies parameters related to ``ASE``. + +- ``solver_name`` + + Format: string + + Description: The name of the solver. Currently, only ``qe`` is given. + +- ``kpts`` + + Format: list + + Description: Specify the k-points to be sampled (Monkhorst-Pack grid). + +- ``command`` + + Format: string + + Description: Set the command used to run the solver. + +``Solver`` section +------------------------ +In this section, parameters related to ``Solver`` are specified. +You will need to specify this if you want to perform first-principles calculations directly using ASE. +Basically, the configuration is the same as the one specified in the input file of each solver. +For example, in the case of QE, ``Solver.control`` contains the parameters to be set in the ``control`` section of QE. + +3. Execute the following command. + +.. code-block:: + + python3 to_dft.py input.toml + +After finishing calculations, the following files are generated: + +- ``surf_bulk_new111_ext.xyz`` +- ``surf_bulk_new111_ext.cif`` +- ``espresso.pwi`` + +If the path to the QE and pseudopotential is set in the input file, the first-principle calculation will be performed as is. If not, the ab initio calculation will not be performed and you will get the message ``Calculation of get_potential_energy is not normally finished.`` at the end, but the above file will still be output. + +The following is a description of the output file. + +- ``surf_bulk_new111_ext.xyz`` + +The output is the result of the replacement of the lowest level atom with H and the addition of H to form a tetrahedral structure. +The actual output is as follows. + +.. code-block:: + + 14 + Lattice="7.67932 0.0 0.0 0.0 3.83966 0.0 0.0 0.0 17.0241" Properties=species:S:1:pos:R:3 pbc="T T T" + Si 1.219476 0.000000 4.264930 + Si 6.459844 0.000000 4.987850 + Si 1.800417 1.919830 3.404650 + Si 5.878903 1.919830 3.404650 + Si 3.839660 1.919830 2.155740 + Si 0.000000 1.919830 1.900440 + Si 3.839660 0.000000 0.743910 + Si 0.000000 0.000000 0.597210 + Si 1.919830 0.000000 -0.678750 + Si 5.759490 0.000000 -0.678750 + H 1.919830 -1.208630 -1.532925 + H 1.919830 1.208630 -1.532925 + H 5.759490 -1.208630 -1.532925 + H 5.759490 1.208630 -1.532925 + +This file can be read by appropriate visualization software as ordinary XYZFormat coordinate data, but the lattice vector information of the periodic structure is written in the place where comments are usually written. You can also copy the data of "element name + 3D coordinate" from the third line of the output file to the input file of QE. + +``espresso.pwi`` is the input file for QE's scf calculation, and structural optimization and band calculation can be done by modifying this file accordingly. For details, please refer to the `QE online manual `_ . diff --git a/manual/v2.2.0/en/_sources/tutorial/bayes.rst.txt b/manual/v2.2.0/en/_sources/tutorial/bayes.rst.txt new file mode 100644 index 00000000..bc5c1370 --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/bayes.rst.txt @@ -0,0 +1,236 @@ +Optimization by Bayesian Optimization +======================================== + +This tutorial subscribes how to estimate atomic positions from the experimental diffraction data by using Bayesian optimization (BO). +2DMAT uses `PHYSBO `_ for BO. + +Sample files +~~~~~~~~~~~~~~~~~~~~~~~~ + +Sample files are available from ``sample/sim-trhepd-rheed/single_beam/bayes`` . +This directory includes the following files: + +- ``bulk.txt`` + + The input file of ``bulk.exe`` + +- ``experiment.txt`` , ``template.txt`` + + Reference files for the main program + +- ``ref_BayesData.txt`` + + Solution file for checking whether the calucation successes or not + +- ``input.toml`` + + The input file of py2dmat + +- ``prepare.sh`` , ``do.sh`` + + Script files for running this tutorial + +In the following, we will subscribe these files and then show the result. + +Reference files +~~~~~~~~~~~~~~~~~~~ + +This tutorial uses ``template.txt`` , ``experiment.txt`` similar to the previous one (``minsearch``). +Only difference is that in this tutorial the third parameter ``value_03`` is fixed to ``3.5`` in order to speed up the calculation. +The parameter space to be explored is given by ``MeshData.txt``. + +.. code-block:: + + 1 3.5 3.5 + 2 3.6 3.5 + 3 3.6 3.6 + 4 3.7 3.5 + 5 3.7 3.6 + 6 3.7 3.7 + 7 3.8 3.5 + 8 3.8 3.6 + 9 3.8 3.7 + 10 3.8 3.8 + ... + +The first column is the index of the point and the remaining ones are the coodinates, ``value_0`` and ``value_1`` in the ``template.txt``. + +Input files +~~~~~~~~~~~~~~~~~~~ + +This subsection describes the input file. +For details, see :ref:`the manual of bayes `. +``input.toml`` in the sample directory is shown as the following :: + + [base] + dimension = 2 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + [algorithm] + name = "bayes" + label_list = ["z1", "z2"] + + [algorithm.param] + mesh_path = "MeshData.txt" + + [algorithm.bayes] + random_max_num_probes = 10 + bayes_max_num_probes = 20 + + +- The ``[base]`` section describes the settings for a whole calculation. + + - ``dimension`` is the number of variables you want to optimize. In this case, specify ``2`` because it optimizes two variables. + +- The ``[solver]`` section specifies the solver to use inside the main program and its settings. + + - See the minsearch tutorial. + +- The ``[algorithm]`` section sets the algorithm to use and its settings. + + - ``name`` is the name of the algorithm you want to use, and in this tutorial we will do a Bayesian optimization analysis, so specify ``bayes``. + + - ``label_list`` is a list of label names to be given when outputting the value of ``value_0x`` (x = 1,2). + + - The ``[algorithm.bayes]`` section sets the parameters for Bayesian optimization. + + - ``random_max_num_probes`` specifies the number of random searches before Bayesian optimization. + + - ``bayes_max_num_probes`` specifies the number of Bayesian searches. + +For details on other parameters that can be specified in the input file, see the chapter on input files of ``bayes``. + +Calculation +~~~~~~~~~~~~ + +First, move to the folder where the sample file is located (hereinafter, it is assumed that you are the root directory of 2DMAT). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/bayes + +Copy ``bulk.exe`` and ``surf.exe`` as the tutorial for the direct problem. + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +Execute ``bulk.exe`` to generate ``bulkP.b`` . + +.. code-block:: + + ./bulk.exe + +Then, run the main program (it takes a few secondes) + +.. code-block:: + + python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +This makes a directory with the name of ``0`` . +The following standard output will be shown: + +.. code-block:: + + # parameter + random_max_num_probes = 10 + bayes_max_num_probes = 20 + score = TS + interval = 5 + num_rand_basis = 5000 + value_01 = 5.10000 + value_02 = 4.90000 + R-factor = 0.037237314010261195 + 0001-th step: f(x) = -0.037237 (action=150) + current best f(x) = -0.037237 (best action=150) + + value_01 = 4.30000 + value_02 = 3.50000 + + +A list of hyperparameters, followed by candidate parameters at each step and the corresponding ``R-factor`` multiplied by :math:`-1`, are shown first. +It also outputs the grid index (``action``) and ``f(x)`` with the best ``R-factor`` at that time. +Under the directory ``0``, subdirectories with the name is the grid id are created, like ``Log%%%%%`` (``%%%%%`` is the grid id), and the solver output for each grid is saved. +(The first column in ``MeshData.txt`` will be assigned as the id of the grid). +The final estimated parameters are output to ``BayesData.txt``. + +In this case, ``BayesData.txt`` can be seen as the following + +.. code-block:: + + #step z1 z2 fx z1_action z2_action fx_action + 0 5.1 4.9 0.037237314010261195 5.1 4.9 0.037237314010261195 + 1 5.1 4.9 0.037237314010261195 4.3 3.5 0.06050786306685965 + 2 5.1 4.9 0.037237314010261195 5.3 3.9 0.06215778000834068 + 3 5.1 4.9 0.037237314010261195 4.7 4.2 0.049210767760634364 + 4 5.1 4.9 0.037237314010261195 5.7 3.7 0.08394457854191653 + 5 5.1 4.9 0.037237314010261195 5.2 5.2 0.05556857782716691 + 6 5.1 4.9 0.037237314010261195 5.7 4.0 0.0754639895013157 + 7 5.1 4.9 0.037237314010261195 6.0 4.4 0.054757310814479355 + 8 5.1 4.9 0.037237314010261195 6.0 4.2 0.06339787375966344 + 9 5.1 4.9 0.037237314010261195 5.7 5.2 0.05348404677676544 + 10 5.1 4.7 0.03002813055356341 5.1 4.7 0.03002813055356341 + 11 5.1 4.7 0.03002813055356341 5.0 4.4 0.03019977423448576 + 12 5.3 4.5 0.02887504880071686 5.3 4.5 0.02887504880071686 + 13 5.1 4.5 0.025865346123665988 5.1 4.5 0.025865346123665988 + 14 5.2 4.4 0.02031077875240244 5.2 4.4 0.02031077875240244 + 15 5.2 4.4 0.02031077875240244 5.2 4.6 0.023291891689059388 + 16 5.2 4.4 0.02031077875240244 5.2 4.5 0.02345999725278686 + 17 5.2 4.4 0.02031077875240244 5.1 4.4 0.022561543431398066 + 18 5.2 4.4 0.02031077875240244 5.3 4.4 0.02544527153306051 + 19 5.2 4.4 0.02031077875240244 5.1 4.6 0.02778877135528466 + 20 5.2 4.3 0.012576357659158034 5.2 4.3 0.012576357659158034 + 21 5.1 4.2 0.010217361468113488 5.1 4.2 0.010217361468113488 + 22 5.1 4.2 0.010217361468113488 5.2 4.2 0.013178053637167673 + ... + + +The first column contains the number of steps, and the second, third, and fourth columns contain ``value_01``, ``value_02``, and ``R-factor``, which give the highest score at that time. +This is followed by the candidate ``value_01``, ``value_02`` and ``R-factor`` for that step. +In this case, you can see that the correct solution is obtained at the 21th step. + +In addition, ``do.sh`` is prepared as a script for batch calculation. +``do.sh`` also checks the difference between ``BayesData.dat`` and ``ref_BayesData.dat``. +I will omit the explanation below, but I will post the contents. + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time python3 ../../../../src/py2dmat_main.py input.toml + + echo diff BayesData.txt ref_BayesData.txt + res=0 + diff BayesData.txt ref_BayesData.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: BayesData.txt.txt and ref_BayesData.txt.txt differ + false + fi + +Visualization +~~~~~~~~~~~~~~~~~~~ + +You can see at what step the parameter gave the minimum score by looking at ``BayesData.txt``. +Since ``RockingCurve.txt`` is stored in a subfolder for each step, it is possible to compare it with the experimental value by following the procedure of :doc:``minsearch``. diff --git a/manual/v2.2.0/en/_sources/tutorial/exchange.rst.txt b/manual/v2.2.0/en/_sources/tutorial/exchange.rst.txt new file mode 100644 index 00000000..e6dce52c --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/exchange.rst.txt @@ -0,0 +1,244 @@ +Optimization by replica exchange Monte Carlo +================================================ + +This tutorial subscribes how to estimate atomic positions from the experimental diffraction data by using the replica exchange Monte Carlo method (RXMC). + +Sample files +~~~~~~~~~~~~~~~~~~ + +Sample files are available from ``sample/sim-trhepd-rheed/single_beam/exchange`` . +This directory includes the following files: + +- ``bulk.txt`` + + The input file of ``bulk.exe`` + +- ``experiment.txt`` , ``template.txt`` + + Reference files for the main program + +- ``ref.txt`` + + Solution file for checking whether the calucation successes or not + +- ``input.toml`` + + The input file of py2dmat + +- ``prepare.sh`` , ``do.sh`` + + Script files for running this tutorial + +In the following, we will subscribe these files and then show the result. + +Reference files +~~~~~~~~~~~~~~~~~~~ + +This tutorial uses reference files, ``template.txt`` and ``experiment.txt``, +which are the same as the previous tutorial (:doc:`minsearch`) uses. + +Input files +~~~~~~~~~~~~~ + +This subsection describes the input file. +For details, see :ref:`the manual of bayes `. +``input.toml`` in the sample directory is shown as the following :: + + [base] + dimension = 2 + + [algorithm] + name = "exchange" + label_list = ["z1", "z2"] + seed = 12345 + + [algorithm.param] + min_list = [3.0, 3.0] + max_list = [6.0, 6.0] + + [algorithm.exchange] + numsteps = 1000 + numsteps_exchange = 20 + Tmin = 0.005 + Tmax = 0.05 + Tlogspace = true + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + +In the following, we will briefly describe this input file. +For details, see the manual of :doc:`../algorithm/exchange`. + +- The ``[base]`` section describes the settings for a whole calculation. + + - ``dimension`` is the number of variables you want to optimize. In this case, specify ``2`` because it optimizes two variables. + +- The ``[solver]`` section specifies the solver to use inside the main program and its settings. + + - See the minsearch tutorial. + +- The ``[algorithm]`` section sets the algorithm to use and its settings. + + - ``name`` is the name of the algorithm you want to use, and in this tutorial we will use RXMC, so specify ``exchange``. + + - ``label_list`` is a list of label names to be given when outputting the value of ``value_0x`` (x = 1,2). + + - ``seed`` is the seed that a pseudo-random number generator uses. + + - The ``[algorithm.param]`` section sets the parameter space to be explored. + + - ``min_list`` is a lower bound and ``max_list`` is an upper bound. + + - The ``[algorithm.exchange]`` section sets the parameters for RXMC. + + - ``numstep`` is the number of Monte Carlo steps. + + - ``numsteps_exchange`` is the number of interval steps between temperature exchanges. + + - ``Tmin``, ``Tmax`` are the minimum and the maximum of temperature, respectively. + + - When ``Tlogspace`` is ``true``, the temperature points are distributed uniformly in the logarithmic space. + +- The ``[solver]`` section specifies the solver to use inside the main program and its settings. + + - See the :doc:`minsearch` tutorial. + + +Calculation +~~~~~~~~~~~~ + +First, move to the folder where the sample file is located (hereinafter, it is assumed that you are the root directory of 2DMAT). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/exchange + +Copy ``bulk.exe`` and ``surf.exe`` as the tutorial for the direct problem. + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +Execute ``bulk.exe`` to generate ``bulkP.b`` . + +.. code-block:: + + ./bulk.exe + +Then, run the main program (it takes a few secondes) + +.. code-block:: + + mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + + +Here, the calculation is performed using MPI parallel with 4 processes. +(If you are using Open MPI and you request more processes than you can use, add the ``--oversubscribed`` option to the ``mpiexec`` command.) + +When executed, a folder for each rank will be created, and a ``trial.txt`` file containing the parameters evaluated in each Monte Carlo step and the value of the objective function, and a ``result.txt`` file containing the parameters actually adopted will be created. + +These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters. + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +In the case of the sim-trhepd-rheed solver, a subfolder ``Log%%%%%`` (``%%%%%`` is the number of MC steps) is created under each working folder, and locking curve information etc. are recorded. + +Finally, ``best_result.txt`` is filled with information about the parameter with the optimal objective function (R-factor), the rank from which it was obtained, and the Monte Carlo step. + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + x[0] = 4.221129370933539 + x[1] = 5.139591716517661 + +In addition, ``do.sh`` is prepared as a script for batch calculation. +``do.sh`` also checks the difference between ``best_result.txt`` and ``ref.txt``. +I will omit the explanation below, but I will post the contents. + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml + + echo diff best_result.txt ref.txt + res=0 + diff best_result.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: best_result.txt and ref.txt differ + false + fi + +Post process +~~~~~~~~~~~~~ +The ``result.txt`` in each rank folder records the data sampled by each replica, but the same replica holds samples at different temperatures because of the temperature exchanges. +2DMat provides a script, ``script/separateT.py``, that rearranges the results of all replicas into samples by temperature. + +.. code-block:: + + python3 ../../../../script/separateT.py + + +The data reorganized for each temperature point is written to ``result_T%.txt`` (``%`` is the index of the temperature point). +The first column is the step, the second column is the rank, the third column is the value of the objective function, and the fourth and subsequent columns are the parameters. + +Example:: + + # T = 0.004999999999999999 + # step rank fx x1 x2 + 0 0 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.07830821484593968 3.682008067401509 3.9502750191292586 + + +Visualization +~~~~~~~~~~~~~~~~~~~ + +By illustrating ``result_T.txt``, you can estimate regions where the parameters with small R-factor are. +In this case, the figure ``result.png`` of the 2D parameter space is created by using the following command. + +.. code-block:: + + python3 plot_result_2d.py + +Looking at the resulting diagram, we can see that the samples are concentrated near (5.25, 4.25) and (4.25, 5.25), and that the ``R-factor`` value is small there. + + +.. figure:: ../../../common/img/exchange.* + + Sampled parameters and ``R-factor``. The horizontal axes is ``value_01`` and the vertical axes is ``value_02`` . + +Also, ``RockingCurve.txt`` is stored in each subfolder, +``LogXXX_YYY`` (``XXX`` is an index of MC step and ``YYY`` is an index of a replica in the MPI process). +By using this, it is possible to compare with the experimental value according to the procedure of the previous tutorial. diff --git a/manual/v2.2.0/en/_sources/tutorial/index.rst.txt b/manual/v2.2.0/en/_sources/tutorial/index.rst.txt new file mode 100644 index 00000000..b22f28c5 --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/index.rst.txt @@ -0,0 +1,49 @@ +.. 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 +================================== + +The direct problem solver, ``sim_trhepd_rheed``, is based on the Reflection-High-Energy Electron Diffraction (RHEED, TRHEPD) analysis software developed by Prof. Takashi Hanada at Tohoku University. +In TRHEPD, when atomic coordinates are given, diffraction data is given as a simulation result. +Therefore, we are dealing with the direct problem from atomic coordinates to diffraction data. +On the other hand, in many cases, diffraction data is given experimentally, and the atomic coordinates are required to reproduce the experimental data. These are inverse problems to the above direct problems. + +In 2DMAT, the algorithms for solving the inverse problem can be selected as following algorithms: + +- ``minsearch`` + + Estimating plausible atomic coordinates using the Nealder-Mead method. + +- ``mapper_mpi`` + + Estimate plausible atomic coordinates by searching the entire search grid for a given parameter. + +- ``bayes`` + + Estimate plausible atomic coordinates using Bayesian optimization. + +- ``exchange`` + + Sampling plausible atomic coordinates using a replica exchange Monte Carlo method. + +- ``pamc`` + + Sampling plausible atomic coordinates using a population annealing Monte Carlo method. + +In this tutorial, we will first introduce how to run the sequential problem program, and then how to run ``minsearch`` , ``mapper_mpi``, ``bayes``, ``exchange``, and ``pamc`` . + + +.. toctree:: + :maxdepth: 1 + + sim_trhepd_rheed + minsearch + mpi + bayes + exchange + limitation + pamc + solver_simple diff --git a/manual/v2.2.0/en/_sources/tutorial/limitation.rst.txt b/manual/v2.2.0/en/_sources/tutorial/limitation.rst.txt new file mode 100644 index 00000000..baf41136 --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/limitation.rst.txt @@ -0,0 +1,175 @@ +Replica Exchange Monte Carlo search with limitation +========================================================================== + +This tutorial describes the constraint expression function that can be set in the ``[runner.limitation]`` section. +As an example, the replica exchange Monte Carlo method is applied to the calculation of Himmelblau with constraints. + +Sample files location +~~~~~~~~~~~~~~~~~~~~~~~~ + +Sample files are available in the ``sample/analytical/limitation`` directory. +This directory contains the following files. + +- ``ref.txt`` + + File to check if the calculation is executed correctly (answer to obtain by performing this tutorial). + +- ``input.toml`` + + Input file for the main program. + +- ``do.sh`` + + Script prepared to calculate this tutorial at once. + +In the following, we will explain these files, and then introduce the actual calculation results. + +Input files +~~~~~~~~~~~~~~~~~~~ + +The following ``input.toml`` is an input file for the main program. + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "exchange" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + unit_list = [0.3, 0.3] + + [algorithm.exchange] + Tmin = 1.0 + Tmax = 100000.0 + numsteps = 10000 + numsteps_exchange = 100 + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.limitation] + co_a = [[1, -1],[1, 1]] + co_b = [[0], [-1]] + +``[base]`` section is the parameter of the main program. +``dimension`` is the number of variables to be optimized, and in this case, it is 2. + +``[algorithm]`` section is the section to set the search algorithm. +``name`` is the name of the search algorithm. In this case, specify ``"exchange"`` for the replica exchange Monte Carlo method. +``seed`` is the seed given to the pseudo-random number generator. + +``[algorithm.param]`` sub-section specifies the range of parameters to be optimized. +``min_list`` indicates the minimum value, and ``max_list`` indicates the maximum value. + +``[algorithm.exchange]`` sub-section specifies the hyperparameters of the replica exchange Monte Carlo method. + +- ``numstep`` is the number of Monte Carlo updates. +- ``numsteps_exchange`` specifies the number of times to attempt temperature exchange. +- ``Tmin`` and ``Tmax`` are the lower and upper limits of the temperature, respectively. +- If ``Tlogspace`` is ``true``, the temperature is divided equally in log space. This option is not specified in this ``input.toml`` because the default value is ``true``. + +``[solver]`` section specifies the solver used internally in the main program. +In this case, the ``analytical`` solver is specified. +The ``analytical`` solver sets the function using the ``function_name`` parameter, and in this case, the Himmelblau function is specified. + +``[runner]`` section has a sub-section ``[runner.limitation]``, and in this section, the constraint expression is set. +In the current version, the constraint expression is defined as :math:`Ax+b>0` where :math:`x` is :math:`N` dimensional input parameter, :math:`A` is a :math:`M \times N` matrix, and :math:`b` is a :math:`M` dimensional vector. +:math:`A` and :math:`b` are set by ``co_a`` and ``co_b``, respectively. +For details, see the ``[limitation]`` section in the input file in the manual. + +In this case, the following constraint is imposed: + +.. math:: + + x_{1} − x_{2} > 0\\ + x_{1} + x_{2} − 1 > 0 + + +Calculation +~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample file is located (assuming that you are directly under the directory where you downloaded this software). + +.. code-block:: + + cd sample/analytical/limitation + +Then, execute the main program as follows (the calculation time will end in about 20 seconds on a normal PC). + +.. code-block:: + + mpiexec -np 10 python3 ../../../src/py2dmat_main.py input.toml | tee log.txt + +In this case, a calculation with 10 MPI parallel processes is performed. +(When using OpenMPI, if the number of processes to be used is greater than the number of available cores, add the ``--oversubscribed`` option to the ``mpiexec`` command.) +After executed, the ``output`` folder is generated, and in it, a subfolder for each rank is created. +Each subfolder contains the results of the calculation. +``trial.txt`` file, which contains the parameters and objective function values evaluated at each Monte Carlo step, and ``result.txt`` file, which contains the parameters actually adopted, are created. +Both files have the same format, with the first two columns being the step number and the walker number within the process, the next being the temperature, the third being the value of the objective function, and the fourth and subsequent being the parameters. +The following is the beginning of the ``output/0/result.txt`` file: + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569 + 1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + +Finally, the best parameter and the rank and Monte Carlo step at which the objective function is minimized are written to ``output/best_result.txt``. + +.. code-block:: + + nprocs = 10 + rank = 2 + step = 4523 + walker = 0 + fx = 0.00010188398524402734 + x1 = 3.584944906595298 + x2 = -1.8506985826548874 + +``do.sh`` is available as a script to calculate all at once. +Additionally, in ``do.sh``, the difference between ``best_result.txt`` and ``ref.txt`` is also compared. + +.. code-block:: + + #!/bin/bash + mpiexec -np 10 --oversubscribe python3 ../../../src/py2dmat_main.py input.toml + + echo diff output/best_result.txt ref.txt + res=0 + diff output/best_result.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: best_result.txt and ref.txt differ + false + fi + +Visualization of the calculation result +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By visualizing the ``result.txt`` file, we can confirm that the search is only for coordinates that satisfy the constraint expression. +``hist2d_limitation_sample.py`` is prepared to visualize the 2D parameter space. +This generates a histogram of the posterior probability distribution in the ``_histogram`` folder. +The histogram is generated using the data obtained by discarding the first 1000 steps of the search as a burn-in period. + +.. code-block:: + + python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1 + +The figure shows the posterior probability distribution and the two lines :math:`x_{1} − x_{2} = 0, x_{1} + x_{2} − 1 = 0`, +and it is confirmed that the search is only for the range where :math:`x_{1} − x_{2} > 0, x_{1} + x_{2} − 1 > 0`. + +.. figure:: ../../../common/img/limitation_beta_min.* + +.. figure:: ../../../common/img/limitation_beta_max.* diff --git a/manual/v2.2.0/en/_sources/tutorial/minsearch.rst.txt b/manual/v2.2.0/en/_sources/tutorial/minsearch.rst.txt new file mode 100644 index 00000000..3d20a633 --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/minsearch.rst.txt @@ -0,0 +1,286 @@ +Optimization by Nelder-Mead method +==================================== + +In this section, we will explain how to calculate the inverse problem of analyzing atomic coordinates from diffraction data using the Nelder-Mead method. +The specific calculation procedure is as follows. + +0. Preparation of the reference file + + Prepare the reference file to be matched (in this tutorial, it corresponds to ``experiment.txt`` described below). + + +1. Perform calculations on the bulk part of the surface structure. + + Copy ``bulk.exe`` to ``sample/sim-trhepd-rheed/minsearch`` and run the calculation. + +2. Run the main program + + Run the calculation using ``src/py2dmat_main.py`` to estimate the atomic coordinates. + +In the main program, the Nelder-Mead method (using `scipy.optimize.fmin `_) is used. ) to find the parameter that minimizes the deviation (R-value) between the intensity obtained using the solver (in this case ``surf.exe``) and the intensity listed in the reference file (``experiment.txt``). + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/py2dmat/sim-trhepd-rheed/single_beam/minsearch``. +The following files are stored in the folder. + +- ``bulk.txt`` + + Input file of ``bulk.exe``. + +- ``experiment.txt`` , ``template.txt`` + + Reference file to proceed with calculations in the main program. + +- ``ref.txt`` + + A file containing the answers you want to seek in this tutorial. + +- ``input.toml`` + + Input file of the main program. + +- ``prepare.sh`` , ``do.sh`` + + Script prepared for doing all calculation of this tutorial + +The following sections describe these files and then show the actual calculation results. + +The reference file +~~~~~~~~~~~~~~~~~~~ + +The ``template.txt`` file is almost the same format as the input file for ``surf.exe``. +The parameters to be run (such as the atomic coordinates you want to find) are rewritten as ``value_*`` or some other appropriate string. +The following is the content of ``template.txt``. + +.. code-block:: + + 2 ,NELMS, -------- Ge(001)-c4x2 + 32,1.0,0.1 ,Ge Z,da1,sap + 0.6,0.6,0.6 ,BH(I),BK(I),BZ(I) + 32,1.0,0.1 ,Ge Z,da1,sap + 0.4,0.4,0.4 ,BH(I),BK(I),BZ(I) + 9,4,0,0,2, 2.0,-0.5,0.5 ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS + 8 ,NATM + 1, 1.0, 1.34502591 1 value_01 ,IELM(I),ocr(I),X(I),Y(I),Z(I) + 1, 1.0, 0.752457792 1 value_02 + 2, 1.0, 1.480003343 1.465005851 value_03 + 2, 1.0, 2 1.497500418 2.281675 + 2, 1.0, 1 1.5 1.991675 + 2, 1.0, 0 1 0.847225 + 2, 1.0, 2 1 0.807225 + 2, 1.0, 1.009998328 1 0.597225 + 1,1 ,(WDOM,I=1,NDOM) + +In this input file, ``value_01``, ``value_02``, and ``value_03`` are used. +In the sample folder, there is a reference file ``ref.txt`` to know if the atomic positions are estimated correctly. The contents of this file are + +.. code-block:: + + fx = 7.382680568652868e-06 + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 + + +``value_0x`` corresponds to ``z_x`` (x=1, 2, 3). +``fx`` is the optimal value of the objective function. +The ``experiment.txt`` is a file that is used as a reference in the main program, and is equivalent to ``convolution.txt``, which is calculated by putting the parameters in ``ref.txt`` into ``template.txt`` and following the same procedure as in the tutorial on direct problems. (Note that the input files for ``bulk.exe`` and ``suft.exe`` are different from those in the sequential problem tutorial.) + + +Input file +~~~~~~~~~~~~~~~~~~~ + +In this section, we will prepare the input file ``input.toml`` for the main program. +The details of ``input.toml`` can be found in the input file. +This section describes the contents of ``input.toml`` in the sample file. + +.. code-block:: + + [base] + dimension = 3 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02", "value_03" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + [algorithm] + name = "minsearch" + label_list = ["z1", "z2", "z3"] + + [algorithm.param] + min_list = [0.0, 0.0, 0.0] + max_list = [10.0, 10.0, 10.0] + initial_list = [5.25, 4.25, 3.50] + + +First, ``[base]`` section is explained. + +- The ``dimension`` is the number of variables to be optimized, in this case ``3`` since we are optimizing three variables as described in ``template.txt``. + + +The ``[solver]`` section specifies the solver to be used inside the main program and its settings. + +- The ``name`` is the name of the solver you want to use, which in this tutorial is ``sim-trhepd-rheed``, since we will be using it for our analysis. + +The solver can be configured in the subsections ``[solver.config]``, ``[solver.param]``, and ``[solver.reference]``. + +The ``[solver.config]`` section specifies options for reading the output file produced by the main program's internal call, ``surf.exe``. + +- The ``calculated_first_line`` specifies the first line to read from the output file. + +- The ``calculated_last_line`` specifies the last line of the output file to be read. + +- The ``row_number`` specifies the number of columns in the output file to read. + +The ``[solver.param]`` section specifies options for reading the output file produced by the main program's internal call, ``surf.exe``. + +- The ``string_list`` is a list of variable names to be read in ``template.txt``. + +- ``degree_max`` specifies the maximum angle in degrees. + +The ``[solver.reference]`` section specifies the location of the experimental data and the range to read. + +- The ``path`` specifies the path where the experimental data is located. + +- The ``first`` specifies the first line of the experimental data file to read. + +- The ``end`` specifies the last line of the experimental data file to read. + +The ``[algorithm]`` section specifies the algorithm to use and its settings. + +- The ``name`` is the name of the algorithm you want to use, in this tutorial we will use ``minsearch`` since we will be using the Nelder-Mead method. + +- The ``label_list`` is a list of label names to be added to the output of ``value_0x`` (x=1,2,3). + +The ``[algorithm.param]`` section specifies the range of parameters to search and their initial values. + +- The ``min_list`` and ``max_list`` specify the minimum and maximum values of the search range, respectively. +- The ``initial_list`` specifies the initial values. + +Other parameters, such as convergence judgments used in the Nelder-Mead method, can be done in the ``[algorithm]`` section, although they are omitted here because the default values are used. +See the input file chapter for details. + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample files are located (we will assume that you are directly under the directory where you downloaded this software). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/minsearch + +Copy ``bulk.exe`` and ``surf.exe``. + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +First, run ``bulk.exe`` to create ``bulkP.b``. + +.. code-block:: + + ./bulk.exe + +After that, run the main program (the computation time takes only a few seconds on a normal PC). + +.. code-block:: + + python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +Then, the standard output will be seen as follows. + +.. code-block:: + + Read experiment.txt + z1 = 5.25000 + z2 = 4.25000 + z3 = 3.50000 + [' 5.25000', ' 4.25000', ' 3.50000'] + PASS : degree in lastline = 7.0 + PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70 + R-factor = 0.015199251773721183 + z1 = 5.50000 + z2 = 4.25000 + z3 = 3.50000 + [' 5.50000', ' 4.25000', ' 3.50000'] + PASS : degree in lastline = 7.0 + PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70 + R-factor = 0.04380131351780189 + z1 = 5.25000 + z2 = 4.50000 + z3 = 3.50000 + [' 5.25000', ' 4.50000', ' 3.50000'] + ... + +The ``z1``, ``z2``, and ``z3`` are the candidate parameters at each step and the ``R-factor`` at that time. +The results of each step are also output to the folder ``Logxxxxx`` (where xxxxxx is the number of steps). +The final estimated parameters will be output to ``res.dat``. +In the current case, the following result is obtained: + +.. code-block:: + + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 + +You can see that we get the same value as the correct answer data ``ref.txt``. +Note that ``do.sh`` is available as a script for batch calculation. +In ``do.sh``, it also compares the difference between ``res.txt`` and ``ref.txt``. +Here is what it does, without further explanation. + +.. code-block:: + + sh ./prepare.sh + + ./bulk.exe + + time python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + + echo diff res.txt ref.txt + res=0 + diff res.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo Test PASS + true + else + echo Test FAILED: res.txt and ref.txt differ + false + fi + +Visualization of calculation results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The data of the rocking curve at each step is stored in ``Logxxxx_00000001`` (where ``xxxx`` is the index of steps) as ``RockingCurve.txt``. +A tool ``draw_RC_double.py`` is provided to visualize this data. +In this section, we will use this tool to visualize the results. + +.. code-block:: + + cp 0/Log00000001_00000001/RockingCurve.txt RockingCurve_ini.txt + cp 0/Log00000062_00000001/RockingCurve.txt RockingCurve_con.txt + cp ../../../../script/draw_RC_double.py . + python draw_RC_double.py + +Running the above will output ``RC_double.png``. + +.. figure:: ../../../common/img/RC_double_minsearch.* + + Analysis using the Nelder-Mead method. The red circle represents the experimental value, the blue line represents the first step, and the green line represents the rocking curve obtained at the last step. + +From the figure, we can see that the last step agrees with the experimental one. diff --git a/manual/v2.2.0/en/_sources/tutorial/mpi.rst.txt b/manual/v2.2.0/en/_sources/tutorial/mpi.rst.txt new file mode 100644 index 00000000..b40afeba --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/mpi.rst.txt @@ -0,0 +1,241 @@ +Grid search +===================================== + +In this section, we will explain how to perform a grid-type search and analyze atomic coordinates from diffraction data. +The grid type search is compatible with MPI. The specific calculation procedure is the same as for ``minsearch``. +However, it is necessary to prepare the data ``MeshData.txt`` to give the search grid in advance. + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/sim-trhepd-rheed/single_beam/mapper``. +The following files are stored in the folder + +- ``bulk.txt`` + + Input file of ``bulk.exe`` + +- ``experiment.txt`` , ``template.txt`` + + Reference file to proceed with calculations in the main program. + +- ``ref_ColorMap.txt`` + + A file to check if the calculation was performed correctly (the answer to ``ColorMap.txt`` obtained by doing this tutorial). + +- ``input.toml`` + + Input file of the main program. + +- ``prepare.sh`` , ``do.sh`` + + Script prepared for bulk calculation of this tutorial. + +Below, we will describe these files and then show the actual calculation results. + +Reference file +~~~~~~~~~~~~~~~~~~~ + +The ``template.txt`` and ``experiment.txt`` are the same as in the previous tutorial (Nealder-Mead optimization). +However, to reduce the computation time, the value is fixed to ``3.5`` instead of ``value_03``, and the grid is searched in 2D. +The actual grid to be searched is given in ``MeshData.txt``. +In the sample, the contents of ``MeshData.txt`` are as follows. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +The first column is the serial number, and the second and subsequent columns are the values of ``value_0`` , ``value_1`` that go into ``template.txt``, in that order. + +Input file +~~~~~~~~~~~~~~~~~~~ + +This section describes the input file for the main program, ``input.toml``. +The details of ``input.toml`` can be found in the input file. +The following is the content of ``input.toml`` in the sample file. + +.. code-block:: + + [base] + dimension = 2 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + [algorithm] + name = "mapper" + label_list = ["z1", "z2"] + +First, ``[base]`` section is explained. + +- The ``dimension`` is the number of variables to be optimized, in this case ``2`` since we are optimizing two variables as described in ``template.txt``. + + +The ``[solver]`` section specifies the solver to be used inside the main program and its settings. + +- The ``name`` is the name of the solver you want to use, which in this tutorial is ``sim-trhepd-rheed``, since we will be using it for our analysis. + +The solver can be configured in the subsections ``[solver.config]``, ``[solver.param]``, and ``[solver.reference]``. + +The ``[solver.config]`` section specifies options for reading the output file produced by the main program's internal call, ``surf.exe``. + +- The ``calculated_first_line`` specifies the first line to read from the output file. + +- The ``calculated_last_line`` specifies the last line of the output file to be read. + +- The ``row_number`` specifies the number of columns in the output file to read. + +The ``[solver.param]`` section specifies options for reading the output file produced by the main program's internal call, ``surf.exe``. + +- The ``string_list`` is a list of variable names to be read in ``template.txt``. + +- ``degree_max`` specifies the maximum angle in degrees. + +The ``[solver.reference]`` section specifies the location of the experimental data and the range to read. + +- The ``path`` specifies the path where the experimental data is located. + +- The ``first`` specifies the first line of the experimental data file to read. + +- The ``end`` specifies the last line of the experimental data file to read. + +The ``[algorithm]`` section specifies the algorithm to use and its settings. + +- The ``name`` is the name of the algorithm you want to use, in this tutorial we will use ``mapper`` since we will be using grid-search method. + + +- The ``label_list`` is a list of label names to be attached to the output ``value_0x`` (x=1,2). + +For details on other parameters that can be specified in the input file, please see the Input File chapter. + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~ + + +First, move to the folder where the sample files are located (we will assume that you are directly under the directory where you downloaded this software). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/minsearch + +Copy ``bulk.exe`` and ``surf.exe``. + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +First, run ``bulk.exe`` to create ``bulkP.b``. + +.. code-block:: + + ./bulk.exe + +After that, run the main program (the computation time takes only a few seconds on a normal PC). + +.. code-block:: + + mpiexec -np 2 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +Here, the calculation using MPI parallel with 2 processes will be done. +When executed, a folder for each rank will be created, and a subfolder ``Log%%%%%`` (where ``%%%%%`` is the grid id) will be created under it. +(The grid id is assigned to the number in ``MeshData.txt``). +The standard output will be seen like this. + +.. code-block:: + + Iteration : 1/33 + Read experiment.txt + mesh before: [1.0, 6.0, 6.0] + z1 = 6.00000 + z2 = 6.00000 + [' 6.00000', ' 6.00000'] + PASS : degree in lastline = 7.0 + PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70 + R-factor = 0.04785241875354398 + ... + +The ``z1`` and ``z2`` are the candidate parameters for each mesh and the ``R-factor`` at that time. +Finally, the ``R-factor`` calculated for all the points on the grid will be output to ``ColorMap.txt``. +In this case, the following results will be obtained. + +.. code-block:: + + 6.000000 6.000000 0.047852 + 6.000000 5.750000 0.055011 + 6.000000 5.500000 0.053190 + 6.000000 5.250000 0.038905 + 6.000000 5.000000 0.047674 + 6.000000 4.750000 0.065919 + 6.000000 4.500000 0.053675 + 6.000000 4.250000 0.061261 + 6.000000 4.000000 0.069351 + 6.000000 3.750000 0.071868 + 6.000000 3.500000 0.072739 + ... + +The first and second columns will contain the values of ``value_01`` and ``value_02``, and the third column will contain the ``R-factor``. +Note that ``do.sh`` is available as a script for batch calculation. +In ``do.sh``, it also compares the difference between ``res.txt`` and ``ref.txt``. +Here is what it does, without further explanation. + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time mpiexec -np 2 python3 ../../../../src/py2dmat_main.py input.toml + + echo diff ColorMap.txt ref_ColorMap.txt + res=0 + diff ColorMap.txt ref_ColorMap.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: ColorMap.txt and ref_ColorMap.txt differ + false + fi + +Visualization of calculation results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By seeing ``ColorMap.txt``, we can estimate the region where the small parameters of ``R-factor`` are located. +In this case, the following command will create a two-dimensional parameter space diagram ``ColorMapFig.png``. + +.. code-block:: + + python3 plot_colormap_2d.py + +Looking at the generated figure, we can see that it has a minimum value around (5.25, 4.25). + +.. figure:: ../../../common/img/mapper.* + + ``R-factor`` on a two-dimensional parameter space. + +``RockingCurve.txt`` is stored in each subfolder. +By using it, you can compare the results with the experimental values following the procedure in the previous tutorial. diff --git a/manual/v2.2.0/en/_sources/tutorial/pamc.rst.txt b/manual/v2.2.0/en/_sources/tutorial/pamc.rst.txt new file mode 100644 index 00000000..fe6beef4 --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/pamc.rst.txt @@ -0,0 +1,257 @@ +Optimization by population annealing +================================================ + +This tutorial subscribes how to estimate atomic positions from the experimental diffraction data by using the population annealing Monte Carlo method (PAMC). + +Sample files +~~~~~~~~~~~~~~~~~~ + +Sample files are available from ``sample/sim-trhepd-rheed/single_beam/pamc`` . +This directory includes the following files: + +- ``bulk.txt`` + + The input file of ``bulk.exe`` + +- ``experiment.txt`` , ``template.txt`` + + Reference files for the main program + +- ``ref.txt`` + + Solution file for checking whether the calucation successes or not (reference for ``fx.txt``) + +- ``input.toml`` + + The input file of py2dmat + +- ``prepare.sh`` , ``do.sh`` + + Script files for running this tutorial + +In the following, we will subscribe these files and then show the result. + +Reference files +~~~~~~~~~~~~~~~~~~~ + +This tutorial uses reference files, ``template.txt`` and ``experiment.txt``, +which are the same as the previous tutorial (:doc:`minsearch`) uses. + +Input files +~~~~~~~~~~~~~ + +This subsection describes the input file. +For details, see :ref:`the manual of bayes `. +``input.toml`` in the sample directory is shown as the following :: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "pamc" + label_list = ["z1", "z2"] + seed = 12345 + + [algorithm.param] + min_list = [3.0, 3.0] + max_list = [6.0, 6.0] + unit_list = [0.3, 0.3] + + [algorithm.pamc] + numsteps_annealing = 5 + bmin = 0.0 + bmax = 200.0 + Tnum = 21 + Tlogspace = false + nreplica_per_proc = 10 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + +In the following, we will briefly describe this input file. +For details, see the manual of :doc:`../algorithm/exchange`. + +- The ``[base]`` section describes the settings for a whole calculation. + + - ``dimension`` is the number of variables you want to optimize. In this case, specify ``2`` because it optimizes two variables. + +- The ``[solver]`` section specifies the solver to use inside the main program and its settings. + + - See the minsearch tutorial. + +- The ``[algorithm]`` section sets the algorithm to use and its settings. + + - ``name`` is the name of the algorithm you want to use, and in this tutorial we will use RXMC, so specify ``exchange``. + + - ``label_list`` is a list of label names to be given when outputting the value of ``value_0x`` (x = 1,2). + + - ``seed`` is the seed that a pseudo-random number generator uses. + + - The ``[algorithm.param]`` section sets the parameter space to be explored. + + - ``min_list`` is a lower bound and ``max_list`` is an upper bound. + - ``unit_list`` is step length in one MC update (deviation of Gaussian) + + - The ``[algorithm.pamc]`` section sets the parameters for PAMC. + + - ``numsteps_annealing`` is the number of interval steps between temperature decreasing. + + - ``bmin``, ``bmax`` are the minimum and the maximum of inversed temperature, respectively. + + - ``Tnum`` is the number of (inversed) temperature points. + + - When ``Tlogspace`` is ``true``, the temperature points are distributed uniformly in the logarithmic space. + + - ``nreplica_per_proc`` is the number of replicas (MC walkers) in one MPI process. + +- The ``[solver]`` section specifies the solver to use inside the main program and its settings. + + - See the :doc:`minsearch` tutorial. + + +Calculation +~~~~~~~~~~~~ + +First, move to the folder where the sample file is located (hereinafter, it is assumed that you are the root directory of 2DMAT). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/pamc + +Copy ``bulk.exe`` and ``surf.exe`` as the tutorial for the direct problem. + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +Execute ``bulk.exe`` to generate ``bulkP.b`` . + +.. code-block:: + + ./bulk.exe + +Then, run the main program (it takes a few secondes) + +.. code-block:: + + mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + + +Here, the calculation is performed using MPI parallel with 4 processes. +(If you are using Open MPI and you request more processes than you can use, add the ``--oversubscribed`` option to the ``mpiexec`` command.) + +When executed, a folder for each rank will be created, and ``trial_TXXX.txt`` files containing the parameters evaluated in each Monte Carlo step and the value of the objective function at each temperature (``XXX`` is the index of points), and ``result_TXXX.txt`` files containing the parameters actually adopted will be created. +These files are concatnated into ``result.txt`` and ``trial.txt``. + +These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the (inversed) temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters. +The final two columns are the weight of walker (Neal-Jarzynski weight) and the index of the grand ancestor (the replica index at the beginning of the calculation). + +.. code-block:: + + # step walker beta fx z1 z2 weight ancestor + 0 0 0.0 0.07702743614780189 5.788848278451443 3.949126663745358 1.0 0 + 0 1 0.0 0.08737730661436376 3.551756435031283 3.6136808356591192 1.0 1 + 0 2 0.0 0.04954470587051104 4.70317508724506 4.786634108937754 1.0 2 + 0 3 0.0 0.04671675601156148 5.893543559206865 4.959531290614713 1.0 3 + 0 4 0.0 0.04142014655238446 5.246719912601735 4.960709612555206 1.0 4 + + +In the case of the sim-trhepd-rheed solver, a subfolder ``Log%%%%%`` (``%%%%%`` is the number of MC steps) is created under each working folder, and locking curve information etc. are recorded. + +Finally, ``best_result.txt`` is filled with information about the parameter with the optimal objective function (R-factor), the rank from which it was obtained, and the Monte Carlo step. + +.. code-block:: + + nprocs = 4 + rank = 0 + step = 71 + walker = 5 + fx = 0.008186713312593607 + z1 = 4.225633749839847 + z2 = 5.142666117413409 + +Finally, ``fx.txt`` stores the statistics at each temperature point: + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.0 0.06428002079611472 0.002703413400677839 40 0.0 0.795 + 10.0 0.061399304916174735 0.002649424392996749 40 -0.6280819199879947 0.85 + 20.0 0.05904248889111052 0.0031622711212952034 40 -1.2283060742855603 0.74 + 30.0 0.04956921148431115 0.0028298565759159633 40 -1.7991035905899855 0.67 + +The first column is (inversed) temperature, and +the second/third ones are the mean and standard error of :math:`f(x)`, respectively. +The fourth column is the number of replicas and the fifth one is the logarithm of the ratio of the partition functions, :math:`\log(Z_n/Z_0)`, where :math:`Z_0` is the partition function at the first temperature. +The sixth column is the acceptance ratio of MC updates. + +In addition, ``do.sh`` is prepared as a script for batch calculation. +``do.sh`` also checks the difference between ``best_result.txt`` and ``ref.txt``. +I will omit the explanation below, but I will post the contents. + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml + + echo diff output/fx.txt ref.txt + res=0 + diff output/fx.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: output/fx.txt and ref.txt differ + false + fi + +Visualization +~~~~~~~~~~~~~~~~~~~ + +By illustrating ``result_T.txt``, you can estimate regions where the parameters with small R-factor are. +In this case, the figure ``result_fx.pdf`` and ``result_T.pdf`` of the 2D parameter space is created by using the following command. +The color of symbols of ``result_fx.pdf`` and ``result_T.pdf`` mean ``R-factor`` and :math:`\beta`, respectively. + +.. code-block:: + + python3 plot_result_2d.py + +Looking at the resulting diagram, we can see that the samples are concentrated near (5.25, 4.25) and (4.25, 5.25), and that the ``R-factor`` value is small there. + + +.. figure:: ../../../common/img/pamc_fx.* + + Sampled parameters and ``R-factor``. The horizontal axes is ``value_01`` and the vertical axes is ``value_02`` . + +.. figure:: ../../../common/img/pamc_T.* + + Sampled parameters and :math:`\beta`. The horizontal axes is ``value_01`` and the vertical axes is ``value_02`` . + +Also, ``RockingCurve.txt`` is stored in each subfolder, +``LogXXX_YYY`` (``XXX`` is an index of MC step and ``YYY`` is an index of a replica in the MPI process). +By using this, it is possible to compare with the experimental value according to the procedure of the previous tutorial. diff --git a/manual/v2.2.0/en/_sources/tutorial/sim_trhepd_rheed.rst.txt b/manual/v2.2.0/en/_sources/tutorial/sim_trhepd_rheed.rst.txt new file mode 100644 index 00000000..9d5d879c --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/sim_trhepd_rheed.rst.txt @@ -0,0 +1,144 @@ +TRHEPD Direct Problem Solver +============================ + +As one of the forward problem solvers, 2DMAT provides a wrapper for the program `sim-trhepd-rheed `_ , which calculates the intensity of reflection fast (positron) electron diffraction (RHEED, TRHEPD) (A. Ichimiya, Jpn. J. Appl. Phys. 22, 176 (1983); 24, 1365 (1985)). +In this tutorial, we will show some examples which use some algorithms with sim-trhepd-rheed. +First, we will install and test sim-trhepd-rheed (for details, see the official web page for `sim-trhepd-rheed `_). + +Download and Install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, in the tutorial, we assume that you are at the location where the ``2DMAT`` folder is located. :: + + $ ls -d 2DMAT + 2DMAT/ + +Get the source codes from the sim-trhepd-rheed repository on GitHub and build it. :: + + git clone http://github.com/sim-trhepd-rheed/sim-trhepd-rheed + cd sim-trhepd-rheed/src + make + +If make is successful, ``bulk.exe`` and ``surf.exe`` will be created. + + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~ + +In sim-trhepd-rheed, the bulk part of the surface structure is first calculated with ``bulk.exe``. +Then, using the results of the ``bulk.exe`` calculation (the ``bulkP.b`` file), +the surface portion of the ``surf.exe`` surface structure is calculated. + +In this tutorial, we will actually try to do the TRHEPD calculation. +The sample input files are located in ``sample/sim-trhepd-rheed`` in 2DMAT. +First, copy this folder to a suitable working folder ``work``. + +.. code-block:: + + cd ../../ + cp -r 2DMAT/sample/sim-trhepd-rheed/solver work + cd work + +Next, copy ``bulk.exe`` and ``surf.exe`` to ``work``. + +.. code-block:: + + cp ../sim-trhepd-rheed/src/bulk.exe . + cp ../sim-trhepd-rheed/src/surf.exe . + +Execute ``bulk.exe``. + +.. code-block:: + + ./bulk.exe + +Then, the bulk file ``bulkP.b`` will be generated with the following output. + +.. code-block:: + + 0:electron 1:positron ? + P + input-filename (end=e) ? : + bulk.txt + output-filename : + bulkP.b + +Next, execute ``surf.exe``. + +.. code-block:: + + ./surf.exe + +Then, the following standard output will be seen. + +.. code-block:: + + bulk-filename (end=e) ? : + bulkP.b + structure-filename (end=e) ? : + surf.txt + output-filename : + surf-bulkP.md + surf-bulkP.s + +After execution, the files ``surf-bulkP.md``, ``surf-bulkP.s`` and ``SURFYYYYMMDD-HHMMSSlog.txt`` will be generated. +(YYYYMMDD and HHMMSS are numbers corresponding to the execution date and time). + +Visualization of calculation result +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The contents of ``surf-bulkP.s`` are shown as follow: + +.. code-block:: + + #azimuths,g-angles,beams + 1 56 13 + #ih,ik + 6 0 5 0 4 0 3 0 2 0 1 0 0 0 -1 0 -2 0 -3 0 -4 0 -5 0 -6 0 + 0.5000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1595E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.6000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1870E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.7000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2121E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.8000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2171E-02, 0.1927E-01, 0.2171E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.9000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.4397E-02, 0.1700E-01, 0.4397E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.1000E+01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.6326E-02, 0.1495E-01, 0.6326E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + ... + +From the above file, create a rocking curve from the angle on the vertical axis (first column of data after row 5) and the intensity of the (0,0) peak (eighth column of data after row 5). +You can use Gnuplot or other graphing software, but here we use the program ``plot_bulkP.py`` in the ``2DMAT/script`` folder. +Run it as follows. + +.. code-block:: + + python3 ../2DMAT/script/plot_bulkP.py + +The following ``plot_bulkP.png`` will be created. + +.. figure:: ../../../common/img/plot_bulkP.* + + Rocking curve of Si(001)-2x1 surface. + +We will convolute and normalize the diffraction intensity data of the 00 peaks. +Prepare ``surf-bulkP.s`` and run ``make_convolution.py``. + +.. code-block:: + + python3 ../2DMAT/script/make_convolution.py + +When executed, the following file ``convolution.txt`` will be created. + +.. code-block:: + + 0.500000 0.010818010 + 0.600000 0.013986716 + 0.700000 0.016119093 + 0.800000 0.017039022 + 0.900000 0.017084666 + ... skipped ... + 5.600000 0.000728539 + 5.700000 0.000530758 + 5.800000 0.000412908 + 5.900000 0.000341740 + 6.000000 0.000277553 + +The first column is the viewing angle, and the second column is the normalized 00-peak diffraction intensity data +written in ``surf-bulkP.s`` with a convolution of half-width 0.5. diff --git a/manual/v2.2.0/en/_sources/tutorial/solver_simple.rst.txt b/manual/v2.2.0/en/_sources/tutorial/solver_simple.rst.txt new file mode 100644 index 00000000..3616f210 --- /dev/null +++ b/manual/v2.2.0/en/_sources/tutorial/solver_simple.rst.txt @@ -0,0 +1,90 @@ +Addition of a direct problem solver +===================================== + +Solver for benchmarking, ``analytical`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``py2dmat`` provides an ``analytical`` solver as a direct problem solver that can be used to test search algorithms. + +To use the ``analytical`` solver, set ``name`` to ``"analytical"`` in the ``[solver]`` section of the input file. +You can also use the ``function_name`` parameter to select the benchmark function :math:`f(x)`. + +For example, to use Himmelblau function, make an input file including the following:: + + [solver] + name = "analytical" + function_name = "himmelblau" + +For details of ``analytical`` solver, please check the :doc:`the reference of the analytical solver <../solver/analytical>`. + + +Addition of a direct problem solver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The easiest way to define and analyze a user-defined direct problem solver is to add it to the ``analytical`` solver. +As an example, we will explain the case of adding `the Booth function `_ (the minimum point is :math:`f(1,3) = 0`): + +.. math:: + + f(x,y) = (x+2y-7)^2 + (2x+y-5)^2. + + +To do so, we need to download the source code for ``py2dmat`` and edit the file for ``analytical`` solver. +For instructions on how to download the source code and run ``py2dmat`` from the source code, see :doc:`how to install <../start>`. +``analytical`` solver is defined in the ``src/py2dmat/solver/analytical.py``, so edit it. + +First, define the booth function as follows: + +.. code-block:: python + + def booth(xs: np.ndarray) -> float: + """Booth function + + it has one global minimum f(xs) = 0 at xs = [1,3]. + """ + + if xs.shape[0] != 2: + raise RuntimeError( + f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one" + ) + return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2 + +Next, insert the following code in the if branch of the ``Solver`` class's constructor (``__init__``) +to allow users to choose the ``booth`` function by the ``solver.function_name`` parameter of the input file. + +.. code-block:: python + + elif function_name == "booth": + self.set_function(booth) + +With this modified ``analytical`` solver, you can optimize the Booth function. +For example, to optimize it by the Nelder-Mead method, pass the following input file (``input.toml``) :: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "minsearch" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + initial_list = [0, 0] + + [solver] + name = "analytical" + function_name = "booth" + +to ``src/py2dmat_main.py`` script as follows:: + + $ python3 src/py2dmat_main.py input.toml + + ... skipped ... + + Iterations: 38 + Function evaluations: 75 + Solution: + x1 = 1.0000128043523089 + x2 = 2.9999832920260863 diff --git a/manual/v2.2.0/en/_static/alert_info_32.png b/manual/v2.2.0/en/_static/alert_info_32.png new file mode 100644 index 00000000..ea4d1baf Binary files /dev/null and b/manual/v2.2.0/en/_static/alert_info_32.png differ diff --git a/manual/v2.2.0/en/_static/alert_warning_32.png b/manual/v2.2.0/en/_static/alert_warning_32.png new file mode 100644 index 00000000..a687c3dc Binary files /dev/null and b/manual/v2.2.0/en/_static/alert_warning_32.png differ diff --git a/manual/v2.2.0/en/_static/basic.css b/manual/v2.2.0/en/_static/basic.css new file mode 100644 index 00000000..bdef29d8 --- /dev/null +++ b/manual/v2.2.0/en/_static/basic.css @@ -0,0 +1,925 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 59em; + max-width: 70em; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/manual/v2.2.0/en/_static/bg-page.png b/manual/v2.2.0/en/_static/bg-page.png new file mode 100644 index 00000000..fe0a6dc8 Binary files /dev/null and b/manual/v2.2.0/en/_static/bg-page.png differ diff --git a/manual/v2.2.0/en/_static/bullet_orange.png b/manual/v2.2.0/en/_static/bullet_orange.png new file mode 100644 index 00000000..1cb8097c Binary files /dev/null and b/manual/v2.2.0/en/_static/bullet_orange.png differ diff --git a/manual/v2.2.0/en/_static/doctools.js b/manual/v2.2.0/en/_static/doctools.js new file mode 100644 index 00000000..d06a71d7 --- /dev/null +++ b/manual/v2.2.0/en/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/manual/v2.2.0/en/_static/documentation_options.js b/manual/v2.2.0/en/_static/documentation_options.js new file mode 100644 index 00000000..7d6a5ab9 --- /dev/null +++ b/manual/v2.2.0/en/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '2.2-dev', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/manual/v2.2.0/en/_static/file.png b/manual/v2.2.0/en/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/manual/v2.2.0/en/_static/file.png differ diff --git a/manual/v2.2.0/en/_static/haiku.css b/manual/v2.2.0/en/_static/haiku.css new file mode 100644 index 00000000..6830f3fc --- /dev/null +++ b/manual/v2.2.0/en/_static/haiku.css @@ -0,0 +1,375 @@ +/* + * haiku.css_t + * ~~~~~~~~~~~ + * + * Sphinx stylesheet -- haiku theme. + * + * Adapted from http://haiku-os.org/docs/Haiku-doc.css. + * Original copyright message: + * + * Copyright 2008-2009, Haiku. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Francois Revol + * Stephan Assmus + * Braden Ewing + * Humdinger + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +html { + margin: 0px; + padding: 0px; + background: #FFF url(bg-page.png) top left repeat-x; +} + +body { + line-height: 1.5; + margin: auto; + padding: 0px; + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; + min-width: 59em; + max-width: 70em; + color: #333333; +} + +div.footer { + padding: 8px; + font-size: 11px; + text-align: center; + letter-spacing: 0.5px; +} + +/* link colors and text decoration */ + +a:link { + font-weight: bold; + text-decoration: none; + color: #dc3c01; +} + +a:visited { + font-weight: bold; + text-decoration: none; + color: #551a8b; +} + +a:hover, a:active { + text-decoration: underline; + color: #ff4500; +} + +/* Some headers act as anchors, don't give them a hover effect */ + +h1 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h2 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h3 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h4 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +a.headerlink { + color: #a7ce38; + padding-left: 5px; +} + +a.headerlink:hover { + color: #a7ce38; +} + +/* basic text elements */ + +div.content { + margin-top: 20px; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 50px; + font-size: 0.9em; +} + +/* heading and navigation */ + +div.header { + position: relative; + left: 0px; + top: 0px; + height: 85px; + /* background: #eeeeee; */ + padding: 0 40px; +} +div.header h1 { + font-size: 1.6em; + font-weight: normal; + letter-spacing: 1px; + color: #0c3762; + border: 0; + margin: 0; + padding-top: 15px; +} +div.header h1 a { + font-weight: normal; + color: #0c3762; +} +div.header h2 { + font-size: 1.3em; + font-weight: normal; + letter-spacing: 1px; + text-transform: uppercase; + color: #aaa; + border: 0; + margin-top: -3px; + padding: 0; +} + +div.header img.rightlogo { + float: right; +} + + +div.title { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-bottom: 25px; +} +div.topnav { + /* background: #e0e0e0; */ +} +div.topnav p { + margin-top: 0; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 0px; + text-align: right; + font-size: 0.8em; +} +div.bottomnav { + background: #eeeeee; +} +div.bottomnav p { + margin-right: 40px; + text-align: right; + font-size: 0.8em; +} + +a.uplink { + font-weight: normal; +} + + +/* contents box */ + +table.index { + margin: 0px 0px 30px 30px; + padding: 1px; + border-width: 1px; + border-style: dotted; + border-color: #e0e0e0; +} +table.index tr.heading { + background-color: #e0e0e0; + text-align: center; + font-weight: bold; + font-size: 1.1em; +} +table.index tr.index { + background-color: #eeeeee; +} +table.index td { + padding: 5px 20px; +} + +table.index a:link, table.index a:visited { + font-weight: normal; + text-decoration: none; + color: #dc3c01; +} +table.index a:hover, table.index a:active { + text-decoration: underline; + color: #ff4500; +} + + +/* Haiku User Guide styles and layout */ + +/* Rounded corner boxes */ +/* Common declarations */ +div.admonition { + -webkit-border-radius: 10px; + -khtml-border-radius: 10px; + -moz-border-radius: 10px; + border-radius: 10px; + border-style: dotted; + border-width: thin; + border-color: #dcdcdc; + padding: 10px 15px 10px 15px; + margin-bottom: 15px; + margin-top: 15px; +} +div.note { + padding: 10px 15px 10px 80px; + background: #e4ffde url(alert_info_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.warning { + padding: 10px 15px 10px 80px; + background: #fffbc6 url(alert_warning_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.seealso { + background: #e4ffde; +} + +/* More layout and styles */ +h1 { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h2 { + font-size: 1.2em; + font-weight: normal; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h3 { + font-size: 1.1em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +h4 { + font-size: 1.0em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +p { + text-align: justify; +} + +p.last { + margin-bottom: 0; +} + +ol { + padding-left: 20px; +} + +ul { + padding-left: 5px; + margin-top: 3px; +} + +li { + line-height: 1.3; +} + +div.content ul > li { + -moz-background-clip:border; + -moz-background-inline-policy:continuous; + -moz-background-origin:padding; + background: transparent url(bullet_orange.png) no-repeat scroll left 0.45em; + list-style-image: none; + list-style-type: none; + padding: 0 0 0 1.666em; + margin-bottom: 3px; +} + +td { + vertical-align: top; +} + +code { + background-color: #e2e2e2; + font-size: 1.0em; + font-family: monospace; +} + +pre { + border-color: #0c3762; + border-style: dotted; + border-width: thin; + margin: 0 0 12px 0; + padding: 0.8em; +} + +hr { + border-top: 1px solid #ccc; + border-bottom: 0; + border-right: 0; + border-left: 0; + margin-bottom: 10px; + margin-top: 20px; +} + +/* printer only pretty stuff */ +@media print { + .noprint { + display: none; + } + /* for acronyms we want their definitions inlined at print time */ + acronym[title]:after { + font-size: small; + content: " (" attr(title) ")"; + font-style: italic; + } + /* and not have mozilla dotted underline */ + acronym { + border: none; + } + div.topnav, div.bottomnav, div.header, table.index { + display: none; + } + div.content { + margin: 0px; + padding: 0px; + } + html { + background: #FFF; + } +} + +.viewcode-back { + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; + margin: -1px -10px; + padding: 0 12px; +} + +/* math display */ +div.math p { + text-align: center; +} \ No newline at end of file diff --git a/manual/v2.2.0/en/_static/language_data.js b/manual/v2.2.0/en/_static/language_data.js new file mode 100644 index 00000000..250f5665 --- /dev/null +++ b/manual/v2.2.0/en/_static/language_data.js @@ -0,0 +1,199 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, is available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/manual/v2.2.0/en/_static/minus.png b/manual/v2.2.0/en/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/manual/v2.2.0/en/_static/minus.png differ diff --git a/manual/v2.2.0/en/_static/plus.png b/manual/v2.2.0/en/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/manual/v2.2.0/en/_static/plus.png differ diff --git a/manual/v2.2.0/en/_static/pygments.css b/manual/v2.2.0/en/_static/pygments.css new file mode 100644 index 00000000..0d49244e --- /dev/null +++ b/manual/v2.2.0/en/_static/pygments.css @@ -0,0 +1,75 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #eeffcc; } +.highlight .c { color: #408090; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #333333 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #208050 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #208050 } /* Literal.Number.Bin */ +.highlight .mf { color: #208050 } /* Literal.Number.Float */ +.highlight .mh { color: #208050 } /* Literal.Number.Hex */ +.highlight .mi { color: #208050 } /* Literal.Number.Integer */ +.highlight .mo { color: #208050 } /* Literal.Number.Oct */ +.highlight .sa { color: #4070a0 } /* Literal.String.Affix */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #06287e } /* Name.Function.Magic */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ +.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/manual/v2.2.0/en/_static/searchtools.js b/manual/v2.2.0/en/_static/searchtools.js new file mode 100644 index 00000000..7918c3fa --- /dev/null +++ b/manual/v2.2.0/en/_static/searchtools.js @@ -0,0 +1,574 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + `Search finished, found ${resultCount} page(s) matching the search query.` + ); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent !== undefined) return docContent.textContent; + console.warn( + "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + /** + * execute search (requires search index to be loaded) + */ + query: (query) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + // array of [docname, title, anchor, descr, score, filename] + let results = []; + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + let score = Math.round(100 * queryLower.length / title.length) + results.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score, + filenames[file], + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id] of foundEntries) { + let score = Math.round(100 * queryLower.length / entry.length) + results.push([ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + ]); + } + } + } + + // lookup as object + objectTerms.forEach((term) => + results.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + results.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item))); + + // now sort the results by score (in opposite order of appearance, since the + // display function below uses pop() to retrieve items) and then + // alphabetically + results.sort((a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; + }); + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + results = results.reverse(); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord) && !terms[word]) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord) && !titleTerms[word]) + arr.push({ files: titleTerms[word], score: Scorer.partialTitle }); + }); + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1) + fileMap.get(file).push(word); + else fileMap.set(file, [word]); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords) => { + const text = Search.htmlToText(htmlText); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/manual/v2.2.0/en/_static/sphinx_highlight.js b/manual/v2.2.0/en/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/manual/v2.2.0/en/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/manual/v2.2.0/en/acknowledgement.html b/manual/v2.2.0/en/acknowledgement.html new file mode 100644 index 00000000..4e65f8dc --- /dev/null +++ b/manual/v2.2.0/en/acknowledgement.html @@ -0,0 +1,65 @@ + + + + + + + + Acknowledgements — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

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 +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).

+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/algorithm/bayes.html b/manual/v2.2.0/en/algorithm/bayes.html new file mode 100644 index 00000000..2aba8393 --- /dev/null +++ b/manual/v2.2.0/en/algorithm/bayes.html @@ -0,0 +1,186 @@ + + + + + + + + Bayse optimization bayes — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Bayse optimization bayes

+

bayes is an Algorithm that uses Bayesian optimization to perform parameter search. +The implementation is based on PHYSBO.

+
+

Preparation

+

You will need to install PHYSBO beforehand.:

+
python3 -m pip install physbo
+
+
+

If mpi4py is installed, MPI parallel computing is possible.

+
+
+

Input parameters

+
+

[algorithm.param] section

+

In this section, the search parameter space is defined.

+

If mesh_path is defined, it will be read from a mesh file. +In a mesh file, one line gives one point in the parameter space, +the first column is the data number, and the second and subsequent columns are the coordinates of each dimension.

+

If mesh_path is not defined, min_list, max_list, and num_list are used to create an evenly spaced grid for each parameter.

+
    +

  • mesh_path

    +

    Format: String

    +

    Description: The path to a reference file that contains information about the mesh data.

    +
    • +

  • min_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: The minimum value the parameter can take.

    +
    • +

  • max_list

    +

    Format: List of float.The length should match the value of dimension.

    +

    Description: The maximum value the parameter can take.

    +
    • +

  • num_list

    +

    Format: List of integer. The length should match the value of dimension.

    +

    Description: The number of grids the parametar can take at each dimension.

    +
    • +
+
+
+

[algorithm.bayes] section

+

The hyper parameters are defined.

+
    +

  • random_max_num_probes

    +

    Format: Integer (default: 20)

    +

    Description: Number of random samples to be taken before Bayesian optimization (random sampling is needed if parameters and scores are not available at the beginning).

    +
    • +

  • bayes_max_num_probes

    +

    Format: Integer (default: 40)

    +

    Description: Number of times to perform Bayesian optimization.

    +
    • +

  • score

    +

    Format: String (default: TS )

    +

    Description: Parameter to specify the score function. +EI (expected improvement), PI (probability of improvement), and TS (Thompson sampling) can be chosen.

    +
    • +

  • interval

    +

    Format: Integer (default: 5)

    +

    Description: The hyperparameters are learned at each specified interval. If a negative value is specified, no hyperparameter learning will be performed. +If a value of 0 is specified, hyperparameter learning will be performed only in the first step.

    +
    • +

  • num_rand_basis

    +

    Format: Integer (default: 5000)

    +

    Description: Number of basis functions; if 0 is specified, the normal Gaussian process is performed without using the Bayesian linear model.

    +
    • +
+
+
+
+

Reference file

+
+

Mesh definition file

+

Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables defined in string_list in the [solver.param] section.

+

Below, a sample file is shown.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

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.

+
#step z1 z2 R-factor z1_action z2_action R-factor_action
+0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885
+1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033
+2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189
+3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794
+...
+
+
+
+
+
+

Algorithm Description

+

Bayesian optimization (BO) is an optimization algorithm that uses machine learning as an aid, and is particularly powerful when it takes a long time to evaluate the objective function.

+

In BO, the objective function \(f(\vec{x})\) is approximated by a model function (often a Gaussian process) \(g(\vec{x})\) that is quick to evaluate and easy to optimize. +The \(g\) is trained to reproduce well the value of the objective function \(\{\vec{x}_i\}_{i=1}^N\) at some suitably predetermined points (training data set) \(\{f(\vec{x}_i)\}_{i=1}^N\).

+

At each point in the parameter space, we propose the following candidate points for computation \(\vec{x}_{N+1}\), where the expected value of the trained \(g(\vec{x})\) value and the “score” (acquition function) obtained from the error are optimal. +The training is done by evaluating \(f(\vec{x}_{N+1})\), adding it to the training dataset, and retraining \(g\). +After repeating these searches, the best value of the objective function as the optimal solution will be returned.

+

A point that gives a better expected value with a smaller error is likely to be the correct answer, +but it does not contribute much to improving the accuracy of the model function because it is considered to already have enough information. +On the other hand, a point with a large error may not be the correct answer, +but it is a place with little information and is considered to be beneficial for updating the model function. +Selecting the former is called “exploition,” while selecting the latter is called “exploration,” and it is important to balance both. +The definition of “score” defines how to choose between them.

+

In 2DMAT, we use PHYSBO as a library for Bayesian optimization. +PHYSBO, like mapper_mpi, computes a “score” for a predetermined set of candidate points, and proposes an optimal solution. +MPI parallel execution is possible by dividing the set of candidate points. +In addition, we use a kernel that allows us to evaluate the model function and thus calculate the “score” with a linear amount of computation with respect to the number of training data points \(N\). +In PHYSBO, “expected improvement (EI)”, “probability of improvement (PI)”, and “Thompson sampling (TS)” are available as “score” functions.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/algorithm/exchange.html b/manual/v2.2.0/en/algorithm/exchange.html new file mode 100644 index 00000000..9a8c1c55 --- /dev/null +++ b/manual/v2.2.0/en/algorithm/exchange.html @@ -0,0 +1,346 @@ + + + + + + + + Replica exchange Monte Carlo exchange — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Replica exchange Monte Carlo exchange

+

exchange explores the parameter space by using the replica exchange Monte Carlo (RXMC) method.

+
+

Preparation

+

mpi4py should be installed.

+
python3 -m pip install mpi4py
+
+
+
+
+

Input parameters

+

This has two subsections algorithm.param and algorithm.exchange .

+
+

[algorithm.param]

+

This defines a space to be explored. +When mesh_path key is defined the discrete space is used. +Otherwise, continuous space is used.

+
    +

  • Continuous space

    +
      +

    • initial_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      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. +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.

      +
      +
      +
      • +

    • 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.

      +
      +
      +
      • +
    +
    • +

  • Discrete space

    +
      +

    • mesh_path

      +

      Format: string

      +

      Description: Path to the mesh definition file.

      +
      • +

    • neighborlist_path

      +

      Format: string

      +

      Description: Path to the neighborhood-list file.

      +
      • +
    +
    • +
+
+
+

[algorithm.exchange]

+
    +

  • numsteps

    +

    Format: Integer

    +

    Description: The number of Monte Carlo steps.

    +
    • +

  • numsteps_exchange

    +

    Format: Integer

    +

    Description: The number of interval Monte Carlo steps between replica exchange.

    +
    • +

  • Tmin

    +

    Format: Float

    +

    Description: The minimum value of the “temperature” (\(T\)).

    +
    • +

  • Tmax

    +

    Format: Float

    +

    Description: The maximum value of the “temperature” (\(T\)).

    +
    • +

  • bmin

    +

    Format: Float

    +

    Description: The minimum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • bmax

    +

    Format: Float

    +

    Description: The maximum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • Tlogspace

    +

    Format: Boolean (default: true)

    +

    Description: Whether to assign “temperature” to replicas equally spaced in the logarithmic space or not.

    +
    • +

  • nreplica_per_proc

    +

    Format: Integer (default: 1)

    +

    Description: The number of replicas in a MPI process.

    +
    • +
+
+
+
+

Reference file

+
+

Mesh definition file

+

Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this “algorithm”.

+

Below, a sample file is shown.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

Neighborhood-list file

+

Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define “neighborhoods” for each point \(i\), which are points that a walker can move from \(i\) +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point \(i\) is specified by the first column, +and the indices of final points \(j\) are specified by the second and successive columns.

+

An utility tool, py2dmat_neighborlist is available for generating a neighborhood-list file from a mesh file. For details, please see Related Tools.

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

Output files

+
+

RANK/trial.txt

+

This file stores the suggested parameters and the corresponding value returned from the solver for each replica. +The first column is the index of the MC step. +The second column is the index of the walker in the process. +The third column is the temperature of the replica. +The fourth column is the value of the solver. +The remaining columns are the coordinates.

+

Example:

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861
+2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

RANK/result.txt

+

This file stores the sampled parameters and the corresponding value returned from the solver for each replica. +This has the same format as trial.txt.

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

best_result.txt

+

The optimal value of the solver and the corresponding parameter among the all samples.

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

result_T#.txt

+

This file stores samples for each temperature ( # is replaced with the index of temperature ). +The first column is the index of the MC step. +The second column is the index of the walker. +The third column is the value of the solver. +The remaining columns are the coordinates.

+
# T = 1.0
+0 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+1 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+2 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+3 15 28.98676409223712 3.7442621319489637 -3.868754990884034
+
+
+
+

Algorithm

+
+
+
+
+

Markov chain Monte Carlo

+

The Markov chain Monte Carlo (MCMC) sampling explores the parameter space by moving walkers \(\vec{x}\) stochastically according to the weight function \(W(\vec{x})\). +For the weight function, the Boltzmann factor \(W(\vec{x}) = e^{-f(\vec{x})/T}\) is generally adopted, where \(T>0\) is the “temperature.” +It is impossible in the many cases, unfortunately, to sample walkers according to \(W\) directly. +Insteadly, the MCMC method moves walkers slightly and generates a time series \(\{\vec{x}_t\}\) such that the distribution of the walkers obeys \(W\) . +Let us call the transision probability from \(\vec{x}\) to \(\vec{x}'\) as \(p(\vec{x}' | \vec{x})\). +When \(p\) is determined by the following condition (“the balance condition”)

+
+\[W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x}),\]
+

the distribution of the generated time series \(\{\vec{x}_t\}\) will converges to \(W(\vec{x})\) [1]. +Practically, the stronger condition (“the detailed balance condition”)

+
+\[p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x})\]
+

is usually imposed. +The detailed balance condition returns to the balance condition by taking the summation of \(\vec{x}\).

+

2DMAT adopts the Metropolis-Hasting (MH) method for solving the detailed balance condition. +The MH method splits the transition process into the suggestion process and the acceptance process.

+
    +

  1. Generate a candidate \(\vec{x}\) with the suggestion probability \(P(\vec{x} | \vec{x}_t)\).

    +
      +

    • As \(P\), use a simple distribution such as the normal distribution with centered at x.

      • +
    +
    2. +

  2. Accept the candidate \(\vec{x}\) with the acceptance probability \(Q(\vec{x} | \vec{x}_t)\).

    +
      +

    • If accepted, let \(\vec{x}_{t+1}\) be vec{x}.

      • +

    • Otherwise, let \(\vec{x}_{t+1}\) be vec{x}_t.

      • +
    +
    3. +
+

The whole transision probability is the product of these two ones, \(p(\vec{x} | \vec{x_t}) = P(\vec{x} | \vec{x}_t) Q(\vec{x} | \vec{x}_t)\). +The acceptance probability \(Q(\vec{x} | \vec{x}_t)\) is defined as

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right].\]
+

It is easy to verify that the detailed balance condition is satisfied by substituting it into the detailed balance condition equation.

+

When adopting the Boltzmann factor for the weight and a symmetry distribution +\(P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})\) for the suggestion probability, +the acceptance probability \(Q\) will be the following simple form:

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right].\]
+

By saying \(\Delta f = f(\vec{x}) - f(\vec{x}_t)\) and using the fact \(Q=1\) for \(\Delta f \le 0\), +the procedure of MCMC with the MH algorithm is the following:

+
    +

  1. Choose a candidate from near the current position and calculate \(f\) and \(\Delta f\).

    2. +

  2. If \(\Delta f \le 0\), that is, the walker is descending, accept it.

    3. +

  3. Otherwise, accept it with the probability \(Q=e^{-\Delta f/T}\).

    4. +

  4. Repeat 1-3.

    5. +
+

The solution is given as the point giving the minimum value of \(f(\vec{x})\). +The third process of the above procedure endures that walkers can climb over the hill with a height of \(\Delta f \sim T\), the MCMC sampling can escape from local minima.

+
+
+

Replica exchange Monte Carlo

+

The “temperature” \(T\) is one of the most important hyper parameters in the MCMC sampling. +The MCMC sampling can climb over the hill with a height of \(T\) but cannot easily escape from the deeper valley than \(T\). +It is why we should increase the temperature in order to avoid stuck to local minima. +On the other hand, since walkers cannot see the smaller valleys than \(T\), the precision of the obtained result \(\min f(\vec{x})\) becomes about \(T\), and it is necessary to decrease the temperature in order to achieve more precise result. +This dilemma leads us that we should tune the temperature carefully.

+

One of the ways to overcome this problem is to update temperature too. +For example, simulated annealing decreases temperature as the iteration goes. +Another algorithm, simulated tempering, treats temperature as another parameter to be sampled, not a fixed hyper parameter, +and update temperature after some iterations according to the (detailed) balance condition. +Simulated tempering studies the details of a valley by cooling and escapes from a valley by heating. +Replica exchange Monte Carlo (RXMC), also known as parallel tempering, is a parallelized version of the simulated tempering. +In this algorithm, several copies of a system with different temperature, called as replicas, will be simulated in parallel. +Then, with some interval of steps, each replica exchanges temperature with another one according to the (detailed) balance condition. +As the simulated tempering does, RXMC can observe the details of a valley and escape from it by cooling and heating. +Moreover, because each temperature is assigned to just one replica, the temperature distribution will not be biased. +Using more replicas narrows the temperature interval, and increases the acceptance ratio of the temperature exchange. +This is why this algorithm suits for the massively parallel calculation.

+

It is recommended that users perform minsearch optimization starting from the result of exchange, because the RXMC result has uncertainty due to temperature.

+

footnote

+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/algorithm/index.html b/manual/v2.2.0/en/algorithm/index.html new file mode 100644 index 00000000..3f0d2e27 --- /dev/null +++ b/manual/v2.2.0/en/algorithm/index.html @@ -0,0 +1,72 @@ + + + + + + + + Search algorithms — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Search algorithms

+

py2dmat searches the parameter space \(\mathbf{X}\ni x\) by using the search algorithm Algorithm and the result of Solver \(f(x)\). +In this section, the search algorithms implemented in py2dmat are described.

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/algorithm/mapper_mpi.html b/manual/v2.2.0/en/algorithm/mapper_mpi.html new file mode 100644 index 00000000..418f2da8 --- /dev/null +++ b/manual/v2.2.0/en/algorithm/mapper_mpi.html @@ -0,0 +1,142 @@ + + + + + + + + Direct parallel search mapper — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Direct parallel search mapper

+

mapper_mpi is an algorithm to search for the minimum value by computing \(f(x)\) on all the candidate points in the parameter space prepared in advance. +In the case of MPI execution, the set of candidate points is divided into equal parts and automatically assigned to each process to perform trivial parallel computation.

+
+

Preparation

+

For MPI parallelism, you need to install mpi4py.:

+
python3 -m pip install mpi4py
+
+
+
+
+

Input parameters

+
+

[param] section

+

In this section, the search parameter space is defined.

+

If mesh_path is defined, it is read from a mesh file. +In the mesh file, one line defines one point in the parameter space, the first column is the data number, and the second and subsequent columns are the coordinates of each dimension.

+

If mesh_path is not defined, min_list, max_list, and num_list are used to create an evenly spaced grid for each parameter.

+
    +

  • mesh_path

    +

    Format: String

    +

    Description: Path to the mesh definition file.

    +
    • +

  • min_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: The minimum value the parameter can take.

    +
    • +

  • max_list

    +

    Format: List of float.The length should match the value of dimension.

    +

    Description: The maximum value the parameter can take.

    +
    • +

  • num_list

    +

    Format: List of integer. The length should match the value of dimension.

    +

    Description: The number of grids the parametar can take at each dimension.

    +
    • +
+
+
+
+

Refernce file

+
+

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.

+

A sample file for two dimensions is shown below.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

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.

+

Below, output example is shown.

+
6.000000 6.000000 0.047852
+6.000000 5.750000 0.055011
+6.000000 5.500000 0.053190
+6.000000 5.250000 0.038905
+6.000000 5.000000 0.047674
+6.000000 4.750000 0.065919
+6.000000 4.500000 0.053675
+6.000000 4.250000 0.061261
+6.000000 4.000000 0.069351
+6.000000 3.750000 0.071868
+...
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/algorithm/minsearch.html b/manual/v2.2.0/en/algorithm/minsearch.html new file mode 100644 index 00000000..384e409f --- /dev/null +++ b/manual/v2.2.0/en/algorithm/minsearch.html @@ -0,0 +1,173 @@ + + + + + + + + Nelder-Mead method minsearch — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Nelder-Mead method minsearch

+

When minsearch is selcted, the optimization by the Nelder-Mead method (a.k.a. downhill simplex method) will be done. In the Nelder-Mead method, the dimension of the parameter space is \(D\), and the optimal solution is searched by systematically moving pairs of \(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.

+

In 2DMAT, the Scipy’s function scipy.optimize.minimize(method="Nelder-Mead") is used. +For details, see the official document .

+
+

Preparation

+

You will need to install scipy .:

+
python3 -m pip install scipy
+
+
+
+
+

Input parameters

+

It has subsections param and minimize.

+
+

[param] section

+
    +

  • initial_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: Initial value of the parameter. If not defined, it will be initialized uniformly and randomly.

    +
    • +

  • unit_list

    +

    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.

    +
    +
    +
      +

    • 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 Nelson-Mead method, +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 Nelson-Mead method, +the solver is not evaluated and the value is considered infinite.

      +
      +
      +
      • +
    +
    • +
+
+
+

[minimize] section

+

Set the hyperparameters for the Nelder-Mead method. +See the documentation of scipy.optimize.minimize for details.

+
    +

  • initial_scale_list

    +

    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. +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.

    +
    • +

  • xatol

    +

    Format: Float (default: 1e-4)

    +

    Description: Parameters used to determine convergence of the Nelder-Mead method.

    +
    • +

  • fatol

    +

    Format: Float (default: 1e-4)

    +

    Description: Parameters used to determine convergence of the Nelder-Mead method.

    +
    • +

  • maxiter

    +

    Format: Integer (default: 10000)

    +

    Description: Maximum number of iterations for the Nelder-Mead method.

    +
    • +

  • maxfev

    +

    Format: Integer (default: 100000)

    +

    Description: Maximum number of times to evaluate the objective function.

    +
    • +
+
+
+
+

Output files

+
+

SimplexData.txt

+

Outputs information about the process of finding the minimum value. +The first line is a header, the second and subsequent lines are step, +the values of variables defined in string_list in the [solver] - [param] sections of the input file, +and finally the value of the function.

+

The following is an example of the output.

+
#step z1 z2 z3 R-factor
+0 5.25 4.25 3.5 0.015199251773721183
+1 5.25 4.25 3.5 0.015199251773721183
+2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375
+3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261
+4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+
+
+
+
+

res.txt

+

The value of the final objective function and the value of the parameters at that time are described. +The objective function is listed first, followed by the values of the variables defined in string_list in the [solver] - [param] sections of the input file, in that order.

+

The following is an example of the output.

+
fx = 7.382680568652868e-06
+z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/algorithm/pamc.html b/manual/v2.2.0/en/algorithm/pamc.html new file mode 100644 index 00000000..c0661b34 --- /dev/null +++ b/manual/v2.2.0/en/algorithm/pamc.html @@ -0,0 +1,429 @@ + + + + + + + + Population Annealing Monte Carlo pamc — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Population Annealing Monte Carlo pamc

+

pamc explores the parameter space by using the Population Annealing Monte Carlo (PAMC) method.

+
+

Preparation

+

mpi4py should be installed for the MPI parallelization

+
python3 -m pip install mpi4py
+
+
+
+
+

Input parameters

+

This has two subsections algorithm.param and algorithm.pamc .

+
+

[algorithm.param]

+

This defines a space to be explored. +When mesh_path key is defined the discrete space is used. +Otherwise, continuous space is used.

+
    +

  • Continuous space

    +
      +

    • initial_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      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. +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.

      +
      +
      +
      • +

    • 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.

      +
      +
      +
      • +
    +
    • +

  • Discrete space

    +
      +

    • mesh_path

      +

      Format: string

      +

      Description: Path to the mesh definition file.

      +
      • +

    • neighborlist_path

      +

      Format: string

      +

      Description: Path to the neighborhood-list file.

      +
      • +
    +
    • +
+
+
+

[algorithm.pamc]

+
    +

  • numsteps

    +

    Format: Integer

    +

    Description: The number of Monte Carlo steps.

    +
    • +

  • numsteps_annealing

    +

    Format: Integer

    +

    Description: The number of interval Monte Carlo steps between lowering “temperature”.

    +
    • +

  • numT

    +

    Format: Integer

    +

    Description: The number of “temperature” points.

    +
    • +

  • Tmin

    +

    Format: Float

    +

    Description: The minimum value of the “temperature” (\(T\)).

    +
    • +

  • Tmax

    +

    Format: Float

    +

    Description: The maximum value of the “temperature” (\(T\)).

    +
    • +

  • bmin

    +

    Format: Float

    +

    Description: The minimum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • bmax

    +

    Format: Float

    +

    Description: The maximum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • Tlogspace

    +

    Format: Boolean (default: true)

    +

    Description: Whether to assign “temperature” to replicas equally spaced in the logarithmic space or not.

    +
    • +

  • nreplica_per_proc

    +

    Format: Integer (default: 1)

    +

    Description: The number of replicas in a MPI process.

    +
    • +

  • resampling_interval

    +

    Format: Integer (default: 1)

    +

    Description: The number of annealing processes between resampling of the replicas.

    +
    • +

  • fix_num_replicas

    +

    Format: Boolean (default: true)

    +

    Description: Whether to fix the number of replicas or not on resampling.

    +
    • +
+
+

About the number of steps

+

Specify just two of numstep, numsteps_annealing, and numT. +The value of the remaining one will be determined automatically.

+
+
+
+
+

Reference file

+
+

Mesh definition file

+

Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this “algorithm”.

+

Below, a sample file is shown.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

Neighborhood-list file

+

Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define “neighborhoods” for each point \(i\), which are points that a walker can move from \(i\) +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point \(i\) is specified by the first column, +and the indices of final points \(j\) are specified by the second and successive columns.

+

An utility tool, py2dmat_neighborlist is available for generating a neighborhood-list file from a mesh file. For details, please see Related Tools.

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

Output files

+
+

RANK/trial_T#.txt

+

This file stores the suggested parameters and the corresponding value returned from the solver for each temperature point (specified by #). +The first column (step) is the index of the MC step. +The second column (walker) is the index of the walker in the process. +The third column (beta) is the inverse temperature of the replica. +The fourth column (fx) is the value of the solver. +The fifth - (4+dimension)-th columns are the coordinates. +The last two columns (weight and ancestor) are the Neal-Jarzynsky weight and the grand-ancestor of the replica.

+

Example:

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/trial.txt

+

This is a combination of all the trial_T#.txt in one.

+
+
+

RANK/result_T#.txt

+

This file stores the sampled parameters and the corresponding value returned from the solver for each replica and each temperature. +This has the same format as trial.txt.

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/result.txt

+

This is a combination of all the result_T#.txt in one.

+
+
+

best_result.txt

+

The optimal value of the solver and the corresponding parameter among the all samples.

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

fx.txt

+

This file stores statistical metrics over the all replicas for each temperature. +The first column is inverse temperature. +The second and third column are the expectation value and the standard error of the solver’s output (\(f(x)\)), respectively. +The fourth column is the number of replicas. +The fifth column is the logarithmic of the ratio between the normalization factors (partition functions)

+
+\[\log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)},\]
+

where \(\beta_0\) is the minimum value of \(\beta\) used in the calculation. +The sixth column is the acceptance ratio of MC updates.

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804
+0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058
+0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004
+...
+
+
+
+
+
+

Algorithm

+
+

Goal

+

When the weight of the configuration \(x\) under some parameter \(\beta_i\) is given as \(f_i(x)\) +(e.g., the Bolzmann factor \(f_i(x) = \exp[-\beta_i E(x)]\) ), +the expectation value of \(A\) is defined as

+
+\[\langle A\rangle_i += \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} += \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) += \int \mathrm{d}xA(x)\tilde{f}_i(x),\]
+

where \(Z = \int \mathrm{d} x f_i(x)\) is the normalization factor (partition function) +and \(\tilde{f}(x) = f(x)/Z\) is the probability of \(x\).

+

Our goal is to numerically calculate the expectation value for each \(\beta_i\) and the (ratio of) the normalization factor.

+
+
+

Annealed Importance Sampling (AIS) [1]

+

First, we introduce a series of configurations \(\{x_i\}\) obeying the following joint probability

+
+\[\tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0),\]
+

with

+
+\[\tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)},\]
+

where \(T_i(x, x')\) is a transition probability from \(x\) to \(x'\) under \(\beta_i\) +holding the balance condition,

+
+\[\int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x').\]
+

It turns out that \(\tilde{f}_n(x_n)\) is the marginal distribution of \(\tilde{f}(x_0, x_1, \dots, x_n)\), that is,

+
+\[\tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n),\]
+

from

+
+\[\int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) += \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) += 1.\]
+

Consequently, +\(\langle A \rangle_n\) is represented by using the extended configuration \(\{x_i\}\) as

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&\equiv +\int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n). +\end{split}\end{split}\]
+

Unfortunately, it is difficult to generate directly a series of configurations \(\{x_i\}\) +following the distribution \(\tilde{f}(x_0, x_1, \dots, x_n)\). +Then, instead of \(\tilde{f}(x_0, x_1, \dots, x_n)\), we consider \(\{x_i\}\) obeying the joint distribution

+
+\[\tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n),\]
+

by using the following the following scheme:

+
    +

  1. Generete \(x_0\) from the initial distribution \(\tilde{f}_0(x)\)

    2. +

  2. Generate \(x_{i+1}\) from \(x_i\) through \(T_{i+1}(x_i, x_{i+1})\)

    3. +
+

By using the reweighting method (or importance sampling method), +\(\langle A \rangle_n\) is rewritten as

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ +&= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} +\end{split}.\end{split}\]
+

Because the ratio between \(\tilde{f}\) and \(\tilde{g}\) is

+
+\[\begin{split}\begin{split} +\frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\frac{f_n(x_n)}{f_0(x_0)} +\prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ +&\equiv +\frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n), +\end{split}\end{split}\]
+

the form of the expectation value will be

+
+\[\langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} += \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n}.\]
+

Finally, the ratio between the normalization factors \(Z_n/Z_0\) can be evaluated as

+
+\[\frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n},\]
+

and therefore the expectation value of \(A\) can be evaluated as a weighted arithmetic mean:

+
+\[\langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}}.\]
+

This weight \(w_n\) is called as the Neal-Jarzynski weight.

+
+
+

population annealing (PA) [2]

+

Although the AIS method can estimate the expectation values of \(A\) for each parameter \(\beta\) as the form of weighted arithmetic mean, +the variance of weights \(w\) is generally large and then the accuracy of the result gets worse. +In order to overcome this problem, the population annealing Monte Carlo (PAMC) method resamples all the replicas according to the probability +\(p^{(k)} = w^{(k)} / \sum_k w^{(k)}\) at some periods and resets all the weights to unity.

+

The following pseudo code describes the scheme of PAMC:

+
for k in range(K):
+    w[0, k] = 1.0
+    x[0, k] = draw_from(β[0])
+for i in range(1, N):
+    for k in range(K):
+        w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) )
+    if i % interval == 0:
+        x[i, :] = resample(x[i, :], w[i, :])
+        w[i, :] = 1.0
+    for k in range(K):
+        x[i, k] = transfer(x[i-1, k], β[i])
+    a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:])
+
+
+

There are two resampling methods: one with a fixed number of replicas[2] and one without[3].

+
+
+

References

+

[1] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[2] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[3] J. Machta, PRE 82, 026704 (2010).

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/contact.html b/manual/v2.2.0/en/contact.html new file mode 100644 index 00000000..65a6fbc2 --- /dev/null +++ b/manual/v2.2.0/en/contact.html @@ -0,0 +1,71 @@ + + + + + + + + Contact — 2DMAT 2.2-dev documentation + + + + + + + + + + + +
+ + +
+

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 you are using.

      2. +

    2. If there are problems for installation, please inform us about your operating system and the compiler.

      3. +

    3. If a problem occurs during execution, enter the input file used for execution and its output.

      4. +
    +

    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 @)

    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/customize/algorithm.html b/manual/v2.2.0/en/customize/algorithm.html new file mode 100644 index 00000000..87f5d38d --- /dev/null +++ b/manual/v2.2.0/en/customize/algorithm.html @@ -0,0 +1,262 @@ + + + + + + + + Algorithm — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Algorithm

+

Algorithm is defined as a subclass of py2dmat.algorithm.AlgorithmBase

+
import py2dmat
+
+class Algorithm(py2dmat.algorithm.AlgorithmBase):
+    ...
+
+
+
+

AlgorithmBase

+

AlgorithmBase class offers the following methods

+
- ``__init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)``
+
+
+
+
    +

  • Reads the common parameters from info and sets the following instance variables:

    +
    +
      +

    • self.mpicomm: Optional[MPI.Comm] : MPI.COMM_WORLD

      +
      +
        +

      • When import mpi4py fails, this will be None.

        • +
      +
      +
      • +

    • self.mpisize: int : the number of MPI processes

      +
      +
        +

      • When import mpi4py fails, this will be 1.

        • +
      +
      +
      • +

    • self.mpirank: int : the rank of this process

      +
      +
        +

      • When import mpi4py fails, this will be 0.

        • +
      +
      +
      • +

    • self.rng: np.random.Generator : pseudo random number generator

      +
      +
      +
      +
      • +

    • self.dimension: int : the dimension of the parameter space

      • +

    • self.label_list: List[str] : the name of each axes of the parameter space

      • +

    • self.root_dir: pathlib.Path : root directory

      +
      +
        +

      • info.base["root_dir"]

        • +
      +
      +
      • +

    • self.output_dir: pathlib.Path : output directory

      +
      +
        +

      • info.base["root_dir"]

        • +
      +
      +
      • +

    • self.proc_dir: pathlib.Path : working directory of each process

      +
      +
        +

      • self.output_dir / str(self.mpirank)

        • +

      • Directory will be made automatically

        • +

      • Each process performs an optimization algorithm in this directory

        • +
      +
      +
      • +

    • self.timer: dict[str, dict] : dictionary storing elapsed time

      +
      +
        +

      • Three empty dictinaries, "prepare", "run", and "post" will be defined

        • +
      +
      +
      • +
    +
    +
    • +
+
+
    +

  • prepare(self) -> None

    +
    +
      +

    • Prepares the algorithm

      • +

    • It should be called before self.run() is called

      • +

    • It calls self._prepare()

      • +
    +
    +
    • +

  • run(self) -> None

    +
    +
      +

    • Performs the algorithm

      • +

    • Enters into self.proc_dir, calls self._run(), and returns to the original directory.

      • +
    +
    +
    • +

  • post(self) -> None

    +
    +
      +

    • Runs a post process of the algorithm, for example, write the result into files

      • +

    • It should be called after self.run() is called

      • +

    • Enters into self.output_dir, calls self._post(), and returns to the original directory.

      • +
    +
    +
    • +

  • main(self) -> None

    +
    +
      +

    • Calls prepare, run, and post

      • +

    • Measures the elapsed times for calling each function, and write them into file

      • +
    +
    +
    • +

  • _read_param(self, info: py2dmat.Info) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

    +
    +
      +

    • Helper method for initializing defining the continuous parameter space

      • +

    • Reads info.algorithm["param"] and returns the followings:

      +
      +
        +

      • Initial value

        • +

      • Lower bound

        • +

      • Upper bound

        • +

      • Unit

        • +
      +
      +
      • +

    • For details, see [algorithm.param] subsection for minsearch

      • +
    +
    +
    • +

  • _meshgrid(self, info: py2dmat.Info, split: bool = False) -> Tuple[np.ndarray, np.ndarray]

    +
    +
      +

    • Helper method for initializing defining the discrete parameter space

      • +

    • Reads info.algorithm["param"] and returns the followings:

      +
      +
        +

      • N points in the D dimensinal space as a NxD matrix

        • +

      • IDs of points as a N dimensional vector

        • +
      +
      +
      • +

    • If split is True, the set of points is scatterred to MPI processes

      • +

    • For details, see [algorithm.param] subsection for mapper

      • +
    +
    +
    • +
+
+
+

Algorithm

+

In Algorithm, the following methods should be defined:

+
    +

  • __init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)

    +
    +
      +

    • Please transfer the arguments to the constructor of the base class:

      +
      +
        +

      • super().__init__(info=info, runner=runner)

        • +
      +
      +
      • +

    • Reads info and sets information

      • +
    +
    +
    • +

  • _prepare(self) -> None

    +
    +
      +

    • Pre process

      • +
    +
    +
    • +

  • _run(self) -> None

    +
    +
      +

    • The algorithm itself

      • +

    • In this method, you can calculate f(x) from a parameter x as the following:

      +
      message = py2dmat.Message(x, step, set)
+fx = self.runner.submit(message)
+
      +
      +
      • +
    +
    +
    • +

  • _post(self) -> None

    +
    +
      +

    • Post process

      • +
    +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/customize/common.html b/manual/v2.2.0/en/customize/common.html new file mode 100644 index 00000000..b35142d3 --- /dev/null +++ b/manual/v2.2.0/en/customize/common.html @@ -0,0 +1,182 @@ + + + + + + + + Commons — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Commons

+
+

py2dmat.Info

+

This class treats the input parameters. +This has the following four instance variables.

+
    +

  • base : dict[str, Any]

    +
    +
      +

    • Parameters for whole program such as the directory where the output will be written.

      • +
    +
    +
    • +

  • solver : dict[str, Any]

    +
    +
      +

    • Parameters for Solver

      • +
    +
    +
    • +

  • algorithm : dict[str, Any]

    +
    +
      +

    • Parameters for Algorithm

      • +
    +
    +
    • +

  • runner : dict[str, Any]

    +
    +
      +

    • Parameters for Runner

      • +
    +
    +
    • +
+

An instance of Info is initialized by passing a dict which has the following four sub dictionaries, base, solver, algorithm, and "runner". +Each value will be set to the corresponding field of Info.

+
    +

  • About base

    +
    +
      +

    • Root directory root_dir

      +
      +
        +

      • The default value is "." (the current directory).

        • +

      • Value of root_dir will be converted to an absolute path.

        • +

      • The leading ~ will be expanded to the user’s home directory.

        • +

      • Specifically, the following code is executed

        +
        p = pathlib.Path(base.get("root_dir", "."))
+base["root_dir"] = p.expanduser().absolute()
+
        +
        +
        • +
      +
      +
      • +

    • Output directory output_dir

      +
      +
        +

      • The default value is ".", that is, the same to root_dir

        • +

      • The leading ~ will be expanded to the user’s home directory.

        • +

      • If a relative path is given, its origin is root_dir.

        • +

      • Specifically, the following code is executed

        +
        p = pathlib.Path(base.get("work_dir", "."))
+p = p.expanduser()
+base["work_dir"] = base["root_dir"] / p
+
        +
        +
        • +
      +
      +
      • +
    +
    +
    • +
+
+
+

py2dmat.Message

+

When Algorithm tries to invoke Solver, an instance of this class is passed from Algorithm to Solver via Runner.

+

This has the following three instance variables.

+
    +

  • x: np.ndarray

    +
    +
      +

    • Coordinates of a point \(x\) to calculate \(f(x)\)

      • +
    +
    +
    • +

  • step: int

    +
    +
      +

    • The index of parameters

      • +

    • For example, the index of steps in exchange and the ID of parameter in mapper.

      • +
    +
    +
    • +

  • set: int

    +
    +
      +

    • Which lap it is

      • +

    • For example, min_search has two laps, the first one is optimization and the second one is recalculation the optimal values for each step.

      • +
    +
    +
    • +
+
+
+

py2dmat.Runner

+

Runner connects Algorithm and Solver. +The constructor of Runner takes solver: Solver, info: Info, and mapping: Callable[[np.ndarray], np.ndarray].

+

submit(self, message: py2dmat.Message) -> float method invokes the solver and returns the result. +To evaluate fx = f(x), use the following code snippet:

+
message = py2dmat.Message(x, step, set)
+fx = runner.submit(message)
+
+
+

submit internally uses mapping for generating a parameter used in Solver, \(y\), from a parameter searched by Algorithm, \(x\), as y = mapping(x). +When mapping is omitted in the constructor (or None is passed), an affine mapping (py2dmat.util.mapping.Affine(A,b)) \(y=Ax+b\) is used as mapping. +The elements of A and b are defined in info. +See Input file for details how/which components of info Runner uses.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/customize/index.html b/manual/v2.2.0/en/customize/index.html new file mode 100644 index 00000000..fad294c4 --- /dev/null +++ b/manual/v2.2.0/en/customize/index.html @@ -0,0 +1,71 @@ + + + + + + + + (For developers) User-defined algorithm and solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

(For developers) User-defined algorithm and solver

+

py2dmat solves the reverse problem by combination of Solver for the direct problem and Algorithm for the optimization problem. +Instead of some Solver and Algorithm which are served by py2dmat, users can define and use their own components. +In this chapter, how to define Solver and Algorithm and to use them will be described.

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/customize/solver.html b/manual/v2.2.0/en/customize/solver.html new file mode 100644 index 00000000..291e5342 --- /dev/null +++ b/manual/v2.2.0/en/customize/solver.html @@ -0,0 +1,160 @@ + + + + + + + + Solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Solver

+

Solver is defined as a subclass of py2dmat.solver.SolverBase

+
import py2dmat
+
+class Solver(py2dmat.solver.SolverBase):
+    ...
+
+
+

The following methods should be defined.

+
    +

  • __init__(self, info: py2dmat.Info)

    +
    +
      +

    • It is required to call the constructor of the base class.

      +
      +
        +

      • super().__init__(info)

        • +
      +
      +
      • +

    • The constructor of SolverBase defines the following instance variables.

      +
      +
        +

      • self.root_dir: pathlib.Path : Root directory

        +
        +
          +

        • use info.base["root_dir"]

          • +
        +
        +
        • +

      • self.output_dir: pathlib.Path : Output directory

        +
        +
          +

        • use info.base["output_dir"]

          • +
        +
        +
        • +

      • self.proc_dir: pathlib.Path : Working directory for each MPI process

        +
        +
          +

        • as self.output_dir / str(mpirank)

          • +
        +
        +
        • +

      • self.work_dir: pathlib.Path : Directory where the solver is invoked

        +
        +
          +

        • same to self.proc_dir

          • +
        +
        +
        • +
      +
      +
      • +

    • Read the input parameter info and save as instance variables.

      • +
    +
    +
    • +

  • prepare(self, message: py2dmat.Message) -> None

    +
    +
      +

    • This is called before the solver starts

      • +

    • message includes an input parameter x, convert it to something to be used by the solver

      +
      +
        +

      • e.g., to generate an input file of the solver

        • +
      +
      +
      • +
    +
    +
    • +

  • run(self, nprocs: int = 1, nthreads: int = 1) -> None

    +
    +
      +

    • Run the solver

      • +

    • Result should be saved to somewhere in order to be read by get_results later

      +
      +
        +

      • e.g., save f(x) as an instance variable

        • +
      +
      +
      • +
    +
    +
    • +

  • get_results(self) -> float

    +
    +
      +

    • This is called after the solver finishes

      • +

    • Returns the result of the solver

      +
      +
        +

      • e.g., to retrieve the result from the output file of the solver

        • +
      +
      +
      • +
    +
    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/customize/usage.html b/manual/v2.2.0/en/customize/usage.html new file mode 100644 index 00000000..3a2e1bc9 --- /dev/null +++ b/manual/v2.2.0/en/customize/usage.html @@ -0,0 +1,111 @@ + + + + + + + + Usage — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Usage

+

The following flow solves the optimization problem. +The number of flow corresponds the comment in the program example.

+
    +

  1. Define your Algorithm and/or Solver

    +
      +

    • Of course, classes that py2dmat defines are available

      • +
    +
    2. +

  2. Prepare the input parameter, info: py2dmat.Info

    +
      +

    • Make a dictionary as your favorite way

      +
      +
        +

      • The below example uses a TOML formatted input file for generating a dictionary

        • +
      +
      +
      • +
    +
    3. +

  3. Instantiate solver: Solver, runner: py2dmat.Runner, and algorithm: Algorithm

    4. +

  4. Invoke algorithm.main()

    5. +
+

Example

+
import sys
+import tomli
+import py2dmat
+
+# (1)
+class Solver(py2dmat.solver.SolverBase):
+    # Define your solver
+    ...
+
+class Algorithm(py2dmat.algorithm.AlgorithmBase):
+    # Define your algorithm
+    ...
+
+
+# (2)
+with open(sys.argv[1]) as f:
+    inp = tomli.load(f)
+info = py2dmat.Info(inp)
+
+# (3)
+solver = Solver(info)
+runner = py2dmat.Runner(solver, info)
+algorithm = Algorithm(info, runner)
+
+# (4)
+algorithm.main()
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/genindex.html b/manual/v2.2.0/en/genindex.html new file mode 100644 index 00000000..10bcc124 --- /dev/null +++ b/manual/v2.2.0/en/genindex.html @@ -0,0 +1,52 @@ + + + + + + + Index — 2DMAT 2.2-dev documentation + + + + + + + + + + +
+ + + +

Index

+ +
+ +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/index.html b/manual/v2.2.0/en/index.html new file mode 100644 index 00000000..739676a0 --- /dev/null +++ b/manual/v2.2.0/en/index.html @@ -0,0 +1,128 @@ + + + + + + + + Welcome to 2DMAT’s documentation! — 2DMAT 2.2-dev documentation + + + + + + + + + + + +
+ + +
+

Welcome to 2DMAT’s documentation!

+
+

Contents:

+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/input.html b/manual/v2.2.0/en/input.html new file mode 100644 index 00000000..4fe9d1bd --- /dev/null +++ b/manual/v2.2.0/en/input.html @@ -0,0 +1,279 @@ + + + + + + + + Input file — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Input file

+

As the input file format, TOML format is used. +The input file consists of the following six sections.

+
    +

  • base

    +
      +

    • Specify the basic parameters about py2dmat .

      • +
    +
    • +

  • solver

    +
      +

    • Specify the parameters about Solver .

      • +
    +
    • +

  • algorithm

    +
      +

    • Specify the parameters about Algorithm .

      • +
    +
    • +

  • runner

    +
      +

    • Specify the parameters about Runner .

      • +
    +
    • +

  • mapping

    +
      +

    • Define the mapping from a parameter searched by Algorithm .

      • +
    +
    • +

  • limitation

    +
      +

    • Define the limitation (constration) of parameter searched by Algorithm .

      • +
    +
    • +

  • log

    +
      +

    • Specify parameters related to logging of solver calls.

      • +
    +
    • +
+
+

[base] section

+
    +

  • dimension

    +

    Format: Integer

    +

    Description: Dimension of the search space (number of parameters to search)

    +
    • +

  • root_dir

    +

    Format: string (default: The directory where the program was executed)

    +

    Description: Name of the root directory. The origin of the relative paths to input files.

    +
    • +

  • output_dir

    +

    Format: string (default: The directory where the program was executed)

    +

    Description: Name of the directory to output the results.

    +
    • +
+
+
+

[solver] section

+

The name determines the type of solver. Each parameter is defined for each solver.

+
    +

  • name

    +

    Format: String

    +

    Description: Name of the solver. The following solvers are available.

    +
    +
      +

    • sim-trhepd-rheed : Solver to calculate Total-reflection high energy positron diffraction (TRHEPD) or Reflection High Energy Electron Diffraction (RHEED) intensities.

      • +

    • analytical : Solver to provide analytical solutions (mainly used for testing).

      • +
    +
    +
    • +
+

See Direct Problem Solver for details of the various solvers and their input/output files.

+
+
+

[algorithm] section

+

The name determines the type of algorithm. Each parameter is defined for each algorithm.

+
    +

  • name

    +

    Format: String

    +

    Description: Algorithm name. The following algorithms are available.

    +
    +
      +

    • minsearch : Minimum value search using Nelder-Mead method

      • +

    • mapper : Grid search

      • +

    • exchange : Replica Exchange Monte Carlo

      • +

    • bayes : Bayesian optimization

      • +
    +
    +
    • +

  • seed

    +

    Format: Integer

    +
    +
    Description: A parameter to specify seeds of the pseudo-random number generator used for random generation of initial values, Monte Carlo updates, etc.

    For each MPI process, the value of seed + mpi_rank * seed_delta is given as seeds. +If omitted, the initialization is done by the Numpy’s prescribed method.

    +
    +
    +
    • +

  • seed_delta

    +

    Format: Integer (default: 314159)

    +
    +
    Description: A parameter to calculate the seed of the pseudo-random number generator for each MPI process.

    For details, see the description of seed.

    +
    +
    +
    • +
+

See Search algorithms for details of the various algorithms and their input/output files.

+
+
+

[runner] section

+

This section sets the configuration of Runner, which bridges Algorithm and Solver. +It has two subsections, mapping and log .

+
+
+

[mapping] section

+

This section defines the mapping from an \(N\) dimensional parameter searched by Algorithm, \(x\), to an \(M\) dimensional parameter used in Solver, \(y\) . +In the case of \(N \ne M\), the parameter dimension in [solver] section should be specified.

+

In the current version, the affine mapping (linear mapping + translation) \(y = Ax+b\) is available.

+
    +

  • A

    +

    Format: List of list of float, or a string (default: [])

    +
    +
    Description: \(N \times M\) matrix \(A\). An empty list [] is a shorthand of an identity matrix.

    If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example).

    +
    +
    +
    • +

  • b

    +

    Format: List of float, or a string (default: [])

    +
    +
    Description: \(M\) dimensional vector \(b\). An empty list [] is a shorthand of a zero vector.

    If you want to set it by a string, arrange the elements of the vector separated with spaces.

    +
    +
    +
    • +
+

For example, both

+
A = [[1,1], [0,1]]
+
+
+

and

+
A = """
+1 1
+0 1
+"""
+
+
+

mean

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right).\end{split}\]
+
+
+

[limitation] section

+

This section defines the limitation (constraint) in an \(N\) dimensional parameter searched by Algorithm, \(x\), in addition of min_list and max_list.

+

In the current version, a linear inequation with the form \(Ax+b>0\) is available.

+
    +

  • co_a

    +

    Format: List of list of float, or a string (default: [])

    +
    +
    Description: \(N \times M\) matrix \(A\). An empty list [] is a shorthand of an identity matrix.

    If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example).

    +
    +
    +
    • +

  • co_b

    +

    Format: List of float, or a string (default: [])

    +
    +
    Description: \(M\) dimensional vector \(b\). An empty list [] is a shorthand of a zero vector.

    If you want to set it by a string, arrange the elements of the vector separated with spaces.

    +
    +
    +
    • +
+

For example, both

+
A = [[1,1], [0,1]]
+
+
+

and

+
A = """
+1 1
+0 1
+"""
+
+
+

mean

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right).\end{split}\]
+
+
+

[log] section

+

Setting parametrs related to logging of solver calls.

+
    +

  • filename

    +

    Format: String (default: “runner.log”)

    +

    Description: Name of log file.

    +
    • +

  • interval

    +

    Format: Integer (default: 0)

    +
    +
    Description: The log will be written out every time solver is called interval times.

    If the value is less than or equal to 0, no log will be written.

    +
    +
    +
    • +

  • write_result

    +

    Format: Boolean (default: false)

    +

    Description: Whether to record the output from solver.

    +
    • +

  • write_input

    +

    Format: Boolean (default: false)

    +

    Description: Whether to record the input to solver.

    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/introduction.html b/manual/v2.2.0/en/introduction.html new file mode 100644 index 00000000..dc731238 --- /dev/null +++ b/manual/v2.2.0/en/introduction.html @@ -0,0 +1,153 @@ + + + + + + + + Introduction — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

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) experiment[1, 2], sxrd[3], and leed[4]. +As algorithms, it offers the Nelder-Mead method[5], the grid search method[6], the Bayesian optimization method[7], the replica exchange Monte Carlo method[8], and the population annealing Monte Carlo method[9-11]. +In the future, we plan to add other direct problem solvers and search algorithms in 2DMAT.

+

[1] As a review, see Y. Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019).

+

[2] T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022).

+

[3] W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252 (2006) 5259.

+

[4] M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993).

+

[5] K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020).

+

[6] K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series,.

+

[7] Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022)

+

[8] K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996), R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986).

+

[9] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[10] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[11] J. Machta, Phys. Rev. E 82, 026704 (2010).

+
+
+

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

+
    +

  • 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.

+
    +

  • v2.0.0 -

    +
      +
      • +

      1. Motoyama (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Yoshimi (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Iwamoto (Department of Applied Mathematics and Physics, Tottori University)

        2. +
      +
      • +
      • +

      1. Hoshi (Department of Applied Mathematics and Physics, Tottori University)

        2. +
      +
      • +
    +
    • +

  • v0.1.0 - v1.0.1

    +
      +
      • +

      1. Motoyama (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Yoshimi (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Hoshi (Department of Applied Mathematics and Physics, Tottori University)

        2. +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/objects.inv b/manual/v2.2.0/en/objects.inv new file mode 100644 index 00000000..aa338e59 Binary files /dev/null and b/manual/v2.2.0/en/objects.inv differ diff --git a/manual/v2.2.0/en/output.html b/manual/v2.2.0/en/output.html new file mode 100644 index 00000000..0db149a4 --- /dev/null +++ b/manual/v2.2.0/en/output.html @@ -0,0 +1,106 @@ + + + + + + + + Output files — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Output files

+

See Direct Problem Solver and Search algorithms for the output files of each Solver and Algorithm.

+
+

Common file

+
+

time.log

+

The total time taken for the calculation for each MPI rank is outputted. +These files will be output under the subfolders of each rank respectively. +The time taken to pre-process the calculation, the time taken to compute, and the time taken to post-process the calculation are listed in the prepare , run , and post sections.

+

The following is an example of the output.

+
#prepare
+ total = 0.007259890999989693
+#run
+ total = 1.3493346729999303
+ - file_CM = 0.0009563499997966574
+ - submit = 1.3224223930001244
+#post
+ total = 0.000595873999941432
+
+
+
+
+

runner.log

+

The log information about solver calls for each MPI rank is outputted. +These files will be output under the subfolder of each rank. +The output is only available when the runner.log.interval parameter is a positive integer in the input.

+
    +

  • The first column is the serial number of the solver call.

    • +

  • The second column is the time elapsed since the last solver call.

    • +

  • The third column is the time elapsed since the start of the calculation.

    • +
+

The following is an example of the output.

+
# $1: num_calls
+# $2: elapsed_time_from_last_call
+# $3: elapsed_time_from_start
+
+1 0.0010826379999999691 0.0010826379999999691
+2 6.96760000000185e-05 0.0011523139999999876
+3 9.67080000000009e-05 0.0012490219999999885
+4 0.00011765699999999324 0.0013666789999999818
+5 4.965899999997969e-05 0.0014163379999999615
+6 8.666900000003919e-05 0.0015030070000000006
+   ...
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/search.html b/manual/v2.2.0/en/search.html new file mode 100644 index 00000000..6bbd3f2a --- /dev/null +++ b/manual/v2.2.0/en/search.html @@ -0,0 +1,81 @@ + + + + + + + Search — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + + + + +
+ + +

Search

+ + + + +

+ Searching for multiple words only shows matches that contain + all words. +

+ + +
+ + + +
+ + + +
+ +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/searchindex.js b/manual/v2.2.0/en/searchindex.js new file mode 100644 index 00000000..9664dfe0 --- /dev/null +++ b/manual/v2.2.0/en/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"docnames": ["acknowledgement", "algorithm/bayes", "algorithm/exchange", "algorithm/index", "algorithm/mapper_mpi", "algorithm/minsearch", "algorithm/pamc", "contact", "customize/algorithm", "customize/common", "customize/index", "customize/solver", "customize/usage", "index", "input", "introduction", "output", "solver/analytical", "solver/index", "solver/leed", "solver/sim-trhepd-rheed", "solver/sxrd", "start", "tool", "tutorial/bayes", "tutorial/exchange", "tutorial/index", "tutorial/limitation", "tutorial/minsearch", "tutorial/mpi", "tutorial/pamc", "tutorial/sim_trhepd_rheed", "tutorial/solver_simple"], "filenames": ["acknowledgement.rst", "algorithm/bayes.rst", "algorithm/exchange.rst", "algorithm/index.rst", "algorithm/mapper_mpi.rst", "algorithm/minsearch.rst", "algorithm/pamc.rst", "contact.rst", "customize/algorithm.rst", "customize/common.rst", "customize/index.rst", "customize/solver.rst", "customize/usage.rst", "index.rst", "input.rst", "introduction.rst", "output.rst", "solver/analytical.rst", "solver/index.rst", "solver/leed.rst", "solver/sim-trhepd-rheed.rst", "solver/sxrd.rst", "start.rst", "tool.rst", "tutorial/bayes.rst", "tutorial/exchange.rst", "tutorial/index.rst", "tutorial/limitation.rst", "tutorial/minsearch.rst", "tutorial/mpi.rst", "tutorial/pamc.rst", "tutorial/sim_trhepd_rheed.rst", "tutorial/solver_simple.rst"], "titles": ["Acknowledgements", "Bayse optimization bayes", "Replica exchange Monte Carlo exchange", "Search algorithms", "Direct parallel search mapper", "Nelder-Mead method minsearch", "Population Annealing Monte Carlo pamc", "Contact", "Algorithm", "Commons", "(For developers) User-defined algorithm and solver", "Solver", "Usage", "Welcome to 2DMAT\u2019s documentation!", "Input file", "Introduction", "Output files", "analytical solver", "Direct Problem Solver", "leed solver", "sim-trhepd-rheed solver", "sxrd solver", "Install of py2dmat", "Related Tools", "Optimization by Bayesian Optimization", "Optimization by replica exchange Monte Carlo", "Tutorials", "Replica Exchange Monte Carlo search with limitation", "Optimization by Nelder-Mead method", "Grid search", "Optimization by population annealing", "TRHEPD Direct Problem Solver", "Addition of a direct problem solver"], "terms": {"The": [0, 1, 2, 4, 5, 6, 8, 9, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 29, 30, 31, 32], "develop": [0, 13, 22, 26], "2dmat": [0, 1, 2, 5, 7, 22, 24, 25, 26, 30, 31], "wa": [0, 14, 15, 25, 29, 30], "support": [0, 15], "jsp": 0, "kakenhi": 0, "grant": 0, "number": [0, 1, 2, 4, 5, 8, 12, 14, 16, 19, 20, 21, 24, 25, 27, 28, 29, 30, 31], "19h04125": 0, "unif": 0, "comput": [0, 1, 4, 6, 15, 16, 17, 20, 21, 28, 29], "statist": [0, 6, 15, 30], "measur": [0, 8, 15], "technologi": 0, "massiv": [0, 2], "parallel": [0, 1, 2, 3, 6, 13, 23, 25, 27, 29, 30], "machin": [0, 1], "project": [0, 15], "advanc": [0, 4, 15, 21, 29], "softwar": [0, 15, 23, 26, 27, 28, 29, 31], "usabl": [0, 15], "materi": [0, 15], "scienc": [0, 15, 19], "institut": [0, 15], "solid": [0, 15], "state": [0, 15, 23], "physic": [0, 15], "univers": [0, 15, 26], "tokyo": [0, 7, 15], "A": [0, 1, 2, 4, 6, 9, 14, 15, 19, 20, 21, 23, 24, 27, 28, 29, 31], "part": [0, 4, 28, 31], "design": 0, "name": [0, 8, 14, 17, 21, 23, 24, 25, 27, 28, 29, 30, 32], "i": [0, 1, 2, 4, 5, 6, 8, 9, 11, 13, 14, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "inspir": 0, "abic": 0, "For": [0, 2, 4, 5, 6, 8, 9, 13, 14, 15, 19, 20, 21, 22, 23, 24, 25, 27, 29, 30, 32], "implement": [0, 1, 3], "forward": [0, 22, 31], "problem": [0, 2, 5, 6, 7, 10, 12, 13, 14, 15, 16, 22, 24, 25, 26, 28, 30], "solver": [0, 1, 2, 3, 4, 5, 6, 9, 12, 13, 15, 16, 22, 24, 25, 26, 27, 28, 29, 30], "we": [0, 1, 2, 6, 15, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "thank": [0, 7], "t": [0, 1, 2, 6, 15, 19, 23, 24, 25, 27, 30], "hanada": [0, 15, 26], "tohoku": [0, 26], "univ": 0, "mochizuki": [0, 15], "kek": 0, "w": [0, 2, 6, 15, 19, 20], "voeg": [0, 15], "gakugei": 0, "shirasawa": 0, "aist": 0, "r": [0, 1, 4, 5, 6, 15, 20, 21, 23, 24, 25, 28, 29, 30, 31], "ahm": 0, "kyushu": 0, "k": [0, 5, 6, 15, 21, 23], "wada": 0, "ad": [0, 1, 28, 32], "tutori": [0, 13, 22, 24, 25, 27, 28, 29, 30, 31], "custom": 0, "tsukamoto": 0, "issp": [0, 22], "an": [1, 2, 4, 5, 6, 7, 8, 9, 11, 14, 16, 19, 20, 21, 23, 25, 27, 30, 32], "us": [1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 14, 15, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "bayesian": [1, 13, 14, 15, 26], "perform": [1, 2, 4, 5, 8, 17, 23, 25, 27, 28, 29, 30], "search": [1, 2, 5, 6, 9, 13, 14, 15, 16, 17, 18, 20, 22, 24, 26, 28, 32], "base": [1, 8, 9, 11, 13, 19, 24, 25, 26, 27, 28, 29, 30, 32], "physbo": [1, 22, 24], "you": [1, 4, 5, 7, 8, 14, 15, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "need": [1, 4, 5, 20, 21, 23, 32], "instal": [1, 2, 4, 5, 6, 7, 13, 19, 20, 21, 23, 32], "beforehand": [1, 20, 21], "python3": [1, 2, 4, 5, 6, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "m": [1, 2, 4, 5, 6, 14, 15, 19, 20, 22, 27], "pip": [1, 2, 4, 5, 6, 22, 23], "If": [1, 2, 4, 5, 6, 7, 8, 9, 14, 20, 21, 22, 23, 25, 27, 30, 31], "mpi4pi": [1, 2, 4, 6, 8, 22], "mpi": [1, 2, 4, 6, 8, 11, 14, 16, 23, 25, 27, 29, 30], "possibl": [1, 24, 25, 30], "In": [1, 2, 3, 4, 5, 6, 8, 10, 14, 15, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31], "thi": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 14, 15, 20, 21, 24, 25, 26, 27, 28, 29, 30, 31, 32], "space": [1, 2, 3, 4, 5, 6, 8, 14, 23, 24, 25, 27, 29, 30], "defin": [1, 2, 4, 5, 6, 8, 9, 11, 12, 13, 14, 15, 20, 21, 22, 27, 32], "mesh_path": [1, 2, 4, 6, 24], "read": [1, 4, 8, 11, 20, 23, 28, 29], "from": [1, 2, 4, 5, 6, 8, 9, 11, 14, 19, 20, 21, 22, 23, 24, 25, 26, 28, 29, 30, 31, 32], "one": [1, 2, 4, 5, 6, 9, 20, 23, 24, 28, 30, 31, 32], "line": [1, 4, 5, 20, 21, 23, 27, 28, 29], "give": [1, 2, 15, 21, 24, 29], "point": [1, 2, 4, 5, 6, 8, 9, 23, 24, 25, 29, 30, 32], "first": [1, 2, 4, 5, 6, 9, 16, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "column": [1, 2, 4, 6, 16, 20, 24, 25, 27, 28, 29, 30, 31], "data": [1, 4, 15, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31], "second": [1, 2, 4, 5, 6, 9, 16, 20, 21, 23, 24, 25, 27, 28, 29, 30, 31], "subsequ": [1, 2, 4, 5, 6, 20, 21, 25, 27, 29, 30], "ar": [1, 2, 3, 4, 5, 6, 7, 9, 10, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31], "coordin": [1, 2, 4, 5, 6, 9, 20, 21, 23, 26, 27, 28, 29], "each": [1, 2, 4, 5, 6, 8, 9, 11, 14, 16, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30], "dimens": [1, 2, 4, 5, 6, 8, 14, 20, 23, 24, 25, 27, 28, 29, 30, 32], "min_list": [1, 2, 4, 5, 6, 14, 25, 27, 28, 30, 32], "max_list": [1, 2, 4, 5, 6, 14, 25, 27, 28, 30, 32], "num_list": [1, 4], "creat": [1, 4, 5, 20, 21, 23, 24, 25, 27, 28, 29, 30, 31], "evenli": [1, 4], "grid": [1, 2, 4, 6, 13, 14, 15, 22, 23, 24, 26], "format": [1, 2, 4, 5, 6, 12, 14, 17, 19, 20, 21, 23, 25, 27, 28, 30], "string": [1, 2, 4, 6, 14, 17, 19, 20, 21, 23, 28], "path": [1, 2, 4, 6, 8, 9, 11, 14, 19, 20, 21, 23, 24, 25, 28, 29, 30], "contain": [1, 4, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30], "inform": [1, 5, 7, 8, 13, 16, 19, 20, 21, 23, 25, 30], "about": [1, 2, 5, 7, 9, 14, 16, 25, 27, 30], "list": [1, 4, 5, 8, 14, 16, 19, 20, 21, 23, 24, 25, 28, 29, 30], "float": [1, 2, 4, 5, 6, 9, 11, 14, 20, 21, 23, 32], "length": [1, 2, 4, 5, 6, 20, 23, 30], "should": [1, 2, 4, 5, 6, 8, 11, 14, 20, 21], "match": [1, 4, 5, 19, 20, 28], "valu": [1, 2, 4, 5, 6, 8, 9, 14, 17, 20, 21, 23, 24, 25, 27, 28, 29, 30], "minimum": [1, 2, 4, 5, 6, 14, 24, 25, 27, 28, 29, 30, 32], "can": [1, 2, 4, 6, 8, 10, 15, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "take": [1, 2, 4, 9, 24, 25, 28, 29, 30], "maximum": [1, 2, 4, 5, 6, 21, 25, 27, 28, 29, 30], "integ": [1, 2, 4, 5, 6, 14, 16, 19, 20], "parametar": [1, 4], "hyper": [1, 2], "random_max_num_prob": [1, 24], "default": [1, 2, 5, 6, 9, 14, 20, 21, 23, 27, 28], "20": [1, 17, 23, 24, 25, 27, 30], "random": [1, 8, 14, 24, 25, 27, 30], "sampl": [1, 2, 4, 19, 22, 23, 26, 31], "taken": [1, 16], "befor": [1, 2, 6, 8, 11, 19, 20, 21, 24, 29], "score": [1, 24], "avail": [1, 2, 6, 12, 14, 16, 17, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30], "begin": [1, 6, 14, 20, 27, 30], "bayes_max_num_prob": [1, 24], "40": [1, 30], "time": [1, 2, 4, 5, 8, 14, 21, 22, 24, 25, 27, 28, 29, 30, 31], "specifi": [1, 2, 6, 7, 14, 17, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30], "function": [1, 2, 5, 6, 8, 15, 17, 18, 20, 25, 27, 28, 30, 32], "ei": 1, "expect": [1, 6, 32], "improv": 1, "pi": [1, 17], "probabl": [1, 2, 6, 27], "thompson": 1, "chosen": 1, "interv": [1, 2, 6, 14, 16, 24, 25, 30], "5": [1, 2, 4, 5, 6, 15, 16, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30, 31, 32], "hyperparamet": [1, 5, 24, 27], "learn": 1, "neg": 1, "0": [1, 2, 4, 5, 6, 8, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "onli": [1, 16, 20, 23, 24, 27, 28, 29], "step": [1, 2, 5, 8, 9, 20, 24, 25, 27, 28, 30], "num_rand_basi": [1, 24], "5000": [1, 24], "basi": 1, "normal": [1, 2, 5, 6, 20, 23, 27, 28, 29, 31], "gaussian": [1, 30], "process": [1, 2, 4, 5, 6, 8, 11, 14, 16, 27, 29, 30], "without": [1, 6, 28, 29], "linear": [1, 14], "model": [1, 21, 23], "explor": [1, 2, 4, 6, 24, 25, 30], "index": [1, 2, 4, 6, 9, 20, 24, 25, 28, 30], "variabl": [1, 2, 4, 5, 6, 8, 9, 11, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30], "string_list": [1, 4, 5, 20, 24, 25, 28, 29, 30], "below": [1, 2, 4, 5, 6, 12, 19, 20, 21, 22, 23, 24, 25, 28, 29, 30], "shown": [1, 2, 4, 6, 19, 20, 21, 22, 24, 25, 30, 31], "1": [1, 2, 4, 5, 8, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "6": [1, 2, 4, 6, 15, 16, 20, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "000000": [1, 2, 4, 6, 21, 23, 29, 31], "2": [1, 2, 4, 5, 12, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "750000": [1, 2, 4, 6, 29], "3": [1, 2, 4, 5, 6, 12, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "500000": [1, 2, 4, 6, 21, 29, 31], "4": [1, 2, 4, 5, 6, 12, 15, 16, 19, 20, 23, 24, 25, 27, 28, 29, 30, 31], "250000": [1, 2, 4, 6, 21, 29], "7": [1, 2, 4, 5, 6, 15, 17, 20, 21, 23, 24, 25, 28, 29, 30, 32], "8": [1, 2, 4, 6, 15, 16, 20, 22, 24, 28, 29], "9": [1, 2, 4, 6, 15, 16, 20, 24, 28, 29], "At": [1, 20], "correspond": [1, 2, 6, 9, 12, 20, 21, 23, 24, 28, 31], "object": [1, 5, 20, 25, 27, 28, 30], "order": [1, 2, 4, 5, 6, 11, 19, 20, 23, 24, 29], "so": [1, 5, 20, 24, 25, 30, 32], "far": 1, "z1": [1, 2, 5, 6, 24, 25, 28, 29, 30], "z2": [1, 2, 5, 6, 24, 25, 28, 29, 30], "factor": [1, 2, 4, 5, 6, 20, 21, 24, 25, 28, 29, 30], "z1_action": [1, 24], "z2_action": [1, 24], "factor_act": 1, "75": [1, 32], "05141906746102885": 1, "06591878368102033": 1, "25": [1, 5, 25, 28, 29, 30], "04380131351780189": [1, 28], "02312528177606794": 1, "bo": [1, 24], "aid": 1, "particularli": 1, "power": 1, "when": [1, 2, 5, 6, 7, 8, 9, 15, 16, 20, 23, 24, 25, 26, 27, 29, 30, 31], "long": 1, "evalu": [1, 2, 5, 6, 9, 17, 25, 27, 30, 32], "f": [1, 2, 3, 4, 6, 8, 9, 11, 12, 17, 18, 19, 20, 21, 24, 30, 32], "vec": [1, 2, 17, 21], "x": [1, 2, 3, 4, 6, 8, 9, 11, 14, 15, 17, 18, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30, 32], "approxim": 1, "often": 1, "g": [1, 6, 11, 15, 19, 20, 23, 31], "quick": 1, "easi": [1, 2], "train": 1, "reproduc": [1, 26], "well": 1, "_i": [1, 6, 20], "_": [1, 2, 6, 20], "n": [1, 6, 8, 14, 15, 17, 19, 20, 27], "some": [1, 2, 6, 10, 28, 31], "suitabl": [1, 31], "predetermin": 1, "set": [1, 4, 5, 8, 9, 14, 19, 21, 23, 24, 25, 27, 28, 29, 30, 32], "propos": 1, "follow": [1, 2, 5, 6, 7, 8, 9, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "candid": [1, 2, 4, 24, 28, 29], "where": [1, 2, 6, 9, 11, 14, 19, 23, 24, 25, 27, 28, 29, 30, 31], "acquit": 1, "obtain": [1, 2, 15, 21, 23, 24, 25, 27, 28, 29, 30], "error": [1, 6, 19, 21, 30, 32], "done": [1, 5, 14, 22, 23, 28, 29], "dataset": [1, 20], "retrain": 1, "after": [1, 2, 8, 11, 19, 20, 21, 23, 27, 28, 29, 31], "repeat": [1, 2, 5], "best": [1, 24, 27], "solut": [1, 2, 5, 14, 15, 24, 25, 30, 32], "return": [1, 2, 6, 8, 9, 11, 19, 20, 21, 32], "better": [1, 21], "smaller": [1, 2], "like": [1, 24, 29], "correct": [1, 24, 28], "answer": [1, 27, 28, 29], "doe": [1, 2, 28, 29], "contribut": 1, "much": 1, "accuraci": [1, 6], "becaus": [1, 2, 6, 24, 25, 27, 28, 30], "consid": [1, 2, 5, 6, 21, 23], "alreadi": [1, 19], "have": [1, 7, 19, 23, 25, 27, 30], "enough": 1, "On": [1, 2, 26], "other": [1, 2, 7, 15, 24, 26, 28, 29, 31], "hand": [1, 2, 26], "larg": [1, 6, 20], "mai": 1, "place": [1, 23], "littl": 1, "benefici": 1, "updat": [1, 2, 6, 14, 22, 27, 30], "select": [1, 26, 32], "former": 1, "call": [1, 2, 6, 8, 11, 14, 16, 20, 21, 23, 28, 29], "exploit": 1, "while": 1, "latter": 1, "import": [1, 2, 5, 8, 11, 12], "balanc": [1, 2, 6], "both": [1, 14, 27], "how": [1, 9, 10, 13, 20, 24, 25, 26, 28, 29, 30, 32], "choos": [1, 2, 32], "between": [1, 2, 6, 15, 20, 23, 24, 25, 27, 28, 29, 30], "them": [1, 8, 10], "librari": 1, "mapper_mpi": [1, 4, 26], "execut": [1, 4, 7, 9, 14, 19, 21, 23, 24, 25, 27, 30], "divid": [1, 2, 4, 5, 6, 23, 27], "addit": [1, 13, 14, 23, 24, 25, 26, 30], "kernel": 1, "allow": [1, 23, 32], "u": [1, 2, 7, 15, 19, 20, 22, 23], "thu": 1, "calcul": [1, 2, 5, 6, 8, 9, 14, 15, 16, 18, 19, 20, 21, 23], "amount": 1, "respect": [1, 6, 16, 20, 25, 27, 28, 30], "rxmc": [2, 25, 30], "method": [2, 3, 6, 8, 9, 11, 13, 14, 15, 22, 25, 26, 27, 29, 30, 32], "ha": [2, 5, 6, 9, 14, 15, 27, 29, 32], "two": [2, 4, 6, 9, 14, 15, 23, 24, 25, 27, 29, 30], "subsect": [2, 5, 6, 8, 14, 19, 24, 25, 28, 29, 30], "kei": [2, 6], "discret": [2, 6, 8], "otherwis": [2, 6], "continu": [2, 6, 8], "initial_list": [2, 5, 6, 28, 32], "equal": [2, 4, 5, 6, 14, 27], "descript": [2, 4, 5, 6, 14, 17, 19, 20, 21, 23], "initi": [2, 5, 6, 8, 9, 14, 21, 28], "randomli": [2, 5, 6], "unit_list": [2, 5, 6, 27, 30], "unit": [2, 5, 6, 8, 21, 23], "make": [2, 6, 12, 20, 21, 24, 31, 32], "dimensionless": [2, 5, 6], "compon": [2, 5, 6, 9, 10], "fall": [2, 5, 6], "dure": [2, 5, 6, 7], "infinit": [2, 5, 6], "exce": [2, 5, 6], "neighborlist_path": [2, 6], "numstep": [2, 6, 25, 27], "numsteps_exchang": [2, 25, 27], "tmin": [2, 6, 25, 27], "temperatur": [2, 6, 25, 27, 30], "tmax": [2, 6, 25, 27], "bmin": [2, 6, 30], "invers": [2, 6, 15, 26, 28, 30], "beta": [2, 6, 21, 30], "One": [2, 6], "bmax": [2, 6, 30], "tlogspac": [2, 6, 25, 27, 30], "boolean": [2, 6, 14, 20], "true": [2, 6, 8, 20, 24, 25, 27, 28, 29, 30], "whether": [2, 6, 14, 20, 21, 24, 25, 30], "assign": [2, 4, 6, 24, 29], "logarithm": [2, 6, 25, 30], "nreplica_per_proc": [2, 6, 30], "note": [2, 6, 19, 20, 21, 22, 28, 29], "ignor": [2, 6], "which": [2, 6, 9, 10, 14, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30, 31], "walker": [2, 6, 25, 27, 30], "move": [2, 5, 6, 20, 21, 24, 25, 27, 28, 29, 30], "indic": [2, 6, 27], "final": [2, 5, 6, 21, 24, 25, 27, 28, 29, 30], "j": [2, 6, 15, 19, 20, 31], "success": [2, 6, 24, 25, 30, 31], "util": [2, 6, 9, 19], "tool": [2, 6, 13, 28], "py2dmat_neighborlist": [2, 6, 13], "gener": [2, 6, 8, 9, 11, 12, 14, 15, 19, 20, 23, 24, 25, 27, 29, 30, 31], "detail": [2, 5, 6, 8, 9, 14, 19, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "pleas": [2, 6, 7, 8, 22, 23, 29, 32], "see": [2, 5, 6, 8, 9, 14, 15, 16, 19, 20, 21, 22, 24, 25, 27, 28, 29, 30, 31, 32], "relat": [2, 6, 13, 14], "store": [2, 6, 8, 19, 21, 24, 25, 28, 29, 30], "suggest": [2, 6], "mc": [2, 6, 25, 30], "third": [2, 6, 16, 20, 21, 23, 24, 25, 27, 29, 30], "fourth": [2, 6, 20, 24, 25, 27, 30], "remain": [2, 6, 24], "exampl": [2, 4, 5, 6, 8, 9, 12, 14, 16, 19, 20, 21, 23, 25, 27, 31, 32], "fx": [2, 5, 8, 9, 20, 24, 25, 27, 28, 30], "004999999999999999": [2, 25], "07830821484593968": [2, 25], "682008067401509": [2, 25], "9502750191292586": [2, 25], "0758494287185766": 2, "811346329442423": 2, "691101784194861": 2, "08566823949124412": 2, "606664760390988": 2, "2093903670436497": 2, "06273922648753057": [2, 25], "330900869594549": [2, 25], "311333132184154": [2, 25], "same": [2, 6, 9, 11, 21, 22, 23, 25, 27, 28, 29, 30], "optim": [2, 3, 5, 6, 8, 9, 10, 12, 13, 14, 15, 17, 18, 19, 21, 22, 23, 26, 27, 29, 32], "among": [2, 6, 22], "all": [2, 4, 5, 6, 7, 15, 20, 22, 23, 25, 27, 28, 29], "nproc": [2, 6, 11, 25, 27, 30], "65": [2, 6, 15, 25], "008233957976993406": [2, 6, 25], "221129370933539": [2, 6, 25], "139591716517661": [2, 6, 25], "replac": [2, 7, 20, 23], "15": [2, 15, 20, 24], "28": [2, 20], "70157662892569": 2, "3139009347685118": 2, "20946994566609": 2, "98676409223712": 2, "7442621319489637": 2, "868754990884034": 2, "mcmc": 2, "stochast": 2, "accord": [2, 5, 6, 25, 30], "weight": [2, 6, 20, 30], "boltzmann": 2, "e": [2, 6, 7, 11, 15, 17, 20, 23, 31], "adopt": [2, 25, 27, 30], "It": [2, 5, 6, 8, 11, 14, 20, 21, 24], "imposs": 2, "mani": [2, 20, 21, 26], "case": [2, 4, 14, 20, 23, 24, 25, 26, 27, 28, 29, 30, 32], "unfortun": [2, 6], "directli": [2, 6, 23, 27, 28, 29], "insteadli": 2, "slightli": 2, "seri": [2, 6, 15], "_t": 2, "distribut": [2, 6, 15, 25, 27, 30], "obei": [2, 6], "let": [2, 20], "transis": 2, "p": [2, 6, 9, 15, 19, 27, 31], "determin": [2, 5, 6, 14, 15, 19], "condit": [2, 6, 20], "sum_": [2, 17, 20], "converg": [2, 5, 21, 28], "practic": 2, "stronger": 2, "usual": [2, 23], "impos": [2, 27], "summat": [2, 20], "metropoli": 2, "hast": 2, "mh": 2, "solv": [2, 10, 12, 15, 26], "split": [2, 6, 8, 23], "transit": [2, 6], "accept": [2, 6, 30], "As": [2, 14, 15, 27, 31, 32], "simpl": [2, 5], "center": [2, 21, 22], "q": [2, 23], "whole": [2, 9, 21, 23, 24, 25, 30], "product": 2, "ones": [2, 24, 30], "x_t": 2, "min": 2, "left": [2, 6, 14, 17, 20], "frac": [2, 6, 17, 20], "right": [2, 6, 14, 15, 17, 20], "verifi": 2, "satisfi": [2, 27], "substitut": 2, "equat": [2, 20], "symmetri": 2, "form": [2, 6, 14, 19, 23], "exp": [2, 6, 17, 19], "By": [2, 6, 25, 27, 29, 30], "sai": 2, "delta": 2, "fact": 2, "le": 2, "procedur": [2, 24, 25, 28, 29, 30], "current": [2, 9, 14, 15, 23, 24, 27, 28], "posit": [2, 15, 16, 19, 20, 21, 23, 24, 25, 28, 30], "descend": 2, "given": [2, 5, 6, 9, 14, 15, 21, 23, 24, 25, 26, 27, 29, 30], "abov": [2, 19, 23, 26, 28, 31], "endur": 2, "climb": 2, "over": [2, 6, 15, 19], "hill": 2, "height": 2, "sim": [2, 13, 14, 18, 22, 24, 25, 28, 29, 30, 31], "escap": 2, "local": [2, 5, 22], "minima": 2, "most": 2, "cannot": 2, "easili": 2, "deeper": 2, "vallei": 2, "than": [2, 5, 14, 23, 25, 27, 30], "why": 2, "increas": [2, 21], "avoid": 2, "stuck": 2, "sinc": [2, 16, 24, 28, 29], "precis": 2, "becom": [2, 20], "necessari": [2, 19, 29], "decreas": [2, 30], "achiev": 2, "more": [2, 5, 19, 25, 30], "dilemma": 2, "lead": [2, 9], "tune": [2, 23], "carefulli": 2, "wai": [2, 12, 32], "overcom": [2, 6], "too": [2, 20], "simul": [2, 21, 23, 26], "anneal": [2, 3, 13, 15, 26], "iter": [2, 5, 20, 21, 29, 32], "goe": 2, "anoth": 2, "temper": 2, "treat": [2, 9, 21], "fix": [2, 6, 24, 29], "studi": 2, "cool": 2, "heat": 2, "also": [2, 19, 23, 24, 25, 27, 28, 29, 30, 32], "known": 2, "version": [2, 7, 13, 14, 21, 22, 27], "sever": [2, 5], "copi": [2, 23, 24, 25, 28, 29, 30, 31], "system": [2, 7, 19, 20, 23], "differ": [2, 5, 24, 25, 27, 28, 29, 30], "Then": [2, 6, 24, 25, 27, 28, 30, 31], "observ": 2, "moreov": 2, "just": [2, 6], "bias": 2, "narrow": 2, "ratio": [2, 6, 30], "suit": 2, "recommend": [2, 5, 22], "user": [2, 9, 13, 15, 22, 32], "minsearch": [2, 3, 8, 13, 14, 24, 25, 26, 28, 29, 30, 32], "start": [2, 11, 16, 21], "uncertainti": [2, 21], "due": 2, "footnot": 2, "To": [2, 7, 9, 20, 32], "non": 2, "period": [2, 6, 23, 27], "ergod": 2, "py2dmat": [3, 8, 10, 11, 12, 13, 14, 19, 20, 21, 23, 24, 25, 28, 30, 32], "paramet": [3, 8, 9, 11, 12, 14, 15, 16, 18, 23, 24, 25, 26, 27, 28, 29, 30, 32], "mathbf": 3, "ni": 3, "result": [3, 5, 8, 9, 11, 14, 15, 21, 23, 24, 25, 26, 30], "section": [3, 8, 13, 16, 17, 24, 25, 27, 28, 29, 30, 32], "describ": [3, 5, 6, 10, 20, 21, 23, 24, 25, 27, 28, 29, 30], "nelder": [3, 13, 14, 15, 22, 25, 26, 30, 32], "mead": [3, 13, 14, 15, 22, 25, 26, 29, 30, 32], "direct": [3, 10, 13, 14, 15, 16, 21, 22, 24, 25, 26, 28, 30], "mapper": [3, 8, 9, 13, 14, 29], "replica": [3, 6, 13, 14, 15, 20, 26, 30], "exchang": [3, 9, 13, 14, 15, 26, 30], "mont": [3, 13, 14, 15, 20, 26, 30], "carlo": [3, 13, 14, 15, 20, 26, 30], "popul": [3, 13, 15, 26], "pamc": [3, 13, 26, 30], "bays": [3, 13], "bay": [3, 13, 14, 24, 25, 26, 30], "algorithm": [4, 5, 9, 12, 13, 15, 16, 17, 20, 22, 24, 25, 26, 27, 28, 29, 30, 31, 32], "automat": [4, 6, 8, 20], "trivial": 4, "requir": [4, 11, 22, 23, 26], "last": [4, 6, 16, 20, 23, 24, 25, 28, 29, 30], "047852": [4, 29], "055011": [4, 29], "053190": [4, 29], "038905": [4, 29], "047674": [4, 29], "065919": [4, 29], "053675": [4, 29], "061261": [4, 29], "069351": [4, 29], "071868": [4, 29], "selct": 5, "downhil": 5, "simplex": 5, "d": [5, 6, 8, 15, 19, 20, 31, 32], "systemat": 5, "pair": [5, 23], "although": [5, 6, 28], "stabl": 5, "steepest": 5, "descent": 5, "still": [5, 23], "being": [5, 20, 27], "trap": 5, "optimum": 5, "check": [5, 23, 24, 25, 27, 29, 30, 32], "scipi": [5, 22, 23, 28], "": [5, 6, 9, 14, 15, 20, 21, 23, 28, 29, 31, 32], "offici": [5, 20, 31], "document": 5, "uniformli": [5, 25, 30], "nelson": 5, "initial_scale_list": 5, "shift": 5, "initial_simplex": 5, "sum": [5, 6, 20], "plu": 5, "scale": [5, 21, 23], "xatol": 5, "1e": 5, "fatol": 5, "maxit": 5, "10000": [5, 24, 27], "maxfev": 5, "100000": [5, 27], "find": [5, 15, 20, 21, 28], "header": [5, 20, 23], "z3": [5, 28], "015199251773721183": [5, 28], "229166666666666": 5, "3125": 5, "645833333333333": 5, "013702918021532375": 5, "225694444444445": 5, "40625": 5, "5451388888888884": 5, "012635279378225261": 5, "179976851851851": 5, "348958333333334": 5, "5943287037037033": 5, "006001660077530159": 5, "382680568652868e": [5, 28], "06": [5, 20, 28], "230524973874179": [5, 28], "370622919269477": [5, 28], "5961444501081647": [5, 28], "numsteps_ann": [6, 30], "lower": [6, 8, 25, 27, 30], "numt": 6, "resampling_interv": 6, "resampl": 6, "fix_num_replica": 6, "markov": 6, "chain": 6, "fifth": [6, 25, 30], "th": [6, 24], "ancestor": [6, 30], "neal": [6, 15, 30], "jarzynski": [6, 30], "grand": [6, 30], "x1": [6, 25, 27, 32], "73": 6, "82799488298886": 6, "592321856342956": 6, "13": [6, 20, 24, 31], "487174782058675": 6, "672488908364282": 6, "39": 6, "96292704464803": 6, "321623766458111": 6, "34": 6, "913851603463": 6, "908794428939206": 6, "834671825646121": 6, "354500581633733": 6, "65151610695736": 6, "910894059585031": 6, "combin": [6, 10], "metric": 6, "standard": [6, 15, 20, 21, 24, 28, 29, 30, 31], "partit": [6, 30], "log": [6, 13, 20, 24, 25, 27, 28, 29, 30], "z": [6, 20, 23, 28, 30], "z_0": [6, 21, 30], "int": [6, 8, 9, 11, 21], "mathrm": [6, 23], "beta_0": 6, "sixth": [6, 30], "mean": [6, 14, 20, 30], "z0": [6, 30], "33": [6, 23, 29], "36426034198166": 6, "0193077565358273": 6, "100": [6, 17, 27], "9804": 6, "518006242920819": 6, "9535301415484388": 6, "2134775491597027": 6, "9058": 6, "5919146358616842": 6, "2770369776964151": 6, "538611313376179": 6, "9004": 6, "configur": [6, 14, 23, 28, 29], "under": [6, 15, 16, 20, 21, 23, 24, 25, 27, 28, 29, 30], "beta_i": 6, "f_i": 6, "bolzmann": 6, "langl": 6, "rangle_i": 6, "xa": 6, "tild": 6, "our": [6, 28, 29], "numer": 6, "introduc": [6, 26, 27], "x_i": [6, 17], "joint": 6, "x_0": [6, 21], "x_1": 6, "dot": [6, 20], "x_n": 6, "_n": 6, "x_": [6, 17, 27], "cdot": 6, "_1": 6, "t_i": 6, "hold": [6, 25], "turn": 6, "out": [6, 14], "margin": [6, 23], "prod_": 6, "consequ": 6, "rangle_n": 6, "repres": [6, 21, 23, 28], "extend": 6, "equiv": 6, "prod_i": 6, "end": [6, 14, 20, 23, 27, 28, 29, 31], "difficult": [6, 7], "instead": [6, 10, 29], "_0": 6, "t_1": 6, "t_2": 6, "x_2": 6, "t_n": 6, "scheme": 6, "generet": 6, "through": 6, "t_": 6, "reweight": 6, "rewritten": [6, 28], "big": 6, "rangle_": 6, "z_n": [6, 30], "f_n": 6, "f_0": 6, "f_": 6, "w_n": 6, "aw_n": 6, "therefor": [6, 19, 26], "arithmet": 6, "estim": [6, 15, 24, 25, 26, 28, 29, 30], "varianc": 6, "get": [6, 9, 23, 28, 31], "wors": 6, "sum_k": 6, "reset": 6, "uniti": 6, "pseudo": [6, 8, 14, 23, 25, 27, 30], "code": [6, 9, 19, 20, 21, 22, 31, 32], "rang": [6, 27, 28, 29], "draw_from": 6, "\u03b2": 6, "transfer": [6, 8], "There": 6, "11": [6, 15, 17, 20, 24], "125": [6, 15], "139": [6, 15], "2001": [6, 15], "hukushima": [6, 15], "y": [6, 9, 14, 15, 17, 20, 28, 32], "iba": [6, 15], "aip": [6, 15], "conf": [6, 15], "proc": [6, 15], "690": [6, 15], "200": [6, 15, 30], "2003": [6, 15], "machta": [6, 15], "pre": [6, 8, 16], "82": [6, 15], "026704": [6, 15], "2010": [6, 15], "bug": 7, "report": [7, 15, 19], "github": [7, 21, 22, 31], "issu": 7, "page": [7, 15, 31], "resolv": 7, "earli": 7, "guidelin": 7, "your": [7, 12, 21], "oper": 7, "compil": [7, 19], "occur": 7, "enter": [7, 8], "input": [7, 8, 9, 11, 12, 13, 16, 22, 23, 31, 32], "file": [7, 8, 9, 11, 12, 13, 22, 23, 31, 32], "its": [7, 9, 15, 24, 25, 28, 29, 30], "output": [7, 8, 9, 11, 13, 14, 23, 24, 25, 27, 28, 29, 30, 31, 32], "cooper": 7, "ani": [7, 9], "question": 7, "research": 7, "consult": 7, "send": 7, "mail": 7, "address": 7, "dev__at__issp": 7, "ac": 7, "jp": 7, "_at_": 7, "subclass": [8, 11], "class": [8, 9, 11, 12, 32], "offer": [8, 15], "__init__": [8, 11, 32], "self": [8, 9, 11, 32], "info": [8, 11, 12], "runner": [8, 12, 13, 27], "none": [8, 9, 11, 20], "common": [8, 10, 13], "instanc": [8, 9, 11], "mpicomm": 8, "option": [8, 22, 23, 25, 27, 28, 29, 30], "comm": 8, "comm_world": 8, "fail": [8, 24, 25, 27, 28, 29, 30], "mpisiz": 8, "mpirank": [8, 11], "rank": [8, 16, 19, 20, 21, 25, 27, 29, 30], "rng": 8, "np": [8, 9, 23, 25, 27, 29, 30, 32], "seed": [8, 14, 25, 27, 30, 32], "label_list": [8, 24, 25, 28, 29, 30], "str": [8, 9, 11], "ax": [8, 9, 14, 25, 27, 30], "root_dir": [8, 9, 11, 14], "pathlib": [8, 9, 11], "root": [8, 9, 11, 14, 24, 25, 30], "directori": [8, 9, 11, 14, 19, 20, 23, 24, 25, 27, 28, 29, 30], "output_dir": [8, 9, 11, 14, 27, 30, 32], "proc_dir": [8, 11], "work": [8, 11, 20, 25, 30, 31], "made": [8, 19], "timer": 8, "dict": [8, 9], "dictionari": [8, 9, 12], "elaps": [8, 16], "three": [8, 9, 19, 21, 23, 28], "empti": [8, 14], "dictinari": 8, "prepar": [8, 11, 12, 15, 16, 22, 23, 24, 25, 27, 28, 29, 30, 31], "run": [8, 11, 13, 16, 19, 20, 21, 23, 24, 25, 26, 28, 29, 30, 31, 32], "post": [8, 16, 21, 24, 30], "_prepar": 8, "_run": 8, "origin": [8, 9, 14, 15], "write": 8, "_post": 8, "main": [8, 12, 13, 24, 25, 27, 28, 29, 30], "_read_param": 8, "tupl": 8, "ndarrai": [8, 9, 32], "helper": 8, "param": [8, 24, 25, 27, 28, 29, 30, 32], "bound": [8, 25, 30], "upper": [8, 25, 27, 30], "_meshgrid": 8, "bool": [8, 21], "fals": [8, 14, 20, 21, 24, 25, 27, 28, 29, 30], "dimensin": 8, "nxd": 8, "matrix": [8, 14, 21, 27], "id": [8, 9, 24, 29], "dimension": [8, 14, 15, 23, 27, 29], "vector": [8, 14, 20, 21, 23, 27], "scatter": 8, "argument": [8, 23], "constructor": [8, 9, 11, 32], "super": [8, 11], "itself": [8, 23], "messag": [8, 11, 23], "submit": [8, 9, 16], "four": 9, "program": [9, 12, 14, 19, 21, 24, 25, 26, 27, 28, 29, 30, 31], "written": [9, 14, 20, 21, 23, 25, 27, 31], "pass": [9, 23, 24, 25, 27, 28, 29, 30, 32], "sub": [9, 21, 27], "field": 9, "convert": [9, 11], "absolut": 9, "expand": 9, "home": [9, 22], "specif": [9, 28, 29], "expandus": 9, "rel": [9, 14], "work_dir": [9, 11], "tri": 9, "invok": [9, 11, 12], "via": [9, 23], "lap": 9, "min_search": 9, "recalcul": 9, "connect": 9, "map": [9, 13], "callabl": 9, "snippet": 9, "intern": [9, 27, 28, 29], "omit": [9, 14, 20, 21, 24, 25, 28, 30], "affin": [9, 14], "b": [9, 14, 20, 21, 24, 25, 27, 28, 29, 30, 31], "element": [9, 14, 23], "revers": 10, "serv": 10, "own": [10, 20], "chapter": [10, 24, 28, 29], "usag": [10, 13], "solverbas": [11, 12], "save": [11, 23, 24], "includ": [11, 22, 23, 24, 25, 30, 32], "someth": 11, "nthread": 11, "somewher": 11, "get_result": 11, "later": 11, "finish": [11, 23], "retriev": 11, "flow": 12, "comment": [12, 21, 23], "Of": 12, "cours": 12, "favorit": 12, "toml": [12, 14, 22, 23, 24, 25, 27, 28, 29, 30, 32], "instanti": 12, "sy": 12, "tomli": [12, 22], "algorithmbas": 12, "open": [12, 25, 30], "argv": 12, "inp": 12, "load": 12, "introduct": 13, "what": [13, 20, 24, 28, 29], "licens": 13, "prerequisit": 13, "download": [13, 19, 20, 21, 27, 28, 29, 32], "uninstal": 13, "trhepd": [13, 14, 15, 18, 22, 24, 25, 26, 28, 29, 30], "limit": [13, 26], "analyt": [13, 14, 18, 27], "rheed": [13, 14, 18, 22, 24, 25, 26, 28, 29, 30, 31], "sxrd": [13, 15, 18, 22], "leed": [13, 15, 18, 22], "to_dft": 13, "py": [13, 24, 25, 27, 28, 29, 30, 31, 32], "acknowledg": 13, "contact": 13, "consist": [14, 23], "six": 14, "basic": [14, 23], "constrat": 14, "type": [14, 20, 21, 22, 29], "total": [14, 15, 16, 20], "reflect": [14, 15, 20, 26, 31], "high": [14, 15, 26], "energi": [14, 15, 23, 26], "positron": [14, 15, 31], "diffract": [14, 15, 20, 21, 24, 25, 26, 28, 29, 30, 31], "electron": [14, 23, 26, 31], "intens": [14, 20, 21, 28, 31], "provid": [14, 25, 28, 31, 32], "mainli": 14, "test": [14, 24, 25, 27, 28, 29, 30, 31, 32], "variou": [14, 23], "etc": [14, 19, 25, 30], "mpi_rank": 14, "seed_delta": 14, "numpi": [14, 22, 23], "prescrib": 14, "314159": 14, "bridg": 14, "ne": 14, "translat": 14, "shorthand": 14, "ident": 14, "want": [14, 19, 20, 21, 22, 23, 24, 25, 28, 29, 30], "arrang": 14, "separ": [14, 22], "newlin": 14, "zero": 14, "constraint": [14, 27], "inequ": 14, "co_a": [14, 27], "co_b": [14, 27], "parametr": 14, "filenam": [14, 20, 23, 31], "everi": 14, "less": [14, 23], "write_result": 14, "record": [14, 25, 30], "write_input": 14, "framework": 15, "appli": [15, 27], "experiment": [15, 19, 20, 21, 24, 25, 26, 28, 29, 30], "analysi": [15, 22, 24, 26, 28, 29], "structur": [15, 19, 20, 23, 28, 31], "deviat": [15, 20, 28, 30], "atom": [15, 19, 20, 23, 24, 25, 26, 28, 29, 30], "loss": 15, "minim": [15, 20, 27, 28], "further": [15, 28, 29], "wrapper": [15, 31], "experi": [15, 20, 24, 25, 28, 29, 30], "futur": 15, "plan": 15, "add": [15, 19, 25, 27, 30, 32], "review": 15, "fukaya": 15, "et": 15, "al": 15, "phy": [15, 31], "appl": [15, 31], "52": 15, "013002": 15, "2019": [15, 21], "motoyama": 15, "yoshimi": 15, "hoshi": 15, "commun": 15, "277": 15, "108371": 15, "2022": 15, "akimoto": 15, "aoyama": 15, "sumitani": 15, "nakatani": 15, "h": [15, 19, 21, 23], "tajiri": 15, "takahashi": 15, "hisada": 15, "mukainakano": 15, "zhang": 15, "sugiyama": 15, "kawata": 15, "surfac": [15, 19, 20, 21, 23, 28, 31], "252": 15, "2006": 15, "5259": 15, "van": [15, 19], "hove": [15, 19], "moritz": [15, 19], "rou": [15, 19], "wander": [15, 19], "barbieri": [15, 19], "mater": [15, 19], "stark": [15, 19], "somorjai": [15, 19], "autom": [15, 19], "complex": [15, 19], "volum": [15, 19], "19": [15, 19, 22, 24], "191": [15, 19], "229": [15, 19], "1993": [15, 19], "tanaka": 15, "ichimiya": [15, 31], "hyodo": 15, "acta": 15, "pol": 15, "137": 15, "188": 15, "2020": 15, "jjap": 15, "tamura": 15, "terayama": 15, "ueno": 15, "tsuda": 15, "278": 15, "108405": 15, "nemoto": 15, "soc": 15, "japan": 15, "1604": 15, "1996": 15, "swendsen": 15, "wang": 15, "rev": 15, "lett": 15, "57": 15, "2607": 15, "1986": 15, "10": [15, 19, 20, 23, 24, 27, 28, 30], "packag": [15, 22, 23], "gnu": 15, "public": 15, "gpl": 15, "v3": 15, "copyright": 15, "c": [15, 21], "reserv": 15, "hope": 15, "cite": 15, "refer": [15, 22, 23, 32], "publish": 15, "applic": 15, "iwamoto": 15, "ichinos": 15, "280": 15, "108465": 15, "bibtex": 15, "articl": 15, "motoyama2022108465": 15, "titl": 15, "journal": 15, "year": 15, "issn": 15, "0010": 15, "4655": 15, "doi": [15, 19], "http": [15, 19, 21, 22, 31], "org": [15, 19], "1016": [15, 19], "cpc": 15, "url": [15, 19, 21], "www": [15, 19], "sciencedirect": 15, "com": [15, 21, 22, 31], "pii": 15, "s0010465522001849": 15, "author": 15, "yuichi": 15, "kazuyoshi": 15, "izumi": 15, "harumichi": 15, "hayato": 15, "takeo": 15, "v2": 15, "04": [15, 20], "08": [15, 20], "01": [15, 20, 31], "17": [15, 23, 24], "v1": 15, "2021": 15, "03": [15, 20], "12": [15, 20, 23, 24], "v0": 15, "02": [15, 19, 20, 31], "been": 15, "member": 15, "depart": 15, "mathemat": 15, "tottori": 15, "These": [16, 20, 25, 26, 30], "subfold": [16, 24, 25, 27, 29, 30], "007259890999989693": 16, "3493346729999303": 16, "file_cm": 16, "0009563499997966574": 16, "3224223930001244": 16, "000595873999941432": 16, "serial": [16, 29], "num_cal": 16, "elapsed_time_from_last_cal": 16, "elapsed_time_from_start": 16, "0010826379999999691": 16, "96760000000185e": 16, "05": [16, 20, 25], "0011523139999999876": 16, "67080000000009e": 16, "0012490219999999885": 16, "00011765699999999324": 16, "0013666789999999818": 16, "965899999997969e": 16, "0014163379999999615": 16, "666900000003919e": 16, "0015030070000000006": 16, "predefin": [17, 22], "benchmark": 17, "funtion_nam": 17, "function_nam": [17, 27, 32], "quadrat": 17, "quad": 17, "forall_i": 17, "rosenbrock": 17, "acklei": 17, "sqrt": [17, 20], "co": 17, "himmerblau": 17, "805118": 17, "131312": 17, "779310": 17, "283186": 17, "584428": 17, "848126": 17, "rock": [19, 20, 21, 28, 31], "curv": [19, 20, 21, 25, 28, 30, 31], "satle": [19, 22], "0167": 19, "5729": 19, "93": 19, "90011": 19, "access": [19, 21], "ict": 19, "hkbu": 19, "edu": 19, "hk": 19, "vanhove_fil": 19, "leedsatl": 19, "zip": [19, 21], "depend": 19, "chang": [19, 21], "sourc": [19, 20, 21, 22, 31, 32], "stal1": 19, "ex": [19, 20, 23, 24, 25, 28, 29, 30, 31], "satl2": 19, "try": [19, 31], "script": [19, 23, 24, 25, 27, 28, 29, 30, 31, 32], "setup": 19, "sh": [19, 24, 25, 27, 28, 29, 30], "rewrit": 19, "cd": [19, 24, 25, 27, 28, 29, 30, 31], "satl1": 19, "assum": [19, 24, 25, 27, 28, 29, 30, 31], "must": [19, 21, 22], "rfac": 19, "tleed4": 19, "tleed5": 19, "tleed": 19, "o": [19, 23], "short": 19, "path_to_solv": 19, "path_to_base_dir": 19, "fit": [19, 21], "edit": [19, 21, 32], "optxxx": 19, "xxx": [19, 25, 30], "digit": 19, "000": 19, "001": [19, 20, 23, 28, 31], "002": [19, 20], "iflag": 19, "lsflag": 19, "side": 19, "ipr": 19, "istart": 19, "lrflag": 19, "nsym": 19, "astep": 19, "vstep": 19, "nt0": 19, "nset": 19, "lsmax": 19, "llcut": 19, "ninset": 19, "0000": 19, "pqex": 19, "ndim": 19, "opt000": 19, "disp": 19, "opt001": 19, "dvopt": 19, "mflag": 19, "ngrid": 19, "niv": 19, "folder": [19, 20, 21, 23, 24, 25, 27, 28, 29, 30, 31], "websit": 20, "src": [20, 23, 24, 25, 27, 28, 29, 30, 31, 32], "bulk": [20, 23, 24, 25, 28, 29, 30, 31], "surf": [20, 23, 24, 25, 28, 29, 30, 31], "generate_rocking_curv": 20, "remove_work_dir": 20, "remov": [20, 23], "surface_exec_fil": 20, "surface_input_fil": 20, "bulk_output_fil": 20, "bulkp": [20, 24, 25, 28, 29, 30, 31], "surface_output_fil": 20, "calculated_first_lin": [20, 24, 25, 28, 29, 30], "calculated_info_lin": 20, "glanc": 20, "angl": [20, 21, 23, 28, 29, 31], "beam": [20, 31], "cal_numb": 20, "multipl": 20, "postprocess": 20, "draw": 20, "rfactor_typ": 20, "v": 20, "With": [20, 32], "a2": 20, "singl": 20, "many_beam": 20, "weight_typ": 20, "max": 20, "longer": 20, "calc": [20, 23], "manual": [20, 23, 24, 25, 27, 30], "sum_i": 20, "sum_j": 20, "spot_weight": 20, "mandatori": 20, "omega": 20, "half": [20, 31], "width": [20, 31], "convolut": [20, 28, 31], "value_01": [20, 24, 25, 28, 29, 30], "value_02": [20, 24, 25, 28, 29, 30], "placehold": 20, "reference_first_lin": 20, "dexp": 20, "reference_last_lin": 20, "exp_numb": 20, "appropri": [20, 23, 28], "value_": [20, 28], "nelm": [20, 28], "ge": [20, 28], "c4x2": [20, 28], "32": [20, 28], "da1": [20, 28], "sap": [20, 28], "bh": [20, 28], "bk": [20, 28], "bz": [20, 28], "nsg": [20, 28], "msa": [20, 28], "msb": [20, 28], "nsa": [20, 28], "nsb": [20, 28], "dthick": [20, 28], "dx": [20, 28], "dy": [20, 28], "natm": [20, 28], "34502591": [20, 28], "ielm": [20, 28], "ocr": [20, 28], "752457792": [20, 28], "480003343": [20, 28], "465005851": [20, 28], "value_03": [20, 24, 28, 29], "497500418": [20, 28], "281675": [20, 28], "991675": [20, 28], "847225": [20, 28], "807225": [20, 28], "009998328": [20, 28], "597225": [20, 28], "wdom": [20, 28], "ndom": [20, 28], "multipli": [20, 24], "00000e": 20, "17149e": 20, "03057e": 20, "88164e": 20, "13871e": 20, "01611e": 20, "23952e": 20, "44044e": 20, "29668e": 20, "53633e": 20, "68659e": 20, "49471e": 20, "38656e": 20, "85375e": 20, "93037e": 20, "67719e": 20, "93113e": 20, "52987e": 20, "02117e": 20, "92590e": 20, "53448e": 20, "69136e": 20, "00": [20, 31], "86780e": 20, "64176e": 20, "97661e": 20, "07": 20, "10000e": 20, "80255e": 20, "57932e": 20, "32760e": 20, "20000e": 20, "77339e": 20, "07634e": 20, "50410e": 20, "30000e": 20, "80264e": 20, "99008e": 20, "53791e": 20, "group": 20, "storag": 20, "locat": [20, 24, 25, 30, 31], "mark": 20, "portion": [20, 31], "glancing_angl": 20, "show": [20, 23, 24, 25, 27, 28, 29, 30, 31], "intenc": 20, "squar": [20, 21], "00000": [20, 23, 29], "03686180462340505": 20, "933": 20, "026": 20, "036": 20, "003": 20, "notic": 20, "NOT": 20, "i_": 20, "spot": 20, "30000": [20, 24], "278160358686800e": 20, "378767858296659e": 20, "396046839668212e": 20, "14": [20, 22, 23, 24], "342648818357391e": 20, "30": [20, 30], "697979700048016e": 20, "53": 20, "40000": 20, "778953628930054e": 20, "281839702773564e": 20, "108814173486245e": 20, "467220122612354e": 20, "252675318478533e": 20, "50": [20, 28], "50000": [20, 24, 28], "247181148723425e": 20, "671115124520428e": 20, "250758278908295e": 20, "632860054842994e": 20, "26": 20, "291667506376419e": 20, "47": 20, "sxrdcalc": [21, 22], "occup": 21, "deby": 21, "waller": 21, "site": 21, "unzip": 21, "makefil": 21, "environ": [21, 23], "auxiliari": 21, "sxrd_exec_fil": 21, "bulk_struc_in_fil": 21, "sic111": 21, "r3xr3": 21, "blk": 21, "scale_factor": 21, "opt_scale_factor": 21, "flag": 21, "type_vector": 21, "thei": [21, 28], "paramt": 21, "domain_occup": 21, "belong": 21, "duplic": 21, "pos_cent": 21, "y_0": 21, "\u306ffloat": 21, "dwfactor": 21, "text": 21, "\u00e5": 21, "displace_vector": 21, "displac": 21, "d_": 21, "i1": 21, "i2": 21, "i3": 21, "follw": 21, "l_": 21, "vari": 21, "dr_i": 21, "lattic": 21, "struc_in_fil": 21, "opt_dw": 21, "coeffici": 21, "opt_occup": 21, "si": [21, 23, 31], "00000000": 21, "33333333": 21, "66666667": 21, "f_in_fil": 21, "lock": [21, 25, 30], "l": [21, 31], "sigma": 21, "here": [21, 25, 28, 29, 30, 31], "wavenumb": 21, "050000": 21, "572": 21, "805262": 21, "150000": 21, "190": 21, "712559": 21, "114": 21, "163340": 21, "350000": 21, "81": 21, "267319": 21, "450000": 21, "62": 21, "927325": 21, "alpha": 21, "gamma": 21, "constant": 21, "cell": 21, "atomsymbol": 21, "r1": 21, "r2": 21, "r3": 21, "speci": [21, 23], "rate": 21, "sic": 21, "111": [21, 23], "33940": 21, "5510487": 21, "90": 21, "120": 21, "25000000": 21, "least": 21, "rfactor": 21, "shot": 21, "mapper_sxrd": 21, "rai": 21, "august": 21, "inputfil": 21, "lsfit": 21, "chi": 21, "10493110": 21, "323318": 21, "degre": [21, 23, 28, 29], "freedom": 21, "223257": 21, "666454": 21, "3707027": 21, "897897": 21, "78872": 21, "933998": 21, "378801": 21, "00000000000000": 21, "000196": 21, "nr": 21, "299467640982": 21, "406067": 21, "898402922947": 21, "218384": 21, "covari": 21, "0000000383": 21, "20107160": 21, "3315223120": 21, "60321480": 21, "9945669472": 21, "89680867995567253356544": 21, "0000000000": 21, "269042603986701827178496": 21, "807127811960105615753216": 21, "python": [22, 23, 28], "baysian": 22, "command": [22, 23, 25, 27, 29, 30], "pypi": 22, "git": [22, 31], "clone": [22, 31], "dev": 22, "higher": 22, "yourself": 22, "neighborhood": 23, "mesh": [23, 29], "bin": [23, 27], "neighborlist": 23, "txt": [23, 24, 25, 27, 28, 29, 30, 31], "meshdata": [23, 24, 29], "Or": 23, "unit1": 23, "unit2": 23, "dim": 23, "put": [23, 28], "whitespac": 23, "quot": 23, "radiu": 23, "node": 23, "euclidean": 23, "distanc": 23, "quiet": 23, "do": [23, 24, 25, 27, 28, 29, 30, 31, 32], "progress": 23, "bar": 23, "tqdm": 23, "selfloop": 23, "allpair": 23, "debug": 23, "quantum": 23, "espresso": 23, "qe": 23, "principl": 23, "isotetrahedr": 23, "bond": 23, "network": 23, "valid": 23, "microscop": 23, "elimin": 23, "influenc": 23, "dangl": 23, "deriv": 23, "opposit": 23, "interest": 23, "techniqu": 23, "hydrogen": 23, "termin": 23, "lowest": 23, "21": [23, 24, 30], "matplotlib": 23, "xyz": 23, "layer": 23, "next": [23, 27, 31, 32], "extract": 23, "bottom": 23, "adjust": 23, "tetrahedr": 23, "silan": 23, "molecul": 23, "cif": 23, "surf_bulk_new111": 23, "todft": 23, "content": [23, 24, 25, 28, 29, 30, 31], "219476": 23, "264930": 23, "459844": 23, "987850": 23, "800417": 23, "919830": 23, "404650": 23, "878903": 23, "839660": 23, "155740": 23, "900440": 23, "743910": 23, "597210": 23, "678750": 23, "759490": 23, "036250": 23, "input_xyz_fil": 23, "output_file_head": 23, "surf_bulk_new111_ext": 23, "z_margin": 23, "slab_margin": 23, "r_sih": 23, "48": 23, "angstrom": 23, "theta": 23, "109": 23, "unit_vec": 23, "67932": 23, "83966": 23, "solver_nam": 23, "kpt": 23, "monkhorst": 23, "pack": 23, "mpirun": 23, "pw": 23, "pwi": 23, "pwo": 23, "control": 23, "band": 23, "scf": 23, "realx": 23, "pseudo_dir": 23, "pseudopotenti": 23, "ecutwfc": 23, "cut": 23, "off": 23, "ry": 23, "nband": 23, "pbe": 23, "mt_fhi": 23, "upf": 23, "brief": 23, "z_min": 23, "size": 23, "slab": 23, "top": 23, "z_max": 23, "mathr": 23, "vertex": 23, "2d": [23, 25, 27, 29, 30], "plane": 23, "ab": 23, "initio": 23, "get_potential_energi": 23, "level": 23, "actual": [23, 25, 27, 28, 29, 30, 31], "0241": 23, "properti": 23, "po": 23, "pbc": 23, "208630": 23, "532925": 23, "visual": 23, "ordinari": 23, "xyzformat": 23, "3d": 23, "modifi": [23, 32], "accordingli": 23, "onlin": 23, "subscrib": [24, 25, 30], "single_beam": [24, 25, 28, 29, 30], "templat": [24, 25, 28, 29, 30], "ref_bayesdata": 24, "caluc": [24, 25, 30], "similar": 24, "previou": [24, 25, 29, 30], "speed": 24, "up": 24, "coodin": 24, "value_0": [24, 29], "value_1": [24, 29], "config": [24, 25, 28, 29, 30], "calculated_last_lin": [24, 25, 28, 29, 30], "74": [24, 25, 28, 29, 30], "row_numb": [24, 25, 28, 29, 30], "degree_max": [24, 25, 28, 29, 30], "70": [24, 25, 28, 29, 30], "insid": [24, 25, 28, 29, 30], "label": [24, 25, 28, 29, 30], "value_0x": [24, 25, 28, 29, 30], "hereinaft": [24, 25, 30], "cp": [24, 25, 28, 29, 30, 31], "few": [24, 25, 28, 29, 30], "py2dmat_main": [24, 25, 27, 28, 29, 30, 32], "tee": [24, 25, 27, 28, 29, 30], "90000": 24, "037237314010261195": 24, "0001": 24, "037237": 24, "action": 24, "150": 24, "subdirectori": 24, "bayesdata": 24, "seen": [24, 28, 29, 31], "fx_action": 24, "06050786306685965": 24, "06215778000834068": 24, "049210767760634364": 24, "08394457854191653": 24, "05556857782716691": 24, "0754639895013157": 24, "054757310814479355": 24, "06339787375966344": 24, "05348404677676544": 24, "03002813055356341": 24, "03019977423448576": 24, "02887504880071686": 24, "025865346123665988": 24, "02031077875240244": 24, "023291891689059388": 24, "16": 24, "02345999725278686": 24, "022561543431398066": 24, "18": 24, "02544527153306051": 24, "02778877135528466": 24, "012576357659158034": 24, "010217361468113488": 24, "22": [24, 31], "013178053637167673": 24, "highest": 24, "21th": 24, "batch": [24, 25, 28, 29, 30], "dat": [24, 28], "explan": [24, 25, 28, 29, 30], "echo": [24, 25, 27, 28, 29, 30], "diff": [24, 25, 27, 28, 29, 30], "re": [24, 25, 27, 28, 29, 30], "eq": [24, 25, 27, 28, 29, 30], "els": [24, 25, 27, 28, 29, 30], "fi": [24, 25, 27, 28, 29, 30], "gave": 24, "look": [24, 25, 29, 30], "rockingcurv": [24, 25, 28, 29, 30], "compar": [24, 25, 27, 28, 29, 30], "doc": 24, "ref": [25, 27, 28, 29, 30], "12345": [25, 27, 30, 32], "1000": [25, 27], "005": 25, "briefli": [25, 30], "mpiexec": [25, 27, 29, 30], "request": [25, 30], "oversubscrib": [25, 27, 30], "trial": [25, 27, 30], "x2": [25, 27, 32], "best_result": [25, 27, 30], "fill": [25, 30], "separatet": 25, "rearrang": 25, "reorgan": 25, "result_t": [25, 30], "illustr": [25, 30], "region": [25, 29, 30], "small": [25, 29, 30], "figur": [25, 27, 28, 29, 30], "png": [25, 28, 29, 31], "plot_result_2d": [25, 30], "diagram": [25, 29, 30], "concentr": [25, 30], "horizont": [25, 30], "vertic": [25, 30, 31], "logxxx_yyi": [25, 30], "yyi": [25, 30], "sim_trhepd_rhe": 26, "prof": 26, "takashi": 26, "deal": 26, "plausibl": 26, "nealder": [26, 29], "entir": 26, "sequenti": [26, 28], "express": 27, "himmelblau": [27, 32], "correctli": [27, 28, 29], "onc": 27, "explain": [27, 28, 29, 32], "attempt": 27, "pc": [27, 28, 29], "openmpi": 27, "greater": 27, "core": 27, "within": 27, "187": 27, "94429125133564": 27, "155393113805774": 27, "203493345018569": 27, "148": 27, "23606736778044": 27, "9995614992887525": 27, "370212436322816": 27, "4523": 27, "00010188398524402734": 27, "584944906595298": 27, "8506985826548874": 27, "addition": 27, "bash": 27, "confirm": 27, "hist2d_limitation_sampl": 27, "histogram": 27, "posterior": 27, "date": [27, 31], "_histogram": 27, "discard": 27, "burn": 27, "analyz": [28, 29, 32], "fmin": 28, "proce": [28, 29], "seek": 28, "almost": 28, "know": 28, "z_x": 28, "equival": 28, "suft": 28, "those": 28, "found": [28, 29], "produc": [28, 29], "judgment": 28, "25000": 28, "lastlin": [28, 29], "len": [28, 29], "calculated_list": [28, 29], "convolution_i_calculated_list": [28, 29], "logxxxxx": 28, "xxxxxx": 28, "logxxxx_00000001": 28, "xxxx": 28, "draw_rc_doubl": 28, "log00000001_00000001": 28, "rockingcurve_ini": 28, "log00000062_00000001": 28, "rockingcurve_con": 28, "rc_doubl": 28, "red": 28, "circl": 28, "blue": 28, "green": 28, "agre": 28, "compat": 29, "howev": 29, "ref_colormap": 29, "colormap": 29, "reduc": 29, "go": 29, "attach": 29, "04785241875354398": 29, "072739": 29, "colormapfig": 29, "plot_colormap_2d": 29, "around": 29, "tnum": 30, "trial_txxx": 30, "result_txxx": 30, "concatn": 30, "07702743614780189": 30, "788848278451443": 30, "949126663745358": 30, "08737730661436376": 30, "551756435031283": 30, "6136808356591192": 30, "04954470587051104": 30, "70317508724506": 30, "786634108937754": 30, "04671675601156148": 30, "893543559206865": 30, "959531290614713": 30, "04142014655238446": 30, "246719912601735": 30, "960709612555206": 30, "71": 30, "008186713312593607": 30, "225633749839847": 30, "142666117413409": 30, "06428002079611472": 30, "002703413400677839": 30, "795": 30, "061399304916174735": 30, "002649424392996749": 30, "6280819199879947": 30, "85": 30, "05904248889111052": 30, "0031622711212952034": 30, "2283060742855603": 30, "04956921148431115": 30, "0028298565759159633": 30, "7991035905899855": 30, "67": 30, "result_fx": 30, "pdf": 30, "color": 30, "symbol": 30, "fast": 31, "jpn": 31, "176": 31, "1983": 31, "24": 31, "1365": 31, "1985": 31, "web": 31, "repositori": 31, "build": 31, "md": 31, "surfyyyymmdd": 31, "hhmmsslog": 31, "yyyymmdd": 31, "hhmmss": 31, "azimuth": 31, "56": 31, "ih": 31, "ik": 31, "5000e": 31, "0000e": 31, "1595e": 31, "6000e": 31, "1870e": 31, "7000e": 31, "2121e": 31, "8000e": 31, "2171e": 31, "1927e": 31, "9000e": 31, "4397e": 31, "1700e": 31, "1000e": 31, "6326e": 31, "1495e": 31, "axi": 31, "row": 31, "peak": 31, "eighth": 31, "gnuplot": 31, "graph": 31, "plot_bulkp": 31, "2x1": 31, "make_convolut": 31, "010818010": 31, "600000": 31, "013986716": 31, "700000": 31, "016119093": 31, "800000": 31, "017039022": 31, "900000": 31, "017084666": 31, "skip": [31, 32], "000728539": 31, "000530758": 31, "000412908": 31, "000341740": 31, "000277553": 31, "view": 31, "easiest": 32, "booth": 32, "2y": 32, "2x": 32, "instruct": 32, "def": 32, "global": 32, "shape": 32, "rais": 32, "runtimeerror": 32, "receiv": 32, "insert": 32, "branch": 32, "elif": 32, "set_funct": 32, "38": 32, "0000128043523089": 32, "9999832920260863": 32}, "objects": {}, "objtypes": {}, "objnames": {}, "titleterms": {"acknowledg": 0, "bays": 1, "optim": [1, 24, 25, 28, 30], "bay": 1, "prepar": [1, 2, 4, 5, 6, 19, 20, 21], "input": [1, 2, 4, 5, 6, 14, 17, 19, 20, 21, 24, 25, 27, 28, 29, 30], "paramet": [1, 2, 4, 5, 6, 17, 19, 20, 21], "algorithm": [1, 2, 3, 6, 8, 10, 14], "param": [1, 2, 4, 5, 6, 20, 21, 23], "section": [1, 4, 5, 14, 19, 20, 21, 23], "refer": [1, 2, 6, 19, 20, 21, 24, 25, 28, 29, 30], "file": [1, 2, 4, 5, 6, 14, 16, 19, 20, 21, 24, 25, 27, 28, 29, 30], "mesh": [1, 2, 4, 6], "definit": [1, 2, 4, 6], "output": [1, 2, 4, 5, 6, 16, 19, 20, 21], "bayesdata": 1, "txt": [1, 2, 4, 5, 6, 20], "descript": 1, "replica": [2, 25, 27], "exchang": [2, 25, 27], "mont": [2, 6, 25, 27], "carlo": [2, 6, 25, 27], "neighborhood": [2, 6], "list": [2, 6], "rank": [2, 6], "trial": [2, 6], "result": [2, 6, 27, 28, 29, 31], "best_result": [2, 6], "result_t": [2, 6], "markov": 2, "chain": 2, "search": [3, 4, 27, 29], "direct": [4, 18, 31, 32], "parallel": 4, "mapper": 4, "refernc": 4, "colormap": 4, "nelder": [5, 28], "mead": [5, 28], "method": [5, 28], "minsearch": 5, "minim": 5, "simplexdata": 5, "re": 5, "popul": [6, 30], "anneal": [6, 30], "pamc": 6, "about": 6, "number": 6, "step": 6, "trial_t": 6, "fx": 6, "goal": 6, "import": 6, "sampl": [6, 24, 25, 27, 28, 29, 30], "ai": 6, "1": 6, "pa": 6, "2": 6, "contact": 7, "algorithmbas": 8, "common": [9, 16], "py2dmat": [9, 22], "info": 9, "messag": 9, "runner": [9, 14, 16], "For": 10, "develop": [10, 15], "user": 10, "defin": 10, "solver": [10, 11, 14, 17, 18, 19, 20, 21, 23, 31, 32], "usag": [12, 23], "welcom": 13, "2dmat": [13, 15], "": 13, "document": 13, "content": 13, "base": 14, "map": 14, "limit": [14, 27], "log": [14, 16], "introduct": 15, "what": 15, "i": 15, "licens": 15, "version": 15, "inform": 15, "main": [15, 23], "time": 16, "analyt": [17, 32], "problem": [18, 31, 32], "leed": 19, "config": [19, 20, 21], "target": [19, 20, 21], "sim": 20, "trhepd": [20, 31], "rheed": 20, "subsect": [20, 21], "post": [20, 25], "templat": 20, "stdout": [20, 21], "rockingcurve_calcul": 20, "sxrd": 21, "domain": 21, "atom": 21, "bulk": 21, "structur": 21, "instal": [22, 31], "prerequisit": [22, 23], "how": 22, "download": [22, 31], "run": 22, "uninstal": 22, "relat": 23, "tool": 23, "py2dmat_neighborlist": 23, "to_dft": 23, "py": 23, "overview": 23, "thi": 23, "tutori": [23, 26], "lattic": 23, "ASE": 23, "bayesian": 24, "calcul": [24, 25, 27, 28, 29, 30, 31], "visual": [24, 25, 27, 28, 29, 30, 31], "process": 25, "locat": [27, 28, 29], "The": 28, "execut": [28, 29, 31], "grid": 29, "addit": 32, "benchmark": 32}, "envversion": {"sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx": 60}, "alltitles": {"Acknowledgements": [[0, "acknowledgements"]], "Bayse optimization bayes": [[1, "bayse-optimization-bayes"]], "Preparation": [[1, "preparation"], [2, "preparation"], [4, "preparation"], [5, "preparation"], [6, "preparation"], [19, "preparation"], [20, "preparation"], [21, "preparation"]], "Input parameters": [[1, "input-parameters"], [2, "input-parameters"], [4, "input-parameters"], [5, "input-parameters"], [6, "input-parameters"], [17, "input-parameters"], [19, "input-parameters"], [20, "input-parameters"], [21, "input-parameters"]], "[algorithm.param] section": [[1, "algorithm-param-section"]], "[algorithm.bayes] section": [[1, "algorithm-bayes-section"]], "Reference file": [[1, "reference-file"], [2, "reference-file"], [6, "reference-file"], [20, "reference-file"], [29, "reference-file"]], "Mesh definition file": [[1, "mesh-definition-file"], [2, "mesh-definition-file"], [4, "mesh-definition-file"], [6, "mesh-definition-file"]], "Output files": [[1, "output-files"], [2, "output-files"], [5, "output-files"], [6, "output-files"], [16, "output-files"], [21, "output-files"]], "BayesData.txt": [[1, "bayesdata-txt"]], "Algorithm Description": [[1, "algorithm-description"]], "Replica exchange Monte Carlo exchange": [[2, "replica-exchange-monte-carlo-exchange"]], "[algorithm.param]": [[2, "algorithm-param"], [6, "algorithm-param"]], "[algorithm.exchange]": [[2, "algorithm-exchange"]], "Neighborhood-list file": [[2, "neighborhood-list-file"], [6, "neighborhood-list-file"]], "RANK/trial.txt": [[2, "rank-trial-txt"], [6, "rank-trial-txt"]], "RANK/result.txt": [[2, "rank-result-txt"], [6, "rank-result-txt"]], "best_result.txt": [[2, "best-result-txt"], [6, "best-result-txt"]], "result_T#.txt": [[2, "result-t-txt"]], "Algorithm": [[2, "algorithm"], [6, "algorithm"], [8, "algorithm"], [8, "id1"]], "Markov chain Monte Carlo": [[2, "markov-chain-monte-carlo"]], "Replica exchange Monte Carlo": [[2, "replica-exchange-monte-carlo"]], "Search algorithms": [[3, "search-algorithms"]], "Direct parallel search mapper": [[4, "direct-parallel-search-mapper"]], "[param] section": [[4, "param-section"], [5, "param-section"], [21, "param-section"]], "Refernce file": [[4, "refernce-file"]], "Output file": [[4, "output-file"], [19, "output-file"], [20, "output-file"]], "ColorMap.txt": [[4, "colormap-txt"]], "Nelder-Mead method minsearch": [[5, "nelder-mead-method-minsearch"]], "[minimize] section": [[5, "minimize-section"]], "SimplexData.txt": [[5, "simplexdata-txt"]], "res.txt": [[5, "res-txt"]], "Population Annealing Monte Carlo pamc": [[6, "population-annealing-monte-carlo-pamc"]], "[algorithm.pamc]": [[6, "algorithm-pamc"]], "About the number of steps": [[6, "about-the-number-of-steps"]], "RANK/trial_T#.txt": [[6, "rank-trial-t-txt"]], "RANK/result_T#.txt": [[6, "rank-result-t-txt"]], "fx.txt": [[6, "fx-txt"]], "Goal": [[6, "goal"]], "Annealed Importance Sampling (AIS) [1]": [[6, "annealed-importance-sampling-ais-1"]], "population annealing (PA) [2]": [[6, "population-annealing-pa-2"]], "References": [[6, "references"]], "Contact": [[7, "contact"]], "AlgorithmBase": [[8, "algorithmbase"]], "Commons": [[9, "commons"]], "py2dmat.Info": [[9, "py2dmat-info"]], "py2dmat.Message": [[9, "py2dmat-message"]], "py2dmat.Runner": [[9, "py2dmat-runner"]], "(For developers) User-defined algorithm and solver": [[10, "for-developers-user-defined-algorithm-and-solver"]], "Solver": [[11, "solver"]], "Usage": [[12, "usage"], [23, "usage"]], "Welcome to 2DMAT\u2019s documentation!": [[13, "welcome-to-2dmat-s-documentation"]], "Contents:": [[13, null]], "Input file": [[14, "input-file"], [28, "input-file"], [29, "input-file"]], "[base] section": [[14, "base-section"]], "[solver] section": [[14, "solver-section"], [20, "solver-section"]], "[algorithm] section": [[14, "algorithm-section"]], "[runner] section": [[14, "runner-section"]], "[mapping] section": [[14, "mapping-section"]], "[limitation] section": [[14, "limitation-section"]], "[log] section": [[14, "log-section"]], "Introduction": [[15, "introduction"]], "What is 2DMAT ?": [[15, "what-is-2dmat"]], "License": [[15, "license"]], "Version Information": [[15, "version-information"]], "Main developers": [[15, "main-developers"]], "Common file": [[16, "common-file"]], "time.log": [[16, "time-log"]], "runner.log": [[16, "runner-log"]], "analytical solver": [[17, "analytical-solver"]], "Direct Problem Solver": [[18, "direct-problem-solver"]], "leed solver": [[19, "leed-solver"]], "[config] section": [[19, "config-section"], [21, "config-section"]], "[reference] section": [[19, "reference-section"], [21, "reference-section"]], "Reference file for Solver": [[19, "reference-file-for-solver"], [21, "reference-file-for-solver"]], "Target reference file": [[19, "target-reference-file"], [21, "target-reference-file"]], "sim-trhepd-rheed solver": [[20, "sim-trhepd-rheed-solver"]], "[solver.config] subsection": [[20, "solver-config-subsection"]], "[solver.post] subsection": [[20, "solver-post-subsection"]], "[solver.param] subsection": [[20, "solver-param-subsection"]], "[solver.reference] subsection": [[20, "solver-reference-subsection"]], "Input template file": [[20, "input-template-file"]], "Target file": [[20, "target-file"]], "stdout": [[20, "stdout"], [21, "stdout"]], "RockingCurve_calculated.txt": [[20, "rockingcurve-calculated-txt"]], "sxrd solver": [[21, "sxrd-solver"]], "[param.domain] subsection": [[21, "param-domain-subsection"]], "[param.domain.atom] subsection": [[21, "param-domain-atom-subsection"]], "Bulk structure file": [[21, "bulk-structure-file"]], "Install of py2dmat": [[22, "install-of-py2dmat"]], "Prerequisites": [[22, "prerequisites"], [23, "prerequisites"]], "How to download and install": [[22, "how-to-download-and-install"]], "How to run": [[22, "how-to-run"]], "How to uninstall": [[22, "how-to-uninstall"]], "Related Tools": [[23, "related-tools"]], "py2dmat_neighborlist": [[23, "py2dmat-neighborlist"]], "tool/to_dft/to_dft.py": [[23, "tool-to-dft-to-dft-py"]], "Overview of this tool": [[23, "overview-of-this-tool"]], "Tutorial": [[23, "tutorial"]], "Main section": [[23, "main-section"]], "Main.Param section": [[23, "main-param-section"]], "Main.lattice section": [[23, "main-lattice-section"]], "ASE section": [[23, "ase-section"]], "Solver section": [[23, "solver-section"]], "Optimization by Bayesian Optimization": [[24, "optimization-by-bayesian-optimization"]], "Sample files": [[24, "sample-files"], [25, "sample-files"], [30, "sample-files"]], "Reference files": [[24, "reference-files"], [25, "reference-files"], [30, "reference-files"]], "Input files": [[24, "input-files"], [25, "input-files"], [27, "input-files"], [30, "input-files"]], "Calculation": [[24, "calculation"], [25, "calculation"], [27, "calculation"], [30, "calculation"]], "Visualization": [[24, "visualization"], [25, "visualization"], [30, "visualization"]], "Optimization by replica exchange Monte Carlo": [[25, "optimization-by-replica-exchange-monte-carlo"]], "Post process": [[25, "post-process"]], "Tutorials": [[26, "tutorials"]], "Replica Exchange Monte Carlo search with limitation": [[27, "replica-exchange-monte-carlo-search-with-limitation"]], "Sample files location": [[27, "sample-files-location"]], "Visualization of the calculation result": [[27, "visualization-of-the-calculation-result"]], "Optimization by Nelder-Mead method": [[28, "optimization-by-nelder-mead-method"]], "Location of the sample files": [[28, "location-of-the-sample-files"], [29, "location-of-the-sample-files"]], "The reference file": [[28, "the-reference-file"]], "Calculation execution": [[28, "calculation-execution"], [29, "calculation-execution"], [31, "calculation-execution"]], "Visualization of calculation results": [[28, "visualization-of-calculation-results"], [29, "visualization-of-calculation-results"]], "Grid search": [[29, "grid-search"]], "Optimization by population annealing": [[30, "optimization-by-population-annealing"]], "TRHEPD Direct Problem Solver": [[31, "trhepd-direct-problem-solver"]], "Download and Install": [[31, "download-and-install"]], "Visualization of calculation result": [[31, "visualization-of-calculation-result"]], "Addition of a direct problem solver": [[32, "addition-of-a-direct-problem-solver"], [32, "id1"]], "Solver for benchmarking, analytical": [[32, "solver-for-benchmarking-analytical"]]}, "indexentries": {}}) \ No newline at end of file diff --git a/manual/v2.2.0/en/solver/analytical.html b/manual/v2.2.0/en/solver/analytical.html new file mode 100644 index 00000000..c6f99169 --- /dev/null +++ b/manual/v2.2.0/en/solver/analytical.html @@ -0,0 +1,113 @@ + + + + + + + + analytical solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

analytical solver

+

analytical is a Solver that computes a predefined benchmark function \(f(x)\) for evaluating the performance of search algorithms.

+
+

Input parameters

+

The funtion_name parameter in the solver section specifies the function to use.

+
    +

  • function_name

    +

    Format: string

    +

    Description: Function name. The following functions are available.

    +
      +

    • quadratics

      +
        +

      • Quadratic function

        +
        +\[f(\vec{x}) = \sum_{i=1}^N x_i^2\]
        +
        • +

      • The optimized value \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • rosenbrock

      + +
      +\[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 \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)\)

        • +
      +
      • +

    • ackley

      + +
      +\[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 \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • himmerblau

      + +
      +\[f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2\]
      +
        +

      • The optimized value \(f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0\)

        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/solver/index.html b/manual/v2.2.0/en/solver/index.html new file mode 100644 index 00000000..56f14e4d --- /dev/null +++ b/manual/v2.2.0/en/solver/index.html @@ -0,0 +1,70 @@ + + + + + + + + Direct Problem Solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Direct Problem Solver

+

Direct problem solver Solver calculates the function to be optimized \(f(x)\) at the search parameter \(x\).

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/solver/leed.html b/manual/v2.2.0/en/solver/leed.html new file mode 100644 index 00000000..16427f1f --- /dev/null +++ b/manual/v2.2.0/en/solver/leed.html @@ -0,0 +1,147 @@ + + + + + + + + leed solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

leed solver

+

leed is a Solver made by M.A. Van Hove, which calculates the Rocking curve from atomic positions etc., using SATLEED, and returns the error from the experimental Rocking curve as \(f(x)\). +For more information on SATLEED, see [SATLEED].

+
+
+[SATLEED] +

M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). https://doi.org/10.1016/0167-5729(93)90011-D

+
+
+
+

Preparation

+

First, install SATLEED . +Access to the following URL +http://www.icts.hkbu.edu.hk/VanHove_files/leed/leedsatl.zip +and download a zip file. +Depending on the details of the system you want to calculate, it is necessary to change the parameters in the source code for SATLEED. +After changing parameters, compile programs to generate the executable files such as stal1.exe, satl2.exe .

+

For trying the example at sample/py2dmat/leed, a utility script file setup.sh for downloading SATLEED, rewriting source codes, and compiling the program is available.:

+
$ cd sample/py2dmat/leed
+$ sh ./setup.sh
+
+
+

After running setup.sh, executable files satl1.exe and satl2.exe are generated in leedsatl directory.

+

Note that it is assumed that you have already executed satl1.exe before using py2dmat . +Therefore, the following files must be generated.

+
    +

  • Input files of satl1.exe : exp.d, rfac.d, tleed4.i, tleed5.i

    • +

  • Output files of satl1.exe : tleed.o , short.t

    • +
+

py2dmat will run satl2.exe based on the above files.

+
+
+

Input parameters

+

Input parameters are specified in subsections in the solver section (config and reference).

+
+

[config] section

+
    +

  • path_to_solver

    +

    Format: string

    +

    Description: Path to the solver satl2.exe .

    +
    • +
+
+
+

[reference] section

+
    +

  • path_to_base_dir

    +

    Format: string

    +

    Description: Path to the directory which stores exp.d, rfac.d, tleed4.i, tleed5.i , tleed.o , short.t .

    +
    • +
+
+
+
+

Reference file for Solver

+
+

Target reference file

+

The file containing the data to be targeted to fit. Edit tleed4.i in path_to_base_dir in the [reference] section. +Add the number you want to optimize to optxxx (where xxx is a three-digit number in the format 000, 001, 002, …). (where xxx is a three-digit integer in the form 000, 001, 002, …). +Note that the number of xxx must match the order and number of variables in the list of py2dmat variables to be optimized. +Note that if IFLAG and LSFLAG are not set to 0, the satleed side is also optimized.

+

An example file is shown below.

+
1  0  0                          IPR ISTART LRFLAG
+1 10  0.02  0.2                  NSYM  NSYMS ASTEP VSTEP
+5  1  2  2                       NT0  NSET LSMAX LLCUT
+5                                NINSET
+1.0000 0.0000                  1      PQEX
+1.0000 2.0000                  2      PQEX
+1.0000 1.0000                  3      PQEX
+2.0000 2.0000                  4      PQEX
+2.0000 0.0000                  5      PQEX
+3                                 NDIM
+opt000 0.0000 0.0000  0           DISP(1,j)  j=1,3
+0.0000 opt001 0.0000  0           DISP(2,j)  j=1,3
+0.0000 0.0000 0.0000  1           DISP(3,j)  j=1,3
+0.0000 0.0000 0.0000  0           DISP(4,j)  j=1,3
+0.0000  0                         DVOPT  LSFLAG
+3  0  0                           MFLAG NGRID NIV
+...
+
+
+
+
+
+

Output file

+

In leed, the output files are stored in the folder with the rank number.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/solver/sim-trhepd-rheed.html b/manual/v2.2.0/en/solver/sim-trhepd-rheed.html new file mode 100644 index 00000000..ef4465e9 --- /dev/null +++ b/manual/v2.2.0/en/solver/sim-trhepd-rheed.html @@ -0,0 +1,339 @@ + + + + + + + + sim-trhepd-rheed solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

sim-trhepd-rheed solver

+

sim-trhepd-rheed is a Solver that uses sim-trhepd-rheed to calculate the diffraction rocking curve from the atomic position \(x\) and returns the deviation from the experimental rocking curve as \(f(x)\).

+
+

Preparation

+

You will need to install sim-trhepd-rheed beforehand.

+
    +

  1. Download the source code from the official sim-trhepd-rheed website.

    2. +

  2. Move to sim-trhepd-rheed/src folder and make bulk.exe and surf.exe by using make.

    3. +
+

Before running py2dmat, run bulk.exe to create the bulk data. +The surf.exe is called from py2dmat.

+
+
+

Input parameters

+

Input parameters can be specified in subsections config, post, param, reference in solver section.

+
+

[solver] section

+
    +

  • generate_rocking_curve

    +

    Format: boolean (default: false)

    +

    Description: Whether to generate RockingCurve_calculated.txt. +If true, RockingCurve_calculated.txt will be generated in the working directory Log%%%_###. +Note that if remove_work_dir (in [post] subsection) is true, Log%%%_### will be removed.

    +
    • +
+
+
+

[solver.config] subsection

+
    +

  • surface_exec_file

    +

    Format: string (default: “surf.exe”)

    +

    Description: Path to sim-trhepd-rheed surface reflection solver surf.exe.

    +
    • +

  • surface_input_file

    +

    Format: string (default: “surf.txt”)

    +

    Description: Input file for surface structure.

    +
    • +

  • bulk_output_file

    +

    Format: string (default: “bulkP.b”)

    +

    Description: Output file for bulk structure.

    +
    • +

  • surface_output_file

    +

    Format: string (default: “surf-bulkP.s”)

    +

    Description: Output file for surface structure.

    +
    • +

  • calculated_first_line

    +

    Format: integer (default: 5)

    +

    Description: In the output file, the first line to be read as D(x). +The last line is automatically calculated from the number of the reference data.

    +
    • +

  • calculated_info_line

    +

    Format: integer (default: 2)

    +

    Description: In the output file, the line contains the information of the calculated data – the number of glancing angles (second column) and the number of beams (third column).

    +
    • +

  • cal_number

    +

    Format: Integer or List of integers

    +

    Description: In the output file, the columns to be read as D(x). Multiple columns can be specified (many-beam condition).

    +
    • +
+
+
+

[solver.post] subsection

+

This subsection is used to the postprocess – to specify how to calculate the objective function, that is, the deviation between the experimental and computational data, and to draw the rocking curve.

+
    +

  • Rfactor_type

    +

    Format: string (“A” or “B”, default: “A”)

    +

    Description: This parameter specifies how to calculate the R-factor to be minimized. +Let \(n\) be the number of dataset, \(m\) be the number of glancing angles, and \(v^{(n)} = (v^{(n)}_{1}, v^{(n)}_{2}, \dots ,v^{(n)}_{m})\) be the calculated data. +With the weights of the beams, \(w^{(j)}\), R-factors is defined as follows:

    +
    +
      +

    • “A” type:

      +
      +\[R = \sqrt{ \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2} }\]
      +
      • +

    • “A2” type:

      +
      +\[R^{2} = \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2}\]
      +
      • +

    • “B” type:

      +
      +\[R = \frac{\sum_{i}^{m} \left(u^{(1)}_{i}-v^{(1)}_{i}\right)^{2}}{\sum_{i}^{m} \left(u^{(1)}_{i}\right)^{2} + \sum_{i}^{m} (v^{(1)}_{i})^2}\]
      +
        +

      • “B” type is available only for the single dataset (\(n=1\)).

        • +
      +
      • +
    +
    +
    • +

  • normalization

    +

    Format: string (“TOTAL” or “MANY_BEAM”)

    +

    Description: This parameter specifies how to normalize the experimental and computational data vectors.

    +
      +

    • “TOTAL”

      +
        +

      • To normalize the data as the summation is 1.

        • +

      • The number of dataset should be one (the number of cal_number should be one).

        • +
      +
      • +

    • “MANY_BEAM”

      +
        +

      • To normalize with weights as specified by weight_type.

        • +
      +
      • +
    +

    NOTE: “MAX” is no longer available

    +
    • +

  • weight_type

    +

    Format: string or None. “calc” or “manual” (default: None)

    +

    Description: The weights of the datasets for the “MANY_BEAM” normalization.

    +
      +

    • “calc”

      • +
    +
    +\[w^{(n)} = \left(\frac{\sum_i^m v^{(n)}_{i}}{\sum_j^n \sum_i^m v^{(j)}_i} \right)^2\]
    +
      +

    • “manual”

      • +
    +

    \(w^{(n)}\) is specified by spot_weight.

    +
    • +

  • spot_weight

    +

    Format: list of float (mandatory when weight_type is “manual”)

    +

    Description: The weights of the beams in the calculation of R-factor. +The weights are automatically normalized as the sum be 1. +For example, [3,2,1] means \(w^{(1)}=1/2, w^{(2)}=1/3, w^{(3)}=1/6\).

    +
    • +

  • omega

    +

    Format: float (default: 0.5)

    +

    Description: This parameter specifies the half-width of convolution.

    +
    • +

  • remove_work_dir

    +

    Format: boolean (default: false)

    +

    Description: Whether to remove working directories Log%%%_### after reading R-factor or not

    +
    • +
+
+
+

[solver.param] subsection

+
    +

  • string_list

    +

    Format: list of string. The length should match the value of dimension (default: [“value_01”, “value_02”]).

    +

    Description: List of placeholders to be used in the reference template file to create the input file for the solver. These strings will be replaced with the values of the parameters being searched for.

    +
    • +
+
+
+

[solver.reference] subsection

+
    +

  • path

    +

    Format: string (default: experiment.txt)

    +

    Description: Path to the reference data file.

    +
    • +

  • reference_first_line

    +

    Format: integer

    +

    Description: In the reference data file, the first line to be read as Dexp. The default value is 1, that is, the first line of the file.

    +
    • +

  • reference_last_line

    +

    Format: integer

    +

    Description: In the reference data file, the last line to be read as Dexp. If omitted, all lines from the first line to the end of the file will be read.

    +
    • +

  • exp_number

    +

    Format: Integer or List of integers

    +

    Description: In the reference data file, the column numbers to be read. Multiple columns can be specified (many-beam condition).

    +
    • +
+
+
+
+

Reference file

+
+

Input template file

+

The input template file template.txt is a template for creating an input file for surf.exe. +The parameters to be moved in py2dmat (such as the atomic coordinates you want to find) should be replaced with the appropriate string, such as value_*. +The strings to be used are specified by string_list in the [solver] - [param] section of the input file for the solver. +An example template is shown below.

+
2                                    ,NELMS,  -------- Ge(001)-c4x2
+32,1.0,0.1                           ,Ge Z,da1,sap
+0.6,0.6,0.6                          ,BH(I),BK(I),BZ(I)
+32,1.0,0.1                           ,Ge Z,da1,sap
+0.4,0.4,0.4                          ,BH(I),BK(I),BZ(I)
+9,4,0,0,2, 2.0,-0.5,0.5               ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS
+8                                    ,NATM
+1, 1.0, 1.34502591  1       value_01   ,IELM(I),ocr(I),X(I),Y(I),Z(I)
+1, 1.0, 0.752457792 1       value_02
+2, 1.0, 1.480003343 1.465005851     value_03
+2, 1.0, 2   1.497500418     2.281675
+2, 1.0, 1   1.5     1.991675
+2, 1.0, 0   1       0.847225
+2, 1.0, 2   1       0.807225
+2, 1.0, 1.009998328 1       0.597225
+1,1                                  ,(WDOM,I=1,NDOM)
+
+
+

In this case, value_01, value_02, and value_03 are the parameters to be moved in py2dmat.

+
+
+

Target file

+

This file (experiment.txt) contains the data to be targeted. +The first column contains the angle, and the second and following columns contain the calculated value of the reflection intensity multiplied by the weight. +An example of the file is shown below.

+
3.00000e-01 8.17149e-03 1.03057e-05 8.88164e-15 ...
+4.00000e-01 1.13871e-02 4.01611e-05 2.23952e-13 ...
+5.00000e-01 1.44044e-02 1.29668e-04 4.53633e-12 ...
+6.00000e-01 1.68659e-02 3.49471e-04 7.38656e-11 ...
+7.00000e-01 1.85375e-02 7.93037e-04 9.67719e-10 ...
+8.00000e-01 1.93113e-02 1.52987e-03 1.02117e-08 ...
+9.00000e-01 1.92590e-02 2.53448e-03 8.69136e-08 ...
+1.00000e+00 1.86780e-02 3.64176e-03 5.97661e-07 ...
+1.10000e+00 1.80255e-02 4.57932e-03 3.32760e-06 ...
+1.20000e+00 1.77339e-02 5.07634e-03 1.50410e-05 ...
+1.30000e+00 1.80264e-02 4.99008e-03 5.53791e-05 ...
+...
+
+
+
+
+
+

Output file

+

For sim-trhepd-rheed, the files output by surf.exe will be output in the Log%%%%%_##### folder under the folder with the rank number. +%%%%% means an index of iteration in Algorithm (e.g., steps in Monte Carlo), +and ##### means an index of group (e.g., replica index in Monte Carlo). +In large calculation, the number of these folders becomes too large to be written in the storage of the system. +For such a case, let solver.post.remove_work_dir parameter be true in order to remove these folders. +This section describes the own files that are output by this solver.

+
+

stdout

+

It contains the standard output of surf.exe. +An example is shown below.

+
bulk-filename (end=e) ? :
+bulkP.b
+structure-filename (end=e) ? :
+surf.txt
+output-filename :
+surf-bulkP.s
+
+
+
+
+

RockingCurve_calculated.txt

+

This file is located in the Log%%%%%_##### folder. +At the beginning of the file, the lines beginning with # are headers. +The header contains the values of the input variables, the objective function value f(x), the parameters Rfactor_type, normalization, weight_type, cal_number, spot_weight, and what is marked in the data portion columns (e.g. # #0 glancing_angle).

+

The header is followed by the data. +The first column shows the glancing angle, and the second and subsequent columns show the intensity of each data column. +You can see which data columns are marked in the header. For example,

+
# #0 glancing_angle
+# #1 cal_number=1
+# #2 cal_number=2
+# #3 cal_number=4
+
+
+

shows that the first column is the glancing angle, and the second, third, and fourth columns are the calculated data corresponding to the first, second, and fourth columns of the calculated data file, respectively.

+

Intencities in each column are normalized so that the sum of the intensity is 1. +To calculate the objective function value (R-factor and R-factor squared), the data columns are weighted by spot_weight and normalized by normalization.

+
#value_01 =  0.00000 value_02 =  0.00000
+#Rfactor_type = A
+#normalization = MANY_BEAM
+#weight_type = manual
+#fx(x) = 0.03686180462340505
+#cal_number = [1, 2, 4, 6, 8]
+#spot_weight = [0.933 0.026 0.036 0.003 0.002]
+#NOTICE : Intensities are NOT multiplied by spot_weight.
+#The intensity I_(spot) for each spot is normalized as in the following equation.
+#sum( I_(spot) ) = 1
+#
+# #0 glancing_angle
+# #1 cal_number=1
+# #2 cal_number=2
+# #3 cal_number=4
+# #4 cal_number=6
+# #5 cal_number=8
+0.30000 1.278160358686800e-02 1.378767858296659e-04 8.396046839668212e-14 1.342648818357391e-30 6.697979700048016e-53
+0.40000 1.778953628930054e-02 5.281839702773564e-04 2.108814173486245e-12 2.467220122612354e-28 7.252675318478533e-50
+0.50000 2.247181148723425e-02 1.671115124520428e-03 4.250758278908295e-11 3.632860054842994e-26 6.291667506376419e-47
+...
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/solver/sxrd.html b/manual/v2.2.0/en/solver/sxrd.html new file mode 100644 index 00000000..f5ef4bfd --- /dev/null +++ b/manual/v2.2.0/en/solver/sxrd.html @@ -0,0 +1,285 @@ + + + + + + + + sxrd solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

sxrd solver

+

sxrd is a Solver that uses sxrdcalc to calculate the Rocking curve by giving atomic positions \(x\) , atomic occupancies, and Debye-Waller factor and finally returnes the error \(f(x)\) from the experimental Rocking curve.

+
+

Preparation

+

The sxrdcalc is called from py2dmat. +You will need to install sxrdcalc beforehand. +sxrdcalc is available on GitHub at the following URL:

+

https://github.com/sxrdcalc/sxrdcalc

+

Access the site and download the source code from “Code” - “Download zip”. +After unzipping the zip file, edit the Makefile to fit your computing environment, and then type make to create the sxrdcalc executable.

+

It is noted that the bulk data must be prepared in advance before running py2dmat (see the auxiliary file for solvers below for the format).

+
+
+

Input parameters

+

Input parameters are specified in subsections in the solver section (config, post, param, and reference).

+
+

[config] section

+
    +

  • sxrd_exec_file

    +

    Format: string

    +

    Description: Path to the solver sxrdcalc.

    +
    • +

  • bulk_struc_in_file

    +

    Format: string

    +

    Description: Input file name of the bulk structure.

    +
    • +
+
+

An example of the input input is given as follows:

+
+
[config]
+sxrd_exec_file = "../../sxrdcalc"
+bulk_struc_in_file = "sic111-r3xr3.blk"
+
+
+
+
+

[param] section

+
    +

  • scale_factor

    +

    Format: float (default: 1.0)

    +

    Description: The value of the target Rocking Curve and the scale of the Rocking Curve obtained from the simulation.

    +
    • +

  • opt_scale_factor

    +

    Format: bool (default: false)

    +

    Description: Flag whether scale_factor should be optimized or not.

    +
    • +

  • type_vector

    +

    Format: list

    +

    Description: A list of positive numbers which specifies the type of variables to be optimized. +This list corresponds to the types specified in the [param.atom] subsection. +If the type is the same, they are treated as the same variable.

    +
    • +
+
+

[param.domain] subsection

+

In this section, parameters to create domains are specified. +You will need to define the domains you want to create. +In the [param.domain.atom] sub-subsection, paramters of the information in the domain are specified.

+
    +

  • domain_occupancy

    +

    Format: float

    +

    Description: Occupancy of the whole domain.

    +
    • +
+
+
+

[param.domain.atom] subsection

+

This section needs to be defined as many times as the number of atoms you want to optimize belonging to the domain. +Note that the type, which represents the type of variable, must be a positive number.

+
    +

  • name

    +

    Format: string (can be duplicated)

    +

    Description: The name of the atom to be optimized.

    +
    • +

  • pos_center

    +

    Format: list

    +

    Description: Center coordinates of the atom. Describe in format of [\(x_0, y_0, z_0\)](\(x_0, y_0, z_0\) はfloat).

    +
    • +

  • DWfactor

    +

    Format: float

    +

    Description: Debye-Waller factor (in the unit of \(\text{Å}^{2}\) ).

    +
    • +

  • occupancy

    +

    Format: float (default: 1.0)

    +

    Description: Atom occupancy.

    +
    • +

  • displace_vector (can be omitted)

    +

    Format: list of lists

    +

    Description: A vector that defines the direction in which the atoms are moved. A maximum of three directions can be specified. +Define displacement vectors and initial values in each list as [type, \(D_{i1}, D_{i2}, D_{i3}\) ](type is int, \(D_{i1}, D_{i2}, D_{i3}\) is float type). +Follwing the specified information, \(l_{type}\) is varied as +\(dr_i = (D_{i1} \vec{a} + D_{i2} \vec{b} + D_{i3} \vec{c}) * l_{type}\) +( \(\vec{a}, \vec{b}, \vec{c}\) is a unit lattice vector defined in bulk_struc_in_file or struc_in_file).

    +
    • +

  • opt_DW (can be omitted)

    +

    Format: list

    +

    Description: Sets the scale at which the Debye-Waller coefficient is varied. +It is defined as [type, scale].

    +
    • +

  • opt_occupancy

    +

    Format: int

    +

    Description: If defined, the occupancy changes. The specified variable represents the type.

    +
    • +
+

An example of an input file is given as follows:

+
[param]
+scale_factor = 1.0
+type_vector = [1, 2]
+
+[[param.domain]]
+domain_occupancy = 1.0
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.00000000, 0.00000000, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[1, 0.0, 0.0, 1.0]]
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.33333333, 0.66666667, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[1, 0.0, 0.0, 1.0]]
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.66666667, 0.33333333, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[1, 0.0, 0.0, 1.0]]
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.33333333, 0.33333333, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[2, 0.0, 0.0, 1.0]]
+
+
+
+
+
+

[reference] section

+
    +

  • f_in_file

    +

    Format: string

    +

    Description: Path to the input file for the target locking curve.

    +
    • +
+
+
+
+

Reference file for Solver

+
+

Target reference file

+

The file containing the data to be targeted to fit. The path is specified by f_in_file in the [reference] section. +For each line, h k l F sigma is written. Here, h, k, l are the wavenumbers, F is the intensity, and sigma is the uncertainty of F. +An example file is shown below.

+
0.000000 0.000000 0.050000 572.805262 0.1
+0.000000 0.000000 0.150000 190.712559 0.1
+0.000000 0.000000 0.250000 114.163340 0.1
+0.000000 0.000000 0.350000 81.267319 0.1
+0.000000 0.000000 0.450000 62.927325 0.1
+...
+
+
+
+
+

Bulk structure file

+

The file containing the bulk structure data. The path is specified by bulk_struc_in_file in the [config] section. +The first line is a comment, the second line is a b c alpha beta gamma. +Here, a , b, and c are the lattice constants of the unit cells, and alpha, beta , and gamma are their angles. +The third and subsequent lines specify the atomsymbol r1 r2 r3 DWfactor occupancy. +Here, atomsymbol is the atom species, r1, r2, and r3 are the position coordinates of the atom, DWfactor is the Debye-Waller factor, and occupancy is the occupancy rate. +An example file is given below.

+
# SiC(111) bulk
+5.33940 5.33940  7.5510487  90.000000 90.000000 120.000000
+Si 0.00000000   0.00000000   0.00000000 0.0 1.0
+Si 0.33333333   0.66666667   0.00000000 0.0 1.0
+Si 0.66666667   0.33333333   0.00000000 0.0 1.0
+C  0.00000000   0.00000000   0.25000000 0.0 1.0
+...
+
+
+
+
+
+

Output files

+

In sxrd, the output files are stored in the folder with the rank number. +Here is a description of the files that are output by py2dmat.

+
+

stdout

+

The standard output by sxrd is described. +For sxrd’s Least square fitting, we give variables as initial parameters and calculate the Rfactor for a 1-shot calculation (number of iterations = 0). +The Rfactor is written in R under Fit results. +Here is an example of the output.

+
---------------------------------------
+Program py2dmat/mapper_sxrd/sxrdcalc for surface x-ray diffraction calculations.
+Version 3.3.3 - August 2019
+
+
+ Inputfile: lsfit.in
+Least-squares fit of model to experimental structure factors.
+
+...
+
+Fit results:
+Fit not converged after 0 iterations.
+Consider increasing the maximum number of iterations or find better starting values.
+chi^2 = 10493110.323318, chi^2 / (degree of freedom) = 223257.666454 (Intensities)
+chi^2 = 3707027.897897, chi^2 / (degree of freedom) = 78872.933998 (Structure factors)
+R = 0.378801
+
+Scale factor:   1.00000000000000 +/- 0.000196
+Parameter Nr. 1:   3.500000 +/- 299467640982.406067
+Parameter Nr. 2:   3.500000 +/- 898402922947.218384
+
+Covariance matrix:
+          0            1            2
+ 0  0.0000000383 20107160.3315223120 -60321480.9945669472
+ 1  20107160.3315223120 89680867995567253356544.0000000000 -269042603986701827178496.0000000000
+ 2  -60321480.9945669472 -269042603986701827178496.0000000000 807127811960105615753216.0000000000
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/start.html b/manual/v2.2.0/en/start.html new file mode 100644 index 00000000..9326f727 --- /dev/null +++ b/manual/v2.2.0/en/start.html @@ -0,0 +1,155 @@ + + + + + + + + Install of py2dmat — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Install of py2dmat

+
+

Prerequisites

+
    +

  • Python3 (>=3.6.8)

    +
    +
      +
    • +
      The following Python packages are required.
        +

      • tomli >= 1.2

        • +

      • numpy >= 1.14

        • +
      +
      +
      +
      • +

    • Optional packages

      +
      +
        +

      • mpi4py (required for grid search)

        • +

      • scipy (required for Nelder-Mead method)

        • +

      • physbo (>=0.3, required for Baysian optimization)

        • +
      +
      +
      • +
    +
    +
    • +
+
+
+

How to download and install

+

You can install the py2dmat python package and the py2dmat command using the method shown below.

+
    +

  • Installation using PyPI (recommended)

    +
    +
      +

    • python3 -m pip install py2dmat

      +
      +
        +

      • --user option to install locally ($HOME/.local)

        • +

      • If you use py2dmat[all], optional packages will be installed at the same time.

        • +
      +
      +
      • +
    +
    +
    • +

  • Installation from source code

    +
    +
      +

    1. git clone https://github.com/issp-center-dev/2DMAT

      2. +

    2. python3 -m pip install ./2DMAT

      +
      +
        +

      • The pip version must be 19 or higher (can be updated with python3 -m pip install -U pip).

        • +
      +
      +
      3. +
    +
    +
    • +

  • Download the sample files

    +
    +
      +

    • Sample files are included in the source code.

      • +

    • git clone https://github.com/issp-center-dev/2DMAT

      • +
    +
    +
    • +
+

Note that among the direct problem solvers used in py2dmat, +the following solver must be installed separately:

+
    +

  • TRHEPD forward problem solver (sim-trhepd-rheed)

    • +

  • SXRD forward problem solver (sxrdcalc)

    • +

  • LEED forward problem solver (satleed)

    • +
+

Please refer to the tutorials of each solver for installation details.

+
+
+

How to run

+

In py2dmat , the analysis is done by using a predefined optimization algorithm Algorithm and a direct problem solver Solver

+
$ py2dmat input.toml
+
+
+

See Search algorithms for the predefined Algorithm and Direct Problem Solver for the Solver.

+

If you want to prepare the Algorithm or Solver by yourself, use the py2dmat package. +See (For developers) User-defined algorithm and solver for details.

+
+
+

How to uninstall

+

Please type the following command:

+
$ python3 -m pip uninstall py2dmat
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tool.html b/manual/v2.2.0/en/tool.html new file mode 100644 index 00000000..bb060b3a --- /dev/null +++ b/manual/v2.2.0/en/tool.html @@ -0,0 +1,312 @@ + + + + + + + + Related Tools — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + + + + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/bayes.html b/manual/v2.2.0/en/tutorial/bayes.html new file mode 100644 index 00000000..c1fa557b --- /dev/null +++ b/manual/v2.2.0/en/tutorial/bayes.html @@ -0,0 +1,277 @@ + + + + + + + + Optimization by Bayesian Optimization — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Optimization by Bayesian Optimization

+

This tutorial subscribes how to estimate atomic positions from the experimental diffraction data by using Bayesian optimization (BO). +2DMAT uses PHYSBO for BO.

+
+

Sample files

+

Sample files are available from sample/sim-trhepd-rheed/single_beam/bayes . +This directory includes the following files:

+
    +

  • bulk.txt

    +

    The input file of bulk.exe

    +
    • +

  • experiment.txt , template.txt

    +

    Reference files for the main program

    +
    • +

  • ref_BayesData.txt

    +

    Solution file for checking whether the calucation successes or not

    +
    • +

  • input.toml

    +

    The input file of py2dmat

    +
    • +

  • prepare.sh , do.sh

    +

    Script files for running this tutorial

    +
    • +
+

In the following, we will subscribe these files and then show the result.

+
+
+

Reference files

+

This tutorial uses template.txt , experiment.txt similar to the previous one (minsearch). +Only difference is that in this tutorial the third parameter value_03 is fixed to 3.5 in order to speed up the calculation. +The parameter space to be explored is given by MeshData.txt.

+
1 3.5 3.5
+2 3.6 3.5
+3 3.6 3.6
+4 3.7 3.5
+5 3.7 3.6
+6 3.7 3.7
+7 3.8 3.5
+8 3.8 3.6
+9 3.8 3.7
+10 3.8 3.8
+  ...
+
+
+

The first column is the index of the point and the remaining ones are the coodinates, value_0 and value_1 in the template.txt.

+
+
+

Input files

+

This subsection describes the input file. +For details, see the manual of bayes. +input.toml in the sample directory is shown as the following

+
[base]
+dimension = 2
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+[algorithm]
+name = "bayes"
+label_list = ["z1", "z2"]
+
+[algorithm.param]
+mesh_path = "MeshData.txt"
+
+[algorithm.bayes]
+random_max_num_probes = 10
+bayes_max_num_probes = 20
+
+
+
    +

  • The [base] section describes the settings for a whole calculation.

    +
    +
      +

    • dimension is the number of variables you want to optimize. In this case, specify 2 because it optimizes two variables.

      • +
    +
    +
    • +

  • The [solver] section specifies the solver to use inside the main program and its settings.

    +
    +
      +

    • See the minsearch tutorial.

      • +
    +
    +
    • +

  • The [algorithm] section sets the algorithm to use and its settings.

    +
    +
      +

    • name is the name of the algorithm you want to use, and in this tutorial we will do a Bayesian optimization analysis, so specify bayes.

      • +

    • label_list is a list of label names to be given when outputting the value of value_0x (x = 1,2).

      • +

    • The [algorithm.bayes] section sets the parameters for Bayesian optimization.

      +
      +
        +

      • random_max_num_probes specifies the number of random searches before Bayesian optimization.

        • +

      • bayes_max_num_probes specifies the number of Bayesian searches.

        • +
      +
      +
      • +
    +
    +
    • +
+

For details on other parameters that can be specified in the input file, see the chapter on input files of bayes.

+
+
+

Calculation

+

First, move to the folder where the sample file is located (hereinafter, it is assumed that you are the root directory of 2DMAT).

+
cd sample/sim-trhepd-rheed/single_beam/bayes
+
+
+

Copy bulk.exe and surf.exe as the tutorial for the direct problem.

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

Execute bulk.exe to generate bulkP.b .

+
./bulk.exe
+
+
+

Then, run the main program (it takes a few secondes)

+
python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

This makes a directory with the name of 0 . +The following standard output will be shown:

+
# parameter
+random_max_num_probes = 10
+bayes_max_num_probes = 20
+score = TS
+interval = 5
+num_rand_basis = 5000
+value_01 =  5.10000
+value_02 =  4.90000
+R-factor = 0.037237314010261195
+0001-th step: f(x) = -0.037237 (action=150)
+   current best f(x) = -0.037237 (best action=150)
+
+value_01 =  4.30000
+value_02 =  3.50000
+
+
+

A list of hyperparameters, followed by candidate parameters at each step and the corresponding R-factor multiplied by \(-1\), are shown first. +It also outputs the grid index (action) and f(x) with the best R-factor at that time. +Under the directory 0, subdirectories with the name is the grid id are created, like Log%%%%% (%%%%% is the grid id), and the solver output for each grid is saved. +(The first column in MeshData.txt will be assigned as the id of the grid). +The final estimated parameters are output to BayesData.txt.

+

In this case, BayesData.txt can be seen as the following

+
#step z1 z2 fx z1_action z2_action fx_action
+0 5.1 4.9 0.037237314010261195 5.1 4.9 0.037237314010261195
+1 5.1 4.9 0.037237314010261195 4.3 3.5 0.06050786306685965
+2 5.1 4.9 0.037237314010261195 5.3 3.9 0.06215778000834068
+3 5.1 4.9 0.037237314010261195 4.7 4.2 0.049210767760634364
+4 5.1 4.9 0.037237314010261195 5.7 3.7 0.08394457854191653
+5 5.1 4.9 0.037237314010261195 5.2 5.2 0.05556857782716691
+6 5.1 4.9 0.037237314010261195 5.7 4.0 0.0754639895013157
+7 5.1 4.9 0.037237314010261195 6.0 4.4 0.054757310814479355
+8 5.1 4.9 0.037237314010261195 6.0 4.2 0.06339787375966344
+9 5.1 4.9 0.037237314010261195 5.7 5.2 0.05348404677676544
+10 5.1 4.7 0.03002813055356341 5.1 4.7 0.03002813055356341
+11 5.1 4.7 0.03002813055356341 5.0 4.4 0.03019977423448576
+12 5.3 4.5 0.02887504880071686 5.3 4.5 0.02887504880071686
+13 5.1 4.5 0.025865346123665988 5.1 4.5 0.025865346123665988
+14 5.2 4.4 0.02031077875240244 5.2 4.4 0.02031077875240244
+15 5.2 4.4 0.02031077875240244 5.2 4.6 0.023291891689059388
+16 5.2 4.4 0.02031077875240244 5.2 4.5 0.02345999725278686
+17 5.2 4.4 0.02031077875240244 5.1 4.4 0.022561543431398066
+18 5.2 4.4 0.02031077875240244 5.3 4.4 0.02544527153306051
+19 5.2 4.4 0.02031077875240244 5.1 4.6 0.02778877135528466
+20 5.2 4.3 0.012576357659158034 5.2 4.3 0.012576357659158034
+21 5.1 4.2 0.010217361468113488 5.1 4.2 0.010217361468113488
+22 5.1 4.2 0.010217361468113488 5.2 4.2 0.013178053637167673
+  ...
+
+
+

The first column contains the number of steps, and the second, third, and fourth columns contain value_01, value_02, and R-factor, which give the highest score at that time. +This is followed by the candidate value_01, value_02 and R-factor for that step. +In this case, you can see that the correct solution is obtained at the 21th step.

+

In addition, do.sh is prepared as a script for batch calculation. +do.sh also checks the difference between BayesData.dat and ref_BayesData.dat. +I will omit the explanation below, but I will post the contents.

+
sh prepare.sh
+
+./bulk.exe
+
+time python3 ../../../../src/py2dmat_main.py input.toml
+
+echo diff BayesData.txt ref_BayesData.txt
+res=0
+diff BayesData.txt ref_BayesData.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: BayesData.txt.txt and ref_BayesData.txt.txt differ
+  false
+fi
+
+
+
+
+

Visualization

+

You can see at what step the parameter gave the minimum score by looking at BayesData.txt. +Since RockingCurve.txt is stored in a subfolder for each step, it is possible to compare it with the experimental value by following the procedure of :doc:minsearch.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/exchange.html b/manual/v2.2.0/en/tutorial/exchange.html new file mode 100644 index 00000000..7450e107 --- /dev/null +++ b/manual/v2.2.0/en/tutorial/exchange.html @@ -0,0 +1,281 @@ + + + + + + + + Optimization by replica exchange Monte Carlo — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Optimization by replica exchange Monte Carlo

+

This tutorial subscribes how to estimate atomic positions from the experimental diffraction data by using the replica exchange Monte Carlo method (RXMC).

+
+

Sample files

+

Sample files are available from sample/sim-trhepd-rheed/single_beam/exchange . +This directory includes the following files:

+
    +

  • bulk.txt

    +

    The input file of bulk.exe

    +
    • +

  • experiment.txt , template.txt

    +

    Reference files for the main program

    +
    • +

  • ref.txt

    +

    Solution file for checking whether the calucation successes or not

    +
    • +

  • input.toml

    +

    The input file of py2dmat

    +
    • +

  • prepare.sh , do.sh

    +

    Script files for running this tutorial

    +
    • +
+

In the following, we will subscribe these files and then show the result.

+
+
+

Reference files

+

This tutorial uses reference files, template.txt and experiment.txt, +which are the same as the previous tutorial (Optimization by Nelder-Mead method) uses.

+
+
+

Input files

+

This subsection describes the input file. +For details, see the manual of bayes. +input.toml in the sample directory is shown as the following

+
[base]
+dimension = 2
+
+[algorithm]
+name = "exchange"
+label_list = ["z1", "z2"]
+seed = 12345
+
+[algorithm.param]
+min_list = [3.0, 3.0]
+max_list = [6.0, 6.0]
+
+[algorithm.exchange]
+numsteps = 1000
+numsteps_exchange = 20
+Tmin = 0.005
+Tmax = 0.05
+Tlogspace = true
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+
+

In the following, we will briefly describe this input file. +For details, see the manual of Replica exchange Monte Carlo exchange.

+
    +

  • The [base] section describes the settings for a whole calculation.

    +
    +
      +

    • dimension is the number of variables you want to optimize. In this case, specify 2 because it optimizes two variables.

      • +
    +
    +
    • +

  • The [solver] section specifies the solver to use inside the main program and its settings.

    +
    +
      +

    • See the minsearch tutorial.

      • +
    +
    +
    • +

  • The [algorithm] section sets the algorithm to use and its settings.

    +
    +
      +

    • name is the name of the algorithm you want to use, and in this tutorial we will use RXMC, so specify exchange.

      • +

    • label_list is a list of label names to be given when outputting the value of value_0x (x = 1,2).

      • +

    • seed is the seed that a pseudo-random number generator uses.

      • +

    • The [algorithm.param] section sets the parameter space to be explored.

      +
      +
        +

      • min_list is a lower bound and max_list is an upper bound.

        • +
      +
      +
      • +

    • The [algorithm.exchange] section sets the parameters for RXMC.

      +
      +
        +

      • numstep is the number of Monte Carlo steps.

        • +

      • numsteps_exchange is the number of interval steps between temperature exchanges.

        • +

      • Tmin, Tmax are the minimum and the maximum of temperature, respectively.

        • +

      • When Tlogspace is true, the temperature points are distributed uniformly in the logarithmic space.

        • +
      +
      +
      • +
    +
    +
    • +

  • The [solver] section specifies the solver to use inside the main program and its settings.

    +
    +
    +
    +
    • +
+
+
+

Calculation

+

First, move to the folder where the sample file is located (hereinafter, it is assumed that you are the root directory of 2DMAT).

+
cd sample/sim-trhepd-rheed/single_beam/exchange
+
+
+

Copy bulk.exe and surf.exe as the tutorial for the direct problem.

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

Execute bulk.exe to generate bulkP.b .

+
./bulk.exe
+
+
+

Then, run the main program (it takes a few secondes)

+
mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

Here, the calculation is performed using MPI parallel with 4 processes. +(If you are using Open MPI and you request more processes than you can use, add the --oversubscribed option to the mpiexec command.)

+

When executed, a folder for each rank will be created, and a trial.txt file containing the parameters evaluated in each Monte Carlo step and the value of the objective function, and a result.txt file containing the parameters actually adopted will be created.

+

These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters.

+
# step walker T fx x1 x2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+

In the case of the sim-trhepd-rheed solver, a subfolder Log%%%%% (%%%%% is the number of MC steps) is created under each working folder, and locking curve information etc. are recorded.

+

Finally, best_result.txt is filled with information about the parameter with the optimal objective function (R-factor), the rank from which it was obtained, and the Monte Carlo step.

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+x[0] = 4.221129370933539
+x[1] = 5.139591716517661
+
+
+

In addition, do.sh is prepared as a script for batch calculation. +do.sh also checks the difference between best_result.txt and ref.txt. +I will omit the explanation below, but I will post the contents.

+
sh prepare.sh
+
+./bulk.exe
+
+time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml
+
+echo diff best_result.txt ref.txt
+res=0
+diff best_result.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: best_result.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

Post process

+

The result.txt in each rank folder records the data sampled by each replica, but the same replica holds samples at different temperatures because of the temperature exchanges. +2DMat provides a script, script/separateT.py, that rearranges the results of all replicas into samples by temperature.

+
python3 ../../../../script/separateT.py
+
+
+

The data reorganized for each temperature point is written to result_T%.txt (% is the index of the temperature point). +The first column is the step, the second column is the rank, the third column is the value of the objective function, and the fourth and subsequent columns are the parameters.

+

Example:

+
# T = 0.004999999999999999
+# step rank fx x1 x2
+0 0 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.07830821484593968 3.682008067401509 3.9502750191292586
+
+
+
+
+

Visualization

+

By illustrating result_T.txt, you can estimate regions where the parameters with small R-factor are. +In this case, the figure result.png of the 2D parameter space is created by using the following command.

+
python3 plot_result_2d.py
+
+
+

Looking at the resulting diagram, we can see that the samples are concentrated near (5.25, 4.25) and (4.25, 5.25), and that the R-factor value is small there.

+
+../_images/exchange.png +
+

Fig. 4 Sampled parameters and R-factor. The horizontal axes is value_01 and the vertical axes is value_02 .

+
+
+

Also, RockingCurve.txt is stored in each subfolder, +LogXXX_YYY (XXX is an index of MC step and YYY is an index of a replica in the MPI process). +By using this, it is possible to compare with the experimental value according to the procedure of the previous tutorial.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/index.html b/manual/v2.2.0/en/tutorial/index.html new file mode 100644 index 00000000..dfa9f4a0 --- /dev/null +++ b/manual/v2.2.0/en/tutorial/index.html @@ -0,0 +1,105 @@ + + + + + + + + Tutorials — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Tutorials

+

The direct problem solver, sim_trhepd_rheed, is based on the Reflection-High-Energy Electron Diffraction (RHEED, TRHEPD) analysis software developed by Prof. Takashi Hanada at Tohoku University. +In TRHEPD, when atomic coordinates are given, diffraction data is given as a simulation result. +Therefore, we are dealing with the direct problem from atomic coordinates to diffraction data. +On the other hand, in many cases, diffraction data is given experimentally, and the atomic coordinates are required to reproduce the experimental data. These are inverse problems to the above direct problems.

+

In 2DMAT, the algorithms for solving the inverse problem can be selected as following algorithms:

+
    +

  • minsearch

    +
    +

    Estimating plausible atomic coordinates using the Nealder-Mead method.

    +
    +
    • +

  • mapper_mpi

    +
    +

    Estimate plausible atomic coordinates by searching the entire search grid for a given parameter.

    +
    +
    • +

  • bayes

    +
    +

    Estimate plausible atomic coordinates using Bayesian optimization.

    +
    +
    • +

  • exchange

    +
    +

    Sampling plausible atomic coordinates using a replica exchange Monte Carlo method.

    +
    +
    • +

  • pamc

    +
    +

    Sampling plausible atomic coordinates using a population annealing Monte Carlo method.

    +
    +
    • +
+

In this tutorial, we will first introduce how to run the sequential problem program, and then how to run minsearch , mapper_mpi, bayes, exchange, and pamc .

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/limitation.html b/manual/v2.2.0/en/tutorial/limitation.html new file mode 100644 index 00000000..e0a54250 --- /dev/null +++ b/manual/v2.2.0/en/tutorial/limitation.html @@ -0,0 +1,208 @@ + + + + + + + + Replica Exchange Monte Carlo search with limitation — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Replica Exchange Monte Carlo search with limitation

+

This tutorial describes the constraint expression function that can be set in the [runner.limitation] section. +As an example, the replica exchange Monte Carlo method is applied to the calculation of Himmelblau with constraints.

+
+

Sample files location

+

Sample files are available in the sample/analytical/limitation directory. +This directory contains the following files.

+
    +

  • ref.txt

    +

    File to check if the calculation is executed correctly (answer to obtain by performing this tutorial).

    +
    • +

  • input.toml

    +

    Input file for the main program.

    +
    • +

  • do.sh

    +

    Script prepared to calculate this tutorial at once.

    +
    • +
+

In the following, we will explain these files, and then introduce the actual calculation results.

+
+
+

Input files

+

The following input.toml is an input file for the main program.

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "exchange"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+unit_list = [0.3, 0.3]
+
+[algorithm.exchange]
+Tmin = 1.0
+Tmax = 100000.0
+numsteps = 10000
+numsteps_exchange = 100
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.limitation]
+co_a = [[1, -1],[1, 1]]
+co_b = [[0], [-1]]
+
+
+

[base] section is the parameter of the main program. +dimension is the number of variables to be optimized, and in this case, it is 2.

+

[algorithm] section is the section to set the search algorithm. +name is the name of the search algorithm. In this case, specify "exchange" for the replica exchange Monte Carlo method. +seed is the seed given to the pseudo-random number generator.

+

[algorithm.param] sub-section specifies the range of parameters to be optimized. +min_list indicates the minimum value, and max_list indicates the maximum value.

+

[algorithm.exchange] sub-section specifies the hyperparameters of the replica exchange Monte Carlo method.

+
    +

  • numstep is the number of Monte Carlo updates.

    • +

  • numsteps_exchange specifies the number of times to attempt temperature exchange.

    • +

  • Tmin and Tmax are the lower and upper limits of the temperature, respectively.

    • +

  • If Tlogspace is true, the temperature is divided equally in log space. This option is not specified in this input.toml because the default value is true.

    • +
+

[solver] section specifies the solver used internally in the main program. +In this case, the analytical solver is specified. +The analytical solver sets the function using the function_name parameter, and in this case, the Himmelblau function is specified.

+

[runner] section has a sub-section [runner.limitation], and in this section, the constraint expression is set. +In the current version, the constraint expression is defined as \(Ax+b>0\) where \(x\) is \(N\) dimensional input parameter, \(A\) is a \(M \times N\) matrix, and \(b\) is a \(M\) dimensional vector. +\(A\) and \(b\) are set by co_a and co_b, respectively. +For details, see the [limitation] section in the input file in the manual.

+

In this case, the following constraint is imposed:

+
+\[\begin{split}x_{1} − x_{2} > 0\\ +x_{1} + x_{2} − 1 > 0\end{split}\]
+
+
+

Calculation

+

First, move to the folder where the sample file is located (assuming that you are directly under the directory where you downloaded this software).

+
cd sample/analytical/limitation
+
+
+

Then, execute the main program as follows (the calculation time will end in about 20 seconds on a normal PC).

+
mpiexec -np 10 python3 ../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

In this case, a calculation with 10 MPI parallel processes is performed. +(When using OpenMPI, if the number of processes to be used is greater than the number of available cores, add the --oversubscribed option to the mpiexec command.) +After executed, the output folder is generated, and in it, a subfolder for each rank is created. +Each subfolder contains the results of the calculation. +trial.txt file, which contains the parameters and objective function values evaluated at each Monte Carlo step, and result.txt file, which contains the parameters actually adopted, are created. +Both files have the same format, with the first two columns being the step number and the walker number within the process, the next being the temperature, the third being the value of the objective function, and the fourth and subsequent being the parameters. +The following is the beginning of the output/0/result.txt file:

+
# step walker T fx x1 x2
+0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569
+1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+
+
+

Finally, the best parameter and the rank and Monte Carlo step at which the objective function is minimized are written to output/best_result.txt.

+
nprocs = 10
+rank = 2
+step = 4523
+walker = 0
+fx = 0.00010188398524402734
+x1 = 3.584944906595298
+x2 = -1.8506985826548874
+
+
+

do.sh is available as a script to calculate all at once. +Additionally, in do.sh, the difference between best_result.txt and ref.txt is also compared.

+
#!/bin/bash
+mpiexec -np 10 --oversubscribe python3 ../../../src/py2dmat_main.py input.toml
+
+echo diff output/best_result.txt ref.txt
+res=0
+diff output/best_result.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: best_result.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

Visualization of the calculation result

+

By visualizing the result.txt file, we can confirm that the search is only for coordinates that satisfy the constraint expression. +hist2d_limitation_sample.py is prepared to visualize the 2D parameter space. +This generates a histogram of the posterior probability distribution in the <execution date>_histogram folder. +The histogram is generated using the data obtained by discarding the first 1000 steps of the search as a burn-in period.

+
python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1
+
+
+

The figure shows the posterior probability distribution and the two lines \(x_{1} − x_{2} = 0, x_{1} + x_{2} − 1 = 0\), +and it is confirmed that the search is only for the range where \(x_{1} − x_{2} > 0, x_{1} + x_{2} − 1 > 0\).

+
+../_images/limitation_beta_min.png +
+
+../_images/limitation_beta_max.png +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/minsearch.html b/manual/v2.2.0/en/tutorial/minsearch.html new file mode 100644 index 00000000..a78a7d7f --- /dev/null +++ b/manual/v2.2.0/en/tutorial/minsearch.html @@ -0,0 +1,302 @@ + + + + + + + + Optimization by Nelder-Mead method — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

Optimization by Nelder-Mead method

+

In this section, we will explain how to calculate the inverse problem of analyzing atomic coordinates from diffraction data using the Nelder-Mead method. +The specific calculation procedure is as follows.

+
    +

  1. Preparation of the reference file

    +

    Prepare the reference file to be matched (in this tutorial, it corresponds to experiment.txt described below).

    +
    2. +

  2. Perform calculations on the bulk part of the surface structure.

    +

    Copy bulk.exe to sample/sim-trhepd-rheed/minsearch and run the calculation.

    +
    3. +

  3. Run the main program

    +

    Run the calculation using src/py2dmat_main.py to estimate the atomic coordinates.

    +
    4. +
+

In the main program, the Nelder-Mead method (using scipy.optimize.fmin) is used. ) to find the parameter that minimizes the deviation (R-value) between the intensity obtained using the solver (in this case surf.exe) and the intensity listed in the reference file (experiment.txt).

+
+

Location of the sample files

+

The sample files are located in sample/py2dmat/sim-trhepd-rheed/single_beam/minsearch. +The following files are stored in the folder.

+
    +

  • bulk.txt

    +

    Input file of bulk.exe.

    +
    • +

  • experiment.txt , template.txt

    +

    Reference file to proceed with calculations in the main program.

    +
    • +

  • ref.txt

    +

    A file containing the answers you want to seek in this tutorial.

    +
    • +

  • input.toml

    +

    Input file of the main program.

    +
    • +

  • prepare.sh , do.sh

    +
    +

    Script prepared for doing all calculation of this tutorial

    +
    +
    • +
+

The following sections describe these files and then show the actual calculation results.

+
+
+

The reference file

+

The template.txt file is almost the same format as the input file for surf.exe. +The parameters to be run (such as the atomic coordinates you want to find) are rewritten as value_* or some other appropriate string. +The following is the content of template.txt.

+
2                                    ,NELMS,  -------- Ge(001)-c4x2
+32,1.0,0.1                           ,Ge Z,da1,sap
+0.6,0.6,0.6                          ,BH(I),BK(I),BZ(I)
+32,1.0,0.1                           ,Ge Z,da1,sap
+0.4,0.4,0.4                          ,BH(I),BK(I),BZ(I)
+9,4,0,0,2, 2.0,-0.5,0.5               ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS
+8                                    ,NATM
+1, 1.0, 1.34502591  1       value_01   ,IELM(I),ocr(I),X(I),Y(I),Z(I)
+1, 1.0, 0.752457792 1       value_02
+2, 1.0, 1.480003343 1.465005851     value_03
+2, 1.0, 2   1.497500418     2.281675
+2, 1.0, 1   1.5     1.991675
+2, 1.0, 0   1       0.847225
+2, 1.0, 2   1       0.807225
+2, 1.0, 1.009998328 1       0.597225
+1,1                                  ,(WDOM,I=1,NDOM)
+
+
+

In this input file, value_01, value_02, and value_03 are used. +In the sample folder, there is a reference file ref.txt to know if the atomic positions are estimated correctly. The contents of this file are

+
fx = 7.382680568652868e-06
+z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+

value_0x corresponds to z_x (x=1, 2, 3). +fx is the optimal value of the objective function. +The experiment.txt is a file that is used as a reference in the main program, and is equivalent to convolution.txt, which is calculated by putting the parameters in ref.txt into template.txt and following the same procedure as in the tutorial on direct problems. (Note that the input files for bulk.exe and suft.exe are different from those in the sequential problem tutorial.)

+
+
+

Input file

+

In this section, we will prepare the input file input.toml for the main program. +The details of input.toml can be found in the input file. +This section describes the contents of input.toml in the sample file.

+
[base]
+dimension = 3
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02", "value_03" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+[algorithm]
+name = "minsearch"
+label_list = ["z1", "z2", "z3"]
+
+[algorithm.param]
+min_list = [0.0, 0.0, 0.0]
+max_list = [10.0, 10.0, 10.0]
+initial_list = [5.25, 4.25, 3.50]
+
+
+

First, [base] section is explained.

+
    +

  • The dimension is the number of variables to be optimized, in this case 3 since we are optimizing three variables as described in template.txt.

    • +
+

The [solver] section specifies the solver to be used inside the main program and its settings.

+
    +

  • The name is the name of the solver you want to use, which in this tutorial is sim-trhepd-rheed, since we will be using it for our analysis.

    • +
+

The solver can be configured in the subsections [solver.config], [solver.param], and [solver.reference].

+

The [solver.config] section specifies options for reading the output file produced by the main program’s internal call, surf.exe.

+
    +

  • The calculated_first_line specifies the first line to read from the output file.

    • +

  • The calculated_last_line specifies the last line of the output file to be read.

    • +

  • The row_number specifies the number of columns in the output file to read.

    • +
+

The [solver.param] section specifies options for reading the output file produced by the main program’s internal call, surf.exe.

+
    +

  • The string_list is a list of variable names to be read in template.txt.

    • +

  • degree_max specifies the maximum angle in degrees.

    • +
+

The [solver.reference] section specifies the location of the experimental data and the range to read.

+
    +

  • The path specifies the path where the experimental data is located.

    • +

  • The first specifies the first line of the experimental data file to read.

    • +

  • The end specifies the last line of the experimental data file to read.

    • +
+

The [algorithm] section specifies the algorithm to use and its settings.

+
    +

  • The name is the name of the algorithm you want to use, in this tutorial we will use minsearch since we will be using the Nelder-Mead method.

    • +

  • The label_list is a list of label names to be added to the output of value_0x (x=1,2,3).

    • +
+

The [algorithm.param] section specifies the range of parameters to search and their initial values.

+
    +

  • The min_list and max_list specify the minimum and maximum values of the search range, respectively.

    • +

  • The initial_list specifies the initial values.

    • +
+

Other parameters, such as convergence judgments used in the Nelder-Mead method, can be done in the [algorithm] section, although they are omitted here because the default values are used. +See the input file chapter for details.

+
+
+

Calculation execution

+

First, move to the folder where the sample files are located (we will assume that you are directly under the directory where you downloaded this software).

+
cd sample/sim-trhepd-rheed/single_beam/minsearch
+
+
+

Copy bulk.exe and surf.exe.

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

First, run bulk.exe to create bulkP.b.

+
./bulk.exe
+
+
+

After that, run the main program (the computation time takes only a few seconds on a normal PC).

+
python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

Then, the standard output will be seen as follows.

+
Read experiment.txt
+z1 =  5.25000
+z2 =  4.25000
+z3 =  3.50000
+[' 5.25000', ' 4.25000', ' 3.50000']
+PASS : degree in lastline = 7.0
+PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70
+R-factor = 0.015199251773721183
+z1 =  5.50000
+z2 =  4.25000
+z3 =  3.50000
+[' 5.50000', ' 4.25000', ' 3.50000']
+PASS : degree in lastline = 7.0
+PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70
+R-factor = 0.04380131351780189
+z1 =  5.25000
+z2 =  4.50000
+z3 =  3.50000
+[' 5.25000', ' 4.50000', ' 3.50000']
+...
+
+
+

The z1, z2, and z3 are the candidate parameters at each step and the R-factor at that time. +The results of each step are also output to the folder Logxxxxx (where xxxxxx is the number of steps). +The final estimated parameters will be output to res.dat. +In the current case, the following result is obtained:

+
z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+

You can see that we get the same value as the correct answer data ref.txt. +Note that do.sh is available as a script for batch calculation. +In do.sh, it also compares the difference between res.txt and ref.txt. +Here is what it does, without further explanation.

+
sh ./prepare.sh
+
+./bulk.exe
+
+time python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+echo diff res.txt ref.txt
+res=0
+diff res.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo Test PASS
+  true
+else
+  echo Test FAILED: res.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

Visualization of calculation results

+

The data of the rocking curve at each step is stored in Logxxxx_00000001 (where xxxx is the index of steps) as RockingCurve.txt. +A tool draw_RC_double.py is provided to visualize this data. +In this section, we will use this tool to visualize the results.

+
cp 0/Log00000001_00000001/RockingCurve.txt RockingCurve_ini.txt
+cp 0/Log00000062_00000001/RockingCurve.txt RockingCurve_con.txt
+cp ../../../../script/draw_RC_double.py .
+python draw_RC_double.py
+
+
+

Running the above will output RC_double.png.

+
+../_images/RC_double_minsearch.png +
+

Fig. 2 Analysis using the Nelder-Mead method. The red circle represents the experimental value, the blue line represents the first step, and the green line represents the rocking curve obtained at the last step.

+
+
+

From the figure, we can see that the last step agrees with the experimental one.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/mpi.html b/manual/v2.2.0/en/tutorial/mpi.html new file mode 100644 index 00000000..275c7b7d --- /dev/null +++ b/manual/v2.2.0/en/tutorial/mpi.html @@ -0,0 +1,261 @@ + + + + + + + + Grid search — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + + + + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/pamc.html b/manual/v2.2.0/en/tutorial/pamc.html new file mode 100644 index 00000000..05ec6955 --- /dev/null +++ b/manual/v2.2.0/en/tutorial/pamc.html @@ -0,0 +1,297 @@ + + + + + + + + Optimization by population annealing — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Optimization by population annealing

+

This tutorial subscribes how to estimate atomic positions from the experimental diffraction data by using the population annealing Monte Carlo method (PAMC).

+
+

Sample files

+

Sample files are available from sample/sim-trhepd-rheed/single_beam/pamc . +This directory includes the following files:

+
    +

  • bulk.txt

    +

    The input file of bulk.exe

    +
    • +

  • experiment.txt , template.txt

    +

    Reference files for the main program

    +
    • +

  • ref.txt

    +

    Solution file for checking whether the calucation successes or not (reference for fx.txt)

    +
    • +

  • input.toml

    +

    The input file of py2dmat

    +
    • +

  • prepare.sh , do.sh

    +

    Script files for running this tutorial

    +
    • +
+

In the following, we will subscribe these files and then show the result.

+
+
+

Reference files

+

This tutorial uses reference files, template.txt and experiment.txt, +which are the same as the previous tutorial (Optimization by Nelder-Mead method) uses.

+
+
+

Input files

+

This subsection describes the input file. +For details, see the manual of bayes. +input.toml in the sample directory is shown as the following

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "pamc"
+label_list = ["z1", "z2"]
+seed = 12345
+
+[algorithm.param]
+min_list = [3.0, 3.0]
+max_list = [6.0, 6.0]
+unit_list = [0.3, 0.3]
+
+[algorithm.pamc]
+numsteps_annealing = 5
+bmin = 0.0
+bmax = 200.0
+Tnum = 21
+Tlogspace = false
+nreplica_per_proc = 10
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+
+

In the following, we will briefly describe this input file. +For details, see the manual of Replica exchange Monte Carlo exchange.

+
    +

  • The [base] section describes the settings for a whole calculation.

    +
    +
      +

    • dimension is the number of variables you want to optimize. In this case, specify 2 because it optimizes two variables.

      • +
    +
    +
    • +

  • The [solver] section specifies the solver to use inside the main program and its settings.

    +
    +
      +

    • See the minsearch tutorial.

      • +
    +
    +
    • +

  • The [algorithm] section sets the algorithm to use and its settings.

    +
    +
      +

    • name is the name of the algorithm you want to use, and in this tutorial we will use RXMC, so specify exchange.

      • +

    • label_list is a list of label names to be given when outputting the value of value_0x (x = 1,2).

      • +

    • seed is the seed that a pseudo-random number generator uses.

      • +

    • The [algorithm.param] section sets the parameter space to be explored.

      +
      +
        +

      • min_list is a lower bound and max_list is an upper bound.

        • +

      • unit_list is step length in one MC update (deviation of Gaussian)

        • +
      +
      +
      • +

    • The [algorithm.pamc] section sets the parameters for PAMC.

      +
      +
        +

      • numsteps_annealing is the number of interval steps between temperature decreasing.

        • +

      • bmin, bmax are the minimum and the maximum of inversed temperature, respectively.

        • +

      • Tnum is the number of (inversed) temperature points.

        • +

      • When Tlogspace is true, the temperature points are distributed uniformly in the logarithmic space.

        • +

      • nreplica_per_proc is the number of replicas (MC walkers) in one MPI process.

        • +
      +
      +
      • +
    +
    +
    • +

  • The [solver] section specifies the solver to use inside the main program and its settings.

    +
    +
    +
    +
    • +
+
+
+

Calculation

+

First, move to the folder where the sample file is located (hereinafter, it is assumed that you are the root directory of 2DMAT).

+
cd sample/sim-trhepd-rheed/single_beam/pamc
+
+
+

Copy bulk.exe and surf.exe as the tutorial for the direct problem.

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

Execute bulk.exe to generate bulkP.b .

+
./bulk.exe
+
+
+

Then, run the main program (it takes a few secondes)

+
mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

Here, the calculation is performed using MPI parallel with 4 processes. +(If you are using Open MPI and you request more processes than you can use, add the --oversubscribed option to the mpiexec command.)

+

When executed, a folder for each rank will be created, and trial_TXXX.txt files containing the parameters evaluated in each Monte Carlo step and the value of the objective function at each temperature (XXX is the index of points), and result_TXXX.txt files containing the parameters actually adopted will be created. +These files are concatnated into result.txt and trial.txt.

+

These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the (inversed) temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters. +The final two columns are the weight of walker (Neal-Jarzynski weight) and the index of the grand ancestor (the replica index at the beginning of the calculation).

+
# step walker beta fx z1 z2 weight ancestor
+0 0 0.0 0.07702743614780189 5.788848278451443 3.949126663745358 1.0 0
+0 1 0.0 0.08737730661436376 3.551756435031283 3.6136808356591192 1.0 1
+0 2 0.0 0.04954470587051104 4.70317508724506 4.786634108937754 1.0 2
+0 3 0.0 0.04671675601156148 5.893543559206865 4.959531290614713 1.0 3
+0 4 0.0 0.04142014655238446 5.246719912601735 4.960709612555206 1.0 4
+
+
+

In the case of the sim-trhepd-rheed solver, a subfolder Log%%%%% (%%%%% is the number of MC steps) is created under each working folder, and locking curve information etc. are recorded.

+

Finally, best_result.txt is filled with information about the parameter with the optimal objective function (R-factor), the rank from which it was obtained, and the Monte Carlo step.

+
nprocs = 4
+rank = 0
+step = 71
+walker = 5
+fx = 0.008186713312593607
+z1 = 4.225633749839847
+z2 = 5.142666117413409
+
+
+

Finally, fx.txt stores the statistics at each temperature point:

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.0 0.06428002079611472 0.002703413400677839 40 0.0 0.795
+10.0 0.061399304916174735 0.002649424392996749 40 -0.6280819199879947 0.85
+20.0 0.05904248889111052 0.0031622711212952034 40 -1.2283060742855603 0.74
+30.0 0.04956921148431115 0.0028298565759159633 40 -1.7991035905899855 0.67
+
+
+

The first column is (inversed) temperature, and +the second/third ones are the mean and standard error of \(f(x)\), respectively. +The fourth column is the number of replicas and the fifth one is the logarithm of the ratio of the partition functions, \(\log(Z_n/Z_0)\), where \(Z_0\) is the partition function at the first temperature. +The sixth column is the acceptance ratio of MC updates.

+

In addition, do.sh is prepared as a script for batch calculation. +do.sh also checks the difference between best_result.txt and ref.txt. +I will omit the explanation below, but I will post the contents.

+
sh prepare.sh
+
+./bulk.exe
+
+time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml
+
+echo diff output/fx.txt ref.txt
+res=0
+diff output/fx.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: output/fx.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

Visualization

+

By illustrating result_T.txt, you can estimate regions where the parameters with small R-factor are. +In this case, the figure result_fx.pdf and result_T.pdf of the 2D parameter space is created by using the following command. +The color of symbols of result_fx.pdf and result_T.pdf mean R-factor and \(\beta\), respectively.

+
python3 plot_result_2d.py
+
+
+

Looking at the resulting diagram, we can see that the samples are concentrated near (5.25, 4.25) and (4.25, 5.25), and that the R-factor value is small there.

+
+../_images/pamc_fx.png +
+

Fig. 5 Sampled parameters and R-factor. The horizontal axes is value_01 and the vertical axes is value_02 .

+
+
+
+../_images/pamc_T.png +
+

Fig. 6 Sampled parameters and \(\beta\). The horizontal axes is value_01 and the vertical axes is value_02 .

+
+
+

Also, RockingCurve.txt is stored in each subfolder, +LogXXX_YYY (XXX is an index of MC step and YYY is an index of a replica in the MPI process). +By using this, it is possible to compare with the experimental value according to the procedure of the previous tutorial.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/sim_trhepd_rheed.html b/manual/v2.2.0/en/tutorial/sim_trhepd_rheed.html new file mode 100644 index 00000000..581ef723 --- /dev/null +++ b/manual/v2.2.0/en/tutorial/sim_trhepd_rheed.html @@ -0,0 +1,177 @@ + + + + + + + + TRHEPD Direct Problem Solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + +
+ + +
+

TRHEPD Direct Problem Solver

+

As one of the forward problem solvers, 2DMAT provides a wrapper for the program sim-trhepd-rheed , which calculates the intensity of reflection fast (positron) electron diffraction (RHEED, TRHEPD) (A. Ichimiya, Jpn. J. Appl. Phys. 22, 176 (1983); 24, 1365 (1985)). +In this tutorial, we will show some examples which use some algorithms with sim-trhepd-rheed. +First, we will install and test sim-trhepd-rheed (for details, see the official web page for sim-trhepd-rheed).

+
+

Download and Install

+

First, in the tutorial, we assume that you are at the location where the 2DMAT folder is located.

+
$ ls -d 2DMAT
+2DMAT/
+
+
+

Get the source codes from the sim-trhepd-rheed repository on GitHub and build it.

+
git clone http://github.com/sim-trhepd-rheed/sim-trhepd-rheed
+cd sim-trhepd-rheed/src
+make
+
+
+

If make is successful, bulk.exe and surf.exe will be created.

+
+
+

Calculation execution

+

In sim-trhepd-rheed, the bulk part of the surface structure is first calculated with bulk.exe. +Then, using the results of the bulk.exe calculation (the bulkP.b file), +the surface portion of the surf.exe surface structure is calculated.

+

In this tutorial, we will actually try to do the TRHEPD calculation. +The sample input files are located in sample/sim-trhepd-rheed in 2DMAT. +First, copy this folder to a suitable working folder work.

+
cd ../../
+cp -r 2DMAT/sample/sim-trhepd-rheed/solver work
+cd work
+
+
+

Next, copy bulk.exe and surf.exe to work.

+
cp ../sim-trhepd-rheed/src/bulk.exe .
+cp ../sim-trhepd-rheed/src/surf.exe .
+
+
+

Execute bulk.exe.

+
./bulk.exe
+
+
+

Then, the bulk file bulkP.b will be generated with the following output.

+
0:electron 1:positron ?
+P
+input-filename (end=e) ? :
+bulk.txt
+output-filename :
+bulkP.b
+
+
+

Next, execute surf.exe.

+
./surf.exe
+
+
+

Then, the following standard output will be seen.

+
bulk-filename (end=e) ? :
+bulkP.b
+structure-filename (end=e) ? :
+surf.txt
+output-filename :
+surf-bulkP.md
+surf-bulkP.s
+
+
+

After execution, the files surf-bulkP.md, surf-bulkP.s and SURFYYYYMMDD-HHMMSSlog.txt will be generated. +(YYYYMMDD and HHMMSS are numbers corresponding to the execution date and time).

+
+
+

Visualization of calculation result

+

The contents of surf-bulkP.s are shown as follow:

+
#azimuths,g-angles,beams
+1 56 13
+#ih,ik
+6 0 5 0 4 0 3 0 2 0 1 0 0 0 -1 0 -2 0 -3 0 -4 0 -5 0 -6 0
+0.5000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1595E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.6000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1870E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.7000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2121E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.8000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2171E-02, 0.1927E-01, 0.2171E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.9000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.4397E-02, 0.1700E-01, 0.4397E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.1000E+01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.6326E-02, 0.1495E-01, 0.6326E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+...
+
+
+

From the above file, create a rocking curve from the angle on the vertical axis (first column of data after row 5) and the intensity of the (0,0) peak (eighth column of data after row 5). +You can use Gnuplot or other graphing software, but here we use the program plot_bulkP.py in the 2DMAT/script folder. +Run it as follows.

+
python3 ../2DMAT/script/plot_bulkP.py
+
+
+

The following plot_bulkP.png will be created.

+
+../_images/plot_bulkP.png +
+

Fig. 1 Rocking curve of Si(001)-2x1 surface.

+
+
+

We will convolute and normalize the diffraction intensity data of the 00 peaks. +Prepare surf-bulkP.s and run make_convolution.py.

+
python3 ../2DMAT/script/make_convolution.py
+
+
+

When executed, the following file convolution.txt will be created.

+
0.500000 0.010818010
+0.600000 0.013986716
+0.700000 0.016119093
+0.800000 0.017039022
+0.900000 0.017084666
+  ... skipped ...
+5.600000 0.000728539
+5.700000 0.000530758
+5.800000 0.000412908
+5.900000 0.000341740
+6.000000 0.000277553
+
+
+

The first column is the viewing angle, and the second column is the normalized 00-peak diffraction intensity data +written in surf-bulkP.s with a convolution of half-width 0.5.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/en/tutorial/solver_simple.html b/manual/v2.2.0/en/tutorial/solver_simple.html new file mode 100644 index 00000000..9f638da8 --- /dev/null +++ b/manual/v2.2.0/en/tutorial/solver_simple.html @@ -0,0 +1,136 @@ + + + + + + + + Addition of a direct problem solver — 2DMAT 2.2-dev documentation + + + + + + + + + + + + + +
+ + +
+

Addition of a direct problem solver

+
+

Solver for benchmarking, analytical

+

py2dmat provides an analytical solver as a direct problem solver that can be used to test search algorithms.

+

To use the analytical solver, set name to "analytical" in the [solver] section of the input file. +You can also use the function_name parameter to select the benchmark function \(f(x)\).

+

For example, to use Himmelblau function, make an input file including the following:

+
[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+
+

For details of analytical solver, please check the the reference of the analytical solver.

+
+
+

Addition of a direct problem solver

+

The easiest way to define and analyze a user-defined direct problem solver is to add it to the analytical solver. +As an example, we will explain the case of adding the Booth function (the minimum point is \(f(1,3) = 0\)):

+
+\[f(x,y) = (x+2y-7)^2 + (2x+y-5)^2.\]
+

To do so, we need to download the source code for py2dmat and edit the file for analytical solver. +For instructions on how to download the source code and run py2dmat from the source code, see how to install. +analytical solver is defined in the src/py2dmat/solver/analytical.py, so edit it.

+

First, define the booth function as follows:

+
def booth(xs: np.ndarray) -> float:
+    """Booth function
+
+    it has one global minimum f(xs) = 0 at xs = [1,3].
+    """
+
+    if xs.shape[0] != 2:
+        raise RuntimeError(
+            f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one"
+        )
+    return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2
+
+
+

Next, insert the following code in the if branch of the Solver class’s constructor (__init__) +to allow users to choose the booth function by the solver.function_name parameter of the input file.

+
elif function_name == "booth":
+        self.set_function(booth)
+
+
+

With this modified analytical solver, you can optimize the Booth function. +For example, to optimize it by the Nelder-Mead method, pass the following input file (input.toml)

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "minsearch"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+initial_list = [0, 0]
+
+[solver]
+name = "analytical"
+function_name = "booth"
+
+
+

to src/py2dmat_main.py script as follows:

+
$ python3 src/py2dmat_main.py input.toml
+
+... skipped ...
+
+Iterations: 38
+Function evaluations: 75
+Solution:
+x1 = 1.0000128043523089
+x2 = 2.9999832920260863
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/.buildinfo b/manual/v2.2.0/ja/.buildinfo new file mode 100644 index 00000000..17f42ee1 --- /dev/null +++ b/manual/v2.2.0/ja/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 62ac14d79bb4ba077fd8ea93d70e95b4 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/manual/v2.2.0/ja/_images/RC_double_minsearch.png b/manual/v2.2.0/ja/_images/RC_double_minsearch.png new file mode 100644 index 00000000..ac258e46 Binary files /dev/null and b/manual/v2.2.0/ja/_images/RC_double_minsearch.png differ diff --git a/manual/v2.2.0/ja/_images/exchange.png b/manual/v2.2.0/ja/_images/exchange.png new file mode 100644 index 00000000..615df198 Binary files /dev/null and b/manual/v2.2.0/ja/_images/exchange.png differ diff --git a/manual/v2.2.0/ja/_images/limitation_beta_max.png b/manual/v2.2.0/ja/_images/limitation_beta_max.png new file mode 100644 index 00000000..4446b42d Binary files /dev/null and b/manual/v2.2.0/ja/_images/limitation_beta_max.png differ diff --git a/manual/v2.2.0/ja/_images/limitation_beta_min.png b/manual/v2.2.0/ja/_images/limitation_beta_min.png new file mode 100644 index 00000000..7360c798 Binary files /dev/null and b/manual/v2.2.0/ja/_images/limitation_beta_min.png differ diff --git a/manual/v2.2.0/ja/_images/mapper.png b/manual/v2.2.0/ja/_images/mapper.png new file mode 100644 index 00000000..ef4faa25 Binary files /dev/null and b/manual/v2.2.0/ja/_images/mapper.png differ diff --git a/manual/v2.2.0/ja/_images/pamc_T.png b/manual/v2.2.0/ja/_images/pamc_T.png new file mode 100644 index 00000000..331bb662 Binary files /dev/null and b/manual/v2.2.0/ja/_images/pamc_T.png differ diff --git a/manual/v2.2.0/ja/_images/pamc_fx.png b/manual/v2.2.0/ja/_images/pamc_fx.png new file mode 100644 index 00000000..8d58285b Binary files /dev/null and b/manual/v2.2.0/ja/_images/pamc_fx.png differ diff --git a/manual/v2.2.0/ja/_images/plot_bulkP.png b/manual/v2.2.0/ja/_images/plot_bulkP.png new file mode 100644 index 00000000..293325a1 Binary files /dev/null and b/manual/v2.2.0/ja/_images/plot_bulkP.png differ diff --git a/manual/v2.2.0/ja/_sources/acknowledgement.rst.txt b/manual/v2.2.0/ja/_sources/acknowledgement.rst.txt new file mode 100644 index 00000000..19f6cd11 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/acknowledgement.rst.txt @@ -0,0 +1,7 @@ +*************************** +謝辞 +*************************** +本ソフトウェアの開発は、科研費(2019-2021年度)「超並列マシンを用いた計算統計と測定技術の融合」および東京大学物性研究所 ソフトウェア高度化プロジェクト (2020, 2021 年度) の支援を受け開発されました。 +本ソフトウェアの設計・変数命名の一部は `abics `_ を参考にしています。 +また、順問題ソルバーの実装にあたり、花田貴氏 (東北大学)、望月出海氏(KEK)、W. Voegeli氏(東京学芸大学)、白澤徹郎氏(AIST)、R. Ahmed氏(九州大学)、和田健氏(KEK)にお世話になりました。ソルバーの追加方法について、塚本恭平氏(物性研)にチュートリアルを追加していただきました。 +この場を借りて感謝します。 diff --git a/manual/v2.2.0/ja/_sources/algorithm/bayes.rst.txt b/manual/v2.2.0/ja/_sources/algorithm/bayes.rst.txt new file mode 100644 index 00000000..a20722cf --- /dev/null +++ b/manual/v2.2.0/ja/_sources/algorithm/bayes.rst.txt @@ -0,0 +1,161 @@ +ベイズ最適化 ``bayes`` +******************************* + +.. _PHYSBO: https://pasums.issp.u-tokyo.ac.jp/physbo + +``bayes`` はベイズ最適化を用いてパラメータ探索を行う ``Algorithm`` です。 + +実装には `PHYSBO`_ を用いています。 + +前準備 +~~~~~~ +あらかじめ `PHYSBO`_ をインストールしておく必要があります。:: + + python3 -m pip install physbo + +`mpi4py `_ がインストールされている場合、 +MPI 並列計算が可能です。 + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~ + +[``algorithmparam``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索パラメータ空間を定義します。 + +``mesh_path`` が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。 + +``mesh_path`` が定義されていない場合は、 ``min_list``, ``max_list``, ``num_list`` を用いて、 +各パラメータについて等間隔なグリッドを作成します。 + +- ``mesh_path`` + + 形式: string型 + + 説明: メッシュデータの情報が記載された参照用ファイルへのパス。 + +- ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + +- ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + +- ``num_list`` + + 形式: 整数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる数。 + +[``algorithm.bayes``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +手法のハイパーパラメータを定義します。 + +- ``random_max_num_probes`` + + 形式： int型 (default: 20) + + 説明: ベイズ最適化を行う前に行うランダムサンプリングの回数(パラメータとスコアが初めに無い場合にはランダムサンプリングは必須)。 + +- ``bayes_max_num_probes`` + + 形式： int型 (default: 40) + + 説明: ベイズ最適化を行う回数。 + +- ``score`` + + 形式: string型 (default: ``TS`` ) + + 説明: スコア関数を指定するパラメータ。 + ``EI``, ``PI``, ``TS`` より選択可能で、それぞれ "expected improvement", "probability of improvement", "Thompson sampling" を行う。 + +- ``interval`` + + 形式： int型 (default: 5) + + 説明: 指定したインターバルごとに、ハイパーパラメータを学習します。負の値を指定すると、ハイパーパラメータの学習は行われません。 + 0を指定すると、ハイパーパラメータの学習は最初のステップでのみ行われます。 + +- ``num_rand_basis`` + + 形式： int型 (default: 5000) + + 説明： 基底関数の数。0を指定した場合、Bayesian linear modelを利用しない通常のガウシアンプロセスが行われます。 + + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス、 +2列目以降は ``[solver.param]`` セクションにある、 +``string_list`` で定義された変数に入る値が入ります。 + +以下、サンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``BayesData.txt`` +^^^^^^^^^^^^^^^^^^^^^^ +最適化過程の各ステップにおいて、 +パラメータと対応する目的関数の値が、 +これまでの最適パラメータとそのステップで探索したパラメータの順に記載されます。 + +.. code-block:: + + #step z1 z2 R-factor z1_action z2_action R-factor_action + 0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885 + 1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033 + 2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189 + 3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794 + ... + + +アルゴリズム解説 +~~~~~~~~~~~~~~~~~~~~~~ + +`ベイズ最適化 (Bayesian optimization, BO) `_ は、機械学習を援用した最適化アルゴリズムであり、特に目的関数の評価に時間がかかるときに強力な手法です。 + +BO では目的関数 :math:`f(\vec{x})` を、評価が早く最適化のしやすいモデル関数（多くの場合ガウス過程） :math:`g(\vec{x})` で近似します。 +:math:`g` は、あらかじめ適当に決められたいくつかの点（訓練データセット） :math:`\{\vec{x}_i\}_{i=1}^N` での目的関数の値 :math:`\{f(\vec{x}_i)\}_{i=1}^N` をよく再現するように訓練されます。 +パラメータ空間の各点において、訓練された :math:`g(\vec{x})` の値の期待値およびその誤差から求められる「スコア」 (acquition function) が最適になるような点 :math:`\vec{x}_{N+1}` を次の計算候補点として提案します。 +:math:`f(\vec{x}_{N+1})` を評価し、 訓練データセットに追加、 :math:`g` を再訓練します。 +こうした探索を適当な回数繰り返した後、目的関数の値が最も良かったものを最適解として返します。 + +少ない誤差でより良い期待値を与える点は、正解である可能性こそ高いですが、すでに十分な情報があると考えられるので、モデル関数の精度向上にはあまり寄与しません。 +逆に、誤差の大きな点は正解ではないかもしれませんが、情報の少ない場所であり、モデル関数の更新には有益だと考えられます。 +前者を選ぶことを「活用」、後者を選ぶことを「探索」とよび、両者をバランス良く行うのが重要です。 +「スコア」の定義はこれらをどう選ぶかを定めます。 + +2DMAT では、ベイズ最適化のライブラリとして、 `PHYSBO`_ を用います。 +PHYSBO は ``mapper_mpi`` のように、あらかじめ決めておいた候補点の集合に対して「スコア」を計算して、最適解を提案します。 +候補点の集合を分割することでMPI 並列実行が可能です。 +また、 訓練データの点数 :math:`N` に対して線形の計算量でモデル関数の評価、ひいては「スコア」の計算が可能となるようなカーネルを用いています。 +PHYSBO では「スコア」関数として "expected improvement (EI)", "probability of improvement (PI)", "Thompson sampling (TS)" が利用できます。 diff --git a/manual/v2.2.0/ja/_sources/algorithm/exchange.rst.txt b/manual/v2.2.0/ja/_sources/algorithm/exchange.rst.txt new file mode 100644 index 00000000..6d241114 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/algorithm/exchange.rst.txt @@ -0,0 +1,321 @@ +交換モンテカルロ法 ``exchange`` +=================================== + +``exchange`` はレプリカ交換モンテカルロ法を用いてパラメータ探索を行う ``Algorithm`` です。 + +前準備 +~~~~~~~~ + +あらかじめ `mpi4py `_ をインストールしておく必要があります。:: + + python3 -m pip install mpi4py + +入力パラメータ +~~~~~~~~~~~~~~~~~~~ + +サブセクション ``param`` と ``exchange`` を持ちます。 + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索空間を定義します。 +``mesh_path`` キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。 + +- 連続空間 + + - ``initial_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。 + + - ``unit_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: 各パラメータの単位。 + 探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 + 簡易的な無次元化・正規化を行います。 + 定義しなかった場合にはすべての次元で 1.0 となります。 + + - ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + + - ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + +- 離散空間 + + - ``mesh_path`` + + 形式: ファイルパス + + 説明: メッシュ定義ファイル。 + + - ``neighborlist_path`` + + 形式: ファイルパス + + 説明: 近傍リスト定義ファイル。 + + +[``exchange``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + 形式: 整数値。 + + 説明: モンテカルロ更新を行う回数。 + +- ``numsteps_exchange`` + + 形式: 整数値。 + + 説明: 「温度」のレプリカ交換を行う頻度。この回数だけモンテカルロ更新を行ったらレプリカ交換を実行します。 + +- ``Tmin`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最小値。 + +- ``Tmax`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最大値。 + +- ``bmin`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最小値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``bmax`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最大値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``Tlogspace`` + + 形式: 真偽値。 (default: true) + + 説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。 + true のときは対数空間で等分割します。 + +- ``nreplica_per_proc`` + + 形式: 整数。 (default: 1) + + 説明: ひとつのMPI プロセスが担当するレプリカの数。 + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス（実際には使用されません）、 +2列目以降は探索空間の座標を指定します。 + +以下、サンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +近傍リスト定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +離散空間をモンテカルロ法で探索する場合、各点 :math:`i` ごとに次に移動できる点 :math:`j` を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。 + +1列目に始点の番号 :math:`i` を記載し、 +2列目以降に :math:`i` から移動できる終点 :math:`j` を列挙します。 + +近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール ``py2dmat_neighborlist`` が提供されています。 +詳細は :doc:`../tool` を参照してください。 + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ +各レプリカについて、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの温度、4列目に目的関数の値、5列目以降にパラメータが記載されます。 + +.. code-block:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861 + 2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ +各レプリカについて、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +``trial.txt`` と同一の書式です。 + +.. code-block:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ +サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。 + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + +``result_T#.txt`` +^^^^^^^^^^^^^^^^^^^ +サンプリング結果を温度ごとにまとめ直したものです。 +``#`` は温度点の番号です。 +ファイルの1 列目はステップ数、2列目は全体での walker 番号、3列目は目的関数の値、 4列目以降は探索パラメータの値です。 + +.. code-block:: + + # T = 1.0 + 0 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 1 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 2 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 3 15 28.98676409223712 3.7442621319489637 -3.868754990884034 + + +アルゴリズム解説 +******************** + +マルコフ連鎖モンテカルロ法 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +モンテカルロ法（モンテカルロサンプリング）では、パラメータ空間中を動き回る walker :math:`\vec{x}` を重み :math:`W(\vec{x})` に従って確率的に動かすことで目的関数の最適化を行います。 +重み :math:`W(\vec{x})` として、「温度」 :math:`T > 0` を導入して :math:`W(\vec{x}) = e^{-f(\vec{x})/T}` とすることが一般的です（ボルツマン重み）。 +ほとんどの場合において、 :math:`W` に基づいて直接サンプリングする (walker を生成する) のは不可能なので、 walker を確率的に少しずつ動かすことで、頻度分布が :math:`W` に従うように時系列 :math:`\{\vec{x}_t\}` を生成します (マルコフ連鎖モンテカルロ法, MCMC)。 +:math:`\vec{x}` から :math:`\vec{x}'` へ遷移する確率を :math:`p(\vec{x}' | \vec{x})` とすると、 + +.. math:: + + W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x}) + +となるように :math:`p` を定めれば時系列 :math:`\{\vec{x}_t\}` の頻度分布が :math:`W(\vec{x})` に収束することが示されます（釣り合い条件） [#mcmc_condition]_ 。 +実際の計算では、より強い制約である詳細釣り合い条件 + +.. math:: + + p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x}) + +を課すことがほとんどです。 両辺で :math:`vec{x}` についての和を取ると釣り合い条件に帰着します。 + +:math:`p` を求めるアルゴリズムはいくつか提案されていますが、 2DMAT では Metropolis-Hasting 法 (MH法) を用います。 +MH 法では、遷移プロセスを提案プロセスと採択プロセスとに分割します。 + +1. 提案確率 :math:`P(\vec{x} | \vec{x}_t)` で候補点 :math:`\vec{x}` を生成します + + - 提案確率 :math:`P` としては :math:`\vec{x}_t` を中心とした一様分布やガウス関数などの扱いやすいものを利用します + +2. 提案された候補点 :math:`\vec{x}` を採択確率 :math:`Q(\vec{x}, | \vec{x}_t)` で受け入れ、 :math:`\vec{x}_{t+1} = \vec{x}` とします + - 受け入れなかった場合は :math:`\vec{x}_{t+1} = \vec{x}_t` とします + +採択確率 :math:`Q(\vec{x} | \vec{x}_t)` は + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right] + +とします。 +この定義が詳細釣り合い条件を満たすことは、詳細釣り合いの式に代入することで簡単に確かめられます。 +特に、重みとしてボルツマン因子を、 +提案確率として対称なもの :math:`P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})` を用いたときには、 + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right] + +という更に簡単な形になります。 + +:math:`\Delta f = f(\vec{x}) - f(\vec{x}_t)` とおいて、 +:math:`\Delta f \le 0` のときに :math:`Q = 1` となることを踏まえると、 +MH 法によるMCMC は次のようになります。 + +1. 現在地点の近くからランダムに次の座標の候補を選び、目的関数 :math:`f` の値を調べる +2. :math:`\Delta f \le 0` ならば（山を下る方向ならば）移動する +3. :math:`\Delta f > 0` ならば採択確率 :math:`Q = e^{-\Delta f / T}` で移動する +4. 1-3 を適当な回数繰り返す + +得られた時系列のうち、目的関数の値が一番小さいものを最適解とします。 +3 番のプロセスのおかげで、 :math:`\Delta f \sim T` ぐらいの山を乗り越えられるので、局所最適解にトラップされた場合にも脱出可能です。 + +レプリカ交換モンテカルロ法 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +モンテカルロ法による最適化では、温度 :math:`T` は非常に重要なハイパーパラメータとなっています。 +モンテカルロ法では、温度 :math:`T` 程度の山を乗り越えられますが、逆にそれ以上の深さの谷からは容易に脱出できません。 +そのため、局所解へのトラップを防ぐためには温度を上げる必要があります。 +一方で、 :math:`T` よりも小さい谷は谷として見えなくなるため、得られる :math:`\min f(\vec{x})` の精度も :math:`T` 程度になり、精度を上げるためには温度を下げる必要があります。 +ここから、最適解を探すためには温度 :math:`T` を注意深く決める必要があることがわかります。 + +この問題を解決する方法として、温度 :math:`T` を固定せずに更新していくというものがあります。 +たとえば、焼きなまし法 (simulated annealing) では、温度をステップごとに徐々に下げていきます。 +焼戻し法 (simulated tempering) は、温度をハイパーパラメータではなく、サンプリングすべきパラメータとして扱い、（詳細）釣り合い条件を満たすように更新することで、加熱と冷却を実現します。温度を下げることで谷の詳細を調べ、温度を上げることで谷から脱出します。 +レプリカ交換モンテカルロ法 (replica exchange Monte Carlo) は焼戻し法を更に発展させた手法で、並列焼戻し法 (parallel tempering) とも呼ばれます。 +レプリカ交換モンテカルロ法では、レプリカと呼ばれる複数の系を、それぞれ異なる温度で並列にモンテカルロシミュレーションします。 +そして、ある一定間隔で、（詳細）釣り合い条件を満たすように他のレプリカと温度を交換します。 +焼戻し法と同様に、温度を上下することで谷を調べたり脱出したりするのですが、各温度点について、かならずレプリカのどれかが対応しているため、全体として特定の温度に偏ることがなくなります。 +また、複数の MPI プロセスを用意してそれぞれレプリカを担当させることで簡単に並列化可能です。 +数多くのレプリカを用意することで温度間隔が狭まると、温度交換の採択率も上がるため、大規模並列計算に特に向いたアルゴリズムです。 +有限温度由来の「ぼやけ」がどうしても生まれるので、モンテカルロ法の結果を初期値として ``minsearch`` をするのがおすすめです。 + +.. only:: html + + .. rubric:: 脚注 + +.. [#mcmc_condition] 正確には、収束のためには非周期性とエルゴード性も必要です。 diff --git a/manual/v2.2.0/ja/_sources/algorithm/index.rst.txt b/manual/v2.2.0/ja/_sources/algorithm/index.rst.txt new file mode 100644 index 00000000..cabd8f0a --- /dev/null +++ b/manual/v2.2.0/ja/_sources/algorithm/index.rst.txt @@ -0,0 +1,19 @@ +.. 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. + +探索アルゴリズム +==================== + +探索アルゴリズム ``Algorithm`` は ``Solver`` の結果 :math:`f(x)` を用いて +パラメータ空間 :math:`\mathbf{X} \ni x` を探索します。 + +.. toctree:: + :maxdepth: 1 + + minsearch + mapper_mpi + exchange + pamc + bayes diff --git a/manual/v2.2.0/ja/_sources/algorithm/mapper_mpi.rst.txt b/manual/v2.2.0/ja/_sources/algorithm/mapper_mpi.rst.txt new file mode 100644 index 00000000..716defd8 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/algorithm/mapper_mpi.rst.txt @@ -0,0 +1,108 @@ +自明並列探索 ``mapper`` +****************************** + +``mapper_mpi`` はパラメータ空間中の候補点をあらかじめ用意しておいて、そのすべてで :math:`f(x)` を計算することで最小値を探索するアルゴリズムです。 +MPI 実行した場合、候補点の集合を等分割して各プロセスに自動的に割り振ることで自明並列計算を行います。 + +前準備 +~~~~~~~ + +MPI 並列を行う場合は、 `mpi4py `_ をインストールしておく必要があります。:: + + python3 -m pip install mpi4py + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _mapper_input_param: + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索パラメータ空間を定義します。 + +``mesh_path`` が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。 + +``mesh_path`` が定義されていない場合は、 ``min_list``, ``max_list``, ``num_list`` を用いて、 +各パラメータについて等間隔なグリッドを作成します。 + +- ``mesh_path`` + + 形式: string型 + + 説明: メッシュ定義ファイルへのパス。 + +- ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + +- ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + +- ``num_list`` + + 形式: 整数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる数。 + + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1 + ``dimension`` 列のテキストファイルで、 +1列目にメッシュのインデックス、 +2列目以降は探索パラメータ :math:`x` に対応する値を記載します。 +また、 ``#`` から始まる行はコメントとして無視されます。 + +以下、2次元パラメータ空間探索のサンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ColorMap.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +各メッシュでの候補パラメータと、その時の ``R-factor`` が記載されたファイルです。 +入力ファイルの ``[solver]`` - ``[param]`` セクションにある、 +``string_list`` で定義された変数の順番でメッシュデータは記載され、 +最後に ``R-factor`` の値が記載されます。 + +以下、出力例です。 + +.. code-block:: + + 6.000000 6.000000 0.047852 + 6.000000 5.750000 0.055011 + 6.000000 5.500000 0.053190 + 6.000000 5.250000 0.038905 + 6.000000 5.000000 0.047674 + 6.000000 4.750000 0.065919 + 6.000000 4.500000 0.053675 + 6.000000 4.250000 0.061261 + 6.000000 4.000000 0.069351 + 6.000000 3.750000 0.071868 + ... diff --git a/manual/v2.2.0/ja/_sources/algorithm/minsearch.rst.txt b/manual/v2.2.0/ja/_sources/algorithm/minsearch.rst.txt new file mode 100644 index 00000000..65638a5f --- /dev/null +++ b/manual/v2.2.0/ja/_sources/algorithm/minsearch.rst.txt @@ -0,0 +1,140 @@ +Nelder-Mead 法 ``minsearch`` +******************************* + +.. _scipy.optimize.minimize: https://docs.scipy.org/doc/scipy/reference/optimize.minimize-neldermead.html + +``minsearch`` は `Nelder-Mead 法 `_ (a.k.a. downhill simplex 法) によって最適化を行います。 +Nelder-Mead 法では、 パラメータ空間の次元を :math:`D` として、 :math:`D+1` 個の座標点の組を、各点での目的関数の値に応じて系統的に動かすことで最適解を探索します。 + +重要なハイパーパラメータとして、座標の初期値があります。 +局所最適解にトラップされるという問題があるので、初期値を変えた計算を何回か繰り返して結果を確認することをおすすめします。 + +2DMATは、SciPy の ``scipy.optimize.minimize(method="Nelder-Mead")`` 関数を用いています。 +詳しくは `公式ドキュメント `_ をご参照ください。 + + +前準備 +~~~~~~ + +あらかじめ `scipy `_ をインストールしておく必要があります。 :: + + python3 -m pip install scipy + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サブセクション ``param`` と ``minimize`` を持ちます。 + +.. _minsearch_input_param: + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``initial_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。 + +- ``unit_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: 各パラメータの単位。 + 探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 + 簡易的な無次元化・正規化を行います。 + 定義しなかった場合にはすべての次元で 1.0 となります。 + +- ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + 最適化中にこの値を下回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + +- ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + 最適化中にこの値を上回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + +[``minimize``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Nelder-Mead 法のハイパーパラメータを設定します。 +詳細は `scipy.optimize.minimize`_ のドキュメントを参照してください。 + +- ``initial_scale_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: Nelder-Mead 法の初期 simplex を作るために、初期値からずらす差分。 + ``initial_list`` と、 ``initial_list`` に ``initial_scale_list`` の成分ひとつを足してできるdimension 個の点を 合わせたものが ``initial_simplex`` として使われます。 + 定義しなかった場合、各次元に 0.25 が設定されます。 + +- ``xatol`` + + 形式: 実数型 (default: 1e-4) + + 説明: Nelder-Mead 法の収束判定に使うパラメータ + +- ``fatol`` + + 形式: 実数型 (default: 1e-4) + + 説明: Nelder-Mead 法の収束判定に使うパラメータ + +- ``maxiter`` + + 形式: 整数 (default: 10000) + + 説明: Nelder-Mead 法の反復回数の最大値 + +- ``maxfev`` + + 形式: 整数 (default: 100000) + + 説明: 目的関数を評価する回数の最大値 + + +出力ファイル +~~~~~~~~~~~~~~~~~ + +``SimplexData.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +最小値を求める途中経過に関する情報を出力します。 +1行目はヘッダー、2行目以降にstep, 入力ファイルの ``[solver]`` - ``[param]`` セクションにある、 +``string_list`` で定義された変数の値、最後に関数の値が出力されます。 + +以下、出力例です。 + +.. code-block:: + + #step z1 z2 z3 R-factor + 0 5.25 4.25 3.5 0.015199251773721183 + 1 5.25 4.25 3.5 0.015199251773721183 + 2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375 + 3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261 + 4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + 5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + +``res.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +最終的に得られた目的関数の値とその時のパラメータの値を記載しています。 +最初に目的関数が、 +その後は入力ファイルの ``[solver]`` - ``[param]`` セクションにある、 +``string_list`` で定義された変数の値が順に記載されます。 + +以下、出力例です。 + +.. code-block:: + + fx = 7.382680568652868e-06 + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 diff --git a/manual/v2.2.0/ja/_sources/algorithm/pamc.rst.txt b/manual/v2.2.0/ja/_sources/algorithm/pamc.rst.txt new file mode 100644 index 00000000..547e4bd9 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/algorithm/pamc.rst.txt @@ -0,0 +1,476 @@ +ポピュレーションアニーリングモンテカルロ法 ``pamc`` +========================================================= + +``pamc`` はポピュレーションアニーリングモンテカルロ法を用いてパラメータ探索を行う ``Algorithm`` です。 + +前準備 +~~~~~~~~ + +MPI 並列をする場合にはあらかじめ `mpi4py `_ をインストールしておく必要があります。:: + + python3 -m pip install mpi4py + +入力パラメータ +~~~~~~~~~~~~~~~~~~~ + +サブセクション ``param`` と ``pamc`` を持ちます。 + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索空間を定義します。 +``mesh_path`` キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。 + +- 連続空間 + + - ``initial_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。 + + - ``unit_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: 各パラメータの単位。 + 探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 + 簡易的な無次元化・正規化を行います。 + 定義しなかった場合にはすべての次元で 1.0 となります。 + + - ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + + - ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + +- 離散空間 + + - ``mesh_path`` + + 形式: ファイルパス + + 説明: メッシュ定義ファイル。 + + - ``neighborlist_path`` + + 形式: ファイルパス + + 説明: 近傍リスト定義ファイル。 + + +[``pamc``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + 形式: 整数値。 + + 説明: モンテカルロ更新を行う総回数。 + +- ``numsteps_annealing`` + + 形式: 整数値。 + + 説明: 「温度」を下げる頻度。この回数モンテカルロ更新を行った後に温度が下がります。 + +- ``numT`` + + 形式: 整数値。 + + 説明: 「温度」点の数。 + +- ``Tmin`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最小値。 + +- ``Tmax`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最大値。 + +- ``bmin`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最小値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``bmax`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最大値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``Tlogspace`` + + 形式: 真偽値。 (default: true) + + 説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。 + true のときは対数空間で等分割します。 + +- ``nreplica_per_proc`` + + 形式: 整数。 (default: 1) + + 説明: ひとつのMPI プロセスが担当するレプリカの数。 + +- ``resampling_interval`` + + 形式: 整数。 (default: 1) + + 説明: レプリカのリサンプリングを行う頻度。この回数だけ温度降下を行った後にリサンプリングが行われます。 + +- ``fix_num_replicas`` + + 形式: 真偽値。 (default: true) + + 説明: リサンプリングの際、レプリカ数を固定するかどうか。 + +ステップ数について +******************** + +``numsteps``, ``numsteps_annealing``, ``numT`` の3つのうち、どれか2つを同時に指定してください。 +残りの1つは自動的に決定されます。 + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス（実際には使用されません）、 +2列目以降は探索空間の座標を指定します。 + +以下、サンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +近傍リスト定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +離散空間をモンテカルロ法で探索する場合、各点 :math:`i` ごとに次に移動できる点 :math:`j` を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。 + +1列目に始点の番号 :math:`i` を記載し、 +2列目以降に :math:`i` から移動できる終点 :math:`j` を列挙します。 + +近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール ``py2dmat_neighborlist`` が提供されています。 +詳細は :doc:`../tool` を参照してください。 + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +各温度点(``#``) ごと、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの逆温度、4列目に目的関数の値、5列目からパラメータが記載されます。 +最後の2列はそれぞれレプリカの重み (Neal-Jarzynski weight) と祖先（計算開始時のレプリカ番号）です。 + +.. code-block:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +``trial_T#.txt`` をすべてまとめたものです。 + +``RANK/result_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +各温度点、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +``trial.txt`` と同一の書式です。 + +.. code-block:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +``result_T#.txt`` をすべてまとめたものです。 + + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ + +サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。 + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + + +``fx.txt`` +^^^^^^^^^^^^^^ + +各温度ごとに、全レプリカの情報をまとめたものです。 +1列目は逆温度が、2列目と3列目には目的関数の期待値およびその標準誤差が、4列目にはレプリカの総数が、5列目には規格化因子（分配関数）の比の対数 + +.. math:: + + \log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)} + +が、6列目にはモンテカルロ更新の採択率が出力されます。 +ここで :math:`\beta_0` は計算している :math:`\beta` の最小値です。 + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804 + 0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058 + 0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004 + ... + +アルゴリズム解説 +~~~~~~~~~~~~~~~~~~~ + +問題と目的 +^^^^^^^^^^^^ + +分布パラメータ :math:`\beta_i` のもとでの配位 :math:`x` の重みを +:math:`f_i(x)` と書くと（例えばボルツマン因子 :math:`f_i(x) = \exp\left[-\beta_i E(x)\right]`\ ）、 +:math:`A` の期待値は + +.. math:: + + \langle A\rangle_i + = \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} + = \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) + = \int \mathrm{d}xA(x)\tilde{f}_i(x) + +とかけます。 +ここで :math:`Z = \int \mathrm{d} x f_i(x)` は規格化因子（分配関数）で、 :math:`\tilde{f}(x) = f(x)/Z` は配位 :math:`x` の確率密度です。 + +目的は複数の分布パラメータについてこの期待値および規格化因子（の比）を数値的に求めることです。 + +Annealed Importance Sampling (AIS) [1] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +次の同時確率分布 + +.. math:: + + \tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0) + +を満たす点列 :math:`\{x_i\}` を考えます。ここで + +.. math:: + + \tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} + +であり、 :math:`T_i(x, x')` は :math:`\beta_i` のもとでの配位 :math:`x` +から :math:`x'` への遷移確率で、釣り合い条件 + +.. math:: + + + \int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x') + +を満たすようにとります（つまりは普通のMCMCにおける遷移確率行列）。 + +.. math:: + + + \int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) + = \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) + = 1 + +となるので、 :math:`\tilde{f}_n(x_n)` は +:math:`\tilde{f}(x_0, x_1, \dots, x_n)` の周辺分布 + +.. math:: + + + \tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n) + +です。 +これを利用すると、 :math:`\tilde{f}_n` における平均値 :math:`\langle A \rangle_n` は拡張した配位の重み付き平均として + +.. math:: + + + \begin{split} + \langle A \rangle_n + &\equiv + \int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) + \end{split} + +と表せます。 + +さて、残念ながら :math:`\tilde{f}(x_0, x_1, \dots, x_n)` +に従うような点列を直接生成することは困難です。そこでもっと簡単に、 + +1. 確率 :math:`\tilde{f}_0(x)` に従う :math:`x_0` を生成する + + - 例えば MCMC を利用する + +2. :math:`x_i` から :math:`T_{i+1}(x_i, x_{i+1})` によって :math:`x_{i+1}` を生成する + + - :math:`T_{i+1}` は釣り合い条件を満たすような遷移確率行列なので、普通にMCMCを行えば良い + +という流れに従って点列 :math:`\{x_i\}` を生成すると、これは同時確率分布 + +.. math:: + + \tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n) + +に従います。これを利用すると期待値 :math:`\langle A \rangle_n` は + +.. math:: + + + \begin{split} + \langle A \rangle_n + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ + &= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + \end{split} + +と評価できます (reweighting method)。 +:math:`\tilde{f}` と :math:`\tilde{g}` との比は、 + +.. math:: + + + \begin{split} + \frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \frac{f_n(x_n)}{f_0(x_0)} + \prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ + &\equiv + \frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n) + \end{split} + +とかけるので、期待値は + +.. math:: + + \langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + = \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n} + +となります。 +規格化因子の比 :math:`Z_n/Z_0` は :math:`\langle 1 \rangle_n = 1` を用いると + +.. math:: + + \frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n} + +と評価できるので、 :math:`A` の期待値は + +.. math:: + + \langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}} + +という、重み付き平均の形で評価できます。 +この重み :math:`w_n` を Neal-Jarzynski 重みと呼びます。 + +population annealing (PA) [2] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +AIS を使うと各 :math:`\beta` に対する期待値を重み付き平均という形で計算できますが、 +:math:`\beta` の幅が大きくなると重み :math:`w` の分散が大きくなってしまいます。 +そのため、適当な周期で確率 :math:`p^{(k)} = w^{(k)} / \sum_k w^{(k)}` に従いレプリカをリサンプリングし、 +レプリカに割当られた重みをリセット :math:`(w=1)` します。 + +PAMC のアルゴリズムは次の擬似コードで示されます: + +.. code-block:: python + + for k in range(K): + w[0, k] = 1.0 + x[0, k] = draw_from(β[0]) + for i in range(1, N): + for k in range(K): + w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) ) + if i % interval == 0: + x[i, :] = resample(x[i, :], w[i, :]) + w[i, :] = 1.0 + for k in range(K): + x[i, k] = transfer(x[i-1, k], β[i]) + a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:]) + +リサンプリング手法として、レプリカ数を固定する方法[2]と固定しない方法[3]の2通りがあります。 + +参考文献 +^^^^^^^^^^^^^ + +[1] R. M. Neal, Statistics and Computing **11**, 125-139 (2001). + +[2] K. Hukushima and Y. Iba, AIP Conf. Proc. **690**, 200 (2003). + +[3] J. Machta, PRE **82**, 026704 (2010). diff --git a/manual/v2.2.0/ja/_sources/contact.rst.txt b/manual/v2.2.0/ja/_sources/contact.rst.txt new file mode 100644 index 00000000..7817c383 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/contact.rst.txt @@ -0,0 +1,22 @@ +お問い合わせ +========================================= + +2DMAT に関するお問い合わせはこちらにお寄せください。 + +- バグ報告 + + 2DMAT のバグ関連の報告は `GitHubのIssues `_ で受け付けています。 + + バグを早期に解決するため、報告時には次のガイドラインに従ってください。 + + - 使用している 2DMAT のバージョンを指定してください。 + + - インストールに問題がある場合には、使用しているオペレーティングシステムとコンパイラの情報についてお知らせください。 + + - 実行に問題が生じた場合は、実行に使用した入力ファイルとその出力を記載してください。 + +- その他 + + 研究に関連するトピックなどGitHubのIssuesで相談しづらいことを問い合わせる際には、以下の連絡先にコンタクトをしてください。 + + E-mail: ``2dmat-dev__at__issp.u-tokyo.ac.jp`` (_at_を@に変更してください) diff --git a/manual/v2.2.0/ja/_sources/customize/algorithm.rst.txt b/manual/v2.2.0/ja/_sources/customize/algorithm.rst.txt new file mode 100644 index 00000000..21ad0f0f --- /dev/null +++ b/manual/v2.2.0/ja/_sources/customize/algorithm.rst.txt @@ -0,0 +1,123 @@ +``Algorithm`` の定義 +====================== + +``Algorithm`` クラスは ``py2dmat.algorithm.AlgorithmBase`` を継承したクラスとして定義します。 :: + + import py2dmat + + class Algorithm(py2dmat.algorithm.AlgorithmBase): + pass + +``AlgorithmBase`` +~~~~~~~~~~~~~~~~~~~ + +``AlgorithmBase`` クラスは次のメソッドを提供します。 + +- ``__init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)`` + + - ``info`` から ``Algorithm`` 共通の入力パラメータを読み取り、次のインスタンス変数を設定します。 + + - ``self.mpicomm: Optional[MPI.Comm]`` : ``MPI.COMM_WORLD`` + + - ``mpi4py`` の import に失敗した場合、 ``None`` が設定されます + + - ``self.mpisize: int`` : MPIプロセス数 + + - ``mpi4py`` の import に失敗した場合、 ``1`` が設定されます + + - ``self.mpirank: int`` : MPIランク + + - ``mpi4py`` の import に失敗した場合、 ``0`` が設定されます + + - ``self.rng: np.random.Generator`` : 擬似乱数生成器 + + - 擬似乱数の種について、詳細は :ref:`入力パラメータの [algorithm] セクション ` を参照してください + + - ``self.dimension: int`` : 探索パラメータ空間の次元 + - ``self.label_list: List[str]`` : 各パラメータの名前 + - ``self.root_dir: pathlib.Path`` : ルートディレクトリ + + - ``info.base["root_dir"]`` + + - ``self.output_dir: pathlib.Path`` : 出力ファイルを書き出すディレクトリ + + - ``info.base["root_dir"]`` + + - ``self.proc_dir: pathlib.Path`` : プロセスごとの作業用ディレクトリ + + - ``self.output_dir / str(self.mpirank)`` + - ディレクトリが存在しない場合、自動的に作成されます + - 各プロセスで最適化アルゴリズムはこのディレクトリで実行されます + + - ``self.timer: Dict[str, Dict]`` : 実行時間を保存するための辞書 + + - 空の辞書が3つ、 ``"prepare"``, ``"run"``, ``"post"`` という名前で定義されます + +- ``prepare(self) -> None`` + + - 最適化アルゴリズムの前処理をします + - ``self.run()`` の前に実行する必要があります + +- ``run(self) -> None`` + + - 最適化アルゴリズムを実行します + - ``self.proc_dir`` に移動し、 ``self._run()`` を実行した後、元のディレクトリに戻ります + +- ``post(self) -> None`` + + - 最適化結果のファイル出力など、後処理を行います + - ``self.output_dir`` に移動し、 ``self._post()`` を実行した後、元のディレクトリに戻ります + - ``self.run()`` のあとに実行する必要があります + +- ``main(self) -> None`` + + - ``prepare``, ``run``, ``post`` を順番に実行します + - それぞれの関数でかかった時間を計測し、結果をファイル出力します + + +- ``_read_param(self, info: py2dmat.Info) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]`` + + - 連続なパラメータ空間を定義するためのヘルパーメソッドです + - ``info.algorithm["param"]`` から探索パラメータの初期値や最小値、最大値、単位を取得します + - 詳細は :ref:`min_search の入力ファイル ` を参照してください + +- ``_mesh_grid(self, info: py2dmat.Info, split: bool = False) -> Tuple[np.ndarray, np.ndarray]`` + + - 離散的なパラメータ空間を定義するためのヘルパーメソッドです + - ``info.algorithm["param"]`` を読み取り次を返します: + + - ``D`` 次元の候補点 ``N`` 個からなる集合 (``NxD`` 次元の行列として) + - ``N`` 個の候補点のID(index) + + - ``split`` が ``True`` の場合、候補点集合は分割され各MPI ランクに配られます + - 詳細は :ref:`mapper の入力ファイル ` を参照してください + + +``Algorithm`` +~~~~~~~~~~~~~~~~ + +``Algorithm`` は少なくとも次のメソッドを定義しなければなりません。 + +- ``__init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)`` + + - 引数はそのまま基底クラスのコンストラクタに転送してください + + - ``super().__init__(info=info, runner=runner)`` + + - 入力パラメータである ``info`` から必要な設定を読み取り、保存してください + +- ``_prepare(self) -> None`` + + - 最適化アルゴリズムの前処理を記述します + +- ``_run(self) -> None`` + + - 最適化アルゴリズムを記述します + - 探索パラメータ ``x`` から対応する目的関数の値 ``f(x)`` を得る方法 :: + + message = py2dmat.Message(x, step, set) + fx = self.runner.submit(message) + +- ``_post(self) -> None`` + + - 最適化アルゴリズムの後処理を記述します diff --git a/manual/v2.2.0/ja/_sources/customize/common.rst.txt b/manual/v2.2.0/ja/_sources/customize/common.rst.txt new file mode 100644 index 00000000..014e498f --- /dev/null +++ b/manual/v2.2.0/ja/_sources/customize/common.rst.txt @@ -0,0 +1,90 @@ +共通事項 +========== + +``Solver`` と ``Algorithm`` に共通する事柄について説明します。 + +``py2dmat.Info`` +~~~~~~~~~~~~~~~~~~ +入力パラメータを扱うためのクラスです。 +インスタンス変数として次の4つの ``dict`` を持ちます。 + +- ``base`` + + - ディレクトリ情報など、プログラム全体で共通するパラメータ + +- ``solver`` + + - ``Solver`` が用いる入力パラメータ + +- ``algorithm`` + + - ``Algorithm`` が用いる入力パラメータ + +- ``runner`` + + - ``Runner`` が用いる入力パラメータ + + +``Info`` は ``base``, ``solver``, ``algorithm``, ``runner`` の4つのキーを持つような ``dict`` を渡して初期化出来ます。 + +- ``base`` について + + - 要素として計算のルートディレクトリ ``root_dir`` と出力のルートディレクトリ ``output_dir`` が自動で設定されます + + - ルートディレクトリ ``root_dir`` + + - 絶対パスに変換されたものがあらためて ``root_dir`` に設定されます + - 先頭の ``~`` はホームディレクトリに展開されます + - デフォルトはカレントディレクトリ ``"."`` です + - 具体的には次のコードが実行されます :: + + p = pathlib.Path(base.get("root_dir", ".")) + base["root_dir"] = p.expanduser().absolute() + + - 出力ディレクトリ ``output_dir`` + + - 先頭の ``~`` はホームディレクトリに展開されます + - 絶対パスが設定されていた場合はそのまま設定されます + - 相対パスが設定されていた場合、 ``root_dir`` を起点とした相対パスとして解釈されます + - デフォルトは ``"."`` 、つまり ``root_dir`` と同一ディレクトリです + - 具体的には次のコードが実行されます :: + + p = pathlib.Path(base.get("work_dir", ".")) + p = p.expanduser() + base["work_dir"] = base["root_dir"] / p + + +``py2dmat.Message`` +~~~~~~~~~~~~~~~~~~~~~~ +``Algorithm`` から ``Runner`` を介して ``Solver`` に渡されるクラスです。 +次の3つのインスタンス変数を持ちます。 + +- ``x: np.ndarray`` + + - 探索中のパラメータ座標 + +- ``step: int`` + + - 何個目のパラメータであるか + - 例えば ``exchange`` ではステップ数で、 ``mapper`` ではパラメータの通し番号。 + +- ``set: int`` + + - 何巡目のパラメータであるか + - 例えば ``min_search`` では最適化（1巡目）後にステップごとの最適値を再計算します（2巡目）。 + +``py2dmat.Runner`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ +``Algorithm`` と ``Solver`` とをつなげるためのクラスです。 +コンストラクタ引数として ``Solver`` のインスタンスと ``Info`` のインスタンス、パラメータの変換ルーチン ``mapping : Callable[[np.ndarray], np.ndarray]`` を取ります。 + +``submit(self, message: py2dmat.Message) -> float`` メソッドでソルバーを実行し、結果を返します。 +探索パラメータを ``x`` として、 目的関数 ``fx = f(x)`` を得たい場合は以下のようにします :: + + message = py2dmat.Message(x, step, set) + fx = runner.submit(message) + +``submit`` メソッドは ``mapping`` を用いて、探索アルゴリズムのパラメータ ``x`` から実際にソルバーが使う入力 ``y = mapping(x)`` を得ます。 +``mapping`` を省略した場合 (``None`` を渡した場合)、変換ルーチンとしてアフィン写像 :math:`y=Ax+b` が用いられます (``py2dmat.util.mapping.Affine(A,b)``)。 +``A, b`` の要素は ``info`` で与えられます。 +その他、 ``Runner`` で使われる ``info`` の詳細は :doc:`../input` を参照してください。 diff --git a/manual/v2.2.0/ja/_sources/customize/index.rst.txt b/manual/v2.2.0/ja/_sources/customize/index.rst.txt new file mode 100644 index 00000000..94dd700d --- /dev/null +++ b/manual/v2.2.0/ja/_sources/customize/index.rst.txt @@ -0,0 +1,20 @@ +.. 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. + +(開発者向け)ユーザー定義アルゴリズム・ソルバー +================================================= + +本ソフトウェアは、順問題のためのソルバー ``Solver`` と最適化のためのアルゴリズム ``Algorithm`` を組み合わせることで全体の逆問題を解きます。 +``Solver`` と ``Algorithm`` はすでに定義済みのものがいくつかありますが、これらを自分で定義することで、適用範囲を広げられます。 +本章では、 ``Solver`` や ``Algorithm`` を定義する方法およびこれらを使用する方法を解説します。 + + +.. toctree:: + :maxdepth: 1 + + common + solver + algorithm + usage diff --git a/manual/v2.2.0/ja/_sources/customize/solver.rst.txt b/manual/v2.2.0/ja/_sources/customize/solver.rst.txt new file mode 100644 index 00000000..3cbcf4ab --- /dev/null +++ b/manual/v2.2.0/ja/_sources/customize/solver.rst.txt @@ -0,0 +1,59 @@ +``Solver`` の定義 +================== + +``Solver`` クラスは ``py2dmat.solver.SolverBase`` を継承したクラスとして定義します。:: + + import py2dmat + + class Solver(py2dmat.solver.SolverBase): + pass + +このクラスは少なくとも次のメソッドを定義しなければなりません。 + +- ``__init__(self, info: py2dmat.Info)`` + + - 必ず基底クラスのコンストラクタを呼び出してください + + - ``super().__init__(info)`` + + - 基底クラスのコンストラクタでは次のインスタンス変数が設定されます + + - ``self.root_dir: pathlib.Path`` : ルートディレクトリ + + - ``info.base["root_dir"]`` + + - ``self.output_dir: pathlib.Path`` : 出力ファイルを書き出すディレクトリ + + - ``info.base["output_dir"]`` + + - ``self.proc_dir: pathlib.Path`` : プロセスごとの作業用ディレクトリ + + - ``self.output_dir / str(self.mpirank)`` で初期化されます + + - ``self.work_dir: pathlib.Path`` : ソルバーが実行されるディレクトリ + + - ``self.proc_dir`` で初期化されます + + - 入力パラメータである ``info`` から必要な設定を読み取り、保存してください + +- ``prepare(self, message: py2dmat.Message) -> None`` + + - ソルバーが実行される前によびだされます + - ``message`` には入力パラメータが含まれるので、ソルバーが利用できる形に変換してください + + - 例：ソルバーの入力ファイルを生成する + +- ``run(self, nprocs: int = 1, nthreads: int = 1) -> None`` + + - ソルバーを実行します + - 後ほど ``get_results`` で目的関数の値を読み取れるようにしておいてください + + - 例：出力結果をインスタンス変数に保存しておく + - 例：実行結果をファイルに保存しておく + +- ``get_results(self) -> float`` + + - ソルバーが実行されたあとに呼び出されます + - ソルバーの実行結果を返却してください + + - 例：ソルバーの出力ファイルから実行結果を読み取る diff --git a/manual/v2.2.0/ja/_sources/customize/usage.rst.txt b/manual/v2.2.0/ja/_sources/customize/usage.rst.txt new file mode 100644 index 00000000..1fcb6698 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/customize/usage.rst.txt @@ -0,0 +1,48 @@ +実行方法 +=========== + +次のようなフローで最適化問題を実行できます。 +プログラム例にあるコメントの番号はフローの番号に対応しています。 + +1. ユーザ定義クラスを作成する + + - もちろん、 ``py2dmat`` で定義済みのクラスも利用可能です + +2. 入力パラメータ ``info: py2dmat.Info`` を作成する + + - プログラム例では入力ファイルとしてTOML を利用していますが、辞書をつくれれば何でも構いません + +3. ``solver: Solver``, ``runner: py2dmat.Runner``, ``algorithm: Algorithm`` を作成する + +4. ``algorithm.main()`` を実行する + + +プログラム例 + +.. code-block:: python + + import sys + import tomli + import py2dmat + + # (1) + class Solver(py2dmat.solver.SolverBase): + # Define your solver + pass + + class Algorithm(py2dmat.algorithm.AlgorithmBase): + # Define your algorithm + pass + + # (2) + with open(sys.argv[1]) as f: + inp = tomli.load(f) + info = py2dmat.Info(inp) + + # (3) + solver = Solver(info) + runner = py2dmat.Runner(solver, info) + algorithm = Algorithm(info, runner) + + # (4) + algorithm.main() diff --git a/manual/v2.2.0/ja/_sources/index.rst.txt b/manual/v2.2.0/ja/_sources/index.rst.txt new file mode 100644 index 00000000..d0758145 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/index.rst.txt @@ -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 + start + tutorial/index + input + output + algorithm/index + solver/index + tool + customize/index + acknowledgement + contact diff --git a/manual/v2.2.0/ja/_sources/input.rst.txt b/manual/v2.2.0/ja/_sources/input.rst.txt new file mode 100644 index 00000000..d558044e --- /dev/null +++ b/manual/v2.2.0/ja/_sources/input.rst.txt @@ -0,0 +1,285 @@ +入力ファイル +===================== + +py2dmat は入力ファイルの形式に `TOML `_ を採用しています。 +入力ファイルは次の6つのセクションから構成されます。 + +- ``base`` + + - ``py2dmat`` 全体のパラメータを指定します。 + +- ``solver`` + + - ``Solver`` のパラメータを指定します。 + +- ``algorithm`` + + - ``Algorithm`` のパラメータを指定します。 + +- ``runner`` + + - ``Runner`` のパラメータを指定します。 + +- ``mapping`` + + - ``Algorithm`` で探索しているパラメータから ``Solver`` で使うパラメータへの写像を定義します。 + +- ``log`` + + - solver 呼び出しのlogging に関して設定します。 + +[``base``] セクション +************************ + +- ``dimension`` + + 形式: 整数型 + + 説明: 探索空間の次元（探索するパラメータの数） + +- ``root_dir`` + + 形式: string型 (default: プログラム実行時のディレクトリ) + + 説明: プログラムを実行する一番上のディレクトリ。 + 入力ファイルなどのパスはすべて ``root_dir`` を起点とします。 + +- ``output_dir`` + + 形式: string型 (default: プログラム実行時のディレクトリ) + + 説明: プログラムの実行結果を出力するディレクトリ名 + +[``solver``] セクション +************************ + +``name`` でソルバーの種類を決定します。各パラメータはソルバーごとに定義されています。 + +- ``name`` + + 形式: string型 + + 説明: ソルバーの名前。以下のソルバーが用意されています。 + + - ``sim-trhepd-rheed`` : 反射高速(陽)電子回折(RHEED, TRHEPD)の強度計算をするためのソルバー ``sim-trhepd-rheed`` + + - ``analytical`` : 解析解を与えるソルバー (主にテストに利用) + +- ``dimension`` + + 形式: 整数型 (default: ``base.dimension``) + + 説明: ソルバーが受け取る入力パラメータの数。 + + +各種ソルバーの詳細および入出力ファイルは :doc:`solver/index` を参照してください。 + +.. _input_algorithm: + +[``algorithm``] セクション +******************************* + +``name`` でアルゴリズムの種類を決定します。各パラメータはアルゴリズムごとに定義されています。 + +- ``name`` + + 形式: string型 + + 説明: アルゴリズムの名前。以下のアルゴリズムが用意されています。 + + - ``minsearch`` : Nelder-Mead法による最小値探索 + + - ``mapper`` : グリッド探索 + + - ``exchange`` : レプリカ交換モンテカルロ + + - ``bayes`` : ベイズ最適化 + +- ``seed`` + + 形式: 整数値。 + + 説明: 初期値のランダム生成やモンテカルロ更新などで用いる擬似乱数生成器の種を指定します。 + 各MPIプロセスに対して、 ``seed + mpi_rank * seed_delta`` の値が実際の種として用いられます。 + 省略した場合は `Numpy の規定の方法 `_ で初期化されます。 + + +- ``seed_delta`` + + 形式: 整数値。 (default: 314159) + + 説明: 疑似乱数生成器の種について、MPI プロセスごとの値を計算する際に用いられます。 + 詳しくは ``seed`` を参照してください。 + + +各種アルゴリズムの詳細および入出力ファイルは :doc:`algorithm/index` を参照してください。 + + +[``runner``] セクション +************************ +``Algorithm`` と ``Solver`` を橋渡しする要素である ``Runner`` の設定を記述します。 +サブセクションとして ``mapping`` 、 ``limitation`` 、 ``log`` を持ちます。 + + +[``mapping``] セクション +************************************************ + +``Algorithm`` で探索している :math:`N` 次元のパラメータ :math:`x` から ``Solver`` で使う :math:`M` 次元のパラメータ :math:`y` への写像を定義します。 +:math:`N \ne M` となる場合には、 ``solver`` セクションにも ``dimension`` パラメータを指定してください。 + +現在はアフィン写像（線形写像+平行移動） :math:`y = Ax+b` が利用可能です。 + +- ``A`` + + 形式: リストのリスト、あるいは文字列 (default: []) + + 説明: :math:`N \times M` の変換行列 :math:`A` 。空のリストを渡した場合、単位行列とみなされます。 + 文字列として与える場合はそのまま行列の要素を空白および改行で区切って並べてください。 + +- ``b`` + + 形式: リスト、あるいは文字列 (default: []) + + 説明: :math:`M` 次元の並進移動ベクトル :math:`b` 。空のリストを渡した場合、ゼロベクトルとみなされます。 + 文字列として与える場合はそのままベクトルの要素を空白区切りで並べてください。 + +行列の指定方法について、例えば、 :: + + A = [[1,1], [0,1]] + +と :: + + A = """ + 1 1 + 0 1 + """ + +はともに + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right) + +を表します。 + +[``limitation``] セクション +************************************************ + +``Algorithm`` で探索している :math:`N` 次元のパラメータ :math:`x` に、制約条件を課すことが出来ます。 +``Algorithm`` ごとに定義する探索範囲（例：``exchange`` の ``min_list`` や ``max_list`` ） に加えて課すことが出来ます。 +現在は :math:`M` 行 :math:`N` 列の行列:math:`A` と :math:`M` 次元の縦ベクトル:math:`b` から定義される :math:`Ax+b>0` の制約式が利用可能です。具体的に + +.. math:: + + A_{1,1} x_{1} + A_{1,2} x_{2} + &... + A_{1,N} x_{N} + b_{1} > 0\\ + A_{2,1} x_{1} + A_{2,2} x_{2} + &... + A_{2,N} x_{N} + b_{2} > 0\\ + &...\\ + A_{M,1} x_{1} + A_{M,2} x_{2} + &... + A_{M,N} x_{N} + b_{M} > 0 + +という制約をかけることが出来ます。 +ここで :math:`M` は制約式の個数（任意）となります。 + +- ``co_a`` + + 形式: リストのリスト、あるいは文字列 (default: []) + + 説明: 制約式の行列 :math:`A` を設定します。 + + 行数は制約式数 :math:`M` 列数は探索変数の数 :math:`N` である必要があります。 + + ``co_b`` を同時に定義する必要があります。 + +- ``co_b`` + + 形式: リストのリスト、あるいは文字列 (default: []) + + 説明: 制約式の縦ベクトル :math:`b` を設定します。 + + 次元数が制約式数 :math:`M` の縦ベクトルを設定する必要があります。 + + ``co_a`` を同時に定義する必要があります。 + +行列の指定方法について、[``mapping``] セクションと同様で、例えば、 :: + + A = [[1,1], [0,1]] + +と :: + + A = """ + 1 1 + 0 1 + """ + +はともに + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right) + +を表します。また、 :: + + co_b = [[0], [-1]] + +と :: + + co_b = """0 -1""" + +と :: + + co_b = """ + 0 + -1 + """ + +はともに + +.. math:: + + b = \left( + \begin{matrix} + 0 \\ + -1 + \end{matrix} + \right) + +を表します。 +``co_a`` と ``co_b`` のどちらも定義しない場合、制約式を課さずに探索します。 + +[``log``] セクション +************************************************ + +solver 呼び出しのlogging に関する設定です。 + +- ``filename`` + + 形式: 文字列 (default: "runner.log") + + 説明: ログファイルの名前。 + +- ``interval`` + + 形式: 整数 (default: 0) + + 説明: solver を interval 回呼ぶ毎にログが書き出されます。0以下の場合、ログ書き出しは行われません。 + +- ``write_result`` + + 形式: 真偽値 (default: false) + + 説明: solver からの出力を記録するかどうか。 + +- ``write_input`` + + 形式: 真偽値 (default: false) + + 説明: solver への入力を記録するかどうか。 diff --git a/manual/v2.2.0/ja/_sources/introduction.rst.txt b/manual/v2.2.0/ja/_sources/introduction.rst.txt new file mode 100644 index 00000000..40bec3f8 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/introduction.rst.txt @@ -0,0 +1,89 @@ +はじめに +===================== + +2DMATとは +---------------------- + +2DMATは，順問題ソルバーに対して探索アルゴリズムを適用して最適解を探すためのフレームワークです. 順問題ソルバーはユーザー自身で定義することが可能です. +標準的な順問題ソルバーとしては2次元物質構造解析向け実験データ解析ソフトウェアが用意されています. 順問題ソルバーでは原子位置などをパラメータとし得られたデータと実験データとのずれを損失関数として与えます. +探索アルゴリズムを組み合わせ, この損失関数を最小化することで, 最適なパラメータを推定します. +現バージョンでは, 順問題ソルバーとして量子ビーム回折実験の全反射高速陽電子回折実験（Total-reflection high-energy positron diffraction ,TRHEPD，トレプト）[1, 2],sxrd[3], leed[4]に対応しており, +探索アルゴリズムはNelder-Mead法[5], グリッド型探索法[6], ベイズ最適化[7], レプリカ交換モンテカルロ法[8], ポピュレーションアニーリングモンテカルロ法[9, 10, 11]が実装されています. 今後は, 本フレームワークをもとにより多くの順問題ソルバーおよび探索アルゴリズムを実装していく予定です. + +[1] レビューとして， `Y．Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019) `_; +`兵頭俊夫，「全反射高速陽電子回折　(TRHEPD)による表面構造解析」，固体物理 53, 705 (2018) `_. + +[2] `T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022). `_ + +[3] W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252 (2006) 5259. + +[4] `M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). `_ + +[5] `K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020) `_. + +[6] `K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series, `_. + +[7] `Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022) `_ + +[8] `K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996) `_, `R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986) `_. + +[9] `R. M. Neal, Statistics and Computing 11, 125-139 (2001). `_ + +[10] `K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003). `_ + +[11] `J. Machta, Phys. Rev. E 82, 026704 (2010). `_ + +ライセンス +---------------------- +| 本ソフトウェアのプログラムパッケージおよびソースコード一式はGNU + General Public License version 3（GPL v3）に準じて配布されています。 + +Copyright (c) <2020-> The University of Tokyo. All rights reserved. + +本ソフトウェアは2020年度 東京大学物性研究所 ソフトウェア高度化プロジェクトの支援を受け開発されました。 +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} +} + + + +バージョン履歴 +---------------------- + +- 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は以下のメンバーで開発しています. + +- v2.0.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 岩本 晴道 (鳥取大学 大学院工学研究科) + - 星 健夫 (鳥取大学 大学院工学研究科) + +- v0.1.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 星 健夫 (鳥取大学 大学院工学研究科) diff --git a/manual/v2.2.0/ja/_sources/output.rst.txt b/manual/v2.2.0/ja/_sources/output.rst.txt new file mode 100644 index 00000000..f5adc27e --- /dev/null +++ b/manual/v2.2.0/ja/_sources/output.rst.txt @@ -0,0 +1,53 @@ +出力ファイル +===================== + +各種 ``Solver``, ``Algorithm`` が出力するファイルについては、 :doc:`solver/index` および :doc:`algorithm/index` を参照してください。 + + +共通ファイル +~~~~~~~~~~~~~~~~~~ + +``time.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +MPI のランク毎に計算にかかった総時間を出力します。 +各ランクのサブフォルダ以下に出力されます。 +計算の前処理にかかった時間、計算にかかった時間、計算の後処理にかかった時間について、 +``prepare`` , ``run`` , ``post`` のセクションごとに記載されます。 + +以下、出力例です。 + +.. code-block:: + + #prepare + total = 0.007259890999989693 + #run + total = 1.3493346729999303 + - file_CM = 0.0009563499997966574 + - submit = 1.3224223930001244 + #post + total = 0.000595873999941432 + + +``runner.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +MPI のランクごとに、ソルバー呼び出しに関するログ情報を出力します。 +各ランクのサブフォルダ以下に出力されます。 +入力で ``runner.log.interval`` パラメータが正の整数の時のみ出力されます。 + +- 1列目がソルバー呼び出しの通し番号、 +- 2列目が前回呼び出しからの経過時間、 +- 3列目が計算開始からの経過時間 + +.. code-block:: + + # $1: num_calls + # $2: elapsed_time_from_last_call + # $3: elapsed_time_from_start + + 1 0.0010826379999999691 0.0010826379999999691 + 2 6.96760000000185e-05 0.0011523139999999876 + 3 9.67080000000009e-05 0.0012490219999999885 + 4 0.00011765699999999324 0.0013666789999999818 + 5 4.965899999997969e-05 0.0014163379999999615 + 6 8.666900000003919e-05 0.0015030070000000006 + ... diff --git a/manual/v2.2.0/ja/_sources/solver/analytical.rst.txt b/manual/v2.2.0/ja/_sources/solver/analytical.rst.txt new file mode 100644 index 00000000..42f7e400 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/solver/analytical.rst.txt @@ -0,0 +1,56 @@ +``analytical`` ソルバー +************************ + +``analytical`` は探索アルゴリズムの性能評価を目的とした、 +定義済みのベンチマーク関数 :math:`f(x)` を計算する ``Solver`` です。 + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~ + +``solver`` セクション以下の ``funtion_name`` パラメータで用いる関数を指定します。 + +- ``function_name`` + + 形式: string型 + + 説明: 関数名。以下の関数が選べます。 + + - ``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)` + + - ``himmerblau`` + + - `Himmerblau 関数 `_ + + .. 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/manual/v2.2.0/ja/_sources/solver/index.rst.txt b/manual/v2.2.0/ja/_sources/solver/index.rst.txt new file mode 100644 index 00000000..3f266246 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/solver/index.rst.txt @@ -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. + +順問題ソルバー +=============== + +順問題ソルバー ``Solver`` は探索パラメータ :math:`x` から最適化したい :math:`f(x)` を計算します。 + +.. toctree:: + :maxdepth: 1 + + analytical + sim-trhepd-rheed + sxrd + leed diff --git a/manual/v2.2.0/ja/_sources/solver/leed.rst.txt b/manual/v2.2.0/ja/_sources/solver/leed.rst.txt new file mode 100644 index 00000000..3f0e2f11 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/solver/leed.rst.txt @@ -0,0 +1,87 @@ +``leed`` ソルバー +*********************************************** + +``leed`` は M.A. Van Hove氏により作成された ``SATLEED`` を用いて、原子位置などからRocking curve を計算し、実験で得られた Rocking curve からの誤差を :math:`f(x)` として返す ``Solver`` です。 ``SATLEED`` に関する詳細については [SATLEED]_ をご覧ください。 + +.. [SATLEED] M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). https://doi.org/10.1016/0167-5729(93)90011-D + +前準備 +~~~~~~~~~~~~ +最初に ``SATLEED`` をインストールします。 +http://www.icts.hkbu.edu.hk/VanHove_files/leed/leedsatl.zip へアクセスし、zipファイルをダウンロードします。zipファイル展開後に、所定の手続きに従いコンパイルすることで、 ``stal1.exe``, ``satl2.exe`` などの実行ファイルができます。 +``SATLED`` は計算したい系の詳細によって、ソースコードのパラメータを適宜書き換える必要があります。 +``sample/py2dmat/leed`` にあるサンプルを実行する場合には、 ``SATLEED`` のダウンロードから、サンプル向けのソースコードの書き換え、コンパイルまでを自動で行うスクリプト ``setup.sh`` が用意されています。:: + + $ cd sample/py2dmat/leed + $ sh ./setup.sh + +``setup.sh`` を実行すると、 ``leedsatl`` ディレクトリに ``satl1.exe`` と ``satl2.exe`` が生成されます。 + +``py2dmat`` から ``SATLEED`` を利用するにあたっては、あらかじめ ``satl1.exe`` まで実行していることが前提となります。そのため、以下のファイルが生成されている必要があります。 + +- ``satl1.exe`` の入力ファイル: ``exp.d``, ``rfac.d``, ``tleed4.i``, ``tleed5.i`` + +- ``satl1.exe`` の出力ファイル: ``tleed.o`` , ``short.t`` + +``py2dmat`` はこれらをもちいて ``satl2.exe`` を実行します。 + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``solver`` セクション中のサブセクション +``config``, ``reference`` を利用します。 + +[``config``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``path_to_solver`` + + 形式: string型 + + 説明: ソルバー ``satl2.exe`` へのパス + + +[``reference``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``path_to_base_dir`` + + 形式: string型 + + 説明: - ``exp.d``, ``rfac.d``, ``tleed4.i``, ``tleed5.i`` , ``tleed.o`` , ``short.t`` が格納されたディレクトリへのパス。 + + +ソルバー用補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ターゲット参照ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ターゲットにするデータが格納されたファイル。 [``reference``] セクションの ``path_to_base_dir`` 中にある ``tleed4.i`` を編集します。最適化したい数値を ``optxxx`` (xxxは000, 001, 002, ...の形式で指定する三桁の整数)として指定します。なお、xxxの数字と ``py2dmat`` の最適化する値を入れる変数のリストの順番・個数は一致させる必要があります。なお、IFLAG, LSFLAGを0にしない場合はsatleed側での最適化も行われます。 + +以下、ファイル例を記載します。 + +.. code-block:: + + 1 0 0 IPR ISTART LRFLAG + 1 10 0.02 0.2 NSYM NSYMS ASTEP VSTEP + 5 1 2 2 NT0 NSET LSMAX LLCUT + 5 NINSET + 1.0000 0.0000 1 PQEX + 1.0000 2.0000 2 PQEX + 1.0000 1.0000 3 PQEX + 2.0000 2.0000 4 PQEX + 2.0000 0.0000 5 PQEX + 3 NDIM + opt000 0.0000 0.0000 0 DISP(1,j) j=1,3 + 0.0000 opt001 0.0000 0 DISP(2,j) j=1,3 + 0.0000 0.0000 0.0000 1 DISP(3,j) j=1,3 + 0.0000 0.0000 0.0000 0 DISP(4,j) j=1,3 + 0.0000 0 DVOPT LSFLAG + 3 0 0 MFLAG NGRID NIV + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``leed`` では、 計算時に出力されるファイルが、ランクの番号が記載されたフォルダ下に一式出力されます。 diff --git a/manual/v2.2.0/ja/_sources/solver/sim-trhepd-rheed.rst.txt b/manual/v2.2.0/ja/_sources/solver/sim-trhepd-rheed.rst.txt new file mode 100644 index 00000000..42ff8fb2 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/solver/sim-trhepd-rheed.rst.txt @@ -0,0 +1,329 @@ +``sim-trhepd-rheed`` ソルバー +*********************************************** + +.. _sim-trhepd-rheed: https://github.com/sim-trhepd-rheed/sim-trhepd-rheed + +``sim-trhepd-rheed`` は sim-trhepd-rheed_ を用いて原子位置 :math:`x` から回折 rocking curve を計算し、 +実験で得られた rocking curve からの誤差を :math:`f(x)` として返す ``Solver`` です。 + +前準備 +~~~~~~~~~~~~ + +あらかじめ sim-trhepd-rheed_ をインストールしておく必要があります。 + +1. sim-trhepd-rheed の公式サイトからソースコードをダウンロード +2. ``sim-trhepd-rheed/src`` に移動し、 ``make`` で ``bulk.exe`` と ``surf.exe`` を作成 + +``py2dmat`` を実行する前にあらかじめ ``bulk.exe`` を実行してバルクデータを作成しておきます。 +``surf.exe`` は ``py2dmat`` から呼び出されます。 + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``solver`` セクションとセクション中のサブセクション +``config``, ``post``, ``param``, ``reference`` を利用します。 + +[``solver``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- ``generate_rocking_curve`` + + 形式: 真偽値 (default: false) + + 説明: ``RockingCurve_calculated.txt`` の生成をするかどうか。 ``RockingCurve_calculated.txt`` は作業ディレクトリ ``Log%%%_###`` の中に保存されます。このオプションが"true"であっても、 ``remove_work_dir`` （[``post``] セクション）が"true"であれば ``Log%%%_###`` は削除されてしまうため、注意してください。 + + +[``config``] セクション（サブセクション） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``surface_exec_file`` + + 形式: string型 (default: "surf.exe") + + 説明: ``sim-trhepd-rheed`` の表面反射ソルバー ``surf.exe`` へのパス + +- ``surface_input_file`` + + 形式: string型 (default: "surf.txt") + + 説明: 表面構造のインプットファイル。 + +- ``bulk_output_file`` + + 形式: string型 (default: "bulkP.b") + + 説明: バルク構造のアウトプットファイル。 + +- ``surface_output_file`` + + 形式: string型 (default: "surf-bulkP.s") + + 説明: 表面構造のアウトプットファイル。 + +- ``calculated_first_line`` + + 形式: 整数型 (default: 5) + + 説明: ``surface_output_file`` ファイル中, D(x) として読み込む最初の行。 なお、最終行は実験データとして読み込んだ行数から自動計算されます。 + +- ``calculated_info_line`` + + 形式: 整数型 (default: 2) + + 説明: ``surface_output_file`` ファイル中, glancing angle数やbeam数が記してある行番号。 + +- ``cal_number`` + + 形式: 整数型のリスト (設定必須) + + 説明: ``surface_output_file`` ファイル中, データとして読み出す列番号。複数指定が可能。設定した値は、後述の ``exp_number`` （[``reference``] セクション）の値とリストの長さを一致させる必要があります。 + +[``post``] セクション（サブセクション） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +実験と計算の「ズレ」の大きさを示し、最小化すべき関数である「目的関数」の定義や、ロッキングカーブを描くためのコンボリューション半値幅などを指定するセクションです。 + +- ``Rfactor_type`` + + 形式: string型。"A"、"A2"または"B"のいずれかをとります。 (default: "A") + + 説明: 目的関数値の計算方法の指定。 + 視写角のインデックスを :math:`i = 1,2,\dots,m`, ビームのインデックスを :math:`j = 1,2,\dots,n` として、 + 実験・計算のデータをそれぞれ :math:`u^{(j)}_i` と :math:`v^{(j)}_i` で表し、 + 各ビームの重みを :math:`w^{(j)}` と書くとき + + - "A"タイプ: + + .. math:: + + R = \sqrt{ \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2} } + + - "A2"タイプ: + + .. math:: + + R^{2} = \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2} + + - "B"タイプ: + + .. math:: + + R = \frac{\sum_{i}^{m} \left(u^{(1)}_{i}-v^{(1)}_{i}\right)^{2}}{\sum_{i}^{m} \left(u^{(1)}_{i}\right)^{2} + \sum_{i}^{m} (v^{(1)}_{i})^2} + + - "B"タイプはデータ列が1つの実験・計算データを用いた実行( :math:`n=1` )のみ対応しています。 + + +- ``normalization`` + + 形式: string型。"TOTAL"または"MANY_BEAM"のいずれかをとります。 (設定必須) + + 説明: 実験・計算のデータベクトルの規格化の方法。 + + - "TOTAL" + + - 全体の和で規格化をします。 + - 計算に使用するデータ列が1つのみ適用できる規格化方法であり、 ``cal_number`` （[``config``] セクション）および ``exp_number`` （[``reference``] セクション）で設定したリストの長さが1である必要が有ります。 + + - "MANY_BEAM" + + - "MANY_BEAM"はデータ列が2つ以上であるときに利用できる規格化方法です。後述の ``weight_type`` によって規格化方法が変わります。 + + **なお、 normalization="MAX" は廃止となりました。** + +- ``weight_type`` + + 形式: string型または ``None`` 。"calc"または"manual"のいずれかを設定する必要があります。 (default: ``None`` 、 ``normalization = "MANY_BEAM"`` としたとき設定必須) + + 説明: 目的関数値を計算するときの、ビームごとの重み :math:`w^{(j)}` の計算方法を指定します。 + "calc"とした場合、データ列ごとの重み :math:`w^{(n)}` は次の式で与えられます。 + + .. math:: + + w^{(j)} = \left(\frac{\sum_{i=1}^m v^{(j)}_{i}}{\sum_{k=1}^n \sum_{i=1}^m v^{(j)}_i} \right)^2 + + "manual"とした場合、オプション ``spot_weight`` を用いることで、ユーザーが重みを指定可能です。 + +- ``spot_weight`` + + 形式: float型のリスト。 (default: [] 、 ``weight_type = "manual"`` としたとき設定必須) + + 説明: 目的関数値を計算するときの、データ列ごとの重みを設定します。総和が1になるように自動的に規格化されます。 + 例えば、[3,2,1]を指定すると、 :math:`w^{(1)}=1/2, w^{(2)}=1/3, w^{(3)}=1/6` となります。 + +- ``omega`` + + 形式: 実数型 (default: 0.5) + + 説明: コンボリューションの半値幅の指定。 + +- ``remove_work_dir`` + + 形式: 真偽値 (default: false) + + 説明: R-factor を読み取った後に作業ディレクトリ ``Log%%%_###`` を削除するかどうか。なお、 ``generate_rocking_curve`` ([``solver``] セクション) が"true"であっても、本オプションが"true"ならば ``Log%%%_###`` を削除します。 + + +[``param``] セクション（サブセクション） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``string_list`` + + 形式: string型のリスト。長さはdimensionの値と一致させます。 (default: ["value_01", "value_02"]) + + 説明: ソルバーの入力ファイルを作成するための参照用テンプレートファイルで利用するプレースホルダーのリスト。これらの文字列が探索中のパラメータの値に置換されます。 + +[``reference``] セクション（サブセクション） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``path`` + + 形式: string型 (default: ``experiment.txt``) + + 説明: 実験データファイルへのパス。 + +- ``reference_first_line`` + + 形式: 整数型 + + 説明: 実験データファイル中、実験データを読み出す最初の行の番号。省略時は1, すなわち先頭行から読み出します。 + +- ``reference_last_line`` + + 形式: 整数型 (default: 実験データファイルの最後の行の行数) + + 説明: 実験データファイル中、実験データを読み出す最後の行の番号。省略時は最終行まで読み出します。 + +- ``exp_number`` + + 形式: 整数型のリスト + + 説明: 実験データファイル中、実験データとして読み出す列番号。複数指定が可能。設定した値は、前述の ``cal_number`` （[``config``] セクション）の値とリストの長さを一致させる必要があります。 + +ソルバー用補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +入力テンプレートファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +入力テンプレートファイル ``template.txt`` は ``surf.exe`` の入力ファイルを作成するためのテンプレートです。 +動かすパラメータ（求めたい原子座標などの値）を「 ``value_*`` 」などの適当な文字列に置き換えます。 +使用する文字列は入力ファイルの ``[solver]`` - ``[param]`` セクションにある、 +``string_list`` で指定します。 +以下、テンプレートの例を記載します。 + +.. code-block:: + + 2 ,NELMS, -------- Ge(001)-c4x2 + 32,1.2,0.15 ,Ge Z,da1,sap + 0.6,0.6,0.6 ,BH(I),BK(I),BZ(I) + 32,1.2,0.15 ,Ge Z,da1,sap + 0.4,0.4,0.4 ,BH(I),BK(I),BZ(I) + 9,4,0,0,2,1.7,-0.5,0.5 ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS + 8 ,NATM + 1, 1.0, value_01, 1.00000, 5.231000 ,IELM(I),ocr(I),X(I),Y(I),Z(I + 1, 1.0, value_02, 1.00000, 4.371000 + 2, 1.0, 1.50000, 1.50000, 3.596000 + 2, 1.0, 2.00000, 1.49751, 2.100000 + 2, 1.0, 1.00000, 1.50000, 2.000000 + 2, 1.0, 0.00000, 1.00000, 0.849425 + 2, 1.0, 2.00000, 1.00000, 0.809425 + 2, 1.0, 1.00997, 1.00000, 0.599425 + 1,1 ,(WDOM,I=1,NDOM) + +この場合、 ``value_01``, ``value_02`` が動かすパラメータとなります。 + + +ターゲット参照ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ターゲットにするデータが格納されたファイル ``experiment.txt`` を指定します。 +第一列に角度、第二列以降に反射強度にコンボリューションを計算した値が入ってます。 +以下、ファイルの例を示します。 + +.. code-block:: + + 3.00000e-01 8.17149e-03 1.03057e-05 8.88164e-15 ... + 4.00000e-01 1.13871e-02 4.01611e-05 2.23952e-13 ... + 5.00000e-01 1.44044e-02 1.29668e-04 4.53633e-12 ... + 6.00000e-01 1.68659e-02 3.49471e-04 7.38656e-11 ... + 7.00000e-01 1.85375e-02 7.93037e-04 9.67719e-10 ... + 8.00000e-01 1.93113e-02 1.52987e-03 1.02117e-08 ... + 9.00000e-01 1.92590e-02 2.53448e-03 8.69136e-08 ... + 1.00000e+00 1.86780e-02 3.64176e-03 5.97661e-07 ... + 1.10000e+00 1.80255e-02 4.57932e-03 3.32760e-06 ... + 1.20000e+00 1.77339e-02 5.07634e-03 1.50410e-05 ... + 1.30000e+00 1.80264e-02 4.99008e-03 5.53791e-05 ... + ... + + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``sim-trhepd-rheed`` では、 ``surf.exe`` で出力されるファイルが、 +ランクの番号が記載されたフォルダ下にある ``Log%%%%%_#####`` フォルダに一式出力されます。 +``%%%%%`` はアルゴリズムの反復回数 ``step`` (例：モンテカルロステップ数)で、 +``#####`` はアルゴリズムにおけるグループの番号 ``set`` (例：モンテカルロにおけるレプリカ番号)です。 +大規模計算ではこれらのフォルダの数が多くなり、時には計算機のストレージの制限に引っかかることがあります。 +そのような場合には、 ``solver.post.remove_work_dir`` パラメータを ``true`` にして、計算が終了した作業フォルダを削除してください。 +以下では、 ``py2dmat`` で独自に出力するファイルについて説明します。 + +``stdout`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``surf.exe`` が出力する標準出力が記載されています。 + +以下、出力例です。 + +.. code-block:: + + bulk-filename (end=e) ? : + bulkP.b + structure-filename (end=e) ? : + surf.txt + output-filename : + surf-bulkP.s + +``RockingCurve_calculated.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``generate_rocking_curve`` ([``solver``] セクション) が"true"の場合のみ ``Log%%%%%_#####`` フォルダに出力されます。 + +ファイル冒頭、 ``#`` で始まる行はヘッダーです。 +ヘッダーには探索変数の値、目的関数値 ``f(x)`` オプションで指定した ``Rfactor_type``, ``normalization`, ``weight_type``, ``cal_number``, オプションで指定またはプログラムが計算したデータ列ごとの重み ``spot_weight``, データ部分のどの列に何が記されているか(例： ``# #0 glanceing_angle`` など)が記されています。 + +``#`` が付いていない部分はデータ表記部分になります。1列目は視写角、2列目以降はデータ列ごとに強度が記しています。どのデータ列が記されているかはヘッダーの表記で確認できます。例えば + +.. code-block:: + + # #0 glancing_angle + # #1 cal_number=1 + # #2 cal_number=2 + # #3 cal_number=4 + +との記載があれば、1列目は視写角、2列目は計算データファイルの1列目に相当する反射強度、3列目は計算データファイルの2列目に相当する反射強度、4列目は計算データファイルの4列目に相当する反射強度が記されていることがわかります。 + +また、各列の反射強度は各列の総和が1になるように規格化されています。目的関数値（R-factor及びR-factorの二乗）を算出する際は、データ列ごとの重み ``spot_weight`` を加味して計算されています。 + +以下、出力例です。 + +.. code-block:: + + #value_01 = 0.00000 value_02 = 0.00000 + #Rfactor_type = A + #normalization = MANY_BEAM + #weight_type = manual + #fx(x) = 0.03686180462340505 + #cal_number = [1, 2, 4, 6, 8] + #spot_weight = [0.933 0.026 0.036 0.003 0.002] + #NOTICE : Intensities are NOT multiplied by spot_weight. + #The intensity I_(spot) for each spot is normalized as in the following equation. + #sum( I_(spot) ) = 1 + # + # #0 glancing_angle + # #1 cal_number=1 + # #2 cal_number=2 + # #3 cal_number=4 + # #4 cal_number=6 + # #5 cal_number=8 + 0.30000 1.278160358686800e-02 1.378767858296659e-04 8.396046839668212e-14 1.342648818357391e-30 6.697979700048016e-53 + 0.40000 1.778953628930054e-02 5.281839702773564e-04 2.108814173486245e-12 2.467220122612354e-28 7.252675318478533e-50 + 0.50000 2.247181148723425e-02 1.671115124520428e-03 4.250758278908295e-11 3.632860054842994e-26 6.291667506376419e-47 + ... + diff --git a/manual/v2.2.0/ja/_sources/solver/sxrd.rst.txt b/manual/v2.2.0/ja/_sources/solver/sxrd.rst.txt new file mode 100644 index 00000000..dfc2b1a2 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/solver/sxrd.rst.txt @@ -0,0 +1,263 @@ +``sxrd`` ソルバー +*********************************************** + +``sxrd`` は ``sxrdcalc`` を用いて原子位置 :math:`x` や原子の占有率、デバイワラー因子を与えることで Rocking curve を計算し、実験で得られた Rocking curve からの誤差を :math:`f(x)` として返す ``Solver`` です。 + +前準備 +~~~~~~~~~~~~ + +``sxrdcalc`` は ``py2dmat`` から呼び出されます。 +そのため、あらかじめ ``sxrdcalc`` をインストールしておく必要があります。 +``sxrdcalc`` はGitHubの以下のURLで公開されています。 + +https://github.com/sxrdcalc/sxrdcalc + +サイトにアクセスの上、「Code」-「Download zip」よりソースコード一式をダウンロードします。 +zipファイル解凍後に、Makefileを自身の計算環境に合うように編集したあとに、 ``make`` コマンドを打つことで ``sxrdcalc`` の実行ファイルができます。 + +なお、 ``py2dmat`` を実行する前にあらかじめバルクデータを作成する必要があります(フォーマットについては、後述のソルバー用補助ファイルをご覧ください)。 + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``solver`` セクション中のサブセクション +``config``, ``post``, ``param``, ``reference`` を利用します。 + +[``config``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``sxrd_exec_file`` + + 形式: string型 + + 説明: ソルバー ``sxrdcalc`` へのパス + +- ``bulk_struc_in_file`` + + 形式: string型 + + 説明: バルク構造のインプットファイル。 + +以下、入力例を記載します。 + +.. code-block:: + + [config] + sxrd_exec_file = "../../sxrdcalc" + bulk_struc_in_file = "sic111-r3xr3.blk" + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``scale_factor`` + + 形式: float型 (default: 1.0) + + 説明: ターゲットのRocking Curveとシミュレーションで得られるRocking Curveのスケールの値。 + +- ``opt_scale_factor`` + + 形式: bool型 (default: false) + + 説明: ``scale_factor`` を最適化するかどうかのフラグ。 + +- ``type_vector`` + + 形式: list型 + + 説明: 最適化する変数の種類を正の数のlist形式で指定します。 + [``param.atom``]サブセクションで指定されるtypeの種類と、本リストが対応します。 + typeが同じ場合は、同じ変数として取り扱われます。 + + +[``param.domain``] サブセクション +----------------------------------- +本セクションではドメインを作成します。作成したいドメイン分、定義する必要があります。 +[``param.domain.atom``] サブサブセクションでドメイン内の情報を指定します。 + +- ``domain_occupancy`` + + 形式: float型 + + 説明: ドメイン全体の占有率。 + +[``param.domain.atom``] サブセクション +--------------------------------------------- +本セクションはドメインに所属する最適化したい原子の個数分定義を行う必要があります。 +なお、変数の種類を表すtypeは、正の数で入力します。 + +- ``name`` + + 形式: string型 (重複可) + + 説明: 最適化する原子の名前。 + +- ``pos_center`` + + 形式: list型 + + 説明: 原子の中心座標。[:math:`x_0, y_0, z_0`]の形式で記載します(:math:`x_0, y_0, z_0` はfloat)。 + +- ``DWfactor`` + + 形式: float型 + + 説明: デバイワラー因子(単位は :math:`\text{Å}^{2}` )。 + +- ``occupancy`` + + 形式: float型 (default: 1.0) + + 説明: 原子の占有率。 + +- ``displace_vector`` (省略可) + + 形式: listのlist型 + + 説明: 原子を動かす方向を定義するベクトル。最大3方向まで指定可能。 + 各リストで変位ベクトルと初期値を[type, :math:`D_{i1}, D_{i2}, D_{i3}` ]のようにして定義する(typeはint、:math:`D_{i1}, D_{i2}, D_{i3}` はfloat)。 + 与えられた情報に従い、 + :math:`dr_i = (D_{i1} \vec{a} + D_{i2} \vec{b} + D_{i3} \vec{c}) * l_{type}` + のように :math:`l_{type}` を変位させます( :math:`\vec{a}, \vec{b}, \vec{c}` は ``bulk_struc_in_file`` もしくは ``struc_in_file`` で指定された入力ファイルに記載された単位格子ベクトルを表します)。 + +- ``opt_DW`` (省略可) + + 形式: list型 + + 説明: デバイワラー因子を変化させる場合のスケールを設定します。 + [type, scale]のようにして定義されます。 + +- ``opt_occupancy`` + + 形式: int型 + + 説明: 定義した場合、占有率が変化する。指定された変数がtypeを表します。 + + +以下、入力例を記載します。 + +.. code-block:: + + [param] + scale_factor = 1.0 + type_vector = [1, 2] + + [[param.domain]] + domain_occupancy = 1.0 + [[param.domain.atom]] + name = "Si" + pos_center = [0.00000000, 0.00000000, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[1, 0.0, 0.0, 1.0]] + [[param.domain.atom]] + name = "Si" + pos_center = [0.33333333, 0.66666667, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[1, 0.0, 0.0, 1.0]] + [[param.domain.atom]] + name = "Si" + pos_center = [0.66666667, 0.33333333, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[1, 0.0, 0.0, 1.0]] + [[param.domain.atom]] + name = "Si" + pos_center = [0.33333333, 0.33333333, 1.00000000] + DWfactor = 0.0 + occupancy = 1.0 + displace_vector = [[2, 0.0, 0.0, 1.0]] + + +[``reference``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``f_in_file`` + + 形式: string型 + + 説明: ターゲットとするロッキングカーブのインプットファイルへのパス。 + + +ソルバー用補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ターゲット参照ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ターゲットにするデータが格納されたファイル。 [``reference``] セクションの ``f_in_file`` でパスを指定します。 +1行ごとに ``h k l F sigma`` が出力されます。ここで、 ``h, k, l`` は波数, ``F`` は強度、 ``sigma`` は ``F`` の不確かさをそれぞれ表します。 +以下、ファイル例を記載します。 + +.. code-block:: + + 0.000000 0.000000 0.050000 572.805262 0.1 + 0.000000 0.000000 0.150000 190.712559 0.1 + 0.000000 0.000000 0.250000 114.163340 0.1 + 0.000000 0.000000 0.350000 81.267319 0.1 + 0.000000 0.000000 0.450000 62.927325 0.1 + ... + +バルク構造ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +バルク構造のデータが格納されたファイル。 [``config``] セクションの ``bulk_struc_in_file`` でパスを指定します。 +1行目がコメント, 2行目が ``a b c alpha beta gamma`` を表します。 +ここで、 ``a`` , ``b``, ``c`` はユニットセルの格子定数、 ``alpha``, ``beta``, ``gamma`` はそれらのなす角です。 +3行目以降は ``atomsymbol r1 r2 r3 DWfactor occupancy`` を指定します。 +ここで、 ``atomsymbol`` は原子種、 ``r1``, ``r2``, ``r3`` は原子の位置座標、 ``DWfactor`` はデバイワラー因子、 ``occupancy`` は占有率をそれぞれ表します。 +以下、ファイル例を記載します。 + +.. code-block:: + + # SiC(111) bulk + 5.33940 5.33940 7.5510487 90.000000 90.000000 120.000000 + Si 0.00000000 0.00000000 0.00000000 0.0 1.0 + Si 0.33333333 0.66666667 0.00000000 0.0 1.0 + Si 0.66666667 0.33333333 0.00000000 0.0 1.0 + C 0.00000000 0.00000000 0.25000000 0.0 1.0 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``sxrd`` では、 計算時に出力されるファイルが、ランクの番号が記載されたフォルダ下に一式出力されます。 +ここでは、 ``py2dmat`` で独自に出力するファイルについて説明します。 + +``stdout`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``sxrd`` が出力する標準出力が記載されています。 +sxrdのLeast square fittingに対して、初期パラメータとして変数を与え、1ショット計算(iteration数=0)をした際のRfactorを計算します。 +RfactorはFit results以下のRに記載されます。 +以下、出力例です。 + +.. code-block:: + + --------------------------------------- + Program py2dmat/mapper_sxrd/sxrdcalc for surface x-ray diffraction calculations. + Version 3.3.3 - August 2019 + + + Inputfile: lsfit.in + Least-squares fit of model to experimental structure factors. + + ... + + Fit results: + Fit not converged after 0 iterations. + Consider increasing the maximum number of iterations or find better starting values. + chi^2 = 10493110.323318, chi^2 / (degree of freedom) = 223257.666454 (Intensities) + chi^2 = 3707027.897897, chi^2 / (degree of freedom) = 78872.933998 (Structure factors) + R = 0.378801 + + Scale factor: 1.00000000000000 +/- 0.000196 + Parameter Nr. 1: 3.500000 +/- 299467640982.406067 + Parameter Nr. 2: 3.500000 +/- 898402922947.218384 + + Covariance matrix: + 0 1 2 + 0 0.0000000383 20107160.3315223120 -60321480.9945669472 + 1 20107160.3315223120 89680867995567253356544.0000000000 -269042603986701827178496.0000000000 + 2 -60321480.9945669472 -269042603986701827178496.0000000000 807127811960105615753216.0000000000 + diff --git a/manual/v2.2.0/ja/_sources/start.rst.txt b/manual/v2.2.0/ja/_sources/start.rst.txt new file mode 100644 index 00000000..47650497 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/start.rst.txt @@ -0,0 +1,77 @@ +py2dmat のインストール +============================= + +実行環境・必要なパッケージ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- python 3.6.8 以上 + + - 必要なpythonパッケージ + + - tomli (>= 1.2) + - numpy (>= 1.14) + + - Optional なパッケージ + + - mpi4py (グリッド探索利用時) + - scipy (Nelder-Mead法利用時) + - physbo (ベイズ最適化利用時, ver. 0.3以上) + +ダウンロード・インストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +下記に示す方法で、 ``py2dmat`` python パッケージと ``py2dmat`` コマンドがインストールできます。 + +- PyPI からのインストール（推奨） + + - ``python3 -m pip install py2dmat`` + + - ``--user`` オプションをつけるとローカル (``$HOME/.local``) にインストールできます + + - ``py2dmat[all]`` とすると Optional なパッケージも同時にインストールします + +- ソースコードからのインストール + + 1. ``git clone https://github.com/issp-center-dev/2DMAT`` + 2. ``python3 -m pip install ./2DMAT`` + + - ``pip`` のバージョンは 19 以上が必要です (``python3 -m pip install -U pip`` で更新可能) + +- サンプルファイルのダウンロード + + - サンプルファイルはソースコードに同梱されています。 + - ``git clone https://github.com/issp-center-dev/2DMAT`` + +なお、 ``py2dmat`` で用いる順問題ソルバーのうち、 + +- TRHEPD順問題ソルバー (``sim-trhepd-rheed``) +- SXRD順問題ソルバー (``sxrdcalc``) +- LEED順問題ソルバー (``satleed``) + +については、別途インストールが必要です。 +インストールの詳細については各ソルバーのチュートリアルを参照してください。 + + +実行方法 +~~~~~~~~~~~~~ + +``py2dmat`` コマンドは定義済みの最適化アルゴリズム ``Algorithm`` と順問題ソルバー ``Solver`` の組み合わせで解析を行います。:: + + $ py2dmat input.toml + +定義済みの ``Algorithm`` については :doc:`algorithm/index` を、 +``Solver`` については :doc:`solver/index` を参照してください。 + +``Algorithm`` や ``Solver`` をユーザーが準備する場合は、 ``py2dmat`` パッケージを利用します。 +詳しくは :doc:`customize/index` を参照してください。 + +なお、 プログラムを改造する場合など、 ``py2dmat`` コマンドをインストールせずに直接実行することも可能です。 +``src/py2dmat_main.py`` を利用してください。:: + + $ py2dmat src/py2dmat_main.py input.toml + +アンインストール +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + $ python3 -m pip uninstall py2dmat diff --git a/manual/v2.2.0/ja/_sources/tool.rst.txt b/manual/v2.2.0/ja/_sources/tool.rst.txt new file mode 100644 index 00000000..139088b1 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tool.rst.txt @@ -0,0 +1,272 @@ +関連ツール +===================== + +``py2dmat_neighborlist`` +***************************** + +離散空間をモンテカルロ探索する場合に使用する近傍リスト定義ファイルを +メッシュ定義ファイルから生成するツールです。 + +``pip`` でインストールした場合は ``py2dmat`` と同様に ``bin`` 以下に ``py2dmat_neighborlist`` という名前でインストールされます。 +もしくは、ディレクトリ中の ``src/py2dmat_neighborlist.py`` を直接実行することも可能です。 + +使い方 +~~~~~~~~~~~~~~~~ + +引数としてメッシュ定義ファイルを渡します。 +生成される近傍リスト定義ファイルの名前は ``-o`` オプションで指定可能です。 + +.. code-block:: bash + + $ py2dmat_neighborlist -o neighborlist.txt MeshData.txt + + もしくは + + $ python3 src/py2dmat_neighborlist.py -o MeshData.txt + +次のようなオプションが利用できます。 + +- ``-o output`` or ``--output output`` + + - 出力ファイル名 (default: ``neighborlist.txt``) + +- ``-u "unit1 unit2..."`` or ``--unit "unit1 unit2"`` + + - 各次元の長さスケール (default: すべて 1.0) + + - 空間次元の数だけ値を空白区切りで並べ、全体を引用符でくくってください + + - 各座標はあらかじめこれらの長さスケールで除算されます + +- ``-r radius`` or ``--radius radius`` + + - 近傍とみなされるユークリッド距離 (default: 1.0) + - 距離は ``-u`` で除されたあとの座標に対して計算されます + +- ``-q`` or ``--quiet`` + + - 進捗バーを表示しません + - なお、進捗バーの表示には ``tqdm`` python パッケージが必要です + +- ``--allow-selfloop`` + + - 自分自身を隣接リストに含めます（自己ループ） + +- ``--check-allpairs`` + + - すべての点対に対して距離を計算します + - デバッグ用のオプションです + + +なお、 MPI を用いて計算を高速化できます。 + +``tool/to_dft/to_dft.py`` +****************************** + +本ツールでは、Si等四面体構造のボンドネットワークを有する系の(001)および(111)表面系モデルについて、その原子構造から第一原理電子状態計算ソフトウェア `Quantum Espresso (QE) `_ 用の入力データを作成します。これにより、得られた構造の妥当性検証や、電子状態等の微視的な情報を取得します。なお、注目する表面と反対の表面から生じるダングリングボンド由来の電子の影響を排除するため、最下層のダングリングボンドの位置に水素原子を置く水素終端というテクニックを用いています。 + + +必要な環境 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- Python3 >= 3.6 + +以下のパッケージが必要です。 + +- `Atomic Simulation Environment(ASE) `_ (>= 3.21.1) +- Numpy +- Scipy +- Matplotlib + +スクリプトの概要 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +XYZ形式で記載された構造ファイルのファイル名および、2次元的な周期構造を表すための格子ベクトルの情報などが記載された入力ファイルを読み込み、得られた座標データから、最下層と、その次の層にあたる原子の座標を抽出します。 +最下層の原子は取り除き、対応する位置に H 原子を置いて次層の原子との距離を四面体構造となる距離(例えば、Siの場合はシラン分子となる距離)に調整したモデルを作成します。 +水素終端を行ったモデルはXYZ形式で保存され、cifファイルとQuantum Espresso (QE)の入力ファイルも作成します。 +なお、QEをインストールしている場合には、そのまま計算実行することもできます。 + +チュートリアル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. 参照用のXYZファイルを作成します。 + +以下では、 ``tool/todft/sample/111`` フォルダにある ``surf_bulk_new111.xyz`` を用います。ファイルの中身は以下の通りです。 + +.. code-block:: + + 12 + surf.txt / bulk.txt + Si 1.219476 0.000000 4.264930 + Si 6.459844 0.000000 4.987850 + Si 1.800417 1.919830 3.404650 + Si 5.878903 1.919830 3.404650 + Si 3.839660 1.919830 2.155740 + Si 0.000000 1.919830 1.900440 + Si 3.839660 0.000000 0.743910 + Si 0.000000 0.000000 0.597210 + Si 1.919830 0.000000 -0.678750 + Si 5.759490 0.000000 -0.678750 + Si 1.919830 1.919830 -2.036250 + Si 5.759490 1.919830 -2.036250 + +2. 次に各種パラメータを設定するための入力ファイルを作成します。 + +入力ファイルのファイル形式は ``toml`` を採用しています。以下、 ``tool/todft/sample/111`` フォルダにある ``input.toml`` を用いて、その内容について説明します。ファイルの中身は以下の通りです。 + +.. code-block:: + + [Main] + input_xyz_file = "surf_bulk_new111.xyz" + output_file_head = "surf_bulk_new111_ext" + [Main.param] + z_margin = 0.001 + slab_margin = 10.0 + r_SiH = 1.48 #angstrom + theta = 109.5 #H-Si-H angle in degree + [Main.lattice] + unit_vec = [[7.67932, 0.00000, 0.00000], [0.00000, 3.83966, 0.00000]] + [ASE] + solver_name = "qe" + kpts = [3,3,1] # sampling k points (Monkhorst-Pack grid) + command = "mpirun -np 4 ./pw.x -in espresso.pwi > espresso.pwo" + [Solver] + [Solver.control] + calculation='bands' # 'scf','realx','bands',... + pseudo_dir='./' # Pseudopotential directory + [Solver.system] + ecutwfc = 20.0 # Cut-off energy in Ry + nbands=33 # # of bands (only used in band structure calc + [Solver.pseudo] + Si = 'Si.pbe-mt_fhi.UPF' + H = 'H.pbe-mt_fhi.UPF' + +入力ファイルは、 ``Main`` , ``ASE`` , ``Solver`` の3セクションから構成されます。 +以下、各セクション毎に変数の説明を簡単に記載します。 + +``Main`` セクション +------------------------ +このセクションでは、水素終端を行う際に必要なパラメータに関する設定を行います。 + +- ``input_xyz_file`` + + 形式: string型 + + 説明：入力するxyzファイルの名前 + +- ``output_file_head`` + + 形式: string型 + + 説明：出力ファイル(xyzファイルおよびcifファイル)につくヘッダ + +``Main.Param`` セクション +----------------------------- + +- ``z_margin`` + + 形式: float型 + + 説明: 最下層および下から2番目の原子を抽出する際に用いられるマージン。例えば、最下層にいる原子のz座標を ``z_min`` とした場合に、 ``z_min - z_margin <= z <= z_min + z_margin`` の中にいる原子が抽出されます。 + +- ``slab_margin`` + + 形式: float型 + + 説明: スラブの大きさに下駄をはかせるためのマージン。最下層および一番上の層にいる原子のz座標を ``z_min`` , ``z_max`` とした場合に、スラブの大きさは ``z_max-z_min+slab_margin`` で与えられます。 + +- ``r_SiH`` + + 形式： float型 + + 説明： 四面体構造の頂点(例えばSi)とH間の距離を与えます(単位は :math:`\mathrm{\mathring{A}}` )。 + +- ``theta`` + + 形式： float型 + + 説明： 四面体構造の頂点とH間の角度(例えばSi-H-Siの間の角)を与えます。 + +``Main.lattice`` セクション +----------------------------- + +- ``unit_vec`` + + 形式： list型 + + 説明： 2次元平面を形成するユニットベクトル を指定します (ex. ``unit_vec = [[7.67932, 0.00000, 0.00000], [0.00000, 3.83966, 0.00000]]``)。 + + +``ASE`` セクション +------------------------ +このセクションでは、 ``ASE`` に関連したパラメータを設定します。 + +- ``solver_name`` + + 形式： string型 + + 説明： ソルバーの名前を与えます。現状では ``qe`` のみ。 + +- ``kpts`` + + 形式： list型 + + 説明： サンプリングするkポイントを指定します(Monkhorst-Pack grid)。 + +- ``command`` + + 形式： string型 + + 説明： ソルバーを実行するときのコマンドを記載します。 + +``Solver`` セクション +------------------------ +このセクションでは、 ``Solver`` に関連したパラメータを設定します。 +ASEの機能を用いてそのまま第一原理計算を実行する場合に指定が必要となります。 +基本的には各ソルバーの入力ファイルで指定したものと同じ構成で記載します。 +例えば、QEの場合には ``Solver.control`` に、 +QEの ``control`` セクションで設定するパラメータを記載します。 + +3. 以下のコマンドを実行します。 + +.. code-block:: + + python3 to_dft.py input.toml + + +これを実行すると、 + +- ``surf_bulk_new111_ext.xyz`` +- ``surf_bulk_new111_ext.cif`` +- ``espresso.pwi`` + +が生成されます。QEおよび擬ポテンシャルへのパス設定が行われている場合には、第一原理計算がそのまま行われます。行われていない場合には、第一原理計算が実行されないため、 ``Calculation of get_potential_energy is not normally finished.`` というメッセージが最後にでますが、上記ファイルの出力は行われています。 + +以下、出力ファイルについて説明します。 + +- ``surf_bulk_new111_ext.xyz`` + +最下層原子のHへの置換と四面体構造を形成するためのHの追加が行われた結果が出力されます。 +実際の出力内容は以下の通りです。 + +.. code-block:: + + 14 + Lattice="7.67932 0.0 0.0 0.0 3.83966 0.0 0.0 0.0 17.0241" Properties=species:S:1:pos:R:3 pbc="T T T" + Si 1.219476 0.000000 4.264930 + Si 6.459844 0.000000 4.987850 + Si 1.800417 1.919830 3.404650 + Si 5.878903 1.919830 3.404650 + Si 3.839660 1.919830 2.155740 + Si 0.000000 1.919830 1.900440 + Si 3.839660 0.000000 0.743910 + Si 0.000000 0.000000 0.597210 + Si 1.919830 0.000000 -0.678750 + Si 5.759490 0.000000 -0.678750 + H 1.919830 -1.208630 -1.532925 + H 1.919830 1.208630 -1.532925 + H 5.759490 -1.208630 -1.532925 + H 5.759490 1.208630 -1.532925 + +このファイルは通常のXYZ形式の座標データとして適当な可視化ソフト等に読ませることができますが、通常コメントを書く場所に周期構造の格子ベクトルの情報が書き込まれています。出力されたファイルの3行目以降の「元素名+3次元座標」のデータをそのままQEの入力ファイルにコピーして使用する事もできます。 + +``espresso.pwi`` はQEのscf計算用の入力ファイルで、構造最適化やバンド計算は本ファイルを適宜修正することで行うことができます。 各種設定については `QEのオンラインマニュアル `_ を参考にしてください。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/bayes.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/bayes.rst.txt new file mode 100644 index 00000000..3df2625d --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/bayes.rst.txt @@ -0,0 +1,276 @@ +ベイズ最適化 +===================================== + +ここでは、ベイズ最適化を行い、回折データから原子座標を解析する方法について説明します。 +ベイズ最適化には `PHYSBO `_ を用いています。 +グリッド探索と同様に、探索グリッドを与えるデータ ``MeshData.txt`` を事前に準備する必要があります。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/sim-trhepd-rheed/single_beam/bayes`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``bulk.txt`` + + ``bulk.exe`` の入力ファイル + +- ``experiment.txt`` , ``template.txt`` + + メインプログラムでの計算を進めるための参照ファイル + +- ``ref_BayesData.txt`` + + 計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる ``ColorMap.txt`` の回答)。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``prepare.sh`` , ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。 + +参照ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +``template.txt`` , ``experiment.txt`` については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。 +ただし、計算を軽くするため ``value_03`` は用いずに ``3.5`` に固定し、 +2次元のグリッド探索を行うように変更してあります。 +実際に探索するグリッドは ``MeshData.txt`` で与えます。 +サンプルでは ``MeshData.txt`` の中身は以下のようになっています。 + +.. code-block:: + + 1 3.5 3.5 + 2 3.6 3.5 + 3 3.6 3.6 + 4 3.7 3.5 + 5 3.7 3.6 + 6 3.7 3.7 + 7 3.8 3.5 + 8 3.8 3.6 + 9 3.8 3.7 + 10 3.8 3.8 + ... + +1列目が通し番号、2列目以降は ``template.txt`` に入る ``value_0`` , ``value_1`` の値が順に指定されています。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +ここでは、メインプログラム用の入力ファイル ``input.toml`` について説明します。 +``input.toml`` の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある ``input.toml`` の中身になります。 + +.. code-block:: + + [base] + dimension = 2 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + [algorithm] + name = "bayes" + label_list = ["z1", "z2"] + + [algorithm.param] + mesh_path = "MeshData.txt" + + [algorithm.bayes] + random_max_num_probes = 10 + bayes_max_num_probes = 20 + + +最初に ``[base]`` セクションについて説明します。 + +- ``dimension`` は最適化したい変数の個数で、今の場合は ``template.txt`` で説明したように2つの変数の最適化を行うので、 ``2`` を指定します。 + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。 + +- ``name`` は使用したいソルバーの名前で、このチュートリアルでは、 ``sim-trhepd-rheed`` を用いた解析を行うので、 ``sim-trhepd-rheed`` を指定します。 + +ソルバーの設定は、サブセクションの ``[solver.config]``, ``[solver.param]``, ``[solver.reference]`` で行います。 + +``[solver.config]`` セクションではメインプログラム内部で呼び出す ``surf.exe`` により得られた出力ファイルを読み込む際のオプションを指定します。 + +- ``calculated_first_line`` は出力ファイルを読み込む最初の行数を指定します。 + +- ``calculated_last_line`` は出力ファイルを読み込む最後の行数を指定します。 + +- ``row_number`` は出力ファイルの何列目を読み込むかを指定します。 + +``[solver.param]`` セクションではメインプログラム内部で呼び出す ``surf.exe`` により得られた出力ファイルを読み込む際のオプションを指定します。 + +- ``string_list`` は、 ``template.txt`` で読み込む、動かしたい変数の名前のリストです。 + + +- ``label_list`` は、 ``value_0x`` (x=1,2) を出力する際につけるラベル名のリストです。 + +- ``degree_max`` は、最大角度（度単位）の指定をします。 + +``[solver.reference]`` セクションでは、実験データの置いてある場所と読みこむ範囲を指定します。 + +- ``path`` は実験データが置いてあるパスを指定します。 + +- ``first`` は実験データファイルを読み込む最初の行数を指定します。 + +- ``end`` は実験データファイルを読み込む最後の行数を指定します。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定をします。 + +- ``name`` は使用したいアルゴリズムの名前で、このチュートリアルでは、ベイズ最適化による解析を行うので、 ``bayes`` を指定します。 + +- ``label_list`` は、 ``value_0x`` (x=1,2) を出力する際につけるラベル名のリストです。 + +``[algorithm.param]`` セクションで、探索パラメータを設定します。 + +- ``mesh_path`` はメッシュファイルへのパスを設定します。 + +``[algorithm.bayes]`` セクションでは、ベイズ最適化のハイパーパラメータを設定します。 + +- ``random_max_num_probes`` は、ベイズ最適化を行う前のランダム探索する回数を指定します。 + +- ``bayes_max_num_probes`` は、ベイズ探索を行う回数を指定します。 + +その他、入力ファイルで指定可能なパラメータの詳細については入力ファイルの章をご覧ください。 + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します). + +.. code-block:: + + cd sample/sim-trhepd-rheed/bayes + +順問題の時と同様に、 ``bulk.exe`` と ``surf.exe`` をコピーします。 + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +最初に ``bulk.exe`` を実行し、 ``bulkP.b`` を作成します。 + +.. code-block:: + + ./bulk.exe + +そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。 + +.. code-block:: + + python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +実行すると、各ランクのフォルダが作成されます。 +以下の様な標準出力がされます。 + +.. code-block:: + + # parameter + random_max_num_probes = 10 + bayes_max_num_probes = 20 + score = TS + interval = 5 + num_rand_basis = 5000 + value_01 = 5.10000 + value_02 = 4.90000 + R-factor = 0.037237314010261195 + 0001-th step: f(x) = -0.037237 (action=150) + current best f(x) = -0.037237 (best action=150) + + value_01 = 4.30000 + value_02 = 3.50000 + + ... + +最初に設定したパラメータのリスト、そのあとに各ステップでの候補パラメータと、 +その時の ``R-factor`` にマイナスが乗算された ``f(x)``が出力されます。 +また、その時点での一番良いスコアを持つグリッドインデックス (``action``)とその場合の ``f(x)`` と変数が出力されます。 +0番の下には更にグリッドのidがついたサブフォルダ ``Log%%%%%`` ( ``%%%%%`` がグリッドのid)が作成され、ソルバーの出力が保存されます +(``MeshData.txt`` に付けられた番号がグリッドのidとして割り振られます)。 +最終的に推定されたパラメータは、``BayesData.txt`` に出力されます。 + +今回の場合は + +.. code-block:: + + #step z1 z2 fx z1_action z2_action fx_action + 0 5.1 4.9 0.037237314010261195 5.1 4.9 0.037237314010261195 + 1 5.1 4.9 0.037237314010261195 4.3 3.5 0.06050786306685965 + 2 5.1 4.9 0.037237314010261195 5.3 3.9 0.06215778000834068 + 3 5.1 4.9 0.037237314010261195 4.7 4.2 0.049210767760634364 + 4 5.1 4.9 0.037237314010261195 5.7 3.7 0.08394457854191653 + 5 5.1 4.9 0.037237314010261195 5.2 5.2 0.05556857782716691 + 6 5.1 4.9 0.037237314010261195 5.7 4.0 0.0754639895013157 + 7 5.1 4.9 0.037237314010261195 6.0 4.4 0.054757310814479355 + 8 5.1 4.9 0.037237314010261195 6.0 4.2 0.06339787375966344 + 9 5.1 4.9 0.037237314010261195 5.7 5.2 0.05348404677676544 + 10 5.1 4.7 0.03002813055356341 5.1 4.7 0.03002813055356341 + 11 5.1 4.7 0.03002813055356341 5.0 4.4 0.03019977423448576 + 12 5.3 4.5 0.02887504880071686 5.3 4.5 0.02887504880071686 + 13 5.1 4.5 0.025865346123665988 5.1 4.5 0.025865346123665988 + 14 5.2 4.4 0.02031077875240244 5.2 4.4 0.02031077875240244 + 15 5.2 4.4 0.02031077875240244 5.2 4.6 0.023291891689059388 + 16 5.2 4.4 0.02031077875240244 5.2 4.5 0.02345999725278686 + 17 5.2 4.4 0.02031077875240244 5.1 4.4 0.022561543431398066 + 18 5.2 4.4 0.02031077875240244 5.3 4.4 0.02544527153306051 + 19 5.2 4.4 0.02031077875240244 5.1 4.6 0.02778877135528466 + 20 5.2 4.3 0.012576357659158034 5.2 4.3 0.012576357659158034 + 21 5.1 4.2 0.010217361468113488 5.1 4.2 0.010217361468113488 + 22 5.1 4.2 0.010217361468113488 5.2 4.2 0.013178053637167673 + ... + +のように得られます。1列目にステップ数、2列目、3列目、4列目にその時点での最高スコアを与える +``value_01``, ``value_02`` と ``R-factor`` が記載されます。 +続けて、そのステップで候補となった ``value_01``, ``value_02`` と ``R-factor`` が記載されます。 +今回の場合は21ステップ目で正しい解が得られていることがわかります。 + +なお、一括計算するスクリプトとして ``do.sh`` を用意しています。 +``do.sh`` では ``BayesData.dat`` と ``ref_BayesData.dat`` の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。 + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time python3 ../../../../src/py2dmat_main.py input.toml + + echo diff BayesData.txt ref_BayesData.txt + res=0 + diff BayesData.txt ref_BayesData.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: BayesData.txt.txt and ref_BayesData.txt.txt differ + false + fi + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~ + +``BayesData.txt`` を参照することで、何ステップ目のパラメータが最小スコアを与えたかがわかります。 +``RockingCurve.txt`` は各ステップ毎にサブフォルダに格納されているので、 +``minsearch.rst`` の手順に従い、実験値との比較を行うことが可能です。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/exchange.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/exchange.rst.txt new file mode 100644 index 00000000..8222b00c --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/exchange.rst.txt @@ -0,0 +1,235 @@ +レプリカ交換モンテカルロ法による探索 +===================================== + +ここでは、レプリカ交換モンテカルロ法によって、回折データから原子座標を解析する方法について説明します。 +具体的な計算手順は ``minsearch`` の時と同様です。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/sim-threpd-rheed/single_beam/exchange`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``bulk.txt`` + + ``bulk.exe`` の入力ファイル + +- ``experiment.txt`` , ``template.txt`` + + メインプログラムでの計算を進めるための参照ファイル + +- ``ref.txt`` + + 計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる ``best_result.txt`` の回答)。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``prepare.sh`` , ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。 + +参照ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +``template.txt`` , ``experiment.txt`` については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +ここでは、メインプログラム用の入力ファイル ``input.toml`` について説明します。 +``input.toml`` の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある ``input.toml`` の中身になります。 + +.. code-block:: + + [base] + dimension = 2 + + [algorithm] + name = "exchange" + label_list = ["z1", "z2"] + seed = 12345 + + [algorithm.param] + min_list = [3.0, 3.0] + max_list = [6.0, 6.0] + + [algorithm.exchange] + numsteps = 1000 + numsteps_exchange = 20 + Tmin = 0.005 + Tmax = 0.05 + Tlogspace = true + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + +ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。 + +``[base]`` セクションはメインプログラム全体のパラメータです。 +``dimension`` は最適化したい変数の個数で、今の場合は2つの変数の最適化を行うので、``2`` を指定します。 + +``[algorithm]`` セクションは用いる探索アルゴリズムを設定します。 +交換モンテカルロ法を用いる場合には、 ``name`` に ``"exchange"`` を指定します。 +``label_list`` は、``value_0x`` (x=1,2) を出力する際につけるラベル名のリストです。 +``seed`` は擬似乱数生成器に与える種です。 + +``[algorithm.param]`` サブセクションは、最適化したいパラメータの範囲などを指定します。 +``min_list`` は最小値、 ``max_list`` は最大値を示します。 + +``[algorithm.exchange]`` サブセクションは、交換モンテカルロ法のハイパーパラメータを指定します。 + +- ``numstep`` はモンテカルロ更新の回数です。 +- ``numsteps_exchange`` で指定した回数のモンテカルロ更新の後に、温度交換を試みます。 +- ``Tmin``, ``Tmax`` はそれぞれ温度の下限・上限です。 +- ``Tlogspace`` が ``true`` の場合、温度を対数空間で等分割します + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーを指定します。 +``minsearch`` のチュートリアルを参照してください。 + + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/exchange + +順問題の時と同様に、 ``bulk.exe`` と ``surf.exe`` をコピーします。 + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +最初に ``bulk.exe`` を実行し、``bulkP.b`` を作成します。 + +.. code-block:: + + ./bulk.exe + +そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。 + +.. code-block:: + + mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +ここではプロセス数4のMPI並列を用いた計算を行っています。 +(Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 +``mpiexec`` コマンドに ``--oversubscribed`` オプションを追加してください。) +実行すると、各ランクのフォルダが作成され、 +各モンテカルロステップで評価したパラメータおよび目的関数の値を記した ``trial.txt`` ファイルと、 +実際に採択されたパラメータを記した ``result.txt`` ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。 + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + +また、 sim-trhepd-rheed ソルバーの場合は、 各作業フォルダの下にサブフォルダ ``Log%%%%%`` ( ``%%%%%`` がグリッドのid)が作成され、ロッキングカーブの情報などが記録されます +(各プロセスにおけるモンテカルロステップ数がidとして割り振られます)。 + +最後に、 ``best_result.txt`` に、目的関数 (R-factor) が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。 + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + x[0] = 4.221129370933539 + x[1] = 5.139591716517661 + +なお、一括計算するスクリプトとして ``do.sh`` を用意しています。 +``do.sh`` では ``best_result.txt`` と ``ref.txt`` の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。 + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml + + echo diff best_result.txt ref.txt + res=0 + diff best_result.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: best_result.txt and ref.txt differ + false + fi + +後処理 +~~~~~~~~ +各ランクフォルダにある ``result.txt`` には、各レプリカでサンプリングされたデータが記録されていますが、 +Py2DMat の実装では同一レプリカが様々な温度のサンプルを保持しています。 +2DMat は、全レプリカの結果から温度ごとのサンプルに整列し直す ``script/separateT.py`` スクリプトを提供しています。 + +.. code-block:: + + python3 ../../../../script/separateT.py + +``result_T%.txt`` に各温度点ごとにまとめなおされたデータが書き込まれます(``%`` は温度点のindex)。 +1列目がステップ、2列めがランク、3列目が目的関数の値、4列目以降がパラメータです。 + +.. code-block:: + + # T = 0.004999999999999999 + # step rank fx x1 x2 + 0 0 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.07830821484593968 3.682008067401509 3.9502750191292586 + + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~ + +``result_T%.txt`` を図示することで、 ``R-factor`` の小さいパラメータがどこにあるかを推定することができます。 +今回の場合は、以下のコマンドをうつことで2次元パラメータ空間の図 ``result.png`` が作成されます。 + +.. code-block:: + + python3 plot_result_2d.py + +作成された図を見ると、(5.25, 4.25) と (4.25, 5.25) 付近にサンプルが集中していることと、 +``R-factor`` の値が小さいことがわかります。 + + +.. figure:: ../../../common/img/exchange.* + + サンプルされたパラメータと ``R-factor`` 。横軸は ``value_01`` , 縦軸は ``value_02`` を表す。 + +また、 ``RockingCurve.txt`` が各サブフォルダに格納されています。 +``LogXXX_YYY`` の ``XXX`` はモンテカルロのステップ数、 ``YYY`` は各MPIプロセス内のレプリカの番号です。 +これを用いることで、前チュートリアルの手順に従い、実験値との比較も行うことが可能です。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/index.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/index.rst.txt new file mode 100644 index 00000000..8b3ebded --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/index.rst.txt @@ -0,0 +1,55 @@ +.. 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. + +チュートリアル +================================== + +順問題ソルバーとして用意されている ``sim_trhepd_rheed`` は東北大学の花田貴先生によって開発された +物質反射高速（陽）電子回折(RHEED, TRHEPD)の解析ソフトウェアをベースに作成されています。 +TRHEPDでは原子座標を与えた場合に、回折データがシミュレーション結果として与えられます。 +そのため、原子座標から回折データへの順問題を取り扱っているといえます。 +一方、多くの場合回折データは実験で与えられ、それを再現するような原子座標などが求められます。 +これらは上記の順問題に対して、逆問題に相当します。 + +本ソフトウェアでは逆問題を解くためのアルゴリズムとして + +- ``minsearch`` + + Nealder-Mead法を用いもっともらしい原子座標を推定 + +- ``mapper_mpi`` + + 与えられたパラメータの探索グリッドを全探索することで、もっともらしい原子座標を推定 + +- ``bayes`` + + ベイズ最適化を用いもっともらしい原子座標を推定 + +- ``exchange`` + + レプリカ交換モンテカルロ法を用いてもっともらしい原子座標をサンプリング + +- ``pamc`` + + ポピュレーションアニーリング法を用いてもっともらしい原子座標をサンプリング + +の5つのアルゴリズムが用意されています。 +本チュートリアルでは、最初に順問題プログラム ``sim_trhepd_rheed`` の実行方法、 +その後に ``minsearch`` , ``mapper_mpi``, ``bayes``, ``exchange``, ``pamc`` の実行方法について順に説明します。 +また、制約式を用いて探索範囲を制限出来る ``[runner.limitation]`` セクションを使用した実行方法も説明しています。 +最後に、自分で順問題ソルバーを定義する簡単な例について説明します。 + +.. toctree:: + :maxdepth: 1 + + sim_trhepd_rheed + minsearch + mpi + bayes + exchange + limitation + pamc + solver_simple + diff --git a/manual/v2.2.0/ja/_sources/tutorial/limitation.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/limitation.rst.txt new file mode 100644 index 00000000..8ad1a8f4 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/limitation.rst.txt @@ -0,0 +1,191 @@ +制約式を適用したレプリカ交換モンテカルロ法による探索 +========================================================================== + +ここでは、 ``[runner.limitation]`` セクションに設定できる制約式機能のチュートリアルを示します。 +例として、レプリカ交換モンテカルロ法を、Himmelblauを対象に探索する計算に制約式を適用します。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/analytical/limitation`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``ref.txt`` + + 計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる ``best_result.txt`` の回答)。 + +- ``input.toml`` + + メインプログラムの入力ファイル。 + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` について説明します。 +``input.toml`` の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある ``input.toml`` の中身になります。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "exchange" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + unit_list = [0.3, 0.3] + + [algorithm.exchange] + Tmin = 1.0 + Tmax = 100000.0 + numsteps = 10000 + numsteps_exchange = 100 + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.limitation] + co_a = [[1, -1],[1, 1]] + co_b = [[0], [-1]] + +ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。 + +``[base]`` セクションはメインプログラム全体のパラメータです。 +``dimension`` は最適化したい変数の個数で、今の場合は2つの変数の最適化を行うので、``2`` を指定します。 + +``[algorithm]`` セクションは用いる探索アルゴリズムを設定します。 +交換モンテカルロ法を用いる場合には、 ``name`` に ``"exchange"`` を指定します。 +``seed`` は擬似乱数生成器に与える種です。 + +``[algorithm.param]`` サブセクションは、最適化したいパラメータの範囲などを指定します。 +``min_list`` は最小値、 ``max_list`` は最大値を示します。 + +``[algorithm.exchange]`` サブセクションは、交換モンテカルロ法のハイパーパラメータを指定します。 + +- ``numstep`` はモンテカルロ更新の回数です。 +- ``numsteps_exchange`` で指定した回数のモンテカルロ更新の後に、温度交換を試みます。 +- ``Tmin``, ``Tmax`` はそれぞれ温度の下限・上限です。 +- ``Tlogspace`` が ``true`` の場合、温度を対数空間で等分割します。このオプションはデフォルト値が ``true`` であるため、今回の ``input.toml`` に指定は無いですが、 ``true`` になっています。 + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーを指定します。 +今回は ``analytical`` ソルバーを指定しています。 ``analytical`` ソルバーは ``function_name`` パラメータを用いて関数を設定します。 +今回はHimmelblau 関数を指定しています。 +``analytical`` ソルバーに関してはチュートリアル「順問題ソルバーの追加」を参照してください。 + +``[runner]`` セクションは ``[runner.limitation]`` サブセクションを持ち、この中に制約式を設定します。 +現在、制約式は :math:`N` 次元のパラメータ :math:`x` 、 :math:`M` 行 :math:`N` 列の行列 :math:`A` 、 +:math:`M` 次元の縦ベクトル :math:`b` から定義される :math:`Ax+b>0` の制約式が利用可能です。 +パラメータとしては、以下の項目が設定可能です。 + +- ``co_a`` は行列 :math:`A` を設定します。 +- ``co_b`` は縦ベクトル :math:`b` を設定します。 + +パラメータの詳しい設定方法はマニュアル内「入力ファイル」項の「 [``limitation``] セクション」を参照してください。 +今回は + +.. math:: + + x_{1} − x_{2} > 0\\ + x_{1} + x_{2} − 1 > 0 + +の制約式を課して実行しています。 + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します). + +.. code-block:: + + cd sample/analytical/limitation + +そのあとに、メインプログラムを実行します(計算時間は通常のPCで20秒程度で終わります)。 + +.. code-block:: + + mpiexec -np 10 python3 ../../../src/py2dmat_main.py input.toml | tee log.txt + +ここではプロセス数10のMPI並列を用いた計算を行っています。 +(Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 +``mpiexec`` コマンドに ``--oversubscribed`` オプションを追加してください。) +実行すると、 ``output`` フォルダが生成され、その中に各ランクのフォルダが作成されます。 +更にその中には、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した ``trial.txt`` ファイルと、 +実際に採択されたパラメータを記した ``result.txt`` ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。 +以下は、 ``output/0/result.txt`` ファイルの冒頭部分です。 + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569 + 1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + +最後に、 ``output/best_result.txt`` に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。 + +.. code-block:: + + nprocs = 10 + rank = 2 + step = 4523 + walker = 0 + fx = 0.00010188398524402734 + x1 = 3.584944906595298 + x2 = -1.8506985826548874 + +なお、一括計算するスクリプトとして ``do.sh`` を用意しています。 +``do.sh`` では ``best_result.txt`` と ``ref.txt`` の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。 + +.. code-block:: + + #!/bin/bash + mpiexec -np 10 --oversubscribe python3 ../../../src/py2dmat_main.py input.toml + + echo diff output/best_result.txt ref.txt + res=0 + diff output/best_result.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: best_result.txt and ref.txt differ + false + fi + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~ + +``result.txt`` を図示して、制約式を満たした座標のみを探索しているかを確認します。 +今回の場合は、以下のコマンドを打つことで2次元パラメータ空間の図が ``<実行日>_histogram`` フォルダ内に作成されます。 +生成されるヒストグラムは、burn-in期間として最初の1000ステップ分の探索を捨てたデータを使用しています。 + +.. code-block:: + + python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1 + +作成された図には2本の直線 :math:`x_{1} − x_{2} = 0, x_{1} + x_{2} − 1 = 0` と +探索結果(事後確率分布のヒストグラム)を図示しています。 +図を見ると :math:`x_{1} − x_{2} > 0, x_{1} + x_{2} − 1 > 0` の範囲のみ探索をしていることが確認できます。 +以下に図の一部を掲載します。 + +.. figure:: ../../../common/img/limitation_beta_min.* + +.. figure:: ../../../common/img/limitation_beta_max.* + + サンプルされたパラメータと確率分布。横軸は ``value_01 (x1)`` , 縦軸は ``value_02 (x2)`` を表す。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/minsearch.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/minsearch.rst.txt new file mode 100644 index 00000000..192ab9bb --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/minsearch.rst.txt @@ -0,0 +1,290 @@ +Nelder-Mead法による最適化 +==================================== + +ここでは、Nelder-Mead法を用いて回折データから原子座標を解析する逆問題の計算を行う方法について説明します。 +具体的な計算手順は以下の通りです。 + +0. 参照ファイルの準備 + + 合わせたい参照ファイル (今回は後述する ``experiment.txt`` に相当)を準備する。 + +1. 表面構造のバルク部分に関する計算実行 + + ``bulk.exe`` を ``sample/sim-trhepd-rheed/minsearch`` にコピーして計算を実行する。 + +2. メインプログラムの実行 + + ``src/py2dmat_main.py`` を用いて計算実行し原子座標を推定する。 + +メインプログラムでは、 +Nelder-Mead法 (`scipy.optimize.fmin `_ を使用)を用いて、 +ソルバー(今回は ``surf.exe`` )を用いて得られた強度と、 +参照ファイル(``experiment.txt``)に記載された強度のずれ(R値)を最小化するパラメータを探索します。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/py2dmat/sim-threpd-rheed/single_beam/minsearch`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``bulk.txt`` + + ``bulk.exe`` の入力ファイル + +- ``experiment.txt`` , ``template.txt`` + + メインプログラムでの計算を進めるための参照ファイル + +- ``ref.txt`` + + 本チュートリアルで求めたい回答が記載されたファイル + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``prepare.sh`` , ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。 + +参照ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +``template.txt`` は ``surf.exe`` の入力ファイルとほぼ同じ形式のファイルです。 +動かすパラメータ（求めたい原子座標などの値）を「 ``value_*`` 」などの適当な文字列に書き換えられています。 +以下が、 ``template.txt`` の中身です。 + +.. code-block:: + + 2 ,NELMS, -------- Ge(001)-c4x2 + 32,1.0,0.1 ,Ge Z,da1,sap + 0.6,0.6,0.6 ,BH(I),BK(I),BZ(I) + 32,1.0,0.1 ,Ge Z,da1,sap + 0.4,0.4,0.4 ,BH(I),BK(I),BZ(I) + 9,4,0,0,2, 2.0,-0.5,0.5 ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS + 8 ,NATM + 1, 1.0, 1.34502591 1 value_01 ,IELM(I),ocr(I),X(I),Y(I),Z(I) + 1, 1.0, 0.752457792 1 value_02 + 2, 1.0, 1.480003343 1.465005851 value_03 + 2, 1.0, 2 1.497500418 2.281675 + 2, 1.0, 1 1.5 1.991675 + 2, 1.0, 0 1 0.847225 + 2, 1.0, 2 1 0.807225 + 2, 1.0, 1.009998328 1 0.597225 + 1,1 ,(WDOM,I=1,NDOM) + + +今回の入力ファイルでは、 ``value_01``, ``value_02``, ``value_03`` を用いています。 +サンプルフォルダには、原子位置が正しく推定できているかを知るための参照ファイルとして、 +``ref.txt`` が置いてあります。ファイルの中身は + +.. code-block:: + + fx = 7.382680568652868e-06 + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 + +となっており、 ``value_0x`` が ``z_x`` (x=1, 2, 3)に対応しています。 +``fx`` は目的関数の最適値です。 +``experiment.txt`` は、メインプログラムで参照に用いるファイルで、 +``template.txt`` に ``ref.txt`` の入っているパラメータをいれ、 +順問題のチュートリアルと同様な手順で計算して得られる ``convolution.txt`` に相当しています +(順問題のチュートリアルとは ``bulk.exe`` , ``suft.exe`` の入力ファイルが異なるのでご注意ください)。 + + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +ここでは、メインプログラム用の入力ファイル ``input.toml`` の準備をします。 +``input.toml`` の詳細については入力ファイルに記載されています。 +ここでは、サンプルファイルにある ``input.toml`` の中身について説明します。 + +.. code-block:: + + [base] + dimension = 3 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02", "value_03" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + [algorithm] + name = "minsearch" + label_list = ["z1", "z2", "z3"] + + [algorithm.param] + min_list = [0.0, 0.0, 0.0] + max_list = [10.0, 10.0, 10.0] + initial_list = [5.25, 4.25, 3.50] + + +最初に ``[base]`` セクションについて説明します。 + +- ``dimension`` は最適化したい変数の個数で、今の場合は ``template.txt`` で説明したように3つの変数の最適化を行うので、``3`` を指定します。 + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。 + +- ``name`` は使用したいソルバーの名前で、このチュートリアルでは、 ``sim-trhepd-rheed`` を用いた解析を行うので、 ``sim-trhepd-rheed`` を指定します。 + +ソルバーの設定は、サブセクションの ``[solver.config]``, ``[solver.param]``, ``[solver.reference]`` で行います。 + +``[solver.config]`` セクションではメインプログラム内部で呼び出す ``surf.exe`` により得られた出力ファイルを読み込む際のオプションを指定します。 + +- ``calculated_first_line`` は出力ファイルを読み込む最初の行数を指定します。 + +- ``calculated_last_line`` は出力ファイルを読み込む最後の行数を指定します。 + +- ``row_number`` は出力ファイルの何列目を読み込むかを指定します。 + +``[solver.param]`` セクションではメインプログラム内部で呼び出す ``surf.exe`` により得られた出力ファイルを読み込む際のオプションを指定します。 + +- ``string_list`` は、 ``template.txt`` で読み込む、動かしたい変数の名前のリストです。 + +- ``degree_max`` は、最大角度（度単位）の指定をします。 + +``[solver.reference]`` セクションでは、実験データの置いてある場所と読みこむ範囲を指定します。 + +- ``path`` は実験データが置いてあるパスを指定します。 + +- ``first`` は実験データファイルを読み込む最初の行数を指定します。 + +- ``end`` は実験データファイルを読み込む最後の行数を指定します。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定をします。 + +- ``name`` は使用したいアルゴリズムの名前で、このチュートリアルでは、Nelder-Mead法 を用いた解析を行うので、 ``minsearch`` を指定します。 + +- ``label_list`` は、``value_0x`` (x=1,2,3) を出力する際につけるラベル名のリストです。 + +``[algorithm.param]`` セクションでは、探索するパラメータの範囲や初期値を指定します。 + +- ``min_list`` と ``max_list`` はそれぞれ探索範囲の最小値と最大値を指定します。 +- ``initial_list`` は初期値を指定します。 + +ここではデフォルト値を用いるため省略しましたが、その他のパラメータ、例えばNelder-Mead法で使用する収束判定などについては、``[algorithm]`` セクションで行うことが可能です。 +詳細については入力ファイルの章をご覧ください。 + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/minsearch + +順問題の時と同様に、``bulk.exe`` と ``surf.exe`` をコピーします。 + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +最初に ``bulk.exe`` を実行し、``bulkP.b`` を作成します。 + +.. code-block:: + + ./bulk.exe + +そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。 + +.. code-block:: + + python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +実行すると、以下の様な出力がされます。 + +.. code-block:: + + Read experiment.txt + z1 = 5.25000 + z2 = 4.25000 + z3 = 3.50000 + [' 5.25000', ' 4.25000', ' 3.50000'] + PASS : degree in lastline = 7.0 + PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70 + R-factor = 0.015199251773721183 + z1 = 5.50000 + z2 = 4.25000 + z3 = 3.50000 + [' 5.50000', ' 4.25000', ' 3.50000'] + PASS : degree in lastline = 7.0 + PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70 + R-factor = 0.04380131351780189 + z1 = 5.25000 + z2 = 4.50000 + z3 = 3.50000 + [' 5.25000', ' 4.50000', ' 3.50000'] + ... + +``z1``, ``z2``, ``z3`` に各ステップでの候補パラメータと、その時の``R-factor`` が出力されます。 +また各ステップでの計算結果は ``Logxxxxx`` (xxxxxにステップ数)のフォルダに出力されます。 +最終的に推定されたパラメータは、``res.dat`` に出力されます。今の場合、 + +.. code-block:: + + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 + +が得られ、正解のデータ ``ref.txt`` と同じ値が得られていることがわかります。 +なお、一括計算するスクリプトとして ``do.sh`` を用意しています。 +``do.sh`` では ``res.txt`` と ``ref.txt`` の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。 + +.. code-block:: + + sh ./prepare.sh + + ./bulk.exe + + time python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + + echo diff res.txt ref.txt + res=0 + diff res.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo Test PASS + true + else + echo Test FAILED: res.txt and ref.txt differ + false + fi + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~ + +それぞれのステップでのロッキングカーブのデータは、 ``LogXXX_00000001`` (``XXX`` はステップ数)フォルダに ``RockingCurve.txt`` として保存されています (``LogXXX_00000000`` フォルダはNelder-Mead 法の途中での評価です)。 +このデータを可視化するツール ``draw_RC_double.py`` が準備されています。 +ここでは、このツールを利用して結果を可視化します。 + +.. code-block:: + + cp 0/Log00000001_00000001/RockingCurve.txt RockingCurve_ini.txt + cp 0/Log00000062_00000001/RockingCurve.txt RockingCurve_con.txt + cp ../../../../script/draw_RC_double.py . + python draw_RC_double.py + +上記を実行することで、``RC_double.png`` が出力されます。 + +.. figure:: ../../../common/img/RC_double_minsearch.* + + Nelder-Mead法を用いた解析。赤丸が実験値、青線が最初のステップ、緑線が最後のステップで得られたロッキングカーブを表す。 + +図から最後のステップでは実験値と一致していることがわかります。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/mpi.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/mpi.rst.txt new file mode 100644 index 00000000..500c2bd2 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/mpi.rst.txt @@ -0,0 +1,243 @@ +グリッド型探索 +===================================== + +ここでは、グリッド型探索を行い、回折データから原子座標を解析する方法について説明します。 +グリッド型探索はMPIに対応しています。具体的な計算手順は ``minsearch`` の時と同様です。 +ただし、探索グリッドを与えるデータ ``MeshData.txt`` を事前に準備する必要があります。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/sim-trhepd-rheed/single_beam/mapper`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``bulk.txt`` + + ``bulk.exe`` の入力ファイル + +- ``experiment.txt`` , ``template.txt`` + + メインプログラムでの計算を進めるための参照ファイル + +- ``ref_ColorMap.txt`` + + 計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる ``ColorMap.txt`` の回答)。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``prepare.sh`` , ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。 + +参照ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +``template.txt`` , ``experiment.txt`` については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。 +ただし、計算を軽くするため ``value_03`` は用いずに ``3.5`` に固定し、 +2次元のグリッド探索を行うように変更してあります。 +実際に探索するグリッドは ``MeshData.txt`` で与えます。 +サンプルでは ``MeshData.txt`` の中身は以下のようになっています。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +1列目が通し番号、2列目以降は ``template.txt`` に入る``value_0`` , ``value_1`` の値が順に指定されています。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +ここでは、メインプログラム用の入力ファイル ``input.toml`` について説明します。 +``input.toml`` の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある ``input.toml`` の中身になります。 + +.. code-block:: + + [base] + dimension = 2 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + [algorithm] + name = "mapper" + label_list = ["z1", "z2"] + +最初に ``[base]`` セクションについて説明します。 + +- ``dimension`` は最適化したい変数の個数で、今の場合は ``template.txt`` で説明したように2つの変数の最適化を行うので、``2`` を指定します。 + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。 + +- ``name`` は使用したいソルバーの名前で、このチュートリアルでは、 ``sim-trhepd-rheed`` を用いた解析を行うので、 ``sim-trhepd-rheed`` を指定します。 + +ソルバーの設定は、サブセクションの ``[solver.config]``, ``[solver.param]``, ``[solver.reference]`` で行います。 + +``[solver.config]`` セクションではメインプログラム内部で呼び出す ``surf.exe`` により得られた出力ファイルを読み込む際のオプションを指定します。 + +- ``calculated_first_line`` は出力ファイルを読み込む最初の行数を指定します。 + +- ``calculated_last_line`` は出力ファイルを読み込む最後の行数を指定します。 + +- ``row_number`` は出力ファイルの何列目を読み込むかを指定します。 + +``[solver.param]`` セクションではメインプログラム内部で呼び出す ``surf.exe`` により得られた出力ファイルを読み込む際のオプションを指定します。 + +- ``string_list`` は、 ``template.txt`` で読み込む、動かしたい変数の名前のリストです。 + + +- ``label_list`` は、``value_0x`` (x=1,2) を出力する際につけるラベル名のリストです。 + +- ``degree_max`` は、最大角度（度単位）の指定をします。 + +``[solver.reference]`` セクションでは、実験データの置いてある場所と読みこむ範囲を指定します。 + +- ``path`` は実験データが置いてあるパスを指定します。 + +- ``first`` は実験データファイルを読み込む最初の行数を指定します。 + +- ``end`` は実験データファイルを読み込む最後の行数を指定します。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定をします。 + +- ``name`` は使用したいアルゴリズムの名前で、このチュートリアルでは、グリッド探索による解析を行うので、 ``mapper`` を指定します。 + +- ``label_list`` は、``value_0x`` (x=1,2) を出力する際につけるラベル名のリストです。 + +その他、入力ファイルで指定可能なパラメータの詳細については入力ファイルの章をご覧ください。 + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します). + +.. code-block:: + + cd sample/sim-trhepd-rheed/single_beam/mapper + +順問題の時と同様に、``bulk.exe`` と ``surf.exe`` をコピーします。 + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +最初に ``bulk.exe`` を実行し、``bulkP.b`` を作成します。 + +.. code-block:: + + ./bulk.exe + +そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。 + +.. code-block:: + + mpiexec -np 2 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +ここではプロセス数2のMPI並列を用いた計算を行っています。 +実行すると、各ランクのフォルダが作成され、その下に更にグリッドのidがついたサブフォルダ ``Log%%%%%`` ( ``%%%%%`` がグリッドのid)が作成されます +(``MeshData.txt`` に付けられた番号がグリッドのidとして割り振られます)。 +以下の様な標準出力がされます。 + +.. code-block:: + + Iteration : 1/33 + Read experiment.txt + mesh before: [1.0, 6.0, 6.0] + z1 = 6.00000 + z2 = 6.00000 + [' 6.00000', ' 6.00000'] + PASS : degree in lastline = 7.0 + PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70 + R-factor = 0.04785241875354398 + ... + +``z1``, ``z2`` に各メッシュでの候補パラメータと、その時の``R-factor`` が出力されます。 +最終的にグリッド上の全ての点で計算された ``R-factor`` は、``ColorMap.txt`` に出力されます。 +今回の場合は + +.. code-block:: + + 6.000000 6.000000 0.047852 + 6.000000 5.750000 0.055011 + 6.000000 5.500000 0.053190 + 6.000000 5.250000 0.038905 + 6.000000 5.000000 0.047674 + 6.000000 4.750000 0.065919 + 6.000000 4.500000 0.053675 + 6.000000 4.250000 0.061261 + 6.000000 4.000000 0.069351 + 6.000000 3.750000 0.071868 + 6.000000 3.500000 0.072739 + ... + +のように得られます。1列目、2列目に ``value_01``, ``value_02`` の値が、3列目に ``R-factor`` が記載されます。 +なお、一括計算するスクリプトとして ``do.sh`` を用意しています。 +``do.sh`` では ``ColorMap.dat`` と ``ref_ColorMap.dat`` の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。 + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time mpiexec -np 2 python3 ../../../../src/py2dmat_main.py input.toml + + echo diff ColorMap.txt ref_ColorMap.txt + res=0 + diff ColorMap.txt ref_ColorMap.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: ColorMap.txt and ref_ColorMap.txt differ + false + fi + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~ + +``ColorMap.txt`` を図示することで、``R-factor`` の小さいパラメータがどこにあるかを推定することができます。 +今回の場合は、以下のコマンドをうつことで2次元パラメータ空間の図 ``ColorMapFig.png`` が作成されます。 + +.. code-block:: + + python3 plot_colormap_2d.py + +作成された図を見ると、(5.25, 4.25) 付近に最小値を持っていることがわかります。 + +.. figure:: ../../../common/img/mapper.* + + 2次元パラメータ空間上での ``R-factor`` 。 + +また、 ``RockingCurve.txt`` が各サブフォルダに格納されています。 +これを用いることで、前チュートリアルの手順に従い、実験値との比較も行うことが可能です。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/pamc.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/pamc.rst.txt new file mode 100644 index 00000000..83d0a3af --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/pamc.rst.txt @@ -0,0 +1,244 @@ +ポピュレーションアニーリングによる探索 +======================================== + +ここでは、ポピュレーションアニーリングを用いて、回折データから原子座標を解析する方法について説明します。 +具体的な計算手順は ``minsearch`` の時と同様です。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/sim-trhepd-rheed/single_beam/pamc`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``bulk.txt`` + + ``bulk.exe`` の入力ファイル + +- ``experiment.txt`` , ``template.txt`` + + メインプログラムでの計算を進めるための参照ファイル + +- ``ref.txt`` + + 計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる ``fx.txt`` の回答)。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``prepare.sh`` , ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。 + +参照ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +``template.txt`` , ``experiment.txt`` については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~ + +ここでは、メインプログラム用の入力ファイル ``input.toml`` について説明します。 +``input.toml`` の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある ``input.toml`` の中身になります。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "pamc" + label_list = ["z1", "z2"] + seed = 12345 + + [algorithm.param] + min_list = [3.0, 3.0] + max_list = [6.0, 6.0] + unit_list = [0.3, 0.3] + + [algorithm.pamc] + numsteps_annealing = 5 + bmin = 0.0 + bmax = 200.0 + Tnum = 21 + Tlogspace = false + nreplica_per_proc = 10 + + [solver] + name = "sim-trhepd-rheed" + + [solver.config] + calculated_first_line = 5 + calculated_last_line = 74 + row_number = 2 + + [solver.param] + string_list = ["value_01", "value_02" ] + degree_max = 7.0 + + [solver.reference] + path = "experiment.txt" + first = 1 + last = 70 + + +ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。 + +``[base]`` セクションはメインプログラム全体のパラメータです。 +``dimension`` は最適化したい変数の個数で、今の場合は2つの変数の最適化を行うので、``2`` を指定します。 + +``[algorithm]`` セクションは用いる探索アルゴリズムを設定します。 +交換モンテカルロ法を用いる場合には、 ``name`` に ``"exchange"`` を指定します。 +``label_list`` は、``value_0x`` (x=1,2) を出力する際につけるラベル名のリストです。 +``seed`` は擬似乱数生成器に与える種です。 + +``[algorithm.param]`` サブセクションは、最適化したいパラメータの範囲などを指定します。 +``min_list`` は最小値、 ``max_list`` は最大値を示します。 +``unit_list`` はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。 + +``[algorithm.pamc]`` サブセクションは、ポピュレーションアニーリングのハイパーパラメータを指定します。 + +- ``numsteps_annealing`` で指定した回数のモンテカルロ更新の後に、逆温度を増やします (温度を下げます)。 +- ``bmin``, ``bmax`` はそれぞれ逆温度の下限・上限です。 +- ``Tnum`` は計算する温度・逆温度の点数です。 +- ``Tlogspace`` が ``true`` の場合、温度を対数空間で等分割します +- ``nreplica_per_proc`` はMPIプロセスひとつが受け持つ計算レプリカの数です。 + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーを指定します。 +``minsearch`` のチュートリアルを参照してください。 + + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します). + +.. code-block:: + + cd sample/sim-trhepd-rheed/pamc + +順問題の時と同様に、 ``bulk.exe`` と ``surf.exe`` をコピーします。 + +.. code-block:: + + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe . + cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe . + +最初に ``bulk.exe`` を実行し、``bulkP.b`` を作成します。 + +.. code-block:: + + ./bulk.exe + +そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。 + +.. code-block:: + + mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt + +ここではプロセス数4のMPI並列を用いた計算を行っています。 +(Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 +``mpiexec`` コマンドに ``--oversubscribed`` オプションを追加してください。) +実行すると、各ランクのフォルダが作成され、 +温度ごとに、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した ``trial_TXXX.txt`` ファイル(``XXX`` は温度点の番号)と、 +実際に採択されたパラメータを記した ``result_TXXX.txt`` ファイル、さらにそれぞれを結合した ``trial.txt``, ``result.txt`` ファイルが生成されます。 +それぞれ書式は同じで、最初の2列がステップ数とプロセス内のwalker (replica) 番号、次が（逆）温度、3列目が目的関数の値、4列目以降がパラメータです。 +最後の2 列は、 walker の重み (Neal-Jarzynski weight) と祖先（計算を開始したときのレプリカ）の番号です。 + +.. code-block:: + + # step walker beta fx z1 z2 weight ancestor + 0 0 0.0 0.07702743614780189 5.788848278451443 3.949126663745358 1.0 0 + 0 1 0.0 0.08737730661436376 3.551756435031283 3.6136808356591192 1.0 1 + 0 2 0.0 0.04954470587051104 4.70317508724506 4.786634108937754 1.0 2 + 0 3 0.0 0.04671675601156148 5.893543559206865 4.959531290614713 1.0 3 + 0 4 0.0 0.04142014655238446 5.246719912601735 4.960709612555206 1.0 4 + +また、 sim-trhepd-rheed ソルバーの場合は、 各作業フォルダの下にサブフォルダ ``Log%%%%%`` ( ``%%%%%`` がグリッドのid)が作成され、ロッキングカーブの情報などが記録されます +(各プロセスにおけるモンテカルロステップ数がidとして割り振られます)。 + +``best_result.txt`` に、目的関数 (R-factor) が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。 + +.. code-block:: + + nprocs = 4 + rank = 0 + step = 71 + walker = 5 + fx = 0.008186713312593607 + z1 = 4.225633749839847 + z2 = 5.142666117413409 + +最後に、 ``fx.txt`` には、各温度ごとの統計情報が記録されます。 + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.0 0.06428002079611472 0.002703413400677839 40 0.0 0.795 + 10.0 0.061399304916174735 0.002649424392996749 40 -0.6280819199879947 0.85 + 20.0 0.05904248889111052 0.0031622711212952034 40 -1.2283060742855603 0.74 + 30.0 0.04956921148431115 0.0028298565759159633 40 -1.7991035905899855 0.67 + +1列目は温度・逆温度で、2・3列目は目的関数 :math:`f(x)` の期待値と標準誤差、4列目はレプリカの個数、5列目は分配関数の比の対数 :math:`\log(Z_n/Z_0)` です(:math:`Z_0` は最初の温度点における分配関数)、6列目はモンテカルロ更新の採択率です。 + +なお、一括計算するスクリプトとして ``do.sh`` を用意しています。 +``do.sh`` では ``res.txt`` と ``ref.txt`` の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。 + +.. code-block:: + + sh prepare.sh + + ./bulk.exe + + time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml + + echo diff output/fx.txt ref.txt + res=0 + diff output/fx.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: output/fx.txt and ref.txt differ + false + fi + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~ + +``result_T%.txt`` を図示することで、 ``R-factor`` の小さいパラメータがどこにあるかを推定することができます。 +今回の場合は、以下のコマンドをうつことで2次元パラメータ空間の図 ``result_fx.pdf`` と ``result_T.pdf`` が作成されます。 +シンボルの色はそれぞれ ``R-factor`` と逆温度 :math:`\beta` に対応します。 + +.. code-block:: + + python3 plot_result_2d.py + +作成された図を見ると、(5.25, 4.25) と (4.25, 5.25) 付近にサンプルが集中していることと、 +``R-factor`` の値が小さいことがわかります。 + + +.. figure:: ../../../common/img/pamc_fx.* + + サンプルされたパラメータ。横軸は ``value_01`` , 縦軸は ``value_02`` を、色は ``R-factor`` を表す。 + + +.. figure:: ../../../common/img/pamc_T.* + + サンプルされたパラメータと逆温度。横軸は ``value_01`` , 縦軸は ``value_02`` を、色は逆温度を表す。 + +また、 ``RockingCurve.txt`` が各サブフォルダに格納されています。 +``LogXXX_YYY`` の ``XXX`` はモンテカルロのステップ数、 ``YYY`` は各MPIプロセス内のレプリカの番号です。 +これを用いることで、前チュートリアルの手順に従い、実験値との比較も行うことが可能です。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/sim_trhepd_rheed.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/sim_trhepd_rheed.rst.txt new file mode 100644 index 00000000..d9d328e7 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/sim_trhepd_rheed.rst.txt @@ -0,0 +1,146 @@ +TRHEPD 順問題ソルバー +======================== + +2DMAT は順問題ソルバーのひとつとして、 反射高速(陽)電子回折(RHEED, TRHEPD)の強度計算 (A. Ichimiya, Jpn. J. Appl. Phys. 22, 176 (1983); 24, 1365 (1985)) +を行うプログラム `sim-trhepd-rheed `_ のラッパーを提供しています。 +本チュートリアルでは sim-trhepd-rheed を用い、様々なアルゴリズムを利用した解析を行います。 +最初に、チュートリアルを行うために必要な sim-trhepd-rheed のインストールおよびテストを行います。 + +ダウンロード・インストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +まずチュートリアルの前提として、 ``2DMAT`` フォルダがある場所にいることを仮定します。:: + + $ ls -d 2DMAT + 2DMAT/ + +GitHub の sim-trhepd-rheed リポジトリから、ソースコード一式を入手し、ビルドします。:: + + git clone http://github.com/sim-trhepd-rheed/sim-trhepd-rheed + cd sim-trhepd-rheed/src + make + +makeが成功すると、 ``bulk.exe`` 及び ``surf.exe`` が作成されます。 + + +計算実行 +~~~~~~~~~~ + +sim-trhepd-rheed では、最初に ``bulk.exe`` で表面構造のバルク部分に関する計算をします。 +その後、 ``bulk.exe`` の計算結果 (``bulkP.b`` ファイル) を用いて、 ``surf.exe`` 表面構造の表面部分を計算します。 + +このチュートリアルでは実際に、 TRHEPD 計算をしてみます。 +サンプルとなる入力ファイルは2DMAT の ``sample/sim-trhepd-rheed`` にあります。 +まず、このフォルダを適当な作業用フォルダ ``work`` にコピーします。 + +.. code-block:: + + cd ../../ + cp -r 2DMAT/sample/sim-trhepd-rheed/solver work + cd work + +次に ``bulk.exe`` と ``surf.exe`` を ``work`` にコピーします + +.. code-block:: + + cp ../sim-trhepd-rheed/src/bulk.exe . + cp ../sim-trhepd-rheed/src/surf.exe . + +``bulk.exe`` を実行します。 + +.. code-block:: + + ./bulk.exe + +上記実行時に、以下のように出力され、バルクファイル ``bulkP.b`` が生成されます。 + +.. code-block:: + + 0:electron 1:positron ? + P + input-filename (end=e) ? : + bulk.txt + output-filename : + bulkP.b + +続いて、 ``surf.exe`` を実行します。 + +.. code-block:: + + ./surf.exe + +上記実行時に、以下のように出力されます。 + +.. code-block:: + + bulk-filename (end=e) ? : + bulkP.b + structure-filename (end=e) ? : + surf.txt + output-filename : + surf-bulkP.md + surf-bulkP.s + +実行後に、ファイル ``surf-bulkP.md`` 、 ``surf-bulkP.s`` +及び ``SURFYYYYMMDD-HHMMSSlog.txt`` が生成されます。 +(YYYYMMDD、 HHMMSS には実行日時に対応した数字が入ります) + +計算結果の可視化 +~~~~~~~~~~~~~~~~~ + +``surf-bulkP.s`` は以下の通りです。 + +.. code-block:: + + #azimuths,g-angles,beams + 1 56 13 + #ih,ik + 6 0 5 0 4 0 3 0 2 0 1 0 0 0 -1 0 -2 0 -3 0 -4 0 -5 0 -6 0 + 0.5000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1595E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.6000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1870E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.7000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2121E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.8000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2171E-02, 0.1927E-01, 0.2171E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.9000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.4397E-02, 0.1700E-01, 0.4397E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + 0.1000E+01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.6326E-02, 0.1495E-01, 0.6326E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, + (以下略) + +上記ファイルより、縦軸に角度（5行目以降の1列目データ）と(0,0)ピークの強度（5行目以降の8列目データ）から +ロッキングカーブを作成します。 +Gnuplot等のグラフソフトを用いる事も出来ますが、ここでは、 ``2DMAT/script`` フォルダにあるプログラム ``plot_bulkP.py`` を用います。 +以下のように実行して下さい。 + +.. code-block:: + + python3 ../2DMAT/script/plot_bulkP.py + +以下のような ``plot_bulkP.png`` が作成されます。 + +.. figure:: ../../../common/img/plot_bulkP.* + + Si(001)-2x1面のロッキングカーブ。 + +この00ピークの回折強度のデータに対し、コンボリューションを掛けたうえで規格化します。 +``surf-bulkP.s`` を準備して、 ``make_convolution.py`` を実行してください。 + +.. code-block:: + + python3 ../2DMAT/script/make_convolution.py + +実行すると、以下のようなファイル ``convolution.txt`` ができあがります。 + +.. code-block:: + + 0.500000 0.010818010 + 0.600000 0.013986716 + 0.700000 0.016119093 + 0.800000 0.017039022 + 0.900000 0.017084666 + （中略） + 5.600000 0.000728539 + 5.700000 0.000530758 + 5.800000 0.000412908 + 5.900000 0.000341740 + 6.000000 0.000277553 + +1列目が視射角、2列目が ``surf-bulkP.s`` に書かれた00ピーク回折強度のデータに +半値幅0.5のコンボリューションを付加して規格化したものです。 diff --git a/manual/v2.2.0/ja/_sources/tutorial/solver_simple.rst.txt b/manual/v2.2.0/ja/_sources/tutorial/solver_simple.rst.txt new file mode 100644 index 00000000..686a5298 --- /dev/null +++ b/manual/v2.2.0/ja/_sources/tutorial/solver_simple.rst.txt @@ -0,0 +1,91 @@ +順問題ソルバーの追加 +====================== + +ベンチマーク関数ソルバー +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``py2dmat`` では探索アルゴリズムのテストに利用できる順問題ソルバーとして、 ``analytical`` ソルバーを準備しています。 + +``analytical`` ソルバーを使うには、入力ファイルの ``[solver]`` セクションの ``name`` を ``"analytical"`` に設定します。 +また、 ``function_name`` パラメータを用いてベンチマーク関数 :math:`f(x)` を選択します。 +たとえば、 Himmelblau 関数を用いる場合には :: + + [solver] + name = "analytical" + function_name = "himmelblau" + +とします。 +利用可能な関数の詳細は :doc:`analytical ソルバーのリファレンス <../solver/analytical>` を参照してください。 + +順問題ソルバーの追加 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ユーザ定義の順問題ソルバーを定義・解析する一番簡単な方法は、 ``analytical`` ソルバーに追加することです。 +ここでは例として、 `Booth関数 `_ + +.. math:: + + f(x,y) = (x+2y-7)^{2} + (2x+y-5)^{2} + +を追加してみましょう（最小値は :math:`f(1,3) = 0` ）。 + +そのためには、 ``py2dmat`` のソースコードをダウンロードし、ファイルを編集する必要があります。 +ダウンロード方法や、ソースコードからの実行方法などは、 :doc:`インストールページ <../start>` を参照してください。 + +``analytical`` ソルバーは ``src/py2dmat/solver/analytical.py`` に定義されているので、これを編集します。 + +まず、 ``booth`` 関数を定義します。 + +.. code-block:: python + + def booth(xs: np.ndarray) -> float: + """Booth function + + it has one global minimum f(xs) = 0 at xs = [1,3]. + """ + + if xs.shape[0] != 2: + raise RuntimeError( + f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one" + ) + return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2 + +つぎに、入力ファイルの ``solver.function_name`` パラメータで ``booth`` 関数を指定できるようにするために、 +``Solver`` クラスのコンストラクタ (``__init__``) 中の if 分岐に以下のコードを挿入します。 + +.. code-block:: python + + elif function_name == "booth": + self.set_function(booth) + +この改造した ``analytical`` ソルバーでは、 Booth 関数の最適化が行なえます。 +たとえばNelder-Mead 法による最適化は、以下の入力ファイル (``input.toml``) を :: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "minsearch" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + initial_list = [0, 0] + + [solver] + name = "analytical" + function_name = "booth" + +``src/py2dmat_main.py`` に渡せば実行可能です:: + + $ python3 src/py2dmat_main.py input.toml + + ... skipped ... + + Iterations: 38 + Function evaluations: 75 + Solution: + x1 = 1.0000128043523089 + x2 = 2.9999832920260863 diff --git a/manual/v2.2.0/ja/_static/alert_info_32.png b/manual/v2.2.0/ja/_static/alert_info_32.png new file mode 100644 index 00000000..ea4d1baf Binary files /dev/null and b/manual/v2.2.0/ja/_static/alert_info_32.png differ diff --git a/manual/v2.2.0/ja/_static/alert_warning_32.png b/manual/v2.2.0/ja/_static/alert_warning_32.png new file mode 100644 index 00000000..a687c3dc Binary files /dev/null and b/manual/v2.2.0/ja/_static/alert_warning_32.png differ diff --git a/manual/v2.2.0/ja/_static/basic.css b/manual/v2.2.0/ja/_static/basic.css new file mode 100644 index 00000000..bdef29d8 --- /dev/null +++ b/manual/v2.2.0/ja/_static/basic.css @@ -0,0 +1,925 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 59em; + max-width: 70em; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/manual/v2.2.0/ja/_static/bg-page.png b/manual/v2.2.0/ja/_static/bg-page.png new file mode 100644 index 00000000..fe0a6dc8 Binary files /dev/null and b/manual/v2.2.0/ja/_static/bg-page.png differ diff --git a/manual/v2.2.0/ja/_static/bullet_orange.png b/manual/v2.2.0/ja/_static/bullet_orange.png new file mode 100644 index 00000000..1cb8097c Binary files /dev/null and b/manual/v2.2.0/ja/_static/bullet_orange.png differ diff --git a/manual/v2.2.0/ja/_static/doctools.js b/manual/v2.2.0/ja/_static/doctools.js new file mode 100644 index 00000000..d06a71d7 --- /dev/null +++ b/manual/v2.2.0/ja/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/manual/v2.2.0/ja/_static/documentation_options.js b/manual/v2.2.0/ja/_static/documentation_options.js new file mode 100644 index 00000000..351e787f --- /dev/null +++ b/manual/v2.2.0/ja/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '2.2-dev', + LANGUAGE: 'ja', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/manual/v2.2.0/ja/_static/file.png b/manual/v2.2.0/ja/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/manual/v2.2.0/ja/_static/file.png differ diff --git a/manual/v2.2.0/ja/_static/haiku.css b/manual/v2.2.0/ja/_static/haiku.css new file mode 100644 index 00000000..6830f3fc --- /dev/null +++ b/manual/v2.2.0/ja/_static/haiku.css @@ -0,0 +1,375 @@ +/* + * haiku.css_t + * ~~~~~~~~~~~ + * + * Sphinx stylesheet -- haiku theme. + * + * Adapted from http://haiku-os.org/docs/Haiku-doc.css. + * Original copyright message: + * + * Copyright 2008-2009, Haiku. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Francois Revol + * Stephan Assmus + * Braden Ewing + * Humdinger + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +html { + margin: 0px; + padding: 0px; + background: #FFF url(bg-page.png) top left repeat-x; +} + +body { + line-height: 1.5; + margin: auto; + padding: 0px; + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; + min-width: 59em; + max-width: 70em; + color: #333333; +} + +div.footer { + padding: 8px; + font-size: 11px; + text-align: center; + letter-spacing: 0.5px; +} + +/* link colors and text decoration */ + +a:link { + font-weight: bold; + text-decoration: none; + color: #dc3c01; +} + +a:visited { + font-weight: bold; + text-decoration: none; + color: #551a8b; +} + +a:hover, a:active { + text-decoration: underline; + color: #ff4500; +} + +/* Some headers act as anchors, don't give them a hover effect */ + +h1 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h2 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h3 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h4 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +a.headerlink { + color: #a7ce38; + padding-left: 5px; +} + +a.headerlink:hover { + color: #a7ce38; +} + +/* basic text elements */ + +div.content { + margin-top: 20px; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 50px; + font-size: 0.9em; +} + +/* heading and navigation */ + +div.header { + position: relative; + left: 0px; + top: 0px; + height: 85px; + /* background: #eeeeee; */ + padding: 0 40px; +} +div.header h1 { + font-size: 1.6em; + font-weight: normal; + letter-spacing: 1px; + color: #0c3762; + border: 0; + margin: 0; + padding-top: 15px; +} +div.header h1 a { + font-weight: normal; + color: #0c3762; +} +div.header h2 { + font-size: 1.3em; + font-weight: normal; + letter-spacing: 1px; + text-transform: uppercase; + color: #aaa; + border: 0; + margin-top: -3px; + padding: 0; +} + +div.header img.rightlogo { + float: right; +} + + +div.title { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-bottom: 25px; +} +div.topnav { + /* background: #e0e0e0; */ +} +div.topnav p { + margin-top: 0; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 0px; + text-align: right; + font-size: 0.8em; +} +div.bottomnav { + background: #eeeeee; +} +div.bottomnav p { + margin-right: 40px; + text-align: right; + font-size: 0.8em; +} + +a.uplink { + font-weight: normal; +} + + +/* contents box */ + +table.index { + margin: 0px 0px 30px 30px; + padding: 1px; + border-width: 1px; + border-style: dotted; + border-color: #e0e0e0; +} +table.index tr.heading { + background-color: #e0e0e0; + text-align: center; + font-weight: bold; + font-size: 1.1em; +} +table.index tr.index { + background-color: #eeeeee; +} +table.index td { + padding: 5px 20px; +} + +table.index a:link, table.index a:visited { + font-weight: normal; + text-decoration: none; + color: #dc3c01; +} +table.index a:hover, table.index a:active { + text-decoration: underline; + color: #ff4500; +} + + +/* Haiku User Guide styles and layout */ + +/* Rounded corner boxes */ +/* Common declarations */ +div.admonition { + -webkit-border-radius: 10px; + -khtml-border-radius: 10px; + -moz-border-radius: 10px; + border-radius: 10px; + border-style: dotted; + border-width: thin; + border-color: #dcdcdc; + padding: 10px 15px 10px 15px; + margin-bottom: 15px; + margin-top: 15px; +} +div.note { + padding: 10px 15px 10px 80px; + background: #e4ffde url(alert_info_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.warning { + padding: 10px 15px 10px 80px; + background: #fffbc6 url(alert_warning_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.seealso { + background: #e4ffde; +} + +/* More layout and styles */ +h1 { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h2 { + font-size: 1.2em; + font-weight: normal; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h3 { + font-size: 1.1em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +h4 { + font-size: 1.0em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +p { + text-align: justify; +} + +p.last { + margin-bottom: 0; +} + +ol { + padding-left: 20px; +} + +ul { + padding-left: 5px; + margin-top: 3px; +} + +li { + line-height: 1.3; +} + +div.content ul > li { + -moz-background-clip:border; + -moz-background-inline-policy:continuous; + -moz-background-origin:padding; + background: transparent url(bullet_orange.png) no-repeat scroll left 0.45em; + list-style-image: none; + list-style-type: none; + padding: 0 0 0 1.666em; + margin-bottom: 3px; +} + +td { + vertical-align: top; +} + +code { + background-color: #e2e2e2; + font-size: 1.0em; + font-family: monospace; +} + +pre { + border-color: #0c3762; + border-style: dotted; + border-width: thin; + margin: 0 0 12px 0; + padding: 0.8em; +} + +hr { + border-top: 1px solid #ccc; + border-bottom: 0; + border-right: 0; + border-left: 0; + margin-bottom: 10px; + margin-top: 20px; +} + +/* printer only pretty stuff */ +@media print { + .noprint { + display: none; + } + /* for acronyms we want their definitions inlined at print time */ + acronym[title]:after { + font-size: small; + content: " (" attr(title) ")"; + font-style: italic; + } + /* and not have mozilla dotted underline */ + acronym { + border: none; + } + div.topnav, div.bottomnav, div.header, table.index { + display: none; + } + div.content { + margin: 0px; + padding: 0px; + } + html { + background: #FFF; + } +} + +.viewcode-back { + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; + margin: -1px -10px; + padding: 0 12px; +} + +/* math display */ +div.math p { + text-align: center; +} \ No newline at end of file diff --git a/manual/v2.2.0/ja/_static/language_data.js b/manual/v2.2.0/ja/_static/language_data.js new file mode 100644 index 00000000..b3681270 --- /dev/null +++ b/manual/v2.2.0/ja/_static/language_data.js @@ -0,0 +1,26 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = []; + + +/* Non-minified version is copied as a separate JS file, is available */ + +/** + * Dummy stemmer for languages without stemming rules. + */ +var Stemmer = function() { + this.stemWord = function(w) { + return w; + } +} + diff --git a/manual/v2.2.0/ja/_static/minus.png b/manual/v2.2.0/ja/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/manual/v2.2.0/ja/_static/minus.png differ diff --git a/manual/v2.2.0/ja/_static/plus.png b/manual/v2.2.0/ja/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/manual/v2.2.0/ja/_static/plus.png differ diff --git a/manual/v2.2.0/ja/_static/pygments.css b/manual/v2.2.0/ja/_static/pygments.css new file mode 100644 index 00000000..650b5270 --- /dev/null +++ b/manual/v2.2.0/ja/_static/pygments.css @@ -0,0 +1,72 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #ffffff; } +.highlight .c { color: #aaaaaa; font-style: italic } /* Comment */ +.highlight .err { color: #FF0000; background-color: #FFAAAA } /* Error */ +.highlight .k { color: #0000aa } /* Keyword */ +.highlight .ch { color: #aaaaaa; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #aaaaaa; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #4c8317 } /* Comment.Preproc */ +.highlight .cpf { color: #aaaaaa; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #aaaaaa; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #0000aa; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #aa0000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #aa0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00aa00 } /* Generic.Inserted */ +.highlight .go { color: #888888 } /* Generic.Output */ +.highlight .gp { color: #555555 } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #aa0000 } /* Generic.Traceback */ +.highlight .kc { color: #0000aa } /* Keyword.Constant */ +.highlight .kd { color: #0000aa } /* Keyword.Declaration */ +.highlight .kn { color: #0000aa } /* Keyword.Namespace */ +.highlight .kp { color: #0000aa } /* Keyword.Pseudo */ +.highlight .kr { color: #0000aa } /* Keyword.Reserved */ +.highlight .kt { color: #00aaaa } /* Keyword.Type */ +.highlight .m { color: #009999 } /* Literal.Number */ +.highlight .s { color: #aa5500 } /* Literal.String */ +.highlight .na { color: #1e90ff } /* Name.Attribute */ +.highlight .nb { color: #00aaaa } /* Name.Builtin */ +.highlight .nc { color: #00aa00; text-decoration: underline } /* Name.Class */ +.highlight .no { color: #aa0000 } /* Name.Constant */ +.highlight .nd { color: #888888 } /* Name.Decorator */ +.highlight .ni { color: #880000; font-weight: bold } /* Name.Entity */ +.highlight .nf { color: #00aa00 } /* Name.Function */ +.highlight .nn { color: #00aaaa; text-decoration: underline } /* Name.Namespace */ +.highlight .nt { color: #1e90ff; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #aa0000 } /* Name.Variable */ +.highlight .ow { color: #0000aa } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #009999 } /* Literal.Number.Bin */ +.highlight .mf { color: #009999 } /* Literal.Number.Float */ +.highlight .mh { color: #009999 } /* Literal.Number.Hex */ +.highlight .mi { color: #009999 } /* Literal.Number.Integer */ +.highlight .mo { color: #009999 } /* Literal.Number.Oct */ +.highlight .sa { color: #aa5500 } /* Literal.String.Affix */ +.highlight .sb { color: #aa5500 } /* Literal.String.Backtick */ +.highlight .sc { color: #aa5500 } /* Literal.String.Char */ +.highlight .dl { color: #aa5500 } /* Literal.String.Delimiter */ +.highlight .sd { color: #aa5500 } /* Literal.String.Doc */ +.highlight .s2 { color: #aa5500 } /* Literal.String.Double */ +.highlight .se { color: #aa5500 } /* Literal.String.Escape */ +.highlight .sh { color: #aa5500 } /* Literal.String.Heredoc */ +.highlight .si { color: #aa5500 } /* Literal.String.Interpol */ +.highlight .sx { color: #aa5500 } /* Literal.String.Other */ +.highlight .sr { color: #009999 } /* Literal.String.Regex */ +.highlight .s1 { color: #aa5500 } /* Literal.String.Single */ +.highlight .ss { color: #0000aa } /* Literal.String.Symbol */ +.highlight .bp { color: #00aaaa } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #00aa00 } /* Name.Function.Magic */ +.highlight .vc { color: #aa0000 } /* Name.Variable.Class */ +.highlight .vg { color: #aa0000 } /* Name.Variable.Global */ +.highlight .vi { color: #aa0000 } /* Name.Variable.Instance */ +.highlight .vm { color: #aa0000 } /* Name.Variable.Magic */ +.highlight .il { color: #009999 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/manual/v2.2.0/ja/_static/searchtools.js b/manual/v2.2.0/ja/_static/searchtools.js new file mode 100644 index 00000000..7918c3fa --- /dev/null +++ b/manual/v2.2.0/ja/_static/searchtools.js @@ -0,0 +1,574 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + `Search finished, found ${resultCount} page(s) matching the search query.` + ); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent !== undefined) return docContent.textContent; + console.warn( + "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + /** + * execute search (requires search index to be loaded) + */ + query: (query) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + // array of [docname, title, anchor, descr, score, filename] + let results = []; + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + let score = Math.round(100 * queryLower.length / title.length) + results.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score, + filenames[file], + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id] of foundEntries) { + let score = Math.round(100 * queryLower.length / entry.length) + results.push([ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + ]); + } + } + } + + // lookup as object + objectTerms.forEach((term) => + results.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + results.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item))); + + // now sort the results by score (in opposite order of appearance, since the + // display function below uses pop() to retrieve items) and then + // alphabetically + results.sort((a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; + }); + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + results = results.reverse(); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord) && !terms[word]) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord) && !titleTerms[word]) + arr.push({ files: titleTerms[word], score: Scorer.partialTitle }); + }); + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1) + fileMap.get(file).push(word); + else fileMap.set(file, [word]); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords) => { + const text = Search.htmlToText(htmlText); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/manual/v2.2.0/ja/_static/sphinx_highlight.js b/manual/v2.2.0/ja/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/manual/v2.2.0/ja/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/manual/v2.2.0/ja/_static/translations.js b/manual/v2.2.0/ja/_static/translations.js new file mode 100644 index 00000000..817b128c --- /dev/null +++ b/manual/v2.2.0/ja/_static/translations.js @@ -0,0 +1,60 @@ +Documentation.addTranslations({ + "locale": "ja", + "messages": { + "%(filename)s — %(docstitle)s": "%(filename)s — %(docstitle)s", + "© %(copyright_prefix)s %(copyright)s.": "", + ", in ": ", in ", + "About these documents": "\u3053\u306e\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\u306b\u3064\u3044\u3066", + "Automatically generated list of changes in version %(version)s": "\u30d0\u30fc\u30b8\u30e7\u30f3 %(version)s \u306e\u5909\u66f4\u70b9\uff08\u3053\u306e\u30ea\u30b9\u30c8\u306f\u81ea\u52d5\u751f\u6210\u3055\u308c\u3066\u3044\u307e\u3059\uff09", + "C API changes": "C API \u306b\u95a2\u3059\u308b\u5909\u66f4", + "Changes in Version %(version)s — %(docstitle)s": "\u30d0\u30fc\u30b8\u30e7\u30f3 %(version)s \u306e\u5909\u66f4\u70b9 — %(docstitle)s", + "Collapse sidebar": "\u30b5\u30a4\u30c9\u30d0\u30fc\u3092\u305f\u305f\u3080", + "Complete Table of Contents": "\u7dcf\u5408\u76ee\u6b21", + "Contents": "\u30b3\u30f3\u30c6\u30f3\u30c4", + "Copyright": "\u8457\u4f5c\u6a29", + "Created using Sphinx %(sphinx_version)s.": "", + "Expand sidebar": "\u30b5\u30a4\u30c9\u30d0\u30fc\u3092\u5c55\u958b", + "Full index on one page": "\u7dcf\u7d22\u5f15", + "General Index": "\u7dcf\u5408\u7d22\u5f15", + "Global Module Index": "\u30e2\u30b8\u30e5\u30fc\u30eb\u7dcf\u7d22\u5f15", + "Go": "\u691c\u7d22", + "Hide Search Matches": "\u691c\u7d22\u7d50\u679c\u3092\u96a0\u3059", + "Index": "\u7d22\u5f15", + "Index – %(key)s": "\u7d22\u5f15 – %(key)s", + "Index pages by letter": "\u982d\u6587\u5b57\u5225\u7d22\u5f15", + "Indices and tables:": "\u7d22\u5f15\u3068\u8868\u4e00\u89a7:", + "Last updated on %(last_updated)s.": "\u6700\u7d42\u66f4\u65b0: %(last_updated)s", + "Library changes": "\u30e9\u30a4\u30d6\u30e9\u30ea\u306b\u95a2\u3059\u308b\u5909\u66f4", + "Navigation": "\u30ca\u30d3\u30b2\u30fc\u30b7\u30e7\u30f3", + "Next topic": "\u6b21\u306e\u30c8\u30d4\u30c3\u30af\u3078", + "Other changes": "\u305d\u306e\u4ed6\u306e\u5909\u66f4", + "Overview": "\u6982\u8981", + "Please activate JavaScript to enable the search\n functionality.": "\u691c\u7d22\u6a5f\u80fd\u3092\u4f7f\u3046\u306b\u306f JavaScript \u3092\u6709\u52b9\u306b\u3057\u3066\u304f\u3060\u3055\u3044\u3002", + "Preparing search...": "\u691c\u7d22\u3092\u6e96\u5099\u3057\u3066\u3044\u307e\u3059...", + "Previous topic": "\u524d\u306e\u30c8\u30d4\u30c3\u30af\u3078", + "Quick search": "\u30af\u30a4\u30c3\u30af\u691c\u7d22", + "Search": "\u691c\u7d22", + "Search Page": "\u691c\u7d22\u30da\u30fc\u30b8", + "Search Results": "\u691c\u7d22\u7d50\u679c", + "Search finished, found ${resultCount} page(s) matching the search query.": "", + "Search within %(docstitle)s": "%(docstitle)s \u5185\u3092\u691c\u7d22", + "Searching": "\u691c\u7d22\u4e2d", + "Searching for multiple words only shows matches that contain\n all words.": "\u8907\u6570\u306e\u5358\u8a9e\u3092\u691c\u7d22\u3059\u308b\u3068\u3001\u6b21\u3092\u542b\u3080\u4e00\u81f4\u306e\u307f\u304c\u8868\u793a\u3055\u308c\u307e\u3059\n \u00a0\u00a0\u00a0 \u3059\u3079\u3066\u306e\u7528\u8a9e\u3002", + "Show Source": "\u30bd\u30fc\u30b9\u30b3\u30fc\u30c9\u3092\u8868\u793a", + "Table of Contents": "\u76ee\u6b21", + "This Page": "\u3053\u306e\u30da\u30fc\u30b8", + "Welcome! This is": "Welcome! This is", + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "\u691c\u7d22\u3057\u305f\u6587\u5b57\u5217\u306f\u3069\u306e\u6587\u66f8\u306b\u3082\u898b\u3064\u304b\u308a\u307e\u305b\u3093\u3067\u3057\u305f\u3002\u3059\u3079\u3066\u306e\u5358\u8a9e\u304c\u6b63\u78ba\u306b\u8a18\u8ff0\u3055\u308c\u3066\u3044\u308b\u304b\u3001\u3042\u308b\u3044\u306f\u3001\u5341\u5206\u306a\u30ab\u30c6\u30b4\u30ea\u30fc\u304c\u9078\u629e\u3055\u308c\u3066\u3044\u308b\u304b\u78ba\u8a8d\u3057\u3066\u304f\u3060\u3055\u3044\u3002", + "all functions, classes, terms": "\u95a2\u6570\u3001\u30af\u30e9\u30b9\u304a\u3088\u3073\u7528\u8a9e\u7dcf\u89a7", + "can be huge": "\u5927\u304d\u3044\u5834\u5408\u304c\u3042\u308b\u306e\u3067\u6ce8\u610f", + "last updated": "\u6700\u7d42\u66f4\u65b0", + "lists all sections and subsections": "\u7ae0\uff0f\u7bc0\u4e00\u89a7", + "next chapter": "\u6b21\u306e\u7ae0\u3078", + "previous chapter": "\u524d\u306e\u7ae0\u3078", + "quick access to all modules": "\u5168\u30e2\u30b8\u30e5\u30fc\u30eb\u65e9\u898b\u8868", + "search": "\u691c\u7d22", + "search this documentation": "\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\u3092\u691c\u7d22", + "the documentation for": "the documentation for" + }, + "plural_expr": "0" +}); \ No newline at end of file diff --git a/manual/v2.2.0/ja/acknowledgement.html b/manual/v2.2.0/ja/acknowledgement.html new file mode 100644 index 00000000..85ed1cef --- /dev/null +++ b/manual/v2.2.0/ja/acknowledgement.html @@ -0,0 +1,65 @@ + + + + + + + + 謝辞 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

謝辞

+

本ソフトウェアの開発は、科研費(2019-2021年度)「超並列マシンを用いた計算統計と測定技術の融合」および東京大学物性研究所 ソフトウェア高度化プロジェクト (2020, 2021 年度) の支援を受け開発されました。 +本ソフトウェアの設計・変数命名の一部は abics を参考にしています。 +また、順問題ソルバーの実装にあたり、花田貴氏 (東北大学)、望月出海氏(KEK)、W. Voegeli氏(東京学芸大学)、白澤徹郎氏(AIST)、R. Ahmed氏(九州大学)、和田健氏(KEK)にお世話になりました。ソルバーの追加方法について、塚本恭平氏(物性研)にチュートリアルを追加していただきました。 +この場を借りて感謝します。

+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/algorithm/bayes.html b/manual/v2.2.0/ja/algorithm/bayes.html new file mode 100644 index 00000000..90737b18 --- /dev/null +++ b/manual/v2.2.0/ja/algorithm/bayes.html @@ -0,0 +1,189 @@ + + + + + + + + ベイズ最適化 bayes — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

ベイズ最適化 bayes

+

bayes はベイズ最適化を用いてパラメータ探索を行う Algorithm です。

+

実装には PHYSBO を用いています。

+
+

前準備

+

あらかじめ PHYSBO をインストールしておく必要があります。:

+
python3 -m pip install physbo
+
+
+

mpi4py がインストールされている場合、 +MPI 並列計算が可能です。

+
+
+

入力パラメータ

+
+

[algorithmparam] セクション

+

探索パラメータ空間を定義します。

+

mesh_path が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。

+

mesh_path が定義されていない場合は、 min_list, max_list, num_list を用いて、 +各パラメータについて等間隔なグリッドを作成します。

+
    +

  • mesh_path

    +

    形式: string型

    +

    説明: メッシュデータの情報が記載された参照用ファイルへのパス。

    +
    • +

  • min_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最小値。

    +
    • +

  • max_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最大値。

    +
    • +

  • num_list

    +

    形式: 整数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる数。

    +
    • +
+
+
+

[algorithm.bayes] セクション

+

手法のハイパーパラメータを定義します。

+
    +

  • random_max_num_probes

    +

    形式： int型 (default: 20)

    +

    説明: ベイズ最適化を行う前に行うランダムサンプリングの回数(パラメータとスコアが初めに無い場合にはランダムサンプリングは必須)。

    +
    • +

  • bayes_max_num_probes

    +

    形式： int型 (default: 40)

    +

    説明: ベイズ最適化を行う回数。

    +
    • +

  • score

    +

    形式: string型 (default: TS )

    +

    説明: スコア関数を指定するパラメータ。 +EI, PI, TS より選択可能で、それぞれ "expected improvement", "probability of improvement", "Thompson sampling" を行う。

    +
    • +

  • interval

    +

    形式： int型 (default: 5)

    +

    説明: 指定したインターバルごとに、ハイパーパラメータを学習します。負の値を指定すると、ハイパーパラメータの学習は行われません。 +0を指定すると、ハイパーパラメータの学習は最初のステップでのみ行われます。

    +
    • +

  • num_rand_basis

    +

    形式： int型 (default: 5000)

    +

    説明： 基底関数の数。0を指定した場合、Bayesian linear modelを利用しない通常のガウシアンプロセスが行われます。

    +
    • +
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス、 +2列目以降は [solver.param] セクションにある、 +string_list で定義された変数に入る値が入ります。

+

以下、サンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

出力ファイル

+
+

BayesData.txt

+

最適化過程の各ステップにおいて、 +パラメータと対応する目的関数の値が、 +これまでの最適パラメータとそのステップで探索したパラメータの順に記載されます。

+
#step z1 z2 R-factor z1_action z2_action R-factor_action
+0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885
+1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033
+2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189
+3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794
+...
+
+
+
+
+
+

アルゴリズム解説

+

ベイズ最適化 (Bayesian optimization, BO) は、機械学習を援用した最適化アルゴリズムであり、特に目的関数の評価に時間がかかるときに強力な手法です。

+

BO では目的関数 \(f(\vec{x})\) を、評価が早く最適化のしやすいモデル関数（多くの場合ガウス過程） \(g(\vec{x})\) で近似します。 +\(g\) は、あらかじめ適当に決められたいくつかの点（訓練データセット） \(\{\vec{x}_i\}_{i=1}^N\) での目的関数の値 \(\{f(\vec{x}_i)\}_{i=1}^N\) をよく再現するように訓練されます。 +パラメータ空間の各点において、訓練された \(g(\vec{x})\) の値の期待値およびその誤差から求められる「スコア」 (acquition function) が最適になるような点 \(\vec{x}_{N+1}\) を次の計算候補点として提案します。 +\(f(\vec{x}_{N+1})\) を評価し、 訓練データセットに追加、 \(g\) を再訓練します。 +こうした探索を適当な回数繰り返した後、目的関数の値が最も良かったものを最適解として返します。

+

少ない誤差でより良い期待値を与える点は、正解である可能性こそ高いですが、すでに十分な情報があると考えられるので、モデル関数の精度向上にはあまり寄与しません。 +逆に、誤差の大きな点は正解ではないかもしれませんが、情報の少ない場所であり、モデル関数の更新には有益だと考えられます。 +前者を選ぶことを「活用」、後者を選ぶことを「探索」とよび、両者をバランス良く行うのが重要です。 +「スコア」の定義はこれらをどう選ぶかを定めます。

+

2DMAT では、ベイズ最適化のライブラリとして、 PHYSBO を用います。 +PHYSBO は mapper_mpi のように、あらかじめ決めておいた候補点の集合に対して「スコア」を計算して、最適解を提案します。 +候補点の集合を分割することでMPI 並列実行が可能です。 +また、 訓練データの点数 \(N\) に対して線形の計算量でモデル関数の評価、ひいては「スコア」の計算が可能となるようなカーネルを用いています。 +PHYSBO では「スコア」関数として "expected improvement (EI)", "probability of improvement (PI)", "Thompson sampling (TS)" が利用できます。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/algorithm/exchange.html b/manual/v2.2.0/ja/algorithm/exchange.html new file mode 100644 index 00000000..1608672e --- /dev/null +++ b/manual/v2.2.0/ja/algorithm/exchange.html @@ -0,0 +1,335 @@ + + + + + + + + 交換モンテカルロ法 exchange — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

交換モンテカルロ法 exchange

+

exchange はレプリカ交換モンテカルロ法を用いてパラメータ探索を行う Algorithm です。

+
+

前準備

+

あらかじめ mpi4py をインストールしておく必要があります。:

+
python3 -m pip install mpi4py
+
+
+
+
+

入力パラメータ

+

サブセクション param と exchange を持ちます。

+
+

[param] セクション

+

探索空間を定義します。 +mesh_path キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。

+
    +

  • 連続空間

    +
      +

    • initial_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +

      説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。

      +
      • +

    • unit_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: 各パラメータの単位。

      探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 +簡易的な無次元化・正規化を行います。 +定義しなかった場合にはすべての次元で 1.0 となります。

      +
      +
      +
      • +

    • min_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最小値。

      モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +

    • max_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最大値。

      モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +
    +
    • +

  • 離散空間

    +
      +

    • mesh_path

      +

      形式: ファイルパス

      +

      説明: メッシュ定義ファイル。

      +
      • +

    • neighborlist_path

      +

      形式: ファイルパス

      +

      説明: 近傍リスト定義ファイル。

      +
      • +
    +
    • +
+
+
+

[exchange] セクション

+
    +

  • numsteps

    +

    形式: 整数値。

    +

    説明: モンテカルロ更新を行う回数。

    +
    • +

  • numsteps_exchange

    +

    形式: 整数値。

    +

    説明: 「温度」のレプリカ交換を行う頻度。この回数だけモンテカルロ更新を行ったらレプリカ交換を実行します。

    +
    • +

  • Tmin

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最小値。

    +
    • +

  • Tmax

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最大値。

    +
    • +

  • bmin

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最小値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • bmax

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最大値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • Tlogspace

    +

    形式: 真偽値。 (default: true)

    +
    +
    説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。

    true のときは対数空間で等分割します。

    +
    +
    +
    • +

  • nreplica_per_proc

    +

    形式: 整数。 (default: 1)

    +

    説明: ひとつのMPI プロセスが担当するレプリカの数。

    +
    • +
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス（実際には使用されません）、 +2列目以降は探索空間の座標を指定します。

+

以下、サンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

近傍リスト定義ファイル

+

離散空間をモンテカルロ法で探索する場合、各点 \(i\) ごとに次に移動できる点 \(j\) を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。

+

1列目に始点の番号 \(i\) を記載し、 +2列目以降に \(i\) から移動できる終点 \(j\) を列挙します。

+

近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール py2dmat_neighborlist が提供されています。 +詳細は 関連ツール を参照してください。

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

出力ファイル

+
+

RANK/trial.txt

+

各レプリカについて、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの温度、4列目に目的関数の値、5列目以降にパラメータが記載されます。

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861
+2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

RANK/result.txt

+

各レプリカについて、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +trial.txt と同一の書式です。

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

best_result.txt

+

サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

result_T#.txt

+

サンプリング結果を温度ごとにまとめ直したものです。 +# は温度点の番号です。 +ファイルの1 列目はステップ数、2列目は全体での walker 番号、3列目は目的関数の値、 4列目以降は探索パラメータの値です。

+
# T = 1.0
+0 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+1 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+2 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+3 15 28.98676409223712 3.7442621319489637 -3.868754990884034
+
+
+
+

アルゴリズム解説

+
+
+
+
+

マルコフ連鎖モンテカルロ法

+

モンテカルロ法（モンテカルロサンプリング）では、パラメータ空間中を動き回る walker \(\vec{x}\) を重み \(W(\vec{x})\) に従って確率的に動かすことで目的関数の最適化を行います。 +重み \(W(\vec{x})\) として、「温度」 \(T > 0\) を導入して \(W(\vec{x}) = e^{-f(\vec{x})/T}\) とすることが一般的です（ボルツマン重み）。 +ほとんどの場合において、 \(W\) に基づいて直接サンプリングする (walker を生成する) のは不可能なので、 walker を確率的に少しずつ動かすことで、頻度分布が \(W\) に従うように時系列 \(\{\vec{x}_t\}\) を生成します (マルコフ連鎖モンテカルロ法, MCMC)。 +\(\vec{x}\) から \(\vec{x}'\) へ遷移する確率を \(p(\vec{x}' | \vec{x})\) とすると、

+
+\[W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x})\]
+

となるように \(p\) を定めれば時系列 \(\{\vec{x}_t\}\) の頻度分布が \(W(\vec{x})\) に収束することが示されます（釣り合い条件） [1] 。 +実際の計算では、より強い制約である詳細釣り合い条件

+
+\[p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x})\]
+

を課すことがほとんどです。 両辺で \(vec{x}\) についての和を取ると釣り合い条件に帰着します。

+

\(p\) を求めるアルゴリズムはいくつか提案されていますが、 2DMAT では Metropolis-Hasting 法 (MH法) を用います。 +MH 法では、遷移プロセスを提案プロセスと採択プロセスとに分割します。

+
    +

  1. 提案確率 \(P(\vec{x} | \vec{x}_t)\) で候補点 \(\vec{x}\) を生成します

    +
      +

    • 提案確率 \(P\) としては \(\vec{x}_t\) を中心とした一様分布やガウス関数などの扱いやすいものを利用します

      • +
    +
    2. +

  2. 提案された候補点 \(\vec{x}\) を採択確率 \(Q(\vec{x}, | \vec{x}_t)\) で受け入れ、 \(\vec{x}_{t+1} = \vec{x}\) とします +- 受け入れなかった場合は \(\vec{x}_{t+1} = \vec{x}_t\) とします

    3. +
+

採択確率 \(Q(\vec{x} | \vec{x}_t)\) は

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right]\]
+

とします。 +この定義が詳細釣り合い条件を満たすことは、詳細釣り合いの式に代入することで簡単に確かめられます。 +特に、重みとしてボルツマン因子を、 +提案確率として対称なもの \(P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})\) を用いたときには、

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right]\]
+

という更に簡単な形になります。

+

\(\Delta f = f(\vec{x}) - f(\vec{x}_t)\) とおいて、 +\(\Delta f \le 0\) のときに \(Q = 1\) となることを踏まえると、 +MH 法によるMCMC は次のようになります。

+
    +

  1. 現在地点の近くからランダムに次の座標の候補を選び、目的関数 \(f\) の値を調べる

    2. +

  2. \(\Delta f \le 0\) ならば（山を下る方向ならば）移動する

    3. +

  3. \(\Delta f > 0\) ならば採択確率 \(Q = e^{-\Delta f / T}\) で移動する

    4. +

  4. 1-3 を適当な回数繰り返す

    5. +
+

得られた時系列のうち、目的関数の値が一番小さいものを最適解とします。 +3 番のプロセスのおかげで、 \(\Delta f \sim T\) ぐらいの山を乗り越えられるので、局所最適解にトラップされた場合にも脱出可能です。

+
+
+

レプリカ交換モンテカルロ法

+

モンテカルロ法による最適化では、温度 \(T\) は非常に重要なハイパーパラメータとなっています。 +モンテカルロ法では、温度 \(T\) 程度の山を乗り越えられますが、逆にそれ以上の深さの谷からは容易に脱出できません。 +そのため、局所解へのトラップを防ぐためには温度を上げる必要があります。 +一方で、 \(T\) よりも小さい谷は谷として見えなくなるため、得られる \(\min f(\vec{x})\) の精度も \(T\) 程度になり、精度を上げるためには温度を下げる必要があります。 +ここから、最適解を探すためには温度 \(T\) を注意深く決める必要があることがわかります。

+

この問題を解決する方法として、温度 \(T\) を固定せずに更新していくというものがあります。 +たとえば、焼きなまし法 (simulated annealing) では、温度をステップごとに徐々に下げていきます。 +焼戻し法 (simulated tempering) は、温度をハイパーパラメータではなく、サンプリングすべきパラメータとして扱い、（詳細）釣り合い条件を満たすように更新することで、加熱と冷却を実現します。温度を下げることで谷の詳細を調べ、温度を上げることで谷から脱出します。 +レプリカ交換モンテカルロ法 (replica exchange Monte Carlo) は焼戻し法を更に発展させた手法で、並列焼戻し法 (parallel tempering) とも呼ばれます。 +レプリカ交換モンテカルロ法では、レプリカと呼ばれる複数の系を、それぞれ異なる温度で並列にモンテカルロシミュレーションします。 +そして、ある一定間隔で、（詳細）釣り合い条件を満たすように他のレプリカと温度を交換します。 +焼戻し法と同様に、温度を上下することで谷を調べたり脱出したりするのですが、各温度点について、かならずレプリカのどれかが対応しているため、全体として特定の温度に偏ることがなくなります。 +また、複数の MPI プロセスを用意してそれぞれレプリカを担当させることで簡単に並列化可能です。 +数多くのレプリカを用意することで温度間隔が狭まると、温度交換の採択率も上がるため、大規模並列計算に特に向いたアルゴリズムです。 +有限温度由来の「ぼやけ」がどうしても生まれるので、モンテカルロ法の結果を初期値として minsearch をするのがおすすめです。

+

脚注

+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/algorithm/index.html b/manual/v2.2.0/ja/algorithm/index.html new file mode 100644 index 00000000..5c55af45 --- /dev/null +++ b/manual/v2.2.0/ja/algorithm/index.html @@ -0,0 +1,73 @@ + + + + + + + + 探索アルゴリズム — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

探索アルゴリズム

+

探索アルゴリズム Algorithm は Solver の結果 \(f(x)\) を用いて +パラメータ空間 \(\mathbf{X} \ni x\) を探索します。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/algorithm/mapper_mpi.html b/manual/v2.2.0/ja/algorithm/mapper_mpi.html new file mode 100644 index 00000000..28c3fb3c --- /dev/null +++ b/manual/v2.2.0/ja/algorithm/mapper_mpi.html @@ -0,0 +1,149 @@ + + + + + + + + 自明並列探索 mapper — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

自明並列探索 mapper

+

mapper_mpi はパラメータ空間中の候補点をあらかじめ用意しておいて、そのすべてで \(f(x)\) を計算することで最小値を探索するアルゴリズムです。 +MPI 実行した場合、候補点の集合を等分割して各プロセスに自動的に割り振ることで自明並列計算を行います。

+
+

前準備

+

MPI 並列を行う場合は、 mpi4py をインストールしておく必要があります。:

+
python3 -m pip install mpi4py
+
+
+
+
+

入力パラメータ

+
+

[param] セクション

+

探索パラメータ空間を定義します。

+

mesh_path が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。

+

mesh_path が定義されていない場合は、 min_list, max_list, num_list を用いて、 +各パラメータについて等間隔なグリッドを作成します。

+
    +

  • mesh_path

    +

    形式: string型

    +

    説明: メッシュ定義ファイルへのパス。

    +
    • +

  • min_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最小値。

    +
    • +

  • max_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最大値。

    +
    • +

  • num_list

    +

    形式: 整数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる数。

    +
    • +
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1 + dimension 列のテキストファイルで、 +1列目にメッシュのインデックス、 +2列目以降は探索パラメータ \(x\) に対応する値を記載します。 +また、 # から始まる行はコメントとして無視されます。

+

以下、2次元パラメータ空間探索のサンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

出力ファイル

+
+

ColorMap.txt

+

各メッシュでの候補パラメータと、その時の R-factor が記載されたファイルです。 +入力ファイルの [solver] - [param] セクションにある、 +string_list で定義された変数の順番でメッシュデータは記載され、 +最後に R-factor の値が記載されます。

+

以下、出力例です。

+
6.000000 6.000000 0.047852
+6.000000 5.750000 0.055011
+6.000000 5.500000 0.053190
+6.000000 5.250000 0.038905
+6.000000 5.000000 0.047674
+6.000000 4.750000 0.065919
+6.000000 4.500000 0.053675
+6.000000 4.250000 0.061261
+6.000000 4.000000 0.069351
+6.000000 3.750000 0.071868
+...
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/algorithm/minsearch.html b/manual/v2.2.0/ja/algorithm/minsearch.html new file mode 100644 index 00000000..99444e5f --- /dev/null +++ b/manual/v2.2.0/ja/algorithm/minsearch.html @@ -0,0 +1,175 @@ + + + + + + + + Nelder-Mead 法 minsearch — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

Nelder-Mead 法 minsearch

+

minsearch は Nelder-Mead 法 (a.k.a. downhill simplex 法) によって最適化を行います。 +Nelder-Mead 法では、 パラメータ空間の次元を \(D\) として、 \(D+1\) 個の座標点の組を、各点での目的関数の値に応じて系統的に動かすことで最適解を探索します。

+

重要なハイパーパラメータとして、座標の初期値があります。 +局所最適解にトラップされるという問題があるので、初期値を変えた計算を何回か繰り返して結果を確認することをおすすめします。

+

2DMATは、SciPy の scipy.optimize.minimize(method="Nelder-Mead") 関数を用いています。 +詳しくは 公式ドキュメント をご参照ください。

+
+

前準備

+

あらかじめ scipy をインストールしておく必要があります。

+
python3 -m pip install scipy
+
+
+
+
+

入力パラメータ

+

サブセクション param と minimize を持ちます。

+
+

[param] セクション

+
    +

  • initial_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。

    +
    • +

  • unit_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +
    +
    説明: 各パラメータの単位。

    探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 +簡易的な無次元化・正規化を行います。 +定義しなかった場合にはすべての次元で 1.0 となります。

    +
    +
    +
    • +

  • min_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +
    +
    説明: パラメータが取りうる最小値。

    最適化中にこの値を下回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

    +
    +
    +
    • +

  • max_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +
    +
    説明: パラメータが取りうる最大値。

    最適化中にこの値を上回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

    +
    +
    +
    • +
+
+
+

[minimize] セクション

+

Nelder-Mead 法のハイパーパラメータを設定します。 +詳細は scipy.optimize.minimize のドキュメントを参照してください。

+
    +

  • initial_scale_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: Nelder-Mead 法の初期 simplex を作るために、初期値からずらす差分。 +initial_list と、 initial_list に initial_scale_list の成分ひとつを足してできるdimension 個の点を 合わせたものが initial_simplex として使われます。 +定義しなかった場合、各次元に 0.25 が設定されます。

    +
    • +

  • xatol

    +

    形式: 実数型 (default: 1e-4)

    +

    説明: Nelder-Mead 法の収束判定に使うパラメータ

    +
    • +

  • fatol

    +

    形式: 実数型 (default: 1e-4)

    +

    説明: Nelder-Mead 法の収束判定に使うパラメータ

    +
    • +

  • maxiter

    +

    形式: 整数 (default: 10000)

    +

    説明: Nelder-Mead 法の反復回数の最大値

    +
    • +

  • maxfev

    +

    形式: 整数 (default: 100000)

    +

    説明: 目的関数を評価する回数の最大値

    +
    • +
+
+
+
+

出力ファイル

+
+

SimplexData.txt

+

最小値を求める途中経過に関する情報を出力します。 +1行目はヘッダー、2行目以降にstep, 入力ファイルの [solver] - [param] セクションにある、 +string_list で定義された変数の値、最後に関数の値が出力されます。

+

以下、出力例です。

+
#step z1 z2 z3 R-factor
+0 5.25 4.25 3.5 0.015199251773721183
+1 5.25 4.25 3.5 0.015199251773721183
+2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375
+3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261
+4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+
+
+
+
+

res.txt

+

最終的に得られた目的関数の値とその時のパラメータの値を記載しています。 +最初に目的関数が、 +その後は入力ファイルの [solver] - [param] セクションにある、 +string_list で定義された変数の値が順に記載されます。

+

以下、出力例です。

+
fx = 7.382680568652868e-06
+z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/algorithm/pamc.html b/manual/v2.2.0/ja/algorithm/pamc.html new file mode 100644 index 00000000..0ce184b5 --- /dev/null +++ b/manual/v2.2.0/ja/algorithm/pamc.html @@ -0,0 +1,437 @@ + + + + + + + + ポピュレーションアニーリングモンテカルロ法 pamc — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

ポピュレーションアニーリングモンテカルロ法 pamc

+

pamc はポピュレーションアニーリングモンテカルロ法を用いてパラメータ探索を行う Algorithm です。

+
+

前準備

+

MPI 並列をする場合にはあらかじめ mpi4py をインストールしておく必要があります。:

+
python3 -m pip install mpi4py
+
+
+
+
+

入力パラメータ

+

サブセクション param と pamc を持ちます。

+
+

[param] セクション

+

探索空間を定義します。 +mesh_path キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。

+
    +

  • 連続空間

    +
      +

    • initial_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +

      説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。

      +
      • +

    • unit_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: 各パラメータの単位。

      探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 +簡易的な無次元化・正規化を行います。 +定義しなかった場合にはすべての次元で 1.0 となります。

      +
      +
      +
      • +

    • min_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最小値。

      モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +

    • max_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最大値。

      モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +
    +
    • +

  • 離散空間

    +
      +

    • mesh_path

      +

      形式: ファイルパス

      +

      説明: メッシュ定義ファイル。

      +
      • +

    • neighborlist_path

      +

      形式: ファイルパス

      +

      説明: 近傍リスト定義ファイル。

      +
      • +
    +
    • +
+
+
+

[pamc] セクション

+
    +

  • numsteps

    +

    形式: 整数値。

    +

    説明: モンテカルロ更新を行う総回数。

    +
    • +

  • numsteps_annealing

    +

    形式: 整数値。

    +

    説明: 「温度」を下げる頻度。この回数モンテカルロ更新を行った後に温度が下がります。

    +
    • +

  • numT

    +

    形式: 整数値。

    +

    説明: 「温度」点の数。

    +
    • +

  • Tmin

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最小値。

    +
    • +

  • Tmax

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最大値。

    +
    • +

  • bmin

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最小値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • bmax

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最大値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • Tlogspace

    +

    形式: 真偽値。 (default: true)

    +
    +
    説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。

    true のときは対数空間で等分割します。

    +
    +
    +
    • +

  • nreplica_per_proc

    +

    形式: 整数。 (default: 1)

    +

    説明: ひとつのMPI プロセスが担当するレプリカの数。

    +
    • +

  • resampling_interval

    +

    形式: 整数。 (default: 1)

    +

    説明: レプリカのリサンプリングを行う頻度。この回数だけ温度降下を行った後にリサンプリングが行われます。

    +
    • +

  • fix_num_replicas

    +

    形式: 真偽値。 (default: true)

    +

    説明: リサンプリングの際、レプリカ数を固定するかどうか。

    +
    • +
+
+

ステップ数について

+

numsteps, numsteps_annealing, numT の3つのうち、どれか2つを同時に指定してください。 +残りの1つは自動的に決定されます。

+
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス（実際には使用されません）、 +2列目以降は探索空間の座標を指定します。

+

以下、サンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

近傍リスト定義ファイル

+

離散空間をモンテカルロ法で探索する場合、各点 \(i\) ごとに次に移動できる点 \(j\) を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。

+

1列目に始点の番号 \(i\) を記載し、 +2列目以降に \(i\) から移動できる終点 \(j\) を列挙します。

+

近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール py2dmat_neighborlist が提供されています。 +詳細は 関連ツール を参照してください。

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

出力ファイル

+
+

RANK/trial_T#.txt

+

各温度点(#) ごと、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの逆温度、4列目に目的関数の値、5列目からパラメータが記載されます。 +最後の2列はそれぞれレプリカの重み (Neal-Jarzynski weight) と祖先（計算開始時のレプリカ番号）です。

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/trial.txt

+

trial_T#.txt をすべてまとめたものです。

+
+
+

RANK/result_T#.txt

+

各温度点、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +trial.txt と同一の書式です。

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/result.txt

+

result_T#.txt をすべてまとめたものです。

+
+
+

best_result.txt

+

サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

fx.txt

+

各温度ごとに、全レプリカの情報をまとめたものです。 +1列目は逆温度が、2列目と3列目には目的関数の期待値およびその標準誤差が、4列目にはレプリカの総数が、5列目には規格化因子（分配関数）の比の対数

+
+\[\log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)}\]
+

が、6列目にはモンテカルロ更新の採択率が出力されます。 +ここで \(\beta_0\) は計算している \(\beta\) の最小値です。

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804
+0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058
+0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004
+...
+
+
+
+
+
+

アルゴリズム解説

+
+

問題と目的

+

分布パラメータ \(\beta_i\) のもとでの配位 \(x\) の重みを +\(f_i(x)\) と書くと（例えばボルツマン因子 \(f_i(x) = \exp\left[-\beta_i E(x)\right]\)）、 +\(A\) の期待値は

+
+\[\langle A\rangle_i += \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} += \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) += \int \mathrm{d}xA(x)\tilde{f}_i(x)\]
+

とかけます。 +ここで \(Z = \int \mathrm{d} x f_i(x)\) は規格化因子（分配関数）で、 \(\tilde{f}(x) = f(x)/Z\) は配位 \(x\) の確率密度です。

+

目的は複数の分布パラメータについてこの期待値および規格化因子（の比）を数値的に求めることです。

+
+
+

Annealed Importance Sampling (AIS) [1]

+

次の同時確率分布

+
+\[\tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0)\]
+

を満たす点列 \(\{x_i\}\) を考えます。ここで

+
+\[\tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)}\]
+

であり、 \(T_i(x, x')\) は \(\beta_i\) のもとでの配位 \(x\) +から \(x'\) への遷移確率で、釣り合い条件

+
+\[\int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x')\]
+

を満たすようにとります（つまりは普通のMCMCにおける遷移確率行列）。

+
+\[\int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) += \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) += 1\]
+

となるので、 \(\tilde{f}_n(x_n)\) は +\(\tilde{f}(x_0, x_1, \dots, x_n)\) の周辺分布

+
+\[\tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n)\]
+

です。 +これを利用すると、 \(\tilde{f}_n\) における平均値 \(\langle A \rangle_n\) は拡張した配位の重み付き平均として

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&\equiv +\int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) +\end{split}\end{split}\]
+

と表せます。

+

さて、残念ながら \(\tilde{f}(x_0, x_1, \dots, x_n)\) +に従うような点列を直接生成することは困難です。そこでもっと簡単に、

+
    +

  1. 確率 \(\tilde{f}_0(x)\) に従う \(x_0\) を生成する

    +
      +

    • 例えば MCMC を利用する

      • +
    +
    2. +

  2. \(x_i\) から \(T_{i+1}(x_i, x_{i+1})\) によって \(x_{i+1}\) を生成する

    +
      +

    • \(T_{i+1}\) は釣り合い条件を満たすような遷移確率行列なので、普通にMCMCを行えば良い

      • +
    +
    3. +
+

という流れに従って点列 \(\{x_i\}\) を生成すると、これは同時確率分布

+
+\[\tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n)\]
+

に従います。これを利用すると期待値 \(\langle A \rangle_n\) は

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ +&= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} +\end{split}\end{split}\]
+

と評価できます (reweighting method)。 +\(\tilde{f}\) と \(\tilde{g}\) との比は、

+
+\[\begin{split}\begin{split} +\frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\frac{f_n(x_n)}{f_0(x_0)} +\prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ +&\equiv +\frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n) +\end{split}\end{split}\]
+

とかけるので、期待値は

+
+\[\langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} += \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n}\]
+

となります。 +規格化因子の比 \(Z_n/Z_0\) は \(\langle 1 \rangle_n = 1\) を用いると

+
+\[\frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n}\]
+

と評価できるので、 \(A\) の期待値は

+
+\[\langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}}\]
+

という、重み付き平均の形で評価できます。 +この重み \(w_n\) を Neal-Jarzynski 重みと呼びます。

+
+
+

population annealing (PA) [2]

+

AIS を使うと各 \(\beta\) に対する期待値を重み付き平均という形で計算できますが、 +\(\beta\) の幅が大きくなると重み \(w\) の分散が大きくなってしまいます。 +そのため、適当な周期で確率 \(p^{(k)} = w^{(k)} / \sum_k w^{(k)}\) に従いレプリカをリサンプリングし、 +レプリカに割当られた重みをリセット \((w=1)\) します。

+

PAMC のアルゴリズムは次の擬似コードで示されます:

+
for k in range(K):
+    w[0, k] = 1.0
+    x[0, k] = draw_from(β[0])
+for i in range(1, N):
+    for k in range(K):
+        w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) )
+    if i % interval == 0:
+        x[i, :] = resample(x[i, :], w[i, :])
+        w[i, :] = 1.0
+    for k in range(K):
+        x[i, k] = transfer(x[i-1, k], β[i])
+    a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:])
+
+
+

リサンプリング手法として、レプリカ数を固定する方法[2]と固定しない方法[3]の2通りがあります。

+
+
+

参考文献

+

[1] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[2] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[3] J. Machta, PRE 82, 026704 (2010).

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/contact.html b/manual/v2.2.0/ja/contact.html new file mode 100644 index 00000000..0c8914ac --- /dev/null +++ b/manual/v2.2.0/ja/contact.html @@ -0,0 +1,74 @@ + + + + + + + + お問い合わせ — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + +
+ + +
+

お問い合わせ

+

2DMAT に関するお問い合わせはこちらにお寄せください。

+
    +

  • バグ報告

    +

    2DMAT のバグ関連の報告は GitHubのIssues で受け付けています。

    +

    バグを早期に解決するため、報告時には次のガイドラインに従ってください。

    +
    +
      +

    • 使用している 2DMAT のバージョンを指定してください。

      • +

    • インストールに問題がある場合には、使用しているオペレーティングシステムとコンパイラの情報についてお知らせください。

      • +

    • 実行に問題が生じた場合は、実行に使用した入力ファイルとその出力を記載してください。

      • +
    +
    +
    • +

  • その他

    +

    研究に関連するトピックなどGitHubのIssuesで相談しづらいことを問い合わせる際には、以下の連絡先にコンタクトをしてください。

    +

    E-mail: 2dmat-dev__at__issp.u-tokyo.ac.jp (_at_を@に変更してください)

    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/customize/algorithm.html b/manual/v2.2.0/ja/customize/algorithm.html new file mode 100644 index 00000000..8bee048a --- /dev/null +++ b/manual/v2.2.0/ja/customize/algorithm.html @@ -0,0 +1,252 @@ + + + + + + + + Algorithm の定義 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

Algorithm の定義

+

Algorithm クラスは py2dmat.algorithm.AlgorithmBase を継承したクラスとして定義します。

+
import py2dmat
+
+class Algorithm(py2dmat.algorithm.AlgorithmBase):
+    pass
+
+
+
+

AlgorithmBase

+

AlgorithmBase クラスは次のメソッドを提供します。

+
    +

  • __init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)

    +
    +
      +

    • info から Algorithm 共通の入力パラメータを読み取り、次のインスタンス変数を設定します。

      +
      +
        +

      • self.mpicomm: Optional[MPI.Comm] : MPI.COMM_WORLD

        +
        +
          +

        • mpi4py の import に失敗した場合、 None が設定されます

          • +
        +
        +
        • +

      • self.mpisize: int : MPIプロセス数

        +
        +
          +

        • mpi4py の import に失敗した場合、 1 が設定されます

          • +
        +
        +
        • +

      • self.mpirank: int : MPIランク

        +
        +
          +

        • mpi4py の import に失敗した場合、 0 が設定されます

          • +
        +
        +
        • +

      • self.rng: np.random.Generator : 擬似乱数生成器

        +
        +
        +
        +
        • +

      • self.dimension: int : 探索パラメータ空間の次元

        • +

      • self.label_list: List[str] : 各パラメータの名前

        • +

      • self.root_dir: pathlib.Path : ルートディレクトリ

        +
        +
          +

        • info.base["root_dir"]

          • +
        +
        +
        • +

      • self.output_dir: pathlib.Path : 出力ファイルを書き出すディレクトリ

        +
        +
          +

        • info.base["root_dir"]

          • +
        +
        +
        • +

      • self.proc_dir: pathlib.Path : プロセスごとの作業用ディレクトリ

        +
        +
          +

        • self.output_dir / str(self.mpirank)

          • +

        • ディレクトリが存在しない場合、自動的に作成されます

          • +

        • 各プロセスで最適化アルゴリズムはこのディレクトリで実行されます

          • +
        +
        +
        • +

      • self.timer: Dict[str, Dict] : 実行時間を保存するための辞書

        +
        +
          +

        • 空の辞書が3つ、 "prepare", "run", "post" という名前で定義されます

          • +
        +
        +
        • +
      +
      +
      • +
    +
    +
    • +

  • prepare(self) -> None

    +
    +
      +

    • 最適化アルゴリズムの前処理をします

      • +

    • self.run() の前に実行する必要があります

      • +
    +
    +
    • +

  • run(self) -> None

    +
    +
      +

    • 最適化アルゴリズムを実行します

      • +

    • self.proc_dir に移動し、 self._run() を実行した後、元のディレクトリに戻ります

      • +
    +
    +
    • +

  • post(self) -> None

    +
    +
      +

    • 最適化結果のファイル出力など、後処理を行います

      • +

    • self.output_dir に移動し、 self._post() を実行した後、元のディレクトリに戻ります

      • +

    • self.run() のあとに実行する必要があります

      • +
    +
    +
    • +

  • main(self) -> None

    +
    +
      +

    • prepare, run, post を順番に実行します

      • +

    • それぞれの関数でかかった時間を計測し、結果をファイル出力します

      • +
    +
    +
    • +

  • _read_param(self, info: py2dmat.Info) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

    +
    +
      +

    • 連続なパラメータ空間を定義するためのヘルパーメソッドです

      • +

    • info.algorithm["param"] から探索パラメータの初期値や最小値、最大値、単位を取得します

      • +

    • 詳細は min_search の入力ファイル を参照してください

      • +
    +
    +
    • +

  • _mesh_grid(self, info: py2dmat.Info, split: bool = False) -> Tuple[np.ndarray, np.ndarray]

    +
    +
      +

    • 離散的なパラメータ空間を定義するためのヘルパーメソッドです

      • +

    • info.algorithm["param"] を読み取り次を返します:

      +
      +
        +

      • D 次元の候補点 N 個からなる集合 (NxD 次元の行列として)

        • +

      • N 個の候補点のID(index)

        • +
      +
      +
      • +

    • split が True の場合、候補点集合は分割され各MPI ランクに配られます

      • +

    • 詳細は mapper の入力ファイル を参照してください

      • +
    +
    +
    • +
+
+
+

Algorithm

+

Algorithm は少なくとも次のメソッドを定義しなければなりません。

+
    +

  • __init__(self, info: py2dmat.Info, runner: py2dmat.Runner = None)

    +
    +
      +

    • 引数はそのまま基底クラスのコンストラクタに転送してください

      +
      +
        +

      • super().__init__(info=info, runner=runner)

        • +
      +
      +
      • +

    • 入力パラメータである info から必要な設定を読み取り、保存してください

      • +
    +
    +
    • +

  • _prepare(self) -> None

    +
    +
      +

    • 最適化アルゴリズムの前処理を記述します

      • +
    +
    +
    • +

  • _run(self) -> None

    +
    +
      +

    • 最適化アルゴリズムを記述します

      • +

    • 探索パラメータ x から対応する目的関数の値 f(x) を得る方法

      +
      message = py2dmat.Message(x, step, set)
+fx = self.runner.submit(message)
+
      +
      +
      • +
    +
    +
    • +

  • _post(self) -> None

    +
    +
      +

    • 最適化アルゴリズムの後処理を記述します

      • +
    +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/customize/common.html b/manual/v2.2.0/ja/customize/common.html new file mode 100644 index 00000000..5a722bb4 --- /dev/null +++ b/manual/v2.2.0/ja/customize/common.html @@ -0,0 +1,185 @@ + + + + + + + + 共通事項 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

共通事項

+

Solver と Algorithm に共通する事柄について説明します。

+
+

py2dmat.Info

+

入力パラメータを扱うためのクラスです。 +インスタンス変数として次の4つの dict を持ちます。

+
    +

  • base

    +
    +
      +

    • ディレクトリ情報など、プログラム全体で共通するパラメータ

      • +
    +
    +
    • +

  • solver

    +
    +
      +

    • Solver が用いる入力パラメータ

      • +
    +
    +
    • +

  • algorithm

    +
    +
      +

    • Algorithm が用いる入力パラメータ

      • +
    +
    +
    • +

  • runner

    +
    +
      +

    • Runner が用いる入力パラメータ

      • +
    +
    +
    • +
+

Info は base, solver, algorithm, runner の4つのキーを持つような dict を渡して初期化出来ます。

+
    +

  • base について

    +
    +
      +

    • 要素として計算のルートディレクトリ root_dir と出力のルートディレクトリ output_dir が自動で設定されます

      • +

    • ルートディレクトリ root_dir

      +
      +
        +

      • 絶対パスに変換されたものがあらためて root_dir に設定されます

        • +

      • 先頭の ~ はホームディレクトリに展開されます

        • +

      • デフォルトはカレントディレクトリ "." です

        • +

      • 具体的には次のコードが実行されます

        +
        p = pathlib.Path(base.get("root_dir", "."))
+base["root_dir"] = p.expanduser().absolute()
+
        +
        +
        • +
      +
      +
      • +

    • 出力ディレクトリ output_dir

      +
      +
        +

      • 先頭の ~ はホームディレクトリに展開されます

        • +

      • 絶対パスが設定されていた場合はそのまま設定されます

        • +

      • 相対パスが設定されていた場合、 root_dir を起点とした相対パスとして解釈されます

        • +

      • デフォルトは "." 、つまり root_dir と同一ディレクトリです

        • +

      • 具体的には次のコードが実行されます

        +
        p = pathlib.Path(base.get("work_dir", "."))
+p = p.expanduser()
+base["work_dir"] = base["root_dir"] / p
+
        +
        +
        • +
      +
      +
      • +
    +
    +
    • +
+
+
+

py2dmat.Message

+

Algorithm から Runner を介して Solver に渡されるクラスです。 +次の3つのインスタンス変数を持ちます。

+
    +

  • x: np.ndarray

    +
    +
      +

    • 探索中のパラメータ座標

      • +
    +
    +
    • +

  • step: int

    +
    +
      +

    • 何個目のパラメータであるか

      • +

    • 例えば exchange ではステップ数で、 mapper ではパラメータの通し番号。

      • +
    +
    +
    • +

  • set: int

    +
    +
      +

    • 何巡目のパラメータであるか

      • +

    • 例えば min_search では最適化（1巡目）後にステップごとの最適値を再計算します（2巡目）。

      • +
    +
    +
    • +
+
+
+

py2dmat.Runner

+

Algorithm と Solver とをつなげるためのクラスです。 +コンストラクタ引数として Solver のインスタンスと Info のインスタンス、パラメータの変換ルーチン mapping : Callable[[np.ndarray], np.ndarray] を取ります。

+

submit(self, message: py2dmat.Message) -> float メソッドでソルバーを実行し、結果を返します。 +探索パラメータを x として、 目的関数 fx = f(x) を得たい場合は以下のようにします

+
message = py2dmat.Message(x, step, set)
+fx = runner.submit(message)
+
+
+

submit メソッドは mapping を用いて、探索アルゴリズムのパラメータ x から実際にソルバーが使う入力 y = mapping(x) を得ます。 +mapping を省略した場合 (None を渡した場合)、変換ルーチンとしてアフィン写像 \(y=Ax+b\) が用いられます (py2dmat.util.mapping.Affine(A,b))。 +A, b の要素は info で与えられます。 +その他、 Runner で使われる info の詳細は 入力ファイル を参照してください。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/customize/index.html b/manual/v2.2.0/ja/customize/index.html new file mode 100644 index 00000000..b353dd76 --- /dev/null +++ b/manual/v2.2.0/ja/customize/index.html @@ -0,0 +1,72 @@ + + + + + + + + (開発者向け)ユーザー定義アルゴリズム・ソルバー — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

(開発者向け)ユーザー定義アルゴリズム・ソルバー

+

本ソフトウェアは、順問題のためのソルバー Solver と最適化のためのアルゴリズム Algorithm を組み合わせることで全体の逆問題を解きます。 +Solver と Algorithm はすでに定義済みのものがいくつかありますが、これらを自分で定義することで、適用範囲を広げられます。 +本章では、 Solver や Algorithm を定義する方法およびこれらを使用する方法を解説します。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/customize/solver.html b/manual/v2.2.0/ja/customize/solver.html new file mode 100644 index 00000000..e4dfbcd4 --- /dev/null +++ b/manual/v2.2.0/ja/customize/solver.html @@ -0,0 +1,162 @@ + + + + + + + + Solver の定義 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

Solver の定義

+

Solver クラスは py2dmat.solver.SolverBase を継承したクラスとして定義します。:

+
import py2dmat
+
+class Solver(py2dmat.solver.SolverBase):
+    pass
+
+
+

このクラスは少なくとも次のメソッドを定義しなければなりません。

+
    +

  • __init__(self, info: py2dmat.Info)

    +
    +
      +

    • 必ず基底クラスのコンストラクタを呼び出してください

      +
      +
        +

      • super().__init__(info)

        • +
      +
      +
      • +

    • 基底クラスのコンストラクタでは次のインスタンス変数が設定されます

      +
      +
        +

      • self.root_dir: pathlib.Path : ルートディレクトリ

        +
        +
          +

        • info.base["root_dir"]

          • +
        +
        +
        • +

      • self.output_dir: pathlib.Path : 出力ファイルを書き出すディレクトリ

        +
        +
          +

        • info.base["output_dir"]

          • +
        +
        +
        • +

      • self.proc_dir: pathlib.Path : プロセスごとの作業用ディレクトリ

        +
        +
          +

        • self.output_dir / str(self.mpirank) で初期化されます

          • +
        +
        +
        • +

      • self.work_dir: pathlib.Path : ソルバーが実行されるディレクトリ

        +
        +
          +

        • self.proc_dir で初期化されます

          • +
        +
        +
        • +
      +
      +
      • +

    • 入力パラメータである info から必要な設定を読み取り、保存してください

      • +
    +
    +
    • +

  • prepare(self, message: py2dmat.Message) -> None

    +
    +
      +

    • ソルバーが実行される前によびだされます

      • +

    • message には入力パラメータが含まれるので、ソルバーが利用できる形に変換してください

      +
      +
        +

      • 例：ソルバーの入力ファイルを生成する

        • +
      +
      +
      • +
    +
    +
    • +

  • run(self, nprocs: int = 1, nthreads: int = 1) -> None

    +
    +
      +

    • ソルバーを実行します

      • +

    • 後ほど get_results で目的関数の値を読み取れるようにしておいてください

      +
      +
        +

      • 例：出力結果をインスタンス変数に保存しておく

        • +

      • 例：実行結果をファイルに保存しておく

        • +
      +
      +
      • +
    +
    +
    • +

  • get_results(self) -> float

    +
    +
      +

    • ソルバーが実行されたあとに呼び出されます

      • +

    • ソルバーの実行結果を返却してください

      +
      +
        +

      • 例：ソルバーの出力ファイルから実行結果を読み取る

        • +
      +
      +
      • +
    +
    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/customize/usage.html b/manual/v2.2.0/ja/customize/usage.html new file mode 100644 index 00000000..708e821e --- /dev/null +++ b/manual/v2.2.0/ja/customize/usage.html @@ -0,0 +1,105 @@ + + + + + + + + 実行方法 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

実行方法

+

次のようなフローで最適化問題を実行できます。 +プログラム例にあるコメントの番号はフローの番号に対応しています。

+
    +

  1. ユーザ定義クラスを作成する

    +
      +

    • もちろん、 py2dmat で定義済みのクラスも利用可能です

      • +
    +
    2. +

  2. 入力パラメータ info: py2dmat.Info を作成する

    +
      +

    • プログラム例では入力ファイルとしてTOML を利用していますが、辞書をつくれれば何でも構いません

      • +
    +
    3. +

  3. solver: Solver, runner: py2dmat.Runner, algorithm: Algorithm を作成する

    4. +

  4. algorithm.main() を実行する

    5. +
+

プログラム例

+
import sys
+import tomli
+import py2dmat
+
+# (1)
+class Solver(py2dmat.solver.SolverBase):
+    # Define your solver
+    pass
+
+class Algorithm(py2dmat.algorithm.AlgorithmBase):
+    # Define your algorithm
+    pass
+
+# (2)
+with open(sys.argv[1]) as f:
+    inp = tomli.load(f)
+info = py2dmat.Info(inp)
+
+# (3)
+solver = Solver(info)
+runner = py2dmat.Runner(solver, info)
+algorithm = Algorithm(info, runner)
+
+# (4)
+algorithm.main()
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/genindex.html b/manual/v2.2.0/ja/genindex.html new file mode 100644 index 00000000..45c1fa4d --- /dev/null +++ b/manual/v2.2.0/ja/genindex.html @@ -0,0 +1,53 @@ + + + + + + + 索引 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + +
+ + + +

索引

+ +
+ +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/index.html b/manual/v2.2.0/ja/index.html new file mode 100644 index 00000000..0b13465c --- /dev/null +++ b/manual/v2.2.0/ja/index.html @@ -0,0 +1,129 @@ + + + + + + + + Welcome to 2DMAT's documentation! — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + +
+ + +
+

Welcome to 2DMAT's documentation!

+
+

Contents:

+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/input.html b/manual/v2.2.0/ja/input.html new file mode 100644 index 00000000..e02dca49 --- /dev/null +++ b/manual/v2.2.0/ja/input.html @@ -0,0 +1,315 @@ + + + + + + + + 入力ファイル — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

入力ファイル

+

py2dmat は入力ファイルの形式に TOML を採用しています。 +入力ファイルは次の6つのセクションから構成されます。

+
    +

  • base

    +
      +

    • py2dmat 全体のパラメータを指定します。

      • +
    +
    • +

  • solver

    +
      +

    • Solver のパラメータを指定します。

      • +
    +
    • +

  • algorithm

    +
      +

    • Algorithm のパラメータを指定します。

      • +
    +
    • +

  • runner

    +
      +

    • Runner のパラメータを指定します。

      • +
    +
    • +

  • mapping

    +
      +

    • Algorithm で探索しているパラメータから Solver で使うパラメータへの写像を定義します。

      • +
    +
    • +

  • log

    +
      +

    • solver 呼び出しのlogging に関して設定します。

      • +
    +
    • +
+
+

[base] セクション

+
    +

  • dimension

    +

    形式: 整数型

    +

    説明: 探索空間の次元（探索するパラメータの数）

    +
    • +

  • root_dir

    +

    形式: string型 (default: プログラム実行時のディレクトリ)

    +
    +
    説明: プログラムを実行する一番上のディレクトリ。

    入力ファイルなどのパスはすべて root_dir を起点とします。

    +
    +
    +
    • +

  • output_dir

    +

    形式: string型 (default: プログラム実行時のディレクトリ)

    +

    説明: プログラムの実行結果を出力するディレクトリ名

    +
    • +
+
+
+

[solver] セクション

+

name でソルバーの種類を決定します。各パラメータはソルバーごとに定義されています。

+
    +

  • name

    +

    形式: string型

    +

    説明: ソルバーの名前。以下のソルバーが用意されています。

    +
    +
      +

    • sim-trhepd-rheed : 反射高速(陽)電子回折(RHEED, TRHEPD)の強度計算をするためのソルバー sim-trhepd-rheed

      • +

    • analytical : 解析解を与えるソルバー (主にテストに利用)

      • +
    +
    +
    • +

  • dimension

    +

    形式: 整数型 (default: base.dimension)

    +

    説明: ソルバーが受け取る入力パラメータの数。

    +
    • +
+

各種ソルバーの詳細および入出力ファイルは 順問題ソルバー を参照してください。

+
+
+

[algorithm] セクション

+

name でアルゴリズムの種類を決定します。各パラメータはアルゴリズムごとに定義されています。

+
    +

  • name

    +

    形式: string型

    +

    説明: アルゴリズムの名前。以下のアルゴリズムが用意されています。

    +
    +
      +

    • minsearch : Nelder-Mead法による最小値探索

      • +

    • mapper : グリッド探索

      • +

    • exchange : レプリカ交換モンテカルロ

      • +

    • bayes : ベイズ最適化

      • +
    +
    +
    • +

  • seed

    +

    形式: 整数値。

    +
    +
    説明: 初期値のランダム生成やモンテカルロ更新などで用いる擬似乱数生成器の種を指定します。

    各MPIプロセスに対して、 seed + mpi_rank * seed_delta の値が実際の種として用いられます。 +省略した場合は Numpy の規定の方法 で初期化されます。

    +
    +
    +
    • +

  • seed_delta

    +

    形式: 整数値。 (default: 314159)

    +
    +
    説明: 疑似乱数生成器の種について、MPI プロセスごとの値を計算する際に用いられます。

    詳しくは seed を参照してください。

    +
    +
    +
    • +
+

各種アルゴリズムの詳細および入出力ファイルは 探索アルゴリズム を参照してください。

+
+
+

[runner] セクション

+

Algorithm と Solver を橋渡しする要素である Runner の設定を記述します。 +サブセクションとして mapping 、 limitation 、 log を持ちます。

+
+
+

[mapping] セクション

+

Algorithm で探索している \(N\) 次元のパラメータ \(x\) から Solver で使う \(M\) 次元のパラメータ \(y\) への写像を定義します。 +\(N \ne M\) となる場合には、 solver セクションにも dimension パラメータを指定してください。

+

現在はアフィン写像（線形写像+平行移動） \(y = Ax+b\) が利用可能です。

+
    +

  • A

    +

    形式: リストのリスト、あるいは文字列 (default: [])

    +
    +
    説明: \(N \times M\) の変換行列 \(A\) 。空のリストを渡した場合、単位行列とみなされます。

    文字列として与える場合はそのまま行列の要素を空白および改行で区切って並べてください。

    +
    +
    +
    • +

  • b

    +

    形式: リスト、あるいは文字列 (default: [])

    +
    +
    説明: \(M\) 次元の並進移動ベクトル \(b\) 。空のリストを渡した場合、ゼロベクトルとみなされます。

    文字列として与える場合はそのままベクトルの要素を空白区切りで並べてください。

    +
    +
    +
    • +
+

行列の指定方法について、例えば、

+
A = [[1,1], [0,1]]
+
+
+

と

+
A = """
+1 1
+0 1
+"""
+
+
+

はともに

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right)\end{split}\]
+

を表します。

+
+
+

[limitation] セクション

+

Algorithm で探索している \(N\) 次元のパラメータ \(x\) に、制約条件を課すことが出来ます。 +Algorithm ごとに定義する探索範囲（例：exchange の min_list や max_list ） に加えて課すことが出来ます。 +現在は \(M\) 行 \(N\) 列の行列:math:A と \(M\) 次元の縦ベクトル:math:b から定義される \(Ax+b>0\) の制約式が利用可能です。具体的に

+
+\[\begin{split}A_{1,1} x_{1} + A_{1,2} x_{2} + &... + A_{1,N} x_{N} + b_{1} > 0\\ +A_{2,1} x_{1} + A_{2,2} x_{2} + &... + A_{2,N} x_{N} + b_{2} > 0\\ +&...\\ +A_{M,1} x_{1} + A_{M,2} x_{2} + &... + A_{M,N} x_{N} + b_{M} > 0\end{split}\]
+

という制約をかけることが出来ます。 +ここで \(M\) は制約式の個数（任意）となります。

+
    +

  • co_a

    +

    形式: リストのリスト、あるいは文字列 (default: [])

    +

    説明: 制約式の行列 \(A\) を設定します。

    +
    +

    行数は制約式数 \(M\) 列数は探索変数の数 \(N\) である必要があります。

    +

    co_b を同時に定義する必要があります。

    +
    +
    • +

  • co_b

    +

    形式: リストのリスト、あるいは文字列 (default: [])

    +

    説明: 制約式の縦ベクトル \(b\) を設定します。

    +
    +

    次元数が制約式数 \(M\) の縦ベクトルを設定する必要があります。

    +

    co_a を同時に定義する必要があります。

    +
    +
    • +
+

行列の指定方法について、[mapping] セクションと同様で、例えば、

+
A = [[1,1], [0,1]]
+
+
+

と

+
A = """
+1 1
+0 1
+"""
+
+
+

はともに

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right)\end{split}\]
+

を表します。また、

+
co_b = [[0], [-1]]
+
+
+

と

+
co_b = """0 -1"""
+
+
+

と

+
co_b = """
+0
+-1
+"""
+
+
+

はともに

+
+\[\begin{split}b = \left( +\begin{matrix} +0 \\ +-1 +\end{matrix} +\right)\end{split}\]
+

を表します。 +co_a と co_b のどちらも定義しない場合、制約式を課さずに探索します。

+
+
+

[log] セクション

+

solver 呼び出しのlogging に関する設定です。

+
    +

  • filename

    +

    形式: 文字列 (default: "runner.log")

    +

    説明: ログファイルの名前。

    +
    • +

  • interval

    +

    形式: 整数 (default: 0)

    +

    説明: solver を interval 回呼ぶ毎にログが書き出されます。0以下の場合、ログ書き出しは行われません。

    +
    • +

  • write_result

    +

    形式: 真偽値 (default: false)

    +

    説明: solver からの出力を記録するかどうか。

    +
    • +

  • write_input

    +

    形式: 真偽値 (default: false)

    +

    説明: solver への入力を記録するかどうか。

    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/introduction.html b/manual/v2.2.0/ja/introduction.html new file mode 100644 index 00000000..bae077a7 --- /dev/null +++ b/manual/v2.2.0/ja/introduction.html @@ -0,0 +1,136 @@ + + + + + + + + はじめに — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

はじめに

+
+

2DMATとは

+

2DMATは，順問題ソルバーに対して探索アルゴリズムを適用して最適解を探すためのフレームワークです. 順問題ソルバーはユーザー自身で定義することが可能です. +標準的な順問題ソルバーとしては2次元物質構造解析向け実験データ解析ソフトウェアが用意されています. 順問題ソルバーでは原子位置などをパラメータとし得られたデータと実験データとのずれを損失関数として与えます. +探索アルゴリズムを組み合わせ, この損失関数を最小化することで, 最適なパラメータを推定します. +現バージョンでは, 順問題ソルバーとして量子ビーム回折実験の全反射高速陽電子回折実験（Total-reflection high-energy positron diffraction ,TRHEPD，トレプト）[1, 2],sxrd[3], leed[4]に対応しており, +探索アルゴリズムはNelder-Mead法[5], グリッド型探索法[6], ベイズ最適化[7], レプリカ交換モンテカルロ法[8], ポピュレーションアニーリングモンテカルロ法[9, 10, 11]が実装されています. 今後は, 本フレームワークをもとにより多くの順問題ソルバーおよび探索アルゴリズムを実装していく予定です.

+

[1] レビューとして， Y．Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019); +兵頭俊夫，「全反射高速陽電子回折　(TRHEPD)による表面構造解析」，固体物理 53, 705 (2018).

+

[2] T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022).

+

[3] W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252 (2006) 5259.

+

[4] M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993).

+

[5] K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020).

+

[6] K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series,.

+

[7] Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022)

+

[8] K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996), R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986).

+

[9] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[10] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[11] J. Machta, Phys. Rev. E 82, 026704 (2010).

+
+
+

ライセンス

+
+
本ソフトウェアのプログラムパッケージおよびソースコード一式はGNU +General Public License version 3（GPL v3）に準じて配布されています。
+
+

Copyright (c) <2020-> The University of Tokyo. All rights reserved.

+

本ソフトウェアは2020年度 東京大学物性研究所 ソフトウェア高度化プロジェクトの支援を受け開発されました。 +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} +}

+
+
+

バージョン履歴

+
    +

  • 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は以下のメンバーで開発しています.

+
    +

  • v2.0.0 -

    +
      +

    • 本山 裕一 (東京大学 物性研究所)

      • +

    • 吉見 一慶 (東京大学 物性研究所)

      • +

    • 岩本 晴道 (鳥取大学 大学院工学研究科)

      • +

    • 星 健夫 (鳥取大学 大学院工学研究科)

      • +
    +
    • +

  • v0.1.0 -

    +
      +

    • 本山 裕一 (東京大学 物性研究所)

      • +

    • 吉見 一慶 (東京大学 物性研究所)

      • +

    • 星 健夫 (鳥取大学 大学院工学研究科)

      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/objects.inv b/manual/v2.2.0/ja/objects.inv new file mode 100644 index 00000000..326704ca Binary files /dev/null and b/manual/v2.2.0/ja/objects.inv differ diff --git a/manual/v2.2.0/ja/output.html b/manual/v2.2.0/ja/output.html new file mode 100644 index 00000000..df81fc06 --- /dev/null +++ b/manual/v2.2.0/ja/output.html @@ -0,0 +1,107 @@ + + + + + + + + 出力ファイル — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

出力ファイル

+

各種 Solver, Algorithm が出力するファイルについては、 順問題ソルバー および 探索アルゴリズム を参照してください。

+
+

共通ファイル

+
+

time.log

+

MPI のランク毎に計算にかかった総時間を出力します。 +各ランクのサブフォルダ以下に出力されます。 +計算の前処理にかかった時間、計算にかかった時間、計算の後処理にかかった時間について、 +prepare , run , post のセクションごとに記載されます。

+

以下、出力例です。

+
#prepare
+ total = 0.007259890999989693
+#run
+ total = 1.3493346729999303
+ - file_CM = 0.0009563499997966574
+ - submit = 1.3224223930001244
+#post
+ total = 0.000595873999941432
+
+
+
+
+

runner.log

+

MPI のランクごとに、ソルバー呼び出しに関するログ情報を出力します。 +各ランクのサブフォルダ以下に出力されます。 +入力で runner.log.interval パラメータが正の整数の時のみ出力されます。

+
    +

  • 1列目がソルバー呼び出しの通し番号、

    • +

  • 2列目が前回呼び出しからの経過時間、

    • +

  • 3列目が計算開始からの経過時間

    • +
+
# $1: num_calls
+# $2: elapsed_time_from_last_call
+# $3: elapsed_time_from_start
+
+1 0.0010826379999999691 0.0010826379999999691
+2 6.96760000000185e-05 0.0011523139999999876
+3 9.67080000000009e-05 0.0012490219999999885
+4 0.00011765699999999324 0.0013666789999999818
+5 4.965899999997969e-05 0.0014163379999999615
+6 8.666900000003919e-05 0.0015030070000000006
+   ...
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/search.html b/manual/v2.2.0/ja/search.html new file mode 100644 index 00000000..8da3e15c --- /dev/null +++ b/manual/v2.2.0/ja/search.html @@ -0,0 +1,81 @@ + + + + + + + 検索 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + + + + +
+ + +

検索

+ + + + +

+ 複数の単語を検索すると、次を含む一致のみが表示されます +     すべての用語。 +

+ + +
+ + + +
+ + + +
+ +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/searchindex.js b/manual/v2.2.0/ja/searchindex.js new file mode 100644 index 00000000..56d0dc7a --- /dev/null +++ b/manual/v2.2.0/ja/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"docnames": ["acknowledgement", "algorithm/bayes", "algorithm/exchange", "algorithm/index", "algorithm/mapper_mpi", "algorithm/minsearch", "algorithm/pamc", "contact", "customize/algorithm", "customize/common", "customize/index", "customize/solver", "customize/usage", "index", "input", "introduction", "output", "solver/analytical", "solver/index", "solver/leed", "solver/sim-trhepd-rheed", "solver/sxrd", "start", "tool", "tutorial/bayes", "tutorial/exchange", "tutorial/index", "tutorial/limitation", "tutorial/minsearch", "tutorial/mpi", "tutorial/pamc", "tutorial/sim_trhepd_rheed", "tutorial/solver_simple"], "filenames": ["acknowledgement.rst", "algorithm/bayes.rst", "algorithm/exchange.rst", "algorithm/index.rst", "algorithm/mapper_mpi.rst", "algorithm/minsearch.rst", "algorithm/pamc.rst", "contact.rst", "customize/algorithm.rst", "customize/common.rst", "customize/index.rst", "customize/solver.rst", "customize/usage.rst", "index.rst", "input.rst", "introduction.rst", "output.rst", "solver/analytical.rst", "solver/index.rst", "solver/leed.rst", "solver/sim-trhepd-rheed.rst", "solver/sxrd.rst", "start.rst", "tool.rst", "tutorial/bayes.rst", "tutorial/exchange.rst", "tutorial/index.rst", "tutorial/limitation.rst", "tutorial/minsearch.rst", "tutorial/mpi.rst", "tutorial/pamc.rst", "tutorial/sim_trhepd_rheed.rst", "tutorial/solver_simple.rst"], "titles": ["\u8b1d\u8f9e", "\u30d9\u30a4\u30ba\u6700\u9069\u5316 bayes", "\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 exchange", "\u63a2\u7d22\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0", "\u81ea\u660e\u4e26\u5217\u63a2\u7d22 mapper", "Nelder-Mead \u6cd5 minsearch", "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 pamc", "\u304a\u554f\u3044\u5408\u308f\u305b", "Algorithm \u306e\u5b9a\u7fa9", "\u5171\u901a\u4e8b\u9805", "(\u958b\u767a\u8005\u5411\u3051)\u30e6\u30fc\u30b6\u30fc\u5b9a\u7fa9\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u30fb\u30bd\u30eb\u30d0\u30fc", "Solver \u306e\u5b9a\u7fa9", "\u5b9f\u884c\u65b9\u6cd5", "Welcome to 2DMAT's documentation!", "\u5165\u529b\u30d5\u30a1\u30a4\u30eb", "\u306f\u3058\u3081\u306b", "\u51fa\u529b\u30d5\u30a1\u30a4\u30eb", "analytical \u30bd\u30eb\u30d0\u30fc", "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc", "leed \u30bd\u30eb\u30d0\u30fc", "sim-trhepd-rheed \u30bd\u30eb\u30d0\u30fc", "sxrd \u30bd\u30eb\u30d0\u30fc", "py2dmat \u306e\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb", "\u95a2\u9023\u30c4\u30fc\u30eb", "\u30d9\u30a4\u30ba\u6700\u9069\u5316", "\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22", "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb", "\u5236\u7d04\u5f0f\u3092\u9069\u7528\u3057\u305f\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22", "Nelder-Mead\u6cd5\u306b\u3088\u308b\u6700\u9069\u5316", "\u30b0\u30ea\u30c3\u30c9\u578b\u63a2\u7d22", "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u306b\u3088\u308b\u63a2\u7d22", "TRHEPD \u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc", "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc\u306e\u8ffd\u52a0"], "terms": {"\u30bd\u30d5\u30c8\u30a6\u30a7\u30a2": [0, 10, 15, 23, 24, 25, 26, 27, 28, 29, 30], "\u958b\u767a": [0, 13, 22, 26], "\u79d1\u7814": 0, "\u5e74\u5ea6": [0, 15], ")\u300c": 0, "\u8d85\u4e26\u5217": 0, "\u30de\u30b7\u30f3": 0, "\u7528\u3044": [0, 1, 2, 3, 4, 5, 6, 9, 14, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u8a08\u7b97": [0, 1, 2, 4, 5, 6, 9, 14, 16, 17, 18, 19, 20, 21, 23], "\u7d71\u8a08": [0, 30], "\u6e2c\u5b9a": 0, "\u6280\u8853": 0, "\u878d\u5408": 0, "\u304a\u3088\u3073": [0, 1, 6, 10, 14, 15, 16, 20, 23, 25, 27, 30, 31], "\u6771\u4eac": [0, 15], "\u5927\u5b66": [0, 15, 26], "\u7269\u6027": [0, 15], "\u7814\u7a76": [0, 7, 15], "\u9ad8\u5ea6": [0, 15], "\u30d7\u30ed\u30b8\u30a7\u30af\u30c8": [0, 15], "\u652f\u63f4": [0, 15], "\u53d7\u3051": [0, 2, 14, 15, 30], "\u307e\u3057": [0, 15, 20, 28], "\u8a2d\u8a08": 0, "\u5909\u6570": [0, 1, 4, 5, 8, 9, 11, 14, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30], "\u547d\u540d": 0, "\u4e00\u90e8": [0, 27], "abics": 0, "\u53c2\u8003": [0, 23], "\u307e\u3059": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u307e\u305f": [0, 1, 2, 4, 20, 24, 25, 26, 28, 29, 30, 32], "\u9806\u554f\u984c": [0, 10, 13, 15, 22, 26, 27, 28], "\u30bd\u30eb\u30d0\u30fc": [0, 2, 5, 6, 9, 11, 13, 14, 15, 16, 22, 23, 24, 25, 26, 27, 28, 29, 30], "\u5b9f\u88c5": [0, 1, 15, 25], "\u3042\u305f\u308a": 0, "\u82b1\u7530": [0, 26], "\u8cb4\u6c0f": 0, "\u6771\u5317\u5927\u5b66": 0, ")\u3001": [0, 9, 30], "\u671b\u6708": 0, "\u51fa\u6d77": 0, "(kek": 0, "voegeli": [0, 15], "\u5b66\u82b8": 0, "\u767d\u6fa4": 0, "\u5fb9\u90ce": 0, "(aist": 0, "ahmed": 0, "\u4e5d\u5dde": 0, "\u548c\u7530": 0, "\u5065\u6c0f": 0, "\u306b\u304a\u4e16\u8a71": 0, "\u306a\u308a": [0, 2, 5, 6, 8, 11, 14, 19, 20, 23, 24, 25, 27, 29, 30], "\u8ffd\u52a0": [0, 1, 13, 23, 25, 26, 27, 30], "\u65b9\u6cd5": [0, 2, 6, 8, 10, 13, 14, 20, 24, 25, 26, 27, 28, 29, 30, 32], "\u306b\u3064\u3044\u3066": [0, 1, 2, 4, 7, 8, 9, 14, 16, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30], "\u585a\u672c": 0, "\u606d\u5e73": 0, "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb": [0, 13, 22, 24, 25, 27, 28, 29, 30, 31], "\u305f\u3060\u304d": 0, "\u3053\u306e": [0, 2, 5, 6, 8, 11, 15, 20, 23, 24, 25, 27, 28, 29, 30, 31, 32], "\u501f\u308a": 0, "\u611f\u8b1d": 0, "\u63a2\u7d22": [1, 2, 5, 6, 8, 9, 13, 14, 15, 16, 17, 18, 20, 22, 23, 24, 26, 28, 29, 32], "\u884c\u3046": [1, 2, 4, 6, 19, 21, 23, 24, 25, 27, 28, 29, 30, 31], "algorithm": [1, 2, 3, 6, 9, 10, 12, 13, 14, 16, 22, 24, 25, 27, 28, 29, 30, 32], "\u3067\u3059": [1, 2, 4, 5, 6, 8, 9, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "physbo": [1, 22, 24], "\u3042\u3089\u304b\u3058\u3081": [1, 2, 4, 5, 6, 19, 20, 21, 23], "\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [1, 2, 4, 5, 6, 7, 13, 19, 20, 21, 23], "\u304a\u304f": [1, 2, 4, 5, 6, 11, 20, 21], "\u5fc5\u8981": [1, 2, 4, 5, 6, 8, 11, 13, 14, 19, 20, 21, 24, 29, 31, 32], "\u3042\u308a": [1, 2, 4, 5, 6, 8, 10, 14, 19, 20, 21, 24, 28, 29, 32], "\u3002:": [1, 2, 4, 6, 11, 19, 22, 31], "python": [1, 2, 4, 5, 6, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32], "pip": [1, 2, 4, 5, 6, 22, 23], "install": [1, 2, 4, 5, 6, 22], "mpi": [1, 2, 4, 6, 8, 14, 16, 22, 23, 25, 27, 29, 30], "4py": [1, 2, 4, 6, 8, 22], "\u3044\u308b": [1, 2, 4, 6, 7, 14, 19, 20, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u5834\u5408": [1, 2, 4, 5, 6, 7, 8, 9, 14, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 32], "\u4e26\u5217": [1, 2, 4, 6, 25, 27, 29, 30], "\u53ef\u80fd": [1, 2, 12, 14, 15, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 32], "algorithmparam": 1, "\u7a7a\u9593": [1, 2, 3, 4, 5, 6, 8, 14, 23, 25, 27, 29, 30], "mesh": [1, 2, 4, 6, 24, 29], "_path": [1, 2, 4, 6, 24], "\u30e1\u30c3\u30b7\u30e5\u30d5\u30a1\u30a4\u30eb": [1, 4, 24], "\u304b\u3089": [1, 2, 4, 5, 6, 8, 9, 11, 14, 16, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u8aad\u307f\u8fbc\u307f": [1, 4, 23], "\u610f\u5473": [1, 4], "\u304a\u308a": [1, 4, 15, 28], "\u5217\u76ee": [1, 2, 4, 6, 16, 20, 24, 25, 27, 28, 29, 30, 31], "\u30c7\u30fc\u30bf": [1, 2, 4, 6, 15, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31], "\u756a\u53f7": [1, 2, 4, 6, 9, 12, 16, 19, 20, 21, 24, 25, 27, 29, 30], "\u76ee\u4ee5\u964d": [1, 2, 4, 5, 6, 20, 23, 24, 25, 27, 29, 30, 31], "\u5404\u6b21": [1, 4], "\u5ea7\u6a19": [1, 2, 4, 5, 6, 9, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30], "\u306a\u3044": [1, 2, 4, 6, 8, 14, 19, 20, 23], "min": [1, 2, 4, 5, 6, 8, 9, 14, 25, 27, 28, 30, 32], "_list": [1, 2, 4, 5, 6, 8, 14, 20, 24, 25, 27, 28, 29, 30, 32], "max": [1, 2, 4, 5, 6, 14, 20, 25, 27, 28, 30, 32], "num": [1, 4, 16, 24], "\u7b49\u9593": [1, 4], "\u30b0\u30ea\u30c3\u30c9": [1, 2, 4, 6, 13, 14, 15, 22, 24, 25, 26, 30], "\u4f5c\u6210": [1, 4, 8, 12, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31], "\u5f62\u5f0f": [1, 2, 4, 5, 6, 14, 17, 19, 20, 21, 23, 28], "string": [1, 4, 5, 14, 17, 19, 20, 21, 23, 24, 25, 28, 29, 30], "\u8aac\u660e": [1, 2, 4, 5, 6, 9, 14, 17, 19, 20, 21, 23, 26], "\u30e1\u30c3\u30b7\u30e5\u30c7\u30fc\u30bf": [1, 4], "\u60c5\u5831": [1, 5, 6, 7, 9, 16, 21, 23, 25, 27, 30], "\u8a18\u8f09": [1, 2, 4, 5, 6, 7, 16, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30], "\u53c2\u7167": [1, 2, 5, 6, 8, 9, 14, 16, 22, 27, 32], "\u30d1\u30b9": [1, 4, 9, 14, 19, 20, 21, 23, 24, 28, 29], "\u5b9f\u6570": [1, 2, 4, 5, 6, 20], "\u30ea\u30b9\u30c8": [1, 4, 5, 14, 19, 20, 21, 23, 24, 25, 28, 29, 30], "\u9577\u3055": [1, 2, 4, 5, 6, 20, 23], "dimension": [1, 2, 4, 5, 6, 14, 20, 24, 25, 27, 28, 29, 30, 32], "\u4e00\u81f4": [1, 2, 4, 5, 6, 19, 20, 28], "\u53d6\u308a\u3046\u308b": [1, 2, 4, 5, 6], "\u6700\u5c0f": [1, 2, 4, 5, 6, 8, 14, 15, 20, 24, 25, 27, 28, 30], "\u6700\u5927": [1, 2, 4, 5, 6, 8, 21, 24, 28, 29], "\u6574\u6570": [1, 2, 4, 5, 6, 14, 16, 19, 20], "\u624b\u6cd5": [1, 2, 6], "\u30cf\u30a4\u30d1\u30fc\u30d1\u30e9\u30e1\u30fc\u30bf": [1, 2, 5, 24, 25, 27, 30], "random": [1, 24], "_max": [1, 23, 24, 25, 28, 29, 30], "_num": [1, 6, 24], "_probes": [1, 24], "int": [1, 6, 8, 9, 11, 21], "default": [1, 2, 5, 6, 14, 20, 21, 23], "\u30e9\u30f3\u30c0\u30e0\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": 1, "\u56de\u6570": [1, 2, 5, 6, 20, 24, 25, 27, 30], "\u30b9\u30b3\u30a2": [1, 24], "\u521d\u3081": 1, "\u7121\u3044": [1, 27], "\u5fc5\u9808": [1, 20], ")\u3002": [1, 2, 6, 21, 23, 24, 25, 27, 28, 29, 30], "score": [1, 24], "ts": [1, 24], "\u95a2\u6570": [1, 2, 5, 6, 8, 9, 11, 15, 17, 20, 25, 27, 28, 30], "\u6307\u5b9a": [1, 2, 6, 7, 14, 17, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30, 32], "\u3059\u308b": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "ei": 1, "pi": [1, 17], "\u3088\u308a": [1, 2, 21, 25, 27, 30, 31], "\u9078\u629e": [1, 32], "\u305d\u308c\u305e\u308c": [1, 2, 5, 6, 8, 20, 21, 28, 30], "expected": 1, "improvement": 1, "\",": [1, 9], "probability": 1, "of": [1, 6, 15, 19, 21, 23, 30], "thompson": 1, "sampling": [1, 23], "interval": [1, 6, 14, 24], "\u30a4\u30f3\u30bf\u30fc\u30d0\u30eb": 1, "\u3054\u3068": [1, 2, 6, 8, 9, 11, 14, 16, 20, 21, 25, 30], "\u5b66\u7fd2": 1, "\u884c\u308f": [1, 6, 14, 19, 23], "\u307e\u305b": [1, 2, 8, 11, 12, 14, 23], "\u6700\u521d": [1, 5, 19, 20, 24, 25, 26, 27, 28, 29, 30, 31], "\u30b9\u30c6\u30c3\u30d7": [1, 2, 9, 24, 25, 27, 28, 30], "\u306e\u307f": [1, 16, 20, 23, 27], "_rand": [1, 24], "_basis": [1, 24], "\u57fa\u5e95": [1, 8, 11], "bayesian": 1, "linear": 1, "model": [1, 21], "\u5229\u7528": [1, 2, 6, 11, 12, 14, 19, 20, 21, 22, 23, 27, 28, 31, 32], "\u901a\u5e38": [1, 23, 24, 25, 27, 28, 29, 30], "\u30ac\u30a6\u30b7\u30a2\u30f3\u30d7\u30ed\u30bb\u30b9": 1, "\u30a4\u30f3\u30c7\u30c3\u30af\u30b9": [1, 2, 4, 6, 20], "\u4ee5\u964d": [1, 2, 4, 6, 20, 21], "[solver": [1, 4, 5, 24, 25, 27, 28, 29, 30, 32], ".param": [1, 24, 25, 27, 28, 29, 30, 32], "\u3042\u308b": [1, 2, 4, 5, 7, 8, 9, 11, 12, 14, 19, 20, 23, 24, 25, 27, 28, 29, 30, 31], "\u5165\u308b": [1, 24, 29], "\u5165\u308a": [1, 31], "\u4ee5\u4e0b": [1, 2, 4, 5, 6, 7, 9, 14, 15, 16, 17, 19, 20, 21, 23, 24, 25, 27, 28, 29, 30, 31, 32], "\u30b5\u30f3\u30d7\u30eb": [1, 2, 4, 6, 19, 24, 25, 27, 29, 30, 31], "...": [1, 2, 4, 6, 14, 16, 20, 23, 24, 29, 32], "\u5316\u904e": 1, "\u304a\u3044": [1, 2, 4, 11], "\u5bfe\u5fdc": [1, 2, 6, 8, 12, 20, 21, 23, 31], "\u76ee\u7684": [1, 2, 5, 8, 9, 11, 17, 20, 25, 27, 28, 30], "\u3053\u308c": [1, 6, 23, 25, 29, 30, 32], "\u307e\u3067": [1, 19, 20, 21], "\u305d\u306e": [1, 2, 4, 5, 6, 7, 8, 9, 14, 19, 21, 23, 24, 25, 26, 27, 28, 29, 30, 32], "#step": [1, 5, 24], "-factor": [1, 4, 5, 20, 24, 25, 28, 29, 30], "action": [1, 24], "_action": [1, 24], "optimization": 1, "bo": 1, "\u6a5f\u68b0": 1, "\u63f4\u7528": 1, "\u8a55\u4fa1": [1, 2, 5, 6, 17, 25, 27, 28, 30], "\u6642\u9593": [1, 8, 16, 24, 25, 27, 28, 29, 30], "\u304b\u304b\u308b": [1, 20], "\u3068\u304d": [1, 2, 6, 20, 23, 30], "\u5f37\u529b": 1, "(\\": [1, 2, 17, 20], "vec": [1, 2, 17, 21], "{x": [1, 2, 3, 6, 17], "})": [1, 2, 6, 17, 20, 21], "\u65e9\u304f": 1, "\u3057\u3084\u3059\u3044": 1, "\u30e2\u30c7\u30eb": [1, 23], "\u591a\u304f": [1, 15, 20, 26], "\u30ac\u30a6\u30b9": [1, 2, 30], "\u904e\u7a0b": 1, "\u8fd1\u4f3c": 1, "\u9069\u5f53": [1, 2, 6, 20, 23, 28, 31], "\u6c7a\u3081": 1, "\u3089\u308c": [1, 2, 6, 9, 10, 14, 15, 19, 20, 21, 23, 24, 25, 26, 28, 29, 30], "\u305f\u3044\u304f\u3064\u304b": 1, "\u8a13\u7df4": 1, "\u30c7\u30fc\u30bf\u30bb\u30c3\u30c8": 1, "{\\": [1, 2, 6, 17, 20, 23], "}_": [1, 2, 6], "\\}": [1, 2, 6], "_{i": [1, 20], "}^": [1, 6, 17, 20, 21], "\u3067\u306e": 1, "{f": [1, 2, 6], ")\\": [1, 6, 17], "}_{": 1, "\u3092\u3088\u304f": 1, "\u518d\u73fe": [1, 26], "\u3088\u3046": [1, 2, 6, 9, 11, 12, 20, 21, 23, 24, 26, 28, 29, 31, 32], "\u5404\u70b9": [1, 2, 5, 6], "\u671f\u5f85": [1, 6, 30], "\u8aa4\u5dee": [1, 6, 19, 20, 21, 30], "\u6c42\u3081": [1, 20, 26, 28], "\u3089\u308c\u308b": [1, 2, 21, 23, 24, 25, 27, 28, 29, 30], "acquition": 1, "function": [1, 17, 27, 32], "\u306a\u308b": [1, 2, 6, 8, 20, 23, 28, 31], "\\vec": [1, 2, 21], "\u5019\u88dc": [1, 2, 4, 8, 24, 28, 29], "\u3068\u3057\u3066": [1, 2, 4, 5, 6, 8, 9, 11, 12, 14, 15, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u63d0\u6848": [1, 2, 6], "\u518d\u8a13": 1, "\u3053\u3046\u3057": 1, "\u7e70\u308a\u8fd4\u3057": [1, 5], "\u6700\u3082": 1, "\u826f\u304b\u3063": 1, "\u3082\u306e": [1, 2, 5, 6, 9, 10, 23, 24, 25, 29, 30, 31], "\u8fd4\u3057": [1, 8, 9], "\u5c11\u306a\u3044": 1, "\u826f\u3044": [1, 6, 24], "\u4e0e\u3048\u308b": [1, 14, 21, 24, 25, 27, 29, 30], "\u6b63\u89e3": [1, 28], "\u3053\u305d": 1, "\u9ad8\u3044": 1, "\u3059\u3067": 1, "\u5341\u5206": 1, "\u8003\u3048": [1, 6], "\u306e\u3067": [1, 2, 5, 6, 11, 24, 28, 32], "\u7cbe\u5ea6": [1, 2], "\u5411\u4e0a": 1, "\u3042\u307e\u308a": 1, "\u5bc4\u4e0e": 1, "\u5927\u304d": 1, "\u304b\u3082": 1, "\u3057\u308c": 1, "\u5834\u6240": [1, 23, 31], "\u66f4\u65b0": [1, 2, 6, 14, 22, 25, 27, 30], "\u6709\u76ca": 1, "\u524d\u8005": 1, "\u9078\u3076": 1, "\u3053\u3068": [1, 2, 4, 5, 6, 7, 10, 14, 15, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u6d3b\u7528": 1, "\u5f8c\u8005": 1, "\u3088\u3073": 1, "\u4e21\u8005": 1, "\u30d0\u30e9\u30f3\u30b9": 1, "\u826f\u304f\u884c\u3046": 1, "\u91cd\u8981": [1, 2, 5], "\u3053\u308c\u3089": [1, 2, 5, 6, 10, 20, 23, 24, 25, 26, 27, 28, 29, 30], "\u3069\u3046": [1, 2], "\u9078\u3076\u304b": 1, "\u5b9a\u3081": [1, 2, 6], "2dmat": [1, 2, 5, 6, 7, 8, 11, 12, 14, 19, 20, 21, 24, 25, 27, 28, 29, 30, 31, 32], "\u30e9\u30a4\u30d6\u30e9\u30ea": 1, "mapper": [1, 3, 8, 9, 13, 14, 26, 29], "_mpi": [1, 4, 26], "\u306e\u3088\u3046": [1, 21], "\u96c6\u5408": [1, 4, 8], "\u306b\u5bfe\u3057": [1, 14, 15, 21, 23, 26, 31], "\u6700\u9069\u89e3": [1, 2], "\u5019\u88dc\u70b9": 1, "\u5206\u5272": [1, 2, 8], "\u5b9f\u884c": [1, 2, 4, 7, 8, 9, 10, 11, 13, 14, 19, 20, 21, 23, 26, 32], "\u70b9\u6570": [1, 30], "\u7dda\u5f62": [1, 14], "\u3072\u3044\u3066": 1, "\u30ab\u30fc\u30cd\u30eb": 1, ")\"": 1, ", \"": 1, "\u3067\u304d": [1, 2, 6, 12, 19, 20, 21, 22, 23, 25, 27, 28, 29, 30, 31], "\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3": [2, 5, 6, 14, 19, 24, 25, 27, 28, 29, 30], "param": [2, 4, 5, 6, 8, 20, 21], "\u6301\u3061": [2, 5, 6, 9, 14, 27], "\u30ad\u30fc": [2, 6, 9], "\u5b58\u5728": [2, 6, 8], "\u96e2\u6563": [2, 6, 8, 23], "\u305d\u3046": [2, 6], "\u9023\u7d9a": [2, 6, 8], "initial": [2, 5, 6, 28, 32], "\u521d\u671f\u5024": [2, 5, 6, 8, 14, 21, 28], "\u306a\u304b\u3063": [2, 5, 6], "\u4e00\u69d8": [2, 5, 6], "\u30e9\u30f3\u30c0\u30e0": [2, 5, 6, 14, 24], "\u521d\u671f\u5316": [2, 5, 6, 11, 14], "unit": [2, 5, 6, 23, 27, 30], "\u5358\u4f4d": [2, 5, 6, 8, 14, 21, 23], "\u5272\u308b": [2, 5, 6], "\u7c21\u6613": [2, 5, 6], "\u7121\u6b21": [2, 5, 6], "\u5143\u5316": [2, 5, 6], "\u6b63\u898f": [2, 5, 6], "\u884c\u3044": [2, 4, 5, 6, 8, 22, 23, 24, 28, 29, 31], "\u306f\u3059\u3079\u3066": [2, 5, 6], "\u6b21\u5143": [2, 4, 5, 6, 8, 14, 23, 24, 25, 27, 29, 30], "\u4e0b\u56de\u308b": [2, 5, 6], "\u51fa\u73fe": [2, 5, 6], "\u308c\u305a": [2, 5, 6], "\u7121\u9650": [2, 5, 6], "\u306a\u3055": [2, 5, 6], "\u4e0a\u56de\u308b": [2, 5, 6], "\u30d5\u30a1\u30a4\u30eb\u30d1\u30b9": [2, 6], "neighborlist": [2, 6, 23], "numsteps": [2, 6, 25, 27, 30], "_exchange": [2, 25, 27], "\u6e29\u5ea6": [2, 6, 25, 27, 30], "\u983b\u5ea6": [2, 6], "\u3060\u3051": [2, 6, 23], "\u884c\u3063": [2, 6, 23, 25, 27, 29, 30], "\u305f\u3089": 2, "tmin": [2, 6, 25, 27], "\u300d(": [2, 6], "\u6700\u5c0f\u5024": [2, 4, 6, 25, 27, 29, 30, 32], "tmax": [2, 6, 25, 27], "bmin": [2, 6, 30], "\u9006\u6e29\u5ea6": [2, 6], "\\beta": [2, 6, 30], "\u9006\u6e29": [2, 6, 30], "\u3069\u3061\u3089\u304b": [2, 6], "\u7247\u65b9": [2, 6], "bmax": [2, 6, 30], "\u6700\u5927\u5024": [2, 6, 25, 27, 30], "tlogspace": [2, 6, 25, 27, 30], "\u771f\u507d\u5024": [2, 6, 14, 20], "true": [2, 6, 8, 20, 24, 25, 27, 28, 29, 30], "\u5272\u308a\u5f53\u3066\u308b": [2, 6], "\u5bfe\u6570": [2, 6, 25, 27, 30], "\u7b49\u5206": [2, 4, 6, 25, 27, 30], "\u5426\u304b": [2, 6], "nreplica": [2, 6, 30], "_per": [2, 6, 30], "_proc": [2, 6, 30], "\u3072\u3068\u3064": [2, 6, 31], "\u30d7\u30ed\u30bb\u30b9": [2, 4, 6, 8, 11, 14, 25, 27, 29, 30], "\u62c5\u5f53": [2, 6], "\u5b9f\u969b": [2, 6, 9, 14, 23, 24, 25, 27, 28, 29, 30, 31], "\u4f7f\u7528": [2, 6, 7, 10, 20, 23, 24, 25, 26, 27, 28, 29, 30], "\u308c\u307e\u305b": [2, 6], "\uff09\u3001": [2, 6], "\u79fb\u52d5": [2, 6, 8, 14, 20, 24, 25, 27, 28, 29, 30], "\u3067\u304d\u308b": [2, 5, 6, 11, 20, 27, 32], "\u305f\u3081": [2, 5, 6, 7, 8, 9, 10, 14, 15, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u59cb\u70b9": [2, 6], "\u7d42\u70b9": [2, 6], "\u5217\u6319": [2, 6], "\u751f\u6210": [2, 6, 8, 11, 14, 19, 20, 23, 25, 27, 30, 31], "\u30c4\u30fc\u30eb": [2, 6, 13, 28], "py": [2, 6, 8, 11, 12, 13, 14, 19, 20, 21, 32], "_neighborlist": [2, 6, 13], "\u63d0\u4f9b": [2, 6, 8, 25, 31], "\u8a73\u7d30": [2, 5, 6, 8, 9, 14, 19, 22, 24, 25, 27, 28, 29, 30, 32], "\u95a2\u9023": [2, 6, 7, 13], "\u304f\u3060": [2, 5, 6, 7, 8, 9, 11, 14, 15, 16, 20, 22, 25, 27, 30, 31, 32], "\u3055\u3044": [2, 5, 6, 7, 8, 9, 11, 14, 15, 16, 20, 22, 25, 27, 30, 31, 32], "..": [2, 6, 19, 20, 21, 24, 25, 27, 28, 29, 30, 31, 32], "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": [2, 6], "walker": [2, 6, 25, 27, 30], "step": [2, 5, 6, 8, 9, 20, 24, 25, 27, 30], "fx": [2, 5, 8, 9, 20, 24, 25, 27, 28, 30], "trial": [2, 6, 25, 27, 30], "\u66f8\u5f0f": [2, 6, 25, 27, 30], "\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": [2, 6, 23, 25, 26], "\u3046\u3061": [2, 6, 22], "\u306a\u3063": [2, 6, 24, 25, 27, 28, 29, 30], "nprocs": [2, 6, 11, 25, 27, 30], "\u7d50\u679c": [2, 3, 5, 8, 9, 11, 14, 23, 26], "\u306b\u307e\u3068\u3081": [2, 25], "\u76f4\u3057": 2, "\u5168\u4f53": [2, 9, 10, 14, 20, 21, 23, 25, 27, 30], "\u52d5\u304d": 2, "\u56de\u308b": 2, "\u91cd\u307f": [2, 6, 20, 30], "\u306b\u5f93\u3063": 2, "\u78ba\u7387": [2, 6, 27], "\u52d5\u304b\u3059": [2, 5, 20, 21, 28], "\u6700\u9069": [2, 3, 5, 8, 9, 10, 12, 13, 14, 15, 18, 19, 21, 22, 23, 25, 26, 27, 29, 30, 32], "\u3001\u300c": [2, 21], "\u5c0e\u5165": 2, "^{": [2, 6, 20], "-f": 2, "\u3068\u3059\u308b": [2, 22], "\u4e00\u822c": 2, "\u30dc\u30eb\u30c4\u30de\u30f3": [2, 6], "\uff09\u3002": [2, 6, 9, 32], "\u307b\u3068\u3093\u3069": 2, "\u57fa\u3065\u3044": 2, "\u76f4\u63a5": [2, 6, 22, 23], "\u4e0d\u53ef\u80fd": 2, "\u5c11\u3057": 2, "\u305a\u3064": 2, "\u52d5\u304b": [2, 24, 28, 29], "\u5206\u5e03": [2, 6, 27, 30], "\u306b\u5f93\u3046": [2, 6], "\u6642\u7cfb": 2, "mcmc": [2, 6], "}'": 2, "\u9077\u79fb": [2, 6], "= \\": [2, 6, 20], "sum": [2, 6, 17, 20], "_{": [2, 6, 14, 17, 20, 21, 27], "}}": [2, 6, 20, 23], "\u5b9a\u3081\u308c": 2, "\u53ce\u675f": [2, 5, 28], "\u793a\u3055": [2, 6], "\u91e3\u308a\u5408\u3044": [2, 6], "\u6761\u4ef6": [2, 6, 14], "\u5f37\u3044": 2, "\u5236\u7d04": [2, 14, 26, 27], "| \\": 2, ") w": 2, "\u8ab2\u3059": [2, 14], "\u4e21\u8fba": 2, "\u53d6\u308b": [2, 14], "\u5e30\u7740": 2, "\u6c42\u3081\u308b": [2, 5, 6], "\u3044\u304f\u3064\u304b": [2, 10], "metropolis": 2, "-hasting": 2, "mh\u6cd5": 2, "mh": 2, "\u63a1\u629e": [2, 6, 25, 27, 30], "\u4e2d\u5fc3": [2, 21], "\u306a\u3069": [2, 7, 8, 9, 14, 15, 19, 20, 22, 23, 25, 26, 27, 28, 30, 32], "\u6271\u3044": 2, "\u3084\u3059\u3044": 2, "},": [2, 6, 15, 21], "\u5165\u308c": 2, "\u3068\u3057": [2, 15, 20, 23, 32], "\u53d7\u3051\u5165\u308c": 2, "\\left": [2, 6, 17], "frac": [2, 6, 17, 20], "{w": 2, "}{": [2, 6, 17], ")}": [2, 6, 20], "right": [2, 6, 14, 17, 20], "\u6e80\u305f": [2, 6, 27], "\u4ee3\u5165": 2, "\u7c21\u5358": [2, 6, 23, 25, 26, 27, 30, 32], "\u78ba\u304b\u3081": 2, "\u56e0\u5b50": [2, 6, 21], "\u5bfe\u79f0": 2, "\u306a\u3082\u306e": 2, "= p": 2, "}{w": 2, "exp": [2, 6, 17, 19, 20], "(-": [2, 17], "{t": [2, 6], "}\\": [2, 6, 17, 20], "\u3068\u3044\u3046": [2, 5, 6, 8, 14, 23], "\\delta": 2, "\u3068\u304a\u3044": 2, "le": 2, "\u3068\u306a\u308b": [2, 14], "\u8e0f\u307e\u3048\u308b": 2, "\u306b\u3088\u308b": [2, 13, 14, 15, 24, 26, 29, 32], "\u73fe\u5728": [2, 14, 27], "\u5730\u70b9": 2, "\u8fd1\u304f": 2, "\u9078\u3073": 2, "\u8abf\u3079\u308b": 2, "\u306a\u3089\u3070": [2, 20], "\uff08\u5c71": 2, "\u4e0b\u308b": 2, "\u65b9\u5411": [2, 21], "\u306a\u3089": 2, "-\\": [2, 6], "delta": 2, "\u7e70\u308a": 2, "\u8fd4\u3059": [2, 19, 20, 21], "\u4e00\u756a": [2, 24, 32], "\u304a\u304b\u3052": 2, "sim": [2, 13, 14, 18, 22, 24, 25, 26, 28, 29, 30, 31], "\u3050\u3089\u3044": 2, "\u4e57\u308a": 2, "\u8d8a\u3048": 2, "\u5c40\u6240": [2, 5], "\u30c8\u30e9\u30c3\u30d7": [2, 5], "\u8131\u51fa": 2, "\u975e\u5e38": 2, "\u7a0b\u5ea6": [2, 24, 25, 27, 28, 29, 30], "\u305d\u308c": [2, 25, 26, 27, 30], "\u4ee5\u4e0a": [2, 20, 22], "\u6df1\u3055": 2, "\u5bb9\u6613": 2, "\u9632\u3050": 2, "\u4e0a\u3052\u308b": 2, "\u4e00\u65b9": [2, 26], "\u5c0f\u3055\u3044": [2, 25, 29, 30], "\u8c37\u3068\u3057\u3066": 2, "\u898b\u3048": 2, "\u306a\u304f": 2, "\\min": 2, "\u4e0b\u3052\u308b": [2, 6], "\u3053\u3053\u304b\u3089": 2, "\u63a2\u3059": [2, 15], "\u6ce8\u610f": [2, 20], "\u6df1\u304f": 2, "\u6c7a\u3081\u308b": 2, "\u304c\u308f\u304b\u308a": [2, 20, 24, 25, 28, 29, 30], "\u554f\u984c": [2, 5, 7, 12, 13, 14, 16, 22, 24, 25, 26, 28, 29, 30], "\u89e3\u6c7a": [2, 7], "\u56fa\u5b9a": [2, 6, 24, 29], "\u3044\u304f": [2, 15], "\u305f\u3068\u3048": [2, 32], "\u713c\u304d": 2, "\u306a\u307e\u3057": 2, "simulated": 2, "annealing": 2, "\u5f90\u3005": 2, "\u4e0b\u3052": [2, 30], "\u3044\u304d": 2, "\u713c\u623b\u3057\u6cd5": 2, "tempering": 2, "\u3079\u304d": 2, "\u3001\uff08": 2, "\u52a0\u71b1": 2, "\u51b7\u5374": 2, "\u5b9f\u73fe": 2, "\u8abf\u3079": 2, "replica": [2, 30], "monte": 2, "carlo": 2, "\u713c\u623b": 2, "\u767a\u5c55": 2, "parallel": 2, "\u3068\u3082\u547c\u3070": 2, "\u547c\u3070": 2, "\u308c\u308b": [2, 5, 9, 11, 14, 19, 20, 21, 23, 27], "\u8907\u6570": [2, 6, 20], "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u30b7\u30df\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3": 2, "\u305d\u3057\u3066": 2, "\u4e00\u5b9a": 2, "\u9593\u9694": 2, "\u540c\u69d8": [2, 14, 23, 24, 25, 28, 29, 30], "\u4e0a\u4e0b": 2, "\u305f\u308a": 2, "\u5404\u6e29": [2, 25, 30], "\u5ea6\u70b9": [2, 25], "\u304b\u306a\u3089": 2, "\u3069\u308c": [2, 6], "\u7279\u5b9a": 2, "\u504f\u308b": 2, "\u7528\u610f": [2, 4, 14, 15, 19, 24, 25, 26, 27, 28, 29, 30], "\u305b\u308b": [2, 10, 19, 20, 21], "\u5316\u53ef": 2, "\u6570\u591a\u304f": 2, "\u72ed\u307e\u308b": 2, "\u4e0a\u304c\u308b": 2, "\u5927\u898f": 2, "\u6a21\u4e26": 2, "\u5217\u8a08": 2, "\u7279\u306b": 2, "\u5411\u3044": 2, "\u6709\u9650": 2, "\u7531\u6765": [2, 23], "\u300c\u307c\u3084\u3051": 2, "\u3057\u3066": [2, 7, 23, 31], "\u751f\u307e": 2, "minsearch": [2, 3, 13, 14, 24, 25, 26, 28, 29, 30, 32], "\u304a\u3059\u3059\u3081": 2, "\u811a\u6ce8": 2, "\u6b63\u78ba": 2, "\u975e\u5468": 2, "\u671f\u6027": 2, "\u30a8\u30eb\u30b4\u30fc\u30c9": 2, "solver": [3, 9, 10, 12, 13, 14, 16, 17, 18, 19, 20, 21, 22, 24, 25, 27, 28, 29, 30, 32], "(x": [3, 4, 6, 8, 9, 17, 18, 19, 20, 21, 24, 25, 28, 29, 30, 32], "\u30d1\u30e9\u30e1\u30fc\u30bf": [3, 8, 9, 11, 12, 14, 15, 16, 18, 23, 24, 25, 26, 27, 28, 29, 30, 32], "\\mathbf": 3, "ni": 3, "nelder": [3, 13, 14, 15, 22, 26, 32], "-mead": [3, 13, 14, 15, 22, 24, 25, 26, 29, 30, 32], "\u81ea\u660e\u4e26\u5217": [3, 13], "\u4ea4\u63db": [3, 13, 14, 15, 26, 30], "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": [3, 6, 13, 14, 15, 20, 23, 26, 30], "exchange": [3, 9, 13, 14, 25, 26, 27], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": [3, 13, 15], "pamc": [3, 13, 26, 30], "\u30d9\u30a4\u30ba": [3, 13, 14, 15, 22, 26], "bayes": [3, 13, 14, 24, 26], "\u305d\u306e\u3059\u3079\u3066": 4, "\u5272\u3057": 4, "\u81ea\u52d5": [4, 6, 8, 9, 19, 20], "\u5272\u308a": [4, 24, 25, 29, 30], "\u632f\u308b": 4, "\u81ea\u660e": 4, "\u30c6\u30ad\u30b9\u30c8\u30d5\u30a1\u30a4\u30eb": 4, "\u306b\u5bfe\u5fdc": [4, 15, 28, 29, 30], "\u59cb\u307e\u308b": [4, 20], "\u30b3\u30e1\u30f3\u30c8": [4, 12, 21, 23], "\u7121\u8996": 4, "\u9806\u756a": [4, 8, 19], "\u6700\u5f8c": [4, 5, 6, 20, 23, 24, 25, 26, 27, 28, 29, 30], "(a": [5, 6, 9], ".k": 5, ".a": [5, 15, 19], "downhill": 5, "simplex": 5, "\u306b\u3088\u3063": [5, 6, 19, 20, 25, 26], "\u5fdc\u3058": 5, "\u7cfb\u7d71\u7684": 5, "\u5909\u3048": 5, "\u4f55\u56de": 5, "\u78ba\u8a8d": [5, 20, 24, 25, 27, 29, 30], "\u304a\u3059\u3059\u3081\u3057": 5, "scipy": [5, 22, 23, 28], ".optimize": [5, 28], ".minimize": 5, "(method": 5, "=\"": [5, 20, 23], "\")": [5, 14, 20], "\u8a73\u3057\u304f": [5, 14, 22], "\u516c\u5f0f": [5, 20], "\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8": 5, "\u3092\u3054": 5, "\u53c2\u7167\u304f": 5, "\u3060\u3055\u3044": [5, 7, 11, 14, 19, 21, 23, 24, 28, 29], "minimize": 5, "\u5b9a\u7fa9": [5, 12, 13, 14, 15, 20, 21, 22, 23, 26, 27, 32], "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0": [5, 8, 9, 13, 14, 15, 16, 17, 20, 22, 24, 25, 26, 27, 28, 29, 30, 31, 32], "\u5316\u4e2d": 5, "\u8a2d\u5b9a": [5, 8, 9, 11, 14, 20, 21, 23, 24, 25, 27, 28, 29, 30, 32], "_scale": [5, 21], "\u521d\u671f": [5, 9, 21], "\u4f5c\u308b": 5, "\u305a\u3089\u3059": 5, "\u5dee\u5206": [5, 24, 25, 27, 28, 29, 30], "\u6210\u5206": 5, "\u3068\u3064": [5, 30], "\u8db3\u3057": 5, "\u5408\u308f\u305b": [5, 28], "_simplex": 5, "\u4f7f\u308f": [5, 9], "\u5404\u6b21\u5143": 5, "xatol": 5, "1e": 5, "\u5224\u5b9a": [5, 28], "\u4f7f\u3046": [5, 6, 9, 14, 32], "fatol": 5, "maxiter": 5, "\u53cd\u5fa9": [5, 20], "maxfev": 5, "\u5c0f\u5024": 5, "\u9014\u4e2d": [5, 28], "\u7d4c\u904e": [5, 16], "\u306b\u95a2\u3059\u308b": [5, 7, 14, 16, 19, 23, 28, 31], "\u884c\u76ee": [5, 21], "\u30d8\u30c3\u30c0\u30fc": [5, 20], "\u6700\u7d42": [5, 20, 24], "\u5f97\u3089\u308c": [5, 28], "\u5024\u3068": 5, "\u305d\u306e\u5f8c": [5, 26, 31], "\u7dcf\u56de": 6, "_annealing": [6, 30], "\u4e0b\u304c\u308a": 6, "numt": 6, "\u30ec\u30d7\u30ea\u30ab": [6, 13, 14, 15, 20, 26, 30], "resampling": 6, "_interval": 6, "\u30ea\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": 6, "\u964d\u4e0b": 6, "fix": 6, "_replicas": 6, "\u304b\u3069\u3046": [6, 14, 20, 21], "3\u3064": [6, 8, 9, 28], "2\u3064": [6, 20, 24, 25, 27, 29, 30], "\u540c\u6642": [6, 14, 22], "\u6b8b\u308a": 6, "1\u3064": [6, 20], "\u6c7a\u5b9a": [6, 14], "neal": [6, 15, 30], "-jarzynski": [6, 30], "weight": [6, 20, 30], "\u7956\u5148": [6, 30], "\u958b\u59cb": [6, 16, 30], "beta": [6, 21, 30], "ancestor": [6, 30], "\u3092\u3059\u3079": 6, "\u307e\u3068\u3081": 6, "result": [6, 25, 27, 30], "\u6a19\u6e96": [6, 15, 20, 21, 24, 29, 30], "\u7dcf\u6570": 6, "\u898f\u683c": [6, 20, 31], "\u5316\u56e0\u5b50": 6, "\u5206\u914d": [6, 30], "\\log": [6, 30], "\\frac": 6, "{z": 6, "log": [6, 13, 14, 20, 24, 25, 27, 28, 29, 30], "\\int": 6, "mathrm": 6, "{d": 6, "}x": 6, "\u3053\u3053\u3067": [6, 14, 21, 28, 32], "/t": [6, 30], "mean": [6, 30], "standard": [6, 30], "error": [6, 30], "number": [6, 21, 30], "replicas": [6, 30], "(z": [6, 30], "/z": [6, 30], "acceptance": [6, 30], "ratio": [6, 30], "_i": [6, 17, 20, 21, 28, 29], "\u306e\u3082": 6, "\u914d\u4f4d": 6, "\u66f8\u304f": [6, 20, 23], "\u4f8b\u3048": [6, 9, 14, 20, 23, 28], "[-": [6, 17], "\\langle": 6, "\\rangle": 6, "}xa": 6, ")f": 6, "tilde": 6, "\u3068\u304b\u3051": 6, "\\tilde": 6, "}(": 6, "= f": [6, 17], ")/": 6, "\u5bc6\u5ea6": 6, "\u6570\u5024": [6, 19], "\u6642\u78ba": 6, "\u7387\u5206": 6, "dots": 6, "_n": [6, 30], "cdots": 6, "\u70b9\u5217": 6, "\u3053\u3053": [6, 21, 24, 25, 27, 28, 29, 30, 31], "}{\\": 6, "')": 6, "\u3078\u306e": [6, 14, 19, 20, 21], "\u3068\u308a": [6, 20], "\uff08\u3064\u307e\u308a": 6, "\u666e\u901a": 6, "\u304a\u3051\u308b": [6, 20, 25, 30], "\u884c\u5217": [6, 8, 14, 27], "/ \\": 6, "\u5468\u8fba": 6, "prod": 6, "\u306b\u304a\u3051\u308b": 6, "\u5e73\u5747": 6, "rangle": 6, "\u62e1\u5f35": 6, "\u4ed8\u304d": 6, "\\begin": 6, "{split": 6, "langle": 6, "equiv": 6, "\\\\": [6, 14, 27], "end": [6, 14, 20, 24, 28, 29, 31], "\u3068\u8868\u305b": 6, "\u3055\u3066": 6, "\u6b8b\u5ff5": 6, "\u306a\u304c\u3089": 6, "\u56f0\u96e3": 6, "\u305d\u3053": 6, "\u3067\u3082\u3063\u3068": 6, "\u884c\u3048": 6, "\u6d41\u308c": 6, "\u5f93\u3063": [6, 7], "{g": 6, "\u306b\u5f93\u3044": 6, "left": [6, 14, 17, 20], "big": 6, "/\\": 6, "reweighting": 6, "method": 6, "\u3068\u306e": 6, "=\n\\": 6, "}{t": 6, "&=": 6, "}{f": 6, "&\\": 6, "\u3068\u304b\u3051\u308b": 6, "aw": 6, ",n": [6, 14], "\u7528\u3044\u308b": [6, 9, 14, 17, 20, 22, 25, 27, 28, 29, 30, 31, 32], "\u547c\u3073": 6, "\u306b\u5bfe\u3059\u308b": 6, "\u5927\u304d\u304f": 6, "\u5206\u6563": 6, "\u3057\u307e\u3044": 6, "\u5468\u671f": [6, 23], "(k": 6, "_k": 6, "\u5272\u5f53": 6, "\u30ea\u30bb\u30c3\u30c8": 6, "(w": 6, "\u64ec\u4f3c": [6, 8, 14, 25, 27, 30], "\u30b3\u30fc\u30c9": [6, 9, 32], "for": [6, 15, 20, 21], "in": [6, 20, 23, 28, 29], "range": 6, "):": [6, 8, 11, 12], "draw": [6, 28], "_from": [6, 16], "(\u03b2": 6, "])": [6, 12], "[i": 6, "= w": 6, "( f": 6, "],": [6, 9, 14, 15, 27], "\u03b2[": 6, "-1": 6, "if": [6, 24, 25, 27, 28, 29, 30, 32], ":]": 6, "resample": 6, ", w": 6, "transfer": 6, ",:": 6, "\u901a\u308a": [6, 23, 28, 31], "[1": [6, 15], "statistics": [6, 15], "and": [6, 15, 24, 25, 27, 28, 29, 30], "computing": [6, 15], ").": [6, 15, 24, 25, 27, 28, 29, 30], "[2": [6, 15], "hukushima": [6, 15], "iba": [6, 15], "aip": [6, 15], "conf": [6, 15], "proc": [6, 15], "[3": [6, 15], "machta": [6, 15], "pre": 6, "\u554f\u3044\u5408\u308f\u305b": 7, "\u3053\u3061\u3089": 7, "\u306b\u304a\u5bc4\u305b\u304f": 7, "\u30d0\u30b0": 7, "\u5831\u544a": 7, "github": [7, 21, 22, 31], "issues": 7, "\u53d7\u3051\u4ed8\u3051": 7, "\u65e9\u671f": 7, "\u30ac\u30a4\u30c9\u30e9\u30a4\u30f3": 7, "\u30d0\u30fc\u30b8\u30e7\u30f3": [7, 13, 22], "\u30aa\u30da\u30ec\u30fc\u30c6\u30a3\u30f3\u30b0\u30b7\u30b9\u30c6\u30e0": 7, "\u30b3\u30f3\u30d1\u30a4\u30e9": 7, "\u77e5\u3089": 7, "\u305b\u304f": 7, "\u751f\u3058": 7, "\u5165\u529b": [7, 8, 9, 11, 12, 13, 16, 23, 31, 32], "\u30d5\u30a1\u30a4\u30eb": [7, 8, 9, 11, 12, 13, 23, 31, 32], "\u51fa\u529b": [7, 8, 9, 11, 13, 14, 23, 24, 25, 28, 29, 30, 31], "\u30c8\u30d4\u30c3\u30af": 7, "\u76f8\u8ac7": 7, "\u3057\u3065\u3089\u3044": 7, "\u554f\u3044\u5408\u308f\u305b\u308b": 7, "\u9023\u7d61": 7, "\u30b3\u30f3\u30bf\u30af\u30c8": 7, "-mail": 7, "-dev": [7, 22], "__": [7, 8, 11, 32], "at": [7, 32], "issp": 7, ".u": 7, "-tokyo": 7, ".ac": 7, ".jp": 7, "(_": 7, "\u5909\u66f4": [7, 24, 29], "\u30af\u30e9\u30b9": [8, 9, 11, 12, 32], ".algorithm": [8, 12], ".algorithmbase": [8, 12], "\u7d99\u627f": [8, 11], "import": [8, 11, 12], "class": [8, 11, 12], "(py": [8, 11, 12], "pass": [8, 11, 12, 24, 25, 27, 28, 29, 30], "\u30e1\u30bd\u30c3\u30c9": [8, 9, 11], "_init": [8, 11, 32], "self": [8, 11, 32], "info": [8, 9, 11, 12], "py2dmat": [8, 9, 11, 12, 25], ".info": [8, 11, 12], "runner": [8, 9, 12, 13, 14, 27], ".runner": [8, 12], "none": [8, 9, 11, 20], "\u5171\u901a": [8, 10, 13], "\u8aad\u307f\u53d6\u308a": [8, 11], "\u30a4\u30f3\u30b9\u30bf\u30f3\u30b9": [8, 9, 11], ".mpicomm": 8, "optional": [8, 22], "[mpi": 8, ".comm": 8, "_world": 8, "\u5931\u6557": 8, ".mpisize": 8, ".mpirank": [8, 11], "\u30e9\u30f3\u30af": [8, 16, 19, 20, 21, 24, 25, 27, 29, 30], ".rng": 8, "np": [8, 9, 23, 25, 27, 29, 30, 32], ".random": 8, ".generator": 8, "\u4e71\u6570": [8, 14, 25, 27, 30], "\u30bb\u30af\u30b7\u30e7\u30f3": [8, 13, 16, 17, 24, 25, 26, 27, 28, 29, 30, 32], ".dimension": [8, 14], ".label": 8, "list": [8, 21, 23], "[str": 8, "\u540d\u524d": [8, 14, 21, 23, 24, 28, 29], ".root": [8, 11], "_dir": [8, 9, 11, 14, 19, 20, 23, 27, 30, 32], "pathlib": [8, 9, 11], ".path": [8, 9, 11], "\u30eb\u30fc\u30c8\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": [8, 9, 11], ".base": [8, 11], "[\"": [8, 9, 11, 20, 24, 25, 28, 29, 30], "root": [8, 9, 11, 14], "\"]": [8, 9, 11, 20, 24, 25, 28, 29, 30], ".output": [8, 11], "\u66f8\u304d\u51fa\u3059": [8, 11], "\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": [8, 9, 11, 14, 19, 20, 23, 24, 25, 27, 28, 29, 30], ".proc": [8, 11], "\u4f5c\u696d": [8, 11, 20, 31], "str": [8, 11], "(self": [8, 9, 11], ".timer": 8, "dict": [8, 9], "\u4fdd\u5b58": [8, 11, 20, 23, 24, 28], "\u8f9e\u66f8": [8, 12], "\"prepare": 8, "\"run": 8, "\"post": 8, "prepare": [8, 11, 16, 24, 25, 28, 29, 30], "->": [8, 9, 11, 15, 32], "\u6700\u9069\u5316": [8, 21], "\u524d\u51e6": [8, 16], ".run": 8, "()": [8, 9, 11, 12], "run": [8, 11, 16], "._": 8, "\u623b\u308a": 8, "post": [8, 16, 20, 21], "\u5316\u7d50": 8, "\u5f8c\u51e6": [8, 16], "\u306e\u3042\u3068": 8, "main": 8, "\u304b\u304b\u3063": [8, 16], "\u8a08\u6e2c": 8, "_read": 8, "_param": 8, "tuple": 8, "[np": 8, ".ndarray": [8, 9, 32], "\u30d8\u30eb\u30d1\u30fc\u30e1\u30bd\u30c3\u30c9": 8, "\u53d6\u5f97": [8, 23], "_search": [8, 9], "_mesh": 8, "_grid": 8, "split": 8, "bool": [8, 21], "false": [8, 14, 20, 21, 24, 25, 27, 28, 29, 30], "\u8aad\u307f\u53d6\u308a\u6b21": 8, "nxd": 8, "id": [8, 24, 25, 29, 30], "(index": 8, "\u70b9\u96c6": 8, "\u914d\u3089\u308c": 8, "\u5c11\u306a\u304f": [8, 11], "\u3068\u3082": [8, 11, 14], "\u306a\u3051\u308c": [8, 11], "\u5f15\u6570": [8, 9, 23], "\u307e\u307e": [8, 9, 14, 23], "\u30b3\u30f3\u30b9\u30c8\u30e9\u30af\u30bf": [8, 9, 11, 32], "\u8ee2\u9001": 8, "super": [8, 11], ".__": [8, 11], "init": [8, 11], "=info": 8, "=runner": 8, "_prepare": 8, "\u8a18\u8ff0": [8, 14], "_run": 8, "\u5f97\u308b": 8, "message": [8, 9, 11], ".message": [8, 11], "set": [8, 9, 20], ".submit": [8, 9], "(message": [8, 9], "_post": 8, "\u4e8b\u67c4": 9, "\u6271\u3046": 9, "4\u3064": 9, "base": [9, 13, 14], "\u30d7\u30ed\u30b0\u30e9\u30e0": [9, 12, 14, 20, 22, 26, 31], "\u6301\u3064": [9, 24, 30], "\u6e21\u3057": [9, 14, 23], "\u5316\u51fa": 9, "\u8981\u7d20": [9, 14], "output": [9, 11, 14, 20, 23, 27, 30, 31, 32], "\u7d76\u5bfe\u30d1\u30b9": 9, "\u5909\u63db": [9, 11, 14], "\u3042\u3089": 9, "\u5148\u982d": [9, 20], "\u30db\u30fc\u30e0\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": 9, "\u5c55\u958b": [9, 19], "\u30c7\u30d5\u30a9\u30eb\u30c8": [9, 27, 28], "\u30ab\u30ec\u30f3\u30c8\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": 9, ".\"": 9, "\u5177\u4f53": [9, 14, 25, 28, 29, 30], "(base": 9, ".get": 9, "(\"": 9, "))": [9, 31], ".expanduser": 9, "absolute": 9, "\u76f8\u5bfe\u30d1\u30b9": 9, "\u8d77\u70b9": [9, 14], "\u76f8\u5bfe": 9, "\u89e3\u91c8": 9, "\u3064\u307e\u308a": 9, "work": [9, 31], "\u4ecb\u3057": 9, "\u6e21\u3055": 9, "\u500b\u76ee": 9, "\u901a\u3057": [9, 16, 24, 29], "\u5de1\u76ee": 9, "\u518d\u8a08": 9, "\u3092\u3064\u306a\u3052\u308b": 9, "\u30eb\u30fc\u30c1\u30f3": 9, "mapping": [9, 13, 14], "callable": 9, "[[": [9, 21], "\u53d6\u308a": 9, "submit": [9, 16], "float": [9, 11, 20, 21, 23, 32], "\u5f97\u305f\u3044": 9, "\u7701\u7565": [9, 14, 20, 28], "\u30a2\u30d5\u30a3\u30f3": [9, 14], "\u5199\u50cf": [9, 14], "=ax": 9, "+b": [9, 14, 27], ".util": 9, ".mapping": 9, ".affine": 9, "\u4e0e\u3048": [9, 15, 20, 21, 23, 24, 26, 29], "\u7d44\u307f\u5408\u308f": 10, "\u9006\u554f": [10, 26, 28], "\u89e3\u304d": 10, "\u306f\u3059\u3067": 10, "\u6e08\u307f": [10, 12, 22], "\u81ea\u5206": [10, 23, 26], "\u9069\u7528": [10, 13, 15, 20, 26], "\u7bc4\u56f2": [10, 14, 24, 25, 26, 27, 28, 29, 30], "\u5e83\u3052": 10, "\u672c\u7ae0": 10, "\u89e3\u8aac": 10, "\u4e8b\u9805": [10, 13], ".solver": [11, 12], ".solverbase": [11, 12], "\u5fc5\u305a": 11, "\u547c\u3073\u51fa\u3057": [11, 14, 16], ".work": 11, "\u306b\u3088\u3073": 11, "\u542b\u307e": 11, "nthreads": 11, "\u5f8c\u307b\u3069": 11, "get": [11, 23], "_results": 11, "\u8aad\u307f": [11, 24, 28, 29], "\u53d6\u308c\u308b": 11, "\u3042\u3068": [11, 21, 23, 24, 25, 27, 28, 29, 30], "\u547c\u3073\u51fa\u3055": [11, 20, 21], "\u8fd4\u5374": 11, "\u8aad\u307f\u53d6\u308b": 11, "\u30d5\u30ed\u30fc": 12, "\u30e6\u30fc\u30b6": [12, 32], "\u3082\u3061\u308d\u3093": 12, "toml": [12, 14, 23], "\u3064\u304f\u308c\u308c": 12, "\u3067\u3082": 12, "\u69cb\u3044": 12, ".main": 12, "sys": 12, "tomli": [12, 22], "define": 12, "your": 12, "with": 12, "open": [12, 25, 27, 30], "(sys": 12, ".argv": 12, "as": [12, 20], "inp": 12, ".load": 12, "(f": 12, "(inp": 12, "(info": 12, "(solver": 12, "\u306f\u3058\u3081": 13, "\u30e9\u30a4\u30bb\u30f3\u30b9": 13, "\u5c65\u6b74": 13, "\u74b0\u5883": [13, 21], "\u30d1\u30c3\u30b1\u30fc\u30b8": [13, 23], "\u30c0\u30a6\u30f3\u30ed\u30fc\u30c9": [13, 19, 20, 21, 24, 25, 27, 28, 29, 30, 32], "\u30a2\u30f3\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": 13, "trhepd": [13, 14, 15, 22, 26], "\u578b\u63a2": [13, 15, 26], "\u7d04\u5f0f": [13, 26], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0": [13, 26], "limitation": [13, 14, 27], "analytical": [13, 14, 18, 27, 32], "-trhepd": [13, 14, 18, 22, 24, 25, 28, 29, 30, 31], "-rheed": [13, 14, 18, 22, 24, 25, 28, 29, 30, 31], "sxrd": [13, 15, 18, 22], "leed": [13, 15, 18, 22], "tool": 13, "/to": 13, "_dft": 13, ".py": [13, 22, 24, 25, 27, 28, 29, 30, 31, 32], "\u5411\u3051": [13, 19, 22], "\u30e6\u30fc\u30b6\u30fc": [13, 15, 20, 22], "\u8b1d\u8f9e": 13, "\u304a\u554f\u3044": 13, "\u5408\u308f": 13, "\u63a1\u7528": [14, 23], "6\u3064": 14, "\u69cb\u6210": [14, 23], "logging": 14, "\u306b\u95a2\u3057": [14, 27], "\u4e00\u756a\u4e0a": [14, 23], "\u3059\u3079": 14, "\u3057\u307e\u3059": [14, 24, 28, 29, 31], "name": [14, 21, 24, 25, 27, 28, 29, 30, 32], "\u7a2e\u985e": [14, 21], "\u53cd\u5c04": [14, 20, 26, 31], "\u9ad8\u901f": [14, 23, 26, 31], "(\u967d": [14, 31], "\u96fb\u5b50": [14, 15, 23, 26, 31], "\u56de\u6298": [14, 15, 20, 24, 25, 26, 28, 29, 30, 31], "(rheed": [14, 26, 31], "\u5f37\u5ea6": [14, 20, 21, 28, 31], "\u89e3\u6790\u89e3": 14, "\u30c6\u30b9\u30c8": [14, 31, 32], "\u5404\u7a2e": [14, 16, 23], "\u5165\u51fa": 14, "\u5024\u63a2": 14, "seed": [14, 25, 27, 30, 32], "\u5404mpi": 14, "_rank": 14, "_delta": 14, "\u7a2e\u3068\u3057\u3066": 14, "numpy": [14, 22, 23], "\u898f\u5b9a": 14, "\u7591\u4f3c": 14, "\u6a4b\u6e21": 14, "ne": 14, "\u5e73\u884c": 14, "ax": [14, 27], "\u3042\u308b\u3044": 14, "\u6587\u5b57\u5217": [14, 20, 28], "[]": [14, 20], "times": 14, "\u3002\u7a7a": 14, "\u307f\u306a\u3055": [14, 23], "\u7a7a\u767d": [14, 23], "\u6539\u884c": 14, "\u533a\u5207\u3063": 14, "\u4e26\u3079": [14, 23], "\u4e26\u9032": 14, "\u30d9\u30af\u30c8\u30eb": [14, 21, 23, 27], "\u30bc\u30ed\u30d9\u30af\u30c8\u30eb": 14, "\u533a\u5207\u308a": [14, 23], "]]": [14, 21, 23, 27], "\"\"": [14, 32], "begin": 14, "{matrix": 14, "\u8868\u3057": [14, 20, 21], "\u51fa\u6765": [14, 31], "\uff08\u4f8b": 14, "\u52a0\u3048": 14, ":math": 14, "math": 14, "+ a": 14, "&..": 14, "+ b": 14, "\u304b\u3051\u308b": 14, "\u500b\u6570": [14, 19, 21, 24, 25, 27, 28, 29, 30], "\u4efb\u610f": 14, "co": [14, 27], "_a": [14, 27], "\u884c\u6570": [14, 20, 24, 28, 29], "\u5f0f\u6570": 14, "\u5217\u6570": 14, "_b": [14, 27], "\u3001[": [14, 20], "\u3002\u307e\u305f": 14, "\u306e\u3069\u3061\u3089": 14, "\u8ab2\u3055\u305a": 14, "filename": 14, ".log": 14, "\u30ed\u30b0\u30d5\u30a1\u30a4\u30eb": 14, "\u56de\u547c": 14, "\u30ed\u30b0": [14, 16], "\u66f8\u304d\u51fa\u3055": 14, "\u66f8\u304d\u51fa\u3057": 14, "write": 14, "_result": [14, 25, 27, 30], "\u8a18\u9332": [14, 25, 30], "_input": [14, 20], "\u30d5\u30ec\u30fc\u30e0\u30ef\u30fc\u30af": 15, "\u81ea\u8eab": [15, 21, 23], "\u9806\u554f": [15, 22, 26, 32], "\u5143\u7269": 15, "\u8cea\u69cb": 15, "\u9020\u89e3": 15, "\u6790\u5411": 15, "\u5b9f\u9a13": [15, 19, 20, 21, 24, 25, 26, 28, 29, 30], "\u89e3\u6790": [15, 22, 24, 25, 26, 28, 29, 30, 31, 32], "\u539f\u5b50": [15, 19, 20, 21, 23, 24, 25, 26, 28, 29, 30], "\u4f4d\u7f6e": [15, 19, 20, 21, 23, 28], "\u306e\u305a\u308c": 15, "\u640d\u5931": 15, "\u7d44\u307f\u5408\u308f\u305b": [15, 22], "\u63a8\u5b9a": [15, 24, 25, 26, 28, 29, 30], "\u91cf\u5b50": 15, "\u30d3\u30fc\u30e0": [15, 20], "\u5168\u53cd": 15, "\u5c04\u9ad8": 15, "\u901f\u967d": 15, "\uff08total": 15, "-reflection": 15, "high": 15, "-energy": 15, "positron": [15, 31], "diffraction": [15, 21], "\u30c8\u30ec\u30d7\u30c8": 15, "\uff09[": 15, "\u7d22\u6cd5": 15, "11": 15, "\u4eca\u5f8c": 15, "\u3082\u3068": 15, "\u306b\u3088\u308a": [15, 19, 23, 24, 28, 29], "\u4e88\u5b9a": 15, "\u30ec\u30d3\u30e5\u30fc": 15, "\uff0efukaya": 15, "et": 15, "al": 15, ".,": 15, "phys": [15, 31], "appl": [15, 31], "\u5175\u982d": 15, "\u4fca\u592b": 15, "\uff0c\u300c": 15, "\u8868\u9762": [15, 20, 23, 28, 31], "\u69cb\u9020": [15, 20, 23, 28, 31], "\u300d\uff0c": 15, "\u56fa\u4f53": 15, "\u7269\u7406": 15, "hanada": 15, "motoyama": 15, "yoshimi": 15, "hoshi": 15, "computer": 15, "physics": 15, "communications": 15, "akimoto": 15, "aoyama": 15, "sumitani": 15, "nakatani": 15, "tajiri": 15, "takahashi": 15, "hisada": 15, "mukainakano": 15, "zhang": 15, "sugiyama": 15, "kawata": 15, "applied": 15, "surface": [15, 19, 20, 21], "science": [15, 19], "[4": 15, "van": [15, 19], "hove": [15, 19], "moritz": [15, 19], "over": [15, 19], ".j": [15, 19], "rous": [15, 19], "wander": [15, 19], "barbieri": [15, 19], "materer": [15, 19], "starke": [15, 19], "somorjai": [15, 19], "automated": [15, 19], "determination": [15, 19], "complex": [15, 19], "structures": [15, 19], "by": [15, 19, 20], "reports": [15, 19], "volume": [15, 19], "[5": 15, "tanaka": 15, "mochizuki": 15, "ichimiya": [15, 31], "hyodo": 15, "acta": 15, "pol": 15, "[6": 15, "jjap": 15, "series": 15, "[7": 15, "tamura": 15, "terayama": 15, "ueno": 15, "tsuda": 15, "[8": 15, "nemoto": 15, "soc": 15, "japan": 15, "swendsen": 15, "wang": 15, "rev": 15, "lett": 15, "[9": 15, "10": 15, "\u30d7\u30ed\u30b0\u30e9\u30e0\u30d1\u30c3\u30b1\u30fc\u30b8": 15, "\u30bd\u30fc\u30b9\u30b3\u30fc\u30c9": [15, 19, 20, 21, 22, 31, 32], "\u4e00\u5f0f": [15, 19, 20, 21, 31], "gnu": 15, "general": 15, "public": 15, "license": 15, "version": [15, 21], "gpl": 15, "\u6e96\u3058": 15, "\u914d\u5e03": 15, "copyright": 15, "the": [15, 20, 21], "university": 15, "tokyo": 15, "all": 15, "rights": 15, "reserved": 15, "\u5f15\u7528": [15, 23], "\u6587\u732e": 15, "\u201cdata": 15, "-analysis": 15, "software": 15, "framework": 15, "its": 15, "application": 15, "to": [15, 21, 23], "experimental": [15, 21], "measurements": 15, "two": 15, "-dimensional": 15, "material": 15, "\u201d,": 15, "iwamoto": 15, "ichinose": 15, "bibtex": 15, "@article": 15, "{motoyama": 15, "title": 15, "data": 15, "journal": 15, "pages": 15, "year": 15, "issn": 15, "doi": [15, 19], "https": [15, 19, 21, 22], ":/": [15, 19, 21, 22, 31], ".org": [15, 19], ".cpc": 15, "url": [15, 21], "www": [15, 19], ".sciencedirect": 15, ".com": [15, 21, 22, 31], "/science": 15, "/article": 15, "/pii": 15, "/s": 15, "author": 15, "yuichi": 15, "kazuyoshi": 15, "izumi": 15, "harumichi": 15, "hayato": 15, "takeo": 15, "\u30e1\u30f3\u30d0\u30fc": 15, "\u672c\u5c71": 15, "\u88d5\u4e00": 15, "\u7814\u7a76\u6240": 15, "\u5409\u898b": 15, "\u4e00\u6176": 15, "\u5ca9\u672c": 15, "\u6674\u9053": 15, "\u9ce5\u53d6": 15, "\u5927\u5b66\u9662": 15, "\u5de5\u5b66": 15, "\u5065\u592b": 15, "\u30b5\u30d6\u30d5\u30a9\u30eb\u30c0": [16, 24, 25, 29, 30], "#prepare": 16, "total": [16, 20], "file": 16, "_cm": 16, ".interval": 16, "\u524d\u56de": 16, "_calls": 16, "elapsed": 16, "_time": 16, "_last": [16, 20, 24, 25, 28, 29, 30], "_call": 16, "_start": 16, "\u6027\u80fd": 17, "\u5b9a\u7fa9\u6e08": [17, 22], "\u30d9\u30f3\u30c1\u30de\u30fc\u30af": 17, "funtion": 17, "_name": [17, 23, 27, 32], "\u9078\u3079": 17, "quadratics": 17, "\u4e8c\u6b21": 17, "\u6700\u9069\u5024": 17, "*)": 17, "quad": 17, "forall": 17, "^*": 17, "rosenbrock": 17, "- x": 17, ")^": [17, 20, 32], "ackley": 17, "sqrt": [17, 20], "- \\": 17, "[\\": 17, "cos": 17, "\\right": 17, "himmerblau": 17, "= (": [17, 32], "+y": [17, 32], "\u305f\u3044": [18, 19, 20, 21, 24, 25, 27, 28, 29, 30], "satleed": [19, 22], "rocking": [19, 20, 21], "curve": [19, 20, 21], "[satleed": 19, "\u3092\u3054\u89a7\u304f": 19, "http": [19, 31], ".icts": 19, ".hkbu": 19, ".edu": 19, ".hk": 19, "/vanhove": 19, "_files": 19, "/leed": 19, "/leedsatl": 19, ".zip": 19, "\u30a2\u30af\u30bb\u30b9": [19, 21], "zip": [19, 21], "\u3002zip": 19, "\u6240\u5b9a": 19, "\u624b\u7d9a\u304d": 19, "\u5f93\u3044": [19, 21, 24, 25, 29, 30], "\u30b3\u30f3\u30d1\u30a4\u30eb": 19, "stal": 19, "exe": 19, "satl": 19, "satled": 19, "\u9069\u5b9c": [19, 23], "\u66f8\u304d": [19, 28], "\u63db\u3048\u308b": 19, "sample": [19, 24, 25, 27, 28, 29, 30, 31], "/py": [19, 22, 23, 24, 25, 27, 28, 29, 30, 32], "\u63db\u3048": [19, 20, 28], "\u30b9\u30af\u30ea\u30d7\u30c8": [19, 24, 25, 27, 28, 29, 30], "setup": 19, ".sh": [19, 24, 25, 27, 28, 29, 30], "cd": [19, 24, 25, 27, 28, 29, 30, 31], "sh": [19, 24, 25, 28, 29, 30], "leedsatl": 19, "\u3042\u305f\u3063": 19, "\u524d\u63d0": [19, 31], ".d": 19, "rfac": 19, "tleed": 19, ".o": 19, "short": 19, ".t": 19, "\u306f\u3053\u308c\u3089": 19, "\u3082\u3061\u3044": 19, "config": [19, 20, 21], "reference": [19, 20, 21], "path": [19, 20, 24, 25, 28, 29, 30], "_to": 19, "_solver": 19, "_base": 19, "\u683c\u7d0d": [19, 20, 21, 24, 25, 27, 28, 29, 30], "\u7de8\u96c6": [19, 21, 32], "optxxx": 19, "(xxx": 19, "\u4e09\u6841": 19, "\u306a\u304a": [19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30], "xxx": [19, 25, 28, 30], "\u6570\u5b57": [19, 31], "\u5165\u308c\u308b": 19, "iflag": 19, "lsflag": 19, "ipr": 19, "istart": 19, "lrflag": 19, "nsym": 19, "nsyms": 19, "astep": 19, "vstep": 19, "nt0": 19, "nset": 19, "lsmax": 19, "llcut": 19, "ninset": 19, "pqex": 19, "ndim": 19, "opt": [19, 21], "disp": 19, "dvopt": 19, "mflag": 19, "ngrid": 19, "niv": 19, "\u8a08\u7b97\u6642": [19, 21], "\u30d5\u30a9\u30eb\u30c0": [19, 20, 21, 23, 24, 25, 27, 28, 29, 30, 31], "\u30b5\u30a4\u30c8": [20, 21], "/src": [20, 24, 25, 27, 28, 29, 30, 31], "make": [20, 21, 31], "bulk": [20, 21, 23, 24, 25, 28, 29, 30, 31], ".exe": [20, 24, 25, 28, 29, 30, 31], "surf": [20, 23, 24, 25, 28, 29, 30, 31], "\u30d0\u30eb\u30af\u30c7\u30fc\u30bf": [20, 21], "\u304a\u304d": 20, "generate": 20, "_rocking": 20, "_curve": 20, "%%": [20, 24, 25, 29, 30], "%_": 20, "##": 20, "\u30aa\u30d7\u30b7\u30e7\u30f3": [20, 22, 23, 24, 25, 27, 28, 29, 30], "\"true": 20, "\u3067\u3042\u3063": 20, "remove": 20, "_work": 20, "\uff08[": 20, "\u3042\u308c": 20, "\u524a\u9664": 20, "\u3057\u307e\u3046": 20, "_exec": [20, 21], "_file": [20, 21, 23], "\u30a4\u30f3\u30d7\u30c3\u30c8\u30d5\u30a1\u30a4\u30eb": [20, 21], "_output": 20, "bulkp": [20, 24, 25, 28, 29, 30, 31], ".b": [20, 24, 25, 28, 29, 30, 31], "\u30d0\u30eb\u30af": [20, 28, 31], "\u30a2\u30a6\u30c8\u30d7\u30c3\u30c8\u30d5\u30a1\u30a4\u30eb": 20, "-bulkp": [20, 31], ".s": [20, 31], "calculated": [20, 24, 25, 28, 29, 30], "_first": [20, 24, 25, 28, 29, 30], "_line": [20, 24, 25, 28, 29, 30], "\u8aad\u307f\u8fbc\u3080": [20, 24, 28, 29], "\u6700\u7d42\u884c": 20, "\u8aad\u307f\u8fbc\u3093": 20, "_info": 20, "glancing": 20, "angle": [20, 23], "beam": 20, "\u8a18\u3057": [20, 25, 27, 30], "\u884c\u756a": 20, "cal": 20, "_number": [20, 24, 25, 28, 29, 30], "\u8aad\u307f\u51fa\u3059": 20, "\u5217\u756a": 20, "\u5f8c\u8ff0": [20, 21, 28], "\u300c\u30ba\u30ec": 20, "\u5927\u304d\u3055": [20, 23], "\u793a\u3057": [20, 25, 27, 30], "\u3059\u3079\u304d": 20, "\u300c\u76ee": 20, "\u7684\u95a2\u6570": 20, "\u30ed\u30c3\u30ad\u30f3\u30b0\u30ab\u30fc\u30d6": [20, 21, 25, 28, 30, 31], "\u63cf\u304f": 20, "\u30b3\u30f3\u30dc\u30ea\u30e5\u30fc\u30b7\u30e7\u30f3": [20, 31], "\u534a\u5024": [20, 31], "rfactor": [20, 21], "_type": 20, "string\u578b": 20, "\u3002\"": 20, "\"\u3001": 20, "\"a2": 20, "\"b": 20, "\u306e\u3044\u305a\u308c": 20, "\"a": 20, "\u8996\u5199\u89d2": 20, "\\dots": 20, "(j": 20, "\u30bf\u30a4\u30d7": 20, "{n": 20, "{m": 20, "(u": 20, "}-": 20, "+ \\": 20, "(v": 20, "normalization": 20, "\"many": 20, "_beam": [20, 24, 25, 28, 29, 30], "\u30c7\u30fc\u30bf\u30d9\u30af\u30c8\u30eb": 20, "\"total": 20, "\u5316\u65b9": 20, "\u6709\u308a": 20, "\u5909\u308f\u308a": 20, "\u5ec3\u6b62": 20, "calc": [20, 23], "\"manual": 20, "\u306e\u3044\u305a\u308c\u304b": 20, "many": 20, "(n": 20, "spot": 20, "_weight": 20, "manual": 20, "\u7dcf\u548c": 20, "\u3068\u306a\u308a": 20, "omega": 20, "\u8aad\u307f\u53d6\u3063": 20, "([": 20, "value": [20, 24, 25, 27, 28, 29, 30], "\u30d7\u30ec\u30fc\u30b9\u30db\u30eb\u30c0\u30fc": 20, "\u6587\u5b57": 20, "\u7f6e\u63db": [20, 23], "experiment": [20, 24, 25, 28, 29, 30], "\u30c7\u30fc\u30bf\u30d5\u30a1\u30a4\u30eb": [20, 24, 28, 29], "\u3059\u306a\u308f\u3061": 20, "\u8aad\u307f\u51fa\u3057": 20, "\u524d\u8ff0": 20, "template": [20, 24, 25, 28, 29, 30], "\u30c6\u30f3\u30d7\u30ec\u30fc\u30c8": 20, "_*": [20, 28], "\u7f6e\u304d": 20, "nelms": [20, 28], "--": [20, 21, 28], "ge": [20, 28], ")-": [20, 28, 31], "4x": [20, 28], "da": [20, 28], "sap": [20, 28], "bh": [20, 28], "(i": [20, 28], "),": [20, 28], "bk": [20, 28], "bz": [20, 28], "nsgs": [20, 28], "msa": [20, 28], "msb": [20, 28], "nsa": [20, 28], "nsb": [20, 28], "dthick": [20, 28], "dxs": [20, 28], "dys": [20, 28], "natm": [20, 28], "ielm": [20, 28], "ocr": [20, 28], ",(wdom": [20, 28], "ndom": [20, 28], "\u4e00\u5217": 20, "\u89d2\u5ea6": [20, 23, 24, 28, 29, 31], "\u5165\u3063": [20, 28], "(\u4f8b": 20, "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u30b9\u30c6\u30c3\u30d7": [20, 25, 27, 30], "\u30b0\u30eb\u30fc\u30d7": 20, "\u5927\u898f\u6a21": 20, "\u30b9\u30c8\u30ec\u30fc\u30b8": 20, "\u5236\u9650": [20, 26], "\u5f15\u3063": 20, "\u305d\u306e\u3088\u3046": 20, ".post": 20, ".remove": 20, "\u306b\u3057": 20, "\u7d42\u4e86": 20, "\u72ec\u81ea": [20, 21], "-filename": [20, 31], "=e": [20, 31], "structure": [20, 21, 23, 31], "\u5192\u982d": [20, 27], "`,": 20, "``": [20, 24, 28, 29], "\u90e8\u5206": [20, 27, 28, 31], "\u3069\u306e": 20, "\u8a18\u3055": 20, "glanceing": 20, "_angle": 20, "\u4ed8\u3044": 20, "\u8868\u8a18": 20, "\u8996\u5199": 20, "\u3002\u3069": 20, "\u76f8\u5f53": [20, 26, 28], "\u5404\u5217": 20, "\uff08r": 20, "\u53ca\u3073": [20, 31], "\u7b97\u51fa": 20, "\u52a0\u5473": 20, "#value": 20, "notice": 20, "intensities": [20, 21], "are": 20, "not": [20, 21, 23], "multiplied": 20, "intensity": 20, "_(": 20, "each": 20, "is": [20, 23], "normalized": 20, "following": 20, "equation": 20, "sxrdcalc": [21, 22], "\u5360\u6709": 21, "\u30c7\u30d0\u30a4\u30ef\u30e9\u30fc": 21, "\u516c\u958b": 21, "/sxrdcalc": 21, "code": 21, "\u300d-": 21, "download": 21, "\u89e3\u51cd": 21, "makefile": 21, "\u5408\u3046": 21, "\u30b3\u30de\u30f3\u30c9": [21, 22, 23, 25, 27, 29, 30], "\u6253\u3064": [21, 27], "\u30d5\u30a9\u30fc\u30de\u30c3\u30c8": 21, "\u3054\u89a7\u304f": [21, 24, 28, 29], "_struc": 21, "_in": 21, "/..": [21, 24, 25, 27, 28, 29, 30, 31], "sic": 21, "3xr": 21, "blk": 21, "scale": 21, "_factor": 21, "\u30b7\u30df\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3": [21, 26], "\u30b9\u30b1\u30fc\u30eb": [21, 23], "\u30d5\u30e9\u30b0": 21, "type": 21, "_vector": 21, "\u672c\u30ea\u30b9\u30c8": 21, "\u540c\u3058": [21, 23, 24, 25, 27, 28, 29, 30], "\u53d6\u308a\u6271\u308f": 21, "\u30c9\u30e1\u30a4\u30f3": 21, "\u30b5\u30d6\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3": 21, "domain": 21, "_occupancy": 21, "\u6240\u5c5e": 21, "\u5206\u5b9a": 21, "\u8868\u3059": [21, 23, 25, 27, 28, 30], "\u91cd\u8907\u53ef": 21, "pos": [21, 23], "_center": 21, "\u3002[": 21, "dwfactor": 21, "\\text": 21, "{\u00e5": 21, "occupancy": 21, "displace": 21, "(\u7701\u7565\u53ef": 21, "\u5909\u4f4d": 21, "[type": 21, "(type": 21, "dr": 21, "(d": 21, "{a": [21, 23], "+ d": 21, "{b": 21, "{c": 21, "\u3082\u3057\u304f": [21, 23], "struc": 21, "\u683c\u5b50": [21, 23], "_dw": 21, "\u5909\u5316": [21, 30], "si": [21, 23, 31], "sigma": 21, "\u6ce2\u6570": 21, "\u4e0d\u78ba": 21, "\u304b\u3055": 21, "alpha": 21, "gamma": 21, "\u30e6\u30cb\u30c3\u30c8\u30bb\u30eb": 21, "\u5b9a\u6570": 21, "\u306f\u305d\u308c\u3089": 21, "\u306a\u3059": 21, "atomsymbol": 21, "least": 21, "square": 21, "fitting": 21, "\u30b7\u30e7\u30c3\u30c8": 21, "(iteration": 21, "fit": 21, "results": 21, "program": 21, "/mapper": [21, 29], "_sxrd": 21, "-ray": 21, "calculations": 21, "august": 21, "inputfile": 21, "lsfit": 21, ".in": 21, "-squares": 21, "factors": 21, "converged": 21, "after": 21, "iterations": [21, 32], "consider": 21, "increasing": 21, "maximum": 21, "or": [21, 23], "find": 21, "better": 21, "starting": 21, "values": 21, "chi": 21, "degree": [21, 23, 24, 25, 28, 29, 30], "freedom": 21, "factor": 21, "/-": 21, "parameter": [21, 24], "nr": 21, "covariance": 21, "matrix": 21, ">=": 22, "\u6cd5\u5229": 22, "\u7528\u6642": 22, "\u5316\u5229": 22, "ver": 22, "\u4e0b\u8a18": 22, "\u793a\u3059": 22, "pypi": 22, "\u63a8\u5968": 22, "-user": 22, "\u3064\u3051\u308b": 22, "\u30ed\u30fc\u30ab\u30eb": 22, "$home": 22, "/.": 22, "local": 22, "[all": 22, "git": [22, 31], "clone": [22, 31], "/issp": 22, "-center": 22, "\u30b5\u30f3\u30d7\u30eb\u30d5\u30a1\u30a4\u30eb": 22, "\u540c\u68b1": 22, "\u5225\u9014": 22, "input": [22, 23, 24, 25, 27, 28, 29, 30, 31, 32], ".toml": [22, 23, 24, 25, 27, 28, 29, 30, 32], "\u6e96\u5099": [22, 24, 25, 27, 28, 29, 30, 31, 32], "\u6539\u9020": [22, 32], "src": [22, 23, 28, 32], "_main": [22, 24, 25, 27, 28, 29, 30, 32], "uninstall": 22, "\u8fd1\u508d": 23, "\u30e1\u30c3\u30b7\u30e5": [23, 29], "bin": [23, 27], "-o": 23, ".txt": [23, 24, 25, 27, 28, 29, 30, 31], "meshdata": [23, 24, 29], "-output": 23, "-u": 23, "-unit": 23, "\u3059\u3079\u3066": 23, "\u3067\u304f\u304f\u3063": 23, "\u9664\u7b97": 23, "-r": 23, "radius": 23, "-radius": 23, "\u30e6\u30fc\u30af\u30ea\u30c3\u30c9": 23, "\u8ddd\u96e2": 23, "\u9664\u3055": 23, "-q": 23, "-quiet": 23, "\u9032\u6357\u30d0\u30fc": 23, "\u8868\u793a": 23, "\u9032\u6357": 23, "\u30d0\u30fc": 23, "tqdm": 23, "-allow": 23, "-selfloop": 23, "\u96a3\u63a5": 23, "\u542b\u3081": 23, "\u81ea\u5df1": 23, "\u30eb\u30fc\u30d7": 23, "-check": 23, "-allpairs": 23, "\u70b9\u5bfe": 23, "\u30c7\u30d0\u30c3\u30b0": 23, "\u672c\u30c4\u30fc\u30eb": 23, "\u56db\u9762": 23, "\u4f53\u69cb": 23, "\u30dc\u30f3\u30c9\u30cd\u30c3\u30c8\u30ef\u30fc\u30af": 23, "\u6709\u3059\u308b": 23, "\u4e00\u539f": 23, "\u7406\u96fb\u5b50": 23, "\u72b6\u614b": 23, "quantum": 23, "espresso": 23, "qe": 23, "\u59a5\u5f53": 23, "\u6027\u691c": 23, "\u5fae\u8996": 23, "\u6ce8\u76ee": 23, "\u53cd\u5bfe": 23, "\u751f\u3058\u308b": 23, "\u30c0\u30f3\u30b0\u30ea\u30f3\u30b0\u30dc\u30f3\u30c9": 23, "\u5f71\u97ff": 23, "\u6392\u9664": 23, "\u6700\u4e0b\u5c64": 23, "\u6c34\u7d20": 23, "\u7f6e\u304f": 23, "\u7d42\u7aef": 23, "\u30c6\u30af\u30cb\u30c3\u30af": 23, "atomic": 23, "simulation": 23, "environment": 23, "(ase": 23, "(>": 23, "matplotlib": 23, "xyz": 23, "\u3042\u305f\u308b": 23, "\u62bd\u51fa": 23, "\u53d6\u308a\u9664\u304d": 23, "\u7f6e\u3044": [23, 24, 25, 27, 28, 29, 30], "\u6b21\u5c64": 23, "\u30b7\u30e9\u30f3": 23, "\u5206\u5b50": 23, "\u8abf\u6574": 23, "cif": 23, "\u305d\u306e\u307e\u307e": 23, "\u53c2\u7167\u7528": 23, "/todft": 23, "/sample": [23, 31], "_bulk": 23, "_new": 23, "\u4e2d\u8eab": [23, 24, 25, 27, 28, 29, 30], "\u5185\u5bb9": 23, "[main": 23, "_xyz": 23, "_head": 23, "ext": 23, "_margin": 23, "slab": 23, "_sih": 23, "angstrom": 23, "theta": 23, "-si": 23, "-h": 23, "_vec": 23, "kpts": 23, "points": 23, "monkhorst": 23, "-pack": 23, "grid": 23, "command": 23, "mpirun": 23, "pw": 23, ".x": 23, ".pwi": 23, ".pwo": 23, ".control": 23, "calculation": 23, "='": 23, "bands": 23, "# '": 23, "scf": 23, "',": 23, "realx": 23, "pseudo": 23, "./": [23, 24, 25, 28, 29, 30], "pseudopotential": 23, "directory": 23, ".system": 23, "ecutwfc": 23, "cut": 23, "-off": 23, "energy": 23, "ry": 23, "nbands": 23, "only": 23, "used": 23, "band": 23, ".pseudo": 23, ".pbe": 23, "-mt": 23, "_fhi": 23, ".upf": 23, "'h": 23, "\u884c\u3046\u969b": 23, "\u306b\u3064\u304f": 23, "\u30d8\u30c3\u30c0": 23, "\u30de\u30fc\u30b8\u30f3": 23, "_min": 23, "= z": 23, "\u30b9\u30e9\u30d6": 23, "\u4e0b\u99c4": 23, "\u306f\u304b\u305b\u308b": 23, "-z": 23, "+slab": 23, "\u56db\u9762\u4f53": 23, "\u9802\u70b9": 23, "h\u9593": 23, "\\mathrm": 23, "mathring": 23, "\u5e73\u9762": 23, "\u5f62\u6210": 23, "\u30e6\u30cb\u30c3\u30c8\u30d9\u30af\u30c8\u30eb": 23, "ex": 23, "\u306b\u95a2\u9023": 23, "\u73fe\u72b6": 23, "\u30dd\u30a4\u30f3\u30c8": 23, "(monkhorst": 23, "\u6a5f\u80fd": 23, "\u7406\u8a08": 23, "\u57fa\u672c": 23, "control": 23, ".xyz": 23, ".cif": 23, "\u3002qe": 23, "\u30dd\u30c6\u30f3\u30b7\u30e3\u30eb": 23, "\u7b2c\u4e00\u539f\u7406": 23, "_potential": 23, "_energy": 23, "normally": 23, "finished": 23, "\u30e1\u30c3\u30bb\u30fc\u30b8": 23, "\u4e0a\u8a18": [23, 26, 28, 31], "lattice": 23, "properties": 23, "=species": 23, ":s": 23, ":r": 23, "pbc": 23, "\u53ef\u8996": 23, "\u30bd\u30d5\u30c8": 23, "\u8aad\u307e\u305b\u308b": 23, "\u66f8\u304d\u8fbc\u307e": [23, 25, 27, 30], "\u5143\u7d20": 23, "\u5143\u5ea7": 23, "\u30b3\u30d4\u30fc": [23, 24, 25, 28, 29, 30, 31], "\u4e8b\u3082": 23, "\u30d0\u30f3\u30c9": 23, "\u4fee\u6b63": 23, "\u30aa\u30f3\u30e9\u30a4\u30f3\u30de\u30cb\u30e5\u30a2\u30eb": 23, "\u4e8b\u524d": [24, 29], "/sim": [24, 25, 28, 29, 30, 31], "/single": [24, 25, 28, 29, 30], "/bayes": 24, "\u306b\u3042\u308a": [24, 25, 27, 28, 29, 30, 31], "\u30e1\u30a4\u30f3\u30d7\u30ed\u30b0\u30e9\u30e0": [24, 25, 27, 28, 29, 30], "\u9032\u3081\u308b": [24, 25, 28, 29, 30], "ref": [24, 25, 27, 28, 29, 30], "_bayesdata": 24, "\u6b63\u3057\u304f": [24, 25, 27, 28, 29, 30], "\u305f\u304b": [24, 25, 27, 29, 30], "colormap": [24, 29], "\u56de\u7b54": [24, 25, 27, 28, 29, 30], "do": [24, 25, 27, 28, 29, 30], "\u4e00\u62ec": [24, 25, 27, 28, 29, 30], "\u7d39\u4ecb": [24, 25, 27, 28, 29, 30], "nealder": [24, 25, 26, 29, 30], "\u305f\u3060\u3057": [24, 29], "\u8efd\u304f": [24, 29], "[base": [24, 25, 27, 28, 29, 30, 32], ".config": [24, 25, 28, 29, 30], "row": [24, 25, 28, 29, 30], ".reference": [24, 25, 28, 29, 30], "first": [24, 25, 28, 29, 30], "last": [24, 25, 28, 29, 30], "label": [24, 25, 28, 29, 30], "z1": [24, 25, 28, 29, 30], "z2": [24, 25, 28, 29, 30], ".bayes": 24, "\u5185\u90e8": [24, 25, 27, 28, 29, 30], "\u547c\u3073\u51fa\u3059": [24, 28, 29], "0x": [24, 25, 28, 29, 30], "\u306b\u3064\u3051\u308b": [24, 25, 28, 29, 30], "\u30e9\u30d9\u30eb": [24, 25, 28, 29, 30], "\u5ea6\u5358\u4f4d": [24, 28, 29], "\u3053\u3080": [24, 28, 29], "[algorithm": [24, 25, 27, 28, 29, 30], "\u30a2\u30eb\u30b4\u30ea\u30b9\u30e0": [24, 28, 29], "\u76f4\u4e0b": [24, 25, 27, 28, 29, 30], "\u4eee\u5b9a": [24, 25, 27, 28, 29, 30, 31], "cp": [24, 25, 28, 29, 30, 31], "/trhepd": [24, 25, 28, 29, 30], "/bulk": [24, 25, 28, 29, 30, 31], "/surf": [24, 25, 28, 29, 30, 31], "pc": [24, 25, 27, 28, 29, 30], "\u6570\u79d2": [24, 25, 28, 29, 30], "\u7d42\u308f\u308a": [24, 25, 27, 28, 29, 30], "tee": [24, 25, 27, 28, 29, 30], "th": 24, "current": 24, "best": [24, 25, 27, 30], "\u30de\u30a4\u30ca\u30b9": 24, "\u4e57\u7b97": 24, ")`": 24, "\u6642\u70b9": 24, "\u30b0\u30ea\u30c3\u30c9\u30a4\u30f3\u30c7\u30c3\u30af\u30b9": 24, "\u3068\u305d\u306e": 24, "\u304c\u3064\u3044": [24, 29], "\u4ed8\u3051": [24, 29], "bayesdata": 24, "\u4eca\u56de": [24, 25, 27, 28, 29, 30], "\u6700\u9ad8": 24, "\u7d9a\u3051": 24, "\u6b63\u3057\u3044": 24, ".dat": [24, 28, 29], "\u6bd4\u8f03": [24, 25, 27, 28, 29, 30], "\u5272\u611b": [24, 25, 27, 28, 29, 30], "\u63b2\u8f09": [24, 25, 27, 28, 29, 30], "time": [24, 25, 28, 29, 30], "echo": [24, 25, 27, 28, 29, 30], "diff": [24, 25, 27, 28, 29, 30], "res": [24, 25, 27, 28, 29, 30], "=$": [24, 25, 27, 28, 29, 30], "eq": [24, 25, 27, 28, 29, 30], "then": [24, 25, 27, 28, 29, 30], "test": [24, 25, 27, 28, 29, 30], "else": [24, 25, 27, 28, 29, 30], "failed": [24, 25, 27, 28, 29, 30], "differ": [24, 25, 27, 28, 29, 30], "fi": [24, 25, 27, 28, 29, 30], "\u308f\u304b\u308a": 24, "rockingcurve": [24, 25, 28, 29, 30], ".rst": 24, "\u624b\u9806": [24, 25, 28, 29, 30], "\u6642\u3068": [25, 29, 30], "-threpd": [25, 28], "/exchange": 25, ".exchange": [25, 27], "\u30ec\u30d5\u30a1\u30ec\u30f3\u30b9": [25, 27, 30], "\"exchange": [25, 27, 30], "numstep": [25, 27], "\u8a66\u307f": [25, 27], "\u306f\u305d\u308c\u305e\u308c": [25, 27, 28, 30], "\u4e0b\u9650": [25, 27, 30], "\u4e0a\u9650": [25, 27, 30], "mpiexec": [25, 27, 29, 30], "\u4f7f\u3048\u308b": [25, 27, 30], "\u30b3\u30a2": [25, 27, 30], "\u8981\u6c42": [25, 27, 30], "\u591a\u3044": [25, 27, 30], "-oversubscribed": [25, 27, 30], "\u3002)": [25, 27, 30], "\u3068\u3082\u306b": [25, 27], "\u5404\u4f5c\u696d": [25, 30], "rank": [25, 27, 30], "oversubscribe": [25, 27, 30], "\u30e9\u30f3\u30af\u30d5\u30a9\u30eb\u30c0": 25, "\u69d8\u3005": [25, 31], "\u4fdd\u6301": 25, "\u6574\u5217": 25, "\u76f4\u3059": 25, "script": 25, "/separatet": 25, "/script": [25, 28, 31], "_t": [25, 30], "%.": [25, 30], "txt": [25, 30], "\u306a\u304a\u3055": 25, "index": 25, "\u5217\u3081": 25, "\u56f3\u793a": [25, 27, 29, 30], "\u3069\u3053": [25, 29, 30], "\u3046\u3064": [25, 29, 30], ".png": [25, 28, 29, 31], "plot": [25, 29, 30, 31], "2d": [25, 27, 29, 30], "\u898b\u308b": [25, 27, 29, 30], "\u3001(": [25, 29, 30], "\u4ed8\u8fd1": [25, 29, 30], "\u96c6\u4e2d": [25, 30], "\u6a2a\u8ef8": [25, 27, 30], "\u7e26\u8ef8": [25, 27, 30, 31], "logxxx": [25, 28, 30], "_yyy": [25, 30], "yyy": [25, 30], "_trhepd": 26, "_rheed": 26, "\u6771\u5317": 26, "\u8cb4\u5148": 26, "\u7269\u8cea": 26, "\uff08\u967d": 26, "\u30d9\u30fc\u30b9": 26, "\u53d6\u308a\u6271\u3063": 26, "\u3068\u3044\u3048": 26, "\u9006\u554f\u984c": 26, "\u89e3\u304f": 26, "\u3082\u3063\u3068\u3082\u3089\u3057\u3044": 26, "\u5168\u63a2": 26, "5\u3064": 26, "\u51fa\u6765\u308b": 26, "[runner": [26, 27], ".limitation": [26, 27], "\u5f0f\u6a5f": 27, "himmelblau": [27, 32], "\u5bfe\u8c61": 27, "/analytical": [27, 32], "/limitation": 27, "\u9805\u76ee": 27, "\u8a73\u3057\u3044": 27, "\u30de\u30cb\u30e5\u30a2\u30eb": 27, "\u2212 x": 27, "+ x": 27, "\u8ab2\u3057": 27, "\u306b\u305d\u306e": 27, "/best": 27, "!/": 27, "/bash": 27, ">_": 27, "histogram": 27, "\u30d2\u30b9\u30c8\u30b0\u30e9\u30e0": 27, "burn": 27, "-in": 27, "\u671f\u9593": 27, "\u6368\u3066": 27, "hist": 27, "_limitation": 27, "_sample": 27, "\u76f4\u7dda": 27, "\u4e8b\u5f8c": 27, "/minsearch": 28, ".fmin": 28, "\u305a\u308c": 28, "(r": 28, "\u307b\u307c": 28, "\u30b5\u30f3\u30d7\u30eb\u30d5\u30a9\u30eb\u30c0": 28, "\u77e5\u308b": 28, "_x": 28, "\u3044\u308c": 28, "convolution": [28, 31], "suft": 28, "\u6ce8\u610f\u304f": 28, "z3": 28, "read": [28, 29], "']": [28, 29], "lastline": [28, 29], "len": [28, 29], "(calculated": [28, 29], "(convolution": [28, 29], "_calculated": [28, 29], "logxxxxx": 28, "(xxxxx": 28, "\u6700\u7d42\u7684": [28, 29], "\u540c\u3058\u5024": 28, "\u5f97\u3089": 28, "_rc": 28, "_double": 28, "_ini": 28, "_con": 28, "/draw": 28, "rc": 28, "\u8d64\u4e38": 28, "\u9752\u7dda": 28, "\u7dd1\u7dda": 28, "_colormap": 29, "iteration": 29, "before": 29, "\u5168\u3066": 29, "colormapfig": 29, "\u6301\u3063": 29, "/pamc": 30, ".pamc": 30, "tnum": 30, "\u504f\u5dee": 30, "\u5897\u3084": 30, "_txxx": 30, "\u3055\u3089\u306b": 30, "\u305e\u308c": 30, "\u7d50\u5408": 30, "\uff08\u9006": 30, "/fx": 30, "_fx": 30, ".pdf": 30, "\u30b7\u30f3\u30dc\u30eb": 30, "jpn": 31, ");": 31, "\u30e9\u30c3\u30d1\u30fc": 31, "\u307e\u305a": [31, 32], "ls": 31, "\u30ea\u30dd\u30b8\u30c8\u30ea": 31, "\u5165\u624b": 31, "\u30d3\u30eb\u30c9": 31, "\u6210\u529f": 31, "/solver": [31, 32], "\u30d0\u30eb\u30af\u30d5\u30a1\u30a4\u30eb": 31, "electron": 31, "\u7d9a\u3044": 31, ".md": 31, "\u5b9f\u884c\u5f8c": 31, "surfyyyymmdd": 31, "-hhmmsslog": 31, "yyyymmdd": 31, "hhmmss": 31, "\u65e5\u6642": 31, "#azimuths": 31, "-angles": 31, "beams": 31, "ih": 31, "ik": 31, "\u4ee5\u4e0b\u7565": 31, "\u30d4\u30fc\u30af": 31, "gnuplot": 31, "\u30b0\u30e9\u30d5\u30bd\u30d5\u30c8": 31, "_bulkp": 31, "\u4e0b\u3055\u3044": 31, "/plot": 31, "2x": [31, 32], "\u639b\u3051": 31, "\u305f\u3046\u3048": 31, "_convolution": 31, "/make": 31, "\u3042\u304c\u308a": 31, "\u4e2d\u7565": 31, "\u8996\u5c04": 31, "\u66f8\u304b": 31, "\u4ed8\u52a0": 31, "\"analytical": 32, "\u30ea\u30d5\u30a1\u30ec\u30f3\u30b9": 32, "\u4f8b\u3068\u3057\u3066": 32, "booth": 32, "2y": 32, "\u307f\u307e\u3057\u3087": 32, "\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb\u30da\u30fc\u30b8": 32, "def": 32, "(xs": 32, "\"\"\"": 32, "it": 32, "has": 32, "one": 32, "global": 32, "minimum": 32, "xs": 32, "].": 32, ".shape": 32, "!=": 32, "raise": 32, "runtimeerror": 32, "\"error": 32, "expects": 32, "but": 32, "receives": 32, "={": 32, "]}": 32, "return": 32, "**": 32, "\u3064\u304e": 32, ".function": 32, "\u5206\u5c90": 32, "\u633f\u5165": 32, "elif": 32, "= \"": 32, "\":": 32, ".set": 32, "_function": 32, "(booth": 32, "\u306a\u3048": 32, "\u6e21\u305b": 32, "skipped": 32, "evaluations": 32, "solution": 32}, "objects": {}, "objtypes": {}, "objnames": {}, "titleterms": {"\u8b1d\u8f9e": 0, "\u30d9\u30a4\u30ba": [1, 24], "\u6700\u9069": [1, 24, 28], "bayes": 1, "\u6e96\u5099": [1, 2, 4, 5, 6, 19, 20, 21], "\u5165\u529b": [1, 2, 4, 5, 6, 14, 17, 19, 20, 21, 24, 25, 27, 28, 29, 30], "\u30d1\u30e9\u30e1\u30fc\u30bf": [1, 2, 4, 5, 6, 17, 19, 20, 21], "[algorithmparam": 1, "\u30bb\u30af\u30b7\u30e7\u30f3": [1, 2, 4, 5, 6, 14, 19, 20, 21, 23], "[algorithm": [1, 14], ".bayes": 1, "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0": [1, 2, 3, 4, 6, 10], "\u88dc\u52a9": [1, 2, 4, 6], "\u30d5\u30a1\u30a4\u30eb": [1, 2, 4, 5, 6, 14, 16, 19, 20, 21, 24, 25, 27, 28, 29, 30], "\u30e1\u30c3\u30b7\u30e5": [1, 2, 4, 6], "\u5b9a\u7fa9": [1, 2, 4, 6, 8, 10, 11], "\u51fa\u529b": [1, 2, 4, 5, 6, 16, 19, 20, 21], "bayesdata": 1, ".txt": [1, 2, 4, 5, 6, 20], "\u89e3\u8aac": [1, 2, 6], "\u4ea4\u63db": [2, 25, 27], "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": [2, 25, 27], "exchange": 2, "[param": [2, 4, 5, 6, 20, 21], "[exchange": 2, "\u8fd1\u508d": [2, 6], "\u30ea\u30b9\u30c8": [2, 6], "rank": [2, 6], "/trial": [2, 6], "/result": [2, 6], "best": [2, 6], "_result": [2, 6], "result": 2, "_t": [2, 6], "#.": [2, 6], "txt": [2, 6], "\u30de\u30eb\u30b3\u30d5": 2, "\u9023\u9396": 2, "\u30ec\u30d7\u30ea\u30ab": [2, 25, 27], "\u63a2\u7d22": [3, 4, 25, 27, 30], "\u81ea\u660e\u4e26\u5217": 4, "mapper": 4, "colormap": 4, "nelder": [5, 28], "-mead": [5, 28], "minsearch": 5, "[minimize": 5, "simplexdata": 5, "res": 5, "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": 6, "pamc": 6, "[pamc": 6, "\u30b9\u30c6\u30c3\u30d7": 6, "\u306b\u3064\u3044\u3066": 6, "fx": 6, "\u554f\u984c": [6, 18, 32], "\u76ee\u7684": 6, "annealed": 6, "importance": 6, "sampling": 6, "ais": 6, "population": 6, "annealing": 6, "pa": 6, "\u53c2\u8003": 6, "\u6587\u732e": 6, "\u304a\u554f\u3044": 7, "\u5408\u308f": 7, "algorithm": 8, "algorithmbase": 8, "\u5171\u901a": [9, 16], "\u4e8b\u9805": 9, "py": [9, 22, 23], "2dmat": [9, 13, 15, 22, 23], ".info": 9, ".message": 9, ".runner": 9, "\u958b\u767a": [10, 15], "\u5411\u3051": 10, "\u30e6\u30fc\u30b6\u30fc": 10, "\u30bd\u30eb\u30d0\u30fc": [10, 17, 18, 19, 20, 21, 31, 32], "solver": [11, 23], "\u5b9f\u884c": [12, 22, 24, 25, 27, 28, 29, 30, 31], "\u65b9\u6cd5": [12, 22], "welcome": 13, "to": 13, "'s": 13, "documentation": 13, "contents": 13, "[base": 14, "[solver": [14, 20], "[runner": 14, "[mapping": 14, "[limitation": 14, "[log": 14, "\u306f\u3058\u3081": 15, "\u30e9\u30a4\u30bb\u30f3\u30b9": 15, "\u30d0\u30fc\u30b8\u30e7\u30f3": 15, "\u5c65\u6b74": 15, "time": 16, ".log": 16, "runner": 16, "analytical": 17, "leed": 19, "[config": [19, 20, 21], "[reference": [19, 20, 21], "\u7528\u88dc": [19, 20, 21], "\u30bf\u30fc\u30b2\u30c3\u30c8": [19, 20, 21], "\u53c2\u7167": [19, 20, 21, 24, 25, 28, 29, 30], "sim": 20, "-trhepd": 20, "-rheed": 20, "\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3": [20, 21], "[post": 20, "\u30c6\u30f3\u30d7\u30ec\u30fc\u30c8\u30d5\u30a1\u30a4\u30eb": 20, "stdout": [20, 21], "rockingcurve": 20, "_calculated": 20, "sxrd": 21, ".domain": 21, ".atom": 21, "\u30d0\u30eb\u30af": 21, "\u69cb\u9020": 21, "\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [22, 31], "\u74b0\u5883": [22, 23], "\u5fc5\u8981": [22, 23], "\u30d1\u30c3\u30b1\u30fc\u30b8": 22, "\u30c0\u30a6\u30f3\u30ed\u30fc\u30c9": [22, 31], "\u30a2\u30f3\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": 22, "\u95a2\u9023": 23, "\u30c4\u30fc\u30eb": 23, "_neighborlist": 23, "\u4f7f\u3044\u65b9": 23, "tool": 23, "/to": 23, "_dft": 23, ".py": 23, "\u30b9\u30af\u30ea\u30d7\u30c8": 23, "\u6982\u8981": 23, "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb": [23, 26], "main": 23, ".param": 23, ".lattice": 23, "ase": 23, "\u30b5\u30f3\u30d7\u30eb\u30d5\u30a1\u30a4\u30eb": [24, 25, 27, 28, 29, 30], "\u5834\u6240": [24, 25, 27, 28, 29, 30], "\u8aac\u660e": [24, 25, 27, 28, 29, 30], "\u8a08\u7b97": [24, 25, 27, 28, 29, 30, 31], "\u7d50\u679c": [24, 25, 27, 28, 29, 30, 31], "\u53ef\u8996": [24, 25, 27, 28, 29, 30, 31], "\u306b\u3088\u308b": [25, 27, 28, 30], "\u5f8c\u51e6\u7406": 25, "\u7d04\u5f0f": 27, "\u9069\u7528": 27, "\u30b0\u30ea\u30c3\u30c9": 29, "\u578b\u63a2": 29, "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0": 30, "trhepd": 31, "\u9806\u554f\u984c": 31, "\u8ffd\u52a0": 32, "\u30d9\u30f3\u30c1\u30de\u30fc\u30af": 32, "\u95a2\u6570": 32}, "envversion": {"sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx": 60}, "alltitles": {"\u8b1d\u8f9e": [[0, "id1"]], "\u30d9\u30a4\u30ba\u6700\u9069\u5316 bayes": [[1, "bayes"]], "\u524d\u6e96\u5099": [[1, "id1"], [2, "id1"], [4, "id1"], [5, "id2"], [6, "id1"], [19, "id2"], [20, "id2"], [21, "id1"]], "\u5165\u529b\u30d1\u30e9\u30e1\u30fc\u30bf": [[1, "id2"], [2, "id2"], [4, "id2"], [5, "id3"], [6, "id2"], [17, "id1"], [19, "id3"], [20, "id3"], [21, "id2"]], "[algorithmparam] \u30bb\u30af\u30b7\u30e7\u30f3": [[1, "algorithmparam"]], "[algorithm.bayes] \u30bb\u30af\u30b7\u30e7\u30f3": [[1, "algorithm-bayes"]], "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u88dc\u52a9\u30d5\u30a1\u30a4\u30eb": [[1, "id3"], [2, "id4"], [4, "id3"], [6, "id5"]], "\u30e1\u30c3\u30b7\u30e5\u5b9a\u7fa9\u30d5\u30a1\u30a4\u30eb": [[1, "id4"], [2, "id5"], [4, "id4"], [6, "id6"]], "\u51fa\u529b\u30d5\u30a1\u30a4\u30eb": [[1, "id5"], [2, "id7"], [4, "id5"], [5, "id4"], [6, "id8"], [16, "id1"], [19, "id6"], [20, "id7"], [21, "id6"]], "BayesData.txt": [[1, "bayesdata-txt"]], "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u89e3\u8aac": [[1, "id6"], [2, "id8"], [6, "id9"]], "\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 exchange": [[2, "exchange"]], "[param] \u30bb\u30af\u30b7\u30e7\u30f3": [[2, "param"], [4, "param"], [5, "param"], [6, "param"], [21, "param"]], "[exchange] \u30bb\u30af\u30b7\u30e7\u30f3": [[2, "id3"]], "\u8fd1\u508d\u30ea\u30b9\u30c8\u5b9a\u7fa9\u30d5\u30a1\u30a4\u30eb": [[2, "id6"], [6, "id7"]], "RANK/trial.txt": [[2, "rank-trial-txt"], [6, "rank-trial-txt"]], "RANK/result.txt": [[2, "rank-result-txt"], [6, "rank-result-txt"]], "best_result.txt": [[2, "best-result-txt"], [6, "best-result-txt"]], "result_T#.txt": [[2, "result-t-txt"]], "\u30de\u30eb\u30b3\u30d5\u9023\u9396\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5": [[2, "id9"]], "\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5": [[2, "id11"]], "\u63a2\u7d22\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0": [[3, "id1"]], "\u81ea\u660e\u4e26\u5217\u63a2\u7d22 mapper": [[4, "mapper"]], "ColorMap.txt": [[4, "colormap-txt"]], "Nelder-Mead \u6cd5 minsearch": [[5, "nelder-mead-minsearch"]], "[minimize] \u30bb\u30af\u30b7\u30e7\u30f3": [[5, "minimize"]], "SimplexData.txt": [[5, "simplexdata-txt"]], "res.txt": [[5, "res-txt"]], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 pamc": [[6, "pamc"]], "[pamc] \u30bb\u30af\u30b7\u30e7\u30f3": [[6, "id3"]], "\u30b9\u30c6\u30c3\u30d7\u6570\u306b\u3064\u3044\u3066": [[6, "id4"]], "RANK/trial_T#.txt": [[6, "rank-trial-t-txt"]], "RANK/result_T#.txt": [[6, "rank-result-t-txt"]], "fx.txt": [[6, "fx-txt"]], "\u554f\u984c\u3068\u76ee\u7684": [[6, "id10"]], "Annealed Importance Sampling (AIS) [1]": [[6, "annealed-importance-sampling-ais-1"]], "population annealing (PA) [2]": [[6, "population-annealing-pa-2"]], "\u53c2\u8003\u6587\u732e": [[6, "id11"]], "\u304a\u554f\u3044\u5408\u308f\u305b": [[7, "id1"]], "Algorithm \u306e\u5b9a\u7fa9": [[8, "algorithm"]], "AlgorithmBase": [[8, "algorithmbase"]], "Algorithm": [[8, "id1"]], "\u5171\u901a\u4e8b\u9805": [[9, "id1"]], "py2dmat.Info": [[9, "py2dmat-info"]], "py2dmat.Message": [[9, "py2dmat-message"]], "py2dmat.Runner": [[9, "py2dmat-runner"]], "(\u958b\u767a\u8005\u5411\u3051)\u30e6\u30fc\u30b6\u30fc\u5b9a\u7fa9\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u30fb\u30bd\u30eb\u30d0\u30fc": [[10, "id1"]], "Solver \u306e\u5b9a\u7fa9": [[11, "solver"]], "\u5b9f\u884c\u65b9\u6cd5": [[12, "id1"], [22, "id3"]], "Welcome to 2DMAT's documentation!": [[13, "welcome-to-2dmat-s-documentation"]], "Contents:": [[13, null]], "\u5165\u529b\u30d5\u30a1\u30a4\u30eb": [[14, "id1"]], "[base] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "base"]], "[solver] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "solver"], [20, "solver"]], "[algorithm] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "algorithm"]], "[runner] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "runner"]], "[mapping] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "mapping"]], "[limitation] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "limitation"]], "[log] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "log"]], "\u306f\u3058\u3081\u306b": [[15, "id1"]], "2DMAT\u3068\u306f": [[15, "dmat"]], "\u30e9\u30a4\u30bb\u30f3\u30b9": [[15, "id2"]], "\u30d0\u30fc\u30b8\u30e7\u30f3\u5c65\u6b74": [[15, "id3"]], "\u4e3b\u306a\u958b\u767a\u8005": [[15, "id4"]], "\u5171\u901a\u30d5\u30a1\u30a4\u30eb": [[16, "id2"]], "time.log": [[16, "time-log"]], "runner.log": [[16, "runner-log"]], "analytical \u30bd\u30eb\u30d0\u30fc": [[17, "analytical"]], "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc": [[18, "id1"]], "leed \u30bd\u30eb\u30d0\u30fc": [[19, "leed"]], "[config] \u30bb\u30af\u30b7\u30e7\u30f3": [[19, "config"], [21, "config"]], "[reference] \u30bb\u30af\u30b7\u30e7\u30f3": [[19, "reference"], [21, "reference"]], "\u30bd\u30eb\u30d0\u30fc\u7528\u88dc\u52a9\u30d5\u30a1\u30a4\u30eb": [[19, "id4"], [20, "id4"], [21, "id3"]], "\u30bf\u30fc\u30b2\u30c3\u30c8\u53c2\u7167\u30d5\u30a1\u30a4\u30eb": [[19, "id5"], [20, "id6"], [21, "id4"]], "sim-trhepd-rheed \u30bd\u30eb\u30d0\u30fc": [[20, "sim-trhepd-rheed"]], "[config] \u30bb\u30af\u30b7\u30e7\u30f3\uff08\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3\uff09": [[20, "config"]], "[post] \u30bb\u30af\u30b7\u30e7\u30f3\uff08\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3\uff09": [[20, "post"]], "[param] \u30bb\u30af\u30b7\u30e7\u30f3\uff08\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3\uff09": [[20, "param"]], "[reference] \u30bb\u30af\u30b7\u30e7\u30f3\uff08\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3\uff09": [[20, "reference"]], "\u5165\u529b\u30c6\u30f3\u30d7\u30ec\u30fc\u30c8\u30d5\u30a1\u30a4\u30eb": [[20, "id5"]], "stdout": [[20, "stdout"], [21, "stdout"]], "RockingCurve_calculated.txt": [[20, "rockingcurve-calculated-txt"]], "sxrd \u30bd\u30eb\u30d0\u30fc": [[21, "sxrd"]], "[param.domain] \u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3": [[21, "param-domain"]], "[param.domain.atom] \u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3": [[21, "param-domain-atom"]], "\u30d0\u30eb\u30af\u69cb\u9020\u30d5\u30a1\u30a4\u30eb": [[21, "id5"]], "py2dmat \u306e\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [[22, "py2dmat"]], "\u5b9f\u884c\u74b0\u5883\u30fb\u5fc5\u8981\u306a\u30d1\u30c3\u30b1\u30fc\u30b8": [[22, "id1"]], "\u30c0\u30a6\u30f3\u30ed\u30fc\u30c9\u30fb\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [[22, "id2"], [31, "id1"]], "\u30a2\u30f3\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [[22, "id4"]], "\u95a2\u9023\u30c4\u30fc\u30eb": [[23, "id1"]], "py2dmat_neighborlist": [[23, "py2dmat-neighborlist"]], "\u4f7f\u3044\u65b9": [[23, "id2"]], "tool/to_dft/to_dft.py": [[23, "tool-to-dft-to-dft-py"]], "\u5fc5\u8981\u306a\u74b0\u5883": [[23, "id3"]], "\u30b9\u30af\u30ea\u30d7\u30c8\u306e\u6982\u8981": [[23, "id4"]], "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb": [[23, "id5"], [26, "id1"]], "Main \u30bb\u30af\u30b7\u30e7\u30f3": [[23, "main"]], "Main.Param \u30bb\u30af\u30b7\u30e7\u30f3": [[23, "main-param"]], "Main.lattice \u30bb\u30af\u30b7\u30e7\u30f3": [[23, "main-lattice"]], "ASE \u30bb\u30af\u30b7\u30e7\u30f3": [[23, "ase"]], "Solver \u30bb\u30af\u30b7\u30e7\u30f3": [[23, "solver"]], "\u30d9\u30a4\u30ba\u6700\u9069\u5316": [[24, "id1"]], "\u30b5\u30f3\u30d7\u30eb\u30d5\u30a1\u30a4\u30eb\u306e\u5834\u6240": [[24, "id2"], [25, "id2"], [27, "id2"], [28, "id1"], [29, "id2"], [30, "id2"]], "\u53c2\u7167\u30d5\u30a1\u30a4\u30eb\u306e\u8aac\u660e": [[24, "id3"], [25, "id3"], [28, "id2"], [29, "id3"], [30, "id3"]], "\u5165\u529b\u30d5\u30a1\u30a4\u30eb\u306e\u8aac\u660e": [[24, "id4"], [25, "id4"], [27, "id3"], [28, "id3"], [29, "id4"], [30, "id4"]], "\u8a08\u7b97\u5b9f\u884c": [[24, "id5"], [25, "id5"], [27, "id4"], [28, "id4"], [29, "id5"], [30, "id5"], [31, "id2"]], "\u8a08\u7b97\u7d50\u679c\u306e\u53ef\u8996\u5316": [[24, "id6"], [25, "id7"], [27, "id5"], [28, "id5"], [29, "id6"], [30, "id6"], [31, "id3"]], "\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22": [[25, "id1"]], "\u5f8c\u51e6\u7406": [[25, "id6"]], "\u5236\u7d04\u5f0f\u3092\u9069\u7528\u3057\u305f\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22": [[27, "id1"]], "Nelder-Mead\u6cd5\u306b\u3088\u308b\u6700\u9069\u5316": [[28, "nelder-mead"]], "\u30b0\u30ea\u30c3\u30c9\u578b\u63a2\u7d22": [[29, "id1"]], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u306b\u3088\u308b\u63a2\u7d22": [[30, "id1"]], "TRHEPD \u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc": [[31, "trhepd"]], "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc\u306e\u8ffd\u52a0": [[32, "id1"], [32, "id3"]], "\u30d9\u30f3\u30c1\u30de\u30fc\u30af\u95a2\u6570\u30bd\u30eb\u30d0\u30fc": [[32, "id2"]]}, "indexentries": {}}) \ No newline at end of file diff --git a/manual/v2.2.0/ja/solver/analytical.html b/manual/v2.2.0/ja/solver/analytical.html new file mode 100644 index 00000000..69bd2fc4 --- /dev/null +++ b/manual/v2.2.0/ja/solver/analytical.html @@ -0,0 +1,115 @@ + + + + + + + + analytical ソルバー — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

analytical ソルバー

+

analytical は探索アルゴリズムの性能評価を目的とした、 +定義済みのベンチマーク関数 \(f(x)\) を計算する Solver です。

+
+

入力パラメータ

+

solver セクション以下の funtion_name パラメータで用いる関数を指定します。

+
    +

  • function_name

    +

    形式: string型

    +

    説明: 関数名。以下の関数が選べます。

    +
      +

    • quadratics

      +
        +

      • 二次形式

        +
        +\[f(\vec{x}) = \sum_{i=1}^N x_i^2\]
        +
        • +

      • 最適値は \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • rosenbrock

      + +
      +\[f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right]\]
      +
        +

      • 最適値は \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)\)

        • +
      +
      • +

    • ackley

      + +
      +\[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]\]
      +
        +

      • 最適値は \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • himmerblau

      + +
      +\[f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2\]
      +
        +

      • 最適値は \(f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0\)

        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/solver/index.html b/manual/v2.2.0/ja/solver/index.html new file mode 100644 index 00000000..bd59820b --- /dev/null +++ b/manual/v2.2.0/ja/solver/index.html @@ -0,0 +1,71 @@ + + + + + + + + 順問題ソルバー — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

順問題ソルバー

+

順問題ソルバー Solver は探索パラメータ \(x\) から最適化したい \(f(x)\) を計算します。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/solver/leed.html b/manual/v2.2.0/ja/solver/leed.html new file mode 100644 index 00000000..7524dbe0 --- /dev/null +++ b/manual/v2.2.0/ja/solver/leed.html @@ -0,0 +1,141 @@ + + + + + + + + leed ソルバー — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

leed ソルバー

+

leed は M.A. Van Hove氏により作成された SATLEED を用いて、原子位置などからRocking curve を計算し、実験で得られた Rocking curve からの誤差を \(f(x)\) として返す Solver です。 SATLEED に関する詳細については [SATLEED] をご覧ください。

+
+
+[SATLEED] +

M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). https://doi.org/10.1016/0167-5729(93)90011-D

+
+
+
+

前準備

+

最初に SATLEED をインストールします。 +http://www.icts.hkbu.edu.hk/VanHove_files/leed/leedsatl.zip へアクセスし、zipファイルをダウンロードします。zipファイル展開後に、所定の手続きに従いコンパイルすることで、 stal1.exe, satl2.exe などの実行ファイルができます。 +SATLED は計算したい系の詳細によって、ソースコードのパラメータを適宜書き換える必要があります。 +sample/py2dmat/leed にあるサンプルを実行する場合には、 SATLEED のダウンロードから、サンプル向けのソースコードの書き換え、コンパイルまでを自動で行うスクリプト setup.sh が用意されています。:

+
$ cd sample/py2dmat/leed
+$ sh ./setup.sh
+
+
+

setup.sh を実行すると、 leedsatl ディレクトリに satl1.exe と satl2.exe が生成されます。

+

py2dmat から SATLEED を利用するにあたっては、あらかじめ satl1.exe まで実行していることが前提となります。そのため、以下のファイルが生成されている必要があります。

+
    +

  • satl1.exe の入力ファイル: exp.d, rfac.d, tleed4.i, tleed5.i

    • +

  • satl1.exe の出力ファイル: tleed.o , short.t

    • +
+

py2dmat はこれらをもちいて satl2.exe を実行します。

+
+
+

入力パラメータ

+

solver セクション中のサブセクション +config, reference を利用します。

+
+

[config] セクション

+
    +

  • path_to_solver

    +

    形式: string型

    +

    説明: ソルバー satl2.exe へのパス

    +
    • +
+
+
+

[reference] セクション

+
    +

  • path_to_base_dir

    +

    形式: string型

    +

    説明: - exp.d, rfac.d, tleed4.i, tleed5.i , tleed.o , short.t が格納されたディレクトリへのパス。

    +
    • +
+
+
+
+

ソルバー用補助ファイル

+
+

ターゲット参照ファイル

+

ターゲットにするデータが格納されたファイル。 [reference] セクションの path_to_base_dir 中にある tleed4.i を編集します。最適化したい数値を optxxx (xxxは000, 001, 002, ...の形式で指定する三桁の整数)として指定します。なお、xxxの数字と py2dmat の最適化する値を入れる変数のリストの順番・個数は一致させる必要があります。なお、IFLAG, LSFLAGを0にしない場合はsatleed側での最適化も行われます。

+

以下、ファイル例を記載します。

+
1  0  0                          IPR ISTART LRFLAG
+1 10  0.02  0.2                  NSYM  NSYMS ASTEP VSTEP
+5  1  2  2                       NT0  NSET LSMAX LLCUT
+5                                NINSET
+1.0000 0.0000                  1      PQEX
+1.0000 2.0000                  2      PQEX
+1.0000 1.0000                  3      PQEX
+2.0000 2.0000                  4      PQEX
+2.0000 0.0000                  5      PQEX
+3                                NDIM
+opt000 0.0000 0.0000  0           DISP(1,j)  j=1,3
+0.0000 opt001 0.0000  0           DISP(2,j)  j=1,3
+0.0000 0.0000 0.0000  1           DISP(3,j)  j=1,3
+0.0000 0.0000 0.0000  0           DISP(4,j)  j=1,3
+0.0000  0                         DVOPT  LSFLAG
+3  0  0                          MFLAG NGRID NIV
+...
+
+
+
+
+
+

出力ファイル

+

leed では、 計算時に出力されるファイルが、ランクの番号が記載されたフォルダ下に一式出力されます。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/solver/sim-trhepd-rheed.html b/manual/v2.2.0/ja/solver/sim-trhepd-rheed.html new file mode 100644 index 00000000..08ecab36 --- /dev/null +++ b/manual/v2.2.0/ja/solver/sim-trhepd-rheed.html @@ -0,0 +1,336 @@ + + + + + + + + sim-trhepd-rheed ソルバー — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

sim-trhepd-rheed ソルバー

+

sim-trhepd-rheed は sim-trhepd-rheed を用いて原子位置 \(x\) から回折 rocking curve を計算し、 +実験で得られた rocking curve からの誤差を \(f(x)\) として返す Solver です。

+
+

前準備

+

あらかじめ sim-trhepd-rheed をインストールしておく必要があります。

+
    +

  1. sim-trhepd-rheed の公式サイトからソースコードをダウンロード

    2. +

  2. sim-trhepd-rheed/src に移動し、 make で bulk.exe と surf.exe を作成

    3. +
+

py2dmat を実行する前にあらかじめ bulk.exe を実行してバルクデータを作成しておきます。 +surf.exe は py2dmat から呼び出されます。

+
+
+

入力パラメータ

+

solver セクションとセクション中のサブセクション +config, post, param, reference を利用します。

+
+

[solver] セクション

+
    +

  • generate_rocking_curve

    +

    形式: 真偽値 (default: false)

    +

    説明: RockingCurve_calculated.txt の生成をするかどうか。 RockingCurve_calculated.txt は作業ディレクトリ Log%%%_### の中に保存されます。このオプションが"true"であっても、 remove_work_dir （[post] セクション）が"true"であれば Log%%%_### は削除されてしまうため、注意してください。

    +
    • +
+
+
+

[config] セクション（サブセクション）

+
    +

  • surface_exec_file

    +

    形式: string型 (default: "surf.exe")

    +

    説明: sim-trhepd-rheed の表面反射ソルバー surf.exe へのパス

    +
    • +

  • surface_input_file

    +

    形式: string型 (default: "surf.txt")

    +

    説明: 表面構造のインプットファイル。

    +
    • +

  • bulk_output_file

    +

    形式: string型 (default: "bulkP.b")

    +

    説明: バルク構造のアウトプットファイル。

    +
    • +

  • surface_output_file

    +

    形式: string型 (default: "surf-bulkP.s")

    +

    説明: 表面構造のアウトプットファイル。

    +
    • +

  • calculated_first_line

    +

    形式: 整数型 (default: 5)

    +

    説明: surface_output_file ファイル中, D(x) として読み込む最初の行。 なお、最終行は実験データとして読み込んだ行数から自動計算されます。

    +
    • +

  • calculated_info_line

    +

    形式: 整数型 (default: 2)

    +

    説明: surface_output_file ファイル中, glancing angle数やbeam数が記してある行番号。

    +
    • +

  • cal_number

    +

    形式: 整数型のリスト (設定必須)

    +

    説明: surface_output_file ファイル中, データとして読み出す列番号。複数指定が可能。設定した値は、後述の exp_number （[reference] セクション）の値とリストの長さを一致させる必要があります。

    +
    • +
+
+
+

[post] セクション（サブセクション）

+

実験と計算の「ズレ」の大きさを示し、最小化すべき関数である「目的関数」の定義や、ロッキングカーブを描くためのコンボリューション半値幅などを指定するセクションです。

+
    +

  • Rfactor_type

    +

    形式: string型。"A"、"A2"または"B"のいずれかをとります。 (default: "A")

    +

    説明: 目的関数値の計算方法の指定。 +視写角のインデックスを \(i = 1,2,\dots,m\), ビームのインデックスを \(j = 1,2,\dots,n\) として、 +実験・計算のデータをそれぞれ \(u^{(j)}_i\) と \(v^{(j)}_i\) で表し、 +各ビームの重みを \(w^{(j)}\) と書くとき

    +
    +
      +

    • "A"タイプ:

      +
      +\[R = \sqrt{ \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2} }\]
      +
      • +

    • "A2"タイプ:

      +
      +\[R^{2} = \sum_{j}^{n} w^{(j)} \sum_{i}^{m} \left(u^{(j)}_{i}-v^{(j)}_{i}\right)^{2}\]
      +
      • +

    • "B"タイプ:

      +
      +\[R = \frac{\sum_{i}^{m} \left(u^{(1)}_{i}-v^{(1)}_{i}\right)^{2}}{\sum_{i}^{m} \left(u^{(1)}_{i}\right)^{2} + \sum_{i}^{m} (v^{(1)}_{i})^2}\]
      +
        +

      • "B"タイプはデータ列が1つの実験・計算データを用いた実行( \(n=1\) )のみ対応しています。

        • +
      +
      • +
    +
    +
    • +

  • normalization

    +

    形式: string型。"TOTAL"または"MANY_BEAM"のいずれかをとります。 (設定必須)

    +

    説明: 実験・計算のデータベクトルの規格化の方法。

    +
      +

    • "TOTAL"

      +
        +

      • 全体の和で規格化をします。

        • +

      • 計算に使用するデータ列が1つのみ適用できる規格化方法であり、 cal_number （[config] セクション）および exp_number （[reference] セクション）で設定したリストの長さが1である必要が有ります。

        • +
      +
      • +

    • "MANY_BEAM"

      +
        +

      • "MANY_BEAM"はデータ列が2つ以上であるときに利用できる規格化方法です。後述の weight_type によって規格化方法が変わります。

        • +
      +
      • +
    +

    なお、 normalization="MAX" は廃止となりました。

    +
    • +

  • weight_type

    +

    形式: string型または None 。"calc"または"manual"のいずれかを設定する必要があります。 (default: None 、 normalization = "MANY_BEAM" としたとき設定必須)

    +

    説明: 目的関数値を計算するときの、ビームごとの重み \(w^{(j)}\) の計算方法を指定します。 +"calc"とした場合、データ列ごとの重み \(w^{(n)}\) は次の式で与えられます。

    +
    +\[w^{(j)} = \left(\frac{\sum_{i=1}^m v^{(j)}_{i}}{\sum_{k=1}^n \sum_{i=1}^m v^{(j)}_i} \right)^2\]
    +

    "manual"とした場合、オプション spot_weight を用いることで、ユーザーが重みを指定可能です。

    +
    • +

  • spot_weight

    +

    形式: float型のリスト。 (default: [] 、 weight_type = "manual" としたとき設定必須)

    +
    +
    説明: 目的関数値を計算するときの、データ列ごとの重みを設定します。総和が1になるように自動的に規格化されます。

    例えば、[3,2,1]を指定すると、 \(w^{(1)}=1/2, w^{(2)}=1/3, w^{(3)}=1/6\) となります。

    +
    +
    +
    • +

  • omega

    +

    形式: 実数型 (default: 0.5)

    +

    説明: コンボリューションの半値幅の指定。

    +
    • +

  • remove_work_dir

    +

    形式: 真偽値 (default: false)

    +

    説明: R-factor を読み取った後に作業ディレクトリ Log%%%_### を削除するかどうか。なお、 generate_rocking_curve ([solver] セクション) が"true"であっても、本オプションが"true"ならば Log%%%_### を削除します。

    +
    • +
+
+
+

[param] セクション（サブセクション）

+
    +

  • string_list

    +

    形式: string型のリスト。長さはdimensionの値と一致させます。 (default: ["value_01", "value_02"])

    +

    説明: ソルバーの入力ファイルを作成するための参照用テンプレートファイルで利用するプレースホルダーのリスト。これらの文字列が探索中のパラメータの値に置換されます。

    +
    • +
+
+
+

[reference] セクション（サブセクション）

+
    +

  • path

    +

    形式: string型 (default: experiment.txt)

    +

    説明: 実験データファイルへのパス。

    +
    • +

  • reference_first_line

    +

    形式: 整数型

    +

    説明: 実験データファイル中、実験データを読み出す最初の行の番号。省略時は1, すなわち先頭行から読み出します。

    +
    • +

  • reference_last_line

    +

    形式: 整数型 (default: 実験データファイルの最後の行の行数)

    +

    説明: 実験データファイル中、実験データを読み出す最後の行の番号。省略時は最終行まで読み出します。

    +
    • +

  • exp_number

    +

    形式: 整数型のリスト

    +

    説明: 実験データファイル中、実験データとして読み出す列番号。複数指定が可能。設定した値は、前述の cal_number （[config] セクション）の値とリストの長さを一致させる必要があります。

    +
    • +
+
+
+
+

ソルバー用補助ファイル

+
+

入力テンプレートファイル

+

入力テンプレートファイル template.txt は surf.exe の入力ファイルを作成するためのテンプレートです。 +動かすパラメータ（求めたい原子座標などの値）を「 value_* 」などの適当な文字列に置き換えます。 +使用する文字列は入力ファイルの [solver] - [param] セクションにある、 +string_list で指定します。 +以下、テンプレートの例を記載します。

+
2                                    ,NELMS,  -------- Ge(001)-c4x2
+32,1.2,0.15                          ,Ge Z,da1,sap
+0.6,0.6,0.6                          ,BH(I),BK(I),BZ(I)
+32,1.2,0.15                          ,Ge Z,da1,sap
+0.4,0.4,0.4                          ,BH(I),BK(I),BZ(I)
+9,4,0,0,2,1.7,-0.5,0.5               ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS
+8                                    ,NATM
+1, 1.0,  value_01,  1.00000,  5.231000   ,IELM(I),ocr(I),X(I),Y(I),Z(I
+1, 1.0,  value_02,  1.00000,  4.371000
+2, 1.0,  1.50000,  1.50000,  3.596000
+2, 1.0,  2.00000,  1.49751,  2.100000
+2, 1.0,  1.00000,  1.50000,  2.000000
+2, 1.0,  0.00000,  1.00000,  0.849425
+2, 1.0,  2.00000,  1.00000,  0.809425
+2, 1.0,  1.00997,  1.00000,  0.599425
+1,1                                  ,(WDOM,I=1,NDOM)
+
+
+

この場合、 value_01, value_02 が動かすパラメータとなります。

+
+
+

ターゲット参照ファイル

+

ターゲットにするデータが格納されたファイル experiment.txt を指定します。 +第一列に角度、第二列以降に反射強度にコンボリューションを計算した値が入ってます。 +以下、ファイルの例を示します。

+
3.00000e-01 8.17149e-03 1.03057e-05 8.88164e-15 ...
+4.00000e-01 1.13871e-02 4.01611e-05 2.23952e-13 ...
+5.00000e-01 1.44044e-02 1.29668e-04 4.53633e-12 ...
+6.00000e-01 1.68659e-02 3.49471e-04 7.38656e-11 ...
+7.00000e-01 1.85375e-02 7.93037e-04 9.67719e-10 ...
+8.00000e-01 1.93113e-02 1.52987e-03 1.02117e-08 ...
+9.00000e-01 1.92590e-02 2.53448e-03 8.69136e-08 ...
+1.00000e+00 1.86780e-02 3.64176e-03 5.97661e-07 ...
+1.10000e+00 1.80255e-02 4.57932e-03 3.32760e-06 ...
+1.20000e+00 1.77339e-02 5.07634e-03 1.50410e-05 ...
+1.30000e+00 1.80264e-02 4.99008e-03 5.53791e-05 ...
+...
+
+
+
+
+
+

出力ファイル

+

sim-trhepd-rheed では、 surf.exe で出力されるファイルが、 +ランクの番号が記載されたフォルダ下にある Log%%%%%_##### フォルダに一式出力されます。 +%%%%% はアルゴリズムの反復回数 step (例：モンテカルロステップ数)で、 +##### はアルゴリズムにおけるグループの番号 set (例：モンテカルロにおけるレプリカ番号)です。 +大規模計算ではこれらのフォルダの数が多くなり、時には計算機のストレージの制限に引っかかることがあります。 +そのような場合には、 solver.post.remove_work_dir パラメータを true にして、計算が終了した作業フォルダを削除してください。 +以下では、 py2dmat で独自に出力するファイルについて説明します。

+
+

stdout

+

surf.exe が出力する標準出力が記載されています。

+

以下、出力例です。

+
bulk-filename (end=e) ? :
+bulkP.b
+structure-filename (end=e) ? :
+surf.txt
+output-filename :
+surf-bulkP.s
+
+
+
+
+

RockingCurve_calculated.txt

+

generate_rocking_curve ([solver] セクション) が"true"の場合のみ Log%%%%%_##### フォルダに出力されます。

+

ファイル冒頭、 # で始まる行はヘッダーです。 +ヘッダーには探索変数の値、目的関数値 f(x) オプションで指定した Rfactor_type, normalization`,  ``weight_type, cal_number, オプションで指定またはプログラムが計算したデータ列ごとの重み spot_weight, データ部分のどの列に何が記されているか(例： # #0 glanceing_angle など)が記されています。

+

# が付いていない部分はデータ表記部分になります。1列目は視写角、2列目以降はデータ列ごとに強度が記しています。どのデータ列が記されているかはヘッダーの表記で確認できます。例えば

+
# #0 glancing_angle
+# #1 cal_number=1
+# #2 cal_number=2
+# #3 cal_number=4
+
+
+

との記載があれば、1列目は視写角、2列目は計算データファイルの1列目に相当する反射強度、3列目は計算データファイルの2列目に相当する反射強度、4列目は計算データファイルの4列目に相当する反射強度が記されていることがわかります。

+

また、各列の反射強度は各列の総和が1になるように規格化されています。目的関数値（R-factor及びR-factorの二乗）を算出する際は、データ列ごとの重み spot_weight を加味して計算されています。

+

以下、出力例です。

+
#value_01 =  0.00000 value_02 =  0.00000
+#Rfactor_type = A
+#normalization = MANY_BEAM
+#weight_type = manual
+#fx(x) = 0.03686180462340505
+#cal_number = [1, 2, 4, 6, 8]
+#spot_weight = [0.933 0.026 0.036 0.003 0.002]
+#NOTICE : Intensities are NOT multiplied by spot_weight.
+#The intensity I_(spot) for each spot is normalized as in the following equation.
+#sum( I_(spot) ) = 1
+#
+# #0 glancing_angle
+# #1 cal_number=1
+# #2 cal_number=2
+# #3 cal_number=4
+# #4 cal_number=6
+# #5 cal_number=8
+0.30000 1.278160358686800e-02 1.378767858296659e-04 8.396046839668212e-14 1.342648818357391e-30 6.697979700048016e-53
+0.40000 1.778953628930054e-02 5.281839702773564e-04 2.108814173486245e-12 2.467220122612354e-28 7.252675318478533e-50
+0.50000 2.247181148723425e-02 1.671115124520428e-03 4.250758278908295e-11 3.632860054842994e-26 6.291667506376419e-47
+...
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/solver/sxrd.html b/manual/v2.2.0/ja/solver/sxrd.html new file mode 100644 index 00000000..f1e4df3f --- /dev/null +++ b/manual/v2.2.0/ja/solver/sxrd.html @@ -0,0 +1,288 @@ + + + + + + + + sxrd ソルバー — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

sxrd ソルバー

+

sxrd は sxrdcalc を用いて原子位置 \(x\) や原子の占有率、デバイワラー因子を与えることで Rocking curve を計算し、実験で得られた Rocking curve からの誤差を \(f(x)\) として返す Solver です。

+
+

前準備

+

sxrdcalc は py2dmat から呼び出されます。 +そのため、あらかじめ sxrdcalc をインストールしておく必要があります。 +sxrdcalc はGitHubの以下のURLで公開されています。

+

https://github.com/sxrdcalc/sxrdcalc

+

サイトにアクセスの上、「Code」-「Download zip」よりソースコード一式をダウンロードします。 +zipファイル解凍後に、Makefileを自身の計算環境に合うように編集したあとに、 make コマンドを打つことで sxrdcalc の実行ファイルができます。

+

なお、 py2dmat を実行する前にあらかじめバルクデータを作成する必要があります(フォーマットについては、後述のソルバー用補助ファイルをご覧ください)。

+
+
+

入力パラメータ

+

solver セクション中のサブセクション +config, post, param, reference を利用します。

+
+

[config] セクション

+
    +

  • sxrd_exec_file

    +

    形式: string型

    +

    説明: ソルバー sxrdcalc へのパス

    +
    • +

  • bulk_struc_in_file

    +

    形式: string型

    +

    説明: バルク構造のインプットファイル。

    +
    • +
+

以下、入力例を記載します。

+
[config]
+sxrd_exec_file = "../../sxrdcalc"
+bulk_struc_in_file = "sic111-r3xr3.blk"
+
+
+
+
+

[param] セクション

+
    +

  • scale_factor

    +

    形式: float型 (default: 1.0)

    +

    説明: ターゲットのRocking Curveとシミュレーションで得られるRocking Curveのスケールの値。

    +
    • +

  • opt_scale_factor

    +

    形式: bool型 (default: false)

    +

    説明: scale_factor を最適化するかどうかのフラグ。

    +
    • +

  • type_vector

    +

    形式: list型

    +

    説明: 最適化する変数の種類を正の数のlist形式で指定します。 +[param.atom]サブセクションで指定されるtypeの種類と、本リストが対応します。 +typeが同じ場合は、同じ変数として取り扱われます。

    +
    • +
+
+

[param.domain] サブセクション

+

本セクションではドメインを作成します。作成したいドメイン分、定義する必要があります。 +[param.domain.atom] サブサブセクションでドメイン内の情報を指定します。

+
    +

  • domain_occupancy

    +

    形式: float型

    +

    説明: ドメイン全体の占有率。

    +
    • +
+
+
+

[param.domain.atom] サブセクション

+

本セクションはドメインに所属する最適化したい原子の個数分定義を行う必要があります。 +なお、変数の種類を表すtypeは、正の数で入力します。

+
    +

  • name

    +

    形式: string型 (重複可)

    +

    説明: 最適化する原子の名前。

    +
    • +

  • pos_center

    +

    形式: list型

    +

    説明: 原子の中心座標。[\(x_0, y_0, z_0\)]の形式で記載します(\(x_0, y_0, z_0\) はfloat)。

    +
    • +

  • DWfactor

    +

    形式: float型

    +

    説明: デバイワラー因子(単位は \(\text{Å}^{2}\) )。

    +
    • +

  • occupancy

    +

    形式: float型 (default: 1.0)

    +

    説明: 原子の占有率。

    +
    • +

  • displace_vector (省略可)

    +

    形式: listのlist型

    +
    +
    説明: 原子を動かす方向を定義するベクトル。最大3方向まで指定可能。

    各リストで変位ベクトルと初期値を[type, \(D_{i1}, D_{i2}, D_{i3}\) ]のようにして定義する(typeはint、\(D_{i1}, D_{i2}, D_{i3}\) はfloat)。 +与えられた情報に従い、 +\(dr_i = (D_{i1} \vec{a} + D_{i2} \vec{b} + D_{i3} \vec{c}) * l_{type}\) +のように \(l_{type}\) を変位させます( \(\vec{a}, \vec{b}, \vec{c}\) は bulk_struc_in_file もしくは struc_in_file で指定された入力ファイルに記載された単位格子ベクトルを表します)。

    +
    +
    +
    • +

  • opt_DW (省略可)

    +

    形式: list型

    +
    +
    説明: デバイワラー因子を変化させる場合のスケールを設定します。

    [type, scale]のようにして定義されます。

    +
    +
    +
    • +

  • opt_occupancy

    +

    形式: int型

    +

    説明: 定義した場合、占有率が変化する。指定された変数がtypeを表します。

    +
    • +
+

以下、入力例を記載します。

+
[param]
+scale_factor = 1.0
+type_vector = [1, 2]
+
+[[param.domain]]
+domain_occupancy = 1.0
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.00000000, 0.00000000, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[1, 0.0, 0.0, 1.0]]
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.33333333, 0.66666667, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[1, 0.0, 0.0, 1.0]]
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.66666667, 0.33333333, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[1, 0.0, 0.0, 1.0]]
+ [[param.domain.atom]]
+   name = "Si"
+   pos_center = [0.33333333, 0.33333333, 1.00000000]
+   DWfactor = 0.0
+   occupancy = 1.0
+   displace_vector = [[2, 0.0, 0.0, 1.0]]
+
+
+
+
+
+

[reference] セクション

+
    +

  • f_in_file

    +

    形式: string型

    +

    説明: ターゲットとするロッキングカーブのインプットファイルへのパス。

    +
    • +
+
+
+
+

ソルバー用補助ファイル

+
+

ターゲット参照ファイル

+

ターゲットにするデータが格納されたファイル。 [reference] セクションの f_in_file でパスを指定します。 +1行ごとに h k l F sigma が出力されます。ここで、 h, k, l は波数, F は強度、 sigma は F の不確かさをそれぞれ表します。 +以下、ファイル例を記載します。

+
0.000000 0.000000 0.050000 572.805262 0.1
+0.000000 0.000000 0.150000 190.712559 0.1
+0.000000 0.000000 0.250000 114.163340 0.1
+0.000000 0.000000 0.350000 81.267319 0.1
+0.000000 0.000000 0.450000 62.927325 0.1
+...
+
+
+
+
+

バルク構造ファイル

+

バルク構造のデータが格納されたファイル。 [config] セクションの bulk_struc_in_file でパスを指定します。 +1行目がコメント, 2行目が a b c alpha beta gamma を表します。 +ここで、 a , b, c はユニットセルの格子定数、 alpha, beta, gamma はそれらのなす角です。 +3行目以降は atomsymbol r1 r2 r3 DWfactor occupancy を指定します。 +ここで、 atomsymbol は原子種、 r1, r2, r3 は原子の位置座標、 DWfactor はデバイワラー因子、 occupancy は占有率をそれぞれ表します。 +以下、ファイル例を記載します。

+
# SiC(111) bulk
+5.33940 5.33940  7.5510487  90.000000 90.000000 120.000000
+Si 0.00000000   0.00000000   0.00000000 0.0 1.0
+Si 0.33333333   0.66666667   0.00000000 0.0 1.0
+Si 0.66666667   0.33333333   0.00000000 0.0 1.0
+C  0.00000000   0.00000000   0.25000000 0.0 1.0
+...
+
+
+
+
+
+

出力ファイル

+

sxrd では、 計算時に出力されるファイルが、ランクの番号が記載されたフォルダ下に一式出力されます。 +ここでは、 py2dmat で独自に出力するファイルについて説明します。

+
+

stdout

+

sxrd が出力する標準出力が記載されています。 +sxrdのLeast square fittingに対して、初期パラメータとして変数を与え、1ショット計算(iteration数=0)をした際のRfactorを計算します。 +RfactorはFit results以下のRに記載されます。 +以下、出力例です。

+
---------------------------------------
+Program py2dmat/mapper_sxrd/sxrdcalc for surface x-ray diffraction calculations.
+Version 3.3.3 - August 2019
+
+
+ Inputfile: lsfit.in
+Least-squares fit of model to experimental structure factors.
+
+...
+
+Fit results:
+Fit not converged after 0 iterations.
+Consider increasing the maximum number of iterations or find better starting values.
+chi^2 = 10493110.323318, chi^2 / (degree of freedom) = 223257.666454 (Intensities)
+chi^2 = 3707027.897897, chi^2 / (degree of freedom) = 78872.933998 (Structure factors)
+R = 0.378801
+
+Scale factor:   1.00000000000000 +/- 0.000196
+Parameter Nr. 1:   3.500000 +/- 299467640982.406067
+Parameter Nr. 2:   3.500000 +/- 898402922947.218384
+
+Covariance matrix:
+          0            1            2
+ 0  0.0000000383 20107160.3315223120 -60321480.9945669472
+ 1  20107160.3315223120 89680867995567253356544.0000000000 -269042603986701827178496.0000000000
+ 2  -60321480.9945669472 -269042603986701827178496.0000000000 807127811960105615753216.0000000000
+
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/start.html b/manual/v2.2.0/ja/start.html new file mode 100644 index 00000000..8b80b1aa --- /dev/null +++ b/manual/v2.2.0/ja/start.html @@ -0,0 +1,161 @@ + + + + + + + + py2dmat のインストール — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

py2dmat のインストール

+
+

実行環境・必要なパッケージ

+
    +

  • python 3.6.8 以上

    +
    +
      +

    • 必要なpythonパッケージ

      +
      +
        +

      • tomli (>= 1.2)

        • +

      • numpy (>= 1.14)

        • +
      +
      +
      • +

    • Optional なパッケージ

      +
      +
        +

      • mpi4py (グリッド探索利用時)

        • +

      • scipy (Nelder-Mead法利用時)

        • +

      • physbo (ベイズ最適化利用時, ver. 0.3以上)

        • +
      +
      +
      • +
    +
    +
    • +
+
+
+

ダウンロード・インストール

+

下記に示す方法で、 py2dmat python パッケージと py2dmat コマンドがインストールできます。

+
    +

  • PyPI からのインストール（推奨）

    +
    +
      +

    • python3 -m pip install py2dmat

      +
      +
        +

      • --user オプションをつけるとローカル ($HOME/.local) にインストールできます

        • +

      • py2dmat[all] とすると Optional なパッケージも同時にインストールします

        • +
      +
      +
      • +
    +
    +
    • +

  • ソースコードからのインストール

    +
    +
      +

    1. git clone https://github.com/issp-center-dev/2DMAT

      2. +

    2. python3 -m pip install ./2DMAT

      +
      +
        +

      • pip のバージョンは 19 以上が必要です (python3 -m pip install -U pip で更新可能)

        • +
      +
      +
      3. +
    +
    +
    • +

  • サンプルファイルのダウンロード

    +
    +
      +

    • サンプルファイルはソースコードに同梱されています。

      • +

    • git clone https://github.com/issp-center-dev/2DMAT

      • +
    +
    +
    • +
+

なお、 py2dmat で用いる順問題ソルバーのうち、

+
    +

  • TRHEPD順問題ソルバー (sim-trhepd-rheed)

    • +

  • SXRD順問題ソルバー (sxrdcalc)

    • +

  • LEED順問題ソルバー (satleed)

    • +
+

については、別途インストールが必要です。 +インストールの詳細については各ソルバーのチュートリアルを参照してください。

+
+
+

実行方法

+

py2dmat コマンドは定義済みの最適化アルゴリズム Algorithm と順問題ソルバー Solver の組み合わせで解析を行います。:

+
$ py2dmat input.toml
+
+
+

定義済みの Algorithm については 探索アルゴリズム を、 +Solver については 順問題ソルバー を参照してください。

+

Algorithm や Solver をユーザーが準備する場合は、 py2dmat パッケージを利用します。 +詳しくは (開発者向け)ユーザー定義アルゴリズム・ソルバー を参照してください。

+

なお、 プログラムを改造する場合など、 py2dmat コマンドをインストールせずに直接実行することも可能です。 +src/py2dmat_main.py を利用してください。:

+
$ py2dmat src/py2dmat_main.py input.toml
+
+
+
+
+

アンインストール

+
$ python3 -m pip uninstall py2dmat
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tool.html b/manual/v2.2.0/ja/tool.html new file mode 100644 index 00000000..1fc1cd50 --- /dev/null +++ b/manual/v2.2.0/ja/tool.html @@ -0,0 +1,311 @@ + + + + + + + + 関連ツール — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

関連ツール

+
+

py2dmat_neighborlist

+

離散空間をモンテカルロ探索する場合に使用する近傍リスト定義ファイルを +メッシュ定義ファイルから生成するツールです。

+

pip でインストールした場合は py2dmat と同様に bin 以下に py2dmat_neighborlist という名前でインストールされます。 +もしくは、ディレクトリ中の src/py2dmat_neighborlist.py を直接実行することも可能です。

+
+

使い方

+

引数としてメッシュ定義ファイルを渡します。 +生成される近傍リスト定義ファイルの名前は -o オプションで指定可能です。

+
$ py2dmat_neighborlist -o neighborlist.txt MeshData.txt
+
+もしくは
+
+$ python3 src/py2dmat_neighborlist.py -o MeshData.txt
+
+
+

次のようなオプションが利用できます。

+
    +

  • -o output or --output output

    +
      +

    • 出力ファイル名 (default: neighborlist.txt)

      • +
    +
    • +

  • -u "unit1 unit2..." or --unit "unit1 unit2"

    +
      +

    • 各次元の長さスケール (default: すべて 1.0)

      +
        +

      • 空間次元の数だけ値を空白区切りで並べ、全体を引用符でくくってください

        • +
      +
      • +

    • 各座標はあらかじめこれらの長さスケールで除算されます

      • +
    +
    • +

  • -r radius or --radius radius

    +
      +

    • 近傍とみなされるユークリッド距離 (default: 1.0)

      • +

    • 距離は -u で除されたあとの座標に対して計算されます

      • +
    +
    • +

  • -q or --quiet

    +
      +

    • 進捗バーを表示しません

      • +

    • なお、進捗バーの表示には tqdm python パッケージが必要です

      • +
    +
    • +

  • --allow-selfloop

    +
      +

    • 自分自身を隣接リストに含めます（自己ループ）

      • +
    +
    • +

  • --check-allpairs

    +
      +

    • すべての点対に対して距離を計算します

      • +

    • デバッグ用のオプションです

      • +
    +
    • +
+

なお、 MPI を用いて計算を高速化できます。

+
+
+
+

tool/to_dft/to_dft.py

+

本ツールでは、Si等四面体構造のボンドネットワークを有する系の(001)および(111)表面系モデルについて、その原子構造から第一原理電子状態計算ソフトウェア Quantum Espresso (QE) 用の入力データを作成します。これにより、得られた構造の妥当性検証や、電子状態等の微視的な情報を取得します。なお、注目する表面と反対の表面から生じるダングリングボンド由来の電子の影響を排除するため、最下層のダングリングボンドの位置に水素原子を置く水素終端というテクニックを用いています。

+
+

必要な環境

+
    +

  • Python3 >= 3.6

    • +
+

以下のパッケージが必要です。

+ +
+
+

スクリプトの概要

+

XYZ形式で記載された構造ファイルのファイル名および、2次元的な周期構造を表すための格子ベクトルの情報などが記載された入力ファイルを読み込み、得られた座標データから、最下層と、その次の層にあたる原子の座標を抽出します。 +最下層の原子は取り除き、対応する位置に H 原子を置いて次層の原子との距離を四面体構造となる距離(例えば、Siの場合はシラン分子となる距離)に調整したモデルを作成します。 +水素終端を行ったモデルはXYZ形式で保存され、cifファイルとQuantum Espresso (QE)の入力ファイルも作成します。 +なお、QEをインストールしている場合には、そのまま計算実行することもできます。

+
+
+

チュートリアル

+
    +

  1. 参照用のXYZファイルを作成します。

    2. +
+

以下では、 tool/todft/sample/111 フォルダにある surf_bulk_new111.xyz を用います。ファイルの中身は以下の通りです。

+
12
+ surf.txt             / bulk.txt
+ Si    1.219476    0.000000    4.264930
+ Si    6.459844    0.000000    4.987850
+ Si    1.800417    1.919830    3.404650
+ Si    5.878903    1.919830    3.404650
+ Si    3.839660    1.919830    2.155740
+ Si    0.000000    1.919830    1.900440
+ Si    3.839660    0.000000    0.743910
+ Si    0.000000    0.000000    0.597210
+ Si    1.919830    0.000000   -0.678750
+ Si    5.759490    0.000000   -0.678750
+ Si    1.919830    1.919830   -2.036250
+ Si    5.759490    1.919830   -2.036250
+
+
+
    +

  1. 次に各種パラメータを設定するための入力ファイルを作成します。

    2. +
+

入力ファイルのファイル形式は toml を採用しています。以下、 tool/todft/sample/111 フォルダにある input.toml を用いて、その内容について説明します。ファイルの中身は以下の通りです。

+
[Main]
+input_xyz_file = "surf_bulk_new111.xyz"
+output_file_head = "surf_bulk_new111_ext"
+[Main.param]
+z_margin = 0.001
+slab_margin = 10.0
+r_SiH = 1.48 #angstrom
+theta = 109.5 #H-Si-H angle in degree
+[Main.lattice]
+unit_vec = [[7.67932, 0.00000, 0.00000], [0.00000, 3.83966, 0.00000]]
+[ASE]
+solver_name = "qe"
+kpts = [3,3,1]        # sampling k points (Monkhorst-Pack grid)
+command = "mpirun -np 4 ./pw.x -in espresso.pwi > espresso.pwo"
+[Solver]
+[Solver.control]
+calculation='bands' # 'scf','realx','bands',...
+pseudo_dir='./'     # Pseudopotential directory
+[Solver.system]
+ecutwfc = 20.0        # Cut-off energy in Ry
+nbands=33           # # of bands (only used in band structure calc
+[Solver.pseudo]
+Si = 'Si.pbe-mt_fhi.UPF'
+H = 'H.pbe-mt_fhi.UPF'
+
+
+

入力ファイルは、 Main , ASE , Solver の3セクションから構成されます。 +以下、各セクション毎に変数の説明を簡単に記載します。

+
+

Main セクション

+

このセクションでは、水素終端を行う際に必要なパラメータに関する設定を行います。

+
    +

  • input_xyz_file

    +

    形式: string型

    +

    説明：入力するxyzファイルの名前

    +
    • +

  • output_file_head

    +

    形式: string型

    +

    説明：出力ファイル(xyzファイルおよびcifファイル)につくヘッダ

    +
    • +
+
+
+

Main.Param セクション

+
    +

  • z_margin

    +

    形式: float型

    +

    説明: 最下層および下から2番目の原子を抽出する際に用いられるマージン。例えば、最下層にいる原子のz座標を z_min とした場合に、 z_min - z_margin <= z <= z_min + z_margin の中にいる原子が抽出されます。

    +
    • +

  • slab_margin

    +

    形式: float型

    +

    説明: スラブの大きさに下駄をはかせるためのマージン。最下層および一番上の層にいる原子のz座標を z_min , z_max とした場合に、スラブの大きさは z_max-z_min+slab_margin で与えられます。

    +
    • +

  • r_SiH

    +

    形式： float型

    +

    説明： 四面体構造の頂点(例えばSi)とH間の距離を与えます(単位は \(\mathrm{\mathring{A}}\) )。

    +
    • +

  • theta

    +

    形式： float型

    +

    説明： 四面体構造の頂点とH間の角度(例えばSi-H-Siの間の角)を与えます。

    +
    • +
+
+
+

Main.lattice セクション

+
    +

  • unit_vec

    +

    形式： list型

    +

    説明： 2次元平面を形成するユニットベクトル を指定します (ex. unit_vec = [[7.67932, 0.00000, 0.00000], [0.00000, 3.83966, 0.00000]])。

    +
    • +
+
+
+

ASE セクション

+

このセクションでは、 ASE に関連したパラメータを設定します。

+
    +

  • solver_name

    +

    形式： string型

    +

    説明： ソルバーの名前を与えます。現状では qe のみ。

    +
    • +

  • kpts

    +

    形式： list型

    +

    説明： サンプリングするkポイントを指定します(Monkhorst-Pack grid)。

    +
    • +

  • command

    +

    形式： string型

    +

    説明： ソルバーを実行するときのコマンドを記載します。

    +
    • +
+
+
+

Solver セクション

+

このセクションでは、 Solver に関連したパラメータを設定します。 +ASEの機能を用いてそのまま第一原理計算を実行する場合に指定が必要となります。 +基本的には各ソルバーの入力ファイルで指定したものと同じ構成で記載します。 +例えば、QEの場合には Solver.control に、 +QEの control セクションで設定するパラメータを記載します。

+
    +

  1. 以下のコマンドを実行します。

    2. +
+
python3 to_dft.py input.toml
+
+
+

これを実行すると、

+
    +

  • surf_bulk_new111_ext.xyz

    • +

  • surf_bulk_new111_ext.cif

    • +

  • espresso.pwi

    • +
+

が生成されます。QEおよび擬ポテンシャルへのパス設定が行われている場合には、第一原理計算がそのまま行われます。行われていない場合には、第一原理計算が実行されないため、 Calculation of get_potential_energy is not normally finished. というメッセージが最後にでますが、上記ファイルの出力は行われています。

+

以下、出力ファイルについて説明します。

+
    +

  • surf_bulk_new111_ext.xyz

    • +
+

最下層原子のHへの置換と四面体構造を形成するためのHの追加が行われた結果が出力されます。 +実際の出力内容は以下の通りです。

+
14
+Lattice="7.67932 0.0 0.0  0.0 3.83966 0.0  0.0 0.0 17.0241" Properties=species:S:1:pos:R:3 pbc="T T T"
+Si  1.219476  0.000000  4.264930
+Si  6.459844  0.000000  4.987850
+Si  1.800417  1.919830  3.404650
+Si  5.878903  1.919830  3.404650
+Si  3.839660  1.919830  2.155740
+Si  0.000000  1.919830  1.900440
+Si  3.839660  0.000000  0.743910
+Si  0.000000  0.000000  0.597210
+Si  1.919830  0.000000  -0.678750
+Si  5.759490  0.000000  -0.678750
+H  1.919830  -1.208630  -1.532925
+H  1.919830  1.208630  -1.532925
+H  5.759490  -1.208630  -1.532925
+H  5.759490  1.208630  -1.532925
+
+
+

このファイルは通常のXYZ形式の座標データとして適当な可視化ソフト等に読ませることができますが、通常コメントを書く場所に周期構造の格子ベクトルの情報が書き込まれています。出力されたファイルの3行目以降の「元素名+3次元座標」のデータをそのままQEの入力ファイルにコピーして使用する事もできます。

+

espresso.pwi はQEのscf計算用の入力ファイルで、構造最適化やバンド計算は本ファイルを適宜修正することで行うことができます。 各種設定については QEのオンラインマニュアル を参考にしてください。

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/bayes.html b/manual/v2.2.0/ja/tutorial/bayes.html new file mode 100644 index 00000000..ea5978a6 --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/bayes.html @@ -0,0 +1,295 @@ + + + + + + + + ベイズ最適化 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

ベイズ最適化

+

ここでは、ベイズ最適化を行い、回折データから原子座標を解析する方法について説明します。 +ベイズ最適化には PHYSBO を用いています。 +グリッド探索と同様に、探索グリッドを与えるデータ MeshData.txt を事前に準備する必要があります。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/sim-trhepd-rheed/single_beam/bayes にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • bulk.txt

    +

    bulk.exe の入力ファイル

    +
    • +

  • experiment.txt , template.txt

    +

    メインプログラムでの計算を進めるための参照ファイル

    +
    • +

  • ref_BayesData.txt

    +

    計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる ColorMap.txt の回答)。

    +
    • +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • prepare.sh , do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。

+
+
+

参照ファイルの説明

+

template.txt , experiment.txt については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。 +ただし、計算を軽くするため value_03 は用いずに 3.5 に固定し、 +2次元のグリッド探索を行うように変更してあります。 +実際に探索するグリッドは MeshData.txt で与えます。 +サンプルでは MeshData.txt の中身は以下のようになっています。

+
1 3.5 3.5
+2 3.6 3.5
+3 3.6 3.6
+4 3.7 3.5
+5 3.7 3.6
+6 3.7 3.7
+7 3.8 3.5
+8 3.8 3.6
+9 3.8 3.7
+10 3.8 3.8
+  ...
+
+
+

1列目が通し番号、2列目以降は template.txt に入る value_0 , value_1 の値が順に指定されています。

+
+
+

入力ファイルの説明

+

ここでは、メインプログラム用の入力ファイル input.toml について説明します。 +input.toml の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある input.toml の中身になります。

+
[base]
+dimension = 2
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+[algorithm]
+name = "bayes"
+label_list = ["z1", "z2"]
+
+[algorithm.param]
+mesh_path = "MeshData.txt"
+
+[algorithm.bayes]
+random_max_num_probes = 10
+bayes_max_num_probes = 20
+
+
+

最初に [base] セクションについて説明します。

+
    +

  • dimension は最適化したい変数の個数で、今の場合は template.txt で説明したように2つの変数の最適化を行うので、 2 を指定します。

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。

+
    +

  • name は使用したいソルバーの名前で、このチュートリアルでは、 sim-trhepd-rheed を用いた解析を行うので、 sim-trhepd-rheed を指定します。

    • +
+

ソルバーの設定は、サブセクションの [solver.config], [solver.param], [solver.reference] で行います。

+

[solver.config] セクションではメインプログラム内部で呼び出す surf.exe により得られた出力ファイルを読み込む際のオプションを指定します。

+
    +

  • calculated_first_line は出力ファイルを読み込む最初の行数を指定します。

    • +

  • calculated_last_line は出力ファイルを読み込む最後の行数を指定します。

    • +

  • row_number は出力ファイルの何列目を読み込むかを指定します。

    • +
+

[solver.param] セクションではメインプログラム内部で呼び出す surf.exe により得られた出力ファイルを読み込む際のオプションを指定します。

+
    +

  • string_list は、 template.txt で読み込む、動かしたい変数の名前のリストです。

    • +

  • label_list は、 value_0x (x=1,2) を出力する際につけるラベル名のリストです。

    • +

  • degree_max は、最大角度（度単位）の指定をします。

    • +
+

[solver.reference] セクションでは、実験データの置いてある場所と読みこむ範囲を指定します。

+
    +

  • path は実験データが置いてあるパスを指定します。

    • +

  • first は実験データファイルを読み込む最初の行数を指定します。

    • +

  • end は実験データファイルを読み込む最後の行数を指定します。

    • +
+

[algorithm] セクションでは、使用するアルゴリスムとその設定をします。

+
    +

  • name は使用したいアルゴリズムの名前で、このチュートリアルでは、ベイズ最適化による解析を行うので、 bayes を指定します。

    • +

  • label_list は、 value_0x (x=1,2) を出力する際につけるラベル名のリストです。

    • +
+

[algorithm.param] セクションで、探索パラメータを設定します。

+
    +

  • mesh_path はメッシュファイルへのパスを設定します。

    • +
+

[algorithm.bayes] セクションでは、ベイズ最適化のハイパーパラメータを設定します。

+
    +

  • random_max_num_probes は、ベイズ最適化を行う前のランダム探索する回数を指定します。

    • +

  • bayes_max_num_probes は、ベイズ探索を行う回数を指定します。

    • +
+

その他、入力ファイルで指定可能なパラメータの詳細については入力ファイルの章をご覧ください。

+
+
+

計算実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します).

+
cd sample/sim-trhepd-rheed/bayes
+
+
+

順問題の時と同様に、 bulk.exe と surf.exe をコピーします。

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

最初に bulk.exe を実行し、 bulkP.b を作成します。

+
./bulk.exe
+
+
+

そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。

+
python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

実行すると、各ランクのフォルダが作成されます。 +以下の様な標準出力がされます。

+
# parameter
+random_max_num_probes = 10
+bayes_max_num_probes = 20
+score = TS
+interval = 5
+num_rand_basis = 5000
+value_01 =  5.10000
+value_02 =  4.90000
+R-factor = 0.037237314010261195
+0001-th step: f(x) = -0.037237 (action=150)
+   current best f(x) = -0.037237 (best action=150)
+
+value_01 =  4.30000
+value_02 =  3.50000
+
+  ...
+
+
+

最初に設定したパラメータのリスト、そのあとに各ステップでの候補パラメータと、 +その時の R-factor にマイナスが乗算された f(x)``が出力されます。 +また、その時点での一番良いスコアを持つグリッドインデックス (``action)とその場合の f(x) と変数が出力されます。 +0番の下には更にグリッドのidがついたサブフォルダ Log%%%%% ( %%%%% がグリッドのid)が作成され、ソルバーの出力が保存されます +(MeshData.txt に付けられた番号がグリッドのidとして割り振られます)。 +最終的に推定されたパラメータは、BayesData.txt に出力されます。

+

今回の場合は

+
#step z1 z2 fx z1_action z2_action fx_action
+0 5.1 4.9 0.037237314010261195 5.1 4.9 0.037237314010261195
+1 5.1 4.9 0.037237314010261195 4.3 3.5 0.06050786306685965
+2 5.1 4.9 0.037237314010261195 5.3 3.9 0.06215778000834068
+3 5.1 4.9 0.037237314010261195 4.7 4.2 0.049210767760634364
+4 5.1 4.9 0.037237314010261195 5.7 3.7 0.08394457854191653
+5 5.1 4.9 0.037237314010261195 5.2 5.2 0.05556857782716691
+6 5.1 4.9 0.037237314010261195 5.7 4.0 0.0754639895013157
+7 5.1 4.9 0.037237314010261195 6.0 4.4 0.054757310814479355
+8 5.1 4.9 0.037237314010261195 6.0 4.2 0.06339787375966344
+9 5.1 4.9 0.037237314010261195 5.7 5.2 0.05348404677676544
+10 5.1 4.7 0.03002813055356341 5.1 4.7 0.03002813055356341
+11 5.1 4.7 0.03002813055356341 5.0 4.4 0.03019977423448576
+12 5.3 4.5 0.02887504880071686 5.3 4.5 0.02887504880071686
+13 5.1 4.5 0.025865346123665988 5.1 4.5 0.025865346123665988
+14 5.2 4.4 0.02031077875240244 5.2 4.4 0.02031077875240244
+15 5.2 4.4 0.02031077875240244 5.2 4.6 0.023291891689059388
+16 5.2 4.4 0.02031077875240244 5.2 4.5 0.02345999725278686
+17 5.2 4.4 0.02031077875240244 5.1 4.4 0.022561543431398066
+18 5.2 4.4 0.02031077875240244 5.3 4.4 0.02544527153306051
+19 5.2 4.4 0.02031077875240244 5.1 4.6 0.02778877135528466
+20 5.2 4.3 0.012576357659158034 5.2 4.3 0.012576357659158034
+21 5.1 4.2 0.010217361468113488 5.1 4.2 0.010217361468113488
+22 5.1 4.2 0.010217361468113488 5.2 4.2 0.013178053637167673
+  ...
+
+
+

のように得られます。1列目にステップ数、2列目、3列目、4列目にその時点での最高スコアを与える +value_01, value_02 と R-factor が記載されます。 +続けて、そのステップで候補となった value_01, value_02 と R-factor が記載されます。 +今回の場合は21ステップ目で正しい解が得られていることがわかります。

+

なお、一括計算するスクリプトとして do.sh を用意しています。 +do.sh では BayesData.dat と ref_BayesData.dat の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。

+
sh prepare.sh
+
+./bulk.exe
+
+time python3 ../../../../src/py2dmat_main.py input.toml
+
+echo diff BayesData.txt ref_BayesData.txt
+res=0
+diff BayesData.txt ref_BayesData.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: BayesData.txt.txt and ref_BayesData.txt.txt differ
+  false
+fi
+
+
+
+
+

計算結果の可視化

+

BayesData.txt を参照することで、何ステップ目のパラメータが最小スコアを与えたかがわかります。 +RockingCurve.txt は各ステップ毎にサブフォルダに格納されているので、 +minsearch.rst の手順に従い、実験値との比較を行うことが可能です。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/exchange.html b/manual/v2.2.0/ja/tutorial/exchange.html new file mode 100644 index 00000000..ddad0fc3 --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/exchange.html @@ -0,0 +1,256 @@ + + + + + + + + レプリカ交換モンテカルロ法による探索 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

レプリカ交換モンテカルロ法による探索

+

ここでは、レプリカ交換モンテカルロ法によって、回折データから原子座標を解析する方法について説明します。 +具体的な計算手順は minsearch の時と同様です。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/sim-threpd-rheed/single_beam/exchange にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • bulk.txt

    +

    bulk.exe の入力ファイル

    +
    • +

  • experiment.txt , template.txt

    +

    メインプログラムでの計算を進めるための参照ファイル

    +
    • +

  • ref.txt

    +

    計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる best_result.txt の回答)。

    +
    • +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • prepare.sh , do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。

+
+
+

参照ファイルの説明

+

template.txt , experiment.txt については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。

+
+
+

入力ファイルの説明

+

ここでは、メインプログラム用の入力ファイル input.toml について説明します。 +input.toml の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある input.toml の中身になります。

+
[base]
+dimension = 2
+
+[algorithm]
+name = "exchange"
+label_list = ["z1", "z2"]
+seed = 12345
+
+[algorithm.param]
+min_list = [3.0, 3.0]
+max_list = [6.0, 6.0]
+
+[algorithm.exchange]
+numsteps = 1000
+numsteps_exchange = 20
+Tmin = 0.005
+Tmax = 0.05
+Tlogspace = true
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+
+

ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。

+

[base] セクションはメインプログラム全体のパラメータです。 +dimension は最適化したい変数の個数で、今の場合は2つの変数の最適化を行うので、2 を指定します。

+

[algorithm] セクションは用いる探索アルゴリズムを設定します。 +交換モンテカルロ法を用いる場合には、 name に "exchange" を指定します。 +label_list は、value_0x (x=1,2) を出力する際につけるラベル名のリストです。 +seed は擬似乱数生成器に与える種です。

+

[algorithm.param] サブセクションは、最適化したいパラメータの範囲などを指定します。 +min_list は最小値、 max_list は最大値を示します。

+

[algorithm.exchange] サブセクションは、交換モンテカルロ法のハイパーパラメータを指定します。

+
    +

  • numstep はモンテカルロ更新の回数です。

    • +

  • numsteps_exchange で指定した回数のモンテカルロ更新の後に、温度交換を試みます。

    • +

  • Tmin, Tmax はそれぞれ温度の下限・上限です。

    • +

  • Tlogspace が true の場合、温度を対数空間で等分割します

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーを指定します。 +minsearch のチュートリアルを参照してください。

+
+
+

計算実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します).

+
cd sample/sim-trhepd-rheed/single_beam/exchange
+
+
+

順問題の時と同様に、 bulk.exe と surf.exe をコピーします。

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

最初に bulk.exe を実行し、bulkP.b を作成します。

+
./bulk.exe
+
+
+

そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。

+
mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数4のMPI並列を用いた計算を行っています。 +(Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 +mpiexec コマンドに --oversubscribed オプションを追加してください。) +実行すると、各ランクのフォルダが作成され、 +各モンテカルロステップで評価したパラメータおよび目的関数の値を記した trial.txt ファイルと、 +実際に採択されたパラメータを記した result.txt ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。

+
# step walker T fx x1 x2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+

また、 sim-trhepd-rheed ソルバーの場合は、 各作業フォルダの下にサブフォルダ Log%%%%% ( %%%%% がグリッドのid)が作成され、ロッキングカーブの情報などが記録されます +(各プロセスにおけるモンテカルロステップ数がidとして割り振られます)。

+

最後に、 best_result.txt に、目的関数 (R-factor) が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+x[0] = 4.221129370933539
+x[1] = 5.139591716517661
+
+
+

なお、一括計算するスクリプトとして do.sh を用意しています。 +do.sh では best_result.txt と ref.txt の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。

+
sh prepare.sh
+
+./bulk.exe
+
+time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml
+
+echo diff best_result.txt ref.txt
+res=0
+diff best_result.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: best_result.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

後処理

+

各ランクフォルダにある result.txt には、各レプリカでサンプリングされたデータが記録されていますが、 +Py2DMat の実装では同一レプリカが様々な温度のサンプルを保持しています。 +2DMat は、全レプリカの結果から温度ごとのサンプルに整列し直す script/separateT.py スクリプトを提供しています。

+
python3 ../../../../script/separateT.py
+
+
+

result_T%.txt に各温度点ごとにまとめなおされたデータが書き込まれます(% は温度点のindex)。 +1列目がステップ、2列めがランク、3列目が目的関数の値、4列目以降がパラメータです。

+
# T = 0.004999999999999999
+# step rank fx x1 x2
+0 0 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.07830821484593968 3.682008067401509 3.9502750191292586
+
+
+
+
+

計算結果の可視化

+

result_T%.txt を図示することで、 R-factor の小さいパラメータがどこにあるかを推定することができます。 +今回の場合は、以下のコマンドをうつことで2次元パラメータ空間の図 result.png が作成されます。

+
python3 plot_result_2d.py
+
+
+

作成された図を見ると、(5.25, 4.25) と (4.25, 5.25) 付近にサンプルが集中していることと、 +R-factor の値が小さいことがわかります。

+
+../_images/exchange.png +
+

サンプルされたパラメータと R-factor 。横軸は value_01 , 縦軸は value_02 を表す。

+
+
+

また、 RockingCurve.txt が各サブフォルダに格納されています。 +LogXXX_YYY の XXX はモンテカルロのステップ数、 YYY は各MPIプロセス内のレプリカの番号です。 +これを用いることで、前チュートリアルの手順に従い、実験値との比較も行うことが可能です。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/index.html b/manual/v2.2.0/ja/tutorial/index.html new file mode 100644 index 00000000..ab490c5d --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/index.html @@ -0,0 +1,102 @@ + + + + + + + + チュートリアル — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

チュートリアル

+

順問題ソルバーとして用意されている sim_trhepd_rheed は東北大学の花田貴先生によって開発された +物質反射高速（陽）電子回折(RHEED, TRHEPD)の解析ソフトウェアをベースに作成されています。 +TRHEPDでは原子座標を与えた場合に、回折データがシミュレーション結果として与えられます。 +そのため、原子座標から回折データへの順問題を取り扱っているといえます。 +一方、多くの場合回折データは実験で与えられ、それを再現するような原子座標などが求められます。 +これらは上記の順問題に対して、逆問題に相当します。

+

本ソフトウェアでは逆問題を解くためのアルゴリズムとして

+
    +

  • minsearch

    +

    Nealder-Mead法を用いもっともらしい原子座標を推定

    +
    • +

  • mapper_mpi

    +

    与えられたパラメータの探索グリッドを全探索することで、もっともらしい原子座標を推定

    +
    • +

  • bayes

    +

    ベイズ最適化を用いもっともらしい原子座標を推定

    +
    • +

  • exchange

    +

    レプリカ交換モンテカルロ法を用いてもっともらしい原子座標をサンプリング

    +
    • +

  • pamc

    +

    ポピュレーションアニーリング法を用いてもっともらしい原子座標をサンプリング

    +
    • +
+

の5つのアルゴリズムが用意されています。 +本チュートリアルでは、最初に順問題プログラム sim_trhepd_rheed の実行方法、 +その後に minsearch , mapper_mpi, bayes, exchange, pamc の実行方法について順に説明します。 +また、制約式を用いて探索範囲を制限出来る [runner.limitation] セクションを使用した実行方法も説明しています。 +最後に、自分で順問題ソルバーを定義する簡単な例について説明します。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/limitation.html b/manual/v2.2.0/ja/tutorial/limitation.html new file mode 100644 index 00000000..91f2d1b1 --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/limitation.html @@ -0,0 +1,226 @@ + + + + + + + + 制約式を適用したレプリカ交換モンテカルロ法による探索 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

制約式を適用したレプリカ交換モンテカルロ法による探索

+

ここでは、 [runner.limitation] セクションに設定できる制約式機能のチュートリアルを示します。 +例として、レプリカ交換モンテカルロ法を、Himmelblauを対象に探索する計算に制約式を適用します。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/analytical/limitation にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • ref.txt

    +

    計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる best_result.txt の回答)。

    +
    • +

  • input.toml

    +

    メインプログラムの入力ファイル。

    +
    • +

  • do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。

+
+
+

入力ファイルの説明

+

メインプログラム用の入力ファイル input.toml について説明します。 +input.toml の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある input.toml の中身になります。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "exchange"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+unit_list = [0.3, 0.3]
+
+[algorithm.exchange]
+Tmin = 1.0
+Tmax = 100000.0
+numsteps = 10000
+numsteps_exchange = 100
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.limitation]
+co_a = [[1, -1],[1, 1]]
+co_b = [[0], [-1]]
+
+
+

ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。

+

[base] セクションはメインプログラム全体のパラメータです。 +dimension は最適化したい変数の個数で、今の場合は2つの変数の最適化を行うので、2 を指定します。

+

[algorithm] セクションは用いる探索アルゴリズムを設定します。 +交換モンテカルロ法を用いる場合には、 name に "exchange" を指定します。 +seed は擬似乱数生成器に与える種です。

+

[algorithm.param] サブセクションは、最適化したいパラメータの範囲などを指定します。 +min_list は最小値、 max_list は最大値を示します。

+

[algorithm.exchange] サブセクションは、交換モンテカルロ法のハイパーパラメータを指定します。

+
    +

  • numstep はモンテカルロ更新の回数です。

    • +

  • numsteps_exchange で指定した回数のモンテカルロ更新の後に、温度交換を試みます。

    • +

  • Tmin, Tmax はそれぞれ温度の下限・上限です。

    • +

  • Tlogspace が true の場合、温度を対数空間で等分割します。このオプションはデフォルト値が true であるため、今回の input.toml に指定は無いですが、 true になっています。

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーを指定します。 +今回は analytical ソルバーを指定しています。 analytical ソルバーは function_name パラメータを用いて関数を設定します。 +今回はHimmelblau 関数を指定しています。 +analytical ソルバーに関してはチュートリアル「順問題ソルバーの追加」を参照してください。

+

[runner] セクションは [runner.limitation] サブセクションを持ち、この中に制約式を設定します。 +現在、制約式は \(N\) 次元のパラメータ \(x\) 、 \(M\) 行 \(N\) 列の行列 \(A\) 、 +\(M\) 次元の縦ベクトル \(b\) から定義される \(Ax+b>0\) の制約式が利用可能です。 +パラメータとしては、以下の項目が設定可能です。

+
    +

  • co_a は行列 \(A\) を設定します。

    • +

  • co_b は縦ベクトル \(b\) を設定します。

    • +
+

パラメータの詳しい設定方法はマニュアル内「入力ファイル」項の「 [limitation] セクション」を参照してください。 +今回は

+
+\[\begin{split}x_{1} − x_{2} > 0\\ +x_{1} + x_{2} − 1 > 0\end{split}\]
+

の制約式を課して実行しています。

+
+
+

計算実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します).

+
cd sample/analytical/limitation
+
+
+

そのあとに、メインプログラムを実行します(計算時間は通常のPCで20秒程度で終わります)。

+
mpiexec -np 10 python3 ../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数10のMPI並列を用いた計算を行っています。 +(Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 +mpiexec コマンドに --oversubscribed オプションを追加してください。) +実行すると、 output フォルダが生成され、その中に各ランクのフォルダが作成されます。 +更にその中には、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した trial.txt ファイルと、 +実際に採択されたパラメータを記した result.txt ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。 +以下は、 output/0/result.txt ファイルの冒頭部分です。

+
# step walker T fx x1 x2
+0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569
+1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+
+
+

最後に、 output/best_result.txt に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。

+
nprocs = 10
+rank = 2
+step = 4523
+walker = 0
+fx = 0.00010188398524402734
+x1 = 3.584944906595298
+x2 = -1.8506985826548874
+
+
+

なお、一括計算するスクリプトとして do.sh を用意しています。 +do.sh では best_result.txt と ref.txt の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。

+
#!/bin/bash
+mpiexec -np 10 --oversubscribe python3 ../../../src/py2dmat_main.py input.toml
+
+echo diff output/best_result.txt ref.txt
+res=0
+diff output/best_result.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: best_result.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

計算結果の可視化

+

result.txt を図示して、制約式を満たした座標のみを探索しているかを確認します。 +今回の場合は、以下のコマンドを打つことで2次元パラメータ空間の図が <実行日>_histogram フォルダ内に作成されます。 +生成されるヒストグラムは、burn-in期間として最初の1000ステップ分の探索を捨てたデータを使用しています。

+
python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1
+
+
+

作成された図には2本の直線 \(x_{1} − x_{2} = 0, x_{1} + x_{2} − 1 = 0\) と +探索結果(事後確率分布のヒストグラム)を図示しています。 +図を見ると \(x_{1} − x_{2} > 0, x_{1} + x_{2} − 1 > 0\) の範囲のみ探索をしていることが確認できます。 +以下に図の一部を掲載します。

+
+../_images/limitation_beta_min.png +
+
+../_images/limitation_beta_max.png +
+

サンプルされたパラメータと確率分布。横軸は value_01 (x1) , 縦軸は value_02 (x2) を表す。

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/minsearch.html b/manual/v2.2.0/ja/tutorial/minsearch.html new file mode 100644 index 00000000..6c122da7 --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/minsearch.html @@ -0,0 +1,307 @@ + + + + + + + + Nelder-Mead法による最適化 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

Nelder-Mead法による最適化

+

ここでは、Nelder-Mead法を用いて回折データから原子座標を解析する逆問題の計算を行う方法について説明します。 +具体的な計算手順は以下の通りです。

+
    +

  1. 参照ファイルの準備

    +

    合わせたい参照ファイル (今回は後述する experiment.txt に相当)を準備する。

    +
    2. +

  2. 表面構造のバルク部分に関する計算実行

    +

    bulk.exe を sample/sim-trhepd-rheed/minsearch にコピーして計算を実行する。

    +
    3. +

  3. メインプログラムの実行

    +

    src/py2dmat_main.py を用いて計算実行し原子座標を推定する。

    +
    4. +
+

メインプログラムでは、 +Nelder-Mead法 (scipy.optimize.fmin を使用)を用いて、 +ソルバー(今回は surf.exe )を用いて得られた強度と、 +参照ファイル(experiment.txt)に記載された強度のずれ(R値)を最小化するパラメータを探索します。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/py2dmat/sim-threpd-rheed/single_beam/minsearch にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • bulk.txt

    +

    bulk.exe の入力ファイル

    +
    • +

  • experiment.txt , template.txt

    +

    メインプログラムでの計算を進めるための参照ファイル

    +
    • +

  • ref.txt

    +

    本チュートリアルで求めたい回答が記載されたファイル

    +
    • +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • prepare.sh , do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。

+
+
+

参照ファイルの説明

+

template.txt は surf.exe の入力ファイルとほぼ同じ形式のファイルです。 +動かすパラメータ（求めたい原子座標などの値）を「 value_* 」などの適当な文字列に書き換えられています。 +以下が、 template.txt の中身です。

+
2                                    ,NELMS,  -------- Ge(001)-c4x2
+32,1.0,0.1                           ,Ge Z,da1,sap
+0.6,0.6,0.6                          ,BH(I),BK(I),BZ(I)
+32,1.0,0.1                           ,Ge Z,da1,sap
+0.4,0.4,0.4                          ,BH(I),BK(I),BZ(I)
+9,4,0,0,2, 2.0,-0.5,0.5               ,NSGS,msa,msb,nsa,nsb,dthick,DXS,DYS
+8                                    ,NATM
+1, 1.0, 1.34502591  1       value_01   ,IELM(I),ocr(I),X(I),Y(I),Z(I)
+1, 1.0, 0.752457792 1       value_02
+2, 1.0, 1.480003343 1.465005851     value_03
+2, 1.0, 2   1.497500418     2.281675
+2, 1.0, 1   1.5     1.991675
+2, 1.0, 0   1       0.847225
+2, 1.0, 2   1       0.807225
+2, 1.0, 1.009998328 1       0.597225
+1,1                                  ,(WDOM,I=1,NDOM)
+
+
+

今回の入力ファイルでは、 value_01, value_02, value_03 を用いています。 +サンプルフォルダには、原子位置が正しく推定できているかを知るための参照ファイルとして、 +ref.txt が置いてあります。ファイルの中身は

+
fx = 7.382680568652868e-06
+z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+

となっており、 value_0x が z_x (x=1, 2, 3)に対応しています。 +fx は目的関数の最適値です。 +experiment.txt は、メインプログラムで参照に用いるファイルで、 +template.txt に ref.txt の入っているパラメータをいれ、 +順問題のチュートリアルと同様な手順で計算して得られる convolution.txt に相当しています +(順問題のチュートリアルとは bulk.exe , suft.exe の入力ファイルが異なるのでご注意ください)。

+
+
+

入力ファイルの説明

+

ここでは、メインプログラム用の入力ファイル input.toml の準備をします。 +input.toml の詳細については入力ファイルに記載されています。 +ここでは、サンプルファイルにある input.toml の中身について説明します。

+
[base]
+dimension = 3
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02", "value_03" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+[algorithm]
+name = "minsearch"
+label_list = ["z1", "z2", "z3"]
+
+[algorithm.param]
+min_list = [0.0, 0.0, 0.0]
+max_list = [10.0, 10.0, 10.0]
+initial_list = [5.25, 4.25, 3.50]
+
+
+

最初に [base] セクションについて説明します。

+
    +

  • dimension は最適化したい変数の個数で、今の場合は template.txt で説明したように3つの変数の最適化を行うので、3 を指定します。

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。

+
    +

  • name は使用したいソルバーの名前で、このチュートリアルでは、 sim-trhepd-rheed を用いた解析を行うので、 sim-trhepd-rheed を指定します。

    • +
+

ソルバーの設定は、サブセクションの [solver.config], [solver.param], [solver.reference] で行います。

+

[solver.config] セクションではメインプログラム内部で呼び出す surf.exe により得られた出力ファイルを読み込む際のオプションを指定します。

+
    +

  • calculated_first_line は出力ファイルを読み込む最初の行数を指定します。

    • +

  • calculated_last_line は出力ファイルを読み込む最後の行数を指定します。

    • +

  • row_number は出力ファイルの何列目を読み込むかを指定します。

    • +
+

[solver.param] セクションではメインプログラム内部で呼び出す surf.exe により得られた出力ファイルを読み込む際のオプションを指定します。

+
    +

  • string_list は、 template.txt で読み込む、動かしたい変数の名前のリストです。

    • +

  • degree_max は、最大角度（度単位）の指定をします。

    • +
+

[solver.reference] セクションでは、実験データの置いてある場所と読みこむ範囲を指定します。

+
    +

  • path は実験データが置いてあるパスを指定します。

    • +

  • first は実験データファイルを読み込む最初の行数を指定します。

    • +

  • end は実験データファイルを読み込む最後の行数を指定します。

    • +
+

[algorithm] セクションでは、使用するアルゴリスムとその設定をします。

+
    +

  • name は使用したいアルゴリズムの名前で、このチュートリアルでは、Nelder-Mead法 を用いた解析を行うので、 minsearch を指定します。

    • +

  • label_list は、value_0x (x=1,2,3) を出力する際につけるラベル名のリストです。

    • +
+

[algorithm.param] セクションでは、探索するパラメータの範囲や初期値を指定します。

+
    +

  • min_list と max_list はそれぞれ探索範囲の最小値と最大値を指定します。

    • +

  • initial_list は初期値を指定します。

    • +
+

ここではデフォルト値を用いるため省略しましたが、その他のパラメータ、例えばNelder-Mead法で使用する収束判定などについては、[algorithm] セクションで行うことが可能です。 +詳細については入力ファイルの章をご覧ください。

+
+
+

計算実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します).

+
cd sample/sim-trhepd-rheed/single_beam/minsearch
+
+
+

順問題の時と同様に、bulk.exe と surf.exe をコピーします。

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

最初に bulk.exe を実行し、bulkP.b を作成します。

+
./bulk.exe
+
+
+

そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。

+
python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

実行すると、以下の様な出力がされます。

+
Read experiment.txt
+z1 =  5.25000
+z2 =  4.25000
+z3 =  3.50000
+[' 5.25000', ' 4.25000', ' 3.50000']
+PASS : degree in lastline = 7.0
+PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70
+R-factor = 0.015199251773721183
+z1 =  5.50000
+z2 =  4.25000
+z3 =  3.50000
+[' 5.50000', ' 4.25000', ' 3.50000']
+PASS : degree in lastline = 7.0
+PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70
+R-factor = 0.04380131351780189
+z1 =  5.25000
+z2 =  4.50000
+z3 =  3.50000
+[' 5.25000', ' 4.50000', ' 3.50000']
+...
+
+
+

z1, z2, z3 に各ステップでの候補パラメータと、その時の``R-factor`` が出力されます。 +また各ステップでの計算結果は Logxxxxx (xxxxxにステップ数)のフォルダに出力されます。 +最終的に推定されたパラメータは、res.dat に出力されます。今の場合、

+
z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+

が得られ、正解のデータ ref.txt と同じ値が得られていることがわかります。 +なお、一括計算するスクリプトとして do.sh を用意しています。 +do.sh では res.txt と ref.txt の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。

+
sh ./prepare.sh
+
+./bulk.exe
+
+time python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+echo diff res.txt ref.txt
+res=0
+diff res.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo Test PASS
+  true
+else
+  echo Test FAILED: res.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

計算結果の可視化

+

それぞれのステップでのロッキングカーブのデータは、 LogXXX_00000001 (XXX はステップ数)フォルダに RockingCurve.txt として保存されています (LogXXX_00000000 フォルダはNelder-Mead 法の途中での評価です)。 +このデータを可視化するツール draw_RC_double.py が準備されています。 +ここでは、このツールを利用して結果を可視化します。

+
cp 0/Log00000001_00000001/RockingCurve.txt RockingCurve_ini.txt
+cp 0/Log00000062_00000001/RockingCurve.txt RockingCurve_con.txt
+cp ../../../../script/draw_RC_double.py .
+python draw_RC_double.py
+
+
+

上記を実行することで、RC_double.png が出力されます。

+
+../_images/RC_double_minsearch.png +
+

Nelder-Mead法を用いた解析。赤丸が実験値、青線が最初のステップ、緑線が最後のステップで得られたロッキングカーブを表す。

+
+
+

図から最後のステップでは実験値と一致していることがわかります。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/mpi.html b/manual/v2.2.0/ja/tutorial/mpi.html new file mode 100644 index 00000000..156b2fd1 --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/mpi.html @@ -0,0 +1,265 @@ + + + + + + + + グリッド型探索 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

グリッド型探索

+

ここでは、グリッド型探索を行い、回折データから原子座標を解析する方法について説明します。 +グリッド型探索はMPIに対応しています。具体的な計算手順は minsearch の時と同様です。 +ただし、探索グリッドを与えるデータ MeshData.txt を事前に準備する必要があります。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/sim-trhepd-rheed/single_beam/mapper にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • bulk.txt

    +

    bulk.exe の入力ファイル

    +
    • +

  • experiment.txt , template.txt

    +

    メインプログラムでの計算を進めるための参照ファイル

    +
    • +

  • ref_ColorMap.txt

    +

    計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる ColorMap.txt の回答)。

    +
    • +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • prepare.sh , do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。

+
+
+

参照ファイルの説明

+

template.txt , experiment.txt については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。 +ただし、計算を軽くするため value_03 は用いずに 3.5 に固定し、 +2次元のグリッド探索を行うように変更してあります。 +実際に探索するグリッドは MeshData.txt で与えます。 +サンプルでは MeshData.txt の中身は以下のようになっています。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+

1列目が通し番号、2列目以降は template.txt に入る``value_0`` , value_1 の値が順に指定されています。

+
+
+

入力ファイルの説明

+

ここでは、メインプログラム用の入力ファイル input.toml について説明します。 +input.toml の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある input.toml の中身になります。

+
[base]
+dimension = 2
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+[algorithm]
+name = "mapper"
+label_list = ["z1", "z2"]
+
+
+

最初に [base] セクションについて説明します。

+
    +

  • dimension は最適化したい変数の個数で、今の場合は template.txt で説明したように2つの変数の最適化を行うので、2 を指定します。

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。

+
    +

  • name は使用したいソルバーの名前で、このチュートリアルでは、 sim-trhepd-rheed を用いた解析を行うので、 sim-trhepd-rheed を指定します。

    • +
+

ソルバーの設定は、サブセクションの [solver.config], [solver.param], [solver.reference] で行います。

+

[solver.config] セクションではメインプログラム内部で呼び出す surf.exe により得られた出力ファイルを読み込む際のオプションを指定します。

+
    +

  • calculated_first_line は出力ファイルを読み込む最初の行数を指定します。

    • +

  • calculated_last_line は出力ファイルを読み込む最後の行数を指定します。

    • +

  • row_number は出力ファイルの何列目を読み込むかを指定します。

    • +
+

[solver.param] セクションではメインプログラム内部で呼び出す surf.exe により得られた出力ファイルを読み込む際のオプションを指定します。

+
    +

  • string_list は、 template.txt で読み込む、動かしたい変数の名前のリストです。

    • +

  • label_list は、value_0x (x=1,2) を出力する際につけるラベル名のリストです。

    • +

  • degree_max は、最大角度（度単位）の指定をします。

    • +
+

[solver.reference] セクションでは、実験データの置いてある場所と読みこむ範囲を指定します。

+
    +

  • path は実験データが置いてあるパスを指定します。

    • +

  • first は実験データファイルを読み込む最初の行数を指定します。

    • +

  • end は実験データファイルを読み込む最後の行数を指定します。

    • +
+

[algorithm] セクションでは、使用するアルゴリスムとその設定をします。

+
    +

  • name は使用したいアルゴリズムの名前で、このチュートリアルでは、グリッド探索による解析を行うので、 mapper を指定します。

    • +

  • label_list は、value_0x (x=1,2) を出力する際につけるラベル名のリストです。

    • +
+

その他、入力ファイルで指定可能なパラメータの詳細については入力ファイルの章をご覧ください。

+
+
+

計算実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します).

+
cd sample/sim-trhepd-rheed/single_beam/mapper
+
+
+

順問題の時と同様に、bulk.exe と surf.exe をコピーします。

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

最初に bulk.exe を実行し、bulkP.b を作成します。

+
./bulk.exe
+
+
+

そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。

+
mpiexec -np 2 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数2のMPI並列を用いた計算を行っています。 +実行すると、各ランクのフォルダが作成され、その下に更にグリッドのidがついたサブフォルダ Log%%%%% ( %%%%% がグリッドのid)が作成されます +(MeshData.txt に付けられた番号がグリッドのidとして割り振られます)。 +以下の様な標準出力がされます。

+
Iteration : 1/33
+Read experiment.txt
+mesh before: [1.0, 6.0, 6.0]
+z1 =  6.00000
+z2 =  6.00000
+[' 6.00000', ' 6.00000']
+PASS : degree in lastline = 7.0
+PASS : len(calculated_list) 70 == len(convolution_I_calculated_list)70
+R-factor = 0.04785241875354398
+...
+
+
+

z1, z2 に各メッシュでの候補パラメータと、その時の``R-factor`` が出力されます。 +最終的にグリッド上の全ての点で計算された R-factor は、ColorMap.txt に出力されます。 +今回の場合は

+
6.000000 6.000000 0.047852
+6.000000 5.750000 0.055011
+6.000000 5.500000 0.053190
+6.000000 5.250000 0.038905
+6.000000 5.000000 0.047674
+6.000000 4.750000 0.065919
+6.000000 4.500000 0.053675
+6.000000 4.250000 0.061261
+6.000000 4.000000 0.069351
+6.000000 3.750000 0.071868
+6.000000 3.500000 0.072739
+...
+
+
+

のように得られます。1列目、2列目に value_01, value_02 の値が、3列目に R-factor が記載されます。 +なお、一括計算するスクリプトとして do.sh を用意しています。 +do.sh では ColorMap.dat と ref_ColorMap.dat の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。

+
sh prepare.sh
+
+./bulk.exe
+
+time mpiexec -np 2 python3 ../../../../src/py2dmat_main.py input.toml
+
+echo diff ColorMap.txt ref_ColorMap.txt
+res=0
+diff ColorMap.txt ref_ColorMap.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: ColorMap.txt and ref_ColorMap.txt differ
+  false
+fi
+
+
+
+
+

計算結果の可視化

+

ColorMap.txt を図示することで、R-factor の小さいパラメータがどこにあるかを推定することができます。 +今回の場合は、以下のコマンドをうつことで2次元パラメータ空間の図 ColorMapFig.png が作成されます。

+
python3 plot_colormap_2d.py
+
+
+

作成された図を見ると、(5.25, 4.25) 付近に最小値を持っていることがわかります。

+
+../_images/mapper.png +
+

2次元パラメータ空間上での R-factor 。

+
+
+

また、 RockingCurve.txt が各サブフォルダに格納されています。 +これを用いることで、前チュートリアルの手順に従い、実験値との比較も行うことが可能です。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/pamc.html b/manual/v2.2.0/ja/tutorial/pamc.html new file mode 100644 index 00000000..59827dc9 --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/pamc.html @@ -0,0 +1,268 @@ + + + + + + + + ポピュレーションアニーリングによる探索 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

ポピュレーションアニーリングによる探索

+

ここでは、ポピュレーションアニーリングを用いて、回折データから原子座標を解析する方法について説明します。 +具体的な計算手順は minsearch の時と同様です。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/sim-trhepd-rheed/single_beam/pamc にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • bulk.txt

    +

    bulk.exe の入力ファイル

    +
    • +

  • experiment.txt , template.txt

    +

    メインプログラムでの計算を進めるための参照ファイル

    +
    • +

  • ref.txt

    +

    計算が正しく実行されたか確認するためのファイル(本チュートリアルを行うことで得られる fx.txt の回答)。

    +
    • +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • prepare.sh , do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。

+
+
+

参照ファイルの説明

+

template.txt , experiment.txt については、 +前のチュートリアル(Nealder-Mead法による最適化)と同じものを使用します。

+
+
+

入力ファイルの説明

+

ここでは、メインプログラム用の入力ファイル input.toml について説明します。 +input.toml の詳細については入力ファイルに記載されています。 +以下は、サンプルファイルにある input.toml の中身になります。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "pamc"
+label_list = ["z1", "z2"]
+seed = 12345
+
+[algorithm.param]
+min_list = [3.0, 3.0]
+max_list = [6.0, 6.0]
+unit_list = [0.3, 0.3]
+
+[algorithm.pamc]
+numsteps_annealing = 5
+bmin = 0.0
+bmax = 200.0
+Tnum = 21
+Tlogspace = false
+nreplica_per_proc = 10
+
+[solver]
+name = "sim-trhepd-rheed"
+
+[solver.config]
+calculated_first_line = 5
+calculated_last_line = 74
+row_number = 2
+
+[solver.param]
+string_list = ["value_01", "value_02" ]
+degree_max = 7.0
+
+[solver.reference]
+path = "experiment.txt"
+first = 1
+last = 70
+
+
+

ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。

+

[base] セクションはメインプログラム全体のパラメータです。 +dimension は最適化したい変数の個数で、今の場合は2つの変数の最適化を行うので、2 を指定します。

+

[algorithm] セクションは用いる探索アルゴリズムを設定します。 +交換モンテカルロ法を用いる場合には、 name に "exchange" を指定します。 +label_list は、value_0x (x=1,2) を出力する際につけるラベル名のリストです。 +seed は擬似乱数生成器に与える種です。

+

[algorithm.param] サブセクションは、最適化したいパラメータの範囲などを指定します。 +min_list は最小値、 max_list は最大値を示します。 +unit_list はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。

+

[algorithm.pamc] サブセクションは、ポピュレーションアニーリングのハイパーパラメータを指定します。

+
    +

  • numsteps_annealing で指定した回数のモンテカルロ更新の後に、逆温度を増やします (温度を下げます)。

    • +

  • bmin, bmax はそれぞれ逆温度の下限・上限です。

    • +

  • Tnum は計算する温度・逆温度の点数です。

    • +

  • Tlogspace が true の場合、温度を対数空間で等分割します

    • +

  • nreplica_per_proc はMPIプロセスひとつが受け持つ計算レプリカの数です。

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーを指定します。 +minsearch のチュートリアルを参照してください。

+
+
+

計算実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します).

+
cd sample/sim-trhepd-rheed/pamc
+
+
+

順問題の時と同様に、 bulk.exe と surf.exe をコピーします。

+
cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
+
+
+

最初に bulk.exe を実行し、bulkP.b を作成します。

+
./bulk.exe
+
+
+

そのあとに、メインプログラムを実行します(計算時間は通常のPCで数秒程度で終わります)。

+
mpiexec -np 4 python3 ../../../../src/py2dmat_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数4のMPI並列を用いた計算を行っています。 +(Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 +mpiexec コマンドに --oversubscribed オプションを追加してください。) +実行すると、各ランクのフォルダが作成され、 +温度ごとに、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した trial_TXXX.txt ファイル(XXX は温度点の番号)と、 +実際に採択されたパラメータを記した result_TXXX.txt ファイル、さらにそれぞれを結合した trial.txt, result.txt ファイルが生成されます。 +それぞれ書式は同じで、最初の2列がステップ数とプロセス内のwalker (replica) 番号、次が（逆）温度、3列目が目的関数の値、4列目以降がパラメータです。 +最後の2 列は、 walker の重み (Neal-Jarzynski weight) と祖先（計算を開始したときのレプリカ）の番号です。

+
# step walker beta fx z1 z2 weight ancestor
+0 0 0.0 0.07702743614780189 5.788848278451443 3.949126663745358 1.0 0
+0 1 0.0 0.08737730661436376 3.551756435031283 3.6136808356591192 1.0 1
+0 2 0.0 0.04954470587051104 4.70317508724506 4.786634108937754 1.0 2
+0 3 0.0 0.04671675601156148 5.893543559206865 4.959531290614713 1.0 3
+0 4 0.0 0.04142014655238446 5.246719912601735 4.960709612555206 1.0 4
+
+
+

また、 sim-trhepd-rheed ソルバーの場合は、 各作業フォルダの下にサブフォルダ Log%%%%% ( %%%%% がグリッドのid)が作成され、ロッキングカーブの情報などが記録されます +(各プロセスにおけるモンテカルロステップ数がidとして割り振られます)。

+

best_result.txt に、目的関数 (R-factor) が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。

+
nprocs = 4
+rank = 0
+step = 71
+walker = 5
+fx = 0.008186713312593607
+z1 = 4.225633749839847
+z2 = 5.142666117413409
+
+
+

最後に、 fx.txt には、各温度ごとの統計情報が記録されます。

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.0 0.06428002079611472 0.002703413400677839 40 0.0 0.795
+10.0 0.061399304916174735 0.002649424392996749 40 -0.6280819199879947 0.85
+20.0 0.05904248889111052 0.0031622711212952034 40 -1.2283060742855603 0.74
+30.0 0.04956921148431115 0.0028298565759159633 40 -1.7991035905899855 0.67
+
+
+

1列目は温度・逆温度で、2・3列目は目的関数 \(f(x)\) の期待値と標準誤差、4列目はレプリカの個数、5列目は分配関数の比の対数 \(\log(Z_n/Z_0)\) です(\(Z_0\) は最初の温度点における分配関数)、6列目はモンテカルロ更新の採択率です。

+

なお、一括計算するスクリプトとして do.sh を用意しています。 +do.sh では res.txt と ref.txt の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。

+
sh prepare.sh
+
+./bulk.exe
+
+time mpiexec --oversubscribe -np 4 python3 ../../../../src/py2dmat_main.py input.toml
+
+echo diff output/fx.txt ref.txt
+res=0
+diff output/fx.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: output/fx.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

計算結果の可視化

+

result_T%.txt を図示することで、 R-factor の小さいパラメータがどこにあるかを推定することができます。 +今回の場合は、以下のコマンドをうつことで2次元パラメータ空間の図 result_fx.pdf と result_T.pdf が作成されます。 +シンボルの色はそれぞれ R-factor と逆温度 \(\beta\) に対応します。

+
python3 plot_result_2d.py
+
+
+

作成された図を見ると、(5.25, 4.25) と (4.25, 5.25) 付近にサンプルが集中していることと、 +R-factor の値が小さいことがわかります。

+
+../_images/pamc_fx.png +
+

サンプルされたパラメータ。横軸は value_01 , 縦軸は value_02 を、色は R-factor を表す。

+
+
+
+../_images/pamc_T.png +
+

サンプルされたパラメータと逆温度。横軸は value_01 , 縦軸は value_02 を、色は逆温度を表す。

+
+
+

また、 RockingCurve.txt が各サブフォルダに格納されています。 +LogXXX_YYY の XXX はモンテカルロのステップ数、 YYY は各MPIプロセス内のレプリカの番号です。 +これを用いることで、前チュートリアルの手順に従い、実験値との比較も行うことが可能です。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/sim_trhepd_rheed.html b/manual/v2.2.0/ja/tutorial/sim_trhepd_rheed.html new file mode 100644 index 00000000..61a32cfb --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/sim_trhepd_rheed.html @@ -0,0 +1,180 @@ + + + + + + + + TRHEPD 順問題ソルバー — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

TRHEPD 順問題ソルバー

+

2DMAT は順問題ソルバーのひとつとして、 反射高速(陽)電子回折(RHEED, TRHEPD)の強度計算 (A. Ichimiya, Jpn. J. Appl. Phys. 22, 176 (1983); 24, 1365 (1985)) +を行うプログラム sim-trhepd-rheed のラッパーを提供しています。 +本チュートリアルでは sim-trhepd-rheed を用い、様々なアルゴリズムを利用した解析を行います。 +最初に、チュートリアルを行うために必要な sim-trhepd-rheed のインストールおよびテストを行います。

+
+

ダウンロード・インストール

+

まずチュートリアルの前提として、 2DMAT フォルダがある場所にいることを仮定します。:

+
$ ls -d 2DMAT
+2DMAT/
+
+
+

GitHub の sim-trhepd-rheed リポジトリから、ソースコード一式を入手し、ビルドします。:

+
git clone http://github.com/sim-trhepd-rheed/sim-trhepd-rheed
+cd sim-trhepd-rheed/src
+make
+
+
+

makeが成功すると、 bulk.exe 及び surf.exe が作成されます。

+
+
+

計算実行

+

sim-trhepd-rheed では、最初に bulk.exe で表面構造のバルク部分に関する計算をします。 +その後、 bulk.exe の計算結果 (bulkP.b ファイル) を用いて、 surf.exe 表面構造の表面部分を計算します。

+

このチュートリアルでは実際に、 TRHEPD 計算をしてみます。 +サンプルとなる入力ファイルは2DMAT の sample/sim-trhepd-rheed にあります。 +まず、このフォルダを適当な作業用フォルダ work にコピーします。

+
cd ../../
+cp -r 2DMAT/sample/sim-trhepd-rheed/solver work
+cd work
+
+
+

次に bulk.exe と surf.exe を work にコピーします

+
cp ../sim-trhepd-rheed/src/bulk.exe .
+cp ../sim-trhepd-rheed/src/surf.exe .
+
+
+

bulk.exe を実行します。

+
./bulk.exe
+
+
+

上記実行時に、以下のように出力され、バルクファイル bulkP.b が生成されます。

+
0:electron 1:positron ?
+P
+input-filename (end=e) ? :
+bulk.txt
+output-filename :
+bulkP.b
+
+
+

続いて、 surf.exe を実行します。

+
./surf.exe
+
+
+

上記実行時に、以下のように出力されます。

+
bulk-filename (end=e) ? :
+bulkP.b
+structure-filename (end=e) ? :
+surf.txt
+output-filename :
+surf-bulkP.md
+surf-bulkP.s
+
+
+

実行後に、ファイル surf-bulkP.md 、 surf-bulkP.s +及び SURFYYYYMMDD-HHMMSSlog.txt が生成されます。 +(YYYYMMDD、 HHMMSS には実行日時に対応した数字が入ります)

+
+
+

計算結果の可視化

+

surf-bulkP.s は以下の通りです。

+
#azimuths,g-angles,beams
+1 56 13
+#ih,ik
+6 0 5 0 4 0 3 0 2 0 1 0 0 0 -1 0 -2 0 -3 0 -4 0 -5 0 -6 0
+0.5000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1595E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.6000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.1870E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.7000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2121E-01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.8000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.2171E-02, 0.1927E-01, 0.2171E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.9000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.4397E-02, 0.1700E-01, 0.4397E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+0.1000E+01, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.6326E-02, 0.1495E-01, 0.6326E-02, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00, 0.0000E+00,
+(以下略)
+
+
+

上記ファイルより、縦軸に角度（5行目以降の1列目データ）と(0,0)ピークの強度（5行目以降の8列目データ）から +ロッキングカーブを作成します。 +Gnuplot等のグラフソフトを用いる事も出来ますが、ここでは、 2DMAT/script フォルダにあるプログラム plot_bulkP.py を用います。 +以下のように実行して下さい。

+
python3 ../2DMAT/script/plot_bulkP.py
+
+
+

以下のような plot_bulkP.png が作成されます。

+
+../_images/plot_bulkP.png +
+

Si(001)-2x1面のロッキングカーブ。

+
+
+

この00ピークの回折強度のデータに対し、コンボリューションを掛けたうえで規格化します。 +surf-bulkP.s を準備して、 make_convolution.py を実行してください。

+
python3 ../2DMAT/script/make_convolution.py
+
+
+

実行すると、以下のようなファイル convolution.txt ができあがります。

+
0.500000 0.010818010
+0.600000 0.013986716
+0.700000 0.016119093
+0.800000 0.017039022
+0.900000 0.017084666
+（中略）
+5.600000 0.000728539
+5.700000 0.000530758
+5.800000 0.000412908
+5.900000 0.000341740
+6.000000 0.000277553
+
+
+

1列目が視射角、2列目が surf-bulkP.s に書かれた00ピーク回折強度のデータに +半値幅0.5のコンボリューションを付加して規格化したものです。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v2.2.0/ja/tutorial/solver_simple.html b/manual/v2.2.0/ja/tutorial/solver_simple.html new file mode 100644 index 00000000..46d7efbf --- /dev/null +++ b/manual/v2.2.0/ja/tutorial/solver_simple.html @@ -0,0 +1,139 @@ + + + + + + + + 順問題ソルバーの追加 — 2DMAT 2.2-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

順問題ソルバーの追加

+
+

ベンチマーク関数ソルバー

+

py2dmat では探索アルゴリズムのテストに利用できる順問題ソルバーとして、 analytical ソルバーを準備しています。

+

analytical ソルバーを使うには、入力ファイルの [solver] セクションの name を "analytical" に設定します。 +また、 function_name パラメータを用いてベンチマーク関数 \(f(x)\) を選択します。 +たとえば、 Himmelblau 関数を用いる場合には

+
[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+
+

とします。 +利用可能な関数の詳細は analytical ソルバーのリファレンス を参照してください。

+
+
+

順問題ソルバーの追加

+

ユーザ定義の順問題ソルバーを定義・解析する一番簡単な方法は、 analytical ソルバーに追加することです。 +ここでは例として、 Booth関数

+
+\[f(x,y) = (x+2y-7)^{2} + (2x+y-5)^{2}\]
+

を追加してみましょう（最小値は \(f(1,3) = 0\) ）。

+

そのためには、 py2dmat のソースコードをダウンロードし、ファイルを編集する必要があります。 +ダウンロード方法や、ソースコードからの実行方法などは、 インストールページ を参照してください。

+

analytical ソルバーは src/py2dmat/solver/analytical.py に定義されているので、これを編集します。

+

まず、 booth 関数を定義します。

+
def booth(xs: np.ndarray) -> float:
+    """Booth function
+
+    it has one global minimum f(xs) = 0 at xs = [1,3].
+    """
+
+    if xs.shape[0] != 2:
+        raise RuntimeError(
+            f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one"
+        )
+    return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2
+
+
+

つぎに、入力ファイルの solver.function_name パラメータで booth 関数を指定できるようにするために、 +Solver クラスのコンストラクタ (__init__) 中の if 分岐に以下のコードを挿入します。

+
elif function_name == "booth":
+        self.set_function(booth)
+
+
+

この改造した analytical ソルバーでは、 Booth 関数の最適化が行なえます。 +たとえばNelder-Mead 法による最適化は、以下の入力ファイル (input.toml) を

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "minsearch"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+initial_list = [0, 0]
+
+[solver]
+name = "analytical"
+function_name = "booth"
+
+
+

src/py2dmat_main.py に渡せば実行可能です:

+
$ python3 src/py2dmat_main.py input.toml
+
+... skipped ...
+
+Iterations: 38
+Function evaluations: 75
+Solution:
+x1 = 1.0000128043523089
+x2 = 2.9999832920260863
+
+
+
+
+ + +
+ + + + + \ No newline at end of file