source: branches/UQ/NOTES @ 157

src/Simulation.cpp: a simple model function
 * invoke main
   - Simulation.exe simulation.in simulation.out
 * read simulation.in
   - one column, three rows: x1, x2, x3
 * write simulation.out
   - one value: x1*x2 + x3 + 2.0

src/simulation.template: file template for simulation.in
 * keys from a python dictionary of name and value (?)
   - one column, three rows: {X1}, {X2}, {X3}

========================================================================
test/dakota.in.template: dakota input file, without the "variables" section
 * edited by Concentration.exe
   - replaces value of 'evaluation_concurrency' with that from concentration.in
 * variables section
   - added by Concentration.exe (?)

test/driver.sh: core diameter calculation script
 * invoke main
   - driver params.in.<num> results.out.<num>
   - where num ==> function_eval_num
 * params.in
   - dict of variable name = variable value, created by Dakota
 * results.out
   - value of the objective function returned to Dakota
 * <make a working directory for the function eval, and save param.in (to ?)>
   - simulation.x & simulation_prime.x, where x = in, out, get stored here
 * generate simulation.in, and run F(X)
   - dprepro param.in.<num> simulation.template simulation.in
   - Simulation.exe simulation.in simulation.out
 * generate simulation_prime.in, and run F(X')
   - (simulation_prime.template generated by Concentration.exe)
   - dprepro param.in.<num> simulation_prime.template simulation_prime.in
   - Simulation.exe simulation_prime.in simulation_prime.out
 * Compute |F(X)-F(X')|^2
   - read "F" from simulation.out and "Fprime" from simulation_prime.out
   - "Fdiffsqrd" = -1.0 * (F-Fprime)^2 * CM_DK_SCALING
   - (CM_DK_SCALING generated (?) in ComputeDiameter.cc)
 * write results.out.<num>
   - echo "$Fdiffsqrd" > results.out.<num>

test/Makefile: launch "simulation" or concentration-of-measure calculation
 * Simulation.exe simulation.in simulation.out
   - (see Simulation.cpp)
 * Concentration.exe -s concentration.in concentration.variables \
   dakota.in.template concentration.diameters concentration.fxnevals \
   concentration.metadata concentration.rstrt 2> concentration.err
   - (see main.cc)
   - files except concentration.x; x=in,variables created by Concentration.exe

test/Dakota_Makefile: launch "serial" or parallel Dakota jobs
 * serial execution
   - dakota -input dakota.in -write_restart dakota.rst > dakota.out
 * parallel execution
   - mpirun -np 1 <serial execution call>

test/dprepro: dakota input file pre-processor
 * replace {Xn} with values in param.in, write input file
   - dprepro param.in simulation.template simulation.in

test/Application_Dakota_Makefile: red-headed step-child of Dakota_Makefile
 * ignore this file... simply a combination of Makefile & Dakota_Makefile
   - (see test/README for explaination)

test/concentration.in: primary input file for Concentration.exe
 * UI to configure mpirun, optimization type, and random variable selection
   - (see src/README for explaination)

test/concentration.variables: random variable declarations for dakota
 * UI to configure dakota parameter values (order, name, and bounds)
   - (see src/README for explaination)

========================================================================
src/MAKEDEPEND: includes for compiling *.cc files
 * header paths for x.o, where x=CM,RV,QN,GA,Dakota,Sample,ComputeDiameter,main
   - very hard-wired and very specific... and thus very fragile
   - is this input, or just a log?

src/Makefile: compile source
 * x.exe, where x=Concentration,Simulation,DifferenceSquared,Scaling,Probability

src/Probability.ccp: probability calculation
 * Compute exp(-2 * max(mean - threshold,0)^2 / diameter)
   - Probability.exe mean diameter threshold probability factor
   - "factor" used to scale "mean - threshold"; should be: 1 or -1
   - assert(diameter > 0.0)
   - input files: mean, diameter, threshold
   - output files: probability
   - mean, diameter, threshold, and probability contain a single value (?)

src/DifferenceSquared.ccp: difference squared calculation
 * Compute |F(X)-F(X')|^2
   - DifferenceSquared.exe simulation.in simulation_prime.in difference
   - input files: simulation.in simulation_prime.in
   - output files: difference
   - simulation*.in is one column & three rows, difference is a single value (?)

src/Scaling.cpp: scale the difference squared value (for the optimizer)
 * Multiply result from DifferenceSquared.cpp by scaling factor
   - Scaling.exe scaling scaling.in scaling.out
   - input files: scaling scaling.in
   - output files: scaling.out
   - scaling* is a single value (?)

========================================================================
src/main.cc: calculate concentration of measure
 * invoke main
   - Concentration.exe -s concentration.in concentration.variables \
     dakota.in.template concentration.diameters concentration.fxnevals \
     concentration.metadata concentration.rstrt 2> concentration.err
 * parse input files
   - read all args except concentration.x where x=rstrt,err
 * build Dakota "dak" object
   - init with: Concentration.exe, dakota.in.template, \
     concentration.diameter, concentration.fxnevals
 * initialize (NOTE: assume not restarting)
   - dak.concentrationInputReader(concentration.in)
   - restartRVnumber = -1
 * process dakota input data
   - dak.dakotaInputReader(concentration.variables,1)
 * save "concentration.metadata" (?) to $CM_DK_METADATA
   - ...don't know what this is for, or if it's necessary...
 * compute diameters
   - dak.runCM(1,concentration.metadata,concentration.rstrt,restartRVnumber)

src/CM.cc: concentration-of-measure object
 * instantiate
   - constructor(concentration.diameter,concentration.fxnevals)
 * read CM from input file
   - concentrationInputReader(concentration.in)
 * check CM data read for validity
   - assert(cmNumberRVstart <= cmNumberRVs)
   - assert((cmNumberRVend <= cmNumberRVs)&&(cmNumberRVend >= cmNumberRVstart))
   - assert(abs(dakotaScaling) >= 1.0e-15)
   - assert(machineComputeNodes >= 1)
   - assert(machineProcsPerNodes >= 1)
   - assert(dakotaEvaluationConcurrency >= 1)
   - assert(cmDiameterType <= 2) [actually: 0, 1, or 2]
   - assert(_temp_test_run == 'serial' or 'parallel')

src/Dakota.cc: dakota input parameters (random variables) object
 * instantiate
   - constructor(Concentration.exe,dakota.in.template, \
                 concentration.diameters,concentration.fxnevals)
 * read parameters from input file
   - dakotaInputReader(concentration.variables,1)
   - set dakotaInputFileType = 1
 * check parameters read for validity
   - assert(no random variable "duplicates" [bubble sort by descriptor_number])

========================================================================
src/ComputeDiameter.cc: create dakota input file from input information
 * launch a concentration-of-measure (sub)diameter calculation
   - runCM(1,concentration.metadata,concentration.rstrt,restartRVnumber)
   - set dakotaInputFileType = 1
   - build make_commands
     . test_run = "serial": "make -f Dakota_Makefile dak"
     . test_run = "parallel": "make -f Dakota_Makefile dakprocs PROCS=" + m*n
                  where m = machineComputeNodes, n=machineProcsPerNode
   - set $CM_DK_ENDRV = cnNumberRVs
   - set $CM_DK_SCALING = dakotaScaling
   - create dakota Input File from scratch (i.e. dakotaInputFileType=0)
     . ...skip this, as it seems that always dakotaInputFileType=1...
   - create dakota Input File from template
     . if "not a restart" (i.e. restartRVnumber<0): RVstart = cmNumberRVstart
     . else RVstart = restartRVnumber
     . loop (i) from RVstart to cmNumberRVend
       - set $CM_DK_CURRENTRV = i
       - compute the diameter
         . createDAKOTAInputFileFromSample(i)
         . createPerturbedSimulationTemplate(i,cmNumberRVs)
         . execute "make_command"
         . recoverDAKOTAData(i)
       - write restart file, and issue "make clean" command
 * createDAKOTAInputFileGA
   - ...skipping; not used when dakotaInputFileType=1...
 * createDAKOTAInputFileQN
   - ...skipping; not used when dakotaInputFileType=1...
 * createDAKOTAInputFileFromSample
   - copy dakota.in.template to dakota.in
     . build sed command to modify dakota.in.template
     . use sed to update evaluation_concurrency, and save to dakota.in.temp
     . mv dakota.in.temp to dakota.in
   - if # of cdv > 0, add cdv-specific bounds and descriptor info to dakota.in
     . add entries for each cdv-type variable
     . if ith variable is cdv, then also add it as the (n+1)th variable
     . (n+1)th variable is named 'Xk' where k=numRVs+1
   - similarly for the other variable types (i.e. ddv)
 * createPreturbedSimulationTemplate
   - copy simulation.template to simulation_prime.template
     . build sed command to change {Xi} to {X(cmNumberRVs+1)} 
     . use sed to update tag name, and save to simulation_prime.template
 * recoverDAKOTAData
   - read function evaluations and diameter from dakota.out
     . read # of function evaluations, then store: (rvNum,fxnevals)
     . read diameter, then -diameter/dakotaScaling, then store: (rvNum,diameter)
   - move dakota.out to dakota.out.${CM_DK_CURRENTRV}
   - write diameter and function evaluations to file
     . write computed (sub)diameters to concentration.diameters (?)
     . write total_diameter (sum of sub-diameters) to concentration.diameters
     . write # of function_evals to concentration.fxnevals (?)
     . write total_function_evaluations (i.e. sum) to concentration.fxnevals
 * writeMetaDataFile
   - log currentrv,computed_Diameter,computed_FxnEval to concentration.metadata

src/restart.cc: read/write restart data to restart file
 * write restart file
   - copy concentration.in info to concentration.rstrt
   - append (diameterNumber+1)... to restart after last completed loop
   - append rvname, computed diameters, and function_evaluations
 * read restart file info to "Dakota" object (i.e. 'dak')
   - read "concentration.in" info from concentration.rstrt
   - read diameterNumber
   - read rvname, computed diameters, and function_evaluations
   - return: diameterNumber


========================================================================
"Empty": src/GA.cc, src/QN.cc, src/RV.cc, src/Sample.cc