Adding a new routine to be called from several schemes

[lisa-bengtsson]

Hi! I wonder if anyone can help me out. I am looking to add a new routine that computes a prognostic convective area fraction. Up to this point I have kept the code for this inside of the routine samfdeefcnv.f (in my branch), but since I would like to use it also for shallow convection, and the code segment is some ~150 lines, I though it would be best to move it out to its own subroutine that could be called from both samfdeepcnv.f and samfshalcnv.f (and potentially later on any other cumulus scheme).

I have three questions;

1. what should the header be for such a file. I see one example in e.g. the file mfpbltq.f, is it possible to adapt a similar header and list two groups in \ingroup? E.g. both shallow and deep convection.

!>\file mfpbltq.f                                                                                                                              
!! This file contains the subroutine that calculates mass flux and                                                                             
!! updraft parcel properties for thermals driven by surface heating                                                                            
!! for use in the TKE-EDMF PBL scheme (updated version).                                                                                       

!>\ingroup satmedmfvdifq                                                                                                                       
!! This subroutine computes mass flux and updraft parcel properties for                                                                        
!! thermals driven by surface heating.                                                                                                         
!!\section mfpbltq_gen GFS mfpblt General Algorithm                                                                                            
!> @{

2. Does a .meta file have to be generated? I e.g don't see one for mfpbltq.f

3. is there a makefile (or similar) where this new routine needs to be added?

Thank you in advance,
Lisa

[grantfirl]

Hi Lisa,

Good question. I think that I can help.

The mfpbltq.f example that you gave is a good example of a dependency file used by one scheme only. Another good example for the situation that you described is the use of subroutines in the tridi module used by several different PBL schemes. It is perfectly fine to create a new file with code/subroutines (in a module please) and refer to that code in many schemes.

To answer your specific questions:

1. The Doxygen documentation that you listed is not technically necessary for the dependency to be used by schemes in the CCPP. It is nice to have documentation like you listed, however. The first stanza containing the \file tag is a way to provide a description for what is in the file. This is useful when searching the CCPP scientific documentation for files. The second stanza provides documentation for a particular subroutine. The \ingroup tag is helpful to associate a subroutine with its parent scheme. In your case, you would want to use the \ingroup SAMFdeep and \ingroup SAMF_shal tags in order to associate your subroutine with both. If you want to leave this out for now, it is fine. If your code needs to go into a release, we'll probably want to have the documentation blocks in place, but unless you know how to run the documentation generator, there's not really a way to know that your documentation blocks are working as expected.
2. No. You only need .meta files for the top level of a CCPP scheme. What you're describing is a dependency of an existing CCPP scheme.
3. You don't need to add the new file to a makefile (unless it needs special compilation flags), but you DO need to add it to the list of dependencies in the .meta files for whichever schemes import your new dependency. E.g. in samfdeepcnv.meta, at the top, you should see dependencies = .... Add your new file name to that list. When the CCPP code generator is run, it will grab the filenames of the dependencies that need to be compiled for a given suite.

[lisa-bengtsson]

Thank you very much @grantfirl !