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);
guint               gwy_math_curvature                  (const gdouble *coeffs,
                                                         gdouble *kappa1,
                                                         gdouble *kappa2,
                                                         gdouble *phi1,
                                                         gdouble *phi2,
                                                         gdouble *xc,
                                                         gdouble *yc,
                                                         gdouble *zc);
gdouble             gwy_math_median                     (gsize n,
                                                         gdouble *array);
void                gwy_math_sort                       (gsize n,
                                                         gdouble *array);
gdouble             gwy_math_median_uncertainty         (gsize n,
                                                         gdouble *array,
                                                         gdouble *uarray);

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 4n 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 2n 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_curvature ()

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


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.

gwy_math_median_uncertainty ()

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

See Also

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