improve new README

verification/atm_gray/README.md

@@ -2,46 +2,63 @@ Gray atmosphere physics example on Cubed-Sphere grid
 ============================================================
 
 Use gray atmospheric physics (O'Gorman and Schneider, JCl, 2008)
-from package "atm_phys" inside  MITgcm dynamical core.
-
-1) standard cubed-sphere set-up (6 faces 32x32, 26 levels, non uniform deltaP)
-   atm_gray/code/   : specific code
- primary set-up:
-      uses 10m mixed layer depth with evolving SST (including a Q-flux)
-      + damping of stratospheric winds ; starts @ t= 1.yr from pickup files.
-   atm_gray/input/  : input files (+ uses script "prepare_run" in input)
-   atm_gray/results/output.txt : standard output of a short reference run
- secondary set-up (using same executable):
-      uses fixed SST (APE) and improved radiation code from Ruth Geen.
-   atm_gray/inputu.ape/  : specific input files (remaining files from dir input)
-   atm_gray/results/output.ape.txt : secondary output of a short reference run
-
---------------
-Instructions:
---------------
-Download MITgcm (including verification experiments) from MITgcm repository
- <my_dir_space> cvs co -P -d MITgcm_current MITgcm
-and download "atm_gray" set-up from MITgcm_contrib repository,
-   a) either directly in dir verification
-     <my_dir_space> cd MITgcm_current/verification
-     <verification> cvs co -P -d atm_gray MITgcm_contrib/verification_other/atm_gray
-or b) in a similar level in the directory tree, e.g., in verification_other in MITgcm_current:
-     <my_dir_space> cd MITgcm_current
-     <MITgcm_current> mkdir verification_other ; cd verification_other
-     <verification_other> cvs co -P -d atm_gray MITgcm_contrib/verification_other/atm_gray
-
-to built and run the 1rst (standard) CS-32 set-up:
-> cd atm_gray/build
-> (if done after a previous built, do "make Clean" first)
-> ../../../tools/genmake2 -mods ../code -of ../../../tools/build_options/[Selected-Option-File]
-> make depend
-> make
-> cd ../run
-> (if done after a previous run, clean-up all files: /bin/rm -f * )
-> ln -s ../input/* .
-> ../input/prepare_run
-> ln -s ../build/mitgcmuv .
-> mitgcmuv >& output.txt
-and output.txt can be compared with atm_gray/results/output.txt
-
---------------
+from package `atm_phys` inside  MITgcm dynamical core, in a global
+cubed-sphere grid set-up (6 faces 32x32, 26 levels, non uniform deltaP).
+
+### Overview:
+This experiment contains 2 aqua-planet like set-ups (with corresponding `input[.*]/` dir)
+that can be run with the same executable (built from `build/` dir using customized
+code from `code/`); binary input files have been generated using matlab script
+`gendata.m` from the `input` dir.
+
+The **primary** test, using input files from `input/` dir,
+has an interactive SST with a 10m mixed layer depth and a prescribed,
+time-invariant Q-flux.  It also includes a weak damping of stratospheric winds.
+This test experiment starts from a spin-up state using pickup files (@ t= 1.yr).
+
+The **secondary** test `input.ape/` dir is the same as the primary test but
+use prescribed idealized SST from Neale and Hoskins, 2001, Aqua-Planet Experiment (APE) project
+without stratospheric wind damping.
+
+### Instructions:
+Configure and compile the code:
+
+```
+  cd build
+  ../../../tools/genmake2 -mods ../code [-of my_platform_optionFile]
+  make depend
+  make
+  cd ..
+```
+
+To run primary test:
+
+```
+  cd run
+  ln -s ../input/* .
+  ./prepare_run
+  ../build/mitgcmuv > output.txt
+```
+
+There is comparison output in the directory:
+
+  `results/output.txt`
+
+To run secondary "ape" test:
+
+```
+  cd run
+  rm *
+  ln -s ../input.ape/* .
+  ln -s ../input/* .
+  ./prepare_run
+  ../build/mitgcmuv > output.txt
+```
+There is comparison output in the directory:
+
+  `results/output.ape.txt`
+
+### Notes:
+There special compiler options inside `build/genmake_local` to compile some
+of the files from `pkg/atm_phy` that requires to explicitly provide an optfile
+to `genmake2` command.