5.3 Interfacing with Subprograms

An example may ease the process of learning to modify the template files and how to use the Developer's Interface to access the subprograms stored in the archive. Let's say that we want to compute the potential temperature for all times in our input file, but for some reason do not wish to use MetCal. Using the developer's interface, we would do the following.

1. Start a new project called ptmp by entering the command spaopen ptmp;
2. Enter the new directory using cd ptmp_f90;
3. Begin editing the ptmp.f90 file using our favourite text editor (ie xemacs, vi, etc);
4. Look for a potential temperature calculator in the SPA using either this manual or spalist (we find it as func_tttopt.f90);
5. Examine the subprogram header information to determine which module we need to include in the main program to access the potential temperature function (we use spainfo tttopt and find that it is part of the Thermodynamics module);
6. We now modify the template file (section 1) to use-associate the thermodynamics module by adding use Thermodynamics near the first MODIFY comment in the template (ptmp.f90);
7. Now we scroll down to the next MODFIY comment and find that we need to declare additional data arrays (the tt array is defined by default as an example) - to allow us to store our newly-computed potential temperature, we'll add the pt 3D array by modifying the declaration line to look like:

             real, dimension(:,:,:), allocatable :: tt,pt
        

8. Continuing on to the next MODIFY statement, we find that the timeLoop call will act on every time in the file, which is what we want so no changes are needed (see for a complete description of the other options available for looping);
9. The next MODIFY comment reminds us to allocate our working grids - since we added the 3D pt array, we need to add a new line containing something like: allocate(pt(ni,nj,nk));
10. Now we're ready to change the reads / writes and calls to suit our needs as indicated by the next MODIFY comment. First we check that we are reading all of the required data (we can check in again with spainfo tttopt if we've forgotten what needs to be provided). In this case, we're fine since all we need is temperature (the default) - make sure here that the name of the temperature variable (RPN Standard 'TT' by default) matches with the dataset. Under the Calculations here... comment, we add the call to the required function: pt = tttopt(tt,dim) and then modify the writeGrid call to output the potential temperature field. Something like: call writeGrid(output(1),pt,'PT',timer(t,:),dim) will work just fine;
11. That is all we need to do for the main program - now we just have to modify the well-documented settings.cfg file to provide the file format, and names of the input and output files;
12. Run comp90.d to generate the Makefile;
13. Run make ptmp to create the ptmp executable; and,
14. Run the ptmp executable to compute the potential temperature field.

Although this list may look daunting at the outset, such simple modifications can take as little as a minute once you become familiar with the SPA. The code that you have developed is now ready to handle any input file containing the defined temperature field in either RPN Standard or GEMPAK format without recompiling. Congratulations on your first development with the SPA.