%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright Notice:
%
% All of the 'C' code in this directory is
% Copyright (c) Paul Fieguth, 1995
%
% The Matlab files are written by Paul Fieguth and William Irving
% Copyright (c) 1995
%
% This code or any portion of it may not be distributed
% without prior permission of the author, P. Fieguth.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The file hydrography.tar.gz, which is stored together with this
README file is a compressed archive. The constituent files
can be restored by typing the following commands at a UNIX prompt:
gunzip hydrography.tar
tar xf hydrography.tar
The resulting files in the directory implement a multiscale estimator;
the algorithm of the estimator is too involved to summarize
here, however the following references present the algorithm
and give examples of its use. At least a passing familiarity
with one of these publications is necessary in order to use
the code.
file://ocho.uwaterloo.ca/pub/Papers/hydrography.ps
D. Menemenlis, P. Fieguth, C. Wunsch, A. Willsky,
``A Fast Optimal Interpolation Algorithm for Mapping Hydrographic and Other
Oceanographic Data'', {\em Journal of Geophysical Research} (102) \#C5,
pp.10573--10584, 1997
file://ocho.uwaterloo.ca/pub/Papers/multiscaleocean.ps.gz
P. Fieguth, W. Karl, A. Willsky, C. Wunsch,
``Multiresolution Optimal Interpolation and
Statistical Analysis of TOPEX/POSEIDON Satellite Altimetry'',
{\em IEEE Trans. Geoscience and Remote Sensing} (33) \#2, pp.280--292, 1995.
http://donald-duck.mit.edu/lids/pubs/2175.html
M. Luettgen, W. Karl, A. Willsky, ``Efficient Multiscale
Regularization with Applications to the Computation of Optical Flow'',
{\em IEEE Trans. on Image Processing} (3) \#1, pp.41--64, 1994.
An overview of the structure of the code, and further examples
and considerable discussion on the use of such multiscale
frameworks may be found in the following thesis:
file://ocho.uwaterloo.ca/pub/Papers/thesis.ps.gz
P. Fieguth, ``Application of Multiscale Estimation to Large
Scale Multidimensional Imaging and Remote Sensing Problems'', PhD Thesis,
Dept. of EECS, Massachusetts Institute of Technology, 1995
The following files are contained in this directory:
README - this text file
ho_demo_paper.m - sample Matlab script for duplicating some of the
estimation results from the "A Fast Optimal ..." paper
ho_demo_general.m - sample Matlab script that acts as a simple front-end
to the multiscale code. It allows the user to apply
the multiscale approach to a broader set of problems
than those demonstrated by ho_demo_paper.m
demo_data_p2.mat - a Matlab data file, containing hydrographic measurements
and optimal-interpolation solutions along the P2 line;
this file is used by ho_demo_paper.m
gauss_corr.m - sample correlation function
ho_main_pri.m - multiscale modeling and estimation front-end
build_2d_ho_pri.m - multiscale model builder
compute_ho_corr.m - multiscale node correlation computer
theta_to_cov.m - prescaled linear-functional correlation computer
build_Azz_func.m - convert correlation function to sampled matrix
ms_cc2_pri.c - interface between Matlab and the main multiscale engine
in smth.c
smth.c - core engine and interface definitions
smth_mem.c - multiscale engine memory management
smth_init.c - interface-dependent tree main initialization code
smth_init1234.c - interface 1-4 initialization
smth_init5.c - interface 5 initialization
matrix.c - set of generic matrix macros and functions
random.c - random number generation
Precompiled versions of the code under Matlab 4:
ms_cc2_pri.mexsol Sun SPARC, Solaris Operating System
ms_cc2_pri.mex4 Sun SPARC, Sun OS
ms_cc2_pri.sg SGI 4d (Silicon Graphics)
Precompiled versions of the code under Matlab 5:
ms_cc2_pri.mexaxp DEC Alpha, DEC OSF
To use the code on a different operating system / Matlab version:
Matlab 4:
cmex -Dinterface=2 -DPriorSupplied ms_cc2_pri.c smth.c smth_mem.c
Matlab 5:
mex -V4 -Dinterface=2 -DPriorSupplied -DMatlab5 ms_cc2_pri.c smth.c smth_mem.c
In principle, the engine can be used from a standalone c-program,
in which case a compile line such as
cc main_code.c smth.c smth_mem.c
would be used. Note that the other .c files are not specified
explicitly on the command line; they are incorporated internally
into smth.c.
The script ho_demo_paper.m permits users to duplicate the results of
the Hydrography paper referenced above. Without modifications, the script
will reproduce Figure 9 of the Hydrography paper.
Since a relatively simple multiscale model is being implemented,
ho_demo_general.m, ho_main_pri.m, and ms_cc2_pri.c are relatively
simple pieces of code. Readers of this file should be aware however
that the multiscale engine in smth.c is vastly more powerful and can
accomodate a wide variety of multiscale models and means of specifying
them. An overview of the power and generality is provided in Appendix
A of the thesis referenced at the beginning of this file. Examples of
other multiscale models are given throughout the thesis.
There are some limitations to the code, which should be stated up front.
Addressing these limitations forms a part of our ongoing research efforts.
1. Not all prior correlation functions can be specified.
As the code presently stands, only stationary correlation functions are
allowed, and meaningful estimates will be obtained only if the
correlation function is smooth and monotonic; convergence to the exact
estimates as the sampling density increases can be guaranteed only for
first-order Markov priors.
2. As the order (i.e., state dimension) of the model becomes very large,
the model becomes increasingly singular, leading to numerical instability.
Sampling densities in excess of 2 can lead to such instabilities.
Despite these limitations, if used in the proper context the multiscale code
can yield estimates and error statistics of excellent quality at a
remarkable computational efficiency.
Paul Fieguth
University of Waterloo
December, 1997