The paceval. API. Simple to use and adapt to your requirements.

API- the paceval. application programming interface

The API is simple to use and very powerful. It is written in standard C/C++, but, you can easily create your own interfaces for your development environment and your programming language.

If you own a paceval. source-code license you can easily adapt and extend the API to your requirements. Or create new solutions for your own target hardware.

Application programming interface – paceval.

Version 4

Date: 22nd of January 2018

OVERVIEW

PACEVAL_HANDLE paceval_CreateComputation(
const char* functionString_in,
unsigned long
numberOfVariables_in,
const char*
variables_in,
bool
useInterval,
paceval_callbackStatusType* paceval_callbackStatus_in);

NAME

paceval_CreateComputation

DESCRIPTION

Creates a paceval.-Computation object with the specified attributes and returns its HANDLE.

PARAMETERS

const char* functionString_in – Points to a null-terminated string to be used as the function to work with.
see also Product brief-Supported terms>>

unsigned long numberOfVariables_in – Specifies the number of variables to work with. E.g. if the variables are “xValue yValue zValue” or “x y z” numberOfVariables_in must be set to 3.

const char* variables_in – Points to a null-terminated string specifying the names of the working variables. Generally the variables must be separated by a blank. E.g. the variables xValue, yValue, zValue must be set with “xValue yValue zValue” or the variables x, y, z must be set with “x y z”.

bool useInterval – Enables or disables the Trusted Interval Computation, TINC™ (paceval. specific) putting bounds on rounding errors and measurement errors of the computation system to yield reliable results.

paceval_callbackStatusType* paceval_callbackStatus_in – A user-defined callback function to give status information of the paceval.-Computation object.

RETURN VALUE

PACEVAL_HANDLE – The return value is the HANDLE of the created paceval-Computation object. paceval_GetIsError() should be called to check whether an error has occurred. To get more information about the error, call paceval_GetErrorInformation().

EXAMPLE

see Hello paceval Examples-example 1 of the paceval. SDK for details

bool paceval_DeleteComputation(
PACEVAL_HANDLE handle_pacevalComputation_in);

NAME

paceval_DeleteComputation

DESCRIPTION

Deletes a paceval.-Computation object.

PARAMETERS

PACEVAL_HANDLE handle_pacevalComputation_in – Identifies the paceval.-Computation object.

RETURN VALUE

bool – If the function succeeds, the return value is true. If the given HANDLE is not valid the return value is false.

double paceval_dGetComputationResult(
PACEVAL_HANDLE handle_pacevalComputation_in,
double
values_in[],
double
* trustedMinResult_out,
double
* trustedMaxResult_out);

use paceval_fGetComputationResult(…) for float values
use paceval_ldGetComputationResult(…) for long double values

NAME

paceval_dGetComputationResult
paceval_fGetComputationResult
paceval_ldGetComputationResult

DESCRIPTION

Solves the computation with the variables declared by paceval_CreateComputation(…) and with the given values.

PARAMETERS

PACEVAL_HANDLE handle_pacevalComputation_in – Identifies the paceval.-Computation object.

double values_in[] – Array of double defining the values of the variables.

double* trustedMinResult_out – If Trusted Interval Computation was enabled by paceval_CreateComputation(…) this retrieves the minimum/lower interval limit of the computation.
Annotation: In case of an error the value is not specified.

double* trustedMaxResult_out – If Trusted Interval Computation was enabled by paceval_CreateComputation(…) this retrieves the maximum/upper interval limit of the computation.
Annotation: In case of an error the value is not specified.

RETURN VALUE

double – If the function succeeds, the return value is the result of the computation.
paceval_GetIsError() should be called to check whether an error has occurred. To get more information about the error, call paceval_GetErrorInformation().
Annotation: In case of an error the return value is not specified.

EXAMPLE

see Hello paceval Examples-example 1 of the paceval. SDK for details

bool paceval_GetIsError(
PACEVAL_HANDLE handle_pacevalComputation_in);

NAME

paceval_GetIsError

DESCRIPTION

Determines whether an error has occurred. To get more information about the error, call paceval_GetErrorInformation().

PARAMETERS

PACEVAL_HANDLE handle_pacevalComputation_in – Identifies the paceval.-Computation object.

RETURN VALUE

bool – If an error has occurred, the return value is true. Otherwise it is false.

int paceval_GetErrorInformation(
PACEVAL_HANDLE handle_pacevalComputation_in,
char*
strOperator,
long*
errPosition);

NAME

paceval_GetErrorInformation

DESCRIPTION

The paceval_GetErrorInformation() function returns the paceval.-Computation object error code value.
Possible errors are analysis and computation errors. Errors during the analysis should be checked after of the object by paceval_CreateComputation().
Errors during the computation should be checked after calling paceval_GetComputationResult().

PARAMETERS

PACEVAL_HANDLE handle_pacevalComputation_in – Identifies the paceval.-Computation object.

char* strOperator – Buffer to get the operator causing the error.

long* errPosition – Position in the function where the error occurred.

RETURN VALUE

int – The return value is the paceval.-Computation object error, see also paceval_eErrorTypes in paceval_main.h.

PACEVAL_ERR_NO_ERROR – No error has occurred during analysis or computation.
PACEVAL_ERR_FATAL_INITIALIZE_LIBRARY_NOT_CALLED
PACEVAL_ERR_FATAL_NO_LICENSE
PACEVAL_ERR_ANALYSIS_UNKNOWN_SIGN_OR_FUNCTION
PACEVAL_ERR_ANALYSIS_BRACKETS
PACEVAL_ERR_ANALYSIS_UNKNOWN_CONSTANT_OR_VARIABLE
PACEVAL_ERR_ANALYSIS_COMMENT
PACEVAL_ERR_ANALYSIS_NUMBER_OF_VARIABLES
PACEVAL_ERR_ANALYSIS_MISPLACED_SIGN_CALCULATION
PACEVAL_ERR_ANALYSIS_UNEXPECTED_END
PACEVAL_ERR_ANALYSIS_WRONGLY_USED_FUNCTION
PACEVAL_ERR_ANALYSIS_NO_USER_FUNCTION
PACEVAL_ERR_ANALYSIS_UNKNOWN_CHARACTER
PACEVAL_ERR_ANALYSIS_WRONGLY_USED_CONSTANT_OR_VALUE
PACEVAL_ERR_ANALYSIS_MISSING_OPERATOR
PACEVAL_ERR_ANALYSIS_OUT_OF_MEMORY
PACEVAL_ERR_ANALYSIS_UNKNOWN_OBJECT_TYPE
PACEVAL_ERR_ANALYSIS_MEMORY_CLEANUP
PACEVAL_ERR_ANALYSIS_USER_ABORT
PACEVAL_ERR_COMPUTATION_HANDLE_INVALID
PACEVAL_ERR_COMPUTATION_MULTIPLICATION
PACEVAL_ERR_COMPUTATION_DIVISION
PACEVAL_ERR_COMPUTATION_FUNCTION
PACEVAL_ERR_COMPUTATION_ADDITION
PACEVAL_ERR_COMPUTATION_SUBTRACTION
PACEVAL_ERR_COMPUTATION_UNSPECIFIED
PACEVAL_ERR_COMPUTATION_INTERVAL_RESULT
PACEVAL_ERR_COMPUTATION_USER_ABORT
PACEVAL_ERR_COMPUTATION_RESULT
PACEVAL_ERR_COMPUTATION_BUSY
PACEVAL_ERR_COMPUTATION_USER_COMPILER_NOT_SUPPORTS_LONG_DOUBLE

EXAMPLE

see Hello paceval Examples-example 1 of the paceval. SDK for details

int paceval_GetComputationVersionString(
PACEVAL_HANDLE handle_pacevalComputation_in,
char*
paceval_strVersion_in);

NAME

paceval_GetComputationVersionString

DESCRIPTION

Returns the version string including the version number of the paceval.-Computation object.

PARAMETERS

PACEVAL_HANDLE handle_pacevalComputation_in – Identifies the paceval.-Computation object.

char* paceval_strVersion_in – Points to the buffer that will receive the string. Set paceval_strVersion_in to NULL to receive the length of the version string, see RETURN VALUE.

RETURN VALUE

int – The return value is the length of the version string.

paceval_InitializeLibrary();

NAME

paceval_InitializeLibrary

DESCRIPTION

You must call paceval_InitializeLibrary() before you use paceval.-API function calls in your code.
Annotation: In case you use the standard Windows library version this loads and initializes the paceval_win32.dll.

RETURN VALUE

bool – If the function succeeds, the return value is true. Otherwise it is false.

paceval_FreeLibrary();

NAME

paceval_FreeLibrary

DESCRIPTION

You must call paceval_FreeLibrary() at the end of your application.
Annotation: In case you use the standard Windows library version this frees the paceval_win32.dll.

RETURN VALUE

bool – If the function succeeds, the return value is true. Otherwise it is false.

int paceval_dConvertFloatToString(
char* destinationString_in,
double float_in);

use paceval_fConvertFloatToString(…) for float values
use paceval_ldConvertFloatToString(…) for long double values

NAME

paceval_dConvertFloatToString
paceval_fConvertFloatToString
paceval_ldConvertFloatToString

DESCRIPTION

Converts a floating point number to a string.

PARAMETERS

char* destinationString_in – Points to the buffer that will receive the string of the coverted floating point number.
Annotation: In case of an error the buffer is not specified.

double float_in – The floating point number to convert.

RETURN VALUE

int – If the function succeeds, the return value is >0 and gives the precision of the conversion. Otherwise the return value is <0.

EXAMPLE

see Hello paceval Examples-example 2 of the paceval. SDK for details

double paceval_dConvertStringToFloat(
const char* sourceString_in,
int* errorType_out,
long* errPosition,
bool useInterval,
double* trustedMinResult_out,
double* trustedMaxResult_out);

use paceval_fConvertStringToFloat(…) for float values
use paceval_ldConvertStringToFloat(…) for long double values

NAME

paceval_dConvertStringToFloat
paceval_fConvertStringToFloat
paceval_ldConvertStringToFloat

DESCRIPTION

Converts a to a string to a floating point number. In case a caluclation is given in the string the result is converted.

PARAMETERS

const char* sourceString_in – The string to convert.

int* errorType_out – Points to the buffer that will receive the paceval.-Computation object error, see also paceval_eErrorTypes in paceval_main.h.

long* errPosition – Position in the string where the error occurred.

bool useInterval – – Enables or disables the Trusted Interval Computation, TINC™ (paceval. specific) for the conversion.

double* trustedMinResult_out – If Trusted Interval Computation was enabled this retrieves the minimum/lower interval limit of the conversion.
Annotation: In case of an error the value is not specified.

double* trustedMaxResult_out – If Trusted Interval Computation was enabled this retrieves the maximum/upper interval limit of the conversion.
Annotation: In case of an error the value is not specified.

RETURN VALUE

double – If the function succeeds, the return value is the result of the conversion.
Annotation: In case of an error the return value is not specified.

EXAMPLE

see Hello_paceval_Examples-example2 of the paceval. SDK for details

.

bool paceval_dGetComputationResultExt(
PACEVAL_HANDLE handle_pacevalComputation_in,
double values_in[],
unsigned long numberOfCalculations_in,
double* results_out,
double* trustedMinResults_out,
double* trustedMaxResults_out,
int* errorType_out);

use paceval_fGetComputationResultExt(…) for float values
use paceval_ldGetComputationResultExt(…) for long double values

NAME

paceval_dGetComputationResultExt
paceval_fGetComputationResultExt
paceval_ldGetComputationResultExt

DESCRIPTION

Solves multiple times the computation with different values for the variables declared by paceval_CreateComputation(…). You should use paceval_dGetComputationResultExt(…) to get many results for a single computaton at once (e.g. to plot functions).

PARAMETERS

PACEVAL_HANDLE handle_pacevalComputation_in – Identifies the paceval.-Computation object.

double values_in[] – Array of double defining the multiple values of the variables.

unsigned long numberOfCalculations_in – Specifies the number of different calculations you want to run. This number specifies the size of the array values_in[]. E.g. if the number of variables declared is 50 and the number of calculations is 1000 the size of the array values_in[] is 50*1000; The order of the array values_in[] must be variable values for the first calculation, then variable values for the second calculation and so on.

double* results_out – Pointer to an array for the results of the computation with the multiple values of the variables.
Annotation: In case of an error the values are not specified.

double* trustedMinResult_out – Pointer to an array for the minimum/lower interval limits.
Annotation: In case of an error the values are not specified.

double* trustedMaxResult_out– Pointer to an array for the maximum/upper interval limits.
Annotation: In case of an error the value is not specified.

int* errorType_out – Pointer to an array of the paceval.-Computation object errors, see also paceval_eErrorTypes in paceval_main.h.

RETURN VALUE

bool – The return value indicates paceval.-Computation object errors. You should check the array errorType_out in this case.

EXAMPLE

see Hello_paceval_Examples-example3 of the paceval. SDK for details

.

bool paceval_dGetMultipleComputationsResults(
PACEVAL_HANDLE handle_pacevalComputations_in[],
unsigned long numberOfpacevalComputations_in,
double values_in[],
double* results_out,
double* trustedMinResults_out,
double* trustedMaxResults_out,
int* errorTypes_out);

use paceval_fGetMultipleComputationsResults(…) for float values
use paceval_ldGetMultipleComputationsResults(…) for long double values

NAME

paceval_dGetMultipleComputationsResults
paceval_fGetMultipleComputationsResults
paceval_ldGetMultipleComputationsResults

DESCRIPTION

Solves multiple computations with values for the variables declared by paceval_CreateComputation(…). You should use paceval_dGetMultipleComputationsResults(…) to get results for a multiple computatons at once (e.g. for neural networks).
Annotation: You must use the same number of variables and the same declared variables. To do so you can simply declare all variables in each of the the calls for paceval_CreateComputation(…). There is no performance issue in case a variable is declared but not used by a paceval.-Computation object.

PARAMETERS

PACEVAL_HANDLE handle_pacevalComputation_in[] – Array of the paceval.-Computation objects.

unsigned long numberOfCalculations_in – Specifies the number of the paceval.-Computation objects.

double values_in[] – Array of double defining the values of the variables.

double* results_out – Pointer to an array for the results of the multiple computations.
Annotation: In case of an error the values are not specified.

double* trustedMinResult_out – Pointer to an array for the minimum/lower interval limits.
Annotation: In case of an error the values are not specified.

double* trustedMaxResult_out– Pointer to an array for the maximum/upper interval limits.
Annotation: In case of an error the value is not specified.

int* errorType_out – Pointer to an array of the paceval.-Computation object errors, see also paceval_eErrorTypes in paceval_main.h.

RETURN VALUE

bool – The return value indicates paceval.-Computation object errors. You should check the array errorType_out in this case.

EXAMPLE

see Hello_paceval_Examples-example 4 of the paceval. SDK for details

.

double paceval_dmathv(
PACEVAL_HANDLE* handle_pacevalComputation_in,
int* errorType_out,
const char* functionString_in,
unsigned long numberOfVariables_in,
const char* variables_in,
);

use paceval_fmathv(…) for float values
use paceval_ldmathv(…) for long double values

NAME

paceval_dmathv
paceval_fmathv
paceval_ldmathv

DESCRIPTION

A convenience function to get results of computations in a single step.

PARAMETERS

PACEVAL_HANDLE* handle_pacevalComputation_in – Pointer to a paceval.-Computation object. If handle_pacevalComputation_in is not NULL this buffer is used for the created paceval.-Computation object. In this case the paceval.-Computation object will not be deleted and you must call paceval_DeleteComputation(…).

int* errorType_out – Points to the buffer that will receive the paceval.-Computation object error, see also paceval_eErrorTypes in paceval_main.h.

const char* functionString_in – Points to a null-terminated string to be used as the function to work with.
see also Product brief-Supported terms>>

unsigned long numberOfVariables_in – Specifies the number of variables to work with. E.g. if the variables are “xValue yValue zValue” or “x y z” numberOfVariables_in must be set to 3.

const char* variables_in – Points to a null-terminated string specifying the names of the working variables. Generally the variables must be separated by a blank. E.g. the variables xValue, yValue, zValue must be set with “xValue yValue zValue” or the variables x, y, z must be set with “x y z”.

– Parameters comma seperated will be interpreted as double values for the variables.

RETURN VALUE

double – If the function succeeds, the return value is the result of the computation.
paceval_GetIsError() should be called to check whether an error has occurred. To get more information about the error, call paceval_GetErrorInformation().
Annotation: In case of an error the return value is not specified.

EXAMPLE

see Hello_paceval_Examples-example 2 of the paceval. SDK for details

.

double paceval_dmathvi(
PACEVAL_HANDLE* handle_pacevalComputation_in,
int* errorType_out,
double* trustedMinResult_out,
double* trustedMaxResult_out,
const char* functionString_in,
unsigned long numberOfVariables_in,
const char* variables_in,
);

use paceval_fmathvi(…) for float values
use paceval_ldmathvi(…) for long double values

NAME

paceval_dmathvi
paceval_fmathvi
paceval_ldmathvi

DESCRIPTION

A convenience function to get results of computations in a single step with Trusted Interval Computation.

PARAMETERS

PACEVAL_HANDLE* handle_pacevalComputation_in – Pointer to a paceval.-Computation object. If handle_pacevalComputation_in is not NULL this buffer is used for the created paceval.-Computation object. In this case the paceval.-Computation object will not be deleted and you must call paceval_DeleteComputation(…).

int* errorType_out – Points to the buffer that will receive the paceval.-Computation object error, see also paceval_eErrorTypes in paceval_main.h.

double* trustedMinResult_out – This buffer retrieves the minimum/lower interval limit of the computation.
Annotation: In case of an error the value is not specified.

double* trustedMaxResult_out – This buffer retrieves the maximum/upper interval limit of the computation.
Annotation: In case of an error the value is not specified.

const char* functionString_in – Points to a null-terminated string to be used as the function to work with.
see also Product brief-Supported terms>>

unsigned long numberOfVariables_in – Specifies the number of variables to work with. E.g. if the variables are “xValue yValue zValue” or “x y z” numberOfVariables_in must be set to 3.

const char* variables_in – Points to a null-terminated string specifying the names of the working variables. Generally the variables must be separated by a blank. E.g. the variables xValue, yValue, zValue must be set with “xValue yValue zValue” or the variables x, y, z must be set with “x y z”.

– Parameters comma seperated will be interpreted as double values for the variables.

RETURN VALUE

double – If the function succeeds, the return value is the result of the computation.
paceval_GetIsError() should be called to check whether an error has occurred. To get more information about the error, call paceval_GetErrorInformation().
Annotation: In case of an error the return value is not specified.

EXAMPLE

see Hello_paceval_Examples-example 2 of the paceval. SDK for details

.

unsigned long paceval_CreateXMLFromParameters(
char* bufferXML,
const char* functionString_in,
unsigned long numberOfVariables_in,
const char* variables_in,
const char* valuesString_in,
bool useInterval);

NAME

paceval_CreateXMLFromParameters

DESCRIPTION

A helper function to create XML data representing a paceval.-Computation object. You can use it to store data representing a computation to a file system or to transmit it via a network or channel.

PARAMETERS

char* bufferXML – Pointer to a buffer for the XML data. Set bufferXML to NULL to receive the length of the version string, see RETURN VALUE.

const char* functionString_in – Points to a null-terminated string representing the function.
see also Product brief-Supported terms>>

unsigned long numberOfVariables_in – Specifies the number of variables.

const char* variables_in – Points to a null-terminated string specifying the names of the variables in one string seperated by blanks.

const char* valuesString_in – Specifies the values for the variables in one string seperated by semicolons (;).

bool useInterval – Specifies whether Trusted Interval Computation is enabled or not.

RETURN VALUE

unsigned long – The return value is the size of the XML data. In case of an error the return value is 0.

EXAMPLE

see Hello_paceval_Examples-example 5 of the paceval. SDK for details

.

int paceval_ReadParametersFromXML(
const char* dataXML,
unsigned long* functionStringLength_out,
unsigned long* variablesStringLength_out,
unsigned long* numberOfVariables_out,
unsigned long* valuesStringLength_out,
char* functionString_out,
char* variables_out,
char* valuesString_out,
bool* useInterval_out);

NAME

paceval_ReadParametersFromXML

DESCRIPTION

A helper function to read XML data representing a paceval.-Computation object. You can use it to read data representing a computation from a file system or to receive it via a network or channel.

PARAMETERS

char* dataXML – Pointer to the XML data.

unsigned long* functionStringLength_out – The length of the function string.

unsigned long* variablesStringLength_out – The length of the variable names in one string.

unsigned long* numberOfVariables_out – The number of variables.

unsigned long* valuesStringLength_out – The length of the values seperated by blanks in one string.

char* functionString_out – Points to the buffer for the function string. Set functionString_out to NULL to receive the length at first with functionStringLength_out.

char* variables_out – Points to the buffer for the variable names in one string. Set variables_out to NULL to receive the length at first with variablesStringLength_out.

char* valuesString_out – Points to the buffer for the values seperated by semicolons (;) in one string. Set valuesString_out to NULL to receive the length at first with valuesStringLength_out.

bool* useInterval_out – Points to the buffer specifying whether

const char* variables_in – Specifies the values for the variables in one string seperated by blanks.

bool useInterval – Specifies whether Trusted Interval Computation is enabled or not.

RETURN VALUE

int – In case of an error the return value is <0.

EXAMPLE

see Hello_paceval_Examples-example 5 of the paceval. SDK for details

.