Warning, /optim/README.md is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit 5cf43646 on 2024-03-01 18:50:49 UTC
5cf4364659 Mart*0001 # Description and building instructions for optim.x
0002
0003 This directory contains code to compile the optimization routine `optim.x`.
4cee17c1be Patr*0004
ae17457769 Andr*0005 Note, that there is an alternative optimization package [optim_m1qn3](
5cf4364659 Mart*0006 https://github.com/mjlosch/optim_m1qn3) that is based on the latest (and last)
0007 version of
ae17457769 Andr*0008 [m1qn3](https://who.rocq.inria.fr/Jean-Charles.Gilbert/modulopt/optimization-routines/m1qn3/m1qn3.html).
0009
5cf4364659 Mart*0010 `optim.x` requires the library `lsopt_ecco` and the BLAS library `blas`. The
0011 build procedure is a two step process (first build `lsopt_ecco` and `blas`, and
0012 then `optim.x` ) and by no means foolproof. It requires that you generate a
0013 makefile in this directory and modify the sample `Makefile` in `../lsopt`. For
0014 illustration purposes, let us assume that we want to generate an `optim.x` for
0015 `myExp=tutorial_global_oce_optim` in `MITgcm/verification`.
ae17457769 Andr*0016
5cf4364659 Mart*0017 ## Building library `lsopt_ecco` and `blas`
ae17457769 Andr*0018
5cf4364659 Mart*0019 In `MITgcm/lsopt` adjust the compiler and compiler flags in `Makefile`. Using
0020 the same compiler and flags as for building the `mitgcmuv_ad` executable in
0021 `$myExp` is probably the best guess, see also below how the `MITgcm/optim`
0022 `Makefile` is generated. The default works for a standard Ubuntu system, but
0023 not e.g. for a Mac. There's a makefile `MITgcm/lsopt/Makefile_macos` that has
0024 worked for MacOS, but may require adjustment. After adjusting the makefile,
0025 compile the libraries like this:
ae17457769 Andr*0026
0027 ```
0028 cd ../lsopt
0029 make
0030 ```
5cf4364659 Mart*0031 The resulting libraries `lsopt_ecco` and `blas` will be used in the second
0032 step.
0033
0034 ## Building `optim.x`
ae17457769 Andr*0035
5cf4364659 Mart*0036 To generate the makefile based on the setting in `$myExp` and to build
0037 `optim.x`, change into `optim` and run
ae17457769 Andr*0038
0039 ```
0040 cd ../optim
5cf4364659 Mart*0041 ./prep_make ../../MITgcm/verification/${myExp}/build
0042 make clean
0043 make depend
ae17457769 Andr*0044 make
0045 ```
0046
5cf4364659 Mart*0047 `prep_make` generates a local `Makefile` from `makefile_templ` and from
0048 `$myExp` `build/Makefile`. It fills some `makefile_templ` placeholder
0049 `_GET_keyWord` with the corresponding option/parameter value "keyWord" found in
0050 the build/Makefile (the current list of keyWords is: `BLD_DIR`, `EXTRA_OPT`,
0051 `CPPCMD`, `SFX`, `FC`, `FFLAGS` and `FOPTIM`). A simple usage description is
0052 returned when typing `./prep_make` alone.
0053
0054 In some cases you may have to adjust `makefile_templ`(e.g. for the path to a
0055 non-standard `makedepend`) before running `prep_make`.
0056 Note that the `Makefile` generated using `prep_make` option `-fake` is only for
0057 testing purpose, to get a fake `optim.x` that just reads gradient vector files
0058 without any lsopt pieces.
0059
0060 It may make sense to first generate the makefile in `MITgcm/optim` with
0061 `prep_make`, and then use the parameters in the generated `Makefile` to adjust
0062 the sample `Makefile` in `MITgcm/lsopt`, build the libraries, and then
0063 return to `MITgcm/optim` to build `optim.x`.
0064
0065 ## Backward compatibility
0066
0067 With PR #[796](https://github.com/MITgcm/MITgcm/pull/796), the header format of
0068 the control and gradient vector files and the length of the stored fields has
0069 changed. To read old gradient vector files (typically called
0070 `ecco_cost_MIT_CE_000.opt0000` for the first optimisation call) with `optim.x`,
0071 define CPP flag `READ_OLD_CTRL_PACK_FILE` in `CTRL_OPTIONS.h` before compiling
0072 `optim.x`. The resulting `optim.x` will read the old format gradient vector and
0073 write the new control vector (typically called `ecco_ctrl_MIT_CE_000.opt0001`)
0074 in the new format. After the new control vector has been written,
0075 `READ_OLD_CTRL_PACK_FILE` should be reset to `undef` again (and `optim.x`
0076 recompiled) for the next optimisation.
0077
0078 ## Old README
0079
0080 The following is the content of the old README. It describes some sort of
0081 interface, i.e. the header of the control and gradient vectors written and read
0082 by the `mitgcmuv_ad` (and `optim.x`), see `optim_readdata.F` and
0083 `optim_writedata.F`. More details can be found in the [online
0084 manual](https://mitgcm.readthedocs.io/en/latest/ocean_state_est/ocean_state_est.html#the-line-search-optimisation-algorithm)
0085 (Chapter 10).
0086
ae17457769 Andr*0087 ```
4cee17c1be Patr*0088 c expid - experiment name
0089 c optimcycle - optimization no.
0090 c missing value - missing value identifier (usually -9999.)
0091 c ig - global start index x (zonal)
ae17457769 Andr*0092 c jg - global start index y (merid.)
4cee17c1be Patr*0093 c nsx - no. of x-subgrids
0094 c nsy - no. of y-subgrids
0095
0096 >>> MISSING: <<<
0097 c nr - no. of z-points vertical
0098 c snx
0099 c sny
0100 c nvartype
0101 c nvarlength
0102 >>> <<<
0103
0104 c maxcvars - Number of control variables
0105 c (currently 6; 2 init. + 4 bound.)
0106 integer maxcvars
0107 parameter ( maxcvars = 20 )
0108
0109 c ncvarindex - "arbitrary" index to define variable:
0110 c * 101: initial temp.
0111 c * 102: initial sali.
0112 c * 103: heat flux
0113 c * 104: freshwater flux
0114 c * 105: u stress (zonal)
ae17457769 Andr*0115 c * 106: v stress (merid.)
4cee17c1be Patr*0116 integer ncvarindex ( maxcvars )
0117
0118 c ncvarrecs - no. of records in control vector
0119 c * = 1 for init. temp./sali.
0120 c * = endrec - startrec + 1 for fluxes
0121 integer ncvarrecs ( maxcvars )
0122
0123 c ncvarrecstart - first record:
0124 c * NOT DEFINED for init. temp./sali.
0125 c * = startrec for fluxes
0126 integer ncvarrecstart ( maxcvars )
0127
0128 c ncvarrecsend - last record:
0129 c * NOT DEFINED for init. temp./sali.
0130 c * = endrec for fluxes
0131 integer ncvarrecsend ( maxcvars )
0132
0133 c ncvarxmax - no. of x-points in subgrid (zonal)
0134 c = snx
0135 integer ncvarxmax ( maxcvars )
0136
ae17457769 Andr*0137 c ncvarymax - no. of y-points in subgrid (merid.)
4cee17c1be Patr*0138 c = sny
0139 integer ncvarymax ( maxcvars )
0140
0141 c ncvarnrmax - no. of z-points (vert.)
0142 c * = nr for init. temp./sali.
0143 c * = 1 for fluxes
0144 integer ncvarnrmax ( maxcvars )
0145
0146 c nwet[c/s/w]tile - Number of wet points in a tile for center (c),
0147 c south (s), and western (w) mask, resp.
0148 integer nwetctile ( nsx, nsy, nr )
0149 integer nwetstile ( nsx, nsy, nr )
0150 integer nwetwtile ( nsx, nsy, nr )
0151
0152 c ncvargrd - position in grid
0153 c * = 'c' : (center,center)
0154 c * = 's' : (center,south)
0155 c * = 'w' : (west,center)
0156 character*(1) ncvargrd(maxcvars)
ae17457769 Andr*0157
0158 ```
