Energy_transport_diag: Adding energy transport diagnostics

[andrearosendahl]

Added formulas for calculating different parts of the atmospheric energy transport, so they can be outputted when running NorESM3.

Contributors: Andrea Rosendahl @andrearosendahl

Reviewers: @gold2718

Purpose of changes:

Github PR URL: #247

Changes made to build system: None

Changes made to the namelist: None

Changes to the defaults for the boundary datasets: None

Substantial timing or memory changes: None

Test run to verify that I am able to see the new diagnostics: /cluster/work/users/andrear/n1850.ne16pg3_tn14.noresm3_0_beta03b.entrans.2025-11-28

To have the option of outputting 5 atmospheric meridional energy transport variables.
Top of README.case:
./create_newcase --case /cluster/work/users/andrear/n1850.ne16pg3_tn14.noresm3_0_beta03b.entrans.2025-12-04 --compset 1850_CAM70%LT%NORESM%CAMoslo_CLM60%FATES-NOCOMP_CICE_BLOM%HYB%ECO_MOSART_DGLC%NOEVOLVE_SWAV_SESP --res ne16pg3_tn14 --project nn9560k --machine betzy --compiler intel --run-unsupported --user-mods-dir /cluster/work/users/andrear/NorESM_3_0_beta03b/cime_config/usermods_dirs/reduced_out_devsim/

user_nl_cam:
! Users should add all user specific namelist changes below in the form of
! namelist_var = new_namelist_value

use_aerocom = .false.
interpolate_nlat = 96
interpolate_nlon = 144
interpolate_output = .true.,.true.
history_aerosol = .false.
zmconv_c0_lnd = 0.0075D0
zmconv_c0_ocn = 0.0075D0
zmconv_ke = 5.0E-6
zmconv_ke_lnd = 1.0E-5
clim_modal_aero_top_press = 1.D-4
bndtvg = '/cluster/shared/noresm/inputdata/atm/cam/ggas/noaamisc.r8.nc'
dust_emis_method = 'Leung_2023'
dust_emis_fact = 6.1D0
rafsip_on = .true.
micro_mg_dcs = 700.D-6
clubb_c8 = 4.8
nhtfrq = 0, -24
mfilt = 1, 30
ndens = 2, 2
fincl1 = 'IntHeatTr', 'PotEnerTr', 'LatHeatTr', 'KinEnerTr', 'TotEnerTr'
fincl2 = 'Z500', 'T850', 'U850', 'V850'

[adagj]

@andrearosendahl @gold2718

I compared the output from Andrea's n1850.ne16pg3_tn14.noresm3_0_beta03b.entrans.2025-11-28 simulation to a NorESM2-LM simulation (orange), and the results look reasonable

I will suggest to give the variable names more useful names, maybe:

TotEnergy = total energy transport
LatHeat = latent energy/heat transport
PotEner = potential energy transport
KinEner = kinetic energy transport
IntHeat = internal energy transport

or

TotEnerTr = total energy transport
LatHeatTr = latent energy/heat transport
PotEnerTr = potential energy transport
KinEnerTr = kinetic energy transport
IntHeatTr = internal energy transport

[andrearosendahl]

I like the first option best I think, but happy with both suggestions.

[adagj]

@andrearosendahl Can you update this PR with new names? I think the second suggestion indicates that it is not the energy in itself, but the transport. Maybe good to include? However, both will work. Great to get this in. Thanks!

[andrearosendahl]

True, I'll update the PR with the second option then.

[adagj]

@gold2718 I hope you can review as well - I'm happy with this

[gold2718]

@andrearosendahl, have you run a test with the new names to make sure they come out correctly?
Also, since these fields are not the default anywhere, can you add them to a new history file in a test?
I suggest modifying <cam>/cime_config/testdefs/testmods_dirs/cam/outfrq9s_aero_history/user_nl_cam Something like adding:

fincl3 = 'IntHeatTr:I', 'PotEnerTr:I', 'LatHeatTr:I', 'KinEnerTr:I', 'TotEnerTr:I'

to the bottom of the file. That way, they will show up (and be protected) in our regression test suite.

[andrearosendahl]

How do I run a test with this new history file? I am creating a new case now with the new names in the user_nl_cam list

[adagj]

How do I run a test with this new history file? I am creating a new case now with the new names in the user_nl_cam list

Yes, that is a clean way to test. You don't need a long simulation. A month is probably sufficient.

[andrearosendahl]

New case with the new variable names tested here: /cluster/work/users/andrear/n1850.ne16pg3_tn14.noresm3_0_beta03b.entrans.2025-12-04

I also added the names in a new history file as you suggested above @gold2718

[gold2718]

I have a few suggestions on what to change. Some is cleanup and some so that CAM is not slowed down when these diagnostic fields are not being output.
There is more potential optimization we can look at after this is done.

[gold2718]

Please remove these commented-out outfld calls (here and below). Currently, there are no addfld calls for them and we can add 3-D fields later if desired.

[gold2718]

The ftem calculation is fairly expensive and should only be done if IntHeatTr will be output. Please implement that as shown in this suggestion (and also below with the appropriate history field names).

Suggested change

	ftem(:ncol,:) = (cpair*state%t(:ncol,:)*state%v(:ncol,:))*(state%pdel(:ncol,:)/gravit)
	!call outfld ('INTEnTrans', ftem(:ncol,:) ,ncol ,lchnk )
	!! vertically integrate
	ftem3(:ncol)=ftem(:ncol,1)
	do k=2,pver
	ftem3(:ncol) = ftem3(:ncol) + ftem(:ncol,k)
	end do
	call outfld ('IntHeatTr', ftem3(:ncol), ncol ,lchnk)
	if (hist_field_active('INTEnTrans')) then
	ftem(:ncol,:) = (cpair*state%t(:ncol,:)*state%v(:ncol,:))*(state%pdel(:ncol,:)*rga)
	!call outfld ('INTEnTrans', ftem(:ncol,:) ,ncol ,lchnk )
	!! vertically integrate
	ftem3(:ncol)=ftem(:ncol,1)
	do k=2,pver
	ftem3(:ncol) = ftem3(:ncol) + ftem(:ncol,k)
	end do
	call outfld ('IntHeatTr', ftem3(:ncol), ncol ,lchnk)
	end if

Note that I also replaced dividing by gravit with multiplication by rga which is simply 1/gravit. This is because multiplication is a lot faster than division.

[gold2718]

The gravit terms cancel out here so this can just be:

Suggested change

	ftem(:ncol,:) = (gravit*z3(:ncol,:)*state%v(:ncol,:))*(state%pdel(:ncol,:)/gravit)
	ftem(:ncol,:) = z3(:ncol,:)*state%v(:ncol,:)*state%pdel(:ncol,:)