README
    
    		Community Problems 12/16/02
                APPLICATION I: WELL-FIELD DESIGN
            **************************************

This directory contains the necessary data files to run
the community problem for a well--field design application with 
MODFLOW96 as the simulator and the MPI version of IFFCO as the optimizer. 
The MODFLOW 96 version 3.3 unix source code must be obtained from
http://water.usgs.gov/software/modflow-96.html
and compiled (instructions below). The IFFCO source code is included in this
directory; however documentation can be obtained at 
http://www4.ncsu.edu/eos/users/c/ctkelley/www/iffco.html

This problem is for a well field with 6 wells in a homogeneous, unconfined
aquifer discretized on a 50 x 50 x 10 grid. The 18 decision variables are
the (x,y) locations of the 6 wells and the pumping rates at the wells. 


		    TABLE OF CONTENTS
                    
                A. List of files/subdirectories
                B. Compiling MODFLOW
                C. Compiling optmain
                D. Postprocessing



A. List of files
The following files are included in this directory:

I.) MODFLOW input data files:
	A2.bas
        A2.bcf
        A2.lyr
        A2.oc
        A2.pcg
        A2.rch


II.) IFFCO files
	iffco.f
        vtf.f
        sample_opt_1.out
        sample_opt_2.out
 
Subdirectory MODFLOW is included to put the MODFLOW source code and
also includes appropriate makefile for MODFLOW with the mpxlf compiler
on the IBMS SP2.


II.) Optimization files
     Makefile     makefile for the optimization routines for the IBMSP 2 (mpxlf)
     optmain.f   the main optimization routine that sets the iffco 
                 parameters and calls iffco
     feval.f     computes the objective function
     writewel.f  creates a A2.wel## MODFLOW input file for each processor
     writemfn.f  creates a A2.mfn## input file for MODFLOW for each processor
     readhead.f  reads in head values from MODFLOW output file A1.hed
     costao.f    computes the operational cost
     costac.f    computes the capital cost
     postproc.f  creates the matlab file out.m. Executing out.m
                 plots the head contours in the layer containing the
                 wells with the optimal pumping rates set.
     location_constraint.f check to see if two wells occupy the same place
     head_constraint.f check to see if bounds on head, or head difference
                       constraint is violated
     linear_constraint.f check to see if constraint on net rate is violated
     heads_1.eps   example plot of head contours (initial iterate 1)
     heads_2.eps   example plot of head contours (initial iterate 2)
B. Compiling MODFLOW

The objective function feval.f requires a call to the modflow executable.
Download the MODFLOW source code for unix from 
http://water.usgs.gov/software/modflow-96.html

* The file will be called modflw96.3_3.source.tar.gz
* Move this file into the subdirectory /UNC_HOMparallel_6wells/MODFLOW
* Unzip the file with:
  gunzip modflw96.3_3.source.tar.gz

* Unpack the directory with: 
  tar -xvf modflw96.3_3.source.tar

*** If you are on the SP2 
  --copy the file MakefileXLF to /modflw96.3_3/src
  --change into /modflw96.3_3/src
  --cp MakefileXLF Makefile
  --type make to compile

* The executable is called modflw96 and is put in /modflw96.3_3/bin. 
* Change into /modflw96.3_3/bin with:
  cd ../bin
* move the executable up into the directory with the data files /UNC_HOMparallel_6wells
 with
  mv modflw96 ../../.. 

**Change back into the working directory /UNC_HOMparallel_6wells with
  cd ../../..


C. Compiling optmain

* To compile the optimization routines, including the IFFCO source code and the 
necessary subroutines for the objective function type `make' in the /UNC_HOMparallel_6wells
directory.

* This will create the .o files and the executable is called optmain.

* To run the optimization interactively, type
poe optmain -procs 2 -hfile hf 
Here 2 indicates the number of processors running the job  

* To run the optmization in the batch (using loadleveler), type
llsubmit opt.cmd

opt.cmd is the command file and is set to run the problem on
6 processors. This file can be modified. 


  Below is an example of the output
  printed for each processor:
 ********************************
 Function value = 0.27591E+09
 FLAG= 0
 ********************************
 *********************************
 Function value =  0.27422E+09
 FLAG= 0
 *********************************

There will also be an inoccuous message that can be ignored that says:
Enter the name of the NAME FILE:

 Here, 'Function value' is the current objective function value and
 FLAG = 0 if the constraints are satisfied and FLAG = 1 if the 
 constraints are violated. If FLAG = 1, an additional statement will
 print to the screen indicating which constraint was not satisfied.

D. Postprocessing

* Upon completion the files iffco.out, points.out, and out.m are made. 
  In addition, there will be a .mfn##, a .wel##, and a .hed## file for each 
  processor. You may delete these files--they are MODFLOW data files that are 
  no longer needed.

--iffco.out contains the optimization history:
  At the end of this file is the list of function values, starting with the highest value 
  and ending with the minimum found by iffco. Just above the list of function values is a 
  vector containing the optimal pumping rates found by IFFCO and the total number of function 
  evaluations taken over the coarse the optimization. 
  
--points.out is a file containing all the function values and points evaluated by iffco 
  during the optimization.
  
--For more details about the IFFCO output see the user manual at
  http://www4.ncsu.edu/eos/users/c/ctkelley/www/iffco.html

--You can compare your results in iffco.out to the data file provided called sample_opt_1.out. 

--out.m is a matlab file that will plot the head contours in the layer with the wells 
  operating at the optimal pumping rates. 
  *Start Matlab and type `out' at the prompt to plot the contours.
  *you can compare the plot to our output by viewing heads_1.eps.
  
Notes: 
1.) out.m is created by a call in optmain.f to postproc.f. 
If you are not interested in generating this file, simply 
comment out the call to postproc in optmain.f.

2.) In optmain.f, commenting out the call to iffco and uncommenting the
call to feval will evaluate the objective function once at the initial iterate 
optmain.f then calls postproc to creat the corresponding Matlab data so you can
visualize the initial locations of the wells.

3.) For this application we include two different initial iterates. Both use
the same well locations but different initial pumping rates. Initial iterate
1 leads to 1 well shutting off in the coarse of the optimization and an answer
comparable to the original 5 well application. The results for initial iterate
1 are in sample_opt_1.out and heads_1.eps. Initial iterate 2 leads to a local 
minimum. 
To run the problem with the second initial iterate adjust the initial iterate
in optmain.f. You can compare your answer to sample_opt_2.out and heads_2.eps

4.) Description of the initial iterate and bound constraints can be found in 
optmain.f