Add detailed description of pressure dependency

docs/adusting_with_depth_and_pressure.md

@@ -0,0 +1,155 @@
+(adjustment_section)=
+# Adjusting with Depth and Pressure
+
+The dry_rock model can be adjusted according to depth and pressure:
+
+```yaml
+dry_rock:
+    model:
+        # model type is one of:
+        #  * "polyfit"
+        #  * "friable_sand"
+        #  * "patchy_cement"
+        type: "polyfit"
+    porosity:
+        # porosity of dry rock gotten from column in csv file
+        column: "porosity"
+    # Default polyfit coefficients is used which is:
+    # density: [[0.0, 0.0], [1.0, -1.0]]
+    # bulk_modulus: [[2900.0, -1300.0]]
+    # shear_modulus: [[1700.0, -800.0]]
+    # In  dry_rock, effective reference pressure is used:
+    # pressure = min(max_pressure, overburden_pressure - reference_pressure)
+    adjustments:
+       - type: "pressure_dependency"
+         # In pressure dependency effective rock pressure is used:
+         # pressure = min(max_pressure, overburden_pressure - rock_pressure)
+         # With the exception of the powerfit model which uses rock pore pressure:
+         # pressure = rock_pressure
+         model:
+              # model type is one of:
+              # * "polyfit"
+              # * "expfit"
+              # * "logfit"
+              # * "powerfit"
+              # * "patchy_cement"
+              # * "friable_sand"
+             type: "powerfit"
+             coefficients:
+                # adjusted_bulk_modulus = original_bulk_modulus +
+                #         20.0 * delta_pressure^-40.0
+                bulk_modulus: [20.0E+9, -46.0]
+                # adjusted_shear_modulus = original_shear_modulus +
+                #         12.0 * delta_pressure^-20.0
+                vp_over_vs: [12.0, -26.0]
+                # adjusted_density = original_density
+                density: [1.0, 0.0]
+       - type: "depth_trend"
+         depth:
+           column: "depth"
+         reference_depth: 0.0
+         max_depth: 4000.0
+         # delta_depth = min(depth - reference_depth, max_depth)
+         # coefficients in a 2d polynomial which
+         # adjusts dry rock properties to depth
+         coefficients:
+           # adjusted_bulk_modulus = c[i][j] * delta_depth^i * original_bulk_modulus^j
+           bulk_modulus: [[0.0, 1.5], [1.0, 0.0]]
+           # adjusted_shear_modulus = c[i][j] * delta_depth^i * original_shear_modulus^j
+           shear_modulus: [[0.0, 1.2], [1.0, 0.0]]
+           # adjusted_density = c[i][j] * delta_depth^i * original_density^j
+           density: [[0.0, 1.35], [1.0, 0.0]]
+```
+
+In the above example, the dry_rock material changes both with depth and pressure according to
+the "depth_trend" and "pressure_dependency" adjustment. Depth trend simply adjusts the material 
+according to a two dimensional polynomial (see the above example for details).
+
+## Pressure Dependency
+
+The models for pressure dependency is one of "polyfit", "expfit", "logfit",
+"powerfit", "patchy_cement", and "friable_sand". These are used to calculate
+three factors: `f_density`, `f_1` and `f_2`.
+
+First the dry rock properties are calculated. Then the pressure depenency at
+reference pressure and at effective pressure is calculated and the final
+adjust dry rock properties are as follows, except for "powerfit" which we will
+discuss last:
+
+```
+adjusted_density = density * (fd(effective_pressure) / fd(reference_pressure))
+adjusted_bulk_modulus = bulk_modulus * (f1(effective_pressure) / f1(reference_pressure))
+adjusted_shear_modulus = shear_modulus * (f2(effective_pressure) / f2(reference_pressure))
+```
+
+If velocity coefficients are given to the model then the above calculation is carried
+out with `primary_velocity` and `secondary_velocity` instead of `bulk_modulus` and `shear_modulus`. Except
+for the `friable_sand` and `patch_cement` models which always use moduli.
+
+The models "polyfit", "friable_sand", and "patch_cement" are the same models used
+in the [`dry_rock` section](dry_rock). The factors calculated from these models
+are the `density`, `bulk_modulus` and `shear_modulus` for the corresponding dry_rock model, ie.
+
+```
+f_d=density
+f_1=bulk_modulus
+f_2=shear_modulus
+```
+
+
+Given that you have the following coefficient section:
+
+```yaml
+ coefficients:
+    bulk_modulus: [cb1, cb2, cb3]
+    vp_over_vs: [cv1, cv2, cv3]
+    density: [cd1, cd2, cd3]
+```
+
+The "expfit" model is:
+
+```
+f_d = cd1 + cd2*e^(pressure/cd3)
+f_1 = cb1 + cb2*e^(pressure/cb3)
+f_2 = cv1 + cv2*e^(pressure/cv3)
+```
+
+The "logfit" model is:
+
+```
+f_d = cd1 + cd2*log_10(pressure)
+f_1 = cb1 + cb2*log_10(pressure)
+f_2 = cv1 + cv2*log_10(pressure)
+```
+
+Finally, `powerfit` calculates adjusted `dry_rock` in a quite different way from the other
+models. It uses `vp_over_vs` coefficients:
+
+```
+coefficients:
+  bulk_modulus: [cb1, cb2]
+  vp_over_vs: [cv1, cv2]
+  density: [cd1, cd2]
+```
+
+Which is used to calculate the following factors:
+
+```
+fd = cd1 + pressure ^ cd2
+f1 = cb1 + pressure ^ fb2
+f2 = cv1 + pressure ^ fv2
+```
+
+Then an adjusted vp_over_vs is calculated:
+
+```
+adjusted_vp_over_vs  = vp_over_vs + f2(effective) - f2(ref)
+```
+
+And the final adjusted values are calculated from that:
+
+```
+adjusted_density = density + fd
+adjusted_bulk_modulus = bulk_modulus + f1(eff) - f(reff)
+adjusted_shear_modulus = bulk_modulus / ((vp_over_vs + f2(effective) - f2(ref))^2 - 4/3)
+```

docs/config_file_format.rst

@@ -0,0 +1,6 @@
+
+.. toctree::
+    :maxdepth: 1
+
+    getting_started_with_the_config_file_format
+    adjusting_with_depth_and_pressure

docs/config_file_format.md → docs/getting_started_with_the_config_file_format.md

@@ -1,4 +1,4 @@
-## Config File Format
+# Getting Started With The Config File Format
 
 Input to `open_petro_elastic` consists of a yaml
 config file plus an optional csv data file.
@@ -7,7 +7,7 @@ The yaml config consists of three sections, minerals, fluids and dryrock. Elasti
 values for dry rock, having the mineral as its pore-material and saturated with the fluid
 is outputed.
 
-### Minerals
+## Minerals
 
 Consists only of a list of constituents which will be mixed using Hashin-Shtrikman,
 like so:
@@ -27,7 +27,7 @@ minerals:
           # fraction of shale is 1 - sum(other materials)
 ```
 
-### Fluids
+## Fluids
 
 Same as minerals, but a choice of mixing methods is given, and temperature and
 pressure can be given for costituents from theoretical models:
@@ -57,8 +57,8 @@ fluids:
 The list can be any number of arbitrary materials (see example in mineral section above) or
 given one of the types `["oil", "brine", "gas", "condensate"]`.
 
-
-### Dry Rock
+(dry_rock)=
+## Dry Rock
 
 This section describes the porous dry rock to the corresponding dense mineral.
 
@@ -72,15 +72,18 @@ dry_rock:
            shear_modulus: [[1700.0, -800.0]]
     porosity: 0.36
     adjustments:
-       - model: "powerfit"
-         overburden_pressure: 100.0E6
-         pressure: 70.0E+6 Pa
-         reference_pressure: 30.0E+6 # Pa
-         coefficients:
-            bulk_modulus: [20.0E+9, -46.0]
-            vp_over_vs: [12.0, -26.0]
-            density: [1.0, 0.0]
-       - depth: 1000.0
+       - type: "pressure_dependency"
+         model:
+           type: "powerfit"
+           overburden_pressure: 100.0E6
+           pressure: 70.0E+6 Pa
+           reference_pressure: 30.0E+6 # Pa
+           coefficients:
+              bulk_modulus: [20.0E+9, -46.0]
+              vp_over_vs: [12.0, -26.0]
+              density: [1.0, 0.0]
+       - type: "depth_trend"
+         depth: 1000.0
          reference_depth: 0.0
          coefficients:
            bulk_modulus: [[0.0, 1.5], [1.0, 0.0]]
@@ -104,12 +107,14 @@ dry_rock_shear_modulus = 1700 - 800.0 * porosity
 ```
 
 Adjustments (pressure dependency and depth trend) are applied in the order they
-are given in the adjustments list. In the example above, pressure dependency using
-the powerfit model is applied first, then depth trend which uses a polynomial fit.
-See `examples/example2.yaml` for a detailed description of adjustments.
+are given in the adjustments list. In the example above, pressure dependency
+using the powerfit model is applied first, then depth trend which uses a
+polynomial fit. See the [adjustments
+section](adjustment_section)
+for a detailed description of adjustments.
 
 
-### Inserting from datafile
+## Inserting from datafile
 Values from the csv file are inserted into the config file as columns of vectors,
 `open_petro_elastic` then maps its computation over the columns row-wise. The insertion
 into the yaml file of columns is done by giving the column name to the value you