Annotation of /MITgcm_contrib/ecco_utils/ecco_v4_release3_optimization/README

20171119
Ou Wang 
Jet Propulsion Laboratory

This directory contains the updated optimization package
 used in ECCO Version 4, Release 3. The main difference
 between this updated version and that in the MITgcm main
 CVS repository is whether to overwrite OPWARMI and OPWARMD  
 when either of the two Wolfe conditions is not
 satisfied. This updated version would not overwrite
 OPWARMI and OPWARMD, while that in the main repository
 would.      

1) Compile
 To compile, one first has to set MAX_INDEPEND in 
 optim/Makefile to the control vector length of his/her model.   

 cd lsopt
 make clean
 make 
 cd optim
 make clean
 make 
 The executable would be optim.x in optim/.

2) Check for Wolfe conditions 
 This updated version will NOT overwrite OPWARMI
 and OPWARMD, when either of the two Wolfe 
 conditions is NOT satisfied. The two Wolfe 
 conditions are 1) sufficient decrease condition
 (Armijo rule) and 2) curvature condition (cf. 
 Wolfe [1969], [1971]). Suppose we are computing 
 ecco_ctrl for iteration i (i>1) and we direct the 
 print-outs to a file called op.txt. If we 
 found 'Wolfe test 1: failed' or 'Wolfe test 2: failed'
 in op.txt, then the previous iteration (i-1) is 
 NOT a solution. The optimization package will still
 generate a new ecco_ctrl file that we would use to 
 re-do a new iteration. Note that when deriving 
 iteration one, one would always find 
 'Wolfe test 1: failed' or 'Wolfe test 2: failed' 
 in op.txt and need to disregard this message, 
 since iteration zero is always a solution. 

References:
 Wolfe, P. (1969). "Convergence Conditions for Ascent Methods". SIAM Review. 
  11 (2): 226-235. doi:10.1137/1011036. 
 Wolfe, P. (1971). "Convergence Conditions for Ascent Methods. II: Some Corrections". 
  SIAM Review. 13 (2): 185-188. doi:10.1137/1013035
1	ou.wang	1.1	20171119
2			Ou Wang
3			Jet Propulsion Laboratory
4
5			This directory contains the updated optimization package
6			used in ECCO Version 4, Release 3. The main difference
7			between this updated version and that in the MITgcm main
8	ou.wang	1.2	CVS repository is whether to overwrite OPWARMI and OPWARMD
9	ou.wang	1.1	when either of the two Wolfe conditions is not
10	ou.wang	1.2	satisfied. This updated version would not overwrite
11	ou.wang	1.1	OPWARMI and OPWARMD, while that in the main repository
12			would.
13
14	ou.wang	1.2	1) Compile
15	ou.wang	1.1	To compile, one first has to set MAX_INDEPEND in
16	ou.wang	1.2	optim/Makefile to the control vector length of his/her model.
17	ou.wang	1.1
18			cd lsopt
19	ou.wang	1.2	make clean
20	ou.wang	1.1	make
21			cd optim
22	ou.wang	1.2	make clean
23	ou.wang	1.1	make
24			The executable would be optim.x in optim/.
25
26	ou.wang	1.2	2) Check for Wolfe conditions
27			This updated version will NOT overwrite OPWARMI
28			and OPWARMD, when either of the two Wolfe
29			conditions is NOT satisfied. The two Wolfe
30			conditions are 1) sufficient decrease condition
31			(Armijo rule) and 2) curvature condition (cf.
32			Wolfe [1969], [1971]). Suppose we are computing
33			ecco_ctrl for iteration i (i>1) and we direct the
34			print-outs to a file called op.txt. If we
35			found 'Wolfe test 1: failed' or 'Wolfe test 2: failed'
36			in op.txt, then the previous iteration (i-1) is
37			NOT a solution. The optimization package will still
38			generate a new ecco_ctrl file that we would use to
39			re-do a new iteration. Note that when deriving
40			iteration one, one would always find
41			'Wolfe test 1: failed' or 'Wolfe test 2: failed'
42			in op.txt and need to disregard this message,
43			since iteration zero is always a solution.
44
45			References:
46			Wolfe, P. (1969). "Convergence Conditions for Ascent Methods". SIAM Review.
47			11 (2): 226-235. doi:10.1137/1011036.
48			Wolfe, P. (1971). "Convergence Conditions for Ascent Methods. II: Some Corrections".
49			SIAM Review. 13 (2): 185-188. doi:10.1137/1013035