C_interface_library

Data Structures
struct	modena_function_t
struct	modena_index_set_t
struct	modena_siunits_t
struct	modena_inputs_t
struct	modena_outputs_t
struct	modena_substitute_model_t
	stores a model and mapping for substitution More...
struct	modena_model_t
	stores a surrogate model More...

Typedefs
typedef struct modena_function_t	modena_function_t
typedef struct modena_index_set_t	modena_index_set_t
typedef struct modena_substitute_model_t	modena_substitute_model_t
	stores a model and mapping for substitution
typedef struct modena_model_t	modena_model_t
	stores a surrogate model

Functions
modena_function_t *	modena_function_new (const char *functionId)
modena_function_t *	modena_function_new_from_model (const struct modena_model_t *self)
modena_index_set_t *	modena_function_get_index_set (const modena_function_t *self, const char *name)
void	modena_function_destroy (modena_function_t *model)
modena_index_set_t *	modena_index_set_new (const char *indexSetId)
size_t	modena_index_set_get_index (const modena_index_set_t *self, const char *name)
const char *	modena_index_set_get_name (const modena_index_set_t *self, const size_t index)
size_t	modena_index_set_iterator_start (const modena_index_set_t *self)
size_t	modena_index_set_iterator_end (const modena_index_set_t *self)
void	modena_index_set_destroy (modena_index_set_t *indexSet)
modena_siunits_t *	modena_siunits_new ()
int	modena_siunits_get (const modena_siunits_t *self, const size_t i)
void	modena_siunits_destroy (modena_siunits_t *self)
modena_inputs_t *	modena_inputs_new (const struct modena_model_t *self)
modena_outputs_t *	modena_outputs_new (const struct modena_model_t *self)
void	modena_inputs_destroy (modena_inputs_t *inputs)
void	modena_outputs_destroy (modena_outputs_t *outputs)
INLINE_DECL void	modena_inputs_set (modena_inputs_t *self, const size_t i, double x)
INLINE_DECL void	modena_inherited_inputs_set (modena_inputs_t *self, const size_t i, double x)
INLINE_DECL double	modena_inputs_get (const modena_inputs_t *self, const size_t i)
INLINE_DECL double	modena_inherited_inputs_get (const modena_inputs_t *self, const size_t i)
INLINE_DECL double	modena_outputs_get (const modena_outputs_t *self, const size_t i)
modena_model_t *	modena_model_new (const char *modelId)
	Function fetching a surrogate model from MongoDB. More...
size_t	modena_model_inputs_argPos (const modena_model_t *self, const char *name)
	Function determining position of an argument in the input vector. More...
void	modena_model_argPos_check (const modena_model_t *self)
	Function checking that the user has queried all input positions. More...
size_t	modena_model_outputs_argPos (const modena_model_t *self, const char *name)
	Function determining position of a result in the output vector. More...
char **	modena_model_inputs_names (const modena_model_t *self)
	Function returning the names of the inputs. More...
char **	modena_model_outputs_names (const modena_model_t *self)
	Function returning the names of the outputs. More...
char **	modena_model_parameters_names (const modena_model_t *self)
	Function returning the names of the parameters. More...
size_t	modena_model_inputs_size (const modena_model_t *self)
	Function returning the size of the input vector. More...
size_t	modena_model_outputs_size (const modena_model_t *self)
	Function returning the size of the output vector. More...
size_t	modena_model_parameters_size (const modena_model_t *self)
	Function returning the size of the parameter vector. More...
void	modena_model_inputs_siunits (const modena_model_t *self, const size_t i, modena_siunits_t *units)
void	modena_model_outputs_siunits (const modena_model_t *self, const size_t i, modena_siunits_t *units)
int	modena_model_call (modena_model_t *model, modena_inputs_t *inputs, modena_outputs_t *outputs)
	Function calling the surrogate model and checking for errors. More...
void	modena_model_call_no_check (modena_model_t *model, modena_inputs_t *inputs, modena_outputs_t *outputs)
	Function calling the surrogate model w/o checking for errors. More...
void	modena_model_destroy (modena_model_t *model)
	Function deallocating the memory allocated for the surrogate model. More...

Detailed Description

MoDeNa C interface library

Typedef Documentation

modena_function_t

typedef struct modena_function_t modena_function_t

stores a surrogate function

modena_index_set_t

typedef struct modena_index_set_t modena_index_set_t

stores an index set

Function Documentation

modena_model_argPos_check()

void modena_model_argPos_check

(

const modena_model_t *

self

)

Function checking that the user has queried all input positions.

Parameters

struct

modena_model_t pointer to a surrogate model created by modena_model_new.

Returns

void

Definition at line 408 of file model.c.

modena_model_call()

int modena_model_call	(	modena_model_t *	model,
		modena_inputs_t *	inputs,
		modena_outputs_t *	outputs
	)

Function calling the surrogate model and checking for errors.

Parameters

modena_model_t	model pointer to a surrogate model.
modena_inputs_t	inputs pointer to the input vector
modena_outputs_t	outputs pointer to the output vector

Returns

201 requesting exit for new DOE without Restart

200 requesting exit for new DOE with Restart

100 updated model parameters, requesting to continue this run

1 failure

0 okay If exit is requested, do what's necessary and exit with the same error code!

Definition at line 553 of file model.c.

modena_model_call_no_check()

void modena_model_call_no_check	(	modena_model_t *	model,
		modena_inputs_t *	inputs,
		modena_outputs_t *	outputs
	)

Function calling the surrogate model w/o checking for errors.

Parameters

model	modena_model_t pointer to a surrogate model.
inputs	modena_inputs_t pointer to the input vector
outputs	modena_outputs_t pointer to the output vector

Returns

void

Definition at line 615 of file model.c.

modena_model_destroy()

void modena_model_destroy

(

modena_model_t *

model

)

Function deallocating the memory allocated for the surrogate model.

Parameters

model

modena_model_t pointer to a surrogate model.

Returns

void

Definition at line 665 of file model.c.

modena_model_inputs_argPos()

size_t modena_model_inputs_argPos	(	const modena_model_t *	self,
		const char *	name
	)

Function determining position of an argument in the input vector.

The function is used to determine the position of an argument name in the input vector.

Parameters

self	pointer to surrogate model created by modena_model_new.
name	(char) name of the argument whose position is sought.

Returns

size_t integer representing the position of the argument.

Definition at line 366 of file model.c.

modena_model_inputs_names()

char** modena_model_inputs_names

(

const modena_model_t *

self

)

Function returning the names of the inputs.

The function may be used to determine the inputs of a model.

Parameters

self	pointer to surrogate model created by modena_model_new.

Definition at line 432 of file model.c.

modena_model_inputs_size()

size_t modena_model_inputs_size

(

const modena_model_t *

self

)

Function returning the size of the input vector.

Parameters

modena_model_t

pointer to a surrogate model created by modena_model_new.

Returns

size_t integer length of the input array.

Definition at line 447 of file model.c.

modena_model_new()

modena_model_t* modena_model_new

(

const char *

modelId

)

Function fetching a surrogate model from MongoDB.

About writing adaptors for surrogate models

A adaptor is a code fragment which makes an application able to use the surrogate models (SM) that are stored in the MongoDB database. Writing a adaptor for a SM requires implementation of code fragments that corresponds to the life-span of a surrogate model, which consists of three phases:

• Initialisation
  1. Fetch the model from database.
  2. Allocate memory for input and output vectors.
  3. Query the SM for the position of each individual input and output.
• Execution
  1. Set the input vector.
  2. Evaluate the surrogate model.
  3. Check the MoDeNa framework for errors.
  4. Fetch outputs.
• Termination
  1. Deallocate memory.

About

The function modena_model_new is used in the initialisation phase of the adaptor, and its purpose is to fetch a surrogate model from the database. The input to the function is the name, technically the database "_id", of the surrogate model.

When the surrogate model has been fetched from the database the initialisation continues with allocating memory for the input and output vectors. However, this procedure is only performed one time for every surrogate model.

Usage

The function is only called one time for every surrogate model that the user want to employ in a application. It is implemented as a pointer to modena_model_t as follows:

• C:

  modena_model_t *model = modena_model_new("MY_MODEL");

• Fortran:

  type(c_ptr) :: model = c_null_ptr
  model = modena_model_new(c_char_"MY_MODEL"//c_null_char);

• Python:

  model = SurrogateModel.load("MY_MODEL")

Important

1. Make sure that the name of the surrogate model is spelled correctly, i.e. that it corresponds to the "_id" field in the definition of the SM.

   m = BackwardMappingModel(
          _id= "MY_MODEL",
          surrogateFunction= f,
          exactTask= FlowRateExactSim(),
          substituteModels= [ ],
          initialisationStrategy= Strategy.InitialPoints(),
          outOfBoundsStrategy= Strategy.ExtendSpaceStochasticSampling(),
          parameterFittingStrategy= Strategy.NonLinFitWithErrorContol(),
       )

2. Ensure that the input and output variables are spelled correctly, according to the surrogate function corresponding to the surrogate model.

   f = CFunction(
     Ccode= ''' C-code Omitted ''',
     # Global bounds for the function
     inputs={
         'T': { 'min': -298.15, 'max': 5000.0 },
         'P': { 'min':       0, 'max':  100.0 },
     },
     outputs={
          'N': { 'min': 9e99, 'max': -9e99, 'argPos': 0 },
     },
     parameters={
         'param1': { 'min': 0.0, 'max': 10.0, 'argPos': 1 },
     },
   )

3. Check 1 and 2.

modena_model_t *model = modena_model_new("MY_MODEL");    // Fetch "MY_MODEL"

modena_inputs_t *inputs = modena_inputs_new(model);        // Allocate input
modena_outputs_t *outputs = modena_outputs_new(model);    // Allocate output

size_t T_pos = modena_model_inputs_argPos(model, "T"); // Input position "T"
size_t P_pos = modena_model_inputs_argPos(model, "P"); // Input position "P"
size_t N_pos = modena_model_outputs_argPos(model,"N");// Output position "N"

modena_model_argPos_check(model);   // Check all positions have been queried

The name of the model, here "MY_MODEL", must correspond to the "_id" field in the definition of the surrogate model, which is located in a Python module.

Common issues:

• A common error is to start a simulation without the surrogate model being located in the database. Check this by executing the line below in a terminal (replacing "MY_MODEL" with the name of your surrogate model).

mongo --eval 'db.surrogate_model.find({"_id":"MY_MODEL"}).forEach(printjson)'

---

Parameters

modelId

(char) database '_id' if the desired surrogate model.

Returns

modena_model_t pointer to a surrogate model.

Definition at line 281 of file model.c.

modena_model_outputs_argPos()

size_t modena_model_outputs_argPos	(	const modena_model_t *	self,
		const char *	name
	)

Function determining position of a result in the output vector.

The function is used to determine the position of a result name in the input vector.

Parameters

self	pointer to surrogate model created by modena_model_new.
name	(char) name of the result whose position is sought.

Returns

size_t integer representing the position of the result.

Definition at line 392 of file model.c.

modena_model_outputs_names()

char** modena_model_outputs_names

(

const modena_model_t *

self

)

Function returning the names of the outputs.

The function may be used to determine the outputs of a model.

Parameters

self	pointer to surrogate model created by modena_model_new.

Definition at line 437 of file model.c.

modena_model_outputs_size()

size_t modena_model_outputs_size

(

const modena_model_t *

self

)

Function returning the size of the output vector.

Parameters

modena_model_t

surrogate model created by modena_model_new.

Returns

size_t integer length of the output array.

Definition at line 452 of file model.c.

modena_model_parameters_names()

char** modena_model_parameters_names

(

const modena_model_t *

self

)

Function returning the names of the parameters.

The function may be used to determine the parameters of a model.

Parameters

self	pointer to surrogate model created by modena_model_new.

Definition at line 442 of file model.c.

modena_model_parameters_size()

size_t modena_model_parameters_size

(

const modena_model_t *

self

)

Function returning the size of the parameter vector.

Parameters

modena_model_t

surrogate model created by modena_model_new.

Returns

size_t integer length of the parameter array.

Definition at line 457 of file model.c.

modena_siunits_new()

modena_siunits_t* modena_siunits_new

(

)

creates from nothing

Definition at line 54 of file inputsoutputs.c.