« back to all changes in this revision
Viewing changes to doc/user-ref.html
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Josselin Mouette
- Date: 2002-04-17 10:36:45 UTC
- Revision ID: james.westby@ubuntu.com-20020417103645-29vomjspk4yf4olw
Tags: upstream-2.1
Import upstream version 2.1
- files added:
- autom4te.cache
- base
- doc
- examples
- utils
added
removed
doc/user-ref.html
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2
<HTML><HEAD>
3
<TITLE>User Reference</TITLE>
4
<LINK rel="Bookmark" title="libctl Manual" href="index.html">
5
<LINK rel="Bookmark" title="Ab Initio Physics Home Page"
6
href="http://ab-initio.it.edu">
7
<LINK rel="Contents" href="index.html">
8
<LINK rel="Copyright" href="license.html">
9
<LINK rel="Start" href="index.html">
10
<LINK rel="Previous" href="advanced-user.html">
11
<LINK rel="Next" href="developer.html">
12
</HEAD>
13
<BODY TEXT="#000000" BGCOLOR="#FFFFFF">
14
15
Go to the <a href="developer.html">next</a>, <a
16
href="advanced-user.html">previous</a>, or <a href="index.html">main</a>
17
section.
18
<hr>
19
20
<h1>User Reference</h1>
21
22
In this section, we list all of the special functions provided for
23
users by libctl. We do <i>not</i> attempt to document standard Scheme
24
functions, with a couple of exceptions below, since there are plenty
25
of good Scheme references <a href="guile-links.html">elsewhere</a>.
26
27
<p>Of course, the most important function is:
28
29
<dl>
30
<dt><code>(help)</code>
31
<dd>Outputs a listing of all the available classes, their properties,
32
default values, and types. Also lists the input and output variables.
33
</dl>
34
35
<p>Remember, Guile lets you enter expressions and see their values
36
interactively. This is the best way to learn how to use anything that
37
confuses you--just try it and see how it works!
38
39
<h2>Basic Scheme functions</h2>
40
41
<dl>
42
43
<dt><code>(set! <i>variable value</i>)</code>
44
<dd>Change the value of <code><i>variable</i></code> to <code><i>value</i></code>.
45
46
<p><dt><code>(define <i>variable value</i>)</code>
47
<dd>Define new <code><i>variable</i></code> with initial <code><i>value</i></code>.
48
49
<p><dt><code>(list <i>[ element1 element2 ... ]</i>)</code>
50
<dd>Returns a list consisting of zero or more elements.
51
52
<p><dt><code>(append <i>[ list1 list2 ... ]</i>)</code>
53
<dd>Concatenates zero or more lists into a single list.
54
55
<p><dt><code>(<i>function [ arg1 arg2 ... ]</i>)</code>
56
<dd>This is how you call a Scheme <code><i>function</i></code> in general.
57
58
<p><dt><code>(define (<i>function [ arg1 arg2 ... ]</i>) <i>body</i>)</code>
59
<dd>Define a new <code><i>function</i></code> with zero or more
60
arguments that returns the result of given <code><i>body</i></code>
61
when it is invoked.
62
63
</dl>
64
65
<h2>Command-line parameters</h2>
66
67
<dl>
68
69
<dt><code>(define-param <i>name</i> <i>default-value</i>)</code>
70
<dd>Define a variable <code><i>name</i></code> whose value can be set
71
from the command line, and which assumes a value
72
<code><i>default-value</i></code> if it is not set. To set the value
73
on the command-line, include <code><i>name</i>=<i>value</i></code> on
74
the command-line when the program is executed. In all other respects,
75
<code><i>name</i></code> is an ordinary Scheme variable.
76
77
<p><dt><code>(set-param! <i>name</i> <i>new-default-value</i>)</code>
78
<dd>Like <code>set!</code>, but does nothing if
79
<code><i>name</i></code> was set on the command line.
80
81
</dl>
82
83
<h2>Complex numbers</h2>
84
85
<p>Scheme includes full support for complex numbers and arithmetic;
86
all of the ordinary operations (<code>+</code>, <code>*</code>,
87
<code>sqrt</code>, etcetera) just work. For the same reason, you can
88
freely use complex numbers in libctl's vector and matrix functions,
89
below.
90
91
<p>To specify a complex number <i>a</i>+<i>b</i>i, you simply use the
92
syntax <code><i>a</i>+<i>b</i>i</code> if <i>a</i> and <i>b</i> are
93
constants, and <code>(make-rectangular <i>a</i> <i>b</i>)</code>
94
otherwise. (You can also specify numbers in "polar" format
95
a*e<sup><small>ib</small></sup> by the syntax
96
<code><i>a</i>@<i>b</i></code> or <code>(make-polar <i>a</i>
97
<i>b</i>)</code>.)
98
99
<p>There are a few special functions provided by Scheme to manipulate
100
complex numbers. <code>(real-part <i>z</i>)</code> and
101
<code>(imag-part <i>z</i>)</code> return the real and imaginary parts
102
of <code><i>z</i></code>, respectively. <code>(magnitude
103
<i>z</i>)</code> returns the absolute value and <code>(angle
104
<i>z</i>)</code> returns the phase angle. libctl also provides a
105
<code>(conj <i>z</i>)</code> function, below, to return the complex
106
conjugate.
107
108
<h2>3-vector functions</h2>
109
110
<dl>
111
112
<dt><code>(vector3 <i>x [y z]</i></code>)
113
<dd>Create a new 3-vector with the given components. If the <code><i>y</i></code> or <code><i>z</i></code> value is omitted, it is set to zero.
114
115
<p><dt><code>(vector3-x <i>v</i>)</code>
116
<dt><code>(vector3-y <i>v</i>)</code>
117
<dt><code>(vector3-z <i>v</i>)</code>
118
<dd>Return the corresponding component of the vector <code><i>v</i></code>.
119
120
<p><dt><code>(vector3+ <i>v1 v2</i>)</code>
121
<dt><code>(vector3- <i>v1 v2</i>)</code>
122
<dt><code>(vector3-cross <i>v1 v2</i>)</code>
123
<dd>Return the sum, difference, or cross product of the two vectors.
124
125
<p><dt><code>(vector3* <i>a b</i>)</code>
126
<dd>If <code><i>a</i></code> and <code><i>b</i></code> are both
127
vectors, returns their dot product. If one of them is a number and
128
the other is a vector, then scales the vector by the number.
129
130
<p><dt><code>(vector3-dot <i>v1 v2</i>)</code>
131
<dd>Returns the dot product of <code><i>v1</i></code> and <code><i>v2</i></code>.
132
133
<p><dt><code>(vector3-cross <i>v1 v2</i>)</code>
134
<dd>Returns the cross product of <code><i>v1</i></code> and <code><i>v2</i></code>.
135
136
<p><dt><code>(vector3-cdot <i>v1 v2</i>)</code>
137
<dd>Returns the conjugated dot product: <i>v1</i>* dot <i>v2</i>.
138
139
<p><dt><code>(vector3-norm <i>v</i>)</code>
140
<dd>Returns the length <code>(sqrt (vector3-cdot v v))</code> of the
141
given vector.
142
143
<p><dt><code>(unit-vector3 <i>x [y z]</i></code>)
144
<dt><code>(unit-vector3 <i>v</i>)</code>
145
<dd>Given a vector or, alternatively, one or more components, returns a
146
unit vector in that direction.
147
148
<p><dt><code>(vector3-close? <i>v1 v2 tolerance</i>)</code>
149
<dt>Returns whether or not the corresponding components of the two
150
vectors are within <code><i>tolerance</i></code> of each other.
151
152
<p><dt><code>(vector3= <i>v1 v2</i>)</code>
153
<dt>Returns whether or not the two vectors are numerically equal.
154
Beware of using this function after operations that may have some
155
error due to the finite precision of floating-point numbers; use
156
<code>vector3-close?</code> instead.
157
158
<p><dt><code>(rotate-vector3 <i>axis theta v</i>)</code>
159
<dt>Returns the vector <code><i>v</i></code> rotated by an angle
160
<code><i>theta</i></code> (in radians) in the right-hand direction
161
around the <code><i>axis</i></code> vector (whose length is ignored).
162
You may find the functions <code>(deg->rad <i>theta-deg</i>)</code>
163
and <code>(rad->deg <i>theta-rad</i>)</code> useful to convert angles
164
between degrees and radians.
165
166
</dl>
167
168
<h2>3x3 matrix functions</h2>
169
170
<dl>
171
172
<dt><code>(matrix3x3 <i>c1 c2 c3</i>)</code>
173
<dd>Creates a 3x3 matrix with the given 3-vectors as its columns.
174
175
<p><dt><code>(matrix3x3-transpose <i>m</i>)</code>
176
<dt><code>(matrix3x3-adjoint <i>m</i>)</code>
177
<dt><code>(matrix3x3-determinant <i>m</i>)</code>
178
<dt><code>(matrix3x3-inverse <i>m</i>)</code>
179
<dd>Return the transpose, adjoint (conjugate transpose), determinant,
180
or inverse of the given matrix.
181
182
<p><dt><code>(matrix3x3+ <i>m1 m2</i>)</code>
183
<dt><code>(matrix3x3- <i>m1 m2</i>)</code>
184
<dt><code>(matrix3x3* <i>m1 m2</i>)</code>
185
<dd>Return the sum, difference, or product of the given matrices.
186
187
<p><dt><code>(matrix3x3* <i>v m</i>)</code>
188
<dt><code>(matrix3x3* <i>m v</i>)</code>
189
<dd>Returns the (3-vector) product of the matrix <code><i>m</i></code>
190
by the vector <code><i>v</i></code>, with the vector multiplied on the
191
left or the right respectively.
192
193
<p><dt><code>(matrix3x3* <i>s m</i>)</code>
194
<dt><code>(matrix3x3* <i>m s</i>)</code>
195
<dd>Scales the matrix <code><i>m</i></code> by the number
196
<code><i>s</i></code>.
197
198
<p><dt><code>(rotation-matrix3x3 <i>axis theta</i>)</code>
199
<dd>Like <code>rotate-vector3</code>, except returns the (unitary)
200
rotation matrix that performs the given rotation. i.e.,
201
<code>(matrix3x3* (rotation-matrix3x3 axis theta) v)</code> produces
202
the same result as <code>(rotate-vector3 axis theta v)</code>.
203
204
</dl>
205
206
<h2>Objects (members of classes)</h2>
207
208
<dl>
209
210
<dt><code>(make <i>class [ properties ... ]</i>)</code>
211
<dd>Make an object of the given <code><i>class</i></code>. Each
212
property is of the form <code>(<i>property-name
213
property-value</i>)</code>. A property need not be specified if it
214
has a default value, and properties may be given in any order.
215
216
<p><dt><code>(object-property-value <i>object property-name</i>)</code>
217
<dd>Return the value of the property whose name (symbol) is
218
<code><i>property-name</i></code> in <code><i>object</i></code>. For
219
example, <code>(object-property-value a-circle-object 'radius)</code>.
220
(Returns <code>false</code> if <code><i>property-name</i></code> is
221
not a property of <code><i>object</i></code>.)
222
223
</dl>
224
225
<h2>Miscellaneous utilities</h2>
226
227
<dl>
228
229
<dt><code>(conj <i>x</i>)</code>
230
<dd>Return the complex conjugate of a number <code><i>x</i></code>
231
(for some reason, Scheme doesn't provide such a function).
232
233
<dt><code>(interpolate <i>n list</i>)</code>
234
<dd>Given a <code><i>list</i></code> of numbers or 3-vectors, linearly
235
interpolates between them to add <code><i>n</i></code> new
236
evenly-spaced values between each pair of consecutive values in the
237
original list.
238
239
<dt><code>(print <i>expressions...</i>)</code>
240
<dd>Calls the Scheme <code>display</code> function on each of its
241
arguments from left to right (printing them to standard output). Note
242
that, like <code>display</code>, it does <em>not</em> append a newline
243
to the end of the outputs; you have to do this yourself by including
244
the <code>"\n"</code> string at the end of the expression list. In
245
addition, there is a global variable <code>print-ok?</code>,
246
defaulting to <code>true</code>, that controls whether
247
<code>print</code> does anything; by setting <code>print-ok?</code> to
248
false, you can disable all output.
249
250
<dt><code>(begin-time <i>message-string statements...</i>)</code>
251
<dd>Like the Scheme <code>(begin ...)</code> construct, this executes
252
the given sequence of statements one by one. In addition, however, it
253
measures the elapsed time for the statements and outputs it as
254
<code><i>message-string</i></code>, followed by the time, followed by
255
a newline. The return value of <code>begin-time</code> is the elapsed
256
time in seconds.
257
258
<p><dt><code>(minimize <i>function tolerance</i>)</code>
259
<dd>Given a <code><i>function</i></code> of one (number) argument,
260
finds its minimum within the specified fractional
261
<code><i>tolerance</i></code>. If the return value of
262
<code>minimize</code> is assigned to a variable <code>result</code>,
263
then <code>(min-arg result)</code> and <code>(min-val result)</code>
264
give the argument and value of the function at its minimum. If you
265
can, you should use one of the variant forms of <code>minimize</code>,
266
described below.
267
268
<dt><code>(minimize <i>function tolerance guess</i>)</code>
269
<dd>The same as above, but you supply an initial
270
<code><i>guess</i></code> for where the minimum is located.
271
272
<dt><code>(minimize <i>function tolerance arg-min arg-max</i>)</code>
273
<dd>The same as above, but you supply the minimum and maximum function
274
argument values within which to search for the minimum. This is the
275
most preferred form of <code>minimize</code>, and is faster and more
276
robust than the other two variants.
277
278
<p><dt><code>(minimize-multiple <i>function tolerance arg1 .. argN</i>)</code>
279
<dd>Minimize a <code><i>function</i></code> of N numeric arguments within the
280
specified fractional <code><i>tolerance</i></code>.
281
<code><i>arg1</i></code> .. <code><i>argN</i></code> are an initial
282
guess for the function arguments. Returns both the arguments and
283
value of the function at its minimum. A list of the arguments at the
284
minimum are retrieved via <code>min-arg</code>, and the value via
285
<code>min-val</code>.
286
287
<p><dt><code>maximize</code>, <code>maximize-multiple</code>
288
<dd>These are the same as the <code><i>minimize</i></code> functions
289
except that they maximizes the function instead of minimizing it. The
290
functions <code>max-arg</code> and <code>max-val</code> are provided
291
instead of <code>min-arg</code> and <code>min-val</code>.
292
293
<p><dt><code>(find-root <i>function tolerance arg-min arg-max</i>)</code>
294
<dd>Find a root of the given <code><i>function</i></code> to within
295
the specified fractional <code><i>tolerance</i></code>.
296
<code>arg-min</code> and <code>arg-max</code> <b>bracket</b> the
297
desired root; the function must have opposite signs at these two
298
points!
299
300
<p><dt><code>(derivative <i>function x [dx tolerance]</i>)</code>
301
<dt><code>(deriv <i>function x [dx tolerance]</i>)</code>
302
<dt><code>(derivative2 <i>function x [dx tolerance]</i>)</code>
303
304
<dd>Compute the numerical derivative of the given
305
<code><i>function</i></code> at <code><i>x</i></code> to within the
306
specified fractional <code><i>tolerance</i></code> (defaulting to the
307
maximum achievable tolerance), using Ridder's method of polynomial
308
extrapolation. <code><i>dx</i></code> should be a <i>maximum</i>
309
displacement in <code><i>x</i></code> for derivative evaluation; the
310
<code><i>function</i></code> should change by a significant amount
311
(much larger than the numerical precision) over
312
<code><i>dx</i></code>. <code><i>dx</i></code> defaults to 1% of
313
<code><i>x</i></code> or <code>0.01</code>, whichever is larger.
314
315
<p>If the return value of <code>derivative</code> is assigned to a
316
variable <code>result</code>, then <code>(derivative-df result)</code>
317
and <code>(derivative-df-err result)</code> give the derivative of the
318
function and an estimate of the numerical error in the derivative,
319
respectively.
320
321
<p>The <code>deriv</code> function is identical to
322
<code>derivative</code> except that it returns the derivative value
323
directly (no need to call <code>derivative-df</code>). The
324
<code>derivative2</code> function computes both the first and second
325
derivatives, using minimal extra function evaluations; the second
326
derivative and its error are then obtained by <code>(derivative-d2f
327
result)</code> and <code>(derivative-d2f-err result)</code>.
328
329
330
<p><dt><code>(fold-left <i>op init list</i>)</code>
331
<dd>Combine the elements of <code><i>list</i></code> using the binary
332
"operator" function <code><i>(op x y)</i></code>, with initial value
333
<code><i>init</i></code>, associating from the left of the list. That
334
is, if <code><i>list</i></code> consist of the elements <code>(<i>a b
335
c d</i>)</code>, then <code>(fold-left <i>op init list</i>)</code>
336
computes <code>(op (op (op (op init a) b) c) d)</code>. For example,
337
if <code><i>list</i></code> contains numbers, then <code>(fold-left +
338
0 <i>list</i>)</code> returns the sum of the elements of
339
<code><i>list</i></code>.
340
341
<p><dt><code>(fold-right <i>op init list</i>)</code>
342
<dd>As <code>fold-left</code>, but associate from the right. For
343
example, <code>(op a (op b (op c (op d init))))</code>.
344
345
</dl>
346
347
<hr>
348
Go to the <a href="developer.html">next</a>, <a
349
href="advanced-user.html">previous</a>, or <a href="index.html">main</a>
350
section.
351
352
</BODY>
353
</HTML>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1