Help for PHOTFIT2

PURPOSE:	Photfit2 is a VICAR program which determines the coefficients 
		of various photometric functions.  

	
FUNCTION:

  PHOTFIT2 reads IBIS1 and IBIS2 files which have been generated by the VICAR 
programs PHOTOM, HWPHOCAE/D, PHOTTEST2. PHOTOM or HWPHOCAE/D are used to collect photometric data from images (and their navigation). The IBIS files contain all 
the data required for PHOTFIT2. There is one input IBIS file for each picture. 
The output of PHOTFIT2 is listed coefficient values on screen [or an IBIS2 
photometric parameterfile (subtyp=phopar) - not yet implemented].



EXECUTION:

  Be very conservative about the amount of data to include in the
IBIS files. PHOTFIT3 is a slow program. It is the quality of the
IBIS data points, not their quantity, which matters. You should
assure as broad a coverage of incidence, emission, and phase
angles as possible. If you have 10 points/ibis file
and 6 files (one for each phase angle) that should be sufficient.  
You might consider restricting points (from PHOTOM, HWPHOCA*) to areas of
consistent albedo based upon your theories of morphology.
  The Hapke and Veverka functions are EXTREMELY sensitive to
data which, because of a lack of broad ranges of incidence, emission,
and phase angles, or because of inclusion of various albedo's,
does not truly represent the function being fit. When this 
problem occurs the coefficients will become distorted in order
to accomodate erroneous data. Sometimes you can tell when the coefficients
returned lie up against the limits of their permitted ranges.
  Accuracy: Rerun PHOTFIT2 at least twice to assure that the function
has had sufficient time to find a stable minimum. If you cool the
solution too fast it will 'freeze' on the wall of the error minimum.
Comparing several answers will give a feeling of the precision of the 
result. 'Freezing' can be avoided by providing either a higher initial
'temperature' or more iterations.
  The percent and tolerance keywords permit a solution that is found to
consist of a subset of all of the data points. If there are more than
percent of the points with I/F residuals below tolerance then the
remainder of the points can be ignored if they exceed tolerance.
If there are fewer than percent points with residuals below
tolerance then all of the points will be considered.


USAGE:

  There are sets of four keywords which relate to each function:
These are the parmeters, T_*, MAX_*, MIN_*. These provide the:
1.  Initial position guess for the photometric parameters. This is not 
    important per-se but it assures you that Metropolis will investigate 
    this point (and remember what it found). 
2.  Range over which random guesses can be expected to vary at first:
    PARAM_NEW = T_* * tan( PI * ran_num + PI/2 ).
    This is the 'temperature' for each variable. As the system cools the range 
    will constrict gradually (T_NEW_* = T_OLD_* * scale, scale depends of 
    NUMTEN) until the temperatur is only 10**-MAXITER/NUMTEN times the inital 
    temperatur of the parameter.
3/4.Two limits MIN_*, MAX_* outside of which each of the photometric 
    parameters are stricly prohibited to fall. Each time these limits 
    are violated the attempted solution is abandoned and a new one is 
    attempted.  This will happen thousands of times, especially at first 
    when the temperatures are high.  
  
Each of these has defaults but you must not consider these as gospel.

The maxiter parameter proposals are a bit arbitrary. They will depend
upon experience. You will probably be able to reduce them greatly.



METHOD:

  PHOTFIT2 uses the simulated annealing method  to solve for the function 
coefficients. This is verry inefficient solution method which is good for 
fitting complicated functions. The solution is arrived at through guessing. 
Initially guessing is performed over a large region using a random number
generator. As time progresses the "temperature" is reduced, 
constricting the range of guesses to an ever decreasing region
in the N solution space. Decisions are made at every step based upon
the Boltzmann probability of transitioning from one energy level
(error due to incorrect solution estimate) to the next. This is
essentially a chaotic downhill search scheme which mimics the
cooling history of a thermodynamic system.
  Because of the technique used there is no way to estimate the 
accuracy of the coefficients for a single solution. Rerun the program
several times. Note that the routine Metropolis will take
a different solution route each attempt (based upon the time of day)
so you cannot ever repeat yourself (or cheat).



 STARTING PROGRAM (in tutor mode):

  There are separate PDFs for each selection point seen in the main menu.  On 
selection of a particular menu point you will enter the normal tutor mode of 
this PDF.  

The menu points have the following meanings:

1. Select the first menu point to input the general parameters for the program
   such as the names of input photometric catalog IBIS file, the type of 
   photometric funtion, the fit conditions and the kind of outputs. 

2. This point contains all function specific parameters (first guess, upper and 
   lower limits, first temperatur). The name of this menu point is changing 
   depending on your input of the parameter PHO_FUNC in the first menu point. 

3. Select this menu point to specify the name of the parameter file which is 
   generated by the program (the default name in VICAR programs: LAST.PAR).
   This is useful because in a Menu there is no 'save'-command to save a 
   parameter file with a user-specified name (e.g. "save photfit2.par").

   EXECUTION :

   USER ACTION				RESULT

   don't call this menu point		last.par

   exit this menu point with 'exit'	last.par

   exit this menu point with 'run'	the user-specified name or the 'name 
					of the application procedure .par' as 
					it is given by the parameter 'save_par'

4. This menu point is to be entered to execute the main program.

You can repeat all steps and reenter all menu items except the step that leads 
to the execution of the program.

If you request help for the selection points in the Menu, you will get the help 
text contained in the respective sub PDFs.



HELPS :

- You will get the common help contained in the ".mdf" file (photfit2.mdf) by 
  typing "help *" in the menu,
- but you will get the help text contained in programs main-PDF (photfit2.pdf) 
  by processing of "help-help" applied to the program (should be verry 
  similary ones of photfit2.mdf).
- If you request help for the selection points in the Menu, you will get the 
  help text contained in the respective sub PDFs.




TESTING and EXAMPLES:

  You can test PHOTFIT2 with program PHOTTEST2:

  phottest out=phottest_m.dat PHO_FUNC=MINNAERT CLASS_ID=2    ALBEDO=0.7 EXPONENT=0.6    START=(10,10,10) DELTA=(30,30,180) SIGMA=0.000001 

  photfit2 inp=(phottest_m.dat,phottest_m.dat) PHO_FUNC=MINNAERT CLASS_ID=2    ALBEDO=0.6 MIN_ALBEDO=0.0 MAX_ALBEDO=1.0 T_ALBEDO=0.1    EXPONENT=0.6 MIN_EXPONENT=0.0 MAX_EXPONENT=1.0 T_EXPONENT=0.1    NORM=25 RERUN=2 MAXITER=100 NUMTEN=25 METRO=20 PERCENT=90 TOLERANC=0.02 'PRINT 

  or, to actually run it you must generate a bunch of photom/hwphoca*
  files:

  photom INP=pix#1 out=ibis1    ( interactive job )
  photom INP=(pix#2,ibis1) out=ibis2 'batch   (batch mode)
  photom INP=(pix#3,ibis1) out=ibis3 'batch   (batch mode)
  photom INP=(pix#4,ibis1) out=ibis4 'batch   (batch mode)
  photom INP=(pix#5,ibis1) out=ibis5 'batch   (batch mode)
  photom INP=(pix#6,ibis1) out=ibis6 'batch   (batch mode)
  photfit2 INP=(ibis1,ibis2,ibis3,ibis4,ibis5,ibis6)             PHO_FUNC=HAPKE_86_HG1  MAXITER=20000




INPUT

PHOTFIT2 accepts two types of input files - the old IBIS1 file and a IBIS2 file 
of the type=phocat.


IBIS1 FILE FORMAT:

There are 18 columns in this file. 
All are not used exept for columns # 11, 12, 13, and 16. 
These columns contain :
	column # 11 = incidence angle (degrees),
	column # 12 = emission angle (degrees),
	column # 13 = phase angle (degrees)
	column # 16 = I/F reflectance values.


PHOCAT FILE:

The structure of the IBIS2 file of type phocat is desined in such a way that 
tiepoint files can be extended and containing all collumns of the old IBIS1 
photometric catalog files. The program PHOTFIT2 used only one IMAGE_* group at 
time. but tiepoint files using some IMAGE_* groups containing informations 
relates to the image.
GENERAL_QLF containes informations relates to the object point (e.g. 
CLASS_IDentifier). OBJECT_COORDINATES containes only coordinates of the object 
point (e.g. LATitude, LONGitude or the X,Y,Z-coordinates in planetocentric 
coordinate system).

The structure of the photometric catalog file is given by: 
(There are 19 columns in this file.)

abstract groups	      primitive groups    units	      formats  used in PHOTFIT2

IMAGE_1 		line 		  pixels	REAL	 used
			samp		  pixels	REAL	 used
			ObjectLine	  pixels	REAL	  --
			ObjectSamp	  pixels	REAL	  --
			BoxLines	  pixels	REAL	  --
			LuminanceLat	  degrees	DOUB	  --
			LuminanceLong	  degrees	DOUB	  --
			IncidenceAngle	  degrees	DOUB	 used
			EmissionAngle	  degrees	DOUB	 used
			PhaseAngle	  degrees	DOUB	 used
			DN_BoxMean	  DN		DOUB	  --
			Radiance	W/cm**2/str/nm	DOUB	  --
			I/F		  --		DOUB	 used
			StandDev	  --		DOUB	 used

OBJECT_COORDINATES  	LAT		  degrees	REAL	  --
			LONG		  degrees	REAL	  --

GENERAL_QLF		--		  --		DOUB	  --
			CLASS_ID	  --		FULL	 used

The "phocat" file can contain data of different classes (CLASS_ID). The program 
PHOTFIT2 will using the data of given class only (or all data if class is not 
given).
The program uses the value from the column "StandDev" (if given) for weigthing the reflectance value by fitting. 





SUBROUTINES REQUIRED TO RUN PROGRAM:	pho_routines package,
					PHOPDF package

INCLUDE FILES REQUIRED TO RUN PROGRAM:	pho.h,
					pho_global.pdf,
					ibisfile.h, ibisfile.h, 
					vicmain_c, defines.h, 
					math.h, time.h 

	

BACKGROUND AND REFERENCES :	Jean J. Lorre, 
				Function Minimization With Partially Corrected 
				Data Via Simulated Annealing,
				J. Soc. Ind. Appl. Math., 43 (1990), 123-127


SOFTWARE PLATFORM :		VICAR, TAE
				(AXP/SUNOS/SOLARIS/SGI)

HARDWARE PLATFORM :		No particular hardware required;
				tested on AXP/SUNOS/SOLARIS/SGI

PROGRAMMING LANGUAGE :		TCL , C	

HISTORY:			Programmer: J J Lorre,  Jan 10 1988
				rewritten in C: Friedel Oschuetz, Nov. '95,
Revisions:
 14 Jun 1996  GMY  Removes tabs from IMAKE file (DFR).

 25 Mar 1998  TXH  Modified to work with new IBIS prototypes (DFR).

  4 Sep 2014  WLB  Corrected several memory allocation bugs.

COGNIZANT PROGRAMMER:		Friedel Oschuetz
				Institute of Planetary Exploration
				DLR
				12484 Berlin (FRG)

PARAMETERS: