Contents of /MITgcm_contrib/ecco_utils/ecco_v4_release4_devel/optimization/README

December 18, 2019 
Ou Wang 
Jet Propulsion Laboratory

This directory contains the updated optimization package
 used in ECCO Version 4, Release 4. 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. The control vector length can be found 
 in the model's STDOUT.0000 by searching 
 the string "global nvarlength for Nr". The control 
 vector length is the last number of the line where
 the string is.
 b) include his/her build directory by replacing  
  "../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	December 18, 2019
2	Ou Wang
3	Jet Propulsion Laboratory
4
5	This directory contains the updated optimization package
6	used in ECCO Version 4, Release 4. 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. The control vector length can be found
33	in the model's STDOUT.0000 by searching
34	the string "global nvarlength for Nr". The control
35	vector length is the last number of the line where
36	the string is.
37	b) include his/her build directory by replacing
38	"../build/" in optim/Makefile
39	(line 31) with the path of his/her own build directory.
40	And then do the following:
41	cd lsopt
42	make clean
43	make
44	cd optim
45	make clean
46	make
47	The executable would be optim.x in optim/.
48
49	2) Check for Wolfe conditions
50	This updated version will NOT overwrite OPWARMI
51	and OPWARMD, when either of the two Wolfe
52	conditions is NOT satisfied. The two Wolfe
53	conditions are 1) sufficient decrease condition
54	(Armijo rule) and 2) curvature condition (cf.
55	Wolfe [1969], [1971]). Suppose we are computing
56	ecco_ctrl for iteration i (i>1) and we direct the
57	print-outs to a file called op.txt. If we
58	found 'Wolfe test 1: failed' or 'Wolfe test 2: failed'
59	in op.txt, then the previous iteration (i-1) is
60	NOT a solution. The optimization package will still
61	generate a new ecco_ctrl file that we would use to
62	re-do a new iteration. Note that when deriving
63	iteration one, one would always find
64	'Wolfe test 1: failed' or 'Wolfe test 2: failed'
65	for iteration zero in in op.txt and need to
66	disregard this message, since iteration zero is
67	always a solution.
68
69	References:
70	Wolfe, P. (1969). "Convergence Conditions for Ascent Methods". SIAM Review.
71	11 (2): 226-235. doi:10.1137/1011036.
72	Wolfe, P. (1971). "Convergence Conditions for Ascent Methods. II: Some Corrections".
73	SIAM Review. 13 (2): 185-188. doi:10.1137/1013035