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

#include "nl_linkage.h"
#include <stdio.h>
#include <stdint.h>
#include "nl_ext.h"
#include "nl_64.h"

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

#define	NL_NO_VARIABLES_INDIRECTION 0x402
	Symbolic constant for nlEnable() / nlDisable() to enable or disable variables indirection. 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	nlGetIntegervL (NLenum pname, NLlong *params)
	Gets the value of a 64 bits 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 int32_t	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 uint32_t	NLuint
	A 4-bytes unsigned integer.

typedef int64_t	NLlong
	A 8-bytes signed integer.

typedef uint64_t	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) (void)
	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...

#define	NL_MATRIX_PATTERN 0x3
	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	nlSetRowLength (NLuint i, NLuint n)
	Specifies the length of a row of the matrix. More...

NLAPI void NLAPIENTRY	nlCoefficient (NLuint i, NLdouble value)
	Appends a coefficient to the current row. More...

NLAPI NLulong NLAPIENTRY	nlAddIJCoefficient (NLuint i, NLuint j, NLdouble value)
	Adds a coefficient to the current matrix. More...

NLAPI void NLAPIENTRY	nlAddIJCoefficientAt (NLuint i, NLuint j, NLdouble value, NLulong index)
	Adds a coefficient to the current matrix with known index. 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...

Logging and messages
typedef int(*	NLprintfFunc) (const char *format,...)
	Function pointer type for user printf function.

typedef int(*	NLfprintfFunc) (FILE out, const char format,...)
	Function pointer type for user fprintf function.

NLAPI void NLAPIENTRY	nlPrintfFuncs (NLprintfFunc f1, NLfprintfFunc f2)
	Specifies user functions for printing messages.

Low-level access
typedef struct NLMatrixStruct *	NLMatrix
	Opaque handle to a matrix.

NLAPI NLMatrix NLAPIENTRY	nlGetCurrentMatrix (void)
	Gets the current matrix. 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
nlNewContext();
nlSolverParameteri(NL_NB_VARIABLES, 2);
 
// Build system
nlBegin(NL_SYSTEM);
nlBegin(NL_MATRIX);
nlBegin(NL_ROW);
nlCoefficient(0, 1.0);
nlCoefficient(1, 2.0);
nlRightHandSide(5.0);
nlEnd(NL_ROW);
nlBegin(NL_ROW);
nlCoefficient(0, 3.0);
nlCoefficient(1, 4.0);
nlRightHandSide(6.0);
nlEnd(NL_ROW);
nlEnd(NL_MATRIX);
nlEnd(NL_SYSTEM);
 
// Solve and get solution
nlSolve();
x = nlGetVariable(0);
y = nlGetVariable(1);
 
// Cleanup
nlDeleteContext(nlGetCurrent());

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
nlNewContext();
nlSolverParameteri(NL_LEAST_SQUARES, NL_TRUE);
nlSolverParameteri(NL_NB_VARIABLES, 2);
 
// Build system
nlBegin(NL_SYSTEM);
nlBegin(NL_MATRIX);
while(!feof(input)) {
   fread(input, "%f %f", &X, &Y);
   nlBegin(NL_ROW);
   nlCoefficient(0, X);
   nlCoefficient(1, 1.0);
   nlRightHandSide(Y);
   nlEnd(NL_ROW);
}
nlEnd(NL_MATRIX);
nlEnd(NL_SYSTEM);
 
// Solve and get solution
nlSolve();
a = nlGetVariable(0);
b = nlGetVariable(1);
 
// Cleanup
fclose(input);
nlDeleteContext(nlGetCurrent());

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
nlNewContext();
nlSolverParameteri(NL_LEAST_SQUARES, NL_TRUE);
nlSolverParameteri(NL_NB_VARIABLES, 2);
 
// Build system
nlBegin(NL_SYSTEM);
nlLockVariable(0);
nlSetVariable(0, 1.0);
nlBegin(NL_MATRIX);
while(!feof(input)) {
   fread(input, "%f %f", &X, &Y);
   nlBegin(NL_ROW);
   nlCoefficient(0, X);
   nlCoefficient(1, 1.0);
   nlRightHandSide(Y);
   nlEnd(NL_ROW);
}
nlEnd(NL_MATRIX);
nlEnd(NL_SYSTEM);
 
// Solve and get solution
nlSolve();
a = nlGetVariable(0);
b = nlGetVariable(1);
 
// Cleanup
fclose(input);
nlDeleteContext(nlGetCurrent());

Example 4 (fine tuning)

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

nlSolverParameteri(NL_SOLVER, NL_GMRES);
nlSolverParameteri(NL_MAX_ITERATIONS, 1000);
nlSolverParameterd(NL_THRESHOLD, 1e-10);

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:

nlSolverParameteri(NL_SOLVER, NL_BICGSTAB);

NL_BICGSTAB

#define NL_BICGSTAB

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

Definition: nl.h:566

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 566 of file nl.h.

◆ NL_CG

#define NL_CG 0x200

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

Usage:

nlSolverParameteri(NL_SOLVER, NL_CG);

NL_CG

#define NL_CG

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

Definition: nl.h:553

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 553 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:

NLdouble seconds;

nlGetDoublev(NL_ELAPSED_TIME, &seconds);

NLdouble

double NLdouble

A double-precision floating-point number.

Definition: nl.h:288

nlGetDoublev

NLAPI void NLAPIENTRY nlGetDoublev(NLenum pname, NLdouble *params)

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

NL_ELAPSED_TIME

#define NL_ELAPSED_TIME

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

Definition: nl.h:469

Definition at line 469 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:

NLdouble error;

nlGetDoublev(NL_ERROR, &error);

NL_ERROR

#define NL_ERROR

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

Definition: nl.h:445

Definition at line 445 of file nl.h.

◆ NL_FALSE

#define NL_FALSE 0x0

Constant for false NLbooleans.

See also: NLboolean

Definition at line 311 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 911 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) {
  ...
}
nlSolverParameteri(NL_PRECONDITIONER, NL_PRECOND_USER);
nlSetFunction(NL_FUNC_PRECONDITIONER, (nlFunc)my_precond_func);

See also: nlSetFunction(), NL_PRECONDITIONER

Definition at line 926 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 947 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() {

NLContextStruct* context = (NLContextStruct*)nlGetCurrent();

...

...

}

nlSetFunction(NL_FUNC_SOLVER, (nlFunc)my_solver);

NL_FUNC_SOLVER
#define NL_FUNC_SOLVER
Symbolic constant for nlSetFunction(), used to replace OpenNL solver with a user-defined routine.
Definition: nl.h:897

NLboolean
unsigned char NLboolean
A truth value (NL_TRUE or NL_FALSE).
Definition: nl.h:221

nl_context.h
Internal OpenNL functions to manipulate contexts.

NLContextStruct
Definition: nl_context.h:104

Definition at line 897 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;

nlGetDoublev(NL_GFLOPS, &gflops);

NL_GFLOPS

#define NL_GFLOPS

Symbolic constant for nlGetDoublev() to obtain the average GFlop/Seconds performance counter during t...

Definition: nl.h:496

Definition at line 496 of file nl.h.

◆ NL_GMRES

#define NL_GMRES 0x202

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

Usage:

nlSolverParameteri(NL_SOLVER, NL_GMRES);

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:

nlSolverParameteri(NL_INNER_ITERATIONS,nn);

NL_INNER_ITERATIONS

#define NL_INNER_ITERATIONS

Symbolic constant for nlSolverParameteri() to specify the number of iterations / number of stored vec...

Definition: nl.h:457

Definition at line 583 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:

nlSolverParameteri(NL_INNER_ITERATIONS, nn);

Definition at line 457 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():

nlSolverParameteri(NL_LEAST_SQUARES, NL_TRUE);

or

nlSolverParameteri(NL_LEAST_SQUARES, NL_FALSE);

NL_FALSE

#define NL_FALSE

Constant for false NLbooleans.

Definition: nl.h:311

Definition at line 361 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 1081 of file nl.h.

◆ NL_MATRIX_PATTERN

#define NL_MATRIX_PATTERN 0x3

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

See also: nlBegin(), nlEnd()

Definition at line 1097 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:

nlSolverParameteri(NL_MAX_ITERATIONS, nb);

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 375 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():

nlSolverParameteri(NL_NB_VARIABLES, nb);

where nb is the number of variables.

Definition at line 347 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);

NL_NNZ

#define NL_NNZ

Symbolic constant for nlGetIntegerv() to obtain the number of non-zero coefficient in the latest line...

Definition: nl.h:509

NLint

int32_t NLint

A 4-bytes signed integer.

Definition: nl.h:248

Definition at line 509 of file nl.h.

◆ NL_NO_VARIABLES_INDIRECTION

#define NL_NO_VARIABLES_INDIRECTION 0x402

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

Usage:

nlEnable(NL_NO_VARIABLES_INDIRECTION)

nlEnable

NLAPI void NLAPIENTRY nlEnable(NLenum pname)

Sets a boolean parameter to NL_TRUE.

NL_NO_VARIABLES_INDIRECTION

#define NL_NO_VARIABLES_INDIRECTION

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

Definition: nl.h:705

or

nlDisable(NL_NO_VARIABLES_INDIRECTION)

nlDisable

NLAPI void NLAPIENTRY nlDisable(NLenum pname)

Sets a boolean parameter to NL_FALSE.

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

Definition at line 705 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:

nlEnable(NL_NORMALIZE_ROWS);

NL_NORMALIZE_ROWS

#define NL_NORMALIZE_ROWS

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

Definition: nl.h:674

or

nlDisable(NL_NORMALIZE_ROWS);

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

Definition at line 674 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:

nlSolverParameterd(NL_OMEGA, omega)

NL_OMEGA

#define NL_OMEGA

Symbolic constant for nlSolverParameterd() to specify the relaxation parameter used by the SSOR prec...

Definition: nl.h:400

See also: NL_PRECOND_SSOR

Definition at line 400 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:

nlSolverParameteri(NL_PRECONDITIONER, NL_PRECOND_JACOBI);

NL_PRECOND_JACOBI

#define NL_PRECOND_JACOBI

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

Definition: nl.h:612

Definition at line 612 of file nl.h.

◆ NL_PRECOND_NONE

#define NL_PRECOND_NONE 0x000

Symbolic constant for nlSolverParameteri() to use no preconditioner.

Usage:

nlSolverParameteri(NL_PRECONDITIONER, NL_PRECOND_NONE);

NL_PRECOND_NONE

#define NL_PRECOND_NONE

Symbolic constant for nlSolverParameteri() to use no preconditioner.

Definition: nl.h:599

Definition at line 599 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:

nlSolverParameteri(NL_PRECONDITIONER, NL_PRECOND_SSOR);

NL_PRECOND_SSOR

#define NL_PRECOND_SSOR

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

Definition: nl.h:627

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 627 of file nl.h.

◆ NL_PRECOND_USER

#define NL_PRECOND_USER 0x303

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

Usage:

nlSolverParameteri(NL_PRECONDITIONER, NL_PRECOND_USER);

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

See also: nlSetFunction(), NL_FUNC_PRECONDITIONER, NL_PRECONDITIONER

Definition at line 640 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:

nlSolverParameteri(NL_PRECONDITIONER, NL_JACOBI);

Definition at line 483 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 1089 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():

nlSolverParameteri(NL_SOLVER, solver);

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 336 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:

nlSolverParameteri(NL_SOLVER,NL_SOLVER_DEFAULT);

NL_SOLVER_DEFAULT

#define NL_SOLVER_DEFAULT

Symbolic constant for nlSolverParameteri() to specify that OpenNL should automatically select a reaso...

Definition: nl.h:540

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 540 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:

nlSolverParameteri(NL_SYMMETRIC, NL_TRUE);

NL_SYMMETRIC

#define NL_SYMMETRIC

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

Definition: nl.h:419

or

nlSolverParameteri(NL_SYMMETRIC, NL_FALSE);

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

Definition at line 419 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 1073 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:

nlSolverParameterd(NL_THRESHOLD, epsilon);

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

Definition at line 388 of file nl.h.

◆ NL_TRUE

#define NL_TRUE 0x1

Constant for true NLbooleans.

See also: NLboolean

Definition at line 316 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;

nlGetIntegerv(NL_USED_ITERATIONS, &used_iter);

nlGetIntegerv

NLAPI void NLAPIENTRY nlGetIntegerv(NLenum pname, NLint *params)

Gets the value of an integer parameter.

NL_USED_ITERATIONS

#define NL_USED_ITERATIONS

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

Definition: nl.h:433

Definition at line 433 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 1345 of file nl.h.

◆ NL_VERBOSE

#define NL_VERBOSE 0x401

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

Usage:

nlEnable(NL_VERBOSE)

NL_VERBOSE

#define NL_VERBOSE

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

Definition: nl.h:689

or

nlDisable(NL_VERBOSE)

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

Definition at line 689 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 221 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 305 of file nl.h.

◆ NLfunc

typedef void(* NLfunc) (void)

A function pointer.

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

Definition at line 297 of file nl.h.

Function Documentation

◆ nlAddIJCoefficient()

NLAPI NLulong 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,j	indices
[in]	value	value to be added to the coefficient

Returns: the location where the coefficient was inserted (index in CRS matrix) if matrix pattern was defined, (NLulong)(-1) otherwise.

◆ nlAddIJCoefficientAt()

NLAPI void NLAPIENTRY nlAddIJCoefficientAt	(	NLuint	i,
		NLuint	j,
		NLdouble	value,
		NLulong	index
	)

Adds a coefficient to the current matrix with known index.

Will be faster than nlAddIJCoefficient() if the location (index in the CRS matrix) of the coefficient is known. 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,j	indices
[in]	value	value to be added to the coefficient
[in]	index	the index where the coefficient is stored, return by previous call to nlAddIJCoefficient(). If unknown, use nlAddIJCoefficient().

◆ 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]	i	index of the component
[in]	value	value 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):

nlBegin(NL_SYSTEM)
  nlBegin(NL_MATRIX)
      nlBegin(NL_ROW)
      nlEnd(NL_ROW)
 ...
      nlBegin(NL_ROW)
      nlEnd(NL_ROW)
  nlEnd(NL_MATRIX)
nlEnd(NL_SYSTEM)

Parameters

[in] primitive one 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]	buffer	the type of the buffer, NL_VARIABLES_BUFFER is the only supported value
[in]	k	the 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).
[in]	addr	the address of the array to be bound.
[in]	stride	number of bytes between two consecutive elements.

◆ 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]	i	index of the variable this coefficient is related with
[in]	value	value 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] context the context to be destroyed

◆ nlDisable()

NLAPI void NLAPIENTRY nlDisable ( NLenum pname )

Sets a boolean parameter to NL_FALSE.

Parameters

[in] pname the symbolic name of the parameter

◆ nlEigenSolverParameterd()

NLAPI void NLAPIENTRY nlEigenSolverParameterd	(	NLenum	pname,
		NLdouble	val
	)

Sets a floating-point parameter of the eigen solver.

Parameters

pname symbolic 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

pname symbolic 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] pname the 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):

nlBegin(NL_SYSTEM)
  nlBegin(NL_MATRIX)
      nlBegin(NL_ROW)
      nlEnd(NL_ROW)
 ...
      nlBegin(NL_ROW)
      nlEnd(NL_ROW)
  nlEnd(NL_MATRIX)
nlEnd(NL_SYSTEM)

Parameters

[in] primitive one 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_TRUE	if the extension is initialized.
NL_FALSE	otherwise

◆ nlGetBooleanv()

NLAPI void NLAPIENTRY nlGetBooleanv	(	NLenum	pname,
		NLboolean *	params
	)

Gets the value of a boolean parameter.

Parameters

[in]	pname	the symbolic name of the parameter
[out]	params	a pointer to the obtained parameter value

◆ nlGetCurrent()

NLAPI NLContext NLAPIENTRY nlGetCurrent ( void )

Gets the current context.

Returns: a handle to the current OpenNL context

◆ nlGetCurrentMatrix()

NLAPI NLMatrix NLAPIENTRY nlGetCurrentMatrix ( void )

Gets the current matrix.

for advanced low-level matrix manipulation

Returns: a pointer to the current matrix, can be a NLSparseMatrix or a NLCRSMatrix depending on whether pattern was pre-created.

◆ nlGetDoublev()

NLAPI void NLAPIENTRY nlGetDoublev	(	NLenum	pname,
		NLdouble *	params
	)

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

Parameters

[in]	pname	the symbolic name of the parameter
[out]	params	a pointer to the obtained parameter value

◆ nlGetEigenValue()

NLAPI double NLAPIENTRY nlGetEigenValue ( NLuint i )

Gets an eigenvalue.

Parameters

i	index of the eigenvalue.

Returns: the i th eigenvalue.

◆ nlGetFunction()

NLAPI void NLAPIENTRY nlGetFunction	(	NLenum	pname,
		NLfunc *	param
	)

Gets a function pointer.

Parameters

[in]	pname	symbolic name of the function
[out]	param	the 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]	pname	the symbolic name of the parameter
[out]	params	a pointer to the obtained parameter value

◆ nlGetIntegervL()

NLAPI void NLAPIENTRY nlGetIntegervL	(	NLenum	pname,
		NLlong *	params
	)

Gets the value of a 64 bits integer parameter.

Parameters

[in]	pname	the symbolic name of the parameter
[out]	params	a pointer to the obtained parameter value

◆ nlGetVariable()

NLAPI NLdouble NLAPIENTRY nlGetVariable ( NLuint i )

Gets the value of a variable.

Parameters

[in] i index 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_TRUE	if the extension is supported and could be successfully initialized
NL_FALSE	otherwise

◆ 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] pname the 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] index index 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] matrix one 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]	i	index of the component
[in]	k	index of the system
[in]	value	value 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]	i	index of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
[in]	k	index 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]	k	index of the system, in 0..nlGetInt(NL_NB_SYSTEMS)-1
[in]	value	the 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]	i	index of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
[in]	k	index of the system, between 0 and nlGetInteger(NL_NB_SYSTEMS)-1
[in]	value	value 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);

nlBegin(NL_ROW);

...

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] value value 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] value the 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]	pname	symbolic name of the function, one of (NL_FUNC_MATRIX, NL_FUNC_PRECONDITIONER, NL_FUNC_PROGRESS)
[in]	param	the function pointer

See also: nlGetFunction(), NL_FUNC_MATRIX, NL_FUNC_PRECONDITIONER, NL_FUNC_PROGRESS

◆ nlSetRowLength()

NLAPI void NLAPIENTRY nlSetRowLength	(	NLuint	i,
		NLuint	n
	)

Specifies the length of a row of the matrix.

Should be called between nlBegin(NL_MATRIX_PATTERN) and nlEnd(NL_MATRIX_PATTERN).

Parameters

[in]	i	the index of the row.
[in]	n	the length of the row.

◆ nlSetVariable()

NLAPI void NLAPIENTRY nlSetVariable	(	NLuint	i,
		NLdouble	value
	)

Sets the value of a variable.

Parameters

[in]	i	index of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1
[in]	value	value 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]	pname	the symbolic name of the parameter, one of (NL_THRESHOLD, NL_OMEGA).
[in]	param	the 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]	pname	the 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]	param	the 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] index index 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] values a 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] index index of the variable, between 0 and nlGetInteger(NL_NB_VARIABLES)-1

See also
nlGetVariable(), nlSetVariable(), nlLockVariable(), nlUnlockVariable()

Macros

Functions

DataTypes and constants

Function pointers

Begin/End

Buffers

EigenSolver

Logging and messages

Low-level access

Detailed Description

Example 1 (a simple linear system)

Example 2 (least squares regression)

Example 3 (least squares regression with locked variable)

Example 4 (fine tuning)

Macro Definition Documentation

◆ NL_BICGSTAB

◆ NL_CG

◆ NL_ELAPSED_TIME

◆ NL_ERROR

◆ NL_FALSE

◆ NL_FUNC_MATRIX

◆ NL_FUNC_PRECONDITIONER

◆ NL_FUNC_PROGRESS

◆ NL_FUNC_SOLVER

◆ NL_GFLOPS

◆ NL_GMRES

◆ NL_INNER_ITERATIONS

◆ NL_LEAST_SQUARES

◆ NL_MATRIX

◆ NL_MATRIX_PATTERN

◆ NL_MAX_ITERATIONS

◆ NL_NB_VARIABLES

◆ NL_NNZ

◆ NL_NO_VARIABLES_INDIRECTION

◆ NL_NORMALIZE_ROWS

◆ NL_OMEGA

◆ NL_PRECOND_JACOBI

◆ NL_PRECOND_NONE

◆ NL_PRECOND_SSOR

◆ NL_PRECOND_USER

◆ NL_PRECONDITIONER

◆ NL_ROW

◆ NL_SOLVER

◆ NL_SOLVER_DEFAULT

◆ NL_SYMMETRIC

◆ NL_SYSTEM

◆ NL_THRESHOLD

◆ NL_TRUE

◆ NL_USED_ITERATIONS

◆ NL_VARIABLES_BUFFER

◆ NL_VERBOSE

Typedef Documentation

◆ NLboolean

◆ NLContext

◆ NLfunc

Function Documentation

◆ nlAddIJCoefficient()

◆ nlAddIJCoefficientAt()

◆ nlAddIRightHandSide()

◆ nlBegin()

◆ nlBindBuffer()

◆ nlCoefficient()

◆ nlDeleteContext()

◆ nlDisable()

◆ nlEigenSolverParameterd()

◆ nlEigenSolverParameteri()

◆ nlEnable()

◆ nlEnd()

◆ nlExtensionIsInitialized()

◆ nlGetBooleanv()

◆ nlGetCurrent()

◆ nlGetCurrentMatrix()

◆ nlGetDoublev()

◆ nlGetEigenValue()

◆ nlGetFunction()

◆ nlGetIntegerv()

◆ nlGetIntegervL()

◆ nlGetVariable()

◆ nlInitExtension()

◆ nlInitialize()