FAQ: How can I output a variable that is part of the model but is not currently being written to the output netCDF files?

How can I output a variable that is part of the model but is not currently being written to the output netCDF files?

The following procedure for adding a variable to the output file should be followed. For instructional purposes, we will be looking to add the shortwave all-sky downward radiative flux.

• First, identify the variable that you want to output by scanning/searching scm/src/GFS_typedefs.meta. In this case, keywords like "shortwave" and "downwelling" and "surface" are probably the most relevant. Two standard names that I see are "surface_downwelling_shortwave_flux_on_radiation_time_step", "surface_downwelling_shortwave_flux". The first is in the GFS_coupling_type definition and the second is in the GFS_diag_type definition, which you can tell by scanning upward from where you found the variable until you find something like:

  [ccpp-arg-table]   
name = GFS_coupling_type   
type = ddt

  at the beginning of the section of variables containing your variable of choice. This information will come in handy in the next step. Let's choose the second variable because it is not defined on the radiation time step. It's local name in GFS_typedefs is dswsfci and we know that it is in the GFS_diag_type.

• As mentioned in section 4.6 of the SCM User's Guide, there are two subroutines in gmtb_scm_output.F90 that we'll need to modify: output_init() and output_append(). The first sets up the variables in the output netCDF file and the second actually writes (appends) the variable's instantaneous value to the output file. Let's initialize the variable in the output file first. For each variable that we want to write, we will want a NF90_DEF_VAR call to define the variable and at least two NF90_PUT_ATT calls to define its description and unit attributes. For the new variable, we could use:  

  CALL CHECK(NF90_DEF_VAR(NCID=ncid,NAME='dn_sw_flux_sfc',XTYPE=NF90_FLOAT,DIMIDS= (/ hor_dim_id, time_id /), VARID=dummy_id))
CALL CHECK(NF90_PUT_ATT(NCID=ncid,VARID=dummy_id,NAME="description",VALUES="downwelling_shortwave_flux_sfc"))
CALL CHECK(NF90_PUT_ATT(NCID=ncid,VARID=dummy_id,NAME="units",VALUES="W m-2"))

   

  You can append these lines to the end of the diagnostic variables already in that subroutine. Note that we're giving the variable a horizontal dimension which corresponds to the number of columns, typically 1. Since the variable is defined at the surface, there is no vertical dimension.

• Finally, let's modify the output_append subroutine in gmtb_scm_output.F90. This subroutine has access to any variables within the scm_state or physics derived datatypes. The variable that we want to output is in the physics derived datatype (where all variables defined in GFS_typedefs.F90 are). We will need to find the variable’s netCDF variable-ID with a NF90_INQ_VARID call (passing in whatever name we called it in the output_init subroutine) and put the variable in the file with a NF90_PUT_VAR call. At this point, we will need the information obtained in step 1 that lets us know how to access the memory with values that actually get written out. In this case, we know that it is in the GFS_diag_type and has a local name of dswsfci. The output routine has access to all variables in the physics type defined in gmtb_scm_type_defs.F90. In the physics type, the GFS_Diag_type variable is called Diag. So now we can string together the right names to find it within the nested derived types: physics%Diag%dswsfci. This is what we will write out.

  CALL CHECK(NF90_INQ_VARID(NCID=ncid,NAME="dn_sw_flux_sfc",VARID=var_id))
CALL CHECK(NF90_PUT_VAR(NCID=ncid,VARID=var_id,VALUES=physics%Diag%dswsfci(:),START=(/1,scm_state%itt_out /)))

After compilation and running the model, you can double-check that the variable is indeed written out using 

ncdump -v name_of_your_new_output_variable path/to/your/output.nc