===========
csm Library
===========

.. note::
   The library must be initialized with `csm_init`_ first, before it can be
   used.

The csm library provides a unified interface for the following types of
functions:

- linear functions ``y= a + b*x``
- functions of the form ``y= f(x)`` defined by a lookup table
- functions of the form ``z= f(x, y)`` defined by a lookup table

All these functions are represented with a single abstract data type,
``csm_function``.

A ``csm_function`` object must always be created with `csm_new_function`_.

The csm library provides functions to manage ``csm_function`` objects and to
do calculations. All calculation functions cache the last value and are
optimized for speed.

Linear functions
----------------

This is the most simple type of function of the type ``y= a + b*x``.
It is defined with `csm_def_linear`_. 

One dimensional functions with lookup table
-------------------------------------------

This implements a function ``y= f(x)`` with a lookup table. The lookup table
can be initialized by a file or from two arrays of type ``double``. If the
function ``f(x)`` is monotonic, you can also calculate the inverse function
``x= g(y)``.

The one dimensional lookup table
::::::::::::::::::::::::::::::::

These are requirements/properties for a one dimensional table:

- A line must not be longer than 127 bytes.
- A line that is not empty or a comment must have exactly two numbers
- A line with numbers may start or end with an arbitrary number of white
  spaces
- Lines do not need to be ordered by x or y.
- One value of x must *never* be mapped to two different values of y

Here is a short example of a table::

    5.5000   641.0683
    5.6000   657.0219
    5.7000   673.1084
    5.8000   689.3115
    5.9000   705.6146
    6.0000   722.0005
    6.1000   738.4555
    6.2000   754.9796
    6.3000   771.5765
    6.4000   788.2499

CSM uses *linear interpolation* to compute the function ``y= f(x)`` for *all*
possible values of x (see `csm_x`_). If the function ``f(x)`` is monotonic,
you can also compute the inverse function ``x= g(y)`` (see `csm_y`_).

For x values smaller than the first value in the table or larger than the last
value in the table, the function is *linear extrapolated*.

In the example above, we have::

  f(6.3)  = 771.5765
  f(6.35) = 779.9132
  f(6.4)  = 788.2499
  f(6.45) = 796.5866

Two dimensional functions with lookup table
-------------------------------------------

This implements a function ``z= f(x, y)`` with a lookup table. The lookup table
is always initialized by reading a file. 

The two dimensional lookup table
::::::::::::::::::::::::::::::::

A two-dimensional table specifies a function with two parameters. The first
line and the first column specify the XY-grid. The first line must have
exactly one element less than the remaining lines; it specifies the Y
coordinates of the grid. The first column (i.e. the first elements of the
remaining lines) specify the X coordinates of the grid, while the remaining
elements specify the value (Z coordinate) at the corresponding point in the
grid (see `csm_z`_).

These are requirements for a two dimensional table:

- A line must not be longer than 1023 bytes.
- The first line must contain *all y values*
- All following lines must contain *a single x and all z values for z= f(x,
  y)*.
- Lines and columns do not need to be ordered by x or y.

Here is a short example of a table::

           -6.0000  -3.0000  0.0000   3.0000   6.0000
  15.4000  -0.1990  -0.1150  0.0000   0.1240   0.2580
  15.9000  -0.1990  -0.1150  0.0000   0.1240   0.2580
  16.6000  -0.2050  -0.1230  0.0000   0.0830   0.2190

CSM uses *two dimensional linear interpolation* to compute the function ``z=
f(x, y)`` for *all possible values* of x and y (see `csm_z`_).

In the example above, we have::

  f(15.9, -6) = -0.1990
  f(15.9, -3) = -0.1150
  f(16.6, -6) = -0.2050
  f(16.6, -5) = -0.1777
  f(16.6, -3) = -0.1230

Full API documentation
----------------------

Here is the full API documentation:

`Doxygen generated API docs`_,

.. _csm_init: doxygen/html/csmbase_8h.html#ac258ff5bea878f347c50c33c443ed11a
.. _csm_new_function: doxygen/html/csmbase_8h.html#a9f296fbe09af32a5f6bb32a2b484ebd5
.. _csm_x: doxygen/html/csmbase_8h.html#a6226f2df9d594321101657cd5c53bb7d
.. _csm_y: doxygen/html/csmbase_8c.html#ac28ee80fa3bcc8174ff0844ff92e981f
.. _csm_z: doxygen/html/csmbase_8c.html#ac0e3dcd535ce486f004128f9c270cb2b
.. _csm_def_linear: doxygen/html/csmbase_8h.html#a61750466c2f188e35dadc8be3363c358
.. _Doxygen generated API docs: doxygen/html/files.html