Merge pull request #1 from ubcgif/dev

Dev

content/elements.rst

@@ -8,11 +8,9 @@ The DCIP3D library consists of three core programs and nine utilities.
 Core Programs:
 
 - ``DCIPF3D``: Forward model conductivity/chargeability models to calculate data.
-- ``DCINV3D``: Invert 3D DC data to develop a conductivity models using a Gauss-
-Newton method
+- ``DCINV3D``: Invert 3D DC data to develop a conductivity models using a Gauss-Newton method
 - ``IPSEN3D``: calculates the sensitivity matrix for the 3D IP inversion
-- ``IPINV3D``: Invert 3D IP data to develop a chargeability models using a Gauss-
-Newton method
+- ``IPINV3D``: Invert 3D IP data to develop a chargeability models using a Gauss-Newton method
 
 Utilities:
 

content/examples.rst

@@ -27,12 +27,11 @@ DC resistivity and IP data are forward modelled for both surface and cross-boreh
 
 3. Combined surface and borehole dataset: A combination of the above pole-dipole surface and borehole arrays, resulting in 260 current electrodes and 2619 total forward modelled observations.
 
-Prior to inversion, 5% Gaussian noise was added to the forward modelled data, and uncertainties were assigned to be 5% of the data value plus a small floor. 
+Prior to inversion, 5% Gaussian noise was added to the forward modelled data, and uncertainties were assigned to be 5% of the data value plus a small floor.
 
 The following pages describe the constant inversion parameters used and then the inversion of each dataset.
 
 .. toctree::
-        :numbered:
         :maxdepth: 2
 
         Inversion parameters <exe5prism/param>

content/overview.rst

@@ -72,23 +72,19 @@ lower), or a file. Details of the structure of the input file and optional bound
 Historical changes from v1.0 to v2.1
 ------------------------------------
 
-Previously, major changes were made to improve upon version 1.0. The major changes were
+Previously, major changes were made to improve upon version 1.0. The major changes were:
+
 - Electrodes can be located anywhere and are not restricted to mesh node locations. This greatly enhances the usability of the code and allows for more uniform meshes with fewer cells to be used in the modeling.
 - A linearized forward modeling of IP data is available. The output is the sensitivity multiplied by the chargeability. In this case, "chargeability" data can be the true dimensionless chargeability, or any of the other chargeability units that are commonly used, eg. pfe, mV/V, mrad etc.
 - ``DCINV3D`` now saves the model after each iteration. This allows additional flexibility when selecting an inverted model that is best suited for interpretation purposes, or possibly choosing a starting model for a subsequent inversion.
 - ``IPINV3D`` saves intermediate models for each Lagrange multiplier.
-- The details of the model objective function can be controlled either with length scales or
-alpha parameters.-
-6. An initial check is now carried out to determine if some data have an incorrect sign. Data
-signs are not changed but suspect data are identified in a new file (see end of section 2.2).
-- In ``DCINV3D``, when the sensitivities are calculated, they are temporarily stored in memory
-rather than in the file dcinv3d.mtx. Hence the large .mtx file is not created. This results in
-a significant gain in performance.
+- The details of the model objective function can be controlled either with length scales or alpha parameters.
+- An initial check is now carried out to determine if some data have an incorrect sign. Data signs are not changed but suspect data are identified in a new file (see end of section 2.2).
+- In ``DCINV3D``, when the sensitivities are calculated, they are temporarily stored in memory rather than in the file dcinv3d.mtx. Hence the large .mtx file is not created. This results in a significant gain in performance.
 - ``DCINV3D`` and ``IPSEN3D`` output a file called sensitivity.txt that contains the average absolute value of the sensitivity matrix for each cell. This is useful to determine which portions of the model domain are sensitive to the survey.
 - Each cell in a model can be set as \active" or \inactive" in the inversion process. In ``DCINV3D``, inactive cells will be held at the value of the reference model. In the IP inversion, inactive cells will be set to zero.
 - An upgraded pre-conditioner is used for the CG (Conjugate Gradient) solver for the Gauss- Newton equations. This enhances the performance of the DC resistivity inversion and it has an even larger impact upon the IP inversion.
-- All floating-point arithmetic is now done in double precision. More accurate results are
-obtained.
+- All floating-point arithmetic is now done in double precision. More accurate results are obtained.
 - The code has been reorganized. Large working arrays are only allocated and used when needed. This results in reduced memory requirements.
 - When calculating the sensitivity matrix G (in programs ``DCINV3D``, ``IPINV3D``, ``DCIPF3D`` with the ip option), the number of times a forward system must be solved is equal to the number of transmitters plus the number of receivers. To speed up the process of calculating G, if the same electrode location appears more than once in the data file, it is solution is stored in memory for future use.
 

content/runPrograms.rst

@@ -3,35 +3,18 @@
 Running the programs
 ====================
 
-The DCIPoctree library consists of three core programs and nine utilities.
+The DCIP3D library consists of three core programs and nine utilities.
 
 Core Programs:
 
-- ``DCIPoctreeFwd``: Forward model conductivity/chargeability models to calculate data
-
-- ``DCoctreeInv``: Invert 3D DC data to develop a conductivity model
-
-- ``IPoctreeInv``: Invert 3D IP data to develop a chargeablility model
+- ``DCIPF3D``: Forward model conductivity/chargeability models to calculate data.
+- ``DCINV3D``: Invert 3D DC data to develop a conductivity models using a Gauss-Newton method
+- ``IPSEN3D``: calculates the sensitivity matrix for the 3D IP inversion
+- ``IPINV3D``: Invert 3D IP data to develop a chargeability models using a Gauss-Newton method
 
 Utilities:
 
-- ``create_octree_mesh``: Create an octree mesh file from electrode locations and optionally topography
-
-- ``3DModel2Octree``: Convert from a 3D UBC-GIF mesh/model to an octree mesh/model
-
-- ``octreeTo3D``: Convert from an octree mesh/model to a standard 3D UBC-GIF mesh/model
-
-- ``refine_octree``: Make an octree mesh finer based on the values of the input model
-
-- ``remesh_octree_model``: Convert a model from one octree mesh to another
-
-- ``surface_electrodes``: Place the electrodes on the topographic surface
-
-- ``octree_cell_centre``: Read in an octree mesh, and output a 3-columns file of cell centres
-
-- ``interface_weights``: Create a weight file for the octree cell interfaces
-
-- ``create_weight_file``: Create an octree cell weighting file
+- ``MAKE_WDAT``: makes a weighting file for smoothing near surface zones of the model
 
 This section discusses the use of these codes individually.
 
@@ -58,95 +41,21 @@ program
 argi
         is a command line argument, which can be a name of corresponding required or optional file. Typing **-inp** as the input file serves as a help function and returns an example input file. Some executables do not require input files and **program** should be followed by multiple arguments instead. This will be discussed in more detail later in this section for specific programs.
 
-Each input control file contains a formatted list of arguments, parameters, and filenames specific to the executable. All input control file formats are explain in detail within this section.
-
-For many large data sets, running one of the codes may require a prohibitively long time, so it is often useful to parallelize the job and send it to multiple processors (cores) on the same computer. The parallelization of the code depends on the version of the code, as described below:
-
-1. Version 1.0: The DCIPoctree program library's main programs have been parallelized with Message Pass Interface (MPI). The MPI installation package can be downloaded `here <http://www.mcs.anl.gov/research/projects/mpich2/>`__.  The following is an example of a command line executing an MPI process to run ``DCIPoctreeFwd`` on 4 processors of the local machine:
-
-.. code-block:: rst
-
-        "C:\Program Files\MPICH2\bin\mpiexec.exe" -localonly 4 -priority 1 DCIPoctreeFwd
-
-Here, the input arguments are:
-
-PATH
-        Properly defined path to mpiexec.exe
-
--localonly #
-        Tells the machine that the job is only going to be run on the local machine, and not on a local network or cluster. The number (#) that follows specifies the total number of processors (cores) to be used.
-
--priority #
-        Sets the priority of the process. The number (#) that follow is an integer from -1 (lowest) to 4 (highest). Higher priority means that RAM and processing resources will be primarily allocated for this process, at expense of lower priority processes. Generally, a large job should be assigned a lower priority, as selective resource allocation may slow down other important processes on the computer, including those needed for stable functioning of the operating system.
-
-program
-        The name of the executable. In this example, it is assumed that there is an existing path to the executable directory, otherwise the proper path should be provided.
-
-2. Version 1.0 (201402 and later): These codes use Pardiso and do not rely on MPI. The names will include "pardiso" (i.e., DCoctreeInv_pardiso). The following is an example of a command line executing the pardiso code:
-
-.. code-block:: rst
-
-        DCIPoctreeFwd_pardiso inputfile.inp
- 
-Execution on a local network or cluster
----------------------------------------
-
-MPI can also be used to run the DCIPoctree core programs on a local nestwork or cluster. The requirements for running an MPI job on a local network or cluster are as follows:
-
-- An identical version of MPI must be installed on all participating machines.
-
-- The user must create an identical network account with matching username and password on every machine.
-
-- Both the executable folder and the working directory need to be shared and visible on every participating computer.
-
-- Before the MPI job is executed, the firewall on all participating computers should be turned off.
-
-- The path should be defined to the executable directory.
-
-The following is an example for running on a local network or cluster:
-
-.. code-block:: rst
-
-        "C:\Program Files\MPICH2\bin\mpiexec.exe" -machinefile machine.txt -n 32 -priority 0 DCIPoctreeFwd
-
-Here, the input arguments are:
-
-PATH
-        Properly defined path to mpiexec.exe
-
--machinefile machinefile.txt
-        The list of participating machines will be read from a machine file. This file lists the network names of the participating machines and number of processors to be allocated for the MPI job for each machine. The following is an example of a machine file:
-
-.. figure:: ../images/machine.PNG
-        :figwidth: 50%
-        :align: center
-
--n #
-        The total number (#) of allocated processors. This number should be equal to the sum of all processors listed for all machines in the machine file.
-
--priority #
-        Sets the priority of the process. The number (#) that follow is an integer from -1 (lowest) to 4 (highest). Higher priority means that RAM and processing resources will be primarily allocated for this process, at expense of lower priority processes. Generally, a large job should be assigned a lower priority, as selective resource allocation may slow down other important processes on the computer, including those needed for stable functioning of the operating system.
-
-program
-        The name of the executable. In this example, it is assumed that there is an existing path to the executable directory, otherwise the proper path should be provided.
+Each control file contains a formatted list of arguments, parameters and file names in a com-
+bination and sequence specific for the executable, which requires this control file. Different control file formats will be explained further in the document for each executable. All files are in ASCII text format - they can be read with any text editor. Input and control files can have any name the user specifies.
 
+**NOTE**: Formats of the files listed in this control file are explained :ref:`here <fileformats>`.
 
 Programs
 --------
 
 .. toctree::
         :maxdepth: 1
 
-        DCIPoctreeFwd <runprog/fwd>
-        DCoctreeInv <runprog/dcinv>
-        IPoctreeInv <runprog/ipinv>
-        create_octree_mesh <runprog/createoctreemesh>
-        refine_octree <runprog/refineoctree>
-        remesh_octree_model <runprog/remeshoctreemodel>
-        octreeTo3D <runprog/octreeTo3D>
-        3Dmodel2octree <runprog/3dmodel2octree>
-        surface_electrodes <runprog/surfaceelectrodes>
-        create_weight_file <runprog/createweightsfile>
-        interface_weights <runprog/interfaceweights> 
+        DCIPF3D <runprog/fwd>
+        DCInv3D <runprog/dcinv>
+        IPSEN3D <runprog/ipsen>
+        IPInv3D <runprog/ipinv>
+        MAKE_WDAT <runprog/interfaceweights>