Budget Tool#

The Budget (budg) Tool evaluates contributions of variables and fluxes underlying the budget of a user-specified quantity.

In this tutorial, we demonstrate how to use the Budget Tool to obtain the heat budget of the upper 10 m of the Niño 3.4 region (5°S-5°N, 170°W-120°W). We then show how to plot some of the results.

Run Budget Tool#

We start EMU (see, e.g., Adjoint Tool) and choose the Budget Tool by entering 6.

choice is 6) Budget Tool (budg)
See /efs_ecco/ECCO/EMU/emu_userinterface_dir/README_budg
 
************************************
    EMU Budget Tool (singularity) 
************************************
 
**** Step 1: Tool Setup
     Running setup_budg.sh
 
... Setting up ECCO V4r4 Budget Tool ...
 
 
**** Step 2: Specification
     Running budg.x
By default, tool will sample EMU reference run from state files in directory 
/efs_ecco/ECCO/EMU/emu_input_dir/emu_ref/diags
 
Press Enter to continue or enter an alternate directory if sampling another run ... ?

We choose the default directory where ECCO V4r4 diagnostic output is saved by typing Enter key.

 ... sampling default EMU reference run.
     Running budg.x
 inputdir read : /emu_input_dir
 srcdir read : /inside_alt

Extracting budget time-series ... 

 Define budget variable ... 
 Available VARIABLES are ... 
    1) Volume (m^3)
    2) Heat (theta) (degC)
    3) Salt (PSU)
    4) Salinity (PSU)
   ==> Budget is MONTHLY ... 

------------------
   Choose budget variable (v in Eq 1 of Guide)  ... (1-5)?

We enter 2 to choose the heat budget.

   Budget variable  is Heat (theta)

 Choose budget for a single model grid point (1) or 
          over a larger volume (2) ... (1/2)?

Then, we enter 2 to calculate the heat budget over a 3d volume, i.e., the upper 10 m of the Niño 3.4 region, and choose to specify a lat/lon/depth volume by entering 1. We are prompted to specify the spatial range, for which we enter -170, -120, -5, 5, 10, and 0, as done in the Tracer Tool. The configuration is now complete.

 ... Budget will be over a volume

Choose either a lat/lon/depth volume (1) or 
    a volume specified in a user-provided file (2) ... (1/2)?
 (user file must be in model's native binary format)
 ... Budget will be over a lat/lon/depth volume
 Enter west most longitude (-180E to 180E)... x1?
-170
 Enter east most longitude (-180E to 180E)... x2?
    (choose x2=x1 for zonally global volume) 
-120
 Enter south most latitude (-90N to 90N)... y1?
-5
 Enter north most latitude (-90N to 90N)... y2?
5
 Enter deepest depth (0-6000m) ... z1?
10
 Enter shallowest depth (0-6000m)... z2?
0
   min/max longitude   -170.0  -120.0
   min/max latitude     -5.0     5.0
   min/max depth     10.0     0.0

Budget Tool output will be in : emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0

... Done budg setup of data.ecco

 
**** Step 3: Calculation
     Running do_budg.x
... Submitting batch job pbs_budg.sh  
    to compute the budget.
 
    Estimated wallclock time:
#SBATCH --ntasks-per-node=36
Submitted batch job 826
 
********************************************
    Results will be in emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0/output
********************************************
 

EMU interactive execution complete. Fri Oct  4 20:20:34 UTC 2024

The run name is emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0.

Visualize Budget Tool Results#

Using the Budget Tool results, we will plot various budget terms and their time integrals.

Tip

A Jupyter Notebook, budg_viz (after downloading, rename it to budg_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, /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0), and then it will generate 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 ... ?

When prompted for the directory of EMU run, we and enter emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0 with the full path if needed.

Reading /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0

Reading Budget Tool output ... 
*********************************************
Read sum of heat budget variables 
   budg_tend: tendency time-series (per second)
   budg_tend_name: name of variables in budg_tend
from file /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0/output/emu_budg.sum_tend

*********************************************
Read sum of heat budget variables
   budg_tint: time-integrated tendency time-series
   budg_tint_name: name of variables in budg_tint
from file /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0/output/emu_budg.sum_tint

*********************************************
Read 3D masks emu_budg.msk3d_* that describe the spatial location
and direction (+/- 1) of the converging fluxes budg_mkup.
   budg_msk: list of dictionaries, each describing a 3D mask
      budg_msk[n]["msk"]: name (location) of mask n
      budg_msk[n]["msk_dim"]: dimension of mask n (n3D)
      budg_msk[n]["f_msk"]: weights (direction) of mask n
      budg_msk[n]["i_msk"]: i-index of mask n
      budg_msk[n]["j_msk"]: j-index of mask n
      budg_msk[n]["k_msk"]: k-index of mask n
The number of different masks (dictionaries) is len(budg_msk)

*********************************************
Read converging fluxes from files emu_budg.mkup_*
(budget makeup)
   budg_mkup: list of class objects, each describing a particular flux
      budg_mkup[n].var: name of flux n
      budg_mkup[n].msk: name (location) of corresponding mask
      budg_mkup[n].isum: term in emu_budg.sum_tend that this flux (n) is summed in
      budg_mkup[n].mkup_dim: spatial dimension of budg_mkup[n]["mkup"]
      budg_mkup[n].mkup: flux time-series
   budg_nmkup: number of different fluxes
               Same as len(budg_mkup)

The plotting tool processes the output of the Budget Tool, which includes contributions from different terms, and generates a figure as shown below:

Budget Tool plots

The top two panels show the time series of heat tendency terms (top left) and their time integral (top right). The black, red, and cyan curves represent the terms from the left-hand side (LHS), the right-hand side (RHS), and the difference, respectively. The difference is zero, confirming that the budget is closed.

Panels [2,1], [2,2], [3,1], [3,2], and [4,1] show contributions due to horizontal advection, horizontal mixing, vertical advection, horizontal mixing, and surface forcing, respectively. The black and red curves use two different methods to compute these contributions. The two methods produce the same results, as the difference (cyan) is zero.

Panel [4,2] shows the heat tendency term (black) and its components, including advection (red), mixing (cyan), and surface forcing (green). Forcing and mixing are the two largest terms. Panels [5,1] and [5,2] are the same as Panel [4,2], but for time integrals. The difference between Panels [5,1] and [5,2] is that the latter does not include the trend. Forcing and mixing are also the two largest terms in Panels [5,1] and [5,2].

Method 2: Argument-based Input#

The detailed steps for Method 2 can be found in budg_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 plot_budg
  • Invoke Method 2

# Budget Tool
globals_dict = ept.emu_plot(run_name="/efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0")
Found file: /efs_ecco/ECCO/EMU/emu_userinterface_dir/emu_env.singularity
EMU Input Files directory: /efs/owang/ECCO/EMU_test/emu_input_dir

Specified directory of EMU run to examine: /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0

Reading /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0

Reading Budget Tool output ... 
*********************************************
Read sum of heat budget variables 
   budg_tend: tendency time-series (per second)
   budg_tend_name: name of variables in budg_tend
from file /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0/output/emu_budg.sum_tend

*********************************************
Read sum of heat budget variables
   budg_tint: time-integrated tendency time-series
   budg_tint_name: name of variables in budg_tint
from file /efs_ecco/owang/ECCO/EMU/tryout/emu_budg_m_2_-170.0_-120.0_-5.0_5.0_10.0_0.0/output/emu_budg.sum_tint

*********************************************
Read 3D masks emu_budg.msk3d_* that describe the spatial location
and direction (+/- 1) of the converging fluxes budg_mkup.
   budg_msk: list of dictionaries, each describing a 3D mask
      budg_msk[n]["msk"]: name (location) of mask n
      budg_msk[n]["msk_dim"]: dimension of mask n (n3D)
      budg_msk[n]["f_msk"]: weights (direction) of mask n
      budg_msk[n]["i_msk"]: i-index of mask n
      budg_msk[n]["j_msk"]: j-index of mask n
      budg_msk[n]["k_msk"]: k-index of mask n
The number of different masks (dictionaries) is len(budg_msk)

*********************************************
Read converging fluxes from files emu_budg.mkup_*
(budget makeup)
   budg_mkup: list of class objects, each describing a particular flux
      budg_mkup[n].var: name of flux n
      budg_mkup[n].msk: name (location) of corresponding mask
      budg_mkup[n].isum: term in emu_budg.sum_tend that this flux (n) is summed in
      budg_mkup[n].mkup_dim: spatial dimension of budg_mkup[n]["mkup"]
      budg_mkup[n].mkup: flux time-series
   budg_nmkup: number of different fluxes
               Same as len(budg_mkup)


***********************
EMU variables read as global variables in module global_emu_var (emu); e.g., emu.nx
***********************
budg_mkup           budg_msk            budg_nmkup          budg_tend           
budg_tend_name      budg_tint           budg_tint_name      cs                  
drc                 drf                 dvol3d              dxc                 
dxg                 dyc                 dyg                 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')
  • Make plot

tt = return_vars_dict['time_values']
lhs_tend = return_vars_dict['lhs_tendency']
rhs_tend = return_vars_dict['rhs_tendency']
lhs_tint = return_vars_dict['lhs_tendency_time_integral']
rhs_tint = return_vars_dict['rhs_tendency_time_integral']
emu_tend = return_vars_dict['emu_tend']
adv_tend = return_vars_dict['adv_tendency']
mix_tend = return_vars_dict['mix_tendency']
frc_tend = return_vars_dict['frc_tendency']
adv_tint = return_vars_dict['adv_tendency_time_integral']
mix_tint = return_vars_dict['mix_tendency_time_integral']
frc_tint = return_vars_dict['frc_tendency_time_integral']
budg_mkup = return_vars_dict['list_flux_obj']
nvar = return_vars_dict['total_num_var']
fbudg = return_vars_dict['budg_quantity']
ibud = return_vars_dict['budg_quantity_idx']
nmonths = return_vars_dict['num_months']
emu_tend_name = return_vars_dict['budg_tend_name']
nmkup = return_vars_dict['num_flux']

# Create the figure
plot_budg.create_budg_fig(tt, lhs_tend, rhs_tend, lhs_tint, rhs_tint, emu_tend, \
            adv_tend, mix_tend, frc_tend, \
            adv_tint, mix_tint, frc_tint, \
                budg_mkup, \
                    nvar, fbudg, ibud, nmonths, emu_tend_name, \
                        nmkup)

Method 2 generates the same figure (not shown; see the second figure embedded in budg_viz.ipynb) as that generated by Method 1.