Forward Gradient Tool#
The Forward Gradient (fgrd) Tool computes state’s forward gradient by computing the model’s response to changes in forcing. In this tutorial, we demonstrate how to compute the ocean’s response to a perturbation of -0.1 Nm-2 in the eastward zonal wind stress at a location near the Equator and the Date Line at week 5.
Run Forward Gradient Tool#
We will first configure the Forward Gradient Tool by providing some input parameters, similar to running the Sampling Tool. After setup, the Forward Gradient Tool will be automatically submitted as a SLURM batch job; there is no need to request an interactive node, as is done in running the Sampling Tool.
We will describe each step in running the Forward Gradient Tool. However, because EMU is menu-driven and some of the outputs are the same or very similar to those presented in Sampling Tool, we will not present those outputs unless necessary.
We start the EMU tool and follow the menu to configure it.
/efs_ecco/ECCO/EMU/emu_userinterface_dir/emu
we will get the same basic information about EMU and press the ENTER key to continue. From the list of tools, we will choose the Forward Gradient Tool by entering 2. We will then need to choose which forcing to perturb.
choice is 2) Forward Gradient Tool (fgrd)
See /efs_ecco/ECCO/EMU/emu_userinterface_dir/README_fgrd
************************************
EMU Forward Gradient Tool (singularity)
************************************
**** Step 1: Tool Setup
Running setup_fgrd.sh
... Setting up ECCO V4r4 Forward Gradient Tool ...
**** Step 2: Specification
Running fgrd_spec.x
Forward Gradient Tool ...
Define control perturbation (denominator in Eq 2 of Guide) ...
Available control variables to perturb ...
1) empmr
2) pload
3) qnet
4) qsw
5) saltflux
6) spflx
7) tauu
8) tauv
Enter control (phi in Eq 2 of Guide) ... (1- 8) ?
We will choose tauu (zonal wind stress) by entering 7. Then, we will choose the i and j indices of 15 and 743.
Output:
..... perturbing tauu
Choose location for perturbation (r in Eq 2 of Guide) ...
Enter 1 to choose native grid location (i,j),
9 to select by longitude/latitude ... (1 or 9)?
1
Enter native (i,j) grid to perturb ...
i ... (1-90) ?
15
j ... (1-1170) ?
743
...... perturbation at (i,j) = 15 743
C-grid is (long E, lat N) = 179.5 0.2
Depth (m) = 5390.7
Enter week to perturb (s in Eq 2) ... (1-1358) ?
The tool will ask which week to perturb (see above). For that, we enter 5 for the 5th week. Note that the perturbation is applied at the beginning of week 5, i.e., day 28.
Default perturbation (delta_phi in Eq 4 of Guide) :
-0.1000E+00 in unit N/m2 (westward wind stress)
Enter 1 to keep, 9 to change ... ?
Next, we need to set the perturbation magnitude (and direction). The tool provides a default perturbation for tauu, which is -0.1 Nm-2 (the negative sign indicates the perturbation is westward wind stress). We will use the default perturbation by entering 1, but we can also enter 9 to specify a different perturbation.
Perturbation amplitude = -0.1000E+00
in unit N/m2 (westward wind stress)
V4r4 integrates 312-months from 1/1/1992 12Z to 12/31/2017 12Z
which requires 18 hours wallclock time.
Enter number of months to integrate (Max t in Eq 2)... (1-312)?
We will then enter 12 to integrate the model for 12 months, which should take less than one hour of wall clock time to complete on the P-Cluster. With that, we have set up the Forward Gradient Tool, and the tool will submit a batch job using the SLURM command sbatch. After the following message, SLURM will obtain the requested resources, which takes a few minutes. Once the resources are ready, the run will start .
Will integrate model over 12 months
... Program has set computation periods in files data and pbs_fgrd.sh accordingly.
... Estimated wallclock hours is 1
Wrote fgrd_pert.nml
Wrote fgrd_pert.str
Forward Gradient Tool output will be in : emu_fgrd_7_15_743_5_-1.00E-01
**** Step 3: Calculation
1) Set up files for MITgcm
2) Perturb forcing
inputdir read : /emu_input_dir/forcing
pert_v 7
pert_i 15
pert_j 743
pert_t 5
pert_a -0.100000001
... perturbing tauu
diags exists
diags exists
3) Run MITgcm
4) Compute difference from reference run
... Running batch job pbs_fgrd.sh
to compute the model's forward gradient.
Estimated wallclock time:
#SBATCH --ntasks-per-node=36
********************************************
Results will be in emu_fgrd_7_15_743_5_-1.00E-01/output
********************************************
Progress of the computation can be monitored by
ls emu_fgrd_7_15_743_5_-1.00E-01/temp/diags/*2d*day*data | wc -l
which counts the number of days the model has integrated.
(As standard output, the model saves daily mean files of
sea level and ocean bottom pressure.)
Submitted batch job 819
EMU interactive execution complete. Thu Oct 3 04:27:26 UTC 2024
We can use the SLURM command squeue to check the status of the run (as described in Reproducing ECCO Version 4 Release 4).
Visualize Forward Gradient Tool Results#
Plotting the results of Forward Gradient Tool is the same as plotting Sampling Tool results, except that we now enter the run directory emu_fgrd_7_15_743_5_-1.00E-01. Again, we will show two methods of using the visualization tool.
Tip
A Jupyter Notebook, fgrd_viz (after downloading, rename it to fgrd_viz.ipynb), is provided for users’ convenience. It reproduces the steps and figures described in this visualization tutorial. Users can also add more sophisticated analysis on top of this notebook.
Same as in Sampling Tool, we first log into OSS and start a Jupyter Notebook session.
Method 1: Menu-driven Input#
First create a new Jupyter Notebook, import the runpy module, and then call the Python plotting script located at /efs_ecco/ECCO/EMU/emu_userinterface_dir/python/emu_plot.py. The plotting script asks for the directory name of the EMU run (in this case, emu_fgrd_7_15_743_5_-1.00E-01), and then it generates the plot.
import runpy
runpy.run_path('/efs_ecco/ECCO/EMU/emu_userinterface_dir/python/emu_plot.py');
Found file: /efs_ecco/ECCO/EMU/emu_userinterface_dir/emu_env.singularity
EMU Input Files directory: /efs_ecco/ECCO/EMU/emu_input_dir
Enter directory of EMU run to examine; e.g., emu_samp_m_2_45_585_1 ... ? /efs_ecco/owang/ECCO/EMU/tryout/emu_fgrd_7_15_743_5_-1.00E-01
Reading /efs_ecco/owang/ECCO/EMU/tryout/emu_fgrd_7_15_743_5_-1.00E-01
Reading Forward Gradient Tool output ...
Detected
395 files of state_2d_set1_day.*.data
12 files of state_2d_set1_mon.*.data
12 files of state_3d_set1_mon.*.data
Choose variable to plot ...
1) SSH
2) OBP
3) THETA
4) SALT
5) U
6) V
Select monthly or daily mean ... (m/d)?
(NOTE: daily mean available for SSH and OBP only.)
Enter 'm' for monthly or 'd' for daily: m
==> Reading and plotting monthly means ...
Enter variable # to plot ... (1-6)? 1
Plotting ... SSH
Enter file # to read ... (1-12 or -1 to exit)? 1
Enter file # to read ... (1-12 or -1 to exit)? -1
*********************************************
Returning variable
fgrd2d: last plotted gradient (2d)
The perturbed SSH at month 1 is shown below:
There is a dipole pattern of SSH, with higher SSH in the west and lower SSH in the east, in response to a westward perturbation of wind stress at the Equator. This perturbation directly piles water in the west and pulls water away from the east because the Coriolis effect is zero at the Equator, preventing the deflection of water flow.
Method 2: Argument-based Input#
The detailed steps for Method 2 can be found in fgrd_viz.ipynb (see Tip above).
Load modules
import sys
sys.path.append('/efs_ecco/ECCO/EMU/emu_userinterface_dir/')
import emu_plot_arg_py as ept
import lib_python
Invoke Method 2
globals_dict = ept.emu_plot(run_name="/efs_ecco/owang/ECCO/EMU/tryout/emu_fgrd_7_15_743_5_-1.00E-01",
frequency='m',
pfile_beg=0, pfile_end=1000000,
pvar=1);
Found file: /efs_ecco/ECCO/EMU/emu_userinterface_dir/emu_env.singularity
EMU Input Files directory: /efs_ecco/ECCO/EMU/emu_input_dir
Specified directory of EMU run to examine: /efs_ecco/owang/ECCO/EMU/tryout/emu_fgrd_7_15_743_5_-1.00E-01
Reading /efs_ecco/owang/ECCO/EMU/tryout/emu_fgrd_7_15_743_5_-1.00E-01
Reading Forward Gradient Tool output ...
Detected
395 files of state_2d_set1_day.*.data
12 files of state_2d_set1_mon.*.data
12 files of state_3d_set1_mon.*.data
Choose variable to plot ...
1) SSH
2) OBP
3) THETA
4) SALT
5) U
6) V
Select monthly or daily mean ... (m/d)?
(NOTE: daily mean available for SSH and OBP only.)
Specified frequency 'm' for monthly or 'd' for daily: m
Specified start and end files #: 0 and 1000000
==> Reading and plotting monthly means ...
Specified variable # to plot: 2
Plotting ... OBP
***********************
EMU variables read as global variables in module global_emu_var (emu); e.g., emu.nx
***********************
cs drc drf dvol3d
dxc dxg dyc dyg
fgrd2d hfacc hfacs hfacw
nr nx ny rac
ras raw raz rc
rf sn xc xg
yc yg
Extract Data from Return Dictionary
return_vars_dict = globals_dict.get('return_vars')
fgrd2d_all = return_vars_dict['variable']
pinfo = 'SSH state_2d_set1_mon.0000000732.data scaled by 1.000000000e+03'
Make Plot
lib_python.plt_state2d(fgrd2d_all[0], pinfo)
Method 2 generates the same figure (see the second figure embedded in fgrd_viz.ipynb) as the one generated by Method 1.