Merge pull request #24 from Clifford-Yen/docs-config

docs: Add 3D velocity model section

docs/_sources/rst/input/material.rst.txt

@@ -39,7 +39,7 @@ Istanbul velocity model
 ``Istanbul_velocity_model``
     * Optional: Yes
     * Type: Yes or No
-    * Description: Whether to use the velocity model developed for the Istanbul or not. If this parameter is set to ``yes``, Hercules will replace the crustal structure information in the region that is covered by the Istanbul velocity model. For the rest of the region, the material information is still provided by the database or the profile that is assigned with the parameter ``cvmdb_input_file``. This is an optional parameter and the default value is ``no``.
+    * Description: Whether to use the velocity model developed for the Istanbul or not. If this parameter is set to ``yes``, Hercules will replace the crustal structure information in the region that is covered by the Istanbul velocity model. For the rest of the region, the material information is still provided by the database or the profile that is assigned with the parameter ``cvmdb_input_file``. This is an optional parameter and the default value is ``no``. 
 
 
 Basin velocity model
@@ -48,7 +48,7 @@ Basin velocity model
 ``basin_velocity_model``
     * Optional: Yes
     * Type: Yes or No
-    * Description: Whether to use the velocity model developed for a basin. If this parameter is set to ``yes``, Hercules will replace the crustal structure information within the basin. For the rest of the region, the material information is still provided by the database or the profile that is assigned with the parameter ``cvmdb_input_file``. This is an optional parameter and the default value is ``no``. Note that either ``Istanbul_velocity_model`` or ``basin_velocity_model`` can be set to ``yes``. If both are set to ``yes``, the Istanbul velocity model will be used.
+    * Description: Whether to use the velocity model developed for a basin. If this parameter is set to ``yes``, Hercules will replace the crustal structure information within the basin. For the rest of the region, the material information is still provided by the database or the profile that is assigned with the parameter ``cvmdb_input_file``. This is an optional parameter and the default value is ``no``. Note that only one of the ``Istanbul_velocity_model``, ``basin_velocity_model``, and ``3D_velocity_model`` can be set to ``yes``. If multiple options are set to ``yes``, the system prioritizes the models in the following order: Istanbul model, Basin model, and then the 3D velocity model. The latter models won't be used if the former models are used.
 
 
 ``basin_input_file``
@@ -98,7 +98,7 @@ Repeat the line with x points written in ascending order, then y points in ascen
     200.0 50.0 4.8
     250.0 50.0 5.0
 
-Note that the increment of x and y should be the same. The increment of z can be different. The unit of x, y, and z is meter.
+Note that the increments of x and y should be the same. The increment of z can be different. The unit of x, y, and z is meter.
 
 The total number of lines in the basin input file should be ``number_of_x_points * number_of_y_points + 1``. In the example above, the total number of lines is ``13``.
 
@@ -125,6 +125,138 @@ Unfortunately, we don't have a universal way to read a text file to define the e
 Note that you should re-compile Hercules after modifying ``basin.c``.
 
 
+3D velocity model
+=========================
+Contrast to the Istanbul velocity model, the 3D velocity model is a general velocity model that covers any interested regions. Users need to provide the velocity model in the designated format. The format of the 3D velocity model is described in the section :ref:`3D velocity model input files`.
+
+``3D_velocity_model``
+    * Optional: Yes
+    * Type: Yes or No
+    * Description: Whether to use the general 3D velocity model or not. If this parameter is set to ``yes``, Hercules will replace the crustal structure information in the region that is covered by the general 3D velocity model. For the rest of the region, the material information is still provided by the database or the profile that is assigned with the parameter ``cvmdb_input_file``. This is an optional parameter and the default value is ``no``. Note that only one of the ``Istanbul_velocity_model``, ``basin_velocity_model``, and ``3D_velocity_model`` can be set to ``yes``. If multiple options are set to ``yes``, the system prioritizes the models in the following order: Istanbul model, Basin model, and then the 3D velocity model. The latter models won't be used if the former models are used.
+
+``3D_velocity_model_origin_latitude_deg``
+    * Optional: Conditional
+    * Type: Float
+    * Description: The latitude of the origin of the 3D velocity model (in degree). Note that the origin is the left bottom corner of the domain of the 3D velocity model. This parameter is required when ``3D_velocity_model`` is set to ``yes``.
+
+``3D_velocity_model_origin_longitude_deg``
+    * Optional: Conditional
+    * Type: Float
+    * Description: The longitude of the origin of the 3D velocity model (in degree). Note that the origin is the left bottom corner of the domain of the 3D velocity model. This parameter is required when ``3D_velocity_model`` is set to ``yes``.
+
+
+3D velocity model input files
+-----------------------------
+To make it easier to understand the format of the 3D velocity model input files, here is an example before we convert it to the format that Hercules can read:
+
+.. code-block::
+    
+    0.0,0.0,0,1709.769,4188.062,1.85
+    0.0,0.0,1000,1894.495,4640.546,1.898
+    0.0,0.0,3000,2430.156,5952.642,2.02
+    0.0,0.0,17400,3400.0,8328.265,2.197
+    500.0,0.0,0,1743.876,4271.606,1.859
+    500.0,0.0,1000,1920.505,4704.257,1.905
+    500.0,0.0,5000,2625.958,6432.257,2.06
+    500.0,0.0,17400,3400.0,8328.265,2.197
+    0.0,500.0,0,1577.978,3865.241,1.814
+    0.0,500.0,1000,1840.914,4509.3,1.885
+    0.0,500.0,6000,2714.21,6648.43,2.077
+    500.0,500.0,0,1609.918,3943.478,1.823
+    500.0,500.0,1000,1861.275,4559.174,1.89
+    500.0,500.0,5000,2712.018,6643.06,2.076
+    500.0,500.0,17400,3400.0,8328.265,2.197
+
+The meanings of each column are:
+
+    * x (in meter, along the north-south direction with north being positive)
+    * y (in meter, along the east-west direction with east being positive)
+    * z (in meter, positive downward)
+    * Vs (in meter/second)
+    * Vp (in meter/second)
+    * density (in kg/meter :superscript:`3`)
+
+The order of the columns is not important since this file has to be converted into multiple files which will be explained later. Note that the increments of x and y can be different, but they have to be consistent (i.e. the increment of x has to be the same for all lines, so does the increment of y). The increment of z can also be different, and it can varies from point to point. The number layers can be different for different points, too.
+
+Some rules have to be followed when writing the 3D velocity model input file:
+
+    * The x coordinates should be written in ascending order
+    * The y coordinates should be written in ascending order
+    * Finish writing all points with the same y coordinate before moving to the next y coordinate.
+    * For each x-y coordinate, the z coordinates should be written in ascending order and should be unique.
+
+The file above should be converted into multiple files. The required files include: ``x.in``, ``y.in``, ``z.in``, ``vs.in``, ``vp.in``, ``rho.in``, and ``index.in``. 
+
+The file ``x.in`` contains the x coordinates of all points. The following is the content of ``x.in`` for the example above:
+
+.. code-block::
+
+    2
+    0.0
+    500.0
+
+The first line of the file is the number of points along the x direction (same as the number of following lines in the file). The following lines are the x coordinates of all points. Note that the x coordinates should be written in ascending order and should be unique. The same rule applies to ``y.in``. In this case, the content of ``y.in`` would be the same as ``x.in``. But if the increment of y or/and the number of points of y are different from x, the content of ``y.in`` will be different.
+
+For ``z.in``, ``vs.in``, ``vp.in``, and ``rho.in``, the content in each of these files is simply the corresponding column in the original file. For example, the content of ``z.in`` for the example above is:
+
+.. code-block::
+
+    15
+    0
+    1000
+    3000
+    17400
+    0
+    1000
+    5000
+    17400
+    0
+    1000
+    6000
+    0
+    1000
+    5000
+    17400
+
+Again, the first line is the total number of the data (same as the number of following lines in the file). The following lines are the z coordinates of all points. The same rule applies to ``vs.in``, ``vp.in``, and ``rho.in``. 
+
+The file ``index.in`` is a special file that includes the starting indices for all points. For example, the content of ``index.in`` for the example above is:
+
+.. code-block::
+
+    4
+    0
+    4
+    8
+    11
+
+The first line is the total number of the x-y coordinates (same as the number of the following lines. It's also the same as the multiplication of the number of x points and the number of y points). The following lines are the starting indices for all points. 
+
+For example, the first point (0.0, 0.0) has the starting index of 0 and the second point (500.0, 0.0) has the starting index of 4, which means the first (index 0) to the fourth (index 3) line in ``z.in``, ``vs.in``, ``vp.in``, and ``rho.in`` are the data for the first point. Similarly, the second point (500.0, 0.0) has the starting index of 4 and the third point (0.0, 500.0) has the starting index of 8, which means the fifth (index 4) to the eighth (index 7) line in ``z.in``, ``vs.in``, ``vp.in``, and ``rho.in`` are the data for the second point. So on and so forth.
+
+The conversion can be done easily with the help of Pandas, a Python library. For your convenience, here is a working Python script that can convert the original file to the required files:
+
+.. code-block:: python3
+
+    import pandas as pd
+
+    def convertToHerculesVelocityModel(fileName):
+        df = pd.read_csv(fileName)
+        for col in ['z', 'vs', 'vp', 'rho']:
+            df[col].to_csv(col+'.in', index=False, header=[len(df[col])])
+        df = df.drop_duplicates(subset=['x', 'y'])
+        df.index.name = len(df)
+        indexSeries = df.index.to_series()
+        indexSeries.to_csv('index.in', index=False, header=[len(indexSeries)])
+        for col in ['x', 'y']:
+            df[col].drop_duplicates().to_csv(col+'.in', index=False, header=[len(df[col].drop_duplicates())])
+
+    if __name__ == '__main__':
+        convertToHerculesVelocityModel('herculesVelocityModel.csv')
+
+All the converted files should be placed in ``./inputfiles/materialfiles`` in order to let Hercules find them. The original file is not necessary, but it is recommended to keep it to easily understand the meaning of each converted file.
+
+
 Misc
 ====
 ``softening_factor``

docs/rst/input/inputFile.html

@@ -99,6 +99,7 @@ <h2>Parameters<a class="headerlink" href="#parameters" title="Link to this headi
 <li class="toctree-l2"><a class="reference internal" href="material.html#one-dimensional-layered-profile">One-dimensional layered profile</a></li>
 <li class="toctree-l2"><a class="reference internal" href="material.html#istanbul-velocity-model">Istanbul velocity model</a></li>
 <li class="toctree-l2"><a class="reference internal" href="material.html#basin-velocity-model">Basin velocity model</a></li>
+<li class="toctree-l2"><a class="reference internal" href="material.html#d-velocity-model">3D velocity model</a></li>
 <li class="toctree-l2"><a class="reference internal" href="material.html#misc">Misc</a></li>
 </ul>
 </li>