Geogram  Version 1.4.7
A programming library of geometric algorithms
nl.h File Reference

The public API of the OpenNL linear solver library. Click the "More..." link below for simple example programs. More...

#include "nl_linkage.h"
#include "nl_ext.h"

Go to the source code of this file.

Macros

#define NL_VERSION_4_0   1
 
#define NLAPI
 
Solver parameters
#define NL_SOLVER   0x100
 Symbolic constant for nlSolverParameteri() to specify the used solver. More...
 
#define NL_NB_VARIABLES   0x101
 Symbolic constant for nlSolverParameteri() to specify the number of variables. More...
 
#define NL_LEAST_SQUARES   0x102
 Symbolic constant for nlSolverParameteri() to specify whether least squares mode is used. More...
 
#define NL_MAX_ITERATIONS   0x103
 Symbolic constant for nlSolverParameteri() to specify the maximum number of iterations before the iterative solver is stopped. More...
 
#define NL_THRESHOLD   0x104
 Symbolic constant for nlSolverParameterd() to specify the maximum threshold $ \| Ax - b \| / \| b \| $ before the iterative solver is stopped. More...
 
#define NL_OMEGA   0x105
 Symbolic constant for nlSolverParameterd() to specify the relaxation parameter $ \omega \in (0,\ldots 2) $ used by the SSOR preconditioner. More...
 
#define NL_SYMMETRIC   0x106
 Symbolic constant for nlSolverParameteri() to specify whether the constructed matrix is symmetric. More...
 
#define NL_USED_ITERATIONS   0x107
 Symbolic constant for nlGetIntegerv() to obtain the used number of iteration. More...
 
#define NL_ERROR   0x108
 Symbolic constant for nlGetDoublev() to obtain the error after nlSolve() is called. More...
 
#define NL_INNER_ITERATIONS   0x109
 Symbolic constant for nlSolverParameteri() to specify the number of iterations / number of stored vector in the inner NL_GMRES loop. More...
 
#define NL_ELAPSED_TIME   0x10a
 Symbolic constant for nlGetDoublev() to obtain the time taken by the latest invocation of nlSolve(), in seconds. More...
 
#define NL_PRECONDITIONER   0x10b
 Symbolic constant for nlSolverParameteri() to specify the used preconditioner. More...
 
#define NL_GFLOPS   0x10c
 Symbolic constant for nlGetDoublev() to obtain the average GFlop/Seconds performance counter during the latest invocation of nlSolve(). More...
 
#define NL_NNZ   0x10d
 Symbolic constant for nlGetIntegerv() to obtain the number of non-zero coefficient in the latest linear system used by nlSolve(). More...
 
#define NL_NB_SYSTEMS   0x10e
 Symbolic constant for nlSolverParameteri()/nlGetIntegerv() to define or query the number of linear systems to be solved.
 
Solvers
#define NL_SOLVER_DEFAULT   0x000
 Symbolic constant for nlSolverParameteri() to specify that OpenNL should automatically select a reasonable solver and preconditioner. More...
 
#define NL_CG   0x200
 Symbolic constant for nlSolverParameteri() to select the Conjugate Gradient solver. More...
 
#define NL_BICGSTAB   0x201
 Symbolic constant for nlSolverParameteri() to select the Conjugate Gradient solver. More...
 
#define NL_GMRES   0x202
 Symbolic constant for nlSolverParameteri() to select the GMRES solver. More...
 
Preconditioners
#define NL_PRECOND_NONE   0x000
 Symbolic constant for nlSolverParameteri() to use no preconditioner. More...
 
#define NL_PRECOND_JACOBI   0x300
 Symbolic constant for nlSolverParameteri() to use the Jacobi preconditioner. More...
 
#define NL_PRECOND_SSOR   0x301
 Symbolic constant for nlSolverParameteri() to use the SSOR (Successive Over Relaxation) preconditioner. More...
 
#define NL_PRECOND_USER   0x303
 Symbolic constant for nlSolverParameteri() to use a user-defined preconditioner. More...
 
Enable / Disable
#define NL_NORMALIZE_ROWS   0x400
 Symbolic constant for nlEnable() / nlDisable() to enable or disable rows normalization. More...
 
#define NL_VERBOSE   0x401
 Symbolic constant for nlEnable() / nlDisable() to enable or disable messages. More...
 

Functions

Context management
NLAPI NLContext NLAPIENTRY nlNewContext (void)
 Creates a new OpenNL context. More...
 
NLAPI void NLAPIENTRY nlDeleteContext (NLContext context)
 Destroys an existing OpenNL context. More...
 
NLAPI void NLAPIENTRY nlMakeCurrent (NLContext context)
 Sets the current OpenNL context. More...
 
NLAPI NLContext NLAPIENTRY nlGetCurrent (void)
 Gets the current context. More...
 
NLAPI NLboolean NLAPIENTRY nlInitExtension (const char *extension)
 Initializes an OpenNL extension. More...
 
NLAPI NLboolean NLAPIENTRY nlExtensionIsInitialized (const char *extension)
 Tests whether an OpenNL extension is initialized. More...
 
NLAPI void NLAPIENTRY nlInitialize (int argc, char **argv)
 Initializes OpenNL using command line arguments. More...
 
State Get/Set
NLAPI void NLAPIENTRY nlSolverParameterd (NLenum pname, NLdouble param)
 Specifies a floating-point solver parameter. More...
 
NLAPI void NLAPIENTRY nlSolverParameteri (NLenum pname, NLint param)
 Specifies an integer solver parameter. More...
 
NLAPI void NLAPIENTRY nlGetBooleanv (NLenum pname, NLboolean *params)
 Gets the value of a boolean parameter. More...
 
NLAPI void NLAPIENTRY nlGetDoublev (NLenum pname, NLdouble *params)
 Gets the value of a double-precision floating-point parameter. More...
 
NLAPI void NLAPIENTRY nlGetIntegerv (NLenum pname, NLint *params)
 Gets the value of an integer parameter. More...
 
NLAPI void NLAPIENTRY nlEnable (NLenum pname)
 Sets a boolean parameter to NL_TRUE. More...
 
NLAPI void NLAPIENTRY nlDisable (NLenum pname)
 Sets a boolean parameter to NL_FALSE. More...
 
NLAPI NLboolean nlIsEnabled (NLenum pname)
 Tests a boolean parameter. More...
 
Variables
NLAPI void NLAPIENTRY nlSetVariable (NLuint i, NLdouble value)
 Sets the value of a variable. More...
 
NLAPI void NLAPIENTRY nlMultiSetVariable (NLuint i, NLuint k, NLdouble value)
 Sets the value of a variable when there are several systems to solve. More...
 
NLAPI NLdouble NLAPIENTRY nlGetVariable (NLuint i)
 Gets the value of a variable. More...
 
NLAPI NLdouble NLAPIENTRY nlMultiGetVariable (NLuint i, NLuint k)
 Gets the value of a variable when there are several systems to solve. More...
 
NLAPI void NLAPIENTRY nlLockVariable (NLuint index)
 Locks a variable. More...
 
NLAPI void NLAPIENTRY nlUnlockVariable (NLuint index)
 Unlocks a variable. More...
 
NLAPI NLboolean NLAPIENTRY nlVariableIsLocked (NLuint index)
 Tests whether a variable is locked. More...
 
Solve
NLAPI NLboolean NLAPIENTRY nlSolve (void)
 Solves the linear system in the current context. More...
 
NLAPI void NLAPIENTRY nlUpdateRightHandSide (NLdouble *values)
 Updates the right hand side of the constructed system in one call. More...
 

DataTypes and constants

#define NL_FALSE   0x0
 Constant for false NLbooleans. More...
 
#define NL_TRUE   0x1
 Constant for true NLbooleans. More...
 
typedef unsigned int NLenum
 A symbolic constant.
 
typedef unsigned char NLboolean
 A truth value (NL_TRUE or NL_FALSE). More...
 
typedef unsigned int NLbitfield
 A set of symbolic constants that can be combined with the bitwise or operator.
 
typedef void NLvoid
 Return type of functions that do not return a value.
 
typedef signed char NLbyte
 A 1-byte signed integer.
 
typedef short NLshort
 A 2-bytes signed integer.
 
typedef int NLint
 A 4-bytes signed integer.
 
typedef unsigned char NLubyte
 A 1-byte unsigned integer.
 
typedef unsigned short NLushort
 A 2-bytes unsigned integer.
 
typedef unsigned int NLuint
 A 4-bytes unsigned integer.
 
typedef unsigned long NLulong
 A 8-bytes unsigned integer.
 
typedef int NLsizei
 Size of an object, 4-bytes signed integer.
 
typedef float NLfloat
 A single-precision floating-point number.
 
typedef double NLdouble
 A double-precision floating-point number.
 
typedef void(* NLfunc) ()
 A function pointer. More...
 
typedef void * NLContext
 An OpenNL context. More...
 

Function pointers

#define NL_FUNC_SOLVER   0x600
 Symbolic constant for nlSetFunction(), used to replace OpenNL solver with a user-defined routine. More...
 
#define NL_FUNC_MATRIX   0x601
 Symbolic constant for nlSetFunction(), used to replace OpenNL matrix-vector product with a user-defined routine. More...
 
#define NL_FUNC_PRECONDITIONER   0x602
 Symbolic constant for nlSetFunction(), used to replace OpenNL preconditioner with a user-defined routine. More...
 
#define NL_FUNC_PROGRESS   0x603
 Symbolic constant for nlSetFunction(), used to display a progress bar during solve, using a user-defined callback. More...
 
NLAPI void NLAPIENTRY nlSetFunction (NLenum pname, NLfunc param)
 Sets a function pointer. More...
 
NLAPI void NLAPIENTRY nlGetFunction (NLenum pname, NLfunc *param)
 Gets a function pointer. More...
 

Begin/End

#define NL_SYSTEM   0x0
 Symbolic constant for nlBegin() / nlEnd(), to be used to start creating / finalizing a linear system. More...
 
#define NL_MATRIX   0x1
 Symbolic constant for nlBegin() / nlEnd(), to be used to start creating / finalizing a matrix. More...
 
#define NL_ROW   0x2
 Symbolic constant for nlBegin() / nlEnd(), to be used to start creating / finalizing a row. More...
 
NLAPI void NLAPIENTRY nlBegin (NLenum primitive)
 Begins a new primitive. More...
 
NLAPI void NLAPIENTRY nlEnd (NLenum primitive)
 Begins a new primitive. More...
 
NLAPI void NLAPIENTRY nlCoefficient (NLuint i, NLdouble value)
 Appends a coefficient to the current row. More...
 
NLAPI void NLAPIENTRY nlAddIJCoefficient (NLuint i, NLuint j, NLdouble value)
 Adds a coefficient to the current matrix. More...
 
NLAPI void NLAPIENTRY nlAddIRightHandSide (NLuint i, NLdouble value)
 Adds a coefficient to a component of the right hand side of the equation. More...
 
NLAPI void NLAPIENTRY nlMultiAddIRightHandSide (NLuint i, NLuint k, NLdouble value)
 Adds a coefficient to a component of the right hand side of the equation. More...
 
NLAPI void NLAPIENTRY nlRightHandSide (NLdouble value)
 Sets the right-hand side of the current row. More...
 
NLAPI void NLAPIENTRY nlMultiRightHandSide (NLuint k, NLdouble value)
 Sets the right-hand side of the current row when there are several systems to be solved. More...
 
NLAPI void NLAPIENTRY nlRowScaling (NLdouble value)
 Sets the row scaling for the next row. More...
 

Buffers

#define NL_VARIABLES_BUFFER   0x1000
 The symbolic constant for variables buffer. More...
 
NLAPI void NLAPIENTRY nlBindBuffer (NLenum buffer, NLuint k, void *addr, NLuint stride)
 Specifies a buffer binding to directly map user data to variables instead of using nlGetVariable() / nlSetVariable() More...
 

EigenSolver

#define NL_STIFFNESS_MATRIX   0x3001
 Constant for nlMatrixMode()
 
#define NL_MASS_MATRIX   0x3002
 Constant for nlMatrixMode()
 
#define NL_NB_EIGENS   NL_NB_SYSTEMS
 Symbolic constant for nlEigenSolverParameteri(), number of eigenpairs to compute.
 
#define NL_EIGEN_MAX_ITERATIONS   NL_MAX_ITERATIONS
 Symbolic constant for nlEigenSolverParameteri(), maximum number of iterations.
 
#define NL_EIGEN_THRESHOLD   NL_THRESHOLD
 Symbolic constant for nlEigenSolverParameterd(), convergence threshold.
 
#define NL_EIGEN_SOLVER   0x2000
 Symbolic constant for nlEigenSolverParameterd(), name of the eigen solver to be used.
 
#define NL_EIGEN_SHIFT   0x2001
 Symbolic constant for nlEigenSolverParameterd(), shift parameter for the shift-invert transform.
 
#define NL_EIGEN_SHIFT_INVERT   0x2002
 Symbolic constant for nlEnable() / nlDisable() / nlIsEnabled(), shift-invert spectral transform.
 
NLAPI void NLAPIENTRY nlMatrixMode (NLenum matrix)
 Specifies to which matrix the subsequent calls to nlBegin(), nlEnd(), nlCoefficient(), nlAddIJCoefficient() will be applied. More...
 
NLAPI void NLAPIENTRY nlEigenSolverParameterd (NLenum pname, NLdouble val)
 Sets a floating-point parameter of the eigen solver. More...
 
NLAPI void NLAPIENTRY nlEigenSolverParameteri (NLenum pname, NLint val)
 Sets an integer parameter of the eigen solver. More...
 
NLAPI void NLAPIENTRY nlEigenSolve (void)
 Calls the eigen solver.
 
NLAPI double NLAPIENTRY nlGetEigenValue (NLuint i)
 Gets an eigenvalue. More...
 

Detailed Description

The public API of the OpenNL linear solver library. Click the "More..." link below for simple example programs.

The purpose of the example programs shown below is to demonstrate OpenNL programs that are as simple as possible. Note that for such small linear systems, the sparse iterative solvers in OpenNL will work, but they are completely inappropriate, one would normally solve the system directly.

Example 1 (a simple linear system)

Solve $ \left[ \begin{array}{ll} 1 & 2 \\ 3 & 4 \end{array} \right] \left[ \begin{array}{l} x \\ y \end{array} \right] = \left[ \begin{array}{l} 5 \\ 6 \end{array} \right] $

double x,y; // Solution of the system
// Create and initialize OpenNL context
// Build system
nlCoefficient(0, 1.0);
nlCoefficient(1, 2.0);
nlCoefficient(0, 3.0);
nlCoefficient(1, 4.0);
// Solve and get solution
// Cleanup

Example 2 (least squares regression)

Reads $ (X,Y) $ coordinates from a file and finds the parameters $ a,b $ of the straight line $ y = ax + b $ that best fits the data points.

FILE* input = fopen("datapoints.dat", "r");
double X,Y; // current datapoint
// Create and initialize OpenNL context
// Build system
while(!feof(input)) {
fread(input, "%f %f", &X, &Y);
nlCoefficient(1, 1.0);
}
// Solve and get solution
// Cleanup
fclose(input);

Example 3 (least squares regression with locked variable)

As in the previous example, reads $ (X,Y) $ coordinates from a file and finds the parameters $ a,b $ of the straight line $ y = ax + b $ that best fits the data points, but this time subject to the constraint $ a = 1 $.

FILE* input = fopen("datapoints.dat", "r");
double X,Y; // current datapoint
// Create and initialize OpenNL context
// Build system
nlSetVariable(0, 1.0);
while(!feof(input)) {
fread(input, "%f %f", &X, &Y);
nlCoefficient(1, 1.0);
}
// Solve and get solution
// Cleanup
fclose(input);

Example 4 (fine tuning)

Before calling nlBegin(NL_SYSTEM), if need be, it is possible to fine-tune additional parameters. See the following examples:

Definition in file nl.h.

Macro Definition Documentation

◆ NL_BICGSTAB

#define NL_BICGSTAB   0x201

Symbolic constant for nlSolverParameteri() to select the Conjugate Gradient solver.

Usage:

BICGSTAB works for both non-symmetric and symmetric matrices. If the matrix is known to be symmetric, then CG will be more efficient.

Definition at line 564 of file nl.h.

◆ NL_CG

#define NL_CG   0x200

Symbolic constant for nlSolverParameteri() to select the Conjugate Gradient solver.

Usage:

Warning
The Conjugate Gradient solver requires the matrix to be symmetric (note that it is always the case in least-squares mode, but NOT in regular mode).

Definition at line 551 of file nl.h.

◆ NL_ELAPSED_TIME

#define NL_ELAPSED_TIME   0x10a

Symbolic constant for nlGetDoublev() to obtain the time taken by the latest invocation of nlSolve(), in seconds.

Usage:

Definition at line 468 of file nl.h.

◆ NL_ERROR

#define NL_ERROR   0x108

Symbolic constant for nlGetDoublev() to obtain the error after nlSolve() is called.

Gets $ \| Ax - b \| / \| b \| $. Usage:

Definition at line 444 of file nl.h.

◆ NL_FALSE

#define NL_FALSE   0x0

Constant for false NLbooleans.

See also
NLboolean

Definition at line 310 of file nl.h.

◆ NL_FUNC_MATRIX

#define NL_FUNC_MATRIX   0x601

Symbolic constant for nlSetFunction(), used to replace OpenNL matrix-vector product with a user-defined routine.

void my_matrix_func(const double* x, double* y) {
...
}
nlSetFunction(NL_FUNC_MATRIX, (nlFunc)my_matrix_func);

Definition at line 885 of file nl.h.

◆ NL_FUNC_PRECONDITIONER

#define NL_FUNC_PRECONDITIONER   0x602

Symbolic constant for nlSetFunction(), used to replace OpenNL preconditioner with a user-defined routine.

void my_precond_func(const double* x, double* y) {
...
}
nlSetFunction(NL_FUNC_PRECONDITIONER, (nlFunc)my_precond_func);
See also
nlSetFunction(), NL_PRECONDITIONER

Definition at line 900 of file nl.h.

◆ NL_FUNC_PROGRESS

#define NL_FUNC_PROGRESS   0x603

Symbolic constant for nlSetFunction(), used to display a progress bar during solve, using a user-defined callback.

The user-defined progress callback is called after each iteration, and can be used to update a progress bar.

void my_progress_callback(
NLuint cur_iter, // Current iteration
NLuint max_iter, // Maximum number of iterations
double cur_err, // Current (squared, un-normalized) error
double max_err // Maximum (squared, un-normalized) error
) {
...
}
nlSetFunction(NL_FUNC_PROGRESS, (nlFunc)my_progress_callback);

Definition at line 921 of file nl.h.

◆ NL_FUNC_SOLVER

#define NL_FUNC_SOLVER   0x600

Symbolic constant for nlSetFunction(), used to replace OpenNL solver with a user-defined routine.

Note
For advanced users only, requires to dig into OpenNL internal structures.
#include <nl_context.h>
NLboolean my_solver() {
...
...
}
nlSetFunction(NL_FUNC_SOLVER, (nlFunc)my_solver);

Definition at line 871 of file nl.h.

◆ NL_GFLOPS

#define NL_GFLOPS   0x10c

Symbolic constant for nlGetDoublev() to obtain the average GFlop/Seconds performance counter during the latest invocation of nlSolve().

Usage:

NLdouble gflops;

Definition at line 495 of file nl.h.

◆ NL_GMRES

#define NL_GMRES   0x202

Symbolic constant for nlSolverParameteri() to select the GMRES solver.

Usage:

GMRES works for both non-symmetric and symmetric matrices. If the matrix is known to be symmetric, then NL_CG will be more efficient. GMRES has an additional internal number of iterations parameters that can be set as follows:

Definition at line 581 of file nl.h.

◆ NL_INNER_ITERATIONS

#define NL_INNER_ITERATIONS   0x109

Symbolic constant for nlSolverParameteri() to specify the number of iterations / number of stored vector in the inner NL_GMRES loop.

Only relevant if used solver is NL_GMRES. Usage:

Definition at line 456 of file nl.h.

◆ NL_LEAST_SQUARES

#define NL_LEAST_SQUARES   0x102

Symbolic constant for nlSolverParameteri() to specify whether least squares mode is used.

Used as follows, before any call to nlBegin():

or

Definition at line 360 of file nl.h.

◆ NL_MATRIX

#define NL_MATRIX   0x1

Symbolic constant for nlBegin() / nlEnd(), to be used to start creating / finalizing a matrix.

See also
nlBegin(), nlEnd()

Definition at line 1055 of file nl.h.

◆ NL_MAX_ITERATIONS

#define NL_MAX_ITERATIONS   0x103

Symbolic constant for nlSolverParameteri() to specify the maximum number of iterations before the iterative solver is stopped.

Usage:

If the solver is left unspecified or is set to NL_SOLVER_DEFAULT, then a reasonable maximum number of iterations is used (5 times the number of free variables).

Definition at line 374 of file nl.h.

◆ NL_NB_VARIABLES

#define NL_NB_VARIABLES   0x101

Symbolic constant for nlSolverParameteri() to specify the number of variables.

Used as follows, before any call to nlBegin():

where nb is the number of variables.

Definition at line 346 of file nl.h.

◆ NL_NNZ

#define NL_NNZ   0x10d

Symbolic constant for nlGetIntegerv() to obtain the number of non-zero coefficient in the latest linear system used by nlSolve().

Usage:

NLint nnz;
nlGetIngerv(NL_NNZ, &nnz);

Definition at line 508 of file nl.h.

◆ NL_NORMALIZE_ROWS

#define NL_NORMALIZE_ROWS   0x400

Symbolic constant for nlEnable() / nlDisable() to enable or disable rows normalization.

When row normalization is enabled, each time a row is completed with nlEnd(NL_ROW), the coefficients of the current row and its right hand side are divided by the length $ L $ of the current row (and multiplied by the NL_ROW_SCALING $ s $ if one was specified):

\[ \begin{array}{lcl} L & \leftarrow & \sqrt{\sum_{j} a_{i,j}^2} \\ a_{i,j} & \leftarrow & a_{i,j} \times s / L \\ b_i & \leftarrow & b_i \times s / L \end{array} \]

Usage:

or

See also
nlEnable(), nlDisable(), nlIsEnabled(), NL_ROW_SCALING

Definition at line 672 of file nl.h.

◆ NL_OMEGA

#define NL_OMEGA   0x105

Symbolic constant for nlSolverParameterd() to specify the relaxation parameter $ \omega \in (0,\ldots 2) $ used by the SSOR preconditioner.

Usage:

See also
NL_PRECOND_SSOR

Definition at line 399 of file nl.h.

◆ NL_PRECOND_JACOBI

#define NL_PRECOND_JACOBI   0x300

Symbolic constant for nlSolverParameteri() to use the Jacobi preconditioner.

The Jacobi preconditioner corresponds to the inverse of the diagonal elements. Clearly, it requires that the matrix has no zero element on the diagonal. Usage:

Definition at line 610 of file nl.h.

◆ NL_PRECOND_NONE

#define NL_PRECOND_NONE   0x000

Symbolic constant for nlSolverParameteri() to use no preconditioner.

Usage:

Definition at line 597 of file nl.h.

◆ NL_PRECOND_SSOR

#define NL_PRECOND_SSOR   0x301

Symbolic constant for nlSolverParameteri() to use the SSOR (Successive Over Relaxation) preconditioner.

Usage:

The SSOR preconditioner can significantly reduce the number of used iterations, but each iteration takes much longer. It has an additional Omega parameter:

See also
NL_OMEGA

Definition at line 625 of file nl.h.

◆ NL_PRECOND_USER

#define NL_PRECOND_USER   0x303

Symbolic constant for nlSolverParameteri() to use a user-defined preconditioner.

Usage:

The user-defined preconditoner is specified as a function pointer,

See also
nlSetFunction(), NL_FUNC_PRECONDITIONER, NL_PRECONDITIONER

Definition at line 638 of file nl.h.

◆ NL_PRECONDITIONER

#define NL_PRECONDITIONER   0x10b

Symbolic constant for nlSolverParameteri() to specify the used preconditioner.

Should be one of (NL_PRECOND_NONE, NL_PRECOND_JACOBI, NL_PRECOND_SSOR, NL_PRECOND_USER). If NL_PRECOND_USER is used, then the user-defined preconditioner is specified using nlSetFunction(). Usage:

Definition at line 482 of file nl.h.

◆ NL_ROW

#define NL_ROW   0x2

Symbolic constant for nlBegin() / nlEnd(), to be used to start creating / finalizing a row.

See also
nlBegin(), nlEnd()

Definition at line 1063 of file nl.h.

◆ NL_SOLVER

#define NL_SOLVER   0x100

Symbolic constant for nlSolverParameteri() to specify the used solver.

Used as follows, before any call to nlBegin():

where solver is one of (NL_CG, NL_BICGSTAB, NL_GMRES) or one of the extended solvers if supported (NL_xxx_SUPERLU_EXT, NL_CNC_xxx) or NL_SOLVER_DEFAULT to let OpenNL decide and use a reasonable solver.

Definition at line 335 of file nl.h.

◆ NL_SOLVER_DEFAULT

#define NL_SOLVER_DEFAULT   0x000

Symbolic constant for nlSolverParameteri() to specify that OpenNL should automatically select a reasonable solver and preconditioner.

It is the default operating mode of OpenNL. It can also be reset as follows:

It also lets OpenNL choose (hopefully reasonable) values for maximum number of iterations (NL_MAX_ITERATIONS) = 5 times the number of free variables and threshold (NL_THRESHOLD) = 1e-6. It uses the Jacobi-preconditioned conjugate gradient solver (NL_CG and NL_PRECOND_JACOBI) if the matrix is known to be symmetric, and NL_BICGSTAB otherwise.

Definition at line 538 of file nl.h.

◆ NL_SYMMETRIC

#define NL_SYMMETRIC   0x106

Symbolic constant for nlSolverParameteri() to specify whether the constructed matrix is symmetric.

If the constructed matrix is symmetric, pre-notifying OpenNL before constructing it may improve performance, by allowing more efficient data structures and solvers to be used. Usage:

or

Warning
Behavior if undefined if setting NL_SYMMETRIC and constructing a non-symmetric matrix afterwards.

Definition at line 418 of file nl.h.

◆ NL_SYSTEM

#define NL_SYSTEM   0x0

Symbolic constant for nlBegin() / nlEnd(), to be used to start creating / finalizing a linear system.

See also
nlBegin(), nlEnd()

Definition at line 1047 of file nl.h.

◆ NL_THRESHOLD

#define NL_THRESHOLD   0x104

Symbolic constant for nlSolverParameterd() to specify the maximum threshold $ \| Ax - b \| / \| b \| $ before the iterative solver is stopped.

Usage:

If the solver is left unspecified or is set to NL_SOLVER_DEFAULT, then a reasonable value is used (1e-6).

Definition at line 387 of file nl.h.

◆ NL_TRUE

#define NL_TRUE   0x1

Constant for true NLbooleans.

See also
NLboolean

Definition at line 315 of file nl.h.

◆ NL_USED_ITERATIONS

#define NL_USED_ITERATIONS   0x107

Symbolic constant for nlGetIntegerv() to obtain the used number of iteration.

The solver exits whenever the maximum number of iterations (NL_MAX_ITERATIONS) is reached or whenever $ \| Ax - b \| / \| b \| $ gets smaller than NL_THRESHOLD. Usage:

NLint used_iter;

Definition at line 432 of file nl.h.

◆ NL_VARIABLES_BUFFER

#define NL_VARIABLES_BUFFER   0x1000

The symbolic constant for variables buffer.

Used as an argument of nlEnable() / nlDisable() / nlIsEnabled() and as an argument of nlBindBuffer.

Definition at line 1268 of file nl.h.

◆ NL_VERBOSE

#define NL_VERBOSE   0x401

Symbolic constant for nlEnable() / nlDisable() to enable or disable messages.

Usage:

or

See also
nlEnable(), nlDisable(), nlIsEnabled()

Definition at line 687 of file nl.h.

Typedef Documentation

◆ NLboolean

typedef unsigned char NLboolean

A truth value (NL_TRUE or NL_FALSE).

See also
NL_TRUE, NL_FALSE

Definition at line 225 of file nl.h.

◆ NLContext

typedef void* NLContext

An OpenNL context.

OpenNL contexts should be considered as opaque ids.

See also
nlNewContext(), nlDeleteContext(), nlMakeCurrent(), nlGetCurrent()

Definition at line 304 of file nl.h.

◆ NLfunc

typedef void(* NLfunc) ()

A function pointer.

See also
nlSetFunction(), nlGetFunction(), NL_FUNC_SOLVER, NL_FUNC_MATRIX, NL_FUNC_PRECONDITIONER, NL_FUNC_PROGRESS

Definition at line 296 of file nl.h.

Function Documentation

◆ nlAddIJCoefficient()

NLAPI void NLAPIENTRY nlAddIJCoefficient ( NLuint  i,
NLuint  j,
NLdouble  value 
)

Adds a coefficient to the current matrix.

This function should be called between a nlBegin(NL_MATRIX) / nlEnd(NL_MATRIX) pair (else an assertion failure is triggered). This function should not be called in least squares mode. There should not be any locked variable when using this function.

Parameters
[in]i,jindices
[in]valuevalue to be added to the coefficient

◆ nlAddIRightHandSide()

NLAPI void NLAPIENTRY nlAddIRightHandSide ( NLuint  i,
NLdouble  value 
)

Adds a coefficient to a component of the right hand side of the equation.

This function should be called between a nlBegin(NL_MATRIX) / nlEnd(NL_MATRIX) pair (else an assertion failure is triggered). This function should not be called in least squares mode. There should not be any locked variable when using this function.

Parameters
[in]iindex of the component
[in]valuevalue to be added to the component

◆ nlBegin()

NLAPI void NLAPIENTRY nlBegin ( NLenum  primitive)

Begins a new primitive.

nlBegin() / nlEnd() calls should be properly nested, as follows (otherwise an assertion failure is triggered):

Parameters
[in]primitiveone of NL_SYSTEM, NL_MATRIX, NL_ROW

◆ nlBindBuffer()

NLAPI void NLAPIENTRY nlBindBuffer ( NLenum  buffer,
NLuint  k,
void *  addr,
NLuint  stride 
)

Specifies a buffer binding to directly map user data to variables instead of using nlGetVariable() / nlSetVariable()

NL_VARIABLES_BUFFER needs to be previouslyu nlEnabled() else this function has no effect.

Parameters
[in]bufferthe type of the buffer, NL_VARIABLES_BUFFER is the only supported value
[in]kthe index of the buffer. If type = NL_VARIABLES_BUFFER, this corresponds to the index of the linear system (0 if there is a single linear system).

◆ nlCoefficient()

NLAPI void NLAPIENTRY nlCoefficient ( NLuint  i,
NLdouble  value 
)

Appends a coefficient to the current row.

This function should be called between a nlBegin(NL_ROW) / nlEnd(NL_ROW) pair (else an assertion failure is triggered). The coefficient is either accumumated into the matrix or into the right-hand side according to the locked/unlocked status of the variable.

Parameters
[in]iindex of the variable this coefficient is related with
[in]valuevalue of the coefficient
See also
nlBegin(), nlEnd(), NL_ROW, NL_RIGHT_HAND_SIDE, NL_ROW_SCALING, NL_NORMALIZE_ROWS

◆ nlDeleteContext()

NLAPI void NLAPIENTRY nlDeleteContext ( NLContext  context)

Destroys an existing OpenNL context.

This deallocates all the memory used by the context.

Parameters
[in,out]contextthe context to be destroyed

◆ nlDisable()

NLAPI void NLAPIENTRY nlDisable ( NLenum  pname)

Sets a boolean parameter to NL_FALSE.

Parameters
[in]pnamethe symbolic name of the parameter

◆ nlEigenSolverParameterd()

NLAPI void NLAPIENTRY nlEigenSolverParameterd ( NLenum  pname,
NLdouble  val 
)

Sets a floating-point parameter of the eigen solver.

Parameters
pnamesymbolic name of the parameter, one of NL_EIGEN_SHIFT, NL_EIGEN_THRESHOLD.

◆ nlEigenSolverParameteri()

NLAPI void NLAPIENTRY nlEigenSolverParameteri ( NLenum  pname,
NLint  val 
)

Sets an integer parameter of the eigen solver.

Parameters
pnamesymbolic name of the parameter, one of NL_EIGEN_SOLVER, NL_NB_EIGENS, NL_NB_VARIABLES, NL_EIGEN_MAX_ITERATIONS, NL_SYMMETRIC.

◆ nlEnable()

NLAPI void NLAPIENTRY nlEnable ( NLenum  pname)

Sets a boolean parameter to NL_TRUE.

Parameters
[in]pnamethe symbolic name of the parameter

◆ nlEnd()

NLAPI void NLAPIENTRY nlEnd ( NLenum  primitive)

Begins a new primitive.

nlBegin()/nlEnd() calls should be properly nested, as follows (otherwise an assertion failure is triggered):

Parameters
[in]primitiveone of NL_SYSTEM, NL_MATRIX, NL_ROW

◆ nlExtensionIsInitialized()

NLAPI NLboolean NLAPIENTRY nlExtensionIsInitialized ( const char *  extension)

Tests whether an OpenNL extension is initialized.

Return values
NL_TRUEif the extension is initialized.
NL_FALSEotherwise

◆ nlGetBooleanv()

NLAPI void NLAPIENTRY nlGetBooleanv ( NLenum  pname,
NLboolean params 
)

Gets the value of a boolean parameter.

Parameters
[in]pnamethe symbolic name of the parameter
[out]paramsa pointer to the obtained parameter value

◆ nlGetCurrent()

NLAPI NLContext NLAPIENTRY nlGetCurrent ( void  )

Gets the current context.

Returns
a handle to the current OpenNL context

◆ nlGetDoublev()

NLAPI void NLAPIENTRY nlGetDoublev ( NLenum  pname,
NLdouble params 
)

Gets the value of a double-precision floating-point parameter.

Parameters
[in]pnamethe symbolic name of the parameter
[out]paramsa pointer to the obtained parameter value

◆ nlGetEigenValue()

NLAPI double NLAPIENTRY nlGetEigenValue ( NLuint  i)

Gets an eigenvalue.

Parameters
iindex of the eigenvalue.
Returns
the i th eigenvalue.

◆ nlGetFunction()

NLAPI void NLAPIENTRY nlGetFunction ( NLenum  pname,
NLfunc param 
)

Gets a function pointer.

Parameters
[in]pnamesymbolic name of the function
[out]paramthe function pointer
See also
nlSetFunction(), NL_FUNC_MATRIX, NL_FUNC_PRECONDITIONER, NL_FUNC_PROGRESS

◆ nlGetIntegerv()

NLAPI void NLAPIENTRY nlGetIntegerv ( NLenum  pname,
NLint params 
)

Gets the value of an integer parameter.

Parameters
[in]pnamethe symbolic name of the parameter
[out]paramsa pointer to the obtained parameter value

◆ nlGetVariable()

NLAPI NLdouble NLAPIENTRY nlGetVariable ( NLuint  i)

Gets the value of a variable.

Parameters
[in]iindex of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
Returns
the value of the variable
See also
nlSetVariable(), nlLockVariable(), nlUnlockVariable(), nlVariableIsLocked()

◆ nlInitExtension()

NLAPI NLboolean NLAPIENTRY nlInitExtension ( const char *  extension)

Initializes an OpenNL extension.

OpenNL may be compiled with several extensions, that provide alternative solvers, such as SuperLU (sparse direct solver) and CNC (iterative solver on the GPU). This function tests whether an extension is supported, and initializes what needs to be initialized in the extention.

Return values
NL_TRUEif the extension is supported and could be sucessfully initialized
NL_FALSEotherwise

◆ nlInitialize()

NLAPI void NLAPIENTRY nlInitialize ( int  argc,
char **  argv 
)

Initializes OpenNL using command line arguments.

Command line arguments of the form nl:<extension>=true|false are parsed and taken into account. Calling this function is not mandatory.

◆ nlIsEnabled()

NLAPI NLboolean nlIsEnabled ( NLenum  pname)

Tests a boolean parameter.

Parameters
[in]pnamethe symbolic name of the parameter
Returns
the value of the boolean parameter

◆ nlLockVariable()

NLAPI void NLAPIENTRY nlLockVariable ( NLuint  index)

Locks a variable.

Locked variables are no-longer computed by OpenNL, their initial value, specified by nlSetVariable(), is used as follows:

  • in standard mode, locked variables are moved to the right hand side
  • in least squares mode, locked variables are removed from the degrees of freedom and combined into the right hand side
    Parameters
    [in]indexindex of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
    See also
    nlGetVariable(), nlSetVariable(), nlUnlockVariable(), nlVariableIsLocked()

◆ nlMakeCurrent()

NLAPI void NLAPIENTRY nlMakeCurrent ( NLContext  context)

Sets the current OpenNL context.

If several OpenNL contexts need to be used simultaneously, this function can be used to redirect all OpenNL calls to a specific context.

◆ nlMatrixMode()

NLAPI void NLAPIENTRY nlMatrixMode ( NLenum  matrix)

Specifies to which matrix the subsequent calls to nlBegin(), nlEnd(), nlCoefficient(), nlAddIJCoefficient() will be applied.

Parameters
[in]matrixone of NL_STIFFNESS_MATRIX (default), NL_MASS_MATRIX

Calling nlMatrixMode() resets the current row to 0.

◆ nlMultiAddIRightHandSide()

NLAPI void NLAPIENTRY nlMultiAddIRightHandSide ( NLuint  i,
NLuint  k,
NLdouble  value 
)

Adds a coefficient to a component of the right hand side of the equation.

This function should be called between a nlBegin(NL_MATRIX) / nlEnd(NL_MATRIX) pair (else an assertion failure is triggered). This function should not be called in least squares mode. There should not be any locked variable when using this function.

Parameters
[in]iindex of the component
[in]kindex of the system
[in]valuevalue to be added to the component

◆ nlMultiGetVariable()

NLAPI NLdouble NLAPIENTRY nlMultiGetVariable ( NLuint  i,
NLuint  k 
)

Gets the value of a variable when there are several systems to solve.

Parameters
[in]iindex of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
[in]kindex of the system, between 0 and nlGetInteger(NL_NB_SYSTEMS)-1
Returns
value value of the variable
See also
nlMultiSetVariable()

◆ nlMultiRightHandSide()

NLAPI void NLAPIENTRY nlMultiRightHandSide ( NLuint  k,
NLdouble  value 
)

Sets the right-hand side of the current row when there are several systems to be solved.

Parameters
[in]kindex of the system, in 0..nlGetInt(NL_NB_SYSTEMS)-1
[in]valuethe coefficient
See also
nlRightHandSide()

◆ nlMultiSetVariable()

NLAPI void NLAPIENTRY nlMultiSetVariable ( NLuint  i,
NLuint  k,
NLdouble  value 
)

Sets the value of a variable when there are several systems to solve.

Parameters
[in]iindex of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
[in]kindex of the system, between 0 and nlGetInteger(NL_NB_SYSTEMS)-1
[in]valuevalue of the variable
See also
nlMultiGetVariable()

◆ nlNewContext()

NLAPI NLContext NLAPIENTRY nlNewContext ( void  )

Creates a new OpenNL context.

Must be called before any other OpenNL function. On exit, the newly created context is the current OpenNL context. Several OpenNL context may coexist. All OpenNL calls are forwarded to the current OpenNL context. Use nlMakeCurrent() to switch between multiple OpenNL contexts. Any created context needs to be destroyed before the end of the program using nlDeleteContext().

Returns
a handle to the newly created context.

◆ nlRightHandSide()

NLAPI void NLAPIENTRY nlRightHandSide ( NLdouble  value)

Sets the right-hand side of the current row.

  • In regular mode, this corresponds to the right-hand side $ b_i $ of equation:

    \[ \sum_j a_{i,j} x_j = b_i \]

  • In least-squares mode (NL_LEAST_SQUARES), this correspond to the term $ b_i $ in:

    \[ \left( \sum_j a_{i,j} x_j - b_i \right)^2 \]

    Usage:
    nlRowParameterd(NL_RIGHT_HAND_SIDE, bi);
    ...
    nlEnd(NL_ROW);
    Precondition
    This function should be called between a nlBegin(NL_ROW) / nlEnd(NL_ROW) pair, and at most once (else an assertion failure is triggered).
    Note
    The right hand side is reset to zero after completion of nlEnd(NL_ROW).
    Parameters
    [in]valuevalue to be accumulated into the right hand side.

◆ nlRowScaling()

NLAPI void NLAPIENTRY nlRowScaling ( NLdouble  value)

Sets the row scaling for the next row.

  • if NL_NORMALIZE_ROWS is not enabled, then the coefficients are multiplied by the specified row scaling coefficient $ s $ as follows when the row is completed:

    \[ \begin{array}{lcl} a_{i,j} & \leftarrow & a_{i,j} \times s \\ b_i & \leftarrow & b_i \times s \end{array} \]

  • if NL_NORMALIZE_ROWS is enabled, then the coefficients are divided by the row length $ L $ and multiplied by the specified row scaling coefficient $ s $ as follows when the row is completed:

    \[ \begin{array}{lcl} L & \leftarrow & \sqrt{\sum_{j} a_{i,j}^2} \\ a_{i,j} & \leftarrow & a_{i,j} \times s / L\\ b_i & \leftarrow & b_i \times s / L \end{array} \]

    Parameters
    [in]valuethe row scaling.
    Note
    The row scaling is used by the next row, and reset to 1.0 after completion of nlEnd(NL_ROW).
    Precondition
    This function should be called after nlBegin(NL_MATRIX) and before nlBegin(NL_ROW).

◆ nlSetFunction()

NLAPI void NLAPIENTRY nlSetFunction ( NLenum  pname,
NLfunc  param 
)

Sets a function pointer.

Parameters
[in]pnamesymbolic name of the function, one of (NL_FUNC_MATRIX, NL_FUNC_PRECONDITIONER, NL_FUNC_PROGRESS)
[in]paramthe function pointer
See also
nlGetFunction(), NL_FUNC_MATRIX, NL_FUNC_PRECONDITIONER, NL_FUNC_PROGRESS

◆ nlSetVariable()

NLAPI void NLAPIENTRY nlSetVariable ( NLuint  i,
NLdouble  value 
)

Sets the value of a variable.

Parameters
[in]iindex of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
[in]valuevalue of the variable
See also
nlGetVariable(), nlLockVariable(), nlUnlockVariable(), nlVariableIsLocked()

◆ nlSolve()

NLAPI NLboolean NLAPIENTRY nlSolve ( void  )

Solves the linear system in the current context.

This function should be called after nlEnd(NL_SYSTEM), else an assertion failure is triggered. Once the function is called, client code may get the value of the computed variables using nlGetVariable().

◆ nlSolverParameterd()

NLAPI void NLAPIENTRY nlSolverParameterd ( NLenum  pname,
NLdouble  param 
)

Specifies a floating-point solver parameter.

This function should be called in the initial state of OpenNL, before any nlBegin() / nlEnd() call.

Parameters
[in]pnamethe symbolic name of the parameter, one of (NL_THRESHOLD, NL_OMEGA).
[in]paramthe double-precision floating-point value of the parameter.
  • If pname = NL_THRESHOLD, then param is the maximum value of $ \| Ax - b \| / \| b \| $ before iterations are stopped;
  • if pname = NL_OMEGA and the specified preconditioner is NL_SSOR, then param is the relaxation parameter, in (0.0 .. 2.0) excluded, for the SSOR preconditioner.

◆ nlSolverParameteri()

NLAPI void NLAPIENTRY nlSolverParameteri ( NLenum  pname,
NLint  param 
)

Specifies an integer solver parameter.

This function should be called in the initial state of OpenNL, before any nlBegin() / nlEnd() call.

Parameters
[in]pnamethe symbolic name of the parameter, one of (NL_SOLVER, NL_NB_VARIABLES, NL_LEAST_SQUARES, NL_MAX_ITERATIONS, NL_SYMMETRIC, NL_INNER_ITERATIONS, NL_PRECONDITIONER).
[in]paramthe integer value of the parameter.
  • If pname = NL_SOLVER then param is the symbolic constant that specifies the solver, i.e. one of (NL_CG, NL_BICGSTAB, NL_GMRES) or one of the extended solvers if supported (NL_xxx_SUPERLU_EXT, NL_CNC_xxx);
  • if pname = NL_NB_VARIABLES then param specifies the number of variables;
  • if pname = NL_LEAST_SQUARES then param is a boolean value (NL_TRUE or NL_FALSE) that specifies whether least squares mode should be used (solves $ A^t A x = A^t b $ with a possibly non-square matrix $ A $);
  • if pname = NL_MAX_ITERATIONS then param is the maximum number of iterations;
  • if pname = NL_SYMMETRIC then param is a boolean value (NL_TRUE or NL_FALSE) that specifies whether the constructed matrix is symmetric. This is a hint for OpenNL that allows using more efficient data structures / solvers. Behavior is undefined if you lied and specify then a non-symmetric matrix !
  • if pname = NL_INNER_ITERATIONS and the solver is NL_GMRES, then param is the number of inner-loop iterations / number of intermediate vectors used by GMRES;
  • if pname = NL_PRECONDITIONER then param is the symbolic constant that specifies the preconditioner, i.e. one of (NL_PRECOND_NONE, NL_PRECOND_JACOBI, NL_PRECOND_SSOR).
See also
NL_SOLVER, NL_NB_VARIABLES, NL_LEAST_SQUARES, NL_MAX_ITERATIONS, NL_SYMMETRIC, NL_INNER_ITERATIONS, NL_PRECONDITIONER

◆ nlUnlockVariable()

NLAPI void NLAPIENTRY nlUnlockVariable ( NLuint  index)

Unlocks a variable.

Locked variables are no-longer computed by OpenNL, their initial value, specified by nlSetVariable(), is used as follows:

  • in standard mode, locked variables are moved to the right hand side
  • in least squares mode, locked variables are removed from the degrees of freedom and combined into the right hand side
    Parameters
    [in]indexindex of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
    See also
    nlGetVariable(), nlSetVariable(), nlLockVariable(), nlVariableIsLocked()

◆ nlUpdateRightHandSide()

NLAPI void NLAPIENTRY nlUpdateRightHandSide ( NLdouble values)

Updates the right hand side of the constructed system in one call.

Parameters
[in]valuesa pointer to an array of N doubles, where N corresponds to the number of not locked variables.

If the current state is solved, it resets the current state to constructed. This function cannot be called if NL_NB_SYSTEMS is different from 1.

◆ nlVariableIsLocked()

NLAPI NLboolean NLAPIENTRY nlVariableIsLocked ( NLuint  index)

Tests whether a variable is locked.

Locked variables are no-longer computed by OpenNL, their initial value, specified by nlSetVariable(), is used as follows:

  • in standard mode, locked variables are moved to the right hand side
  • in least squares mode, locked variables are removed from the degrees of freedom and combined into the right hand side
    Parameters
    [in]indexindex of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
    See also
    nlGetVariable(), nlSetVariable(), nlLockVariable(), nlUnlockVariable()