antik.texi 68.9 KB
Newer Older
1
2
3
4
5
6
7
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename antik.info
@settitle Antik Manual
@c %**end of header

8
9
10
11
12
13
14
15
16
@macro &optional {}
&optional
@end macro
@macro &key {}
&key
@end macro
@macro &rest {}
&rest
@end macro
17
18
19
@macro &body {}
&body
@end macro
20
21
22
@macro &allow-other-keys {}
&allow-other-keys
@end macro
23
24
25
26

@macro nil {} @code{nil}
@end macro

27
28
@include macros.texinfo

29
@copying
30
Copyright @copyright{} 2009, 2010, 2011, 2013 Liam M. Healy
31
32
33
34
35
36
@end copying

@titlepage
@title Antik
@page
@vskip 0pt plus 1filll
37
@c@insertcopying@node
38
39
40
@end titlepage

@ifnottex
41
@node Top, Introduction, (dir), (dir)
42
@comment  node-name, next,      previous,  up
43
@menu
44
45
* Introduction::
* Mathematics::
46
* Organization of Computation::
47
48
* Grids::                       
* Physical Quantities::         
49
* Numerical Output Format::
50
51
* Mathematical Utility::
* Three Dimensional Space::
52
* Mathematics::
53
54
* Internals::                   
* Download and installation::   
55
* Copying this software::                     
56
* Index::
57
@end menu
58
@c Removed the "detailed menu" (at end of this file) because it's too much clutter.
59

60
61
@top Antik

62
63
This is the manual for the use of Antik, which provides a foundation for
scientific and engineering computing in Common Lisp.
64
65
66
67
68
69
70

@insertcopying
@end ifnottex

@c Output the table of the contents at the beginning.
@contents

71
72
@node Introduction, Mathematics, Top, Top
@chapter Introduction
Liam M. Healy's avatar
Liam M. Healy committed
73
@cindex GSLL
74

75
Antik provides a foundation for scientific and engineering computation in Common Lisp.  It is designed not only to facilitate numerical computations, but to permit the use of numerical computation libraries and the interchange of data and procedures, whether foreign (non-lisp) or Lisp libraries.  Notably, @url{http://common-lisp.net/project/gsll/,GSLL} provides an interface to the @url{http://www.gnu.org/software/gsl/,GNU Scientific Library} and is based on Antik.
76
77
78
79

There are two Common Lisp @url{http://www.lispworks.com/documentation/HyperSpec/Body/11_aa.htm, packages}
defined by Antik, @code{antik} and @code{grid}.  Names within these packages have been chosen to match Common Lisp names where the corresponding function could be considered a generalization of the CL function.  Therefore, @url{http://www.lispworks.com/documentation/HyperSpec/Body/f_shadow.htm#shadow,shadow}ing is used to make sure that within the @code{antik} package and packages that use it, a reference to the symbol will use the Antik definition and not the CL definition.  

80
Antik is designed and developed to provide a common foundation and interoperability between scientific, engineering and mathematical libraries, whether in Lisp or not.  Interoperability means that objects created can easily be passed to one or more libraries, and libraries can be mixed and combined to solve a problem.  It also means that names of like functions will be the same, differening only in the package.  For example, if systems @code{foo} and @code{bar} both provide an LU decomposition, that function will be @code{foo:lu-decomposition} in one and @code{bar:lu-decomposition} in the other.  Should a user wish to compare or switch libraries in such a function call, it is a simple matter of changing the package.  If a whole library should be switched, the names can be used without a package prefix and the use-package form changed.  This makes it easy to compare results, and select and mix the best libraries for a calculation.
81
82
83
84
85

There is a package defined for users to use Antik, @code{antik-user}.  All the appropriate symbols are shadowed.  It @url{http://www.lispworks.com/documentation/HyperSpec/Body/f_use_pk.htm#use-package,use}es the packages @code{common-lisp}, @code{grid}, @code{antik}, and @code{iterate}.  To make another package with the same use and shadowing properties, call the function @code{antik:make-user-package}.

@include include/fun-antik-make-user-package.texinfo

86
87
88
89
90
91
92
93
94
95
There are several (ASDF) systems that comprise Antik, and, those systems can be selectively loaded depending on the definitions needed. The systems of direct interest to most users are
@itemize
@item grid
@item foreign-array
@item input-output
@item physical-dimension
@item mathematics
@end itemize
There are various extensions/additions offered through the @code{asdf-system-connections} mechanism. In particular, if the system @code{lisp-unit} is loaded, then there are a number of regression tests available.

96
@node Mathematics, Organization of Computation, Introduction, Top
97
98
99
100
101
102
103
104
105
@chapter Mathematics

@menu
* Generic Functions::
* Conditions::
@end menu

@node Generic Functions, Conditions, Mathematics, Mathematics
@section Generic Functions
Liam M. Healy's avatar
Liam M. Healy committed
106
107
108
109
110
111
112
113
114
115
116
@cindex Mathematical functions, elementary
@cindex Functions, elementary mathematical
@cindex Elementary mathematical functions
@cindex Trigonometric functions
@cindex Functions, trigonometric
@cindex Exponential functions
@cindex Functions, exponential
@cindex Comparison functions, numerical
@cindex Numerical comparison functions
@cindex Arithmetic functions
@cindex Functions, arithmetic
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
Generic mathematical functions are provided so that they may be called on something other than numbers, such as grids.  When called with CL numbers, they perform they call the equivalent CL function.

@include include/fun-antik-abs.texinfo
@include include/fun-antik-acos.texinfo
@include include/fun-antik-asin.texinfo
@include include/fun-antik-atan.texinfo
@include include/fun-antik-cosh.texinfo
@include include/fun-antik-cos.texinfo
@include include/fun-antik-equals.texinfo
@include include/fun-antik-exp.texinfo
@include include/fun-antik-expt.texinfo
@include include/fun-antik-floor.texinfo
@include include/fun-antik-gt-equals.texinfo
@include include/fun-antik-gt.texinfo
@include include/fun-antik-log.texinfo
@include include/fun-antik-lt-equals.texinfo
@include include/fun-antik-lt.texinfo
@include include/fun-antik-minusp.texinfo
@include include/fun-antik-plusp.texinfo
@include include/fun-antik-plus.texinfo
@include include/fun-antik-round.texinfo
@include include/fun-antik-signum.texinfo
@include include/fun-antik-sinh.texinfo
@include include/fun-antik-sin.texinfo
@include include/fun-antik-slash.texinfo
@include include/fun-antik-sqrt.texinfo
@include include/fun-antik-star.texinfo
@include include/fun-antik-tanh.texinfo
@include include/fun-antik-tan.texinfo
@include include/fun-antik--.texinfo
@include include/fun-antik-zerop.texinfo

@node Conditions,  , Generic Functions, Mathematics
@section Conditions
Liam M. Healy's avatar
Liam M. Healy committed
151
152
@cindex Conditions for numerical computation
@cindex Handler for conditions
153
154
155
156
157
158
159
160
Conditions and handlers are defined for common mathematical computations.

The condition @code{making-complex-number} is signalled when a calculation would make a complex number.  If this outcome is desirable, and handler such as defined by the macro @code{handling-complex-number} is used.  

@include include/condition-antik-making-complex-number.texinfo
@include include/macro-antik-arithmetic-errors-return-nan.texinfo
@include include/macro-antik-handling-complex-number.texinfo

Liam M. Healy's avatar
Liam M. Healy committed
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
@c This needs node information
@section Iterate generalized numbers
Extensions to the @url{http://common-lisp.net/project/iterate/,@command{iterate}}
system are provided.  The following 
@url{http://common-lisp.net/project/iterate/doc/Reductions.html#Reductions,reductions}
and
@url{http://common-lisp.net/project/iterate/doc/Finders.html#Finders,finders}
are provided:
@itemize
@item multiply
@item sum
@item maximize
@item finding ... maximizing
@item minimize
@item finding ... minimizing
@end itemize
These are exactly like those provided in iterate, but are extended to use the appropriate generic functions.  

The driver for @url{http://common-lisp.net/project/iterate/doc/Drivers.html#Drivers,numerical iteration} will work with generalized numbers.

181
@node Organization of Computation, Grids, Mathematics, Top
182
@chapter Organization of Computation
Liam M. Healy's avatar
Liam M. Healy committed
183
184
@cindex Notebook, computation
@cindex Logbook of computation
185
186
187
188
189
190
191
192
193
194
195
@menu
* Introduction to organization::
* Parameters::
@end menu

@node Introduction to organization, Parameters, Organization of Computation, Organization of Computation
@section Introduction
Typically scientific and engineering computation starts with input values and computes values or properties of an object, uses those as inputs to compute more values and properties, and eventually produces an output.  Sometimes it is necessary to examine the intermediate values, as for education or debugging; sometimes, especially when doing production runs, the variable input and output are the only things of interest, the values that remain unchanged with each calculation are recorded but are not the focus of the computation, and the intermediate values are only need temporarily to get to the next stage of the computation.

This section will describe the definitions for organizing computations.  At present very little is written; only @dfn{parameters} definitions exist, and these are likely to change.

196
197
Load the system @code{input-output} for these definitions.

198
199
@node Parameters,  , Introduction to organization, Organization of Computation
@section Parameters
Liam M. Healy's avatar
Liam M. Healy committed
200
@cindex Parameters
201
Parameters are named values that are defined and used in computations or in presentation.  The @url{http://www.lispworks.com/documentation/HyperSpec/Body/m_defpar.htm#defparameter,defparameter} macro defines parameters (dynamic variables) but Antik has definitions that permit grouping them and including properties such as the type, which will be checked when values are assigned, and defining synonyms.  The grouping is in named categories; Antik itself defines one category, @code{NF}, which is used for numerical formatting.  Each category used will become a package, and the symbols exported from that package. The value can be changed with @code{(setf parameter-value)} and used with @code{parameter-value}, or changed locally (analogous to @code{let} for CL variables) with @code{with-parameters}. It is also permissible to assign as a normal variable (e.g., with let and setf), but no type checking is performed.
202
203
204
@example

;;; Then define some parameters
205
206
207
208
209
210
211
212
(define-parameter kepler foo
  :value 122
  :type fixnum
  :documentation "A fixnum parameter of kepler.")
(define-parameter kepler bar
  :value "hi"
  :type string
  :documentation "A string parameter of kepler.")
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230

;;; Get their values
(parameter-value kepler bar)
"hi"
(parameter-value kepler foo)
122

;;; Dynamic binding
(defun show-foo-bar ()
  (format t "~&foo: ~a, bar: ~s"
	  (parameter-value kepler foo)
	  (parameter-value kepler bar)))

(show-foo-bar)
foo: 122, bar: "hi"
NIL

;;; Locally change values
231
(with-parameters (kepler (foo 143) (bar "bye"))
232
233
234
235
236
237
238
239
240
  (show-foo-bar))
foo: 143, bar: "bye"
NIL

(show-foo-bar)
foo: 122, bar: "hi"
NIL

;;; Make a mistake
241
(with-parameters (kepler (foo 143) (bar -44))
242
243
244
245
  (show-foo-bar))
Error: Value -44 is of type FIXNUM, not of the required type STRING.

;;; Globally change values
246
247
(setf (parameter-value kepler bar) "a new value")
(show-foo-bar)
248
249
foo: 122, bar: "a new value"

250
;;; Set multiple values
251
(set-parameters kepler bar "xyz" foo 1)
252
253
(show-foo-bar)
foo: 1, bar: "xyz"
254
255
256

;;; Get information about the categories and parameters
(parameter-help)
257
Parameter categories: KEPLER and NF.
258
259
260
261
262
263

(parameter-help :kepler)
Parameters in KEPLER: BAR and FOO.

(parameter-help :kepler :bar)
BAR: A string parameter of kepler.
264
265
Type is STRING,
Current value is "xyz".
266
267
268
269
270
@end example

@include include/macro-antik-define-parameter.texinfo
@include include/fun-antik-parameter-help.texinfo
@include include/macro-antik-parameter-value.texinfo
271
272
@include include/macro-antik-set-parameter.texinfo
@include include/macro-antik-set-parameters.texinfo
273
274
@include include/macro-antik-with-parameters.texinfo

275
@node Grids, Physical Quantities, Organization of Computation, Top
276
@chapter Grids
Liam M. Healy's avatar
Liam M. Healy committed
277
278
279
@cindex Vectors
@cindex Matrices
@cindex Arrays
280
@menu
281
* Introduction to grids::                
282
283
* Creating a grid::             
* Operations::                  
284
* Input and Output::                  
285
* Physical quantities::         
286
* Capabilities and Internals::
287
288
289
* Efficiency::                  
@end menu

290
@node Introduction to grids, Creating a grid, Grids, Grids
291
@section Introduction to grids
292

293
294
Load the system @code{grid} for these definitions.

295
296
297
298
299
300
301
@menu
* The grid concept::            
* Types of grids::              
* Package::                     
* Tests::                       
@end menu

302
@node The grid concept, Types of grids, Introduction to grids, Introduction to grids
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
@subsection The grid concept

In scientific and engineering computing, data is frequently organized
into a regular pattern indexed by a finite sequence of integers, and
thought of having a Cartesian arrangement.  
We call these @dfn{grids}.
A standard form is the @dfn{array}, but we do not wish to confine
ourselves to representation in terms of
@url{http://www.lispworks.com/documentation/lw50/CLHS/Body/t_array.htm,a
Common Lisp array}.  Other examples might be a list of lists, a C array
accessible through a foreign function interface, or an SQL table.  We
assume a rectangular shape; that is, the range of indices permissible is
independent of the other values of the index.  Each node of the grid is
an @dfn{element} (or sometimes a @dfn{component}).

Since we are primarily focused on the scientific and engineering
applications, the elements will generally be numbers of some type.  Most
320
of the definitions here however do not force this to be the case.
321
322

The @dfn{rank} of a grid is the number of Cartesian axes, and the
323
@dfn{dimensions} are a sequence of non-negative integers of length equal
324
to the rank that give the number of index values possible along each
325
326
327
328
329
330
331
332
axis.  We will call a grid of rank 1 a @dfn{vector} (where there would
not be a confusion with the
@url{http://www.lispworks.com/documentation/HyperSpec/Body/t_vector.htm,CL
vector}) and a grid of rank 2 a @dfn{matrix}.  For example, a matrix
representing rotations in three dimensional space would have rank 2 and
dimensions (3 3).

@node Types of grids, Package, The grid concept, Introduction to grids
333
334
335
336
@subsection Types of grids

Antik defines two types of grids, @dfn{array}s, i.e. ordinary Lisp
arrays, and @dfn{foreign array}s, which are defined in foreign memory
337
338
339
340
341
and therefore are accessible by foreign libraries.  The argument
@code{grid-type} to a function or the variable
@code{grid:*default-grid-type*} should be bound to one of
@code{cl:array} or @code{grid:foreign-array}, to specify an array or
foreign-array respectively.
342

343
@node Package, Tests, Types of grids, Introduction to grids
344
345
346
347
@subsection Package
The symbols defined here are in the @code{grid}
@url{http://www.lispworks.com/documentation/HyperSpec/Body/11_aa.htm,package}.

348
@node Tests,  , Package, Introduction to grids
349
350
351
352
353
354
@subsection Tests

There are some tests defined for these modules; to run the tests, make
sure that @command{asdf-system-connections} system is loaded before
anything else, and @command{lisp-unit} is loaded, then
@example
355
356
(in-package :antik)
(lisp-unit:run-tests)
357
358
359
360
(in-package :grid)
(lisp-unit:run-tests)
@end example

361
@node Creating a grid, Operations, Introduction to grids, Grids
362
@section Creating a grid
Liam M. Healy's avatar
Liam M. Healy committed
363
364
@cindex Grid, creating
@cindex Creating a grid
365
366
367

@menu
* Reader macro and function @code{grid}::  
368
* The foreign-array class::    
369
* Simple grids and default values::  
Liam M. Healy's avatar
Liam M. Healy committed
370
* Functions for creation of grids::           
371
372
@end menu

373
@node Reader macro and function @code{grid}, The foreign-array class, Creating a grid, Creating a grid
Liam M. Healy's avatar
Liam M. Healy committed
374
@cindex Reader macro, grid
375
376
377
378
@subsection Reader macro and function @code{grid}
The #m reader macro in the default form creates a vector or matrix of
element type double-float, which is the most common type needed for
mathematical functions, and grid type given by
379
380
381
382
383
384
@code{grid:*default-grid-type*} (see @ref{Types of grids}).  It
optionally takes a numeric argument prefix to make an array with a
different element type; a guide to the numeric argument is given below.
It should be followed by a list, which is not evaluated.  If the list
contains @code{^}, the object created will be a matrix and each row is
ended with that symbol.
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414

@multitable @columnfractions 0.2 0.2 0.2 0.2
     @headitem Element type @tab #m prefix
     @item double-float
     @tab 1 or empty
     @item (complex double-float)
     @tab 2
     @item single-float
     @tab 3
     @item (complex single-float)
     @tab 4
     @item (signed-byte 8)
     @tab 7
     @item (unsigned-byte 8)
     @tab 8
     @item (signed-byte 16)
     @tab 15
     @item (unsigned-byte 16)
     @tab 16
     @item (signed-byte 32)
     @tab 31
     @item (unsigned-byte 32)
     @tab 32
     @item (signed-byte 64)
     @tab 63
     @item (unsigned-byte 64)
     @tab 64
     @end multitable

The function @code{grid:grid} creates a grid of the default type and
415
416
417
418
419
420
421
422
423
evaluates its arguments.  For example,
@example
ANTIK-USER> (setf grid:*default-grid-type* 'grid:foreign-array)
FOREIGN-ARRAY
ANTIK-USER> (grid:grid 1.0d0 2.0d0 3.0d0)
#m(1.000000000000000d0 2.000000000000000d0 3.000000000000000d0)
ANTIK-USER> (type-of @@)
VECTOR-DOUBLE-FLOAT
@end example
424

Liam M. Healy's avatar
Liam M. Healy committed
425
@cindex Reader macro, array
426
427
428
429
430
431
432
Of course, an ordinary (Common Lisp) array may be created
in the usual fashion, with the @code{#} reader macro
@example
#(1.0d0 2.0d0 3.0d0)
@end example
or with @code{make-array}.

433
434
@node The foreign-array class, Simple grids and default values, Reader macro and function @code{grid}, Creating a grid
@subsection The @command{foreign-array} class
Liam M. Healy's avatar
Liam M. Healy committed
435
436
437
438
439
440
441
442
443
@cindex Class, foreign-array
@cindex Foreign array
@cindex Array accessible in non-Lisp language
@cindex C array
@cindex Fortran array
@cindex Array, C
@cindex Array, foreign
@cindex Matrix, foreign
@cindex Vector, foreign
444
The @command{foreign-array} class
445
uses @url{http://common-lisp.net/project/cffi/,@command{CFFI}} to allow the use
446
of C arrays as grids. Load the system @code{foreign-array} to enable use of foreign arrays.
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502

Classes of vectors and matrices are named by appending the element
type as hypenated words to "vector" or "matrix".  The following table
shows the classes available on a 64-bit platform:
@multitable @columnfractions 0.2 0.2 0.2 0.2
     @headitem Element type @tab Vector class @tab Matrix class @tab #m prefix
     @item double-float
     @tab @code{vector-double-float}
     @tab @code{matrix-double-float}
     @tab 1 or empty
     @item (complex double-float)
     @tab @code{vector-complex-double-float}
     @tab @code{matrix-complex-double-float}
     @tab 2
     @item single-float
     @tab @code{vector-single-float}
     @tab @code{matrix-single-float}
     @tab 3
     @item (complex single-float)
     @tab @code{vector-complex-single-float}
     @tab @code{matrix-complex-single-float}
     @tab 4
     @item (signed-byte 8)
     @tab @code{vector-signed-byte-8}
     @tab @code{matrix-signed-byte-8}
     @tab 7
     @item (unsigned-byte 8)
     @tab @code{vector-unsigned-byte-8}
     @tab @code{matrix-unsigned-byte-8}
     @tab 8
     @item (signed-byte 16)
     @tab @code{vector-signed-byte-16}
     @tab @code{matrix-signed-byte-16}
     @tab 15
     @item (unsigned-byte 16)
     @tab @code{vector-unsigned-byte-16}
     @tab @code{matrix-unsigned-byte-16}
     @tab 16
     @item (signed-byte 32)
     @tab @code{vector-signed-byte-32}
     @tab @code{matrix-signed-byte-32}
     @tab 31
     @item (unsigned-byte 32)
     @tab @code{vector-unsigned-byte-32}
     @tab @code{matrix-unsigned-byte-32}
     @tab 32
     @item (signed-byte 64)
     @tab @code{vector-signed-byte-64}
     @tab @code{matrix-signed-byte-64}
     @tab 63
     @item (unsigned-byte 64)
     @tab @code{vector-unsigned-byte-64}
     @tab @code{matrix-unsigned-byte-64}
     @tab 64
     @end multitable

503
A foreign array is especially useful when sending or receiving data from a foreign library.  In that case, the generic function @code{grid:foreign-pointer} should be called on the foreign array in order to obtain the pointer that the foreign library needs.  The identical contents as a CL array is available with the function @code{cl-array} under two conditions: the @url{http://gitorious.org/iolib/static-vectors,static-vectors} system is installed and supported for the CL implementation used, and foreign array was @emph{not} made with @ref{make-foreign-array-from-pointer}.  If it does exist, this array is the same as the foreign array (not a copy), so for example changing one changes the other:
504
@example
505
506
507
508
509
510

ANTIK-USER> (defparameter *my-fa* (make-foreign-array 'double-float :dimensions 3))
ANTIK-USER> *my-fa*
#m(0.000000000000000d0 1.000000000000000d0 2.000000000000000d0)
ANTIK-USER> (cl-array *my-fa*)
#(0.0 1.0 2.0)
Liam M. Healy's avatar
Liam M. Healy committed
511
ANTIK-USER> (setf (grid:aref *my-fa* 1) 33.3d0)
512
513
514
515
516
33.3
ANTIK-USER>  *my-fa*
#m(0.000000000000000d0 33.300000000000000d0 2.000000000000000d0)
ANTIK-USER> (cl-array *my-fa*)
#(0.0 33.3 2.0)
517
ANTIK-USER> (setf (aref (cl-array *my-fa*) 1) 22.2d0)
518
519
520
22.2
ANTIK-USER> *my-fa*
#m(0.000000000000000d0 22.200000000000000d0 2.000000000000000d0)
521
522
@end example

Liam M. Healy's avatar
Liam M. Healy committed
523
@node Simple grids and default values, Functions for creation of grids, The foreign-array class, Creating a grid
524
525
526
527
528
529
530
531
532
533
534
535
@subsection Simple grids and default values

A simple grid is one which only has one layer, that is, the contents of
the objects are the scalar elements (and not other array-like objects).
Both array and foreign-array are simple grids.  The function
@code{make-simple-grid} will create a simple grid.
It takes the optional keyword arguments (default): @code{grid-type}
(@code{*default-grid-type*}), @code{dimensions}
(@code{*default-dimensions*}), @code{element-type}
(@code{*default-element-type*}), @code{initial-element},
@code{initial-contents}.

Liam M. Healy's avatar
Liam M. Healy committed
536
537
538
539
@node Functions for creation of grids,  , Simple grids and default values, Creating a grid
@cindex Grid, creation functions
@cindex Functions for creation of grids
@subsection Functions for creation of grids
540
541
542
543
544
545
The functions @code{make-grid} and @code{make-foreign-array} are used to
make grids from specifications or parameters.  The functions
@code{map-grid} and @code{map-n-grids} can be used to create grids from
functions of indices.

@menu
546
547
* grid::
* make-simple-grid::                   
548
549
* make-grid::                   
* make-foreign-array::          
550
551
* ensure-foreign-array::          
* make-foreign-array-from-pointer::          
552
553
554
* Summary::                     
@end menu

Liam M. Healy's avatar
Liam M. Healy committed
555
@node grid, make-simple-grid, Functions for creation of grids, Functions for creation of grids
556
557
558
@subsubsection grid
@include include/fun-grid-grid.texinfo

Liam M. Healy's avatar
Liam M. Healy committed
559
@node  make-simple-grid, make-grid, grid, Functions for creation of grids
560
561
562
@subsubsection make-simple-grid
@include include/fun-grid-make-simple-grid.texinfo

Liam M. Healy's avatar
Liam M. Healy committed
563
@node make-grid, make-foreign-array, make-simple-grid, Functions for creation of grids
564
565
@subsubsection make-grid
@include include/fun-grid-make-grid.texinfo
566
567
568
569
570
571
572
573
574
575
576
577
This is used for making any kind of grid with the same value for each
element, or with literally specified values.  The first argument is a
specification, which has the form @code{((grid-type dimensions)
element-type)}.  The keyword arguments are @code{:initial-element} or
@code{:initial-contents}.  For example,
@example
(make-foreign-array 'double-float :dimensions 3 :initial-element 77.0d0)
#m(77.0d0 77.0d0 77.0d0)
(make-grid '((foreign-array 3) double-float) :initial-element 77.0d0)
#m(77.0d0 77.0d0 77.0d0)
@end example

Liam M. Healy's avatar
Liam M. Healy committed
578
@node make-foreign-array, ensure-foreign-array, make-grid, Functions for creation of grids
579
580
@subsubsection make-foreign-array
@include include/fun-grid-make-foreign-array.texinfo
581
582
583
This function can be used instead of @code{make-grid} to make a
foreign-array; the first argument is the @code{element-type} and the
@code{:dimensions} are supplied in a keyword argument, for example, 
584
585
586
587
588
589
590
591
@example
(grid:make-foreign-array 'double-float :dimensions '(2 2))
#m((0.000000000000000d0 .0000000000000000d0)
   (.0000000000000000d0 .0000000000000000d0))
@end example
It is meant as an analogue to @code{cl:make-array} for the convenience
of users who want to use a function with a similar argument list.

Liam M. Healy's avatar
Liam M. Healy committed
592
@node ensure-foreign-array, make-foreign-array-from-pointer, make-foreign-array, Functions for creation of grids
593
594
@subsubsection ensure-foreign-array
@include include/fun-grid-ensure-foreign-array.texinfo
595
596
597
598
599
600
601
If the first argument to this function is a foreign array, it is returned.  If it is not, the foreign array with the desired dimensions, element type, and initial-element is made and returned.
@example
(grid:ensure-foreign-array nil '(2 2) 'double-float)
#m((.0000000000000000d0 .0000000000000000d0)
   (.0000000000000000d0 .0000000000000000d0))
@end example

Liam M. Healy's avatar
Liam M. Healy committed
602
@node make-foreign-array-from-pointer, Summary, ensure-foreign-array, Functions for creation of grids
603
604
@subsubsection make-foreign-array-from-pointer
@include include/fun-grid-make-foreign-array-from-pointer.texinfo
605
If a foreign pointer already exist (for example, the foreign array was allocated by foreign code), this function will make a foreign array from it.  Note that the @code{cl-array} of this grid will always be @nil{}, regardless of whether static-vectors are supported for the CL implementation.
606

Liam M. Healy's avatar
Liam M. Healy committed
607
@node Summary,  , make-foreign-array-from-pointer, Functions for creation of grids
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
@subsubsection Summary: ways to make grids
@itemize
@item General
      @itemize
      @item @code{#m} reader macro
      @item @code{grid:grid}
      @item @code{grid:make-grid}
      @item @code{grid:make-simple-grid}
      @end itemize
@item Array
      @itemize
      @item @code{cl:make-array}
      @item @code{#} and @code{#2A} reader macros
      @end itemize
@item Foreign array
      @itemize
      @item @code{grid:make-foreign-array}
      @item @code{grid:ensure-foreign-array}
      @item @code{grid:make-foreign-array-from-pointer}
      @end itemize
@end itemize

630
@node Operations, Input and Output, Creating a grid, Grids
631
632
@section Operations

Liam M. Healy's avatar
Liam M. Healy committed
633
634
635
@cindex Functions, grid
@cindex Operations on grids
@cindex Grid, operations
636
637

@menu
638
639
640
* Elements::
* Copying::
* Iterate::
641
* Composition functions::       
642
* Mapping::                     
643
* Properties::
644
645
646
* AFFI::                        
@end menu

647
648
@node Elements, Copying, Operations, Operations
@subsection Elements
649
650
651
652
@include include/fun-grid-aref.texinfo
@include include/fun-grid-aref-star.texinfo
@include include/fun-grid-setf-aref.texinfo
@include include/fun-grid-setf-aref-star.texinfo
Liam M. Healy's avatar
Liam M. Healy committed
653
Individual elements are obtained using @code{grid:aref} (analogous to
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
Lisp's @code{cl:aref}), and are set with @code{setf grid:aref}.  For example,
@example
ANTIK-USER> (setf *default-grid-type* 'foreign-array)
ANTIK-USER> (defparameter *array* #m(2.0d0 1.0d0 -1.0d0))
ANTIK-USER> *array*
#m(2.000000000000000d0 1.000000000000000d0 -1.000000000000000d0)
ANTIK-USER> (grid:aref *array* 1)
1.0
ANTIK-USER> (setf (grid:aref *array* 1) 77.0d0)
77.0
ANTIK-USER> (grid:aref *array* 1)
77.0
ANTIK-USER> *array*
#m(2.000000000000000d0 77.000000000000000d0 -1.000000000000000d0)
@end example
669
670
671

@node Copying, Iterate, Elements, Operations
@subsection Copying
672
673
@include include/fun-grid-copy.texinfo
@include include/fun-grid-copy-to.texinfo
674
675
676
677
678
Copying is performed with the function @code{copy}.  This works between
@code{grid:foreign-array}s, pointers, and CL arrays.  There are two
functions provided to extract the dimensions of a vector or array:
@code{dim0} and @code{dim1}; the latter is applicable only for matrices.
To copy to a grid with the same dimensions and element type, use @code{copy-to}.
679

680
@node Iterate, Composition functions, Copying, Operations
681
@subsection Iterate
682
683
684
685
686
687
688
689
690
691
692
693
694
Extensions to the @url{http://common-lisp.net/project/iterate/,@command{iterate}}
system are provided.  The following @code{for} clause iterators are defined:
@itemize
@item @code{matrix-row}
@item @code{matrix-row-index}
@item @code{matrix-column}
@item @code{matrix-column-index}
@item @code{vector-element}
@item @code{vector-element-index}
@item @code{matrix-element}
@item @code{matrix-element-index}
@end itemize
For example,
695
696
697
698
699
700
@example
(defparameter m1 #m(1 2 3 ^ 0 6 8))
(iter:iter (iter:for e :matrix-element m1) (princ e) (princ " "))
1.0 2.0 3.0 0.0 0.0 6.0 8.0
@end example

701
702
703
704
705
The definitions are in the @command{grid-iterate-extension} extension
system which will automatically load if
@url{http://common-lisp.net/project/asdf-system-connections,@command{asdf-system-connnections}},
@url{http://common-lisp.net/project/iterate/,@command{iterate}}, and the
@command{Antik} system are loaded.
706

707
@node Composition functions, Mapping, Iterate, Operations
708
709
@subsection Composition functions
@menu
710
* codimension-one-subspace::
711
712
* column::               
* concatenate-grids::    
713
714
715
716
717
* diagonal::             
* drop::                 
* identity-matrix::
* matrix-from-columns::
* row::                  
718
719
* slice::                
* stride::                      
720
721
* subgrid::              
* transpose::            
722
723
724
* Vector products::             
@end menu

725
726
These functions transform or compose grids to make new grids.

727
728
@node codimension-one-subspace, column, Composition functions, Composition functions
@subsubsection codimension-one-subspace
Liam M. Healy's avatar
Liam M. Healy committed
729
@cindex Grid, subgrid of dimension one less
730
731
@include include/fun-grid-codimension-one-subspace.texinfo
@include include/fun-grid-setf-codimension-one-subspace.texinfo
732

733
734
@node column, concatenate-grids, codimension-one-subspace, Composition functions
@subsubsection column
Liam M. Healy's avatar
Liam M. Healy committed
735
736
737
@cindex Grid, column
@cindex Matrix, column
@cindex Column of grid or matrix
738
739
740
741

@include include/fun-grid-column.texinfo
@include include/fun-grid-setf-column.texinfo

742
743
744
The functions @code{column}, @code{(setf column)}
select or set the column of a matrix.
For example, the first column of the above array is 
745
746
747
748
749
@example
(column (test-grid-double-float 'array '(3 4)) 0)
#(0.0d0 10.0d0 20.0d0)
@end example

750
751
@node concatenate-grids, diagonal, column, Composition functions
@subsubsection concatenate-grids
Liam M. Healy's avatar
Liam M. Healy committed
752
753
@cindex Grid, concatenation
@cindex Concatenation of grids
754
755
756
757
758
@include include/fun-grid-concatenate-grids.texinfo
The function @code{concatenate-grids}
 is used to join two grids on an axis whose dimensions are
the same on the other axes.  For example, join two matrices by
adjoining their columns, all of the same length:
759
@example
760
761
762
763
764
765
766
767
768
769
(map-grid :source (offset-ifd 0.5d0) :source-dims '(3 4))
#2A((0.5d0 1.5d0 2.5d0 3.5d0)
    (10.5d0 11.5d0 12.5d0 13.5d0)
    (20.5d0 21.5d0 22.5d0 23.5d0))
(map-grid :source (offset-ifd 0.1d0) :source-dims '(3 2))
#2A((0.1d0 1.1d0) (10.1d0 11.1d0) (20.1d0 21.1d0))
(concatenate-grids ** * :axis 1)
#2A((0.5d0 1.5d0 2.5d0 3.5d0 0.1d0 1.1d0)
    (10.5d0 11.5d0 12.5d0 13.5d0 10.1d0 11.1d0)
    (20.5d0 21.5d0 22.5d0 23.5d0 20.1d0 21.1d0))
770
771
@end example

772
@node diagonal, drop, concatenate-grids, Composition functions
773
@subsubsection diagonal
Liam M. Healy's avatar
Liam M. Healy committed
774
775
776
@cindex Matrix, diagonal
@cindex Grid, diagonal
@cindex Diagonal of a grid
777
778
779
780
781

@include include/fun-grid-diagonal.texinfo
@include include/fun-grid-setf-diagonal.texinfo
@include include/fun-grid-set-diagonal.texinfo

782
783
784
785
786
787
The functions @code{diagonal}, @code{(setf diagonal)} (or @code{set-diagonal})
get or set the part of the grid where two indices are equal or differ by
a constant to another grid; that is, either the diagonal or a sub- or super-diagonal.
The diagonal of a grid can be set to a fixed value or to a function of its
indices. 

788
789
The diagonal is the collection of elements where there are two indices
equal, or differ by a fixed amount.  For a matrix (two dimensional
790
grid), this would be for example:
791
@example
792
793
794
795
ANTIK-USER> (grid::test-grid-double-float 'array '(3 4))
#2A((0.0 1.0 2.0 3.0) (10.0 11.0 12.0 13.0) (20.0 21.0 22.0 23.0))
ANTIK-USER> (diagonal @@)
#(0.0 11.0 22.0)
796
797
798
@end example
The superdiagonal is accessible with the same function, 
@example
799
800
ANTIK-USER> (diagonal (grid::test-grid-double-float 'array '(3 4)) :offset 1)
#(1.0 12.0 23.0)
801
802
803
@end example
as is the subdiagonal,
@example
804
805
ANTIK-USER> (diagonal (grid::test-grid-double-float 'array '(3 4)) :offset -1)
#(10.0 21.0)
806
807
@end example

808
809
@node drop, identity-matrix, diagonal, Composition functions
@subsubsection drop
Liam M. Healy's avatar
Liam M. Healy committed
810
@cindex Grid, removal of singleton axis
811
812
813
814
815
@include include/fun-grid-drop.texinfo

The function @code{drop} will remove singleton axes (axes with dimension one)
and create a grid of lower rank than the original grid.  For example, a
two-dimensional of dimensions 5 x 1
816
@example
817
818
819
820
821
822
823
824
825
826
827
(test-grid-double-float 'array '(5 1))
#2A((0.0d0) (10.0d0) (20.0d0) (30.0d0) (40.0d0))
@end example
will be converted to a vector (one dimensional array), 
@example
(drop (test-grid-double-float 'array '(5 1)))
#(0.0d0 10.0d0 20.0d0 30.0d0 40.0d0)
@end example

@node identity-matrix, matrix-from-columns, drop, Composition functions
@subsubsection identity-matrix
Liam M. Healy's avatar
Liam M. Healy committed
828
829
@cindex Identity matrix (constant diagonal)
@cindex Matrix, identity (constant diagonal)
830
831
832
833
834
@include include/fun-grid-identity-matrix.texinfo
The function @code{identity-matrix} will create a matrix that has the same number on each element of the diagonal and zeros for other elements.
@example
ANTIK-USER> (identity-matrix 3 8.0d0)
#2A((8.0 0.0 0.0) (0.0 8.0 0.0) (0.0 0.0 8.0))
835
836
@end example

837
838
839
840
841
842
@node matrix-from-columns, row, identity-matrix, Composition functions
@subsubsection matrix-from-columns
@include include/fun-grid-matrix-from-columns.texinfo

@node row, slice, matrix-from-columns, Composition functions
@subsubsection row
Liam M. Healy's avatar
Liam M. Healy committed
843
844
@cindex Row of matrix
@cindex Matrix, row
845
846
847
848
849
850
851
852
853
854
855
856
857
858

@include include/fun-grid-row.texinfo
@include include/fun-grid-setf-row.texinfo

The functions @code{row}, @code{(setf row)}
select or set the row of a matrix.
For example, select the second row from the matrix above:
@example
(row (test-grid-double-float 'array '(3 4)) 1)
#(10.0d0 11.0d0 12.0d0 13.0d0)
@end example

@node slice, stride, row, Composition functions
@subsubsection slice
Liam M. Healy's avatar
Liam M. Healy committed
859
@cindex Grid, slice
860
861
@include include/fun-grid-slice.texinfo
A @dfn{slice} is a subgrid selected by specifying index values.  They can be specified as a single value, range of values, or reversed values.
862
@example
863
864
865
(grid::test-grid-double-float 'array '(3 4))
#2A((0.0 1.0 2.0 3.0) (10.0 11.0 12.0 13.0) (20.0 21.0 22.0 23.0))
(slice (grid::test-grid-double-float 'array '(3 4)) '(1 (:range 0 2)) :drop nil)
866
867
868
#2A((10.0d0 11.0d0 12.0d0))
@end example

869
870
@node stride, subgrid, slice, Composition functions
@subsubsection stride
Liam M. Healy's avatar
Liam M. Healy committed
871
@cindex Grid, stride
872
@include include/fun-grid-stride.texinfo
873
874
875
876
877
878
879
880
881
A @dfn{stride} is the grid resulting from selection of elements at
regular intervals.
@example
(stride #(1 2 3 4 5 6 7 8) 3)
#(1 4 7)
@end example
The resultant grid will have rank one (vector) regardless of the source
rank. 

882
883
@node subgrid, transpose, stride, Composition functions
@subsubsection subgrid
Liam M. Healy's avatar
Liam M. Healy committed
884
@cindex Subgrid
885
886
887
888
889
890
891
892
893
@include include/fun-grid-subgrid.texinfo
@include include/fun-grid-setf-subgrid.texinfo
The functions @code{subgrid}, @code{(setf subgrid)} select or set a
region within a grid as a grid.  For example, The 2 by 2 block starting
at index 1,2 in the previous matrix is
@example
(subgrid (test-grid-double-float 'array '(3 4)) '(2 2) '(1 2))
#2A((12.0d0 13.0d0) (22.0d0 23.0d0))
@end example
894

895
896
897
@node transpose, Vector products, subgrid, Composition functions
@subsubsection transpose
@include include/fun-grid-transpose.texinfo
Liam M. Healy's avatar
Liam M. Healy committed
898
899
900
@cindex Transpose of grid
@cindex Grid, transpose
@cindex Matrix, transpose
901
902
903
The function @code{transpose} exchange elements paired by exchange of indices.
The grid can be of any rank greater than or equal to 2.
For example, the transpose of the above array is
904
@example
905
906
907
908
ANTIK-USER> (grid::test-grid-double-float 'array '(3 4))
#2A((0.0 1.0 2.0 3.0) (10.0 11.0 12.0 13.0) (20.0 21.0 22.0 23.0))
ANTIK-USER> (transpose @@)
#2A((0.0 10.0 20.0) (1.0 11.0 21.0) (2.0 12.0 22.0) (3.0 13.0 23.0))
909
@end example
910

911
@node Vector products,  , transpose, Composition functions
912
@subsubsection Vector products and norms
Liam M. Healy's avatar
Liam M. Healy committed
913
914
915
916
917
918
@cindex Cross product
@cindex Dot product
@cindex Inner product
@cindex Product, cross
@cindex Product, dot
@cindex Product, inner
919
920
921
922
923
924
925
@include include/fun-grid-cross.texinfo
@include include/fun-grid-euclidean.texinfo
@include include/fun-grid-inner.texinfo
@include include/fun-grid-norm.texinfo
@include include/fun-grid-normalize.texinfo

@node Mapping, Properties, Composition functions, Operations
926
@subsection Mapping
Liam M. Healy's avatar
Liam M. Healy committed
927
928
@cindex Mapping functions onto grid(s)
@cindex Grid, mapping functions
929
930
931
932
933
934
There are two more general functions @code{map-grid} and
@code{map-n-grids} on which the above functions are defined.  They will
provide the basis for any elementwise mapping of one (for the former) or
several (for the latter) grids into a destination grid.

@menu
935
936
937
* elementwise::
* map-grid::             
* map-n-grids::
938
939
@end menu

940
941
@node elementwise, map-grid, Mapping, Mapping
@subsubsection elementwise
Liam M. Healy's avatar
Liam M. Healy committed
942
943
@cindex Grid, applying function to each element
@cindex Elementwise application of function to grid
944
945
946
947
948
@include include/fun-grid-elementwise.texinfo

@node map-grid, map-n-grids, elementwise, Mapping
@subsubsection map-grid
@include include/fun-grid-map-grid.texinfo
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
Although this function has other uses, it can be used to create a grid
using a function of the index values.  For example, 
in the file @file{antik/grid/tests/grids.lisp} is a function
@code{index-fill-decadal} that multiplies increasing powers of ten by
each argument in succession, and adds the result.  The array
@code{*array-3-4-double-float*} is created with this function: 
@example
(defparameter *array-3-4-double-float*
  (map-grid :source 'index-fill-decadal :source-dims '(3 4)))
@end example
which gives
@example
*array-3-4-double-float*
#2A((0.0d0 1.0d0 2.0d0 3.0d0)
    (10.0d0 11.0d0 12.0d0 13.0d0)
    (20.0d0 21.0d0 22.0d0 23.0d0))
@end example
(see also the function 'test-grid-double-float).

Take the square root of every element of an array:
@example
(map-grid :source #m((0.0d0 1.0d0 2.0d0) (10.0d0 11.0d0 12.0d0) (20.0d0 21.0d0 22.0d0)) :element-function 'sqrt)
@end example
972
973
974
975
Make a foreign vector with each element the square root of its index:
@example
(map-grid :source 'sqrt :destination-specification '((foreign-array 6) double-float))
@end example
976

977
978
979
@node map-n-grids,  , map-grid, Mapping
@subsubsection map-n-grids
@include include/fun-grid-map-n-grids.texinfo
980
981
982
983
984
985
986
987
This is a more general form of @code{map-grid} which can take multiple
source grids, instead of only one.
For example, combine arrays a and b as a+2b:
@example
(map-n-grids :sources `((,#31m(1 2 3) nil) (,#31m(9 8 7) nil))
             :combination-function (lambda (a b) (+ a (* 2 b))))
@end example

988
989
990
991
992
993
994
995
@node Properties, AFFI, Mapping, Operations
@subsection Properties
These functions give properties of a grid.
@include include/fun-grid-contents.texinfo
@include include/fun-grid-dim0.texinfo
@include include/fun-grid-dim1.texinfo
@include include/fun-grid-dimensions.texinfo
@include include/fun-grid-gridp.texinfo
996
@include include/fun-grid-rank.texinfo
997
998
999
@include include/fun-grid-specification.texinfo

@node AFFI,  , Properties, Operations
1000
1001
1002
1003
@subsection AFFI
@code{extrude} will transform an AFFI into one that will make it appear
that the grid has an extra dimension.  This is useful in
e.g. @code{map-n-grids}.
1004

1005
1006
@node  Input and Output, Physical quantities, Operations, Grids
@section Input and Output
1007
1008
1009
@cartouche
Note: the definitions for reading and writing grids are at present minimal and incomplete.
@end cartouche
1010
1011
1012
1013
1014
1015
These definitions allow reading and writing of grids from and to files.
@include include/fun-grid-read-data-file.texinfo
@include include/fun-grid-read-data-stream.texinfo
@include include/fun-grid-read-vector-from-string.texinfo

@node Physical quantities, Capabilities and Internals, Input and Output, Grids
1016
@section Physical quantities
Liam M. Healy's avatar
Liam M. Healy committed
1017
1018
@cindex Physical dimension quantities in grids
@cindex Grid, with physical units
1019
1020
1021
1022
A grid may also be a physical quantity.  In this case, the magnitude is
a numeric grid, and the units are either scalar, meaning the same unit
applies to all numbers, or mixed, meaning that one set of units applies
to each element.
1023
1024
1025
1026
1027
1028
1029
@example
ANTIK-USER> #_#m(1.0 2.0 3.0)_km
#_#m(1000.000000000000000d0 2000.000000000000000d0 3000.000000000000000d0)_m
ANTIK-USER> #m(#_1.0_km #_2.0_s #_3.0_kg)
#m(#_1000.000000000000000d0_m #dPT2.000s #_3.000000000000000d0_kg)
@end example
See @ref{Physical Quantities} for more details on physical quantities, keeping in mind that whereever a scalar magnitude is shown there, a grid may be used instead.
1030

1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
@node Capabilities and Internals, Efficiency, Physical quantities, Grids
@section Capabilities and Internals
The capabilities of the foreign-array system depend on the CL implementation and the platform.  This section describes ways of obtaining information about the capabilities, and other internal information.  It will be of greatest interest to someone writing an interface to a foreign numeric library.

@menu
* Classes::
* Functions and Macros::
* Condition::
* Constants and Variables::
@end menu

@node Classes, Functions and Macros, Capabilities and Internals, Capabilities and Internals
@subsection Classes
Liam M. Healy's avatar
Liam M. Healy committed
1044
@cindex Class, foreign-array
1045
1046
1047
@include include/class-grid-foreign-array.texinfo
@include include/class-grid-matrix.texinfo
@include include/class-grid-mvector.texinfo
1048
The subclasses of either mvector or matrix are named with the element type, as described in the table in @ref{The foreign-array class}.
1049
1050
1051
1052
1053

@node Functions and Macros, Condition, Classes, Capabilities and Internals
@subsection Functions and Macros
@include include/fun-grid-all-types.texinfo
@include include/fun-grid-cffi-cl.texinfo
1054
@include include/fun-grid-check-dimensions.texinfo
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
@include include/fun-grid-cl-cffi.texinfo
@include include/fun-grid-data-class-name.texinfo
@include include/macro-grid-dcref.texinfo
@include include/fun-grid-element-size.texinfo
@include include/fun-grid-element-types.texinfo
@include include/fun-grid-element-type.texinfo
@include include/fun-grid-lookup-type.texinfo
@include include/macro-grid-metadata-slot.texinfo
@include include/fun-grid-number-class.texinfo
@include include/fun-grid-spec-scalar-p.texinfo
@include include/fun-grid-st-pointerp.texinfo

@node Condition, Constants and Variables, Functions and Macros, Capabilities and Internals
@subsection Condition
@include include/condition-grid-array-mismatch.texinfo

@node Constants and Variables,  , Condition, Capabilities and Internals
@subsection Constants and Variables
@include include/constant-grid-plus-foreign-pointer-class-plus.texinfo
@include include/constant-grid-plus-foreign-pointer-type-plus.texinfo
@include include/var-grid-star-array-element-types-no-complex-star.texinfo
@include include/var-grid-star-array-element-types-star.texinfo
@include include/var-grid-star-complex-types-star.texinfo
@include include/var-grid-star-cstd-cl-type-mapping-star.texinfo
@include include/var-grid-star-cstd-integer-types-star.texinfo
@include include/var-grid-star-double-types-star.texinfo
@include include/var-grid-star-float-complex-types-star.texinfo
@include include/var-grid-star-float-types-star.texinfo
@include include/var-grid-star-grid-types-star.texinfo
@include include/var-grid-star-print-contents-star.texinfo
@include include/var-grid-star-print-foreign-array-readably-star.texinfo

@node Efficiency,  , Capabilities and Internals, Grids
1088
1089
@section Efficiency

Liam M. Healy's avatar
Liam M. Healy committed
1090
1091
@cindex Efficiency of computation for grids
@cindex Grid, efficiency of computation
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
Access to elements of foreign arrays, for getting or setting, can be
very slow if they are not declared.  These declarations can take
@url{http://www.lispworks.com/documentation/HyperSpec/Body/03_c.htm,
several forms}: @command{declare}, @command{declaim},
@command{proclaim}, or @command{the}.  With the exception of the
@command{the} form, these declarations will only be effective in SBCL
and CCL.  Users of other implementations that support the environment
function
@url{http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node102.html,@command{variable-information}}
should contact the Antik maintainer to have support added.  If
declarations are present and the compiler honors the compiler macros
Liam M. Healy's avatar
Liam M. Healy committed
1103
that foreign-array defines, the @command{aref} and related forms are
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
macro-expanded directly into foreign array calls, considerably
increasing the speed of execution.

When using matrices, declarations with explicit dimensions are also
helpful for speed, e.g.
@example
(declare (type (grid:matrix-double-float 100 100) my-matrix new-matrix))
@end example

For setting array elements, it is better to use the macro @command{grid:gsetf}
than @command{setf} when declarations are present.  It is hoped that
eventually this macro can be eliminated.

For example, the declarations in the following function, and the use of
@command{grid:gsetf} instead of @command{setf}, help decrease the
execution time when running this function:
@example
(defun foreign-array-test (dim)
  (let ((input (grid:make-foreign-array
		'double-float
		:dimensions dim
		:initial-element 1.0d0))
	(output (grid:make-foreign-array 'double-float :dimensions dim)))
    (declare (type grid:vector-double-float input output))   ; declaration of foreign arrays
    (let ((tv0 0.0d0) (tv1 0.0d0))
      (declare (type double-float tv0 tv1))
      (iter (for i from 0 below dim)
	    (setf tv0 0.0d0)
	    (iter (for m from 0 to i)
		  (iter (for n from i below dim)
			(setf tv1 0.0d0)
			(iter (for k from m to n)
Liam M. Healy's avatar
Liam M. Healy committed
1136
			      (incf tv1 (grid:aref input k)))
1137
			(incf tv0 (expt tv1 -2))))
Liam M. Healy's avatar
Liam M. Healy committed
1138
	    (grid:gsetf (grid:aref* output i) (- (grid:aref input i) tv0))))))
1139
@end example
1140

1141
@node Physical Quantities, Numerical Output Format, Grids, Top
1142
@chapter Physical Quantities
Liam M. Healy's avatar
Liam M. Healy committed
1143
1144
@section Units

1145
@menu
1146
* Introduction to physical quantities::                
1147
* Physical dimension::          
1148
* Physical constants::
1149
* Date and time::               
1150
* Time arithmetic and time intervals::
1151
1152
@end menu

1153
@node Introduction to physical quantities, Physical dimension, Physical Quantities, Physical Quantities
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
@section Introduction

@dfn{Physical quantities} are numerical values that are used in science, engineering, and other numerical computations.  There are several aspects to them:
@itemize
@item They may have @dfn{physical dimension}, such as length, mass, time, etc.
@item They may have @dfn{attributes} related an object, such as the diameter of a circle.
@end itemize

The symbols defined for physical quantities are in the @code{antik}
@url{http://www.lispworks.com/documentation/HyperSpec/Body/11_aa.htm,package}.

1165
1166
Load the system @code{physical-dimension} for these definitions. If you wish to have the degree symbol, load the external system @code{cl-unicode}. If you need correct UT1, load the external system @code{drakma}. If you don't know what this is, you don't need it.

1167
@node Physical dimension, Physical constants, Introduction to physical quantities, Physical Quantities
1168
1169
1170
1171
@section Physical dimension

@menu
* About physical dimension::
1172
* Making physical dimension quantities::
1173
1174
1175
1176
* Dimensions::                  
* Systems of units::            
@end menu

1177
@node About physical dimension, Making physical dimension quantities, Physical dimension, Physical dimension
1178
@subsection Introduction
Liam M. Healy's avatar
Liam M. Healy committed
1179
@cindex Class, physical-quantity
1180
Antik has a class @code{physical-quantity} which is used to represent values that have physical dimension, such as mass or length; e.g.
1181
1182
1183
@example
ANTIK-USER> #_35_km
#_35000.000000000000000_m
1184
1185
1186
1187
1188
1189
ANTIK-USER> (* #_5_m #_8_kg)
#_40.000000000000000_m-kg
ANTIK-USER> (expt #_12_m 2)
#_144.000000000000000_m^2
(* #_5_kg #_8_m/s^2)
#_40.000000000000000d0_N
1190
@end example
1191
Mathematical operations are allowed on these objects,
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
@example
ANTIK-USER> (+ #_35_km #_12_miles)
#_54312.128000000000000_m
@end example
Of course, such math must be sensible,
@example
ANTIK-USER(3): (+ #_35_km #_12_kg)
debugger invoked on a SIMPLE-ERROR in thread #<THREAD "initial thread" RUNNING @{10040293F1@}>:
  The quantities 3.500d+4m and 12.00kg are not both physical quantities with the same physical dimension.
0] 
@end example
Note also that fractional exponents are acceptable: 
@example
ANTIK-USER> (expt #_16_m 1/2)
#_4.000000000000000_m^1/2
@end example

Each of these quantities has @dfn{units} associated with it -- meters,
kilograms, etc., and those units must be of the appropriate dimension
for the physical quantity.  All quantities are stored internally in the
SI system of units, and converted to desired units either when printed
or when an explicit conversion is requested.

The inspiration for this software came from
@url{http://www.cs.utexas.edu/users/novak/units95.html,Gordon Novak's work}.
Names, abbreviations, and definitions of units come from
@url{http://physics.nist.gov/cuu/Units/index.html,NIST}.

1220
1221
@node Making physical dimension quantities, Dimensions, About physical dimension, Physical dimension
@subsection Making physical dimension quantities
Liam M. Healy's avatar
Liam M. Healy committed
1222
1223
1224
@cindex Reader macro, physical dimension quantities
@cindex Physical dimension quantities, creating
@cindex Physical dimension quantities
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
There are two main ways to make physical quantities: the function @code{make-pq}, and the reader macro @code{#_}
@example
ANTIK-USER> (make-pq 24.5d0 'm/s)
#_24.500000000000000d0_m/s
ANTIK-USER> #_24.5_m/s
#_24.500000000000000d0_m/s
@end example
To get the magnitude and units of a physical quantity, use @code{pqval}.  It returns three values: the magnitude, units, and whether a single unit expression applies to all elements of the grid magnitude:
@example
ANTIK-USER> (pqval #_24.5_m/s)
24.5
(/ METER SECOND)
T
ANTIK-USER> (pqval #m(#_1.0_km #_2.0_s #_3.0_kg))
#m(1000.000000000000000d0 2.000000000000000d0 3.000000000000000d0)
#(METER SECOND KILOGRAM)
NIL
@end example

1244
1245
1246
1247
1248
1249
1250
1251
@include include/class-antik-physical-quantity.texinfo
@include include/fun-antik-check-dimension.texinfo
@include include/fun-antik-make-pq.texinfo
@include include/fun-antik-pqval.texinfo
@include include/macro-antik-with-pq.texinfo
@include include/var-antik-star-zero-is-dimensionless-star.texinfo

@node Dimensions, Systems of units, Making physical dimension quantities, Physical dimension
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
@subsection Dimensions
The fundamental physical dimensions handled by Antik are:
@itemize
@item length
@item time
@item mass 
@item temperature
@item current
@item substance
@item luminosity
@item money
@item angle
@end itemize
In addition, there are derived dimensions:
@itemize
@item force              
@item area               
@item volume             
@item power              
@item energy             
@item velocity           
@item momentum           
@item angular-momentum   
@item acceleration       
@item pressure           
@item density            
@item charge             
@item electric-potential 
@item capacitance        
@item resistance         
@item conductance        
@item magnetic-field     
@item magnetic-flux      
@item inductance         
@item frequency          
@item dose               
@end itemize

1290
1291
For units defined by Antik, see the source file @file{antik/physical-quantities/unit-definitions.lisp}.  Most of the common units for each of the listed physical dimension are defined, together with common abbreviations.

1292
1293
1294
@node Systems of units,  , Dimensions, Physical dimension
@subsection Systems of units
A @dfn{system of units} is a set of units, one for each of the physical dimensions that Antik can handle.  A system of units is needed by Antik for printing output and in special cases for converting physical quantities that have a physical dimension defined (e.g. length), but no units.  The system of units defined by 
1295
@code{(nf-option :system-of-units)} is used to determine the units in which the output is printed.  There are pre-defined several systems of units, @code{si}, @code{english}, @code{cgs}:
1296
1297
1298
1299
1300
@example
ANTIK-USER> (defparameter *length1* #_10_m)
*LENGTH1*
ANTIK-USER> *length1*
#_10.000000000000000_m
1301
1302
ANTIK-USER> (set-system-of-units :english)
; No value
1303
1304
1305
ANTIK-USER> *length1*
#_32.808398950131235_ft
@end example
1306
1307
So by setting the system of units, you can convert values as needed,
@example
1308
1309
ANTIK-USER> (set-system-of-units :si)
; No value
1310
1311
ANTIK-USER> #_12_feet
#_3.657600000000000d0_m
1312
ANTIK-USER> (set-system-of-units :english)
1313
1314
1315
ANTIK-USER> #_3_m
#_9.842519685039370d0_ft
@end example
1316

1317
A new system of units may be defined with @code{define-system-of-units}.  One need not define all physical dimensions, but if a unit is needed for a particular dimension and it's not defined, an error will be signalled.  For convenience, a system of units may be defined by augmentation of an existing system of units.  For example, suppose that you wish to have a system of units that is like SI except that lengths are measured in km instead of meters.  This will define such a system:
1318
@example
1319
(define-system-of-units kmdeg (km degree) si)
1320
1321
@end example

1322
The SI system is the initial system of units.
1323

1324
@include include/macro-antik-define-system-of-units.texinfo
1325
@include include/fun-antik-set-system-of-units.texinfo
1326
@include include/macro-antik-with-system-of-units.texinfo
1327
@include include/macro-antik-with-si-units.texinfo
1328

1329
1330
1331
1332
1333
@node Physical constants, Date and time, Physical dimension, Physical Quantities
@section Physical constants
It is possible to define physical constants which may then be used either in a mathematical expression or in a physical quantity definition
@example
ANTIK-USER> (define-physical-constant smoot
1334
    #_1.70180_m (ors) smoot
1335
1336
1337
1338
1339
1340
1341
  "The unit of length named after Oliver R. Smoot.")
ANTIK-USER> (* 3 smoot)
#_5.105399999999999d0_m
ANTIK-USER> #_3_ors
#_5.105399999999999d0_m
@end example

1342
1343
@include include/macro-antik-define-physical-constant.texinfo

1344
@node Date and time, Time arithmetic and time intervals, Physical constants, Physical Quantities
1345
@section Date and time
Liam M. Healy's avatar
Liam M. Healy committed
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
@cindex Class, date and time
@cindex Date
@cindex Time (of day)
@cindex Date and time, creating
@cindex Reader macro, date and time
@cindex ISO8601
@cindex UTC (coordinated universal time)
@cindex TAI (atomic time)
@cindex Coordinated Universal Time (UTC)
@cindex International Atomic Time (TAI)
@cindex UT1
@cindex Astronomical time (UT1)
@cindex Timezones
1359
Dates and times can be represented in Antik with the @code{timepoint} class.  A timepoint is a specific point in Newtonian time, so includes a date and time, and a @dfn{timescale} (best thought of as a timezone).  Timepoints are most conveniently made with the @dfn{#d} reader macro; the default timescale is @url{http://en.wikipedia.org/wiki/Coordinated_Universal_Time,UTC}, and the standard format for specification of timepoints is 
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
@url{http://en.wikipedia.org/wiki/ISO_8601,ISO 8601}
@example
ANTIK-USER> #d2011-08-04T12:00
2011-08-04 12:00:00.000
#d2011-08-04T12:00EST
2011-08-04 17:00:00.000
@end example
Other timescales available are
@url{http://en.wikipedia.org/wiki/UT1,UT1},
@url{http://en.wikipedia.org/wiki/International_Atomic_Time,TAI},
1370
1371
@url{http://en.wikipedia.org/wiki/GPS#Timekeeping,GPS}, and any of the customary
@url{http://en.wikipedia.org/wiki/List_of_time_zone_abbreviations,time zone abbreviations} that define offsets from UTC; these are listed in the variable @code{*timescales*}.
1372
In order to convert to and from UT1, it is necessary to obtain earth orientation parameters from the US Naval Observatory; if @dfn{*real-ut1-utc*} is @nil{}, then UT1 is taken the same as UTC.
1373

1374
The function @code{read-time} will read a timepoint or time interval in ISO8601 format.  Timepoints may be read in any format using the function @code{read-timepoint}.  The default is the @url{http://en.wikipedia.org/wiki/ISO_8601,ISO8601} format, with a broadened allowance for separators between the components.  A day without a specific time will be marked :day-only.  The function @code{read-us-date} is provided to read US-style dates (month/day/year).
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
@example
ANTIK-USER> (read-time "2011-08-04T12:00")
2011-08-04 12:00:00.000
ANTIK-USER> (read-time "1999?03/30    % 12-33-45")
1999-03-30 12:33:45.000
ANTIK-USER> (read-timepoint "20/12/2011" '(2 1 0)) ; Read a European-style date
2011-12-20
ANTIK-USER> (read-us-date "12/20/2000 3:41:12")
2000-12-20 03:41:12.000
ANTIK-USER> (read-us-date "12/20/11 3:41:12") ; Two-digit years are acceptable
2011-12-20 03:41:12.000
@end example
Dates are output in ISO8601 format.  The function @code{write-us-date} can be used to format in US style.

1389
@include include/class-antik-timepoint.texinfo
1390
@include include/var-antik-star-real-ut1-utc-star.texinfo
1391
1392
1393
1394
1395
1396
1397
@include include/fun-antik-read-time.texinfo
@include include/fun-antik-read-timepoint.texinfo
@include include/fun-antik-read-us-date.texinfo
@include include/fun-antik-write-us-date.texinfo

@node Time arithmetic and time intervals,  , Date and time, Physical Quantities
@section Time arithmetic and time intervals
Liam M. Healy's avatar
Liam M. Healy committed
1398
1399
1400
1401
@cindex Time arithmetic
@cindex Time intervals
@cindex Formatting, time
@cindex ISO8601
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
The difference of two timepoints may be used to compute a time interval, and an interval added to a timepoint to create another timepoint.  Intervals are ordinary physical dimension quantities with dimension of time, and may be format for input or output in several ways.  The reader macro @code{#d} and the function @code{read-time} will read in an interval in ISO8601 format; it should begin with ``P'' as required by that standard.

All components are of fixed size; for example, a month is 30 days, and a year is 12 months.  This may produce some odd-looking results because a year will have only 360 days.
@example
ANTIK-USER> (+ #d2011-08-01T12:00 #DP1m3d)
2011-09-03 12:00:00.000
ANTIK-USER> (- #d2011-09-03T12:00:00.000 #d2011-08-01T12:00)
#dP1m3dT
ANTIK-USER> (- #d2011-09-03T12:00:00.000 #d2010-09-03T12:00:00.000)
#dP1y5dT
@end example

1414
Formatting for an interval is specified by setting the nf parameter @code{:time} to @code{:tud} for an ISO8601 time unit designator, @code{:alternative} for the ISO8601 alternate, or @nil{} for the physical dimension time.  Default is @code{:tud}.
1415
1416
1417
1418
1419
1420
1421
1422
1423
@example
ANTIK-USER> (set-nf-options :time :tud)
ANTIK-USER> #_12345_seconds
#dPT3h25m45.000s
ANTIK-USER> (set-nf-options :time nil)
NIL
ANTIK-USER> #dP8m3dT5h
#_21013200.000000000000000d0_s
@end example
1424

1425
1426
@node Numerical Output Format, Mathematical Utility, Physical Quantities, Top
@chapter Numerical Output Format
Liam M. Healy's avatar
Liam M. Healy committed
1427
1428
1429
1430
1431
1432
1433
@cindex Formatting
@cindex Significant figures
@cindex Grid, formatting
@cindex Physical dimension quantities, formatting
@cindex Number, formatting
@cindex NF, table of options
The function @code{nf} is provided to format numbers according to specific criteria set as parameters in the @code{:nf} category (@pxref{Parameters}).  There is precise control over the number of digits printed, how grids are printed, etc.  To show all parameters available, evaluate @code{(parameter-help :nf)}; to get information about each one, @code{(parameter-help :nf @var{name})}.
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489

@multitable @columnfractions .15 .15 .7
@headitem Parameter @tab Values @tab Description
@item @code{components} @tab list of strings
@tab Names of vector components to use when @code{vector-format} is @code{:coordinate-unit-vectors}.
@item @code{date-time-separator} @tab @nil{}, @code{t}, character
@tab Character to place between date and time in ISO8601 datime output.
   If nil, use a space, if T, use #\T.
@item @code{degrees} @tab boolean
@tab Whether to format angles in degrees and angular rates in Hertz.
@item @code{fracpart-digits} @tab @nil{}, fixnum
@tab The number of digits to the right of the decimal floating point numbers when :significant-figures is @nil{}.
@item @code{full-precision} @tab @nil{}, @code{t}
@tab If not @nil{}, ignore @code{:fracpart-digits}, @code{:intpart-digits}, @code{:significant-figures}, and format floating point numbers to full precision.
@item @code{horizontal-element-separator} @tab character
@tab What to put between horizontally separated elements for plain style.
@item @code{ignore-day-only} @tab boolean
@tab If true, a timepoint specified day-only will show the time part as well.
@item @code{intpart-digits} @tab @nil{}, fixnum
@tab The minimum space allowed for the whole-number part of numbers
   when :significant-figures is @nil{}.  If this is larger than
   the actual number of digits, pad to the left with spaces.
   If this value is @nil{}, allow enough space to accomodate the number.
@item @code{no-units} @tab boolean
@tab Don't print units if true.
@item @code{print-sign} @tab boolean
@tab Whether leading `+' is printed.
@item @code{significant-figures} @tab @nil{}, fixnum
@tab The number of significant figures formatted for numbers.
   If @nil{}, formatting of numbers is done using :intpart-digits
   and, if a float, :fracpart-digits.
@item @code{style} @tab @nil{}, @code{:tex}, fixnum
@tab Style of format: plain (standard or shortened) or LaTeX.
@item @code{tex-decimal-align} @tab boolean
@tab Align columns of numbers on decimal point in LaTeX.
@item @code{tex-element-separator} @tab string
@tab Character to put between vertically separated matrix rows for LaTeX.
@item @code{time} @tab @nil{},@code{:tud},@code{:alternative}
@tab How to format time intervals: with unit for time (@nil{}), ISO8601 time-unit designator (@code{:tud}), ISO8601 alternative (@code{:alternative}).
@item @code{timepoint-linear} @tab symbol, list
@tab Convert timepoints to a linear scale if specified as a list of epoch time and unit.  For example @code{'(*midnight-2000* :year)} will present time points as a real number of calendar years, including fractions, such as 3.3223.  If the value is a symbol representing a unit, like :year, the epoch is taken as 0.
@item @code{vector-format} @tab @code{:horizontal}, @code{:vertical}, @code{:coordinate-unit-vectors}
@tab Vectors are formatted as rows, columns or as linear combination of coordinate unit vectors.
@item @code{vertical-element-separator} @tab character
@tab Character to put between vertically separated elements for plain.
@end multitable

@include include/fun-antik-nf.texinfo
@include include/macro-antik-nf-option.texinfo
@include include/fun-antik-nf-readably.texinfo
@include include/fun-antik-nf-string.texinfo
@include include/macro-antik-set-nf-options.texinfo
@include include/macro-antik-with-nf-options.texinfo
@include include/fun-antik-object-as-nf.texinfo

@node Mathematical Utility, Three Dimensional Space, Numerical Output Format, Top
1490
@chapter Mathematical Utility
1491
This system has definitions for mathematical utilities.  
1492
1493
@include include/fun-antik-angle-law-of-cosines.texinfo
@include include/fun-antik-prime-factors.texinfo
1494
Load the system @code{mathematics} for these definitions.
1495

1496
@node Three Dimensional Space, Mathematics, Mathematical Utility, Top
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
@chapter Three Dimensional Space
This module has definitions related to Cartesian 3-space and rotations.

@menu
* Cartesian::
* Polar::
* Rotation::
@end menu

@node Cartesian, Polar, Three Dimensional Space, Three Dimensional Space
@section Cartesian
Liam M. Healy's avatar
Liam M. Healy committed
1508
1509
@cindex Cartesian space
@cindex Functions, Cartesian space
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
@include include/fun-antik-coordinate-unit-vector.texinfo
@include include/fun-antik-coplanar.texinfo
@include include/fun-antik-distance.texinfo
@include include/fun-antik-first-3vector.texinfo
@include include/fun-antik-right-angle.texinfo
@include include/fun-antik-second-3vector.texinfo
@include include/fun-antik-vector-angle.texinfo

@node Polar, Rotation, Cartesian, Three Dimensional Space
@section Polar