https://doi.org/10.5281/zenodo.1414359 v1.0

"Energetics of the Southern Ocean Mode"
submitted to Journal of Geophysical Research: Oceans

Project Lorenz Energy Cycle (LEC)
by Andr\'e J\"uling, July 2018

Calculates and analyses Lorenz Energy Cycle (LEC) of a high resolution Parallel 
Ocean Program (POP) model run that showed OHC oscillations in the Southern Ocean 
(Le Bars, GRL 2016).

In addition to the LEC other quantities are analysed, such as 
  (a) the barotropic and overturning stream functions,
  (b) the mixed layer depths,
  (c) ocean heat content / temperature anaomalies.


================================================================================
Workflow for the LEC calculation
================================================================================

  (1) set up POP to write out required fields
      ajusted output fields in [advection_BY_JAN.f90]

  (2) calculate geometry files

  (3) run POP

  (4) calculate desired temporal averages (in our case: 5 years) as well as a 
      full run average (in our case: 51 years = one SOM cycle) [TAVG.f90]

  (5) analyse output:
      (a) [LEC.f90]
          to calculate all LEC terms plus kinetic energy advection;
          output is stored as 3D binary files and global integrals as text files
      (b) [analyze_LEC.f90]
          perform regional/phase integrals;
          output is stored as text files
      (c) [OSF_BSF.f90]
          calculates overturning and barotropic streamfunctions
      (d) [MXL.f90]
          calculates max MLD
      (e) [OHC.f90]
          calculates TMP anomaly

  (6) plotting
      (a) [LEC-paper-timeseries.py]
          time series
          Figure 1    : overturning/barotropic streamfunction, SOM index, max MLD
          Figure 10   : LEC components  
      (b) [LEC-paper-boxplots.py]
          Figure 3    : energy flow box plots
      (c) [LEC-paper-maps.py]
          Figure 2    : map of max MLD, depth-time temperature anomaly
          Figures 4-9 : polar maps of LEC components


================================================================================
/doc
================================================================================

[t.t0.1_42l_nccs01.007601.hdr]
- example of a file containing metadata of the original model output [12GB]

[t.t0.1_42l_nccs01.027601.hdr]
- example of full output metadata (necessary for LEC calculations) [56GB]

[LEC_bin.hdr]
- metadata for the derived LEC binary files

[pop_in]
- namelist provided to the POP model

[pop_in_and_meaning_parameters.pdf]
- explanations of parameters in pop_in

[start_run.sc ]
- script to start model run

[movie_contents / tavg_contents] 
- which field to output daily / monthly

================================================================================
/src
================================================================================

subfolders according to file types:
f90: "*.f90"  (Fortran)  for all computations and writing output
do : "do_*"   (cshell)   scripts to compile and execute Fortran programs
run: "run_*"  (bash)     scripts to run do scripts in parallel via sbatch
py : "*.py"   (python)   scripts and notebooks to analyse and plot results


================================================================================
/scr/f90: Programs
================================================================================

[TAVG.f90]
- time averaging of monthly output files
- subroutine files needed:
- output: time averaged binary files with same structure as original output files

[geometry.f90]
- does geometrical calculations from model files
- subroutine files needed:
- output: real binary files: (1) (imt,jmt,4+2*km) , 
                             (2) (6,km) depth dependent quantities

[ref_state.f90]
- creates reference background state from 51 year average file
- subroutine files needed:
    load_3D_field (5), state (6), area_avg(3), area_avg_weighted(3), vert_der(2)
- output: unformatted binary file '/input/ref_state' with these quantities:
          ! k, dz, tdepth, area, p,
          ! <T>, <S>, <RHO>, <PD>, <D(D,T,0)>, <D(D,T,p)>, <Q>,
          ! dz(<PD>), dz(<D(S,T,0)>), dz(<D(S,T,p)>)

[LEC.f90]
- calculates all LEC terms
- subroutine files needed:
- output: total/level terms, binary with LEC terms as 2D/3D fields
- takes about 3:20 mins to run for one file

[analyze_LEC.f90]
- surface/volume integrals over specific areas
- subroutine files needed:
- output: text files for each year with specific area/volume integrals of LEC terms
- takes a little less than 40 sec

[OSF_BSF.f90]
- overturning stream function and barotropic stream function
- import geometry file
- subroutine files needed: none
- output: (3,nt=251)       year,BSF drake, BSF Weddell gyre
          (imt,jmt,nt=251) yearly BSF fields, mean & std fields of last 51 years
          (jmt, km,nt=251) yearly OSF fields, mean & std fields of last 51 years
          in '/projects/0/samoc/jan/Andree/'//'OSF/' and //'BSF/' 
- uses run file and takes somewhat less than 7 hours

[MXL.f90]
- mixed layer depths (HMXL: mean, XMXL: maximum, TMXL: minimum)
- output: (imt,jmt,nt=251 years) 

[mer_adv.f90]
- meridional advection of energy reservoir terms
- subroutine files needed:
- output: (jmt,nt=51 years)

[int_test.f90]
- tests different integration methods
- subroutine files needed:
- output:
- takes about 30 sec

[WVEL_test.f90]
- tests whether the surface integrals of WVEL are 0
- output: 3 files for monthly, 5yr, and 51 yr average file with
          k, WVEL_sint(k), WVEL_sint_abs(k), TTT_WVEL_sint(k), TTT_WVEL_sint_abs(k)
          in 'results/WVEL_test/'
- takes 30 sec

[OHC_adv.f90]
- calculates heat advection across lon/lat stretches; for now along the
  boundaries of a box around the Weddell sinking region [-78S,-60S]x[35W,80E]
- output: /results/OHC_adv/
  - (imin:imax/jmin:jmax,km,nt=251yrs) 2D sections of heat transport across a 
    vertical plane along lat/lon
  - (imin:imax,nt) vertically integrated heat transport
  - (km,nt) zonally/meridionally integrated heat transport
- takes about 10 sec/month so in total 8.3 hours


================================================================================
/scr/f90: Subroutines
================================================================================

(1) [sub_calculations.f90]
       mer_advection      meridional advection
       osf                overturning stream function
(2) [sub_derivatives.f90]
       nabla_hvel         divergence of horizontal velocities
       grad_rho           density gradient
       vert_der           vertical derivative (for n0 calc.)
(3) [sub_integrals.f90]
       vol_int            volume-weighted integral using internal summation
       vol_int2           volume-weighted integral using Kahan summation
       surf_int           simple area-weighted surface integral
       area_avg           simple area-weighted level/area average
       area_avg_weighted  partial bottom cell depth weighted level/area average
       masked_avg         avg over mask (for MXL layer masked TEMP)
       vert_int           vertical integral (along k)
       zonal_int          "zonal" integral (along i)
(4) [sub_interpolation.f90]
       wtt2tt             WTT to TTT grid
       uu2tt              horizontal UU to TT grid weighted by DZU
       uu2tt_3d           calls uu2tt for 3d field
       uu2tt_scalar       like uu2tt but unweighted by DZU
       uu2tt_scalar_3D    same as uu2tt_3d for uu2tt_scalar
       interp_mom_fluxes  used for flux formulation approach
(5) [sub_model.f90]
       load_3D_field      loads 3D field from model output file
       load_2D_field      loads 2D field from model output file
       n/e/s/w_rshift     shifts array, used for geometry
(6) [sub_physics.f90]
       pressure           calculated the pressure [bar] at a given depth [m]
       state              calculates the potential density - rho_0 [g/cm^3]
                          (referenced to level k; rho_0=4.1/3.996*1000)

================================================================================
/results
================================================================================

[analyze_LEC/analysis_LEC_5_[year]_[region].out]
- results of analyse_LEC.f90

[SOM/POP_SOM_index.csv]
- SOM index file

[BSF_OSF/BSF_OSF.out]
- oversturning and barotropic streamfunction data


================================================================================
additional files:
================================================================================

model output files are 56GB per month and are consequently not stored here
the data is stroed on the Cartesius supercomputer at Surfsara (surfsara.nl)
access be requested from the authors or Michael Kliphuis (m.kliphuis(at)uu.nl)

derived files saved in /projects/0/samoc/jan/Andree include
- time averaged POP output files (monthly -> 1 year, 5 year, 11 year, 51 year)
- LEC fields, as binary fields
- cPK[m/e]_[1/5] files
- /MXL: mixed layer derived files
- /Psi: overturning stream function derived files