Math

Math — Mathematical utility functions

Functions

Types and Values

#define GWY_SQRT3
#define GWY_SQRT_PI

Includes

#include <libgwyddion/gwyddion.h>

Description

Function gwy_math_humanize_numbers() deals 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_xy_copy ()

GwyXY *
gwy_xy_copy (const GwyXY *xy);

Copies Cartesian coordinates in plane.

Parameters

xy

Cartesian coordinates in plane.

 

Returns

A copy of xy . The result must be freed using gwy_xy_free(), not g_free().

Since: 2.45


gwy_xy_free ()

void
gwy_xy_free (GwyXY *xy);

Frees Cartesian coordinates in plane created with gwy_xy_copy().

Parameters

xy

Cartesian coordinates in plane.

 

Since: 2.45


gwy_xyz_copy ()

GwyXYZ *
gwy_xyz_copy (const GwyXYZ *xyz);

Copies Cartesian coordinates in space.

Parameters

xyz

Cartesian coordinates in space.

 

Returns

A copy of xyz . The result must be freed using gwy_xyz_free(), not g_free().

Since: 2.45


gwy_xyz_free ()

void
gwy_xyz_free (GwyXYZ *xyz);

Frees Cartesian coordinates in space created with gwy_xyz_copy().

Parameters

xyz

Cartesian coordinates in space.

 

Since: 2.45


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

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

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

gboolean
gwy_math_choleski_invert (gint n,
                          gdouble *matrix);

Inverts a symmetric positive definite matrix in place.

Parameters

n

Matrix size.

 

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 inversion failed and matrix does not contain any meaningful values.

Since: 2.46


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);

gwy_xlnx_int ()

gdouble
gwy_xlnx_int (guint x);

Calculates natural logarithm multiplied by the argument for integers.

The value for zero x is taken as the limit, i.e. zero.

This function is useful for entropy calculations where values of n *log(n ) can be evaulated a lot for small n . Therefore, values for small arguments are tabulated. For large arguments the function is evaluated using the standard log() function which is of course slower.

Parameters

x

Value to calculate x *log(x ) of.

 

Returns

Value of x *log(x ).

Since: 2.44

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