Guidelines for coding projects and use of models

1
Guidelines for coding projects and use of models
(or, How to make your life easier in the long
run)
1 September 2009
2
Guiding philosophies of this advice
I. A good model code is easy to read and trouble
shoot you can find what youre looking for
quickly and you can see what each line of code is
supposed to be doing
II. A good model code preserves forward
compatibility, so that as we add new features, we
dont have to reinvent the wheel
3
1/2 to 2/3 of all problems can be headed off so
easily!
1a. Alert yourself to typos in variable names
Start every program and subroutine with
IMPLICIT NONE
1b. Alert yourself to array overruns and avoid
segmentation faults Use array bounds
checking when compiling
pgf90 Mbounds gfortran fbounds-check ifort
check bounds
4
2. Define physical constants and model
configurations in parameter statements, not in
the body of the code!
INTEGER, PARAMETER NT1000
This prevents accidental overwriting of a
variable somewhere else in the code
5
3. Determine whether a variable needs to be an
integer, a single precision real, or a double
precision real, and declare it properly
INTEGER, PARAMETER NT1000
REAL, PARAMETER DT2.0
DOUBLE PRECISION, PARAMETER
PI3.14159265359D00
6
4. STUDENT SUGGESTION FROM LAST YEAR It is a
good idea to set all variables to zero at the top
of your code, before starting computations.
(Eventually, you will assign other non-zero
values to fields of interest, but this zero-ing
helps ensure that nothing funny is going on, and
often can help you troubleshoot your code)
7
5a. STUDENT SUGGESTION FROM LAST YEAR Some
FORTRAN-90 compilers require files to have a
suffix of .f90 or .F
(or else they will revert to
FORTRAN-77). Be safe and use this convention!
5b. STUDENT SUGGESTION FROM LAST YEAR If you
write code on a DOS/Windows-emulating terminal
and then transfer or paste it onto a Linux
machine, be aware that some Linux text editors
will retain the hidden (in Windows) M
line-break characters at the ends of lines most
compilers will choke on this.
8
6. Remember that for many compilers, the product
of two kinds of variables is restricted by the
less precise variable
INTEGER I REAL A REAL B I2 A2.2 BAI
BAREAL(I)
B may be 4 on some compilers
(On many compilers, IMPLICIT NONE alleviates this
problem)
9
7. Comment your code heavily!
Our goal in this class is to understand every
line of code in our model believe it or not, in
a week or a month, you will forget why you coded
something in a particular way, or you will forget
what a particular line of code is meant to do.
10
8. Call your variables and subroutines by names
that bring to mind what they represent!
We all like to save keystrokes and keep our code
compact, but which of these is unambiguous?
EPS
EPSILON
ASSELINCOEF
11
9. Similarly, make your calculations look like
the equations youre trying to represent
Often its possible to really combine and
condense a lot of coefficients into one compact
variable
GAMMA K DT / DX2.
Models do this to save on the number of
calculations but, when you are trying to modify
a line later in the code (or debug it, or base
another line off of it) you will have to go back
and figure out where the compact variable is
defined, whether it is defined correctly, whether
it needs to be modified for a new application,
etc.
12
10. Continuing the theme dont use a bunch of
temporary/dummy variables for multiple things at
various points in the code
! Condense excess vapor from parcel DUM
QVSLV17.27237.0/(CP (TEMP-36.0)2) DUM
(QVPAR-QVS)/(1DUM) QVPAR QVPAR -
MAX(DUM,0.0)
And later
! Check for parcel buoyancy DUMPTPAR-PTENV IF(D
UM.GE.0.0) CAPE CAPE GDZDUM/PTENV
Some models do this to save on RAM but, when
you are trying to modify a line (or debug it, or
base another line off of it) you will have the
problems previously mentioned. In addition, when
you look at a random line of code, you cant be
sure of what the dummy variable means!
13
11. A two-level time scheme (e.g. forward
scheme) only requires the time dimension of the
arrays to be 2 (not NT)
INTEGER, PARAMETER NX100 INTEGER, PARAMETER
NT10000 REAL, DIMENSION(NX,NT) PSI INTEGER
I INTEGER N ! Omit the initial condition
statements for now DO N1,NT DO
I1,NX PSI(I,N1)PSI(I,N) forcingPSI(I,N)
ENDDO ENDDO
14
11. A two-level time scheme (e.g. forward
scheme) only requires the time dimension of the
arrays to be 2 (not NT)
INTEGER, PARAMETER NX100 INTEGER, PARAMETER
NT10000 REAL, DIMENSION(NX) PSIC !
Current REAL, DIMENSION(NX) PSIF !
Future INTEGER I INTEGER N ! Omit the
initial condition statements for now DO
N1,NT PSICPSIF DO I1,NX PSIF(I)PSIC(I)
forcingPSIC(I) ENDDO ENDDO
Only practical approach for long simulations!
(RAM)
15
12. Obviously, this requires writing output
during the run (not waiting until the very end)
! Omit the declaration statements for now ! Omit
the initial condition statements for now DO
N2,NT TIMENOWREAL(N-1)DT PSIPPSIC PSICPSIF
DO I2,NX PSIF(I)PSIP(I)
forcingPSIC(I) ENDDO ! if it's time, dump
output IF(TIMENOW.GE.THISDUMP) THEN CALL
GRADSHISTORYDUMP ! set next time for output
THISDUMP THISDUMP DTOUTPUT ENDIF ENDDO
16
13. In the atmosphere, all processes happen
simultaneously in the model, they must happen in
a certain order. In short, think about the logic
of what youre coding you cant just put things
anywhere you want!
Example what is the correct order for these
processes in a model?
1
2
Predict dry change in temperature
Compute saturation mixing ratio
4
3
Update water vapor for evap/cond
Update temperature for evap/cond
17

• DEBUGGING!
• The first step to tracking down problems is
  always to add PRINT statements to your code!
• The second step is to add even more PRINT
  statements to your code!
• Check all relevant variable values at
  intermediate waypoints make sure youre
  passing/receiving and calculating what you think
  you are!
• Narrow down the location of the problem
• Make sure you are actually passing the IF checks
  you think you should
• Etc.

18
15. ADVANCED TOPIC
Use compartmentalized
code A. Creating a driver code and using
modules B. Breaking your code up into
meaningful files i) Declaring everything in
one place ii) Compiling a group of files and
modules
19
Breaking your code up into meaningful
files -Declaring everything in one place
declarations.f90
20
Breaking your code up into meaningful
files -Declaring everything in one place -
MODULE and USE
declarations.f90
21
Breaking your code up into meaningful
files -Declaring everything in one place -
MODULE and USE
base.f90
22
Recall creating a driver code and using
subroutines
So, each subroutine is called in order, but we
dont have to pass a large number of
variables Instead, each subroutine begins with
the USE statement(s)!
23
So, each subroutine is called in order, but we
dont have to pass a large number of
variables Instead, each subroutine begins with
the USE statement(s)!
24
Breaking your code up into meaningful
files -Compiling a group of files
Your model code can become quite long(the last
time I did this project, the 2D model driver with
simple microphysics was 1707 lines, excluding all
declarations)
Why not break the subroutines up, too?
All subroutines related to main driver
modeldriver.F
All subroutines related to initial conditions
init.F
All subroutines related to boundary conditions
boundaries.F
All subroutines related to writing out data
writeout.F
All subroutines related to main integration
integration.F
25
-Compiling a group of .f90 files -Dependencies
of USE/MODULE groups

• Use the Unix make utility

Makefile
26
A closer look at
Makefile
--- the Unix shell to use
--- a comment
27
A closer look at
Makefile
--- the f90 compiler command
--- a list of the files containing the main
model subroutines, but not the MODULEs
28
A closer look at
Makefile
The Makefile helps us manage dependencies
associated with MODULEs.
compile it all ---
make archive---
move archive---
--- join all of the individual subroutine files
--- compile all subroutines
--- compile the declarations module
--- compile the user_settings module
When it is time to start introducing MODULEs into
our CMM code, I will distribute another handout
with more information.
29
A closer look at
Makefile
to compile the model, simply put this Makefile in
the same directory where your code is, and then
type make at the Unix prompt!
30
A closer look at
Makefile
to clean things up a bit, type make clean at the
Unix prompt!