Add input file format for version 5.5

ubcgif · Mar 17, 2020 · fb7a946 · fb7a946
1 parent 70966b2
commit fb7a946
Show file tree

Hide file tree

Showing 15 changed files with 99 additions and 16 deletions.
diff --git a/_ext/__pycache__/edit_on_github.cpython-37.pyc b/_ext/__pycache__/edit_on_github.cpython-37.pyc
diff --git a/_ext/__pycache__/example.cpython-37.pyc b/_ext/__pycache__/example.cpython-37.pyc
diff --git a/_ext/__pycache__/purpose.cpython-37.pyc b/_ext/__pycache__/purpose.cpython-37.pyc
diff --git a/conf.py b/conf.py
@@ -67,9 +67,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '5.0'
+version = '5.5'
 # The full version, including alpha/beta/rc tags.
-release = 'July 2013'
+release = 'March 2020'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/content/exeprism/dcinv_example.rst b/content/exeprism/dcinv_example.rst
@@ -2,6 +2,7 @@
 
 DC Inversion
 ============
+
 The data created in section 5.2.1 are contaminated with 5% Gaussian noise. The uncertainties are estimated at 5% and a  oor of 0.0001 Volts. In this case, we know the true datamisfit that should be achieved is near the number of data, therefore we select ``mode=1`` to have ``DCINV3D`` perform a line search to choose the appropriate trade-off parameter. The parameter will be 1.0 to signify 48 that the datamisfit is n number of data. The minimum file requirements for ``DCINV3D`` is just the data file. In this case, we will choose not to use bounds. However, we will use the w.dat that was created when discretizing the topography. We will cap the inversion at 40 iterations. We will use the default reference model (best fitting half-space) and initial model (same as the reference model). The inversion starts from scratch so ``irest=0`` is given. The new incorporation of bounds is useful in real-life situations where there is down-hole mea- surements that often have additional conductivity measurements from well logs. Soft constraints, such as the reference model and weighting file would attempt to enforce the values the geophysicist has chosen from the well log information (which would need to be discretized onto the mesh). The user could also use hard constraints on the inversion by incorporating bounds or by using a reference model in combination of an active cells file where the cells located along the borehole are inactive (i.e., set to 0 in the active file).
 
 The inversion of the DC data is run by using the command
@@ -10,7 +11,15 @@ The inversion of the DC data is run by using the command
 
     dcinv3d dcinv.inp
 
-where the input file, ``dcinv.inp`` looks like the following:
+For version 5.5 and later, the input file ``dcinv.inp`` looks like the following:
+
+.. figure:: ../../images/dcinvinp_new.png
+        :name: dcinvinp_new
+        :figwidth: 75%
+        :align: center
+
+
+For versions before 5.5, the input file would look like (**version 5.0 was used to create this example**):
 
 .. figure:: ../../images/dcinvinp.png
         :name: dcinvinp

diff --git a/content/exeprism/ipinv_example.rst b/content/exeprism/ipinv_example.rst
@@ -2,6 +2,7 @@
 
 IP Inversion
 ============
+
 The data created in section 5.2 are contaminated with 5% Gaussian noise. The uncertainties are estimated at 5% and a floor of 0.0001. We first must create the sensitivity matrix by running ``IPSEN3D``. This is done via the command line:
 
 .. code-block:: rst
@@ -28,7 +29,15 @@ As with the DC, we know the true data misfit that should be achieved is near the
 
         ipinv3d ipinv.inp
 
-where the input file ipinv.inp is
+For version 5.5 and later, the input file ``ipinv.inp`` looks like the following:
+
+.. figure:: ../../images/ipinvinp_new.png
+        :name: ipinvinp_new
+        :figwidth: 75%
+        :align: center
+
+
+For versions before 5.5, the input file would look like (**version 5.0 was used to create this example**:
 
 .. figure:: ../../images/ipinvinp.png
         :name: ipinvinp

diff --git a/content/runprog/dcinv.rst b/content/runprog/dcinv.rst
@@ -1,5 +1,7 @@
 .. _dcinv:
 
+.. important:: In March of 2020, a new version of DCIP3D was released. The latest version has slightly different input files. We will provide documentation for the input files for current and past versions.
+
 DCInv3D
 ===========
 
@@ -11,15 +13,30 @@ DCInv3D
 
 where nThread is an optional integer argument to specify the number of OpenMP threads to use for the parallelization. If this value is missing, ``DCINV3D`` will use the maximum number of threads based on the processor. The input file, dcinv.inp is described below.
 
-Control parameters and input files
+Input file for version 5.5 and later
+------------------------------------
+
+As a command line argument, ``DCInv3D`` requires an input file containing all parameters and files needed to carry out the inversion. Below, we show the input file format for DCIP3D version 5.5 and later.
+
+.. figure:: ../../images/dcinv_new.PNG
+        :figwidth: 75%
+        :align: center
+
+
+Input file for versions before 5.5
 ----------------------------------
 
-As a command line argument, ``DCInv3D`` requires an input file containing all parameters and files needed to carry out the inversion. The following shows the required format:
+As a command line argument, ``DCInv3D`` requires an input file containing all parameters and files needed to carry out the inversion. Below, we show the input file format for DCIP3D versions **before** 5.5.
 
 .. figure:: ../../images/dcinv.PNG
         :figwidth: 75%
         :align: center
 
+
+
+Parameter Definitions
+---------------------
+
 maxit,irest
         Two integers containing the maximum number of Gauss-newton iterations to be performed (maxit) and how to start the inversion. There are two choices for irest:
         1. irest=0 Begins the inversion from scratch
@@ -83,12 +100,15 @@ itol,eps
 weight
         Name of the file containing weighting matrix. If null is entered, the default value of one is used for no extra weighting.
 idisk
-        Integer flag of zero or one to write the sensitivities to disk
+        Integer flag of zero or one to write the sensitivities to disk. This functionality was rendered obsolete in version 5.5
 
                 1. idisk=0: Store the entire sensitivity matrix in memory. This option will be desired in almost all cases.
 
                 2. idisk=1: Access the sensitivity matrix from memory when needed
 
+constr
+        This functionality was introduced in version 5.5. SMOOTH_MOD runs the inversion without implementing a reference model (essential mref=0). “SMOOTH_MOD_DIF” constrains the inversion in the smallness and smoothness terms using a reference model.
+
 tol
         This value indicates how well the forward modelled system is solved (1e-5 is a standard input)
 
@@ -136,8 +156,8 @@ check sign.txt
         This file will prompt the user to check the sign of specific observed potentials after brief data checks. It may or may not be created.
 
 
-Example files
--------------
+Example file for dcinv3d v 5.5
+------------------------------
 
 Below is an example of the input file ``dcinv.inp``. It will start from scratch and stop after 40 iterations if the desired misfit is not achieved. The desired misfit is the number of data and the program will compute the trade-off parameter. The reference and initial models are the best fitting half space. There are bounds throughout the model with the lowest bound of 1e-8 S/m and the upper bound of 0.1 S/m.
 

diff --git a/content/runprog/ipinv.rst b/content/runprog/ipinv.rst
@@ -1,5 +1,8 @@
 .. _ipinv:
 
+
+.. important:: In March of 2020, a new version of DCIP3D was released. The latest version has slightly different input files. We will provide documentation for the input files for current and past versions.
+
 IPInv3D
 ===========
 
@@ -11,30 +14,59 @@ This program performs the inversion of induced polarization data. Command line u
 
 For the control file ``ipinv.inp`` described below.
 
-Control parameters and input files
+Input file for version 5.5 and later
+------------------------------------
+
+The input file for *ipinv3d* versions 5.5 and later is as follows:
+
+.. figure:: ../../images/ipinv_new.PNG
+        :figwidth: 75%
+        :align: center
+
+
+
+
+Input file for versions before 5.5
 ----------------------------------
 
-The bounds for version 5.0 have NOT been added for IP data inversion. Positivity is enforced through the log-barrier method. The format for the main IP inversion input file is:
+The bounds for versions before 5.5 have NOT been added for IP data inversion. Positivity is enforced through the log-barrier method. The format for the main IP inversion input file in this case is:
 
 .. figure:: ../../images/ipinv.PNG
         :figwidth: 75%
         :align: center
 
+
+Parameter Definitions
+---------------------
+
+
 irest
-        An integer specifying how to start the inversion. There are two choices:
+        An integer specifying how to start the inversion. This functionality is no long relevant in version 5.5. There are two choices:
 
         1. irest=0 Begins the inversion from scratch
 
         2. irest=1 Restarts the inversion from a previous iteration. The files ``ipinv3d.aux`` and ``ipinv3d.eta`` must be present for this option.
 
-mode,par
+mode
         An integer specifying one of the two choices for determining the trade-off parameter (a real value):
 
-                1. mode=1: the program chooses the trade off parameter by carrying out a line search so that the target value of data misfit is achieved (e.g.,  :math:`\phi_d= N`). the target misfit value is given by the product of par and the number of data, N. Normally, the value of par should be 1.0 if the correct standard deviation of error is assigned to each datum.
+                1. mode=1: the program chooses the trade off parameter by carrying out a line search so that the target value of data misfit is achieved (e.g.,  :math:`\phi_d= N`). The target misfit is determined by the *par* parameter.
 
-                2. mode=2: the user inputs the trade off parameter as defined by par.
+                2. mode=2: the user inputs the trade off parameter as defined by *par*.
 
-                3. mode=3: the program calculates the trade-off parameter using generalized cross validation (GCV) and par is ignored
+                3. mode=3: the program calculates the trade-off parameter using generalized cross validation (GCV) and *par* is ignored
+
+
+par
+        Specifies the stopping criteria for the inversion:
+
+                1. If *mode* is set to equal 1, then the target misfit value is given by the product of *par* and the number of data, N. Normally, the value of *par* should be 1.0 if the correct standard deviation of error is assigned to each datum.
+
+                2. If *mode* is set to equal 2, the *par* defines the trade off parameter.
+
+
+tolc
+        If *mode* is set to equal 1, then *par* is used to set the target misfit. The *tolc* parameter gives us some 'wiggle room' for the target misfit. If we let *par* = 1 and *tolc* = 0.2, then we are saying the target misfit is somewhere within the number of data time 1 +/- 0.2.
 
 data
         The DC observation locations (with standard deviations).
@@ -112,6 +144,17 @@ ipinv3d.chg
 Example files
 -------------
 
+**Version 5.5 and later**
+
+This example of an IP inversion input file starts the inversion from scratch and performs a line search find the trade-off parameter. The sensitivity matrix file was renamed to ``diffTol.mtx`` so the use new that they had used a different tolerance (and so they could switch to the other matrix file without re-running ``IPSEN3D``). The initial model is set to null and depends upon the IP data type. The ref rence model was zero. Length scales were given to drive the recovered chargeabilities to more layered geometry. Additional weighting was applied through the file ``w.dat``, supplied by the user. Bounds were used to recover chargeabilities between 0 and 1.
+
+.. figure:: ../../images/ipinvexample_new.PNG
+        :figwidth: 75%
+        :align: center
+
+
+**Before version 5.5**
+
 This example of an IP inversion input file starts the inversion from scratch and performs GCV to find the trade-off parameter. The sensitivity matrix file was renamed to ``diffTol.mtx`` so the use new that they had used a different tolerance (and so they could switch to the other matrix file without re-running ``IPSEN3D``). The initial model is set to null and depends upon the IP data type. The ref rence model was zero. Length scales were given to drive the recovered chargeabilities to more layered geometry. Additional weighting was applied through the file ``w.dat``, supplied by the user.
 
 .. figure:: ../../images/ipinvexample.PNG

diff --git a/images/dcinv_new.PNG b/images/dcinv_new.PNG
diff --git a/images/dcinvexample.PNG b/images/dcinvexample.PNG
diff --git a/images/dcinvinp_new.png b/images/dcinvinp_new.png
diff --git a/images/ipinv_new.PNG b/images/ipinv_new.PNG
diff --git a/images/ipinvexample_new.PNG b/images/ipinvexample_new.PNG
diff --git a/images/ipinvinp_new.png b/images/ipinvinp_new.png
diff --git a/index.rst b/index.rst
@@ -1,3 +1,5 @@
+.. important:: In March of 2020, a new version of DCIP3D was released. The latest version has slightly different input files. We will provide documentation for the input files for current and past versions.
+
 DCIP3D package
 ==============