Index: /issm/trunk/src/c/objects/DakotaPlugin.cpp
===================================================================
--- /issm/trunk/src/c/objects/DakotaPlugin.cpp	(revision 804)
+++ /issm/trunk/src/c/objects/DakotaPlugin.cpp	(revision 805)
@@ -1,3 +1,16 @@
 /*!\file:  DakotaPlugin.cpp (see DakotaPlugin.h for explanations)
+ * \brief  header file for derived DirectApplicInterface class. 
+ * \sa SpwanCore.cpp and \sa qmu.cpp
+ *
+ * This class needs to be understood simultaneously with qmu.cpp and SpwanCore.cpp. 
+ * This call is derived from the Dakota DirectApplicInterface class. This is the 
+ * only way to plug ISSM's own routines into the Dakota engine. The derived class 
+ * has one function called derived_map_ac, which is called by Dakota to drive the 
+ * entire snesitivity analysis. 
+ *
+ * We use this routine (which gets variables, variable_descriptors from the Dakota 
+ * engine, and requests responses from the ISSM solution sequences), to call our 
+ * own solutoin cores. This routines calls the SpawnCore routine, which will drive 
+ * the entire computations. 
  */ 
 
Index: /issm/trunk/src/c/objects/DakotaPlugin.h
===================================================================
--- /issm/trunk/src/c/objects/DakotaPlugin.h	(revision 804)
+++ /issm/trunk/src/c/objects/DakotaPlugin.h	(revision 805)
@@ -1,7 +1,3 @@
 /*!\file:  DakotaPlugin.h:
- * \brief  header file for derived DirectApplicInterface class. This class 
- * is used to plug our own functions into the Dakota interface.
- * This class is copied from the PluginSerialDirectApplicInterface.[C,H]
- * file in Dakota/src/
  */ 
 
Index: /issm/trunk/src/c/parallel/SpawnCore.cpp
===================================================================
--- /issm/trunk/src/c/parallel/SpawnCore.cpp	(revision 804)
+++ /issm/trunk/src/c/parallel/SpawnCore.cpp	(revision 805)
@@ -1,4 +1,20 @@
 /*!\file:  SpawnCore.cpp
- * \brief: run core solution, according to analysis_type and sub_analysis_type
+ * \brief: run core ISSM solution using Dakota inputs coming from CPU 0.
+ * \sa qmu.cpp DakotaPlugin.cpp
+ *
+ * This routine needs to be understood simultaneously with qmu.cpp and DakotaPlugin. 
+ * SpawnCore is called by all CPUS, with CPU 0 holding Dakota variable values, along 
+ * with variable descriptors. 
+ *
+ * SpawnCore takes care of broadcasting the variables and their descriptors across the MPI 
+ * ring. Once this is done, we use the variables to modify the inputs for the solution core. 
+ * For ex, if "rho_ice" is provided, for ex 920, we include "rho_ice" in the inputs, then 
+ * call the core with the modified inputs. This is the way we get Dakota to explore the parameter 
+ * spce of the core. 
+ *
+ * Once the core is called, we process the results of the core, and using the processed results, 
+ * we compute response functions. The responses are computed on all CPUS, but they are targeted 
+ * for CPU 0, which will get these values back to the Dakota engine. 
+ *
  */ 
 
Index: /issm/trunk/src/c/parallel/qmu.cpp
===================================================================
--- /issm/trunk/src/c/parallel/qmu.cpp	(revision 804)
+++ /issm/trunk/src/c/parallel/qmu.cpp	(revision 805)
@@ -1,4 +1,28 @@
 /*!\file:  qmu.cpp
- * \brief: run qmu capabilities using Dakota library
+ * \brief: wrapper to the Dakota capabilities. qmu fires up Dakota, and registers a Dakota Pluggin
+ * which will be in charge of running the solution sequences repeteadly, to garner statistics. 
+ *
+ * This routine deals with running ISSM and Dakota in library mode. In library mode, Dakota does not 
+ * run as an execuatble. Its capabilities are linked into the ISSM software. ISSM calls dakota routines 
+ * directly from the dakota library. qmu.cpp is the code that is in charge of calling those routines. 
+ *
+ * Dakota has its own way of running in parallel (for embarassingly parallel jobs). We do not want that, 
+ * as ISSM knows exactly how to run "really parallel" jobs that use all CPUS. To bypass Dakota's parallelism, 
+ * we overloaded the constructor for the parallel library (see the Dakota patch in the externalpackages/dakota
+ * directory). This overloaded constructor fires up Dakota serially on CPU 0 only! We take care of broadcasting 
+ * to the other CPUS, hence ISSM is running in parallel, and Dakota serially on CPU0. 
+ *
+ * Now, how does CPU 0 drive all other CPUS to carry out sensitivity analysese? By synchronizing its call to 
+ * our ISSM cores (diagnostic_core, thermal_core, transient_core, etc ...) on CPU 0 with all other CPUS. 
+ * This explains the structure of qmu.cpp, where cpu 0 runs Dakota, the Dakota pluggin fires up SpawnCore.cpp, 
+ * while the other CPUS are waiting for a broadcast from CPU0, once they get it, they also fire up 
+ * SpawnCore. In the end, SpawnCore is fired up on all CPUS, with CPU0 having Dakota inputs, that it will 
+ * broacast to other CPUS. 
+ *
+ * Now, how does dakota call the SpawnCore routine? The SpawnCore is embedded into the DakotaPlugin object 
+ * which is derived from the Direct Interface Dakota objct. This is the only way to run Dakota in library 
+ * mode (see their developper guide for more info). Dakota registers the DakotaPlugin object into its own 
+ * database, and calls on the embedded SpawnCore from CPU0. 
+ *
  */