------------------------------------------
lines 8-82 of file: at_cascade/bilinear.py
------------------------------------------

{xrst_begin bilinear}

Bilinear Spline Interpolation
#############################

Prototype
*********
{xrst_literal ,
   BEGIN_DEF, END_DEF
   BEGIN_RETURN, END_RETURN
}

x_name
******
is the name in *table* for the x
variable in the interpolation.

y_name
******
is the name in *table* for the y
variable in the interpolation.

z_list
******
Each element of  *z_list* is a ``str`` specifying
the name in *table* for a z
variable in the interpolation.

table
*****
Each element of *table* is a ``dict``.
The values *x_name* , *y_name* and each element of *z_list*
must be a key in each of the dictionaries.
Furthermore, the corresponding dictionary values must be ``str`` or ``float`` .
This table must be non-empty.

Rectangular Grid
================
For each x in *x_grid* and y in *y_grid* there must be one,
and only one, row in *table* with that x and y value.
If this is not the case, ``bilinear`` will return with *spline_dict*
equal to ``None`` .

x_grid
******
Is the a sorted ``list`` of values that appear
in the *x_name* column of *table* .
Duplicates are not included in this list.

y_grid
******
Is the a sorted ``list`` of values that appear
in the *y_name* column of *table* .
Duplicates are not included in this list.

spline_dict
***********
Is a ``dict`` of spline functions with keys equal to
each *z_name* in  *z_list* .
The function call
{xrst_code py}
   z = spline_dict[z_name](x, y)
{xrst_code}
sets z to the value of the spline for *z_name* .

#. The values x and y are ``float`` or ``int`` .
#. The value z is a  ``float`` .
#. The function is extended as constant with respect to x (y)
   for values of x (y) outside the limits of x_grid (y_grid).

Example
*******
:ref:`example_bilinear-name`

{xrst_end bilinear}