Libctl User Reference
From AbInitio
Revision as of 22:41, 31 March 2008 (edit) Stevenj (Talk  contribs) (→Miscellaneous utilities  clarification) ← Previous diff 
Current revision (14:52, 20 July 2012) (edit) Stevenj (Talk  contribs) (→3vector functions) 

Line 72:  Line 72:  
; <code>(rotatevector3 ''axis theta v'')</code>  ; <code>(rotatevector3 ''axis theta v'')</code>  
: Returns the vector <code>''v''</code> rotated by an angle <code>''theta''</code> (in radians) in the righthand direction around the <code>''axis''</code> vector (whose length is ignored). You may find the functions <code>(deg>rad ''thetadeg'')</code> and <code>(rad>deg ''thetarad'')</code> useful to convert angles between degrees and radians.  : Returns the vector <code>''v''</code> rotated by an angle <code>''theta''</code> (in radians) in the righthand direction around the <code>''axis''</code> vector (whose length is ignored). You may find the functions <code>(deg>rad ''thetadeg'')</code> and <code>(rad>deg ''thetarad'')</code> useful to convert angles between degrees and radians.  
+  ; <code>(vector3>exact ''v'')</code>  
+  : Round a vector3 ''v'' to the nearest "exact" representation in Scheme: an integer or a rational number. This is mainly useful if you have an allinteger vector and you want to force Guile to treat it as integers rather than floatingpoint numbers.  
== 3x3 matrix functions ==  == 3x3 matrix functions == 
Current revision
libctl 
Manual: Introduction 
Basic User Experience 
Advanced User Experience 
User Reference 
Developer Experience 
Guile and Scheme links 
License and Copyright 
In this section, we list all of the special functions provided for users by libctl. We do not attempt to document standard Scheme functions, with a couple of exceptions below, since there are plenty of good Scheme references [guilelinks.html elsewhere].
Of course, the most important function is:

(help)
 Outputs a listing of all the available classes, their properties, default values, and types. Also lists the input and output variables.
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!
Contents 
Basic Scheme functions

(set! variable value)
 Change the value of
variable
tovalue
. 
(define variable value)
 Define new
variable
with initialvalue
. 
(list [ element1 element2 ... ])
 Returns a list consisting of zero or more elements.

(append [ list1 list2 ... ])
 Concatenates zero or more lists into a single list.

(function [ arg1 arg2 ... ])
 This is how you call a Scheme
function
in general. 
(define (function [ arg1 arg2 ... ]) body)
 Define a new
function
with zero or more arguments that returns the result of givenbody
when it is invoked.
Commandline parameters

(defineparam name defaultvalue)
 Define a variable
name
whose value can be set from the command line, and which assumes a valuedefaultvalue
if it is not set. To set the value on the commandline, includename=value
on the commandline when the program is executed. In all other respects,name
is an ordinary Scheme variable. 
(setparam! name newdefaultvalue)
 Like
set!
, but does nothing ifname
was set on the command line.
All libctl arguments accept the commandline parameter verbose
to turn on a verbose mode. This sets the variable verbose?
to true
(and, depending on the program, may enable other outputs).
Complex numbers
Scheme includes full support for complex numbers and arithmetic; all of the ordinary operations (+
, *
, sqrt
, etcetera) just work. For the same reason, you can freely use complex numbers in libctl's vector and matrix functions, below.
To specify a complex number a+bi, you simply use the syntax a+bi
if a and b are constants, and (makerectangular a b)
otherwise. (You can also specify numbers in "polar" format a*e^{ib} by the syntax a@b
or (makepolar a b)
.)
There are a few special functions provided by Scheme to manipulate complex numbers. (realpart z)
and (imagpart z)
return the real and imaginary parts of z
, respectively. (magnitude z)
returns the absolute value and (angle z)
returns the phase angle. libctl also provides a (conj z)
function, below, to return the complex conjugate.
3vector functions

(vector3 x [y z]
)  Create a new 3vector with the given components. If the
y
orz
value is omitted, it is set to zero. 
(vector3x v)

(vector3y v)

(vector3z v)
 Return the corresponding component of the vector
v
. 
(vector3+ v1 v2)

(vector3 v1 v2)

(vector3cross v1 v2)
 Return the sum, difference, or cross product of the two vectors.

(vector3* a b)
 If
a
andb
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. 
(vector3dot v1 v2)
 Returns the dot product of
v1
andv2
. 
(vector3cross v1 v2)
 Returns the cross product of
v1
andv2
. 
(vector3cdot v1 v2)
 Returns the conjugated dot product: v1* dot v2.

(vector3norm v)
 Returns the length
(sqrt (vector3cdot v v))
of the given vector. 
(unitvector3 x [y z]
) 
(unitvector3 v)
 Given a vector or, alternatively, one or more components, returns a unit vector in that direction.

(vector3close? v1 v2 tolerance)
 Returns whether or not the corresponding components of the two vectors are within
tolerance
of each other. 
(vector3= v1 v2)
 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 floatingpoint numbers; use
vector3close?
instead. 
(rotatevector3 axis theta v)
 Returns the vector
v
rotated by an angletheta
(in radians) in the righthand direction around theaxis
vector (whose length is ignored). You may find the functions(deg>rad thetadeg)
and(rad>deg thetarad)
useful to convert angles between degrees and radians. 
(vector3>exact v)
 Round a vector3 v to the nearest "exact" representation in Scheme: an integer or a rational number. This is mainly useful if you have an allinteger vector and you want to force Guile to treat it as integers rather than floatingpoint numbers.
3x3 matrix functions

(matrix3x3 c1 c2 c3)
 Creates a 3x3 matrix with the given 3vectors as its columns.

(matrix3x3transpose m)

(matrix3x3adjoint m)

(matrix3x3determinant m)

(matrix3x3inverse m)
 Return the transpose, adjoint (conjugate transpose), determinant, or inverse of the given matrix.

(matrix3x3+ m1 m2)

(matrix3x3 m1 m2)

(matrix3x3* m1 m2)
 Return the sum, difference, or product of the given matrices.

(matrix3x3* v m)

(matrix3x3* m v)
 Returns the (3vector) product of the matrix
m
by the vectorv
, with the vector multiplied on the left or the right respectively. 
(matrix3x3* s m)

(matrix3x3* m s)
 Scales the matrix
m
by the numbers
. 
(rotationmatrix3x3 axis theta)
 Like
rotatevector3
, except returns the (unitary) rotation matrix that performs the given rotation. i.e.,(matrix3x3* (rotationmatrix3x3 axis theta) v)
produces the same result as(rotatevector3 axis theta v)
.
Objects (members of classes)

(make class [ properties ... ])
 Make an object of the given
class
. Each property is of the form(propertyname propertyvalue)
. A property need not be specified if it has a default value, and properties may be given in any order. 
(objectpropertyvalue object propertyname)
 Return the value of the property whose name (symbol) is
propertyname
inobject
. For example,(objectpropertyvalue acircleobject 'radius)
. (Returnsfalse
ifpropertyname
is not a property ofobject
.)
Miscellaneous utilities

(conj x)
 Return the complex conjugate of a number
x
(for some reason, Scheme doesn't provide such a function). 
(interpolate n list)
 Given a
list
of numbers or 3vectors, linearly interpolates between them to addn
new evenlyspaced values between each pair of consecutive values in the original list. 
(interpolateuniform n list)
 Similar to
interpolate
, but attempts to maintain a (roughly) uniform average spacing of the points in the interpolated list. In this casen
is only the number of points interpolated on average between each pair of values in the original list. 
(print expressions...)
 Calls the Scheme
display
function on each of its arguments from left to right (printing them to standard output). Note that, likedisplay
, it does not append a newline to the end of the outputs; you have to do this yourself by including the"\n"
string at the end of the expression list. In addition, there is a global variableprintok?
, defaulting totrue
, that controls whetherprint
does anything; by settingprintok?
to false, you can disable all output. 
(begintime messagestring statements...)
 Like the Scheme
(begin ...)
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 asmessagestring
, followed by the time, followed by a newline. The return value ofbegintime
is the elapsed time in seconds. 
(minimize function tolerance)
 Given a
function
of one (number) argument, finds its minimum within the specified fractionaltolerance
. If the return value ofminimize
is assigned to a variableresult
, then(minarg result)
and(minval result)
give the argument and value of the function at its minimum. If you can, you should use one of the variant forms ofminimize
, described below. 
(minimize function tolerance guess)
 The same as above, but you supply an initial
guess
for where the minimum is located. 
(minimize function tolerance argmin argmax)
 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
minimize
, and is faster and more robust than the other two variants. 
(minimizemultiple function tolerance arg1 .. argN)
 Minimize a
function
of N numeric arguments within the specified fractionaltolerance
.arg1
..argN
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 viaminarg
, and the value viaminval
. 
maximize
,maximizemultiple
 These are the same as the
minimize
functions except that they maximizes the function instead of minimizing it. The functionsmaxarg
andmaxval
are provided instead ofminarg
andminval
. 
(findroot function tolerance argmin argmax)
 Find a root of the given
function
to within the specified fractionaltolerance
.argmin
andargmax
bracket the desired root; the function must have opposite signs at these two points! 
(findrootderiv function tolerance argmin argmax [argguess])
 As
findroot
, butfunction
should return acons
pair of (functionvalue . functionderivative); the derivative information is exploited to achieve faster convergence via Newton's method, compared tofindroot
. The optional argumentargguess
should be an initial guess for the root location. 
(derivative function x [dx tolerance])

(deriv function x [dx tolerance])

(derivative2 function x [dx tolerance])

(deriv2 function x [dx tolerance])
 Compute the numerical derivative of the given
function
atx
to within at best the specified fractionaltolerance
(defaulting to the best achievable tolerance), using Ridder's method of polynomial extrapolation.dx
should be a maximum displacement inx
for derivative evaluation; thefunction
should change by a significant amount (much larger than the numerical precision) overdx
.dx
defaults to 1% ofx
or0.01
, whichever is larger.  If the return value of
derivative
is assigned to a variableresult
, then(derivativedf result)
and(derivativedferr result)
give the derivative of the function and an estimate of the numerical error in the derivative, respectively.  The
derivative2
function computes both the first and second derivatives, using minimal extra function evaluations; the second derivative and its error are then obtained by(derivatived2f result)
and(derivatived2ferr result)
. deriv
andderiv2
are identical toderivative
andderivative2
, except that they directly return the value of the first and second derivatives, respectively (no need to callderivativedf
orderivatived2f
). (They don't provide the error estimate, however, or the ability to compute first and second derivatives simulataneously.) There are also modified versions of these functions that compute onesided derivatives: they only evaluate the function at arguments x that are ≥0 (or only ≤0). These functions are named
derivative+
,deriv+
etc. (orderivative
etc. for negative arguments) and otherwise behave identically. They are generally less accurate than the twosided derivative, above, but are useful for functions with discontinuous derivatives.
 There are also modified versions of these functions that compute onesided derivatives: they only evaluate the function at arguments x that are ≥0 (or only ≤0). These functions are named

(integrate f a b relerr [ abserr maxeval ])
 Return the definite integral of the function
f
froma
tob
, to within the specified relative errorrelerr
, using an adaptive Gaussian quadrature (in 1d) or adaptive cubature (in multiple dimensions). The optional argumentsabserr
andmaxeval
specify an absolute error tolerance (default is zero) and a maximum number of function evaluations (default is no limit). Integration stops when either the relative error or the absolute error or the maximum number of evaluations is met (note that error estimates are only approximate, though).  This function can compute multidimensional integrals, in which case
f
is a function of N variables anda
andb
are either lists or vectors of length N, giving the (constant) integration bounds in each dimension. (Nonconstant integration bounds, i.e. nonrectilinear integration domains, can be handled by an appropriate mapping of the functionf
.) 
(foldleft op init list)
 Combine the elements of
list
using the binary "operator" function(op x y)
, with initial valueinit
, associating from the left of the list. That is, iflist
consist of the elements(a b c d)
, then(foldleft op init list)
computes(op (op (op (op init a) b) c) d)
. For example, iflist
contains numbers, then(foldleft + 0 list)
returns the sum of the elements oflist
. 
(foldright op init list)
 As
foldleft
, but associate from the right. For example,(op a (op b (op c (op d init))))
. 
(memoize func)
 Return a function wrapping around the function
func
that "memoizes" its arguments and return values. That is, it returns the same thing asfunc
, but if passed the same arguments as a previous call it returns a cached return value from the previous call instead of recomputing it.