\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename antik.info
@settitle Antik Manual
@c %**end of header
@macro &optional {}
&optional
@end macro
@macro &key {}
&key
@end macro
@macro &rest {}
&rest
@end macro
@macro &body {}
&body
@end macro
@macro &allow-other-keys {}
&allow-other-keys
@end macro
@macro nil {} @code{nil}
@end macro
@include macros.texinfo
@copying
Copyright @copyright{} 2009, 2010, 2011, 2013 Liam M. Healy
@end copying
@titlepage
@title Antik
@page
@vskip 0pt plus 1filll
@c@insertcopying@node
@end titlepage
@ifnottex
@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
@menu
* Introduction::
* Mathematics::
* Organization of Computation::
* Grids::
* Physical Quantities::
* Numerical Output Format::
* Mathematical Utility::
* Three Dimensional Space::
* Mathematics::
* Internals::
* Download and installation::
* Copying this software::
* Index::
@end menu
@c Removed the "detailed menu" (at end of this file) because it's too much clutter.
@top Antik
This is the manual for the use of Antik, which provides a foundation for
scientific and engineering computing in Common Lisp.
@insertcopying
@end ifnottex
@c Output the table of the contents at the beginning.
@contents
@node Introduction, Mathematics, Top, Top
@chapter Introduction
@cindex GSLL
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.
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.
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.
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
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.
@node Mathematics, Organization of Computation, Introduction, Top
@chapter Mathematics
@menu
* Generic Functions::
* Conditions::
@end menu
@node Generic Functions, Conditions, Mathematics, Mathematics
@section Generic Functions
@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
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
@cindex Conditions for numerical computation
@cindex Handler for conditions
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
@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.
@node Organization of Computation, Grids, Mathematics, Top
@chapter Organization of Computation
@cindex Notebook, computation
@cindex Logbook of computation
@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.
Load the system @code{input-output} for these definitions.
@node Parameters, , Introduction to organization, Organization of Computation
@section Parameters
@cindex Parameters
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.
@example
;;; Then define some parameters
(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.")
;;; 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
(with-parameters (kepler (foo 143) (bar "bye"))
(show-foo-bar))
foo: 143, bar: "bye"
NIL
(show-foo-bar)
foo: 122, bar: "hi"
NIL
;;; Make a mistake
(with-parameters (kepler (foo 143) (bar -44))
(show-foo-bar))
Error: Value -44 is of type FIXNUM, not of the required type STRING.
;;; Globally change values
(setf (parameter-value kepler bar) "a new value")
(show-foo-bar)
foo: 122, bar: "a new value"
;;; Set multiple values
(set-parameters kepler bar "xyz" foo 1)
(show-foo-bar)
foo: 1, bar: "xyz"
;;; Get information about the categories and parameters
(parameter-help)
Parameter categories: KEPLER and NF.
(parameter-help :kepler)
Parameters in KEPLER: BAR and FOO.
(parameter-help :kepler :bar)
BAR: A string parameter of kepler.
Type is STRING,
Current value is "xyz".
@end example
@include include/macro-antik-define-parameter.texinfo
@include include/fun-antik-parameter-help.texinfo
@include include/macro-antik-parameter-value.texinfo
@include include/macro-antik-set-parameter.texinfo
@include include/macro-antik-set-parameters.texinfo
@include include/macro-antik-with-parameters.texinfo
@node Grids, Physical Quantities, Organization of Computation, Top
@chapter Grids
@cindex Vectors
@cindex Matrices
@cindex Arrays
@menu
* Introduction to grids::
* Creating a grid::
* Operations::
* Input and Output::
* Physical quantities::
* Capabilities and Internals::
* Efficiency::
@end menu
@node Introduction to grids, Creating a grid, Grids, Grids
@section Introduction to grids
Load the system @code{grid} for these definitions.
@menu
* The grid concept::
* Types of grids::
* Package::
* Tests::
@end menu
@node The grid concept, Types of grids, Introduction to grids, Introduction to grids
@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
of the definitions here however do not force this to be the case.
The @dfn{rank} of a grid is the number of Cartesian axes, and the
@dfn{dimensions} are a sequence of non-negative integers of length equal
to the rank that give the number of index values possible along each
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
@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
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.
@node Package, Tests, Types of grids, Introduction to grids
@subsection Package
The symbols defined here are in the @code{grid}
@url{http://www.lispworks.com/documentation/HyperSpec/Body/11_aa.htm,package}.
@node Tests, , Package, Introduction to grids
@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
(in-package :antik)
(lisp-unit:run-tests)
(in-package :grid)
(lisp-unit:run-tests)
@end example
@node Creating a grid, Operations, Introduction to grids, Grids
@section Creating a grid
@cindex Grid, creating
@cindex Creating a grid
@menu
* Reader macro and function @code{grid}::
* The foreign-array class::
* Simple grids and default values::
* Functions for creation of grids::
@end menu
@node Reader macro and function @code{grid}, The foreign-array class, Creating a grid, Creating a grid
@cindex Reader macro, grid
@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
@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.
@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
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
@cindex Reader macro, array
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}.
@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
@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
The @command{foreign-array} class
uses @url{http://common-lisp.net/project/cffi/,@command{CFFI}} to allow the use
of C arrays as grids. Load the system @code{foreign-array} to enable use of foreign arrays.
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
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:
@example
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)
ANTIK-USER> (setf (grid:aref *my-fa* 1) 33.3d0)
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)
ANTIK-USER> (setf (aref (cl-array *my-fa*) 1) 22.2d0)
22.2
ANTIK-USER> *my-fa*
#m(0.000000000000000d0 22.200000000000000d0 2.000000000000000d0)
@end example
@node Simple grids and default values, Functions for creation of grids, The foreign-array class, Creating a grid
@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}.
@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
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
* grid::
* make-simple-grid::
* make-grid::
* make-foreign-array::
* ensure-foreign-array::
* make-foreign-array-from-pointer::
* Summary::
@end menu
@node grid, make-simple-grid, Functions for creation of grids, Functions for creation of grids
@subsubsection grid
@include include/fun-grid-grid.texinfo
@node make-simple-grid, make-grid, grid, Functions for creation of grids
@subsubsection make-simple-grid
@include include/fun-grid-make-simple-grid.texinfo
@node make-grid, make-foreign-array, make-simple-grid, Functions for creation of grids
@subsubsection make-grid
@include include/fun-grid-make-grid.texinfo
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
@node make-foreign-array, ensure-foreign-array, make-grid, Functions for creation of grids
@subsubsection make-foreign-array
@include include/fun-grid-make-foreign-array.texinfo
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,
@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.
@node ensure-foreign-array, make-foreign-array-from-pointer, make-foreign-array, Functions for creation of grids
@subsubsection ensure-foreign-array
@include include/fun-grid-ensure-foreign-array.texinfo
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
@node make-foreign-array-from-pointer, Summary, ensure-foreign-array, Functions for creation of grids
@subsubsection make-foreign-array-from-pointer
@include include/fun-grid-make-foreign-array-from-pointer.texinfo
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.
@node Summary, , make-foreign-array-from-pointer, Functions for creation of grids
@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
@node Operations, Input and Output, Creating a grid, Grids
@section Operations
@cindex Functions, grid
@cindex Operations on grids
@cindex Grid, operations
@menu
* Elements::
* Copying::
* Iterate::
* Composition functions::
* Mapping::
* Properties::
* AFFI::
@end menu
@node Elements, Copying, Operations, Operations
@subsection Elements
@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
Individual elements are obtained using @code{grid:aref} (analogous to
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
@node Copying, Iterate, Elements, Operations
@subsection Copying
@include include/fun-grid-copy.texinfo
@include include/fun-grid-copy-to.texinfo
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}.
@node Iterate, Composition functions, Copying, Operations
@subsection Iterate
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,
@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
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.
@node Composition functions, Mapping, Iterate, Operations
@subsection Composition functions
@menu
* codimension-one-subspace::
* column::
* concatenate-grids::
* diagonal::
* drop::
* identity-matrix::
* matrix-from-columns::
* row::
* slice::
* stride::
* subgrid::
* transpose::
* Vector products::
@end menu
These functions transform or compose grids to make new grids.
@node codimension-one-subspace, column, Composition functions, Composition functions
@subsubsection codimension-one-subspace
@cindex Grid, subgrid of dimension one less
@include include/fun-grid-codimension-one-subspace.texinfo
@include include/fun-grid-setf-codimension-one-subspace.texinfo
@node column, concatenate-grids, codimension-one-subspace, Composition functions
@subsubsection column
@cindex Grid, column
@cindex Matrix, column
@cindex Column of grid or matrix
@include include/fun-grid-column.texinfo
@include include/fun-grid-setf-column.texinfo
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
@example
(column (test-grid-double-float 'array '(3 4)) 0)
#(0.0d0 10.0d0 20.0d0)
@end example
@node concatenate-grids, diagonal, column, Composition functions
@subsubsection concatenate-grids
@cindex Grid, concatenation
@cindex Concatenation of grids
@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:
@example
(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))
@end example
@node diagonal, drop, concatenate-grids, Composition functions
@subsubsection diagonal
@cindex Matrix, diagonal
@cindex Grid, diagonal
@cindex Diagonal of a grid
@include include/fun-grid-diagonal.texinfo
@include include/fun-grid-setf-diagonal.texinfo
@include include/fun-grid-set-diagonal.texinfo
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.
The diagonal is the collection of elements where there are two indices
equal, or differ by a fixed amount. For a matrix (two dimensional
grid), this would be for example:
@example
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)
@end example
The superdiagonal is accessible with the same function,
@example
ANTIK-USER> (diagonal (grid::test-grid-double-float 'array '(3 4)) :offset 1)
#(1.0 12.0 23.0)
@end example
as is the subdiagonal,
@example
ANTIK-USER> (diagonal (grid::test-grid-double-float 'array '(3 4)) :offset -1)
#(10.0 21.0)
@end example
@node drop, identity-matrix, diagonal, Composition functions
@subsubsection drop
@cindex Grid, removal of singleton axis
@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
@example
(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
@cindex Identity matrix (constant diagonal)
@cindex Matrix, identity (constant diagonal)
@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))
@end example
@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
@cindex Row of matrix
@cindex Matrix, row
@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
@cindex Grid, slice
@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.
@example
(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)
#2A((10.0d0 11.0d0 12.0d0))
@end example
@node stride, subgrid, slice, Composition functions
@subsubsection stride
@cindex Grid, stride
@include include/fun-grid-stride.texinfo
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.
@node subgrid, transpose, stride, Composition functions
@subsubsection subgrid
@cindex Subgrid
@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
@node transpose, Vector products, subgrid, Composition functions
@subsubsection transpose
@include include/fun-grid-transpose.texinfo
@cindex Transpose of grid
@cindex Grid, transpose
@cindex Matrix, transpose
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
@example
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))
@end example
@node Vector products, , transpose, Composition functions
@subsubsection Vector products and norms
@cindex Cross product
@cindex Dot product
@cindex Inner product
@cindex Product, cross
@cindex Product, dot
@cindex Product, inner
@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
@subsection Mapping
@cindex Mapping functions onto grid(s)
@cindex Grid, mapping functions
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
* elementwise::
* map-grid::
* map-n-grids::
@end menu
@node elementwise, map-grid, Mapping, Mapping
@subsubsection elementwise
@cindex Grid, applying function to each element
@cindex Elementwise application of function to grid
@include include/fun-grid-elementwise.texinfo
@node map-grid, map-n-grids, elementwise, Mapping
@subsubsection map-grid
@include include/fun-grid-map-grid.texinfo
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
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
@node map-n-grids, , map-grid, Mapping
@subsubsection map-n-grids
@include include/fun-grid-map-n-grids.texinfo
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
@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
@include include/fun-grid-rank.texinfo
@include include/fun-grid-specification.texinfo
@node AFFI, , Properties, Operations
@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}.
@node Input and Output, Physical quantities, Operations, Grids
@section Input and Output
@cartouche
Note: the definitions for reading and writing grids are at present minimal and incomplete.
@end cartouche
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
@section Physical quantities
@cindex Physical dimension quantities in grids
@cindex Grid, with physical units
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.
@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.
@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
@cindex Class, foreign-array
@include include/class-grid-foreign-array.texinfo
@include include/class-grid-matrix.texinfo
@include include/class-grid-mvector.texinfo
The subclasses of either mvector or matrix are named with the element type, as described in the table in @ref{The foreign-array class}.
@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
@include include/fun-grid-check-dimensions.texinfo
@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
@section Efficiency
@cindex Efficiency of computation for grids
@cindex Grid, efficiency of computation
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
that foreign-array defines, the @command{aref} and related forms are
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)
(incf tv1 (grid:aref input k)))
(incf tv0 (expt tv1 -2))))
(grid:gsetf (grid:aref* output i) (- (grid:aref input i) tv0))))))
@end example
@node Physical Quantities, Numerical Output Format, Grids, Top
@chapter Physical Quantities
@section Units
@menu
* Introduction to physical quantities::
* Physical dimension::
* Physical constants::
* Date and time::
* Time arithmetic and time intervals::
@end menu
@node Introduction to physical quantities, Physical dimension, Physical Quantities, Physical Quantities
@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}.
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.
@node Physical dimension, Physical constants, Introduction to physical quantities, Physical Quantities
@section Physical dimension
@menu
* About physical dimension::
* Making physical dimension quantities::
* Dimensions::
* Systems of units::
@end menu
@node About physical dimension, Making physical dimension quantities, Physical dimension, Physical dimension
@subsection Introduction
@cindex Class, physical-quantity
Antik has a class @code{physical-quantity} which is used to represent values that have physical dimension, such as mass or length; e.g.
@example
ANTIK-USER> #_35_km
#_35000.000000000000000_m
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
@end example
Mathematical operations are allowed on these objects,
@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 #:
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}.
@node Making physical dimension quantities, Dimensions, About physical dimension, Physical dimension
@subsection Making physical dimension quantities
@cindex Reader macro, physical dimension quantities
@cindex Physical dimension quantities, creating
@cindex Physical dimension quantities
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
@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
@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
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.
@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
@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}:
@example
ANTIK-USER> (defparameter *length1* #_10_m)
*LENGTH1*
ANTIK-USER> *length1*
#_10.000000000000000_m
ANTIK-USER> (set-system-of-units :english)
; No value
ANTIK-USER> *length1*
#_32.808398950131235_ft
@end example
So by setting the system of units, you can convert values as needed,
@example
ANTIK-USER> (set-system-of-units :si)
; No value
ANTIK-USER> #_12_feet
#_3.657600000000000d0_m
ANTIK-USER> (set-system-of-units :english)
ANTIK-USER> #_3_m
#_9.842519685039370d0_ft
@end example
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:
@example
(define-system-of-units kmdeg (km degree) si)
@end example
The SI system is the initial system of units.
@include include/macro-antik-define-system-of-units.texinfo
@include include/fun-antik-set-system-of-units.texinfo
@include include/macro-antik-with-system-of-units.texinfo
@include include/macro-antik-with-si-units.texinfo
@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
#_1.70180_m (ors) smoot
"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
@include include/macro-antik-define-physical-constant.texinfo
@node Date and time, Time arithmetic and time intervals, Physical constants, Physical Quantities
@section Date and time
@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
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
@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},
@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*}.
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.
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).
@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.
@include include/class-antik-timepoint.texinfo
@include include/var-antik-star-real-ut1-utc-star.texinfo
@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
@cindex Time arithmetic
@cindex Time intervals
@cindex Formatting, time
@cindex ISO8601
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
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}.
@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
@node Numerical Output Format, Mathematical Utility, Physical Quantities, Top
@chapter Numerical Output Format
@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})}.
@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
@chapter Mathematical Utility
This system has definitions for mathematical utilities.
@include include/fun-antik-angle-law-of-cosines.texinfo
@include include/fun-antik-prime-factors.texinfo
Load the system @code{mathematics} for these definitions.
@node Three Dimensional Space, Mathematics, Mathematical Utility, Top
@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
@cindex Cartesian space
@cindex Functions, Cartesian space
@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
@cindex Polar coordinates
@cindex Rectangular coordinates
@cindex Functions, polar/rectangular conversion
@include include/fun-antik-polar-to-rectangular.texinfo
@include include/fun-antik-rectangular-to-polar.texinfo
@node Rotation, , Polar, Three Dimensional Space
@section Rotation
@cindex Rotation in two and three dimensions
@cindex Functions, rotation
@include include/fun-antik-euler-angle-rotation.texinfo
@include include/fun-antik-rotate.texinfo
@include include/fun-antik-rotate-3d.texinfo
@include include/fun-antik-rotate-3daa.texinfo
@include include/fun-antik-tait-bryan-angles.texinfo
@include include/fun-antik-tait-bryan-rotation.texinfo
@node Mathematics, Internals, Three Dimensional Space, Top
@chapter Mathematics
@cindex GSLL
@cindex Higher mathematics using external libraries
These functions provide a more straightforward interface to foreign libraries like @url{http://common-lisp.net/project/gsll/,GSLL}. For example, GSLL supplies several functions to invert a matrix, but the function defined here @code{invert-matrix} uses LU decomposition with all the necessary preparation.
Load the systems @code{mathematics} and @code{GSLL} for these definitions.
@menu
* Linear Algebra::
* Optimization::
@end menu
@node Linear Algebra, Optimization, Mathematics, Mathematics
@section Linear Algebra
@cindex Linear Algebra
@cindex GSLL
@cindex Functions, linear algebra
These functions require that @url{http://common-lisp.net/project/gsll/,GSLL} be loaded.
@include include/fun-antik-determinant.texinfo
@include include/fun-antik-invert-matrix.texinfo
@node Optimization, , Linear Algebra, Mathematics
@section Optimization
@cindex Mathematical optimization
@cindex Optimization, mathematical
@cindex Functions, mathematical optimization
These functions require that GSLL be loaded.
@include include/fun-antik-maximize-1d.texinfo
@include include/fun-antik-minimize-1d.texinfo
@include include/fun-antik-root-1d.texinfo
@node Internals, Download and installation, Mathematics, Top
@chapter Internals
@cindex Internals of Antik
This chapter describes some of the designs used internally, for the benefit of those who wish to port libraries to use some of the definitions in Antik, or those who are merely curious. If you wish to simply use Antik, you can skip this chapter.
@menu
* Foreign Library Kit::
* Antik tests::
@end menu
@node Foreign Library Kit, Antik tests, Internals, Internals
@section Foreign Library Kit
@cindex Foreign array metadata
Antik is designed with the idea that scientific and engineering libraries, particularly foreign (non-Lisp) libraries, can easily be integrated, so that data can be exchanged with and among the libraries. Function and other definitions, when duplicated, will be named the same, differing only in the package. For example, if libraries @samp{foo} and @samp{bar} both define a singular value decomposition (SVD), they would use the function names @code{foo:sv-decomposition} and @code{bar:sv-decomposition}, and the arguments would be as similar as possible. Then a user may call either one on a matrix (two-dimensional) grid, and compare results.
To facilitate the exchange of foreign arrays, the class @code{grid:foreign-array} has a slot @code{grid::foreign-metadata}. The interface code for a foreign library can save information there as a plist that the library needs in order to use the array, such as the dimensions.
@node Antik tests, , Foreign Library Kit, Internals
@section Antik tests
Regression (unit) tests are available for both @code{antik} and @code{grid} if the @url{http://www.cliki.net/lisp-unit,lisp-unit} system is installed,
@node Download and installation, Copying this software, Internals, Top
@chapter Download and installation
@cindex Installation of Antik
@cindex Download of Antik
@cindex Dependencies of Antik on external libraries
The recommended way to download and install this software is through
@url{http://www.quicklisp.org/,quicklisp}. Install quicklisp following
the directions, then do one of:
@example
(ql:quickload "antik")
@end example
Users that need the very latest version will need to fetch the
repository via git. The @url{http://repo.or.cz/w/antik.git,gitweb page}
gives a view of the commit history and information on cloning. To
clone,
@example
git clone @url{git://repo.or.cz/antik.git}
@end example
The @code{Antik} system depends on
@itemize
@item
@url{http://common-lisp.net/project/alexandria/,alexandria}
@url{http://common-lisp.net/project/cffi/,cffi},
@url{http://www.cliki.net/trivial-garbage,trivial-garbage}, and
@url{http://www.cliki.net/SPLIT-SEQUENCE,split-sequence}.
In addition, there are two optional systems,
@url{http://repo.or.cz/w/fsbv.git,FSBV}, which permits usage of foreign
arrays of complex number elements, and
@url{http://gitorious.org/iolib/static-vectors,static-vectors} gives
foreign arrays a native Lisp view via the function @code{cl-array} for
foreign arrays made in Lisp (not created in foreign code) for supported
implementations (currently SBCL, CCL, ECL, LispWorks, and Allegro).
@end itemize
Note: FSBV is for the time being mandatory. Only one file is needed, and no foreign libraries, but until it is split into two separate systems, the whole thing must be loaded.
@node Copying this software, Index, Download and installation, Top
@chapter Copying
@cindex Copying Antik software
All code and documentation in this collection is copyright as indicated
at the top of this document. It may be copied under the
@url{http://www.gnu.org/licenses/gpl.html,GPL v3}.
@node Index, , Copying this software, Top
@unnumbered Index
@c what is the condition index?
Concept index
@printindex cp
Function and Macro index
@printindex fn
Constants and Variables index
@printindex vr
@bye
@c********************************************************************************
@c I find this too much clutter
@c********************************************************************************
@detailmenu
--- The Detailed Node Listing ---
Grids
* Introduction to grids::
* Creating a grid::
* Operations::
* Physical quantities::
* Efficiency::
Introduction
* The grid concept::
* Types of grids::
* Package::
* Tests::
Creating a grid
* Reader macro and function @code{grid}::
* The foreign-array class::
* Simple grids and default values::
* Functions for creation of grids::
Functions for creation of grids
* make-grid::
* make-foreign-array::
* ensure-foreign-array::
* make-foreign-array-from-pointer::
* Summary::
Operations
* Summary of defined operations::
* Mapping::
* AFFI::
* Composition functions::
Mapping
* @code{map-grid}::
* @code{map-n-grids}::
Composition functions
* drop::
* row::
* column::
* subgrid::
* transpose::
* diagonal::
* concatenate-grids::
* slice::
* stride::
* Vector products::
Physical Quantities
* Introduction::
* Physical dimension::
* Date and time::
Physical dimension
* Introduction::
* Dimensions::
* Systems of units::
Internals
* Foreign Library Kit::
@end detailmenu