## Math

Math — Mathematical utility functions

## Synopsis

    #include <libgwyddion/gwyddion.h>

    #define             ROUND                               (x)
    #define             GWY_ROUND                           (x)
    #define             GWY_SQRT3
    #define             GWY_SQRT_PI
    gdouble             gwy_math_humanize_numbers           (gdouble unit,
                                                             gdouble maximum,
                                                             gint *precision);
    gboolean            gwy_math_is_in_polygon              (gdouble x,
                                                             gdouble y,
                                                             const gdouble *poly,
                                                             guint n);
    gint                gwy_math_find_nearest_line          (gdouble x,
                                                             gdouble y,
                                                             gdouble *d2min,
                                                             gint n,
                                                             const gdouble *coords,
                                                             const gdouble *metric);
    gint                gwy_math_find_nearest_point         (gdouble x,
                                                             gdouble y,
                                                             gdouble *d2min,
                                                             gint n,
                                                             const gdouble *coords,
                                                             const gdouble *metric);
    gdouble*            gwy_math_lin_solve                  (gint n,
                                                             const gdouble *matrix,
                                                             const gdouble *rhs,
                                                             gdouble *result);
    gdouble*            gwy_math_lin_solve_rewrite          (gint n,
                                                             gdouble *matrix,
                                                             gdouble *rhs,
                                                             gdouble *result);
    gboolean            gwy_math_tridiag_solve_rewrite      (gint n,
                                                             gdouble *d,
                                                             const gdouble *a,
                                                             const gdouble *b,
                                                             gdouble *rhs);
    gdouble*            gwy_math_fit_polynom                (gint ndata,
                                                             const gdouble *xdata,
                                                             const gdouble *ydata,
                                                             gint n,
                                                             gdouble *coeffs);
    gboolean            gwy_math_choleski_decompose         (gint n,
                                                             gdouble *matrix);
    void                gwy_math_choleski_solve             (gint n,
                                                             const gdouble *decomp,
                                                             gdouble *rhs);
    gdouble             gwy_math_median                     (gsize n,
                                                             gdouble *array);
    void                gwy_math_sort                       (gsize n,
                                                             gdouble *array);

## Description

Functions `gwy_math_SI_prefix()` and `gwy_math_humanize_numbers()` deal with number representation.

Nearest object finding functions `gwy_math_find_nearest_line()` and `gwy_math_find_nearest_point()` can be useful in widget and vector layer implementation.

And `gwy_math_lin_solve()`, `gwy_math_lin_solve_rewrite()`, and `gwy_math_fit_polynom()` are general purpose numeric methods.

## Details

### ROUND()

    #define ROUND(x) ((gint)floor((x) + 0.5))

### Warning

`ROUND` is deprecated and should not be used in newly-written code.

Rounds a number to nearest integer. Use `GWY_ROUND` instead.

`x` : | A double value.

### GWY_ROUND()

    #define GWY_ROUND(x) ((gint)floor((x) + 0.5))

Rounds a number to nearest integer.

`x` : | A double value.

Since 2.5

### GWY_SQRT3

    #define GWY_SQRT3 1.73205080756887729352744634150587236694280525381038

The square root of 3.

### GWY_SQRT_PI

    #define GWY_SQRT_PI 1.77245385090551602729816748334114518279754945612237

The square root of pi.

### gwy_math_humanize_numbers ()

    gdouble             gwy_math_humanize_numbers           (gdouble unit,
                                                             gdouble maximum,
                                                             gint *precision);

Finds a human-friendly representation for a range of numbers.

`unit` : | The smallest possible step.
`maximum` : | The maximum possible value.
`precision` : | A location to store `printf()` precession, if not `NULL`.
Returns : | The magnitude i.e., a power of 1000.

### gwy_math_is_in_polygon ()

    gboolean            gwy_math_is_in_polygon              (gdouble x,
                                                             gdouble y,
                                                             const gdouble *poly,
                                                             guint n);

Establishes wether the test point `x`, `y` is inside the polygon `poly`. The polygon can be defined either clockwise or anti-clockwise and can be a concave, convex or self-intersecting polygon.

### Warning

Result can be either TRUE or FALSE if the test point is *exactly* on an edge.

`x` : | The x coordinate of the test point.
`y` : | The y coordinate of the test point.
`poly` : | An array of coordinate pairs (points) that define a polygon.
`n` : | The number of corners of the polygon.
Returns : | TRUE if the test point is inside poly and FALSE otherwise.

Since 2.7

### gwy_math_find_nearest_line ()

    gint                gwy_math_find_nearest_line          (gdouble x,
                                                             gdouble y,
                                                             gdouble *d2min,
                                                             gint n,
                                                             const gdouble *coords,
                                                             const gdouble *metric);

Finds the line from `coords` nearest to the point (`x`, `y`).

`x` : | X-coordinate of the point to search.
`y` : | Y-coordinate of the point to search.
`d2min` : | Where to store the squared minimal distance, or `NULL`.
`n` : | The number of lines (i.e. `coords` has 4`n` items).
`coords` : | Line coordinates stored as x00, y00, x01, y01, x10, y10, etc.
`metric` : | Metric matrix (2x2, but stored sequentially by rows: m11, m12, m21, m22), it must be positive definite. Vector norm is then calculated as m11*x*x + (m12 + m21)*x*y + m22*y*y. It can be `NULL`, standard Euclidean metric is then used.
Returns : | The line number. It may return -1 if (`x`, `y`) doesn't lie in the orthogonal stripe of any of the lines.

### gwy_math_find_nearest_point ()

    gint                gwy_math_find_nearest_point         (gdouble x,
                                                             gdouble y,
                                                             gdouble *d2min,
                                                             gint n,
                                                             const gdouble *coords,
                                                             const gdouble *metric);

Finds the point from `coords` nearest to the point (`x`, `y`).

`x` : | X-coordinate of the point to search.
`y` : | Y-coordinate of the point to search.
`d2min` : | Location to store the squared minimal distance to, or `NULL`.
`n` : | The number of points (i.e. `coords` has 2`n` items).
`coords` : | Point coordinates stored as x0, y0, x1, y1, x2, y2, etc.
`metric` : | Metric matrix (2x2, but stored sequentially by rows: m11, m12, m21, m22). Vector norm is then calculated as m11*x*x + (m12 + m21)*x*y + m22*y*y. It can be `NULL`, standard Euclidean metric is then used.
Returns : | The point number.

### gwy_math_lin_solve ()

    gdouble*            gwy_math_lin_solve                  (gint n,
                                                             const gdouble *matrix,
                                                             const gdouble *rhs,
                                                             gdouble *result);

Solve a regular system of linear equations.

`n` : | The size of the system.
`matrix` : | The matrix of the system (`n` times `n`), ordered by row, then column.
`rhs` : | The right hand side of the sytem.
`result` : | Where the result should be stored. May be `NULL` to allocate a fresh array for the result.
Returns : | The solution (`result` if it wasn't `NULL`), may be `NULL` if the matrix is singular.

### gwy_math_lin_solve_rewrite ()

    gdouble*            gwy_math_lin_solve_rewrite          (gint n,
                                                             gdouble *matrix,
                                                             gdouble *rhs,
                                                             gdouble *result);

Solves a regular system of linear equations.

This is a memory-conservative version of `gwy_math_lin_solve()` overwriting `matrix` and `rhs` with intermediate results.

`n` : | The size of the system.
`matrix` : | The matrix of the system (`n` times `n`), ordered by row, then column.
`rhs` : | The right hand side of the sytem.
`result` : | Where the result should be stored. May be `NULL` to allocate a fresh array for the result.
Returns : | The solution (`result` if it wasn't `NULL`), may be `NULL` if the matrix is singular.

### gwy_math_tridiag_solve_rewrite ()

    gboolean            gwy_math_tridiag_solve_rewrite      (gint n,
                                                             gdouble *d,
                                                             const gdouble *a,
                                                             const gdouble *b,
                                                             gdouble *rhs);

Solves a tridiagonal system of linear equations.

`n` : | The dimension of `d`.
`d` : | The diagonal of a tridiagonal matrix, its contents will be overwritten.
`a` : | The above-diagonal stripe (it has `n`-1 elements).
`b` : | The below-diagonal stripe (it has `n`-1 elements).
`rhs` : | The right hand side of the system, upon return it will contain the solution.
Returns : | `TRUE` if the elimination suceeded, `FALSE` if the system is (numerically) singular. The contents of `d` and `rhs` may be overwritten in the case of failure too, but not to any meaningful values.

### gwy_math_fit_polynom ()

    gdouble*            gwy_math_fit_polynom                (gint ndata,
                                                             const gdouble *xdata,
                                                             const gdouble *ydata,
                                                             gint n,
                                                             gdouble *coeffs);

Fits a polynom through a general (x, y) data set.

`ndata` : | The number of items in `xdata`, `ydata`.
`xdata` : | Independent variable data (of size `ndata`).
`ydata` : | Dependent variable data (of size `ndata`).
`n` : | The degree of polynom to fit.
`coeffs` : | An array of size `n`+1 to store the coefficients to, or `NULL` (a fresh array is allocated then).
Returns : | The coefficients of the polynom (`coeffs` when it was not `NULL`, otherwise a newly allocated array).

### gwy_math_choleski_decompose ()

    gboolean            gwy_math_choleski_decompose         (gint n,
                                                             gdouble *matrix);

Decomposes a symmetric positive definite matrix in place.

`n` : | The dimension of `a`.
`matrix` : | Lower triangular part of a symmetric matrix, stored by rows, i.e., matrix = [a_00 a_10 a_11 a_20 a_21 a_22 a_30 ...].
Returns : | Whether the matrix was really positive definite. If `FALSE`, the decomposition failed and `a` does not contain any meaningful values.

### gwy_math_choleski_solve ()

    void                gwy_math_choleski_solve             (gint n,
                                                             const gdouble *decomp,
                                                             gdouble *rhs);

Solves a system of linear equations with predecomposed symmetric positive definite matrix `a` and right hand side `b`.

`n` : | The dimension of `a`.
`decomp` : | Lower triangular part of Choleski decomposition as computed by `gwy_math_choleski_decompose()`.
`rhs` : | Right hand side vector. Is is modified in place, on return it contains the solution.

### gwy_math_median ()

    gdouble             gwy_math_median                     (gsize n,
                                                             gdouble *array);

Finds median of an array of values using Quick select algorithm.

`n` : | Number of items in `array`.
`array` : | Array of doubles. It is modified by this function. All values are kept, but their positions in the array change.
Returns : | The median value of `array`.

### gwy_math_sort ()

    void                gwy_math_sort                       (gsize n,
                                                             gdouble *array);

Sorts an array of doubles using a quicksort algorithm.

This is usually about twice as fast as the generic quicksort function thanks to specialization for doubles.

`n` : | Number of items in `array`.
`array` : | Array of doubles to sort in place.

## See Also

GwyNLFitter, non-linear least square fitter; Math Fallback, fallback mathematical functions