///////////////////////////////////////////////////////////////////////////////

yeti.txt -

	Documentation for Yeti: a Yorick extension.

	Copyright (C) 2006, Eric Thibaut.

	$Id$
	$Log$

///////////////////////////////////////////////////////////////////////////////

Yeti: a Yorick extension
========================
Eric Thiébaut
v6.1.8, December 2006
:encoding: UTF-8
:iconsdir: ./pics


Description
-----------

Yeti is an extension of Yorick (a fast interpreted interactive data
processing language written by David Munro) which implements (see QUICK
REFERENCE below for a list of additional functions):

 * hash table objects
 * regular expressions
 * complex, real-complex and complex-real FFT by FFTW (the Fastest Fourier
   Transform in the West - version 2)
 * wavelet filtering ("à trou" method)
 * fast convolution along a chosen dimension with various border conditions
 * more string functions
 * memory hacking routines
 * more math functions (sinc, round, arc)
 * generalized matrix-vector multiplication (with possibly sparse matrix)
 * routines to query/check Yorick's symbols
 * support for reading TIFF images
 * morpho-math operators
 * 120 special functions from GSL (the GNU Scientific Library)
 * ...

This distribution of Yeti may come with several extensions (depending
whether corresponding directories exist or not):

 * *yeti_fftw* - support for FFTW
 * *yeti_gsl* - implements special functions from GSL
 * *yeti_regex* - support for POSIX regular expressions
 * *yeti_tiff* - support for reading TIFF images



Compilation and Installation of Yeti Software Suite
---------------------------------------------------

Starting with version 6.0.0, Yeti is built as a regular Yorick plugin
and some of the Yeti extensions are built as standalone Yorick plugins
(they do not require Yeti to be used).  The installation of Yeti
depends on that of Yorick which must have been installed prior to
Yeti.  You'll need at least version 1.6.02 of Yorick (for Yorick
version 1.5, you can install Yeti 5.3).  You can have a look at
accompanying file "BUILD-YORICK" to see how to build and install
Yorick.

The first installation step consists in the configuration of Yeti
software suite.  This is done via the `./config.i` script.  In order
to figure out the different options (and their default values), you
can just do:

-------------------------------
yorick -batch ./config.i --help
-------------------------------

where `yorick` can also be the full path of the particular Yorick
executable you want to use for building Yeti.  At least version 1.6 of
Yorick is required to configure/build Yeti.

By default, Yeti is configured so as to be built as a plugin for the
executable used to run the `./config.i` script.  You can however
specify a different Yorick executable with option `--yorick=PATH`.  If
you have different versions of Yorick installed, you can
configure/build/install different versions of Yeti by runnning the
configure script with option `--yorick` set to the full path name of the
considered Yorick executable.

If you want Yeti plugin for extended regular support, you'll have the
choice to use a system provided POSIX REGEX library or the GNU REGEX
library which can be built into the plugin.  This is achieved by
defining the preprocessor macro HAVE_REGEX to true if you trust your
system REGEX library.  To use the POSIX REGEX library of your system:

--------------------
yorick -batch ./config.i [...] --with-regex-defs='-DHAVE_REGEX=1' [...]
--------------------

and to built the GNU REGEX library into the plugin (this is the default
behaviour):

--------------------
yorick -batch ./config.i [...] --with-regex-defs='-DHAVE_REGEX=0' [...]
--------------------

For instance, here is how to call the configure script to use builtin REGEX
support and to enable FFTW support (installed in `/usr/local`) and TIFF
support (installed in standard locations):

--------------------
yorick -batch ./config.i --with-regex \
    --with-fftw --with-fftw-defs="-I/usr/local/include" \
    --with-fftw-libs="-L/usr/local/lib -lrfftw -lfftw" \
    --with-gsl --with-gsl-defs="-I/usr/local/include/gsl" \
    --with-gsl-libs="-L/usr/local/lib -lgsl -lgslcblas" \
    --with-tiff --with-tiff-libs="-ltiff"
--------------------

In order to check your configuration settings, you can add `--help` as the
last argument of the call to `./config.i`.

After configuration, you can build Yeti and all related plugins by just
doing:

--------------------
make
--------------------

In order to install Yeti files into Yorick installation directories, you
simply do:

--------------------
make install
--------------------


Author
------

Eric Thiébaut

Observatoire de Lyon

9, avenue Charles André

F-69561 Saint Genis Laval Cedex

thiebaut AT obs.univ-lyon1.fr


Thanks
------

Many things in this software suite were inspired or more or less
directly imported/translated from other existing softwares (see file
LICENSE for details).


Links
-----

 * http://sourceforge.net/projects/yorick[Yorick] is an interpreted
   programming language for scientific simulations or calculations,
   postprocessing or steering large simulation codes, interactive
   scientific graphics, and reading, writing, or translating large
   files of numbers.

 * http://www.fftw.org/[FFTW] is the 'Fastest Fourier Transform in the
   West'.  Please note that since FFTW API has changed with FFTW
   version 3, only FFTW version 2 (latest is 2.1.5) is supported in
   Yeti (this may change soon).

 * http://www.gnu.org/software/gsl/[GSL]: the GNU Scientific Library. 

 * http://www.libtiff.org/[LibTIFF]: a free TIFF library which
   provides support for the 'Tag Image File Format' (TIFF), a widely
   used format for storing image data.

 * http://www.scriptics.com/products/tcltk/[Tcl/Tk]: the 'Tool Command
   Language' and its widget toolkit.


Quick Reference of Yeti Functions/Routines
------------------------------------------

Hash Tables
~~~~~~~~~~~
`h_cleanup`:: delete void members of hash table object
`h_clone`:: clone a hash table
`h_copy`:: duplicate hash table object
`h_delete`:: delete members from a hash table
`h_first`:: get name of first hash table member
`h_get`:: get value of hash table member
`h_has`:: check existence of hash table member
`h_info`:: list contents of hash table
`h_keys`:: get member names of a hash table object
`h_list`:: make a hash table into a list
`h_new`:: create a new hash table object
`h_next`:: get name of next hash table member
`h_pop`:: pop member out of an hash table object
`h_restore_builtin`:: restore builtin functions
`h_save_symbols`:: save builtin functions
`h_set`:: set member of hash table object
`h_set_copy`:: set member of hash table object
`h_show`:: display a hash table as an expanded tree
`h_stat`:: get statistics of hash table object


Yeti Hierarchical Data (YHD) files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------
#include "yeti_yhdf.i"
----------------------
`yhd_check`:: check version of YHD file
`yhd_info`:: print some information about an YHD file
`yhd_restore`:: restore a hash table object from an YHD file
`yhd_save`:: save a hash table object into an YHD file

Regular Expressions
~~~~~~~~~~~~~~~~~~~
-----------------------
#include "yeti_regex.i"
-----------------------
`regcomp`:: compile regular expression
`regmatch`:: match a regular expression against an array of strings
`regmatch_part`:: peek substrings given indices returned by regmatch
`regsub`:: substitute regular expression into an array of strings

Miscellaneous
~~~~~~~~~~~~~
`about`:: search for documentation
`current_include`:: full path of currently parsed file
`expand_path`:: expand directory names to absolute paths
`get_path`:: the counterpart of set_path
`heapsort`:: sort an array by heap-sort method
`identof`:: get type identifier of an object
`insure_temporary`:: make sure a variable is not referenced
`is_complex`:: check if an object is an array of complex value(s)
`is_hash`:: check if an object is a hash table
`is_integer`:: check if an object is an array of integer value(s)
`is_list`:: check if an object is a list
`is_matrix`:: check if an object is a 2-D array
`is_numerical`:: check if an object is an array of numerical value(s)
`is_pointer`:: check if an object is an array of pointer(s)
`is_real`:: check if an object is an array of floating point value(s)
`is_scalar`:: check if an object is a scalar array
`is_sparse_matrix`:: check if an object is a sparse matrix
`is_string`:: check if an object is an array of string(s)
`is_vector`:: check if an object is a 1-D array
`pretty_print_string_list`:: print out a list in columns
`quick_select`:: find K-th smallest element in an array
`quick_median`:: find median value (faster than median function)
`quick_interquartile_range`:: compute inter-quartile range of values
`select_file`:: interactively select an existing file
`select_item_in_string_list`:: interactively select an item in a list
`set_alarm`:: invoke a callback function after some time
`swap`:: exchange contents of two variables (n copy needed)
`unref`:: make a symbol temporary
`yeti_init`:: setup Yeti internals

Memory Hacking
~~~~~~~~~~~~~~
`mem_base`:: get base address of an array object
`mem_copy`:: copy array data at a given address
`mem_info`:: print memory information
`mem_peek`:: make a new array from a base address, type and dimension list
`native_byte_order`:: compute native byte order

Files
~~~~~
`filepath`:: get full path of a file
`chn_open`:: open, possibly compressed, file channel.
`chn_seek`:: set i/o position for a channel.
`chn_read`:: read data from a channel.
`chn_rewind`:: go to beginning of a channel file.
`chn_tell`:: get current i/o position into a channel.
`chn_write`:: write data to a channel.

Binary Encoding of Data
~~~~~~~~~~~~~~~~~~~~~~~
`get_encoding`:: get description of binary encoding for various machines
`install_encoding`:: install binary description into a binary stream
`same_encoding`:: compare two encoding

Math/Numerical
~~~~~~~~~~~~~~
`arc`:: lengh of arc in radians
`cost_l2`:: cost function and gradient for l2 norm
`cost_l2l0`:: cost function and gradient for l2-l0 norm
`cost_l2l1`:: cost function and gradient for l2-l1 norm
`machine_constant`:: get machine dependent constant (such as EPSILON)
`mvmult`:: (sparse)matrix-vector multiplication
`round`:: round to nearest integer
`sinc`:: cardinal sine: sinc(x) = sin(pi*x)/(pi*x)
`smooth3`:: smooth an array by 3-element convolution
`sparse_expand`:: convert a sparse 'matrix' array into a regular array
`sparse_grow`:: augment a sparse array
`sparse_matrix`:: create a new sparse 'matrix'
`sparse_squeeze`:: convert a regular array into a sparse one
`yeti_convolve`:: convolution along a given dimension
`yeti_wavelet`:: "à trou" wavelet decomposition

Strings
~~~~~~~
`strlower`:: convert array of strings to lower case
`strtrim`:: remove leading/trailing spaces from an array of strings
`strtrimleft`:: remove leading spaces from an array of strings
`strtrimright`:: remove trailing spaces from an array of strings
`strupper`:: convert array of strings to upper case

Yorick Internals
~~~~~~~~~~~~~~~~
`memory_info`:: display memory used by Yorick symbols
`symbol_exists`:: check existence of a Yorick symbol
`symbol_info`:: get some information about existing Yorick symbols
`symbol_names`:: get names of Yorick symbols
`nrefsof`:: get number of references of an object
`get_includes`:: get list of all included files so far

Graphics
~~~~~~~~
`window_geometry`:: get geometry of a Gist window

Morpho-math operations
~~~~~~~~~~~~~~~~~~~~~~
`morph_black_top_hat`:: perform valley detection
`morph_closing`:: perform morpho-math closing operation
`morph_dilation`:: perform morpho-math dilation operation
`morph_erosion`:: perform morpho-math erosion operation
`morph_opening`:: perform morpho-math opening operation
`morph_white_top_hat`:: perform summit detection

TIFF images
~~~~~~~~~~~
----------------------
#include "yeti_tiff.i"
----------------------
`tiff_open`:: open TIFF file
`tiff_debug`:: control printing of TIFF warning messages
`tiff_read_pixels`:: read pixel values in a TIFF file
`tiff_read_image`:: read image in a TIFF file
`tiff_read_directory`:: move to next TIFF "directory"
`tiff_read`:: read image/pixels in a TIFF file
`tiff_check`:: check if a file is a readable TIFF file.

FFTW
~~~~
----------------------
#include "yeti_fftw.i"
----------------------
`fftw_plan`:: setup a plan for FFTW
`fftw`:: computes FFT of an array according to a plan
`cfftw`:: computes complex FFT of an array
`fftw_indgen`:: generates FFT indices
`fftw_dist`:: computes length of spatial frequencies
`fftw_smooth`:: smooths an array
`fftw_convolve`:: fast convolution of two arrays

///////////////////////////////////////////////////////////////////////////////

 Local Variables:
 mode: text
 coding: utf-8
 End:

///////////////////////////////////////////////////////////////////////////////
