squeeze

DESCRIPTION

The subroutine "squeeze" compresses a set of integer*2 values from a onedimensional array. The purpose of "squeeze" is to effectively pack single fields of model results etc. so decompression can be carried out on a field-to-field basis (rather than decompression on a file-to-file basis). "squeeze" works best for slowly varying fields, and consequtive undefined values are also packed economically.
WARNING!
1.
"squeeze" requires -32768 to be a valid integer*2 number
2.
Input values -32767 and -32768 are both treated as undefined values, and will be decompressed as -32767. No other values are recognized as undefined in this version of "squeeze".
The decompression tool is provided as the subroutine release. A walk-thru of squeeze is also provided.

SYNTAX

subroutine

squeeze

( mode,algorithm,ldat,leading,trailing,length, idata,maxsize,iwork,nfactors,factors,error )

INPUT, OUTPUT VARIABLES

Input:

mode	(i)	-	should be a variable, MUST BE SET TO 0 IN INITIAL CALL,should not be modified in the calling program/subroutine thereafter; e.g.: mode_variable = 0 do i = 1,n call get_field(ldat,...) call squeeze(mode_variable,...) call put_field(ldat,...) end do
algorithm	(i)	-	compression algorithm to be used; values: 1 (2-1), 2 (3-1), 3 (4-1), 4 (3-2), 5 (5-1), 6 (4-2), 7 (6-1), 8 (5-2), 9 (4-3) etc. presently implemented: 4, 6, 9
ldat	(i)	-	no. of values to consider in 'idata()' vector (including leading & trailing)
leading	(i)	-	no. of leading entries in 'idata()' that should not be compressed
trailing	(i)	-	no. of trailing entries in 'idata()' that should not be compressed; will be reset if compression is successful (see information on output variables below)
length	(i)	-	dimension of 'idata()' (suggested value: leading+nx*ny+trailing); left unchanged by "squeeze"
idata	(I2)	-	leading entries, field, trailing entries
maxsize	(i)	-	dimension of 'iwork()' (suggested value: nx*ny)
nfactors	(i)	-	dimension of 'factors()'; min. dimension, 'algorithm'=4: 17 + 1 + 32 + 32 + 181 = 263
factors	(I)	-	vector for storage of factors (time-saving); used if 'mode'<>0 and unchanged 'algorithm' since previous call

Output:

mode	(i)	-	output value: 1 - compression OK -1 - no compression
ldat	(i)	-	length of the compressed 'idata()' vector
idata	(I2)	-	leading entries, compressed field, trailing entries
factors	(I)	-	vector for storage of factors (time-saving)
error	(i)	-	will be set to: 0 if no error is detected 1 if non-implemented 'algorithm' is selected; 2 if dimension of 'factors()' is too small 3 if # leading + # trailing > input 'ldat'

Work:

iwork

(I2)

-

work space vector, temporary starage

DEPENDENCIES

No external.

EXAMPLE

SKETCH:
input values ['idata(21)', ...]:
a b b b c d d d u u u u e e
will be stored as ('u' is undefined, the other values are defined):
the first value, when defined, is stored separately:
a -> s a ('s' is 'single', see below)
the 'b' values may be compressed to a single value:
b b b -> B
the 'c' value is not compressed:
a -> s c
the 'd' values may be compressed to a single value:
d d d -> D
the n=4 undefined values are stored as:
u u u u -> u N (N=32768-n, see below)
the 'e' values may be compressed to a single value:
e e -> E
so the result is
s a B p16 s c D u N E
where 'p16' is the result from "put16" (bitwise sign storage)
Some additional information is added before the first output value
[
-32768 + # leading entries,
-32768 + # trailing entries,
-32768 + # int(#compressed entries/65536),
-32768 + # mod(#compressed entries,65536),
compression algorithm no.
]
Finally, leading and trailing un-compressed entries are added to the head and the tail of the output vector 'idata()', respectively.
A step-by-step explanation (walk-thru) is also provided.