add LICENCE and update README

parent 9ed064ea
This diff is collapsed.
# librinterpolate
librinterpolate: a library to perform linear interpolation on a gridded dataset.
\ No newline at end of file
librinterpolate: a library to perform linear interpolation on a constant gridded dataset.
Usage:
librinterpolate
A library to perform n-dimensional linear interpolation on a table
of data.
The table should be organised (in memory) like this
p1[0] p2[0] p3[0] ... d1[0] d2[0] d3[0] d4[0] ...
p1[1] p2[1] p3[1] ... d1[1] d2[1] d3[1] d4[1] ...
p1[2] p2[2] p3[2] ... d1[2] d2[2] d3[2] d4[2] ...
so there are n parameters (p1, p2, p3...) and d data items
per data line (d1, d2, d3, d4 ...). There are l lines of data.
The parameters should be ordered from low to high values.
The parameters should be on aconstant* grid (which does NOT
need to be regular).
What does this mean?
This is a good data table:
0.1 -100 10 ...data...
0.1 -100 25 ...data...
0.1 -100 30 ...data...
0.1 -50 10 ...data...
0.1 -50 25 ...data...
0.1 -50 30 ...data...
0.3 -100 10 ...data...
0.3 -100 25 ...data...
0.3 -100 30 ...data...
0.3 -50 10 ...data...
0.3 -50 25 ...data...
0.3 -50 30 ...data...
0.9 -100 10 ...data...
0.9 -100 25 ...data...
0.9 -100 30 ...data...
0.9 -50 10 ...data...
0.9 -50 25 ...data...
0.9 -50 30 ...data...
In the above case, the parameters have values:
p0 : 0.1,0.3,0.9
p1 : -100, -50
p2 : 10,25,30
The parameter "hypercube" then is the 3D-hypercube of
323 = 18 data lines.
Note that the points on the cube areconstant* but notregular*,
e.g. p0 has spacing (0.3-0.1)=0.2 and (0.9-0.3)=0.6, which are different,
BUT e.g. the spacing for p1 (-100 - -50 = -50) is the same, whatever the
value of p0. The same is true for p3 which always has spacings 15 and 5
from (25-10) and (30-25) respectively.
Note that the table is assumed to be sorted from SMALLEST
to LARGEST parameter values. It is also assumed to be regular and filled.
So no missing data please, just put some dummy values in the table.
In order to interpolate data, n parameters are passed into this
routine in the array x. The result of the interpolation is put
into the array r (of size d).
If you enable RINTERPOLATE_CACHE then results are cached to avoid
slowing the code too much. (This is set in binary_c_code_options.h) This means
that the interpolate routine checks your input parameters x against
the last few sets of parameters passed in. If you have used these x
recently, the result is simply returned. This saves extra interpolation
and is often faster. This is only true in some cases of course - if your
x are always different you waste time checking the cache. This is why
the cache_hint variable exists: if this is false then the cache is skipped.
Of course onlyyou* know if you are likely to call the interpolate routine
repeated with the same values... I cannot possibly know this in advance!
The interpolation process involved finding the lines of the data table
which span each parameter x. This makes a hypercube of length 2^n (e.g.
in the above it is 8, for simple 1D linear interpolation it would be the
two spanning values). Linear interpolation is then done in the largest
dimension, above this is the third parameter (p2), then the second (p1)
and finally on the remaining variable (p0). This would reduce the table
from 2^3 lines to 2^2 to 2^1 to (finally) 2^0 i.e. one line which is the
interpolation result.
To find the spanning lines a binary search is performed. This code was
donated by Evert Glebbeek. See e.g.
http://en.wikipedia.org/wiki/Binary_search_algorithm
and note the comment "Although the basic idea of binary search is comparatively
straightforward, the details can be surprisingly tricky... " haha! :)
Each table has its own unique table_id number. This is just to allow
us to set up caches (one per table) and save arrays such as varcount and
steps (see below) so they only have to be calculated once.
Since binary_c2 these table_id numbers have been allocated automatically,
you do not have to set one yourself, but this does assume that the tables
are each at fixed memory locations. This is guaranteed if you declare them
with the recommended data type Const_data_table, e.g.
Const_data_table mytable = { 0.0, 100.0, 1.0, 200.0, 2.0, 500.0 };
(Const_data_table is a "const static double" type, which implies its memory
storage is fixed once allocated, and it cannot be changed hence is thread-safe.)
However, it is best to use the data_table_t struct to make data tables.
This is allocated through the NewDataTable_from_Array and NewDataTable_from_Pointer
macros, which require the setting of the number of parameters, data items
and lines of the table. Then, the call to do the interpolation
is far simpler.
I have optimized this as best I can, please let me know if
you can squeeze any more speed out of the function.
I am sorry this has made most of the function unreadable! The
comments should help, but you will need to know some tricks...
(c) Robert Izzard, 2005-2019, please send bug fixes!
\ No newline at end of file
#include "rinterpolate.h"
/*
* A function to perform n-dimensional linear interpolation on a table
* librinterpolate
*
* A library to perform n-dimensional linear interpolation on a table
* of data.
*
* The table should be organised (in memory) like this
......@@ -136,12 +138,13 @@
* but you're less likely to match!
*
* Note: uses FEQUAL macros to check for floating-point equality, you should
* check that TINY is small enough for your parameters, or rescale your
* check that TINY (current the smallest floating point epsilon)
* is small enough for your parameters, or rescale your
* parameters so they are much bigger than TINY (that's best,
* as TINY may be used used elsewhere). You could, of course, define a
* different (slower) macro.
*
* Rob Izzard, 2005-2019, please send bug fixes!
* (c) Robert Izzard, 2005-2019, please send bug fixes!
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment