Merge "TRHEPD_manybeam_with_limitation" into "develop".

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
 ************************
 

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,33 +180,34 @@ 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``
 
   Format: string (default: ``experiment.txt``)
 
   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
+  ...
+

doc/en/source/tutorial/bayes.rst

@@ -7,7 +7,7 @@ This tutorial subscribes how to estimate atomic positions from the experimental
 Sample files
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sample files are available from ``sample/sim-trhepd-rheed/bayes`` .
+Sample files are available from ``sample/sim-trhepd-rheed/single_beam/bayes`` .
 This directory includes the following files:
 
 - ``bulk.txt``
@@ -123,14 +123,14 @@ First, move to the folder where the sample file is located (hereinafter, it is a
 
 .. code-block::
 
-    cd sample/sim-trhepd-rheed/bayes
+    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 .
+    cp ../../../../../sim-trhepd-rheed/src/TRHEPD/bulk.exe .
+    cp ../../../../../sim-trhepd-rheed/src/TRHEPD/surf.exe .
 
 Execute ``bulk.exe`` to generate ``bulkP.b`` .
 
@@ -142,7 +142,7 @@ Then, run the main program (it takes a few secondes)
 
 .. code-block::
 
-   python3 ../../../src/py2dmat_main.py input.toml | tee log.txt
+   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:
@@ -216,7 +216,7 @@ I will omit the explanation below, but I will post the contents.
 
     ./bulk.exe
 
-    time python3 ../../../src/py2dmat_main.py input.toml
+    time python3 ../../../../src/py2dmat_main.py input.toml
 
     echo diff BayesData.txt ref_BayesData.txt
     res=0