## Math Math — Mathematical utility functions |

## Functions

#define | ROUND()
#define | GWY_ROUND()
gdouble | gwy_math_humanize_numbers ()
gboolean | gwy_math_is_in_polygon ()
gint | gwy_math_find_nearest_line ()
gint | gwy_math_find_nearest_point ()
gdouble * | gwy_math_lin_solve ()
gdouble * | gwy_math_lin_solve_rewrite ()
gboolean | gwy_math_tridiag_solve_rewrite ()
gdouble * | gwy_math_fit_polynom ()
gboolean | gwy_math_choleski_decompose ()
void | gwy_math_choleski_solve ()
guint | gwy_math_curvature ()
gboolean | gwy_math_refine_maximum ()
gdouble | gwy_math_median ()
void | gwy_math_sort ()
gdouble | gwy_math_median_uncertainty ()

## Types and Values

#define | GWY_SQRT3
#define | GWY_SQRT_PI

## Includes

    #include <libgwyddion/gwyddion.h>

## 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.

## Functions

### ROUND()

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

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

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

#### Parameters

x | A double value. |

### GWY_ROUND()

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

Rounds a number to nearest integer.

#### Parameters

x | A double value. |

Since: 2.5

### 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.

#### Parameters

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.

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

#### Parameters

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` ).

#### Parameters

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` ).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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_curvature ()

    guint
    gwy_math_curvature (const gdouble *coeffs,
                        gdouble *kappa1,
                        gdouble *kappa2,
                        gdouble *phi1,
                        gdouble *phi2,
                        gdouble *xc,
                        gdouble *yc,
                        gdouble *zc);

### gwy_math_refine_maximum ()

    gboolean
    gwy_math_refine_maximum (const gdouble *z,
                             gdouble *x,
                             gdouble *y);

Performs subpixel refinement of parabolic a two-dimensional maximum.

The central value corresponds to coordinates (0,0), distances between values are unity. The refinement is based by fitting a two-dimensional parabola through the maximum. If it fails or the calculated maximum lies farther than the surrounding values the function sets the refined maximum to the origin and returns `FALSE`.

#### Parameters

z | Array of length 9, containing the square 3x3 neighbourhood values in matrix order and with the maximum in the centre. |
x | Location to store the refined `x` -coordinate. |
y | Location to store the refined `y` -coordinate. |

#### Returns

`TRUE` if the refinement succeeded, `FALSE` if it failed. The values of `x` and `y` are usable regardless of the return value.

Since: 2.42

### gwy_math_median ()

    gdouble
    gwy_math_median (gsize n,
                     gdouble *array);

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

#### Parameters

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.

#### Parameters

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

### gwy_math_median_uncertainty ()

    gdouble
    gwy_math_median_uncertainty (gsize n,
                                 gdouble *array,
                                 gdouble *uarray);

## Types and Values

### 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.

## See Also

GwyNLFitter, non-linear least square fitter;

Math Fallback,

fallback mathematical functions