low-level API
=============

Grid generation
---------------

.. function:: cem_gridtools.gridgen(x,y,beta,ni,nj,ulidx=0)

	This is the low-level interface function to the gridgen-c library.
		
	For general use, see :func:`cem_gridtools.cem_gridtools.CGrid.gen_grid`
   
   :param array x: x boundary points
   :param array y: y boundary values
   :param array b: beta values (corner status)
   :param int ni: Number of required grid **points** in the i-direction
   :param int nj: Number of required grid **points** in the j-direction
   :param int ulidx: The idx of the *upper left* corner of the grid

   :return: (gx,gy) output 2d arrays
   :rtype: tuple

.. code::

	import numpy
	from cem_gridtools.gridgen import gridgen
	# Note that the ordering is important to make a 'simple' shape
	x = numpy.array([0, 1, 1, 0], dtype='d')
	y = numpy.array([0, 0, 1, 1], dtype='d')
	beta = numpy.ones(x.shape, dtype='d')
	(gx,gy) = gridgen(x,y,beta,3,2,0)


Interpolation
-------------

.. function:: cem_gridtools.grid_interp.init(x,y,z,rule)
	
	Initialises the interpolation routine with the given source data

	:param array x: x values of input data
	:param array y: y values of input data
	:param array z: input data values
	:param str rule: interpolation type ("nn_sibson, nn_non_sibson")
	:returns: handle of interpolant
	:rtype: void pointer


.. function:: cem_gridtools.grid_interp.on_point(h,x,y)
	
	Perform the interpolation on the given point

	:param h: handle from output of the `init` function
	:param float x: target x value
	:param float y: target y value
	:returns: interpolated value
	:rtype: float

.. code::

	import numpy
	from cem_gridtools.grid_interp import init,on_point
	x = numpy.array([0, 1,   0.4], dtype='d')
	y = numpy.array([0, 0.2, 0.8], dtype='d')
	z = numpy.array([1, 2, 3], dtype='d')
	H = init(x,y,z,"nn_sibson")
	# Now interpolate on any point
	v = on_point(H, 0.5, 0.2)