From 14846c519e157ccc2ca50deda042723a1df8568d Mon Sep 17 00:00:00 2001 From: Yuichi Motoyama Date: Thu, 22 Feb 2024 16:51:06 +0900 Subject: [PATCH] update docs --- doc/en/source/input.rst | 50 ++++++ doc/en/source/solver/sim-trhepd-rheed.rst | 205 ++++++++++++++++------ doc/en/source/tutorial/index.rst | 1 + doc/en/source/tutorial/limitation.rst | 175 ++++++++++++++++++ doc/ja/source/input.rst | 2 +- doc/ja/source/solver/sim-trhepd-rheed.rst | 77 +++++--- doc/ja/source/tutorial/limitation.rst | 1 - src/py2dmat/solver/sim_trhepd_rheed.py | 2 +- 8 files changed, 437 insertions(+), 76 deletions(-) create mode 100644 doc/en/source/tutorial/limitation.rst diff --git a/doc/en/source/input.rst b/doc/en/source/input.rst index 3edb49c6..f28d61e9 100644 --- a/doc/en/source/input.rst +++ b/doc/en/source/input.rst @@ -24,6 +24,10 @@ The input file consists of the following six sections. - 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. @@ -157,6 +161,52 @@ mean \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 ************************ diff --git a/doc/en/source/solver/sim-trhepd-rheed.rst b/doc/en/source/solver/sim-trhepd-rheed.rst index 4e2cb2f7..da3fc4d6 100644 --- a/doc/en/source/solver/sim-trhepd-rheed.rst +++ b/doc/en/source/solver/sim-trhepd-rheed.rst @@ -19,10 +19,20 @@ The ``surf.exe`` is called from ``py2dmat``. Input parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Input parameters can be specified in subcsections ``config``, ``post``, ``param``, ``reference`` in ``solver`` section. +Input parameters can be specified in subsections ``config``, ``post``, ``param``, ``reference`` in ``solver`` section. -[``config``] 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`` @@ -60,30 +70,94 @@ Input parameters can be specified in subcsections ``config``, ``post``, ``param` Description: One of the parameters that specifies the range of output files to be read, calculated by the solver. This parameter specifies the last line to be read. -- ``row_number`` +- ``calculated_info_line`` - Format: integer (default: 8) + Format: integer (default: 2) - Description: One of the parameters that specifies the range of output files to be read, calculated by the solver. This parameter specifies the column to be read. + Description: One of the parameters that specifies the range of output files to be read, calculated by the solver. + This parameter specifies the line to be read, which contains the number of glancing angles (second column) and the number of beams (third column). + +- ``cal_number`` -[``post``] section -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Format: List of integers -- ``normalization`` + Description: Columns of dataset to be read. Multiple columns can be specified (many-beam condition). - Format: string ("TOTAL" or "MAX", default: "TOTAL") - Description: This parameter specifies whether the experimental and computational data vectors are normalized by the sum of the whole values or by the maximum value. +[``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. - The experimental and computational data vectors are denoted as :math:`u = (u_{1}, u_{2},...,u_{m})`, - :math:`v = (v_{1}, v_{2},...,v_{m})`, respectively. - When "A" type is chosen, R-factor is defined as :math:`R = (\sum_i^m (u_{i}-v_{i})^{2})^{1/2}`. - When "B" type is chosen, R-factor is defined as :math:`R = (\sum_i^m (u_{i}-v_{i})^{2})^{1/2}/( \sum_i^m u_{i}^2 + \sum_i^m v_{i}^2)`. + 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`` @@ -95,9 +169,9 @@ Input parameters can be specified in subcsections ``config``, ``post``, ``param` Format: boolean (default: false) - Description: Whether to remove working directories after reading R-factor or not + Description: Whether to remove working directories ``Log%%%_###`` after reading R-factor or not -[``param``] section +[``solver.param``] subsection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``string_list`` @@ -106,14 +180,9 @@ Input parameters can be specified in subcsections ``config``, ``post``, ``param` 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. -- ``degree_max`` - - Format: float (default: 6.0) - - Description: Maximum angle (in degrees) -[``reference``] section -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +[``solver.reference``] subsection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``path`` @@ -121,18 +190,24 @@ Input parameters can be specified in subcsections ``config``, ``post``, ``param` Description: Path to the experimental data file. -- ``first`` +- ``reference_first_line`` Format: integer (default: 1) Description: One of the parameters that specify the range of experimental data files to be read. This parameter specifies the first line of the experimental file to be read. -- ``last`` +- ``reference_last_line`` Format: integer (default: 56) Description: One of the parameters that specify the range of experimental data files to be read. This parameter specifies the last line of the experimental file to be read. +- ``exp_number`` + + Format: List of integers + + Description: Columns of dataset to be read. Multiple columns can be specified (many-beam condition). + Reference file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -169,21 +244,22 @@ In this case, ``value_01``, ``value_02``, and ``value_03`` are the parameters to Target file ^^^^^^^^^^^^^^ This file (``experiment.txt``) contains the data to be targeted. -The first column contains the angle, and the second column contains the calculated value of the reflection intensity multiplied by the weight. +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:: - 0.100000 0.002374995 - 0.200000 0.003614789 - 0.300000 0.005023215 - 0.400000 0.006504978 - 0.500000 0.007990674 - 0.600000 0.009441623 - 0.700000 0.010839445 - 0.800000 0.012174578 - 0.900000 0.013439485 - 1.000000 0.014625579 + 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 ... ... @@ -210,20 +286,49 @@ An example is shown below. output-filename : surf-bulkP.s -``RockingCurve.txt`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``RockingCurve_calculated.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This file is located in the ``Log%%%%%_#####`` folder. -The first line is the header, and the second and subsequent lines are the angle, convoluted calculated/experimental values, normalized calculated/experimental values, and raw calculated values in that order. -An example is shown below. +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:: - #degree convolution_I_calculated I_experiment convolution_I_calculated(normalized) I_experiment(normalized) I_calculated - 0.1 0.0023816127859192407 0.002374995 0.004354402952499057 0.005364578226620574 0.001722 - 0.2 0.003626530149456865 0.003614789 0.006630537795012198 0.008164993342397588 0.003397 - 0.3 0.00504226607469267 0.005023215 0.009218987407498791 0.011346310125551366 0.005026 - 0.4 0.006533558304296079 0.006504978 0.011945579793136154 0.01469327865677437 0.006607 - 0.5 0.00803056955158873 0.007990674 0.014682628499657693 0.018049130948243314 0.008139 - 0.6 0.009493271317558538 0.009441623 0.017356947736613827 0.021326497600946535 0.00962 - 0.7 0.010899633015118851 0.010839445 0.019928258053867838 0.024483862338931763 0.01105 - ... + # #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/doc/en/source/tutorial/index.rst b/doc/en/source/tutorial/index.rst index 6b33ffa1..b22f28c5 100644 --- a/doc/en/source/tutorial/index.rst +++ b/doc/en/source/tutorial/index.rst @@ -44,5 +44,6 @@ In this tutorial, we will first introduce how to run the sequential problem prog mpi bayes exchange + limitation pamc solver_simple diff --git a/doc/en/source/tutorial/limitation.rst b/doc/en/source/tutorial/limitation.rst new file mode 100644 index 00000000..baf41136 --- /dev/null +++ b/doc/en/source/tutorial/limitation.rst @@ -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/doc/ja/source/input.rst b/doc/ja/source/input.rst index ea2bf59d..d558044e 100644 --- a/doc/ja/source/input.rst +++ b/doc/ja/source/input.rst @@ -172,7 +172,7 @@ py2dmat は入力ファイルの形式に `TOML `_ を採 ``Algorithm`` で探索している :math:`N` 次元のパラメータ :math:`x` に、制約条件を課すことが出来ます。 ``Algorithm`` ごとに定義する探索範囲(例:``exchange`` の ``min_list`` や ``max_list`` ) に加えて課すことが出来ます。 -現在は :math:`M` 行 :math:`N` 列の行列Aと :math:`M` 次元の縦ベクトルbから定義される :math:`Ax+b>0` の制約式が利用可能です。具体的に +現在は :math:`M` 行 :math:`N` 列の行列:math:`A` と :math:`M` 次元の縦ベクトル:math:`b` から定義される :math:`Ax+b>0` の制約式が利用可能です。具体的に .. math:: diff --git a/doc/ja/source/solver/sim-trhepd-rheed.rst b/doc/ja/source/solver/sim-trhepd-rheed.rst index 6f936375..1c9b2a7b 100644 --- a/doc/ja/source/solver/sim-trhepd-rheed.rst +++ b/doc/ja/source/solver/sim-trhepd-rheed.rst @@ -79,18 +79,59 @@ - ``cal_number`` - 形式: 整数型のリスト (default: []、設定必須) + 形式: 整数型のリスト (設定必須) 説明: ソルバーにより計算された出力ファイルを読み込む範囲を指定するパラメータ。読み込むデータ列を指定。複数指定が可能。設定した値は、後述の ``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"のいずれかをとります。 (default: ""、設定必須) + 形式: string型。"TOTAL"または"MANY_BEAM"のいずれかをとります。 (設定必須) + + 説明: 実験・計算のデータベクトルの規格化の方法。 - 説明: 実験・計算のデータベクトルの規格化の方法。"TOTAL"の場合、全体の和で規格化をします。ただし計算に使用するデータ列が1つのみ適用できる規格化方法なので、 ``cal_number`` ([``config``] セクション)および ``exp_number`` ([``reference``] セクション)で設定したリストの長さが1である必要が有ります。"MANY_BEAM"はデータ列が2つ以上であるときに利用できる規格化方法です。後述の ``weight_type`` によって規格化方法が変わります。 + - "TOTAL" + + - 全体の和で規格化をします。 + - 計算に使用するデータ列が1つのみ適用できる規格化方法であり、 ``cal_number`` ([``config``] セクション)および ``exp_number`` ([``reference``] セクション)で設定したリストの長さが1である必要が有ります。 + + - "MANY_BEAM" + + - "MANY_BEAM"はデータ列が2つ以上であるときに利用できる規格化方法です。後述の ``weight_type`` によって規格化方法が変わります。 **なお、 normalization="MAX" は廃止となりました。** @@ -98,33 +139,22 @@ 形式: string型または ``None`` 。"calc"または"manual"のいずれかを設定する必要があります。 (default: ``None`` 、 ``normalization = "MANY_BEAM"`` としたとき設定必須) - 説明: 目的関数値を計算するときの、データ列ごとの重みの計算方法を指定します。 :math:`n` をデータ列のindex( :math:`n = 1,2,3..` ) 、 :math:`m` を視射角のindexとして、計算データを :math:`v^{(n)} = (v^{(n)}_{1}, v^{(n)}_{2}, .. ,v^{(n)}_{m})` と表すとします。 - "calc"とした場合、データ列ごとの重み :math:`w^{(n)}` は次の式で与えられます。 :math:`w^{(n)} = ( \sum_i^m v^{(n)}_{i} / \sum_j^n \sum_i^m v^{(j)}_i )^{2}.` + 説明: 目的関数値を計算するときの、ビームごとの重み :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"`` としたとき設定必須) - 説明: オプション ``weight_type`` を"manual"と設定した際に設定できます。 - それ以外の指定では、このオプションは計算に反映されません。目的関数値を計算するときの、データ列ごとの重みを設定します。また、このオプションで指定された重みは総和が1になります。 + 説明: 目的関数値を計算するときの、データ列ごとの重みを設定します。総和が1になるように自動的に規格化されます。 例えば、[3,2,1]を指定すると、 :math:`w^{(1)}=1/2, w^{(2)}=1/3, w^{(3)}=1/6` となります。 -- ``Rfactor_type`` - - 形式: string型。"A"、"A2"または"B"のいずれかをとります。 (default: "A") - - 説明: 目的関数値の計算方法の指定。 - 実験・計算のデータベクトルを、それぞれ :math:`u^{(n)} = (u^{(n)}_{1}, u^{(n)}_{2},...,u^{(n)}_{m})`, :math:`v^{(n)} = (v^{(n)}_{1}, v^{(n)}_{2},...,v^{(n)}_{m})` と書くとします。 - また、各データ列の重みを :math:`w^{(n)}` とします。:math:`n` はデータ列のindexです( :math:`n = 1,2,3..` )。 - "A"タイプを指定すると、目的関数値は :math:`R = [ \sum_{j}^{n} w^{(j)} \{ \sum_{i}^{m} (u^{(j)}_{i}-v^{(j)}_{i})^{2} \} ]^{1/2}` - で計算されるRファクター値となります。 - "A2"タイプを指定すると、目的関数値は :math:`R^{2} = \sum_{j}^{n} w^{(j)} \{ \sum_{i}^{m} (u^{(j)}_{i}-v^{(j)}_{i})^{2} \}` - で計算されるRファクターの二乗の値となります。 - "B"タイプを指定すると、目的関数値は :math:`R = (\sum_{i}^{m} (u^{(1)}_{i}-v^{(1)}_{i})^{2})^{1/2}/( \sum_{i}^{m} (u^{(1)}_{i})^{2} + \sum_{i}^{m} (v^{(1)}_{i})^2)` - で計算されるRファクター値となります。 - "B"タイプはデータ列が1つの実験・計算データを用いた実行( :math:`n=1` )のみ対応しています。 - - ``omega`` 形式: 実数型 (default: 0.5) @@ -261,7 +291,8 @@ ``generate_rocking_curve`` ([``solver``] セクション) が"true"の場合のみ ``Log%%%%%_#####`` フォルダに出力されます。 -ファイル冒頭には文頭に ``#`` が付いたヘッダーが記されます。ヘッダーには探索変数の値、目的関数値 ``f(x)`` オプションで指定した ``Rfactor_type`` ``normalization` ``weight_type`` ``cal_number`` 、オプションで指定またはプログラムが計算したデータ列ごとの重み ``spot_weight`` 、データ部分の列に何が記されているか( ``# 0 glanceing_angle`` など)が記されています。 +ファイル冒頭、 ``#`` で始まる行はヘッダーです。 +ヘッダーには探索変数の値、目的関数値 ``f(x)`` オプションで指定した ``Rfactor_type``, ``normalization`, ``weight_type``, ``cal_number``, オプションで指定またはプログラムが計算したデータ列ごとの重み ``spot_weight``, データ部分のどの列に何が記されているか(例: ``# #0 glanceing_angle`` など)が記されています。 ``#`` が付いていない部分はデータ表記部分になります。1列目は視写角、2列目以降はデータ列ごとに強度が記しています。どのデータ列が記されているかはヘッダーの表記で確認できます。例えば diff --git a/doc/ja/source/tutorial/limitation.rst b/doc/ja/source/tutorial/limitation.rst index dd53f3be..8ad1a8f4 100644 --- a/doc/ja/source/tutorial/limitation.rst +++ b/doc/ja/source/tutorial/limitation.rst @@ -69,7 +69,6 @@ ``[algorithm]`` セクションは用いる探索アルゴリズムを設定します。 交換モンテカルロ法を用いる場合には、 ``name`` に ``"exchange"`` を指定します。 -``label_list`` は、``value_0x`` (x=1,2) を出力する際につけるラベル名のリストです。 ``seed`` は擬似乱数生成器に与える種です。 ``[algorithm.param]`` サブセクションは、最適化したいパラメータの範囲などを指定します。 diff --git a/src/py2dmat/solver/sim_trhepd_rheed.py b/src/py2dmat/solver/sim_trhepd_rheed.py index e27838bc..c8430c03 100644 --- a/src/py2dmat/solver/sim_trhepd_rheed.py +++ b/src/py2dmat/solver/sim_trhepd_rheed.py @@ -428,7 +428,7 @@ def __init__(self, info, isLogmode, detail_timer): available_normalization = ["TOTAL", "MANY_BEAM"] if v == "MAX": raise exception.InputError( - 'ERROR: normalization == "MAX" is not available' + 'ERROR: normalization == "MAX" is no longer available' ) if v not in available_normalization: msg = "ERROR: normalization must be "