11.16. GTModel for C¶

New in version 3.4.

11.16.1. Types¶

GTApproxModel¶: GTApprox model, binary data.

GTModelError¶: Model error description.

11.16.2. GTApproxModel.h¶

const char* GTApproxModelDescription(const GTApproxModel* model, GTModelError** errorDescription)¶

Get model description in JSON format.

Parameters:	model – model pointer errorDescription – memory location to store an error description pointer
Returns:	model description

Returns a zero-terminated string with model description. The description contains all technical information that can be gathered from the model, including build-time error prediction.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

GTApproxModel* GTApproxModelLoad(const char* modelFileName, GTModelError** errorDescription)¶

Load a model from file.

Parameters:	modelFileName – zero-terminated filename errorDescription – memory location to store an error description pointer
Returns:	model pointer

On success, returns a pointer to model data, and error description pointer is NULL.

On failure, returns a NULL model pointer and stores error description. Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

GTApproxModel* GTApproxModelMemoryLoad(const unsigned char* modelBinaryData, int modelBinaryDataSize, GTModelError** errorDescription)¶

Load a model from memory.

Parameters:	modelBinaryData – model data pointer modelBinaryDataSize – model data size errorDescription – memory location to store an error description pointer
Returns:	model pointer

On success, returns a pointer to model data, and error description pointer is NULL.

On failure, returns a NULL model pointer and stores error description. Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

int GTApproxModelCalc(const GTApproxModel* model, const double* X, int incX, double* F, int incF, GTModelError** errorDescription)¶

Evaluate the model.

Parameters:	model – model pointer X – pointer to the first element of the input vector incX – increment for the elements of X F – output buffer pointer incF – increment for the elements of F errorDescription – memory location to store an error description pointer
Returns:	status

Evaluates the model for point X and stores result to F. The output buffer must be preallocated and must be big enough to hold all data, taking incF into account.

incX specifies the distance, measured in sizeof(double), between the elements of the input vector — that is, the j-th component is X[j*incX]. Similarly, incF specifies the distance in sizeof(double) between the elements of the output vector, and i-th component is F[i*incF].

Returns non-zero value on success, 0 on failure.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

int GTApproxModelCalcAE(const GTApproxModel* model, const double* X, int incX, double* AE, int incAE, GTModelError** errorDescription)¶

Calculate the accuracy evaluation estimate.

Parameters:	model – model pointer X – pointer to the first element of the input vector incX – increment for the elements of X AE – output buffer pointer incAE – increment for the elements of AE errorDescription – memory location to store an error description pointer
Returns:	status

Calculates model accuracy estimate for point X and stores result to AE. The output buffer must be preallocated and must be big enough to hold all data, taking incAE into account.

incX specifies the distance, measured in sizeof(double), between the elements of the input vector — that is, the j-th component is X[j*incX]. Similarly, incAE specifies the distance in sizeof(double) between the elements of the output vector, and i-th component is AE[i*incAE].

Returns non-zero value on success, 0 on failure.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

int GTApproxModelFree(const GTApproxModel* model)¶

Destroy model and free resources.

Parameters:	model – model pointer
Returns:	status

Returns non-zero value on success, 0 on failure.

int GTApproxModelGrad(const GTApproxModel* model, const double* X, int incX, double* dFdX, int incDF, int incDX, GTModelError** errorDescription)¶

Evaluate model gradient.

Parameters:

model – model pointer
X – pointer to the first element of the input vector
incX – increment for the elements of X
dFdX – output buffer pointer
incDF – increment of dFdX for partial derivatives of different outputs with respect to the same input
incDX – increment of dFdX for partial derivatives of the same output with respect to different inputs
errorDescription – memory location to store an error description pointer

Returns:

status

Evaluates model gradient for point X and stores results to dFdX. The output buffer must be preallocated and must be big enough to hold the gradient data.

incDF specifies the distance, measured in sizeof(double), between the partial derivatives of the i-th and (i+1)-th model outputs with respect to the same input. incDX specifies the distance in sizeof(double) between the partial derivatives of the i-th output with respect to the j-th and (j+1)-th model inputs.

The partial derivative of the i-th model output with respect to the j-th model input will be stored to dFdX[incDF*i+incDX*j]. For example, consider a model with n inputs and m outputs. To store its gradient in an F-major (“outputwise”) order, allocate an m by n double buffer:

double dFdX[m][n];

Then call GTApproxModelGrad() with incDF = n (that is, sizeof(dFdX)/sizeof(dFdX[0])) and incDX = 1. Thus dF[i][j] holds \(\frac{dF_i}{dX_j}\), the partial derivative of the i-th model output with respect to j-th model input.

To store the gradient in an X-major (“inputwise”) order, allocate an n by m buffer and call GTApproxModelGrad() with incDF = 1 and incDX = m.

Returns non-zero value on success, 0 on failure.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

int GTApproxModelGradAE(const GTApproxModel* model, const double* X, int incX, double* dAEdX, int incDAE, int incDX, GTModelError** errorDescription)¶

Calculate the gradient of the accuracy evaluation function (AE).

Parameters:

model – model pointer
X – pointer to the first element of the input vector
incX – increment for the elements of X
dAEdX – output buffer pointer
incDAE – increment of dAEdX for partial derivatives of AE for different outputs with respect to the same input
incDX – increment of dAEdX for partial derivatives of AE for the same output with respect to different inputs
errorDescription – memory location to store an error description pointer

Returns:

status

Evaluates the AE gradient for point X and stores results to dAEdX. The output buffer must be preallocated and must be big enough to hold the gradient data.

incDAE specifies the distance, measured in sizeof(double), between the partial derivatives of AE for the i-th and (i+1)-th model outputs with respect to the same input. incDX specifies the distance in sizeof(double) between the partial derivatives of AE for the i-th output with respect to the j-th and (j+1)-th model inputs.

Gradient storage methods are similar to GTApproxModelGrad() — see its description for details.

Returns non-zero value on success, 0 on failure.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

int GTApproxModelHasAE(const GTApproxModel* model, GTModelError** errorDescription)¶

Check if the model supports accuracy evaluation.

Parameters:	model – model pointer errorDescription – memory location to store an error description pointer
Returns:	AE availability status

Returns non-zero value if AE is available from the model, or 0 otherwise.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

int GTApproxModelInputSize(const GTApproxModel* model, GTModelError** errorDescription)¶

Get model input dimension.

Parameters:	model – model pointer errorDescription – memory location to store an error description pointer
Returns:	input dimension

Returns the number of model input (X) components.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

int GTApproxModelOutputSize(const GTApproxModel* model, GTModelError** errorDescription)¶

Get model output dimension.

Parameters:	model – model pointer errorDescription – memory location to store an error description pointer
Returns:	output dimension

Returns the number of model output (F) components.

Note that unless the errorDescription argument is NULL, the error description should be destroyed by GTModelErrorFree().

11.16.3. GTModelError.h¶

const char* GTModelErrorDescription(GTModelError* error)¶

Get error description.

Parameters:	error – error description pointer
Returns:	error description

Returns a pointer to zero-terminated string with error description.

This function always returns a pointer to a valid string, even if given a NULL error description pointer.

int GTModelErrorFree(GTModelError* error)¶

Destroy error description and free associated resources.

Parameters:	error – error description pointer
Returns:	status

Returns non-zero value on success, 0 on failure.