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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/codemanagement.html" />
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>Documentation: Code Management</title>
</head>
<body bgcolor="#ffffff">
<div id="version" align=right><b>petsc-3.4.2 2013-07-02</b></div>
<h1>Documentation: Code Management</h1>
<div id="main">
<p>
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>
<h2>Editing and Compiling</h2>
<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 <code>emacs</code>.</li>
<li>Exit <code>emacs</code>.</li>
<li>Run <code>make</code> and see some error messages.</li>
<li>
Start <code>emacs</code> and try to fix the errors; often starting
<code>emacs</code> hides the error messages so that users cannot
remember all of them and thus do not fix all the compiler errors.
</li>
<li>Run <code>make</code> 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>
<h2>Several easy ways to improve the cycle:</h2>
<ul>
<li>
<code>emacs</code> 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 <code>emacs</code> 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 <code>M-</code> denotes the "meta" key in <code>emacs</code>):
<ul>
<li>
To access the predefined PETSc tags in <code>emacs</code>, type
<code>M-x visit-tags-table</code> and specify the file
<code>${PETSC_DIR}/TAGS</code>
</li>
<li>
To move to where a PETSc function is defined, enter <code>M-.</code>
This is useful for viewing manpages and locating source code.
</li>
<li>
To search for a string and move to the first
occurrence, use <code>M-x tags-search</code> Then, to locate later
occurrences, type <code>M-,</code> In particular, this is useful for
quickly locating examples of usage of certain PETSc routines.
</li>
<li>
Another quite helpful command is <code>M-x tags-query-replace</code>
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>
<li>
Also, <code>emacs</code> 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 <code>emacs</code>.
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 <code>emacs</code>.
</p>
<p>
<code>vi</code> and <code>Eclipse</code> also provide tools for quickly finding things
and searching in PETSc source code, see the Emacs, VI/Vim and Eclipse
sections of the <a href="http://www.mcs.anl.gov/petsc/petsc-dev/docs/manual.pdf">users manual</a>.
<a href="http://gnu.org/s/global">GNU Global</a> is a richer alternative to
etags, see the user's manual for more details.<br>
</p>
<h2>Debugging</h2>
<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 <b>Totalview</b> 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 run-time options
<code>-start_in_debugger</code> [-display xdisplay:0] will open
separate windows and debuggers for each process. You should debug using
the debugging versions of the libraries (run ./configure with the
additional option --with-debugging (the default)).
</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>
<h2>Other suggestions</h2>
<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 <b>over and
over</b> 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 <b>will</b> have to debug your code.
<b>No one</b> 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 faster than using
print statements.
</li>
<li>
<b>Never</b> 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 a variety of large parallel machines, but we
write and initially test all our code on laptops or workstations
because the user interface is friendlier, and the turn-around time
for compiling and running is much faster than for the parallel
machines. We use the parallel machines only for large jobs. Since
PETSc code is completely portable, switching to a parallel machine
from our laptop/workstation development environment simply means
logging into another machine -- there are no code or makefile
changes.
</li>
<li>
Never develop code directly on a multi-node computing system; 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 outdated system
is probably larger than then the time required to keep it up-to-date.
</li>
</ul>
<h2>Fortran notes</h2>
<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.
</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 <b>highly</b> recommend
using the <b>implicit none</b> option at the begining of each
Fortran subroutine you write.
</p>
<p>
Fortran 90 provides the ability to do some type checking of subroutine
calls by using Fortran 90 interfaces or modules. PETSc now provides
interfaces and modules for Fortran 90; see the
<a href="manualpages/Sys/UsingFortran.html">manual page</a>
for how to use them.
</p>
</div>
</body>
</html>
|
