1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
<html>
<body BGCOLOR="FFFFFF">
<h1>Docs: Code Management</h1>
In this file we list
some of the techniques that may be used to increase one's
efficiency when developing PETSc application codes. We have learned to
use these techniques ourselves and they have improved our efficiency
tremendously.
<p align="center"><strong><big><big>Editing and Compiling</big></big></strong></p>
<p>The biggest time sink in code development is generally the
cycle of EDIT-COMPILE-LINK-RUN. We often see users working in a
single window with a cycle such as: </p>
<ul>
<li>Edit a file with VI. </li>
<li>Exit VI. </li>
<li>Run make and see some error messages. </li>
<li>Start VI and try to fix the errors; often starting VI hides
the error messages so that users cannot remember all of them
and thus do not fix all the compiler errors. </li>
<li>Run make generating a bunch of object (.o) files. </li>
<li>Link the executable (which also removes the .o files).
Users may delete the .o files because they anticipate compiling
the next time on a different machine that uses a different
compiler. </li>
<li>Run the executable. </li>
<li>Detect some error condition and restart the cycle. </li>
</ul>
<p>In addition, during this process the user often moves manually
among different directories for editing, compiling, and running.</p>
<p><font size="4"><strong>Several easy ways to improve the cycle:</strong></font> </p>
<ul>
<li>Work in two windows next to each other. </li>
<li>Keep the editor running all the time, rather than
continually exiting and entering it. </li>
<li>Organize directories so code is not scattered all over the
place. </li>
<li>Never use scripts to run makefiles. (This is a common trick
by people who have trouble getting make to do exactly what they
want.) Instead, learn a bit more about how PETSc uses make to
compile complicated application codes portably, quickly, and easily.</li>
<li>If an application generates lots of .o files, store them in
libraries (.a files), with names that indicate the type of
machine and optimization levels. For example, PETSc's libraries
are stored in the directory ${PETSC_DIR}/lib/lib${BOPT}/${PETSC_ARCH}/.
Thus, when switching to another machine that shares the same
file system, one does not have to remember to delete a bunch of
.o files and edit makefiles accordingly. </li>
<li>To alleviate the need for jumping between directories every
time a test run is made, store the executable in the directory
where it has been compiled when possible. </li>
</ul>
<p>Several PETSc authors worked previously for years using
exclusively VI for editing. We have found that EMACS improves one's
programming efficiency enormously. For example, </p>
<ul>
<li>EMACS has a feature to allow the user to compile using make
and have the editor automatically jump to the line of source
code where the compiler detects an error, even when not
currently editing the erroneous file.</li>
<li>The etags feature of EMACS enables one to search quickly
through a group of user-defined source files (and/or PETSc
source files) regardless of the directory in which they are
located. Etags usage tips (where M- denotes the "meta" key in EMACS):
<ul>
<li>To access the predefined PETSc tags in EMACS, type M-x
visit-tags-table and specify the file ${PETSC_DIR}/TAGS </li>
<li>To move to where a PETSc function is defined, enter M-.
This is useful for viewing manpages and locating source
code. </li>
<li>To search for a string and move to the first
occurrence, use M-x tags-search Then, to locate later
occurrences, type M-, In particular, this is useful for quickly
locating examples of usage of certain PETSc routines. </li>
<li>Another quite helpful command is M-x tags-query-replace
which replaces occurrences of a string hroughout all tagged
files (can retain any entries if desired); this enables quick
and painless revisions of source code, particularly when routines are
spread throughout many files and directories. </li>
</ul>
</li>
</ul>
<ul>
<li>Also, EMACS easily enables:
<ul>
<li>editing files that reside in any directory and
retaining one's place within each of them </li>
<li>searching for files in any directory as one attempts to
load them into the editor </li>
</ul>
</li>
</ul>
<p>Admittedly, it takes a while to get the hang of using EMACS.
But we've found that the increase in our programming efficiency has
been well worth the time spent learning to use this editor. We
seriously believe that we could not have developed PETSc as it is
today if we had not switched to EMACS. </p>
<p align="center"><strong><big><big><big>Debugging</big></big></big></strong></p>
<p>Most code development for PETSc codes should be done on one
processor; hence,using a standard debugger such as dbx, gdb, xdbx,
etc. is fine. For debugging parallel runs we suggest <strong>Totalview</strong>
if it is available on your machine. Otherwise, you can run each
process in a separate debugger; this is not the same as using a
parallel debugger, but in most cases it is not so bad. The PETSc,
the run-time options -start_in_debugger [-display xdisplay:0] will
open separate windows and debuggers for each process. You should
debug using the BOPT=g versions of the libraries.</p>
<p>It really pays to learn how to use a debugger; you will end up
writing more interesting and far more ambitious codes once it
is easy for you to track down problems in the codes.</p>
<p align="center"><font size="6"><strong>Other suggestions</strong></font></p>
<ul>
<li>Choose consistent and obvious names for variables and
functions. (Short variable names may be faster to type, but by
using longer names you don't have to remember what they
represent since it is clear from the name.) </li>
<li>Use informative comments. </li>
<li>Leave space in the code to make it readable. </li>
<li>Line things up in the code for readability. Remember that
any code written for an application will be visited <strong>over
and over</strong> again, so spending an extra 20 percent of
effort on it the first time will make each of those visits faster and
more efficient. </li>
<li>Realize that you <strong>will</strong> have to debug your
code. <strong>No one</strong> writes perfect code, so always write code
that may be debugged and learn how to use a debugger. In most
cases using the debugger to track down problems is much fast than using
print statements. </li>
<li><strong>Never</strong> hardwire a large problem size into
your code. Instead, allow a command line option to run a small
problem. We've seen people developing codes who have to wait 15
minutes after starting a run to reach the crashing point; this is an
inefficient way of developing code. </li>
<li>Develop your code on the simplest machine to which you have
access. We have accounts on IBM SPs, Cray T3D, Intel Paragon,
SGIs etc, but we write and initially test all our code on Sun
Sparcstations because the user interface is friendlier and the
turn-around time for compiling and running is much faster than
for the parallel machines. We only use the parallel machines
for large jobs. Since PETSc code is completely portable, switching to
the parallel machine from our Sun development environment simply means
logging into another machine -- there are no code or makefile
changes. </li>
<li>Never develop code directly on an MPP; your productivity
will be much lower than if you developed on a well-organized
workstation. </li>
<li>Keep your machines' operating systems and compilers
up-to-date (or force your systems people to do this :-). You
should always work with whatever tools are currently the best
available. It may seem that you are saving time by not spending the
time upgrading your system, but, in fact, your loss in
efficiency by sticking with an out-dated system is probably
larger than then the time required to keep it up-to-date. </li>
</ul>
<p align="center"><font size="6"><strong>Fortran notes</strong></font></p>
<p>Since Fortran77 does not provide type checking of routine
input/output parameters, we find that many errors encountered
within PETSc Fortran77 programs result from accidentally using
incorrect calling sequences. Thus, if your Fortran program is crashing,
one of the first things to check is that all subroutines are being
called with the correct arguments. Such mistakes are immediately
detected during compilation when using C/C++. Thus, using a mixture
of C/C++ and Fortran often works well for programmers who wish to
employ Fortran for the core numerical routines within their
applications. In particular, one can effectively write PETSc driver
routines in C/C++, thereby preserving flexibility within the
program, and still use Fortran when desired for underlying numerical
computations. </p>
<p>When passing floating point numbers into Fortran subroutines
always make sure you have them marked as double precision (e.g.,
pass in 10.d0 instead of 10.0). Otherwise, the compiler interprets
the input as a single precision number, which can cause crashes or
other mysterious problems. Make sure to declare all variables (do not
use the implicit feature of Fortran). In fact, we <strong>highly</strong>
recommend using the <strong>implicit none</strong> option at the
begining of each Fortran subroutine you write.</body>
</html>
|
