.. highlight:: c

Slope Management for non-periodic domains
*****************************************


Integrating slope-management with real-time code
================================================

Slope management corrects finite aperture slope measurements for the Fourier transform reconstructor. Fourier transforms are implicitly carried out on a fully periodic domain. This assumption does not hold when looking at a typical wavefront sensor. For more details about slope management, see :ref:`slopemanagement`.

A minimial example of slope management::

    #include <slopemanage.h>
    sm_plan plan;
    int nx = 10, ny = 10;
    double * sx, * sy;
    int * ap, i, j;

    sx = malloc(sizeof(double) * nx * ny);
    sy = malloc(sizeof(double) * nx * ny);
    ap = malloc(sizeof(int) * nx * ny);

    // Set up an aperture with a border.
    // At least one border row/column is required for slope
    // management, so that there is enough room to put the
    // fixed slope values.
    for (i = 0; i < nx; ++i)
    {
        for (j = 0; j < ny; ++j)
        {
            if(i == 0 || j == 0 || i == nx - 1 || j == ny - 1)
            {
                ap[i + (j * nx)] = 0;
            }else{
                ap[i + (j * nx)] = 1;
            }
        }
    }


    // Set up the slope management plan
    plan = slope_management_plan(nx, ny, ap);

    // Do the slope managmenet as many times as necessary.
    slope_management_execute(plan, sy, sx);
    // Unlike FTR plans, slope management plans can operate
    // on different arrays each time.

    // Free allocated memory at the end.
    slope_management_destroy(plan);
    free(sx);
    free(sy);
    free(ap);


Slope Management API
====================

.. c:type:: sm_plan

    The slope management plan, which contains the memory allocation for a single slope management scheme. The plan is generated by :c:func:`slope_management_plan`, and is an opaque structure containing the relevant pointers for performing slope management.

.. c:function:: sm_plan slope_management_plan(int ny, int nx, int *ap)

    Prepare a slope management scheme. This function creates a :c:type:`sm_plan` object which contains the memory allocation for the slope management scheme.

    :param int ny: Number of y positions (rows).
    :param int nx: Number of x positions (columns).
    :param int* ap: A pointer to the aperture (which should be `nx` by `ny` in size). Apertures are defined as 1 where light is transmissive.
    :returns: :c:type:`sm_plan`, the slope management plan.

.. c:function:: void slope_management_execute(sm_plan plan, double * sy, double * sx)

    Execute the slope managment plan, adjusting slopes in the `sx` and `sy` pointers. This method adjusts slopes in-place.

    :param sm_plan plan: The slope management plan to execute. A :c:type:`sm_plan` can be created using :c:func:`slope_management_plan`.
    :param double* sy: A pointer to the y slopes, as an array. Must conform to the dimensions set during the planning process.
    :param double* sx: A pointer to the x slopes, as an array. Must conform to the dimensions set during the planning process.
    :returns: No return value is provided, as the function acts on `sx` and `sy` in place.

.. c:function:: void slope_management_destroy(sm_plan plan)

    Deallocate the slope management plan. Memory allocated using :c:func:`slope_management_plan` will be freed.

    :param sm_plan plan: The slope management plan to execute. A :c:type:`sm_plan` can be created using :c:func:`slope_management_plan`.

.. c:function:: void slope_management(int ny, int nx, int *ap, double * sy, double * sx)

    Conduct the entire slope management process in a single call. This will allocate memory and determine aperture settings on the fly.

    Slope management happens in-place on the original arrays. No copy is performed.

    :param int ny: Number of y positions (rows).
    :param int nx: Number of x positions (columns).
    :param int* ap: A pointer to the aperture (which should be `nx` by `ny` in size). Apertures are defined as 1 where light is transmissive.
    :param double* sy: A pointer to the y slopes, as an array. Must conform to the dimensions set during the planning process.
    :param double* sx: A pointer to the x slopes, as an array. Must conform to the dimensions set during the planning process.
    :returns: No return value is provided, as the function acts on `sx` and `sy` in place.