C_SolveEquation

C_SolveEquation is used to solve equations of the form Y(X) = TargetY where Y(X) is an application-defined function. That is a value of X is found which satisfies the above equation. C_SolveEquation currently uses the Newton-Raphson method to solve the equation. Newton-Raphson is an iterative solution method that repeatedly calls Y(X). After each call to Y(X) it chooses a better estimate of X and then calls Y(X) again. This is repeated until either:

an X is chosen which satisfies | Y(X) - TargetY | < Tolerance (Tolerance is specified in lpSolveEquationParameters), or
more than MaxNumberOfIterations iterations have been used MaxNumberOfIterations is specified in lpSolveEquationParameters).

Note that the equation only solved up to a tolerance because machine accuracy makes it impossible in general to find an exact solution.

void C_SolveEquation(

INT_PTR Data,

TSolveEquationCalcYProc SolveEquationCalcYProc,

double *lpX,

double TargetY,

const TSolveEquationParameters *lpSolveEquationParameters,

int *lpStatus

);

Parameters

Data (IN)

An application defined value that is passed to the callback function SolveEquationCalcYProc.

SolveEquationCalcYProc (IN)

A callback function which defines Y(X).

lpX (IN/OUT)

On calling the function this parameter specifies the initial value of X used by the solution algorithm. In general, the closer this value is to the solution, the faster the solution will be found.

On successful return from the function this parameter contains the solution to the equation.

TargetY (IN)

The value used in the equation Y(X) = TargetY.

lpSolveEquationParameters (IN)

Points to a structure containing the convergence parameters for the solve equation algorithm.

Before calling the C_SolveEquation function, set the Size member of the TSolveEquationParameters data structure to sizeof(TSolveEquationParameters).

If this parameter is passed as NULL then default convergence parameters are used. These default parameters are the same as those returned by C_GetDefaultSolveEquationParameters.

lpStatus (OUT)

Points to a variable in which the status result for the function call will be returned.