Merge remote-tracking branch 'origin/release-v4.6.1'
[WRF.git] / test / em_esmf_exp / README_WRF_CPL_SST.txt
blobcce0ad76a91c8f288f13a5dbf9a3669717ce3bd3
3                   Summary of ESMF-Coupled WRF Experiment
5                               Tom Henderson
6                              John Michalakes
7                                 NCAR/MMM
8                              27 February 2007
10 INTRODUCTION
12 This document describes ESMF-enablement and coupling of WRF through ESMF
13 to another component that simulates coupling to an ocean model. As a
14 prelude to availability of an ESMF-enabled implementation of the HYCOM
15 model, WRF has been coupled through ESMF to a very simple "data-ocean"
16 component named "SST" via a very simple coupler component named "CPL".
17 The demonstration, conducted on kraken.navo.hpc.mil, a DoD HPC system
18 at the NAVO MSRC, was supported by AFWA under UCAR contract FA4600-05-P-0162.  
19 The demonstration was later repeated on NCAR's bluesky machine (IBM p690) and 
20 again on NCAR's bluevista machine (IBM p575).  A description of the bluesky 
21 and bluevista experiments follows.  
25 EVENT LOOP
27 Please read the section entitled "NOTES ABOUT THE EVENT LOOP FOR WRF+CPL+SST" 
28 in file external/io_esmf/README.io_esmf for details about order of operations
29 in the current event loop (time-stepping loop).  
33 EXPERIMENT DETAILS
35   The "WRF+CPL+SST" experiment was conducted on bluesky on 12 October 2006 at 
36 which time the following software was installed:  
37   xlfrte   8.1.1.6
38   bos.mp   5.1.0.58
39   xlC.rte   6.0.0.0
40   ESMF 2.2.0rp1
41 WRF source code was installed in
42 WRFDIR=/ptmp/hender/ESMF2.2.0rp1/WRFV2_20061005_1123_WORK/WRFV2/.  
43 (Referred to below as "$WRFDIR".)  
45   The "WRF+CPL+SST" experiment was repeated on bluevista on 27 February 2007 at 
46 which time the following software was installed:  
47   xlfrte   10.1.0.3
48   bos.mp   5.3.0.42
49   xlC.rte  8.0.0.5
50   ESMF     2.2.2r
51 WRF source code was installed in
52 WRFDIR=/ptmp/hender/WRF-LIS/WRFV2_20070214_0906/WRFV2/.
54   Additional documentation that describes the SST component and provides 
55 instructions for building WRF with ESMF can be found in 
56 external/io_esmf/README.io_esmf.  Briefly, the 
57 SST component simply reads SST data stored in a file (sstin_d01_000000), sends 
58 it to WRF via CPL, receives SST data back from WRF via CPL, and verifies that 
59 data received matches data sent.  Since ESMF coupling is implemented within 
60 WRF via the WRF I/O and coupling API (WRF IOAPI), the experiment can be 
61 repeated reading the SST data directly into WRF as a netCDF file simply by 
62 changing the appropriate I/O format in the WRF "namelist.input" file.  This 
63 feature is illustrated below.  
65   The following "recipe" can be used to reproduce the experiment, if desired.  
66 All commands are csh.  
69 1)  On bluesky, set environment variables to build WRF with ESMF using 32-bit 
70 addressing.  On bluevista, use the default 64-bit addressing.  
71 Set the $ESMFLIB and $ESMFINC environment variables are to tell the WRF build 
72 automation where to find an installation of ESMF.  
74 BLUESKY:  
75 OBJECT_MODE=32
76 ESMFLIB=/home/bluesky/hender/esmf/lib/libO/AIX.default.32.default
77 ESMFINC=/home/bluesky/hender/esmf/mod/modO/AIX.default.32.default
79 BLUEVISTA:  
80 OBJECT_MODE=64
81 ESMFLIB=/home/bluevista/hender/esmf/esmf_2_2_2r/lib/libO/AIX.default.64.mpi.default
82 ESMFINC=/home/bluevista/hender/esmf/esmf_2_2_2r/mod/modO/AIX.default.64.mpi.default
86 2)  Set up WRF Registry for WRF+CPL+SST case:  
88 $WRFDIR/Registry >> mv -f Registry.EM Registry.EM_ORIG
89 $WRFDIR/Registry >> cp -f Registry.EM_SST Registry.EM
93 3)  Build WRF from scratch with RSL_LITE for use with ESMF:  
95 $WRFDIR >> echo 5 | configure
96 $WRFDIR >> compile em_real >&! compile.em_real.5.out
98   Verify that executables exist:  
100 $WRFDIR >> ls -1 main/*exe
101 main/ndown.exe
102 main/nup.exe
103 main/real.exe
104 main/wrf.exe
105 main/wrf_SST_ESMF.exe
107   Note that "wrf.exe" is the usual stand-alone WRF executable.  
108 "wrf_SST_ESMF.exe" is the WRF+CPL+SST coupled application.  
112 4)  Go to run directory, unpack the required SST data, namelists and run 
113 scripts from WRF_CPL_SST.tar.gz, and verify that all required files are
114 present:   
116 $WRFDIR/test/em_esmf_exp >> gunzip WRF_CPL_SST.tar.gz
117 $WRFDIR/test/em_esmf_exp >> tar xvf WRF_CPL_SST.tar
118 $WRFDIR/test/em_esmf_exp >> ls -l sstin_d01_000000 namelist.input.jan00.* *.csh
119 -rw-r--r--   6368 Feb 27 13:16 namelist.input.jan00.ESMFSST
120 -rw-r--r--   6368 Feb 27 13:16 namelist.input.jan00.NETCDFSST
121 -rw-r--r--   1286 Feb 27 14:51 real.csh
122 -rwxr-xr-x    948 Feb 27 14:51 real.lsf.csh
123 -rw-r--r-- 458064 Oct 12 11:58 sstin_d01_000000
124 -rw-r--r--   1074 Feb 27 14:51 test4_0.csh
125 -rwxr-xr-x    732 Feb 27 14:51 test4_0.lsf.csh
126 -rw-r--r--   1162 Feb 27 14:51 test4_0_ESMFSST.csh
127 -rw-r--r--    824 Feb 27 14:51 test4_0_ESMFSST.lsf.csh
128 -rw-r--r--   1190 Feb 27 14:52 test4_0_NETCDFSST_wrfexe.csh
129 -rw-r--r--    824 Feb 27 14:52 test4_0_NETCDFSST_wrfexe.lsf.csh
131   "sstin_d01_000000" contains time-varying SST input data.  
132 NOTE:  sstin_d01_000000 also contains LANDMASK fields soley for validation 
133 purposes.  Only the first time-level of LANDMASK is significant.  For
134 historical reasons, the other time-levels may differ -- they are ignored 
135 (and should eventually be removed).  
137   "test4_0_ESMFSST.csh" is a LoadLeveler batch submission script that runs the 
138 WRF+CPL+SST coupled system.  It copies "namelist.input.jan00.ESMFSST" to 
139 "namelist.input" and runs "wrf_SST_ESMF.exe" on four CPUs.
140 "test4_0_ESMFSST.lsf.csh" does the same thing for LSF.  
142   "test4_0_NETCDFSST.csh" is a LoadLeveler batch submission script that runs 
143 WRF by itself, reading the SST data directly into WRF as a netCDF file.  It 
144 copies "namelist.input.jan00.NETCDFSST" to "namelist.input" and runs "wrf.exe" 
145 on four CPUs.  
146 "test4_0_NETCDFSST.lsf.csh" does the same thing for LSF.  
148   Note that namelists namelist.input.jan00.ESMFSST and 
149 namelist.input.jan00.NETCDFSST differ only in the I/O format used for the 
150 I/O streams used to "read" and "write" SST data.  Vanilla netCDF I/O is used 
151 when "io_form" == 2.  ESMFStates are used when "io_form" == 7.  
153 $WRFDIR/test/em_esmf_exp >> diff namelist.input.jan00.ESMFSST namelist.input.jan00.NETCDFSST
154 32c32
155 <  io_form_auxinput5                   = 7,
157 >  io_form_auxinput5                   = 2,
158 37c37
159 <  io_form_auxhist5                    = 7,
161 >  io_form_auxhist5                    = 2,
163   (Also note that a script is provided to run WRF without SST forcing for 
164 comparison purposes.  "test4_0.csh" is a LoadLeveler batch submission script 
165 that runs WRF by itself without SST forcing.  It copies "namelist.input.jan00" 
166 to "namelist.input" and runs "wrf.exe" on four CPUs.  "test4_0.lsf.csh" does 
167 the same thing for LSF.)  
171 5)  Run the wrf real program using the "jan00" data set.  Script "real.csh" 
172 can be modified to do this if desired (or real.lsf.csh for LSF).  
174 BLUESKY (LoadLeveler):  
175 $WRFDIR/test/em_esmf_exp >> llsubmit real.csh
176 BLUEVISTA (LSF):  
177 $WRFDIR/test/em_esmf_exp >> bsub < real.lsf.csh
179   Verify that real.exe produced the usual WRF input and boundary data files 
180 "wrfbdy_d01" and "wrfinput_d01".  
182 $WRFDIR/test/em_esmf_exp >> ls -al wrfbdy_d01 wrfinput_d01
183 -rw-r--r--   9355944 Feb 27 12:58 wrfbdy_d01
184 -rw-r--r--   6076408 Feb 27 12:58 wrfinput_d01
186 Move all other files produced by the real.exe run into a new directory:  
188 $WRFDIR/test/em_esmf_exp >> mkdir real.out
189 $WRFDIR/test/em_esmf_exp >> mv PET?.ESMF* namelist.input rsl.*.* real.*.err real.*.out real.out
193 6)  Run the WRF+CPL+SST test case:  
195 BLUESKY (LoadLeveler):  
196 $WRFDIR/test/em_esmf_exp >> llsubmit test4_0_ESMFSST.csh
197 BLUEVISTA (LSF):  
198 $WRFDIR/test/em_esmf_exp >> bsub < test4_0_ESMFSST.lsf.csh
202 7)  Verify that run completed successfully:  
204 $WRFDIR/test/em_esmf_exp >> tail -1 rsl.out.0000
205  d01 2000-01-25_00:00:00 wrf: SUCCESS COMPLETE WRF
209 8)  Move all files produced by the WRF+CPL+SST run into a new directory:  
211 $WRFDIR/test/em_esmf_exp >> mkdir test4_0_ESMFSST.out
212 $WRFDIR/test/em_esmf_exp >> mv PET?.ESMF* namelist.input rsl.*.* test4_0_ESMFSST.*.* wrfout* test4_0_ESMFSST.out
216 9)  Run the WRF stand-alone test case:  
218 BLUESKY (LoadLeveler):  
219 $WRFDIR/test/em_esmf_exp >> llsubmit test4_0_NETCDFSST_wrfexe.csh
220 BLUEVISTA (LSF):  
221 $WRFDIR/test/em_esmf_exp >> bsub < test4_0_NETCDFSST_wrfexe.lsf.csh
225 10)  Verify that run completed successfully:  
227 $WRFDIR/test/em_esmf_exp >> tail -1 rsl.out.0000
228  d01 2000-01-25_00:00:00 wrf: SUCCESS COMPLETE WRF
232 11)  Move all files produced by the WRF stand-alone run into a new directory:  
234 $WRFDIR/test/em_esmf_exp >> mkdir test4_0_NETCDFSST.out
235 $WRFDIR/test/em_esmf_exp >> mv PET?.ESMF* namelist.input rsl.*.* test4_0_NETCDFSST.*.* wrfout* sstout_d01_000000 test4_0_NETCDFSST.out
239 12)  Verify that both tests produced bitwise-identical history output:  
241 $WRFDIR/test/em_esmf_exp >> ls -l test4_0_ESMFSST.out/wrfout_d01_2000-01-24_12:00:00 test4_0_NETCDFSST.out/wrfout_d01_2000-01-24_12:00:00
242 -rw-r--r--   1 hender   ncar       32614704 Oct 12 15:48 test4_0_ESMFSST.out/wrfout_d01_2000-01-24_12:00:00
243 -rw-r--r--   1 hender   ncar       32614704 Oct 12 15:52 test4_0_NETCDFSST.out/wrfout_d01_2000-01-24_12:00:00
245 $WRFDIR/test/em_esmf_exp >> cmp -l test4_0_ESMFSST.out/wrfout_d01_2000-01-24_12:00:00 test4_0_NETCDFSST.out/wrfout_d01_2000-01-24_12:00:00 | wc
246        0       0       0