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
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML><HEAD>
<TITLE>User Reference</TITLE>
<LINK rel="Bookmark" title="libctl Manual" href="index.html">
<LINK rel="Bookmark" title="Ab Initio Physics Home Page"
href="http://ab-initio.it.edu">
<LINK rel="Contents" href="index.html">
<LINK rel="Copyright" href="license.html">
<LINK rel="Start" href="index.html">
<LINK rel="Previous" href="advanced-user.html">
<LINK rel="Next" href="developer.html">
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF">
Go to the <a href="developer.html">next</a>, <a
href="advanced-user.html">previous</a>, or <a href="index.html">main</a>
section.
<hr>
<h1>User Reference</h1>
In this section, we list all of the special functions provided for
users by libctl. We do <i>not</i> attempt to document standard Scheme
functions, with a couple of exceptions below, since there are plenty
of good Scheme references <a href="guile-links.html">elsewhere</a>.
<p>Of course, the most important function is:
<dl>
<dt><code>(help)</code>
<dd>Outputs a listing of all the available classes, their properties,
default values, and types. Also lists the input and output variables.
</dl>
<p>Remember, Guile lets you enter expressions and see their values
interactively. This is the best way to learn how to use anything that
confuses you--just try it and see how it works!
<h2>Basic Scheme functions</h2>
<dl>
<dt><code>(set! <i>variable value</i>)</code>
<dd>Change the value of <code><i>variable</i></code> to <code><i>value</i></code>.
<p><dt><code>(define <i>variable value</i>)</code>
<dd>Define new <code><i>variable</i></code> with initial <code><i>value</i></code>.
<p><dt><code>(list <i>[ element1 element2 ... ]</i>)</code>
<dd>Returns a list consisting of zero or more elements.
<p><dt><code>(append <i>[ list1 list2 ... ]</i>)</code>
<dd>Concatenates zero or more lists into a single list.
<p><dt><code>(<i>function [ arg1 arg2 ... ]</i>)</code>
<dd>This is how you call a Scheme <code><i>function</i></code> in general.
<p><dt><code>(define (<i>function [ arg1 arg2 ... ]</i>) <i>body</i>)</code>
<dd>Define a new <code><i>function</i></code> with zero or more
arguments that returns the result of given <code><i>body</i></code>
when it is invoked.
</dl>
<h2>Command-line parameters</h2>
<dl>
<dt><code>(define-param <i>name</i> <i>default-value</i>)</code>
<dd>Define a variable <code><i>name</i></code> whose value can be set
from the command line, and which assumes a value
<code><i>default-value</i></code> if it is not set. To set the value
on the command-line, include <code><i>name</i>=<i>value</i></code> on
the command-line when the program is executed. In all other respects,
<code><i>name</i></code> is an ordinary Scheme variable.
<p><dt><code>(set-param! <i>name</i> <i>new-default-value</i>)</code>
<dd>Like <code>set!</code>, but does nothing if
<code><i>name</i></code> was set on the command line.
</dl>
<h2>Complex numbers</h2>
<p>Scheme includes full support for complex numbers and arithmetic;
all of the ordinary operations (<code>+</code>, <code>*</code>,
<code>sqrt</code>, etcetera) just work. For the same reason, you can
freely use complex numbers in libctl's vector and matrix functions,
below.
<p>To specify a complex number <i>a</i>+<i>b</i>i, you simply use the
syntax <code><i>a</i>+<i>b</i>i</code> if <i>a</i> and <i>b</i> are
constants, and <code>(make-rectangular <i>a</i> <i>b</i>)</code>
otherwise. (You can also specify numbers in "polar" format
a*e<sup><small>ib</small></sup> by the syntax
<code><i>a</i>@<i>b</i></code> or <code>(make-polar <i>a</i>
<i>b</i>)</code>.)
<p>There are a few special functions provided by Scheme to manipulate
complex numbers. <code>(real-part <i>z</i>)</code> and
<code>(imag-part <i>z</i>)</code> return the real and imaginary parts
of <code><i>z</i></code>, respectively. <code>(magnitude
<i>z</i>)</code> returns the absolute value and <code>(angle
<i>z</i>)</code> returns the phase angle. libctl also provides a
<code>(conj <i>z</i>)</code> function, below, to return the complex
conjugate.
<h2>3-vector functions</h2>
<dl>
<dt><code>(vector3 <i>x [y z]</i></code>)
<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.
<p><dt><code>(vector3-x <i>v</i>)</code>
<dt><code>(vector3-y <i>v</i>)</code>
<dt><code>(vector3-z <i>v</i>)</code>
<dd>Return the corresponding component of the vector <code><i>v</i></code>.
<p><dt><code>(vector3+ <i>v1 v2</i>)</code>
<dt><code>(vector3- <i>v1 v2</i>)</code>
<dt><code>(vector3-cross <i>v1 v2</i>)</code>
<dd>Return the sum, difference, or cross product of the two vectors.
<p><dt><code>(vector3* <i>a b</i>)</code>
<dd>If <code><i>a</i></code> and <code><i>b</i></code> are both
vectors, returns their dot product. If one of them is a number and
the other is a vector, then scales the vector by the number.
<p><dt><code>(vector3-dot <i>v1 v2</i>)</code>
<dd>Returns the dot product of <code><i>v1</i></code> and <code><i>v2</i></code>.
<p><dt><code>(vector3-cross <i>v1 v2</i>)</code>
<dd>Returns the cross product of <code><i>v1</i></code> and <code><i>v2</i></code>.
<p><dt><code>(vector3-cdot <i>v1 v2</i>)</code>
<dd>Returns the conjugated dot product: <i>v1</i>* dot <i>v2</i>.
<p><dt><code>(vector3-norm <i>v</i>)</code>
<dd>Returns the length <code>(sqrt (vector3-cdot v v))</code> of the
given vector.
<p><dt><code>(unit-vector3 <i>x [y z]</i></code>)
<dt><code>(unit-vector3 <i>v</i>)</code>
<dd>Given a vector or, alternatively, one or more components, returns a
unit vector in that direction.
<p><dt><code>(vector3-close? <i>v1 v2 tolerance</i>)</code>
<dt>Returns whether or not the corresponding components of the two
vectors are within <code><i>tolerance</i></code> of each other.
<p><dt><code>(vector3= <i>v1 v2</i>)</code>
<dt>Returns whether or not the two vectors are numerically equal.
Beware of using this function after operations that may have some
error due to the finite precision of floating-point numbers; use
<code>vector3-close?</code> instead.
<p><dt><code>(rotate-vector3 <i>axis theta v</i>)</code>
<dt>Returns the vector <code><i>v</i></code> rotated by an angle
<code><i>theta</i></code> (in radians) in the right-hand direction
around the <code><i>axis</i></code> vector (whose length is ignored).
You may find the functions <code>(deg->rad <i>theta-deg</i>)</code>
and <code>(rad->deg <i>theta-rad</i>)</code> useful to convert angles
between degrees and radians.
</dl>
<h2>3x3 matrix functions</h2>
<dl>
<dt><code>(matrix3x3 <i>c1 c2 c3</i>)</code>
<dd>Creates a 3x3 matrix with the given 3-vectors as its columns.
<p><dt><code>(matrix3x3-transpose <i>m</i>)</code>
<dt><code>(matrix3x3-adjoint <i>m</i>)</code>
<dt><code>(matrix3x3-determinant <i>m</i>)</code>
<dt><code>(matrix3x3-inverse <i>m</i>)</code>
<dd>Return the transpose, adjoint (conjugate transpose), determinant,
or inverse of the given matrix.
<p><dt><code>(matrix3x3+ <i>m1 m2</i>)</code>
<dt><code>(matrix3x3- <i>m1 m2</i>)</code>
<dt><code>(matrix3x3* <i>m1 m2</i>)</code>
<dd>Return the sum, difference, or product of the given matrices.
<p><dt><code>(matrix3x3* <i>v m</i>)</code>
<dt><code>(matrix3x3* <i>m v</i>)</code>
<dd>Returns the (3-vector) product of the matrix <code><i>m</i></code>
by the vector <code><i>v</i></code>, with the vector multiplied on the
left or the right respectively.
<p><dt><code>(matrix3x3* <i>s m</i>)</code>
<dt><code>(matrix3x3* <i>m s</i>)</code>
<dd>Scales the matrix <code><i>m</i></code> by the number
<code><i>s</i></code>.
<p><dt><code>(rotation-matrix3x3 <i>axis theta</i>)</code>
<dd>Like <code>rotate-vector3</code>, except returns the (unitary)
rotation matrix that performs the given rotation. i.e.,
<code>(matrix3x3* (rotation-matrix3x3 axis theta) v)</code> produces
the same result as <code>(rotate-vector3 axis theta v)</code>.
</dl>
<h2>Objects (members of classes)</h2>
<dl>
<dt><code>(make <i>class [ properties ... ]</i>)</code>
<dd>Make an object of the given <code><i>class</i></code>. Each
property is of the form <code>(<i>property-name
property-value</i>)</code>. A property need not be specified if it
has a default value, and properties may be given in any order.
<p><dt><code>(object-property-value <i>object property-name</i>)</code>
<dd>Return the value of the property whose name (symbol) is
<code><i>property-name</i></code> in <code><i>object</i></code>. For
example, <code>(object-property-value a-circle-object 'radius)</code>.
(Returns <code>false</code> if <code><i>property-name</i></code> is
not a property of <code><i>object</i></code>.)
</dl>
<h2>Miscellaneous utilities</h2>
<dl>
<dt><code>(conj <i>x</i>)</code>
<dd>Return the complex conjugate of a number <code><i>x</i></code>
(for some reason, Scheme doesn't provide such a function).
<dt><code>(interpolate <i>n list</i>)</code>
<dd>Given a <code><i>list</i></code> of numbers or 3-vectors, linearly
interpolates between them to add <code><i>n</i></code> new
evenly-spaced values between each pair of consecutive values in the
original list.
<dt><code>(print <i>expressions...</i>)</code>
<dd>Calls the Scheme <code>display</code> function on each of its
arguments from left to right (printing them to standard output). Note
that, like <code>display</code>, it does <em>not</em> append a newline
to the end of the outputs; you have to do this yourself by including
the <code>"\n"</code> string at the end of the expression list. In
addition, there is a global variable <code>print-ok?</code>,
defaulting to <code>true</code>, that controls whether
<code>print</code> does anything; by setting <code>print-ok?</code> to
false, you can disable all output.
<dt><code>(begin-time <i>message-string statements...</i>)</code>
<dd>Like the Scheme <code>(begin ...)</code> construct, this executes
the given sequence of statements one by one. In addition, however, it
measures the elapsed time for the statements and outputs it as
<code><i>message-string</i></code>, followed by the time, followed by
a newline. The return value of <code>begin-time</code> is the elapsed
time in seconds.
<p><dt><code>(minimize <i>function tolerance</i>)</code>
<dd>Given a <code><i>function</i></code> of one (number) argument,
finds its minimum within the specified fractional
<code><i>tolerance</i></code>. If the return value of
<code>minimize</code> is assigned to a variable <code>result</code>,
then <code>(min-arg result)</code> and <code>(min-val result)</code>
give the argument and value of the function at its minimum. If you
can, you should use one of the variant forms of <code>minimize</code>,
described below.
<dt><code>(minimize <i>function tolerance guess</i>)</code>
<dd>The same as above, but you supply an initial
<code><i>guess</i></code> for where the minimum is located.
<dt><code>(minimize <i>function tolerance arg-min arg-max</i>)</code>
<dd>The same as above, but you supply the minimum and maximum function
argument values within which to search for the minimum. This is the
most preferred form of <code>minimize</code>, and is faster and more
robust than the other two variants.
<p><dt><code>(minimize-multiple <i>function tolerance arg1 .. argN</i>)</code>
<dd>Minimize a <code><i>function</i></code> of N numeric arguments within the
specified fractional <code><i>tolerance</i></code>.
<code><i>arg1</i></code> .. <code><i>argN</i></code> are an initial
guess for the function arguments. Returns both the arguments and
value of the function at its minimum. A list of the arguments at the
minimum are retrieved via <code>min-arg</code>, and the value via
<code>min-val</code>.
<p><dt><code>maximize</code>, <code>maximize-multiple</code>
<dd>These are the same as the <code><i>minimize</i></code> functions
except that they maximizes the function instead of minimizing it. The
functions <code>max-arg</code> and <code>max-val</code> are provided
instead of <code>min-arg</code> and <code>min-val</code>.
<p><dt><code>(find-root <i>function tolerance arg-min arg-max</i>)</code>
<dd>Find a root of the given <code><i>function</i></code> to within
the specified fractional <code><i>tolerance</i></code>.
<code>arg-min</code> and <code>arg-max</code> <b>bracket</b> the
desired root; the function must have opposite signs at these two
points!
<p><dt><code>(find-root-deriv <i>function tolerance arg-min arg-max [arg-guess]</i>)</code>
<dd>As <code>find-root</code>, but <code><i>function</i></code> should
return a <code>cons</code> pair of (<i>function-value
. function-derivative</i>); the derivative information is exploited to
achieve faster convergence via Newton's method, compared to
<code>find-root</code>. The optional argument
<code><i>arg-guess</i></code> should be an initial guess for the root
location.
<p><dt><code>(derivative <i>function x [dx tolerance]</i>)</code>
<dt><code>(deriv <i>function x [dx tolerance]</i>)</code>
<dt><code>(derivative2 <i>function x [dx tolerance]</i>)</code>
<dt><code>(deriv2 <i>function x [dx tolerance]</i>)</code>
<dd>Compute the numerical derivative of the given
<code><i>function</i></code> at <code><i>x</i></code> to within <em>at
best</em> the specified fractional <code><i>tolerance</i></code>
(defaulting to the maximum achievable tolerance), using Ridder's
method of polynomial extrapolation. <code><i>dx</i></code> should be
a <i>maximum</i> displacement in <code><i>x</i></code> for derivative
evaluation; the <code><i>function</i></code> should change by a
significant amount (much larger than the numerical precision) over
<code><i>dx</i></code>. <code><i>dx</i></code> defaults to 1% of
<code><i>x</i></code> or <code>0.01</code>, whichever is larger.
<p>If the return value of <code>derivative</code> is assigned to a
variable <code>result</code>, then <code>(derivative-df result)</code>
and <code>(derivative-df-err result)</code> give the derivative of the
function and an estimate of the numerical error in the derivative,
respectively.
<p>The <code>derivative2</code> function computes both the first and
second derivatives, using minimal extra function evaluations; the
second derivative and its error are then obtained by
<code>(derivative-d2f result)</code> and <code>(derivative-d2f-err
result)</code>.
<p><code>deriv</code> and <code>deriv2</code> are identical to
<code>derivative</code> and <code>derivative2</code>, except that they
directly return the value of the first and second derivatives,
respectively (no need to call <code>derivative-df</code> or
<code>derivative-d2f</code>). (They don't provide the error estimate,
however, or the ability to compute first and second derivatives
simulataneously.)
<p><dt><code>(integrate <i>f a b tolerance</i>)</code>
<dd>Return the definite integral of the function <code><i>f</i></code> from
<code><i>a</i></code> to <code><i>b</i></code>, to within the specified
fractional <code><i>tolerance</i></code>, using an adaptive
trapezoidal rule.
<p>This function can compute multi-dimensional integrals, in which
case <code><i>f</i></code> is a function of <i>N</i> variables and
<code><i>a</i></code> and <code><i>b</i></code> are either lists or
vectors of length <i>N</i>, giving the (constant) integration bounds
in each dimension. (Non-constant integration bounds,
i.e. non-rectilinear integration domains, can be handled by an
appropriate mapping of the function <code><i>f</i></code>.)
<p><dt><code>(fold-left <i>op init list</i>)</code>
<dd>Combine the elements of <code><i>list</i></code> using the binary
"operator" function <code><i>(op x y)</i></code>, with initial value
<code><i>init</i></code>, associating from the left of the list. That
is, if <code><i>list</i></code> consist of the elements <code>(<i>a b
c d</i>)</code>, then <code>(fold-left <i>op init list</i>)</code>
computes <code>(op (op (op (op init a) b) c) d)</code>. For example,
if <code><i>list</i></code> contains numbers, then <code>(fold-left +
0 <i>list</i>)</code> returns the sum of the elements of
<code><i>list</i></code>.
<p><dt><code>(fold-right <i>op init list</i>)</code>
<dd>As <code>fold-left</code>, but associate from the right. For
example, <code>(op a (op b (op c (op d init))))</code>.
<p><dt><code>(memoize <i>func</i>)</code>
<dd>Return a function wrapping around the function
<code><i>func</i></code> that "memoizes" its arguments and return
values. That is, it returns the same thing as
<code><i>func</i></code>, but if passed the same arguments as a
previous call it returns a cached return value from the previous call
instead of recomputing it.
</dl>
<hr>
Go to the <a href="developer.html">next</a>, <a
href="advanced-user.html">previous</a>, or <a href="index.html">main</a>
section.
</BODY>
</HTML>
|
