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 optimization package
 is the so-called "offline" version, where the optimization 
 package generates ecco_ctrl for offline forward/adjoint 
 runs. As such, the logical variable "loffline" has to be 
 set to .TRUE. Also, one has to set numiter=1 and nfunc=1. 
 The code will stop if numiter or nfunc is not set to one. 
 Nothing has been tested for "online" iterations where forward/
 adjoint runs are conducted within the optimization package.   

 The main differences between this updated version and that 
 in the MITgcm main CVS repository are
 a) 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.      
 b) In this version, tact (step size) in the beginning is 
    computed as (xx(i+1)-xx(i))/dd(i-1), but in the version 
    in the main repository tact was set to 1. 
 c) The two parameters used in Wolfe's conditions are  
    xpara1 = 0.000001 and xpara2 = 0.99999. They were 
    0.0001 and 0.9 in the original code.  

1) Compile
 To compile, one has to 
 a) set MAX_INDEPEND in 
 optim/Makefile (line 52) to the control vector length of 
 his/her model;
 b) include his/her build directory by replacing  
  "../../../verification/release3/build/" in optim/Makefile 
  (line 31) with the path of his/her own build directory. 
 And then do the following:
 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' 
 for iteration zero in 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	ou.wang	1.3	used in ECCO Version 4, Release 3. The optimization package
7			is the so-called "offline" version, where the optimization
8			package generates ecco_ctrl for offline forward/adjoint
9			runs. As such, the logical variable "loffline" has to be
10			set to .TRUE. Also, one has to set numiter=1 and nfunc=1.
11			The code will stop if numiter or nfunc is not set to one.
12			Nothing has been tested for "online" iterations where forward/
13			adjoint runs are conducted within the optimization package.
14
15			The main differences between this updated version and that
16			in the MITgcm main CVS repository are
17			a) whether to overwrite OPWARMI and OPWARMD when either
18			of the two Wolfe conditions is not satisfied. This updated
19			version would not overwrite OPWARMI and OPWARMD, while that
20			in the main repository would.
21			b) In this version, tact (step size) in the beginning is
22			computed as (xx(i+1)-xx(i))/dd(i-1), but in the version
23			in the main repository tact was set to 1.
24			c) The two parameters used in Wolfe's conditions are
25			xpara1 = 0.000001 and xpara2 = 0.99999. They were
26			0.0001 and 0.9 in the original code.
27	ou.wang	1.1
28	ou.wang	1.2	1) Compile
29	ou.wang	1.3	To compile, one has to
30			a) set MAX_INDEPEND in
31			optim/Makefile (line 52) to the control vector length of
32			his/her model;
33			b) include his/her build directory by replacing
34			"../../../verification/release3/build/" in optim/Makefile
35			(line 31) with the path of his/her own build directory.
36			And then do the following:
37	ou.wang	1.1	cd lsopt
38	ou.wang	1.2	make clean
39	ou.wang	1.1	make
40			cd optim
41	ou.wang	1.2	make clean
42	ou.wang	1.1	make
43			The executable would be optim.x in optim/.
44
45	ou.wang	1.2	2) Check for Wolfe conditions
46			This updated version will NOT overwrite OPWARMI
47			and OPWARMD, when either of the two Wolfe
48			conditions is NOT satisfied. The two Wolfe
49			conditions are 1) sufficient decrease condition
50			(Armijo rule) and 2) curvature condition (cf.
51			Wolfe [1969], [1971]). Suppose we are computing
52			ecco_ctrl for iteration i (i>1) and we direct the
53			print-outs to a file called op.txt. If we
54			found 'Wolfe test 1: failed' or 'Wolfe test 2: failed'
55			in op.txt, then the previous iteration (i-1) is
56			NOT a solution. The optimization package will still
57			generate a new ecco_ctrl file that we would use to
58			re-do a new iteration. Note that when deriving
59			iteration one, one would always find
60			'Wolfe test 1: failed' or 'Wolfe test 2: failed'
61	ou.wang	1.3	for iteration zero in in op.txt and need to
62			disregard this message, since iteration zero is
63			always a solution.
64	ou.wang	1.2
65			References:
66			Wolfe, P. (1969). "Convergence Conditions for Ascent Methods". SIAM Review.
67			11 (2): 226-235. doi:10.1137/1011036.
68			Wolfe, P. (1971). "Convergence Conditions for Ascent Methods. II: Some Corrections".
69			SIAM Review. 13 (2): 185-188. doi:10.1137/1013035