Contents 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	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 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
28	1) Compile
29	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	cd lsopt
38	make clean
39	make
40	cd optim
41	make clean
42	make
43	The executable would be optim.x in optim/.
44
45	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	for iteration zero in in op.txt and need to
62	disregard this message, since iteration zero is
63	always a solution.
64
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