C/C++ API#

Here is listed the completed API available to implement the Solver Hooks.

Enums#

enum error_code#

It holds the possible returning error code from ALFAsim-SDK-API functions.

Values:

enumerator REFERENCE_NOT_SET#

Some reference from input data wasn’t set.

enumerator UNKNOWN_REFERENCE_TYPE#

Reference type is unknown.

enumerator OUT_OF_BOUNDS#

Index out of array bounds.

enumerator UNKNOWN_CONTEXT#

The context is unknown.

enumerator NOT_AVAILABLE_DATA#

Data from ALFAsim is not available.

enumerator BUFFER_SIZE_INSUFFICIENT#

Buffer size is insufficient.

enumerator UNDEFINED_DATA#

Plugin internal data is undefined.

enumerator NOT_IMPLEMENTED#

A feature is not implemented in an API function.

enumerator OK#

Everything was fine.

enum GridScope#

It holds the variable scope in the grid to retrieve a simulation array.

Values:

enumerator CENTER#

Variable located in the control volume center

enumerator FACE#

Variable located in the control volume face

enum MultiFieldDescriptionScope#

It holds the variable scope in the Multifield description (phases/fields/layers) to retrieve a simulation array.

Values:

enumerator MIXTURE#

Variable associated to the mixture

enumerator GLOBAL#

Global variable

enumerator FIELD#

Variable associated to the field

enumerator LAYER#

Variable associated to the layer

enumerator PHASE#

Variable associated to the phase

enum TwoPhaseSystem#

It holds the two phase system ids for Unit Cell Model related API functions.

Values:

enumerator GAS#

Gas phase.

enumerator LIQUID#

Liquid phase (sum of all phases).

enum LiquidLiquidSystem#

It holds the liquid-liquid system ids for Liquid-Liquid related API functions.

Values:

enumerator OIL#

Oil phase.

enumerator WATER#

Water phase.

enum TimestepScope#

It holds the variable scope in the time level to retrieve a simulation array.

Values:

enumerator CURRENT#

Variable in the current time step

enumerator PREVIOUS#

Variable in the previous (old) time step

enum StateVariable#

It holds the possible state variables that can be computed to a phase inside the plugin. See solver hooks calculate_state_variable and calculate_phase_pair_state_variable

Values:

enumerator RHO#

Density

enumerator MU#

Viscosity

enumerator CP#

Heat Capacity

enumerator DRHO_DP#

Partial derivative of density in relation to pressure

enumerator DRHO_DT#

Partial derivative of density in relation to temperature

enumerator H#

Enthalpy

enumerator K#

Thermal Conductivity

enumerator SIGMA#

Interfacial tension

enumerator RS#

gas mass fraction w.r.t. to hydrocarbon system

enumerator RSW#

vapor mass fraction w.r.t. to gas system

enum sdk_load_error_code#

It holds the possible returning error code when trying to open ALFAsim-SDK API.

Values:

enumerator SDK_DLL_PATH_TOO_LONG#

Path to SDK dll too long (Windows limitation).

enumerator SDK_ALREADY_OPEN_ERROR#

SDK dll already Opened.

enumerator SDK_OK#

Everything was fine.

Structs#

struct VariableScope#

It holds all variable scopes (grid, multifield and timestep)

Public Members

enum GridScope grid_scope#

Which grid scope of the variable

enum MultiFieldDescriptionScope mfd_scope#

Which multifield scope of the variable

enum TimestepScope ts_scope#

Which timestep scope of the variable

Functions#

ALFAsim-SDK API Loading#

Note

The ALFAsim-SDK API must be loaded with alfasim_sdk_open() inside HOOK_INITIALIZE of any plugin, otherwise the plugin will not be able to use any function available in the API. In addition, to avoid memory leak it is important to unload the ALFAsim-SDK API in the last called hook, HOOK_FINALIZE, using the alfasim_sdk_close() function.

inline int alfasim_sdk_open(ALFAsimSDK_API *api)#
inline void alfasim_sdk_close(ALFAsimSDK_API *api)#

Plugin Input Data (From user interface)#

Note

All API functions on this section has the parameter var_name. This parameter must be filled following the rules exposed in Variable Name Parsing section.

int get_plugin_input_data_boolean(void *ctx, bool *out, const char *plugin_id, const char *var_name)#

Gets the data provided from the user on a Boolean input field. For more detail about the Boolean input field check alfasim_sdk.types.Boolean

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Retrieved variable value.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

Returns:

An error_code value.

int get_plugin_input_data_enum(void *ctx, int *out, const char *plugin_id, const char *var_name)#

Gets the data provided from the user on a Enum input field. For more detail about the Enum input field check alfasim_sdk.types.Enum.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Retrieved variable value.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

Returns:

An error_code value.

int get_plugin_input_data_quantity(void *ctx, double *out, const char *plugin_id, const char *var_name)#

Gets the data provided from the user on a Quantity input field. For more detail about the quantity input field check alfasim_sdk.types.Quantity.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Retrieved variable value.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

Returns:

An error_code value.

int get_plugin_input_data_string(void *ctx, char *out, const char *plugin_id, const char *var_name, int size)#

Gets the data provided from the user on a String input field. For more detail about the string input field check alfasim_sdk.types.String.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Retrieved variable value.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

  • size[in] Size of output string (param out).

Returns:

An error_code value.

int get_plugin_input_data_string_size(void *ctx, int *out, const char *plugin_id, const char *var_name)#

Gets the size of the data provided from the user on a String input field.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] String size of a variable in which its name is informed by var_name.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

Returns:

An error_code value.

int get_plugin_input_data_file_content(void *ctx, char *out, const char *plugin_id, const char *var_name, int size)#

Gets the data provided from the user on a FileContent input field. For more detail about the FileContent input field check alfasim_sdk.types.FileContent

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Retrieved variable value.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

  • size[in] Size of output string (param out).

Returns:

An error_code value.

int get_plugin_input_data_file_content_size(void *ctx, int *out, const char *plugin_id, const char *var_name)#

Gets the size of the data provided from the user on a FileContent input field.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] File content size of a variable in which its name is informed by var_name.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

Returns:

An error_code value.

int get_plugin_input_data_table_quantity(void *ctx, double **out, int *size, const char *column_id, const char *plugin_id, const char *var_name)#

Gets the values from a column of an input table. column_id is the string defined in the plugin’s configuration file. If the var_name or the column_id are invalid, UNDEFINED_DATA is returned.

Example of usage:

int size = -1;
double* values = NULL;
int errcode = get_plugin_input_data_table_quantity(
    ctx,
    &values,
    &size,
    "temperature",
    get_plugin_id(),
    "Model.some_table"
);
for (int i = 0; i < size; ++i) {
    some_plugin_data = 1.1 * values[i];
}

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable values array.

  • size[out] Size of variable values array.

  • column_id[in] Table column ID which values are retrieved.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrieved.

Returns:

An error_code value.

int get_plugin_input_data_reference(void *ctx, void **out, const char *plugin_id, const char *var_name)#

Gets an ALFAsim input data internal Reference. Note that a Reference is a specific concept of ALFAsim-SDK and plugins - It is a way to retrieve data from an input outside of the current model. See the ALFAsim’s SDK python configuration file for more information.

Example of usage:

void* tracer_ref = nullptr;
errcode = get_plugin_input_data_reference(
    ctx, &tracer_ref, get_plugin_id(), "Model.tracer_reference");

int tracer_id = -1;
errcode = get_tracer_id(ctx, &tracer_id, tracer_ref);

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] ALFAsim data reference.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable to be retrived.

Returns:

An error_code value.

int get_plugin_input_data_multiplereference_selected_size(void *ctx, int *indexes_size, const char *plugin_id, const char *var_name)#

Get the number of selected references in a multiple-reference selection. User should be able to iterate over the selections to get information.

Example of usage:

int errcode = -1;
int indexes_size = -1;
errcode = get_plugin_input_data_multiplereference_selected_size(
    ctx, &indexes_size, get_plugin_id(), "Model.internal_multiple_reference");

for (int i = 0; i < indexes_size; ++i) {
    auto value = -1.0;
    auto reference_str = std::string(
        "Model.internal_multiple_reference[" + std::to_string(i) + "]->quantity");

    errcode = get_plugin_input_data_quantity(
        ctx, &value, get_plugin_id(), reference_str.c_str());
    }
}

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • indexes_size[out] Number of selected references in a multiple reference input data.

  • plugin_id[in] Plugin ID.

  • var_name[in] Name of the variable.

Returns:

An error_code value.

Plugin Internal Data#

int set_plugin_data(void *ctx, const char *plugin_id, void *data, int thread_id)#

Set the data provided from the plugin developer.

When a plugin has internal data and it has to be accessed by all C/C++ Hooks during the simulation this function allows the plugin to ask the ALFAsim’s solver to hold its internal data.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • plugin_id[in] Plugin ID.

  • data[in] Plugin internal data.

  • thread_id[in] Thread ID, see get_thread_id for more information.

Returns:

An error_code value.

int get_plugin_data(void *ctx, void **out, const char *plugin_id, int thread_id)#

Gets the data provided from the plugin developer.

Once the plugin set an internal data, it can be accessed from any C/C++ Hook during the simulation using this function.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Plugin internal data.

  • plugin_id[in] Plugin ID.

  • thread_id[in] Thread ID, see get_thread_id for more information.

Returns:

An error_code value.

int get_number_of_threads(void *ctx, int *n_threads)#

Gives the number of running threads on the solver

ALFAsim’s Solver runs in multiple threads. To avoid data access concurrency problems the plugin developer must set one internal data to each running thread during the initialization. Then, with number of threads, the developer can do it properly.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • n_threads[out] Number of threads.

Returns:

An error_code value.

int get_thread_id(void *ctx, int *thread_id)#

Gives the current running thread id (in the solver process)

Once the plugin sets one internal data to each running thread, to access this data properly it has to know which thread is trying to access this data. For that, this function retrieves this information from solver.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • thread_id[out] Thread ID.

Returns:

An error_code value.

ALFAsim’s Solver Data#

int get_plugin_variable(void *ctx, void **out, const char *variable_name, int line_index, enum TimestepScope ts_scope, int *size)#

Gets the contents of a plugin-registered secondary variable (Given by name).

It is allowed to the plugins to add new secondary variables via python config file. ALFAsim’s solver registers/holds these variables and make them available in the solver hooks by this function.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Plugin-registered secondary variable values array.

  • variable_name[in] Name of the secondary variable.

  • line_index[in] It can represent Layer/Field/Phase ID, since the secondary variables can be associated to different MultiFieldDescriptionScope.

  • ts_scope[in] A TimestepScope value.

  • size[out] Size of out array of values. It can be the number of volumes or number of faces depending in which GridScope the secondary variable was registered.

Returns:

An error_code value.

int get_field_id(void *ctx, int *out, const char *name)#

Gets the field ID of the given name. Although this depends on the hydrodynamic model being solved, common values include “gas”, “oil”, “droplet” and “bubble”. This functions supports retrieve ID of field added by plugin.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Field ID.

  • name[in] Name of the field to retrieve the ID.

Returns:

An error_code value.

int get_phase_id(void *ctx, int *out, const char *name)#

Gets the phase ID of the given name. Although this depends on the hydrodynamic model being solved, common values include “gas”, “oil” and “water”. This functions supports retrieve ID of phase added by plugin.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Phase ID.

  • name[in] Name of the phase to retrieve the ID.

Returns:

An error_code value.

int get_layer_id(void *ctx, int *out, const char *name)#

Gets the layer ID of the given name. Although this depends on the hydrodynamic model being solved, common values include “gas”, “oil” and “water”. This functions supports retrieve ID of layer added by plugin.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Layer ID.

  • name[in] Name of the layer to retrieve the ID.

Returns:

An error_code value.

int get_number_of_fields(void *ctx, int *out)#

Gives the number of fields in the hydrodynamic model being solved including dispersed and continuous fields. This information may be important when new fields are added by plugins.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Number of Fields.

Returns:

An error_code value.

int get_number_of_phases(void *ctx, int *out)#

Gives the number of phases in the hydrodynamic model being solved. This information may be important when new phases are added by plugins.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Number of Phases.

Returns:

An error_code value.

int get_number_of_layers(void *ctx, int *out)#

Gives the number of layers in the hydrodynamic model being solved. This information may be important when new layers are added by plugins.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Number of layers.

Returns:

An error_code value.

int get_number_of_phase_pairs(void *ctx, int *out)#

Gives the number of phase pairs in the hydrodynamic model being solved. It depends on number of phases and may be important to calculate the phase pair state variables.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Number of phase pairs.

Returns:

An error_code value.

int get_state_variable_array(void *ctx, double **out, enum StateVariable state_var, int field_index, int *size)#

Gets the current contents of a given state variable (For an array data pointer). A state variable is any variable calculated from pressure and temperature, as any thermodynamic variable.

Example of usage:

errcode = get_state_variable_array(
    ctx, &enthalpy, StateVariable::H, FIELD_GAS, &size);

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] State Variable values array.

  • state_var[in] A StateVariable value. It indicates which variable to be retrieved.

  • field_index[in] Index of the field in which the state variable is retrieved.

  • size[out] Size of the out array of values.

Returns:

An error_code value.

int get_primary_field_id_of_phase(void *ctx, int *out, const char *name)#

Gets the primary field ID of the phase with given name. For example, the “oil” phase has primary field “oil”. Different phases may have different primary fields. Use this function when you need a variable from a field, but you aren’t sure about the field name, but you know the phase name.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Field ID.

  • name[in] Name of the phase to retrieve the primary field ID.

Returns:

An error_code value.

Warning

Changing the contents retrieved by this function (out array) has UNDEFINED BEHAVIOR. The plugin must NEVER change the contents returned by this function.

int get_phase_id_of_fields(void *ctx, int **out, int *size)#

Gets an array of phase IDs, in which each element is related to the fields in the hydrodynamic model. This function is usefull when is necessary to get information from a phase of a specific field (for example “oil in water” field is a “oil” phase).

Example of usage:

errcode = get_phase_id_of_fields(ctx, &phase_of_field, &size);
int oil_in_water_phase_id = phase_of_field[oil_in_water_field_id];

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Phase IDs array.

  • size[out] Size of the out array of IDs.

Returns:

An error_code value.

Warning

Changing the contents retrieved by this function (out array) has UNDEFINED BEHAVIOR. The plugin must NEVER change the contents returned by this function.

int get_field_ids_in_layer(void *ctx, int **out, int layer_id, int *size)#

Gets an array of field IDs which are contained in a layer. For example: the “oil” layer could be formed by continuous “oil” field with dispersed “bubble”(gas) and dispersed “water in oil” fields (and also other dispersed fields added by plugins).

Example of usage:

errcode = get_field_ids_in_layer(ctx, &fields_in_Layer, layer_id, &size);

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Field IDs array.

  • layer_id[in] Layer ID in which the field IDs are required.

  • size[out] Size of the out array of IDs.

Returns:

An error_code value.

int get_phase_pair_id(void *ctx, int *out, int phase_0_id, int phase_1_id)#

Gets the phase pair ID given a pair of phase ID’s. It is important to calculate a phase pair properties (like surface tension) for more that one phase pair (For example: Gas-Oil, Gas-Water and Oil-Water).

Since this function has phase ID’s in parameters, it MUST be used in conjunction with get_phase_id function.

Example of usage:

errcode = get_phase_id(ctx, &oil_phase_id, "oil");
errcode = get_phase_id(ctx, &water_phase_id, "water");
errcode = get_phase_pair_id(ctx, &oil_water_id, oil_phase_id, water_phase_id);

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Phase pair ID.

  • phase_0_id[in] First phase ID of the pair.

  • phase_1_id[in] Second phase ID of the pair.

Returns:

An error_code value.

Warning

Changing the contents retrieved by this function (out array) has UNDEFINED BEHAVIOR. The plugin must NEVER change the contents returned by this function.

int get_simulation_array(void *ctx, double **out, const char *variable_name, struct VariableScope var_scope, int line_index, int *size)#

Gets the current contents of a given secondary variable (For an array data pointer). A secondary variable is any variable calculated in the solver iterative procedure. Note that not all variables are available at any time. If a given variable is not available in one of the chosen scopes, a NOT_AVAILABLE_DATA error is returned.

List of variable_name values:

  • "rho": Density [kg/m3]

  • "mu": Viscosity [Pa.s]

  • "alpha": Volume Fraction [m3 of field|layer|phase /m3 of mixture]

  • "mass_concentration": Mass Concentration [kg of field|layer|phase /m3 of mixture]

  • "P": Pressure [Pa]

  • "T": Temperature [K]

  • "h": Specific Enthalpy [J/kg]

  • "cp": Specific Heat Capacity [J/kg.K]

  • "k": Thermal Conductivity [W/m.K]

  • "eta_inner": Heat Transfer Coefficient between inner pipe wall and the fluid layers [W/m2.K]

  • "U": Velocity [m/s]

  • "U_superficial": Superficial Velocity [m/s]

  • "RS": Gas mass fraction in gas/oil mixture [kg/kg]

  • "RSW": Water vapour mass fraction in gas phase [kg/kg]

  • "S_w": Wetted Perimeter of a layer [m]

  • "ff_S_wall": Wall friction factor times wall perimeter [-]

  • "ff_S_interface": Interface Friction factor times interface perimeter [-]

  • "D": Pipe Inner Diameter [m]

  • "A": Cross-sectional Area in each control volume [m2]

  • "theta": Inclination of each control volume [rad]

  • "dx": Control Volume Length along the Pipe Axis [m]

  • "dv": Volume of the control volume [m3]

  • "D_eff": Effective Pipe Inner Diameter, considering the internal deposit layers [m]

  • "A_eff": Cross-sectional Area Effective in each control volume, considering the internal deposit layers [m2]

  • "dv_eff": Effective Volume of the control volume, considering the internal deposit layers [m3]

It is important to know that the listed variable_names are no available in all MultiFieldDescriptionScope and GridScope. Because of that, the error_code must be checked.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable values array.

  • variable_name[in] String with the variable name. See the list of possible values above.

  • var_scope[in] It must be configured to determine all scopes in which the variable will be retrieved. See VariableScope for more information.

  • line_index[in] It can represent Layer/Field/Phase ID, since the secondary variables can be associated to different MultiFieldDescriptionScope. When it is a GLOBAL variable line_index must be 0.

  • size[out] Size of the out array of values.

Returns:

An error_code value.

Warning

Changing the contents retrieved by this function (out array) has UNDEFINED BEHAVIOR. The plugin must NEVER change the contents returned by this function.

int get_simulation_tracer_array(void *ctx, double **out, const char *variable_name_c, struct VariableScope var_scope, int tracer_index, int line_index, int *size)#

Gets the current contents of a given tracer mass fraction (For an array data pointer). A tracer mass fraction is calculated in the extra solver iterative procedure. Note that not all tracer mass fraction are available at any time. If a given tracer mass fraction (in an inexistent field) is not available, a NOT_AVAILABLE_DATA error is returned.

List of variable_name_c values:

  • "phi": Mass Fraction [kg of tracer (in field|phase) / kg of mixture]

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable values array.

  • variable_name_c[in] String with the variable name. See the list of possible values above.

  • var_scope[in] It must be configured to determine all scopes in which the variable will be retrieved. See VariableScope for more information.

  • tracer_index[in] Tracer ID, it can be retrieved by get_tracer_id.

  • line_index[in] It can represent Field or Phase ID, since the tracer masss fraction can be calculated related to Field or Phase. When it is the mass fraction on mixture the line_index must be 0.

  • size[out] Size of the out array of values.

Returns:

An error_code value.

Warning

Changing the contents retrieved by this function (out array) has UNDEFINED BEHAVIOR. The plugin must NEVER change the contents returned by this function.

int get_simulation_quantity(void *ctx, double *out, enum TimestepScope ts_scope, const char *variable_name_c)#

Gets the current contents of a given secondary variable (For a single quantity). A secondary variable is any variable calculated in the solver iterative procedure. Note that not all variables are available at any time. If a given variable is not available, a NOT_AVAILABLE_DATA error is returned.

List of variable_name_c values:

  • "dt": Time Step [s]

  • "time": Current time [s]

It is important to know that dt may have value equal to NAN (Not a number) during the steady state simulation. In this case the plugin must handle it and not use this value.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable value.

  • ts_scope[in] TimestepScope value.

  • variable_name_c[in] String with the variable name. See the list of possible values above.

Returns:

An error_code value.

int get_tracer_id(void *ctx, int *tracer_id, void *reference)#

Retrieves the tracer ID given a tracer reference. A tracer reference may be obtained from the user input data (See get_plugin_input_data_reference API function for an example).

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • tracer_id[out] Tracer ID.

  • reference[in] Tracer reference.

Returns:

An error_code value.

int get_tracer_name_size(void *ctx, int *tracer_name_size, void *reference)#

Retrieves the size of the tracer name, given a tracer reference. A tracer reference may be obtained from the user input data (See get_plugin_input_data_reference API function for an example).

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • tracer_name_size[out] Size of tracer name string.

  • reference[in] Tracer reference.

Returns:

An error_code value.

int get_tracer_name(void *ctx, char *out, void *reference, int size)#

Retrieves the tracer name, given a tracer reference. The tracer_name parameter must be a valid and pre-allocated memory region where the name string will be copied to. A tracer reference may be obtained from the user input data (See get_plugin_input_data_reference API function for an example).

Example of usage:

int tracer_name_size = -1;
errcode = get_tracer_name_size(ctx, &tracer_name_size, tracer_ref);

char* tracer_name = (char*)malloc(sizeof(char) * tracer_name_size);
errcode = get_tracer_name(
    ctx, tracer_name, tracer_ref, tracer_name_size);
std::cout << "TRACER NAME: " << tracer_name << std::endl;
free(tracer_name);

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] String with tracer name.

  • reference[in] Tracer reference.

  • size[in] Size of out string.

Returns:

An error_code value.

int get_tracer_ref_by_name(void *ctx, void **reference, const char *tracer_name, const char *plugin_id)#

Gets the tracer reference for a given tracer name. This function is important to obtain the tracer reference of a user defined tracer added by the plugin.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • reference[out] Tracer reference.

  • tracer_name[in] Tracer name.

  • plugin_id[in] Plugin ID.

Returns:

An error_code value.

int get_tracer_partition_coefficient(void *ctx, double *out, void *reference, int phase_id)#

Gets the partition coefficient input data for a given tracer reference. The phase_id must also be given (See get_phase_id API function). A tracer reference may be obtained from the user input data (See get_plugin_input_data_reference API function for an example).

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Partition coefficient value related to the specified phase.

  • reference[in] Tracer reference.

  • phase_id[in] Phase ID.

Returns:

An error_code value.

int get_wall_interfaces_temperature(void *ctx, double **out, int control_volume, enum TimestepScope ts_scope, int *size)#

Gets the wall interface temperature for a given control volume. Each control volume has an array of temperatures, one for each wall layer. The temperatures are given in the wall interfaces.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Wall interfaces temperature values array.

  • control_volume[in] Control Volume ID.

  • ts_scope[in] TimestepScope value.

  • size[in] Size of out array of values.

Returns:

An error_code value.

int get_flow_pattern(void *ctx, int **out, enum GridScope grid_scope, enum TimestepScope ts_scope, int *size)#

Gets the flow pattern for each control volume.

List of possible values of Flow Pattern is:

  • 0 - Unknown

  • 1 - Stratified

  • 2 - Dispersed Bubble

  • 3 - Bubble

  • 4 - Slug

  • 5 - Annular Mist

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Flow Pattern values array. See list of possible values above.

  • grid_scope[in] A GridScope value.

  • ts_scope[in] A TimestepScope value.

  • size[in] Size of out array of values.

Returns:

An error_code value.

Unit Cell Model (UCM) helpers#

int get_ucm_friction_factor_input_variable(void *ctx, double *out, const char *var_name, int phase_id)#

Gets the current UCM (unit cell model) input data for friction factor calculation. Any available variable by this function is considered for a unit cell, which means that there are variables with one value and there are variables with two values related to the two phase system (GAS and LIQUID). If a given variable name is not available, a NOT_AVAILABLE_DATA error is returned.

List of variable_name with two values (Two phase):

  • "alpha": Volume Fraction [m3 of phase /m3 of mixture]

  • "rho": Density [kg/m3]

  • "mu": Viscosity [Pa.s]

  • "U": Velocity [m/s]

It is important to know that the listed variable_names are not available in any phase, only for two phase systems, in which GAS (0, zero) and LIQUID (1, One)(sum of all liquid phases) are the possible values, and they are available in the TwoPhaseSystem enumeration. Because of that, the error_code must be checked.

List of variable_name with one value:

  • "D": Unit Cell Inner Diameter [m]

  • "ks": Roughness [m]

  • "theta": Inclination of the Unit Cell [rad]

  • "sigma": Gas-liquid Surface Tension [N/m]

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable value.

  • var_name[in] String with the variable name. See the list of possible values above.

  • phase_id[in] A TwoPhaseSystem value. When the requested variable is not associated to a phase any value can be passed.

Returns:

An error_code value.

int get_ucm_fluid_geometrical_properties(void *ctx, double *S_w, double *S_i, double *H, double alpha_G, double D)#

Gets the current UCM (unit cell model) fluid geometrical properties for friction factor calculation.

During the implementation of any HOOK related to the UCM friction factor, this function provides the following fluid geometrical properties:

  • "S_w": Wetted perimeters of phases [m].

  • "S_i": Interface perimeter [m].

  • "H": Phase height [m].

It is important to know that S_w and H must be pointers to an array of size two (GAS and LIQUID).

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • S_w[out] Wetted Perimeters [m].

  • S_i[out] Interface Perimeter [m].

  • H[out] Phase height [m]. For annular flow, H[GAS] is the core diameter and H[LIQUID] is the total liquid film height.

  • alpha_G[in] Unit Cell Gas Volume Fraction [m3 of gas phase /m3 of mixture].

  • D[in] Unit Cell Inner Diameter [m].

Returns:

An error_code value.

Liquid-Liquid Mechanistic Model helpers#

int get_liq_liq_flow_pattern_input_variable(void *ctx, double *out, const char *var_name, int phase_id)#

Gets the current control volume input data for liquid-liquid flow Pattern calculation. Any available variable by this function is considered for a control volume, which means that there are variables with one value and there are variables with two values related to the liquid-liquid system (OIL and WATER). If a given variable name is not available, a NOT_AVAILABLE_DATA error is returned.

List of variable_name with two values (Oil and Water):

  • "rho": Density [kg/m3]

  • "mu": Viscosity [Pa.s]

  • "U_S": Superficial Velocity [m/s]

It is important to know that the listed variable_names are not available in any phase, only for liquid-liquid systems, in which OIL (0, zero) and WATER (1, One) are the possible values, and they are available in the LiquidLiquidSystem enumeration. Because of that, the error_code must be checked.

List of variable_name with one value:

  • "D_h": Unit Cell Liquid (Oil-Water) Hydraulic Diameter [m]

  • "ks": Absolute Roughness [m]

  • "theta": Inclination of the Unit Cell [rad]

  • "sigma": Liquid-liquid (Oil-Water) Surface Tension [N/m]

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable value.

  • var_name[in] String with the variable name. See the list of possible values above.

  • phase_id[in] A LiquidLiquidSystem value. When the requested variable is not associated to a phase any value can be passed.

Returns:

An error_code value.

int get_liquid_effective_viscosity_input_variable(void *ctx, double *out, const char *var_name, int phase_id)#

Gets the current input data for liquid effective viscosity calculation. Any available variable by this function is considered for a control volume, which means that there are variables with one value and there are variables with two values related to the liquid-liquid system (OIL and WATER). If a given variable name is not available, a NOT_AVAILABLE_DATA error is returned.

List of variable_name with two values (Oil and Water):

  • "rho": Density [kg/m3]

  • "mu": Viscosity [Pa.s]

  • "U_S": Superficial Velocity [m/s]

It is important to know that the listed variable_names are not available in any phase, only for liquid-liquid systems, in which OIL (0, zero) and WATER (1, One) are the possible values, and they are available in the LiquidLiquidSystem enumeration. Because of that, the error_code must be checked.

List of variable_name with one value:

  • "alpha_w" : Water Volume Fraction [m3 of water phase / m3 of liquid(Oil+Water) phase]

  • "D_h": Unit Cell Liquid (Oil-Water) Hydraulic Diameter [m]

  • "ks": Absolute Roughness [m]

  • "theta": Inclination of the Unit Cell [rad]

  • "sigma": Liquid-liquid (Oil-Water) Surface Tension [N/m]

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable value.

  • var_name[in] String with the variable name. See the list of possible values above.

  • phase_id[in] A LiquidLiquidSystem value. When the requested variable is not associated to a phase any value can be passed.

Returns:

An error_code value.

int get_gas_liq_surface_tension_input_variable(void *ctx, double *out, const char *var_name, int phase_id)#

Gets the current input data for Gas-Liquid surface tension calculation. Any available variable by this function is considered for a control volume, which means that there are variables with one value and there are variables with two values related to the liquid-liquid system (OIL and WATER). If a given variable name is not available, a NOT_AVAILABLE_DATA error is returned.

List of variable_name with two values (Oil and Water):

  • "sigma_gll": Gas-Liquid-Liquid (Gas-Oil or Gas-Water) Surface Tension [N/m]

It is important to know that the listed variable_names are not available in any phase, only for liquid-liquid systems, in which OIL (0, zero) and WATER (1, One) are the possible values, and they are available in the LiquidLiquidSystem enumeration. Because of that, the error_code must be checked.

List of variable_name with one value:

  • "alpha_w" : Water Volume Fraction [m3 of water phase / m3 of liquid(Oil+Water) phase]

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable value.

  • var_name[in] String with the variable name. See the list of possible values above.

  • phase_id[in] A LiquidLiquidSystem value. When the requested variable is not associated to a phase any value can be passed.

Returns:

An error_code value.

int get_liq_liq_shear_force_per_volume_input_variable(void *ctx, double *out, const char *var_name, int phase_id)#

Gets the current input data for Shear force calculation. Any available variable by this function is considered for a control volume, which means that there are variables with one value and there are variables with two values related to the liquid-liquid system (OIL and WATER). If a given variable name is not available, a NOT_AVAILABLE_DATA error is returned.

The variables available are the same as get_liq_liq_flow_pattern_input_variable and its documentation should be visited for more details.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Variable value.

  • var_name[in] String with the variable name. See the list of possible values above.

  • phase_id[in] A LiquidLiquidSystem value. When the requested variable is not associated to a phase any value can be passed.

Returns:

An error_code value.

int get_relative_emulsion_viscosity(void *ctx, double *out, double mu_disp, double mu_cont, double alpha_disp_in_layer, double T, bool water_in_oil)#

Gets the relative emulsion viscosity for liquid-liquid calculations.

During the implementation of any HOOK related to the Liquid-Liquid Mechanistic model, this function provides the relative emulsion viscosity from Emulsion Model (selected through GUI).

It allows the plugin HOOKs to use the same emulsion model used internally by ALFAsim.

The definition of relative viscosity is given by the ratio between the apparent viscosity (dispersed field + continuous field) and the continuous field.

Parameters:
  • ctx[in] ALFAsim’s plugins context.

  • out[out] Relative Emulsion Viscosity [-].

  • mu_disp[in] Dispersed Field Viscosity [Pa.s].

  • mu_cont[in] Continuous Field Viscosity [Pa.s].

  • alpha_disp_in_layer[in] Dispersed Field Volume Fraction in the layer (emulsion) [m3 of dispersed field /m3 of layer].

  • T[in] Fluid temperature [K].

  • water_in_oil[in] True when water is dispersed in oil, otherwise it is a dispersion of oil in water.

Returns:

An error_code value.

Variable Name Parsing#

To retrieve input data from the plugin’s GUI, the plugin must pass a var_name in a specific format. API functions that use this kind of variable described on Plugin Input Data (From user interface) section.

All variables must begin with the model name described on the plugin model, followed by . (For nested objects) or -> (For references). Lists must be accessed with the list index directly, for example, Model.lst[0] will be the first element of the list “lst”, inside the plugin model named “Model”. References can be internal (Reference to a plugin model) or external (Reference to an ALFAsim model).

Basic example#

Imagine you have the following simple GUI model defined as

@data_model(icon='', caption='Plugin Model')
class Model:
    boolean_data = Boolean(value=True, caption="BOOLEAN CAPTION")

To extract the plugin input data content on C++, the plugin must use the proper API function call:

int errcode = 0;
bool test_api_boolean = false;
errcode = alfasim_sdk_api.get_plugin_input_data_boolean(
    ctx, &test_api_boolean, get_plugin_id(), "Model.boolean_data");
std::cout << " BOOLEAN:" << test_api_boolean
          << " ERROR CODE:" << errcode
          << std::endl;

See get_plugin_input_data_boolean() for details.

List Model Example#

For the cases were the model is a container, it is possible to retrieve the information for each element individually.

@data_model(icon='', caption='Plugin Model 2')
class Model:
    name = String(value='default', caption='Name')
    boolean = Boolean(value=True, caption="Boolean")
    quantity = Quantity(value=1, unit='m', caption='Quantity')


@container_model(icon='', caption='Plugin Container', model=Model)
class ModelContainer:
    pass

To extract the plugin input data content on C++, the plugin must use the proper API function call:

int errcode = 0;
double test_api_quantity = 0.;
errcode = alfasim_sdk_api.get_plugin_input_data_quantity(
   ctx, &test_api_quantity, get_plugin_id(), "ModelContainer[0].quantity");
std::cout << " Quantity from container[0]:" << test_api_quantity
          << " ERROR CODE:" << errcode
          << std::endl;

See get_plugin_input_data_quantity() for details.

Internal Reference Example#

Internal references are references to models defined in the plugin itself. They are useful when you have a list of models, for example, but need to let the user decide from one specific model from the list. Assuming the model container defined in the previous, example, an internal reference for an element inside that container can be programmed as follows. The plugin must use -> to access referenced data, instead of . as in other examples.

@data_model(icon='', caption='Plugin Model')
class OtherModel:
    internal_reference = Reference(
        container_type='ModelContainer',
        ref_type=Model,
        caption="Internal Reference"
    )

Data from the referenced model can then be extracted on C++ code as follows. Note that the developer will extract the values directly, not the model itself, that is, in the example below, there is never an object of type Model. Raw data values such as boolean, strings or floats are directly retrieved instead.

int errcode = 0;
double test_api_quantity = 0.;
errcode = alfasim_sdk_api.get_plugin_input_data_quantity(
    ctx, &test_api_quantity, get_plugin_id(), "OtherModel.internal_reference->quantity");
std::cout << " Quantity from internal reference:" << test_api_quantity
          << " ERROR CODE:" << errcode
          << std::endl;

External Reference Example#

External references gives the user a way to interact with references to specific ALFAsim’s GUI object configurations. Those types of references work a bit different, because ALFAsim developers must provide an API for each specific entity. As of today, the only exposed ALFAsim model is the Tracer model. See the tracer-related functions to have an overview about the available data that can be used:

The example below extracts the tracer Id configured in the plugin.

@data_model(icon='', caption='Plugin Model')
class OtherModel:
    tracer_reference = Reference(
        ref_type=TracerType,
        caption="Tracer Reference",
    )

To extract the plugin input data content on C++, the plugin must use the proper API function call:

int errcode = 0;
void* tracer_ref = nullptr;
errcode = get_plugin_input_data_reference(
    ctx, &tracer_ref, get_plugin_id(), "OtherModel.tracer_reference");

int tracer_id = -1;
errcode = get_tracer_id(ctx, &tracer_id, tracer_ref);
std::cout << "TRACER ID: " << tracer_id << std::endl;

See get_plugin_input_data_reference() for details.

Multiple Reference#

The plugin developer may need to let the user select not one, but several references (This is valid for both internal and external references). To tackle this problem, ALFAsim developers created the notion of Multiple References. It is basically a container of referenced objects, and the usage is simply a mix of the container with the reference syntax.

Example of a GUI model in which has both types of multiple references:

@data_model(icon='', caption='Plugin Model')
class OtherModel:
    multiple_reference = MultipleReference(
        ref_type=TracerType,
        caption='Multiple Reference'
    )

    internal_multiple_reference = MultipleReference(
        ref_type=Model,
        container_type='ModelContainer',
        caption='Internal Multiple Reference'
    )

Example of accessing the external multiple references:

int errcode = -1;
int indexes_size = -1;
errcode = get_plugin_input_data_multiplereference_selected_size(
    ctx, &indexes_size, get_plugin_id(), "OtherModel.multiple_reference");

void* tracer_ref = nullptr;
for (int i = 0; i < indexes_size; ++i) {
    auto reference_str = std::string(
        "OtherModel.multiple_reference[" + std::to_string(i) + "]");
    errcode = get_plugin_input_data_reference(
        ctx, &tracer_ref, get_plugin_id(), reference_str.c_str());

    int tracer_id = -1;
    errcode = get_tracer_id(ctx, &tracer_id, tracer_ref);
    std::cout << "TRACER ID: " << tracer_id << std::endl;
}

Example of accessing the internal multiple references:

int errcode = -1;
 int indexes_size = -1;
 errcode = get_plugin_input_data_multiplereference_selected_size(
     ctx,
     &indexes_size,
     get_plugin_id(),
     "OtherModel.internal_multiple_reference");

 for (int i = 0; i < indexes_size; ++i) {
     auto test_api_bool = false;
     auto reference_str = std::string(
         "OtherModel.internal_multiple_reference[" + std::to_string(i) + "]->boolean");
     errcode = get_plugin_input_data_boolean(
         ctx,
         &test_api_bool,
         get_plugin_id(),
         reference_str.c_str());
     std::cout << " Bool from referenced container[" << i << "]:" << (test_api_bool ? "true" : "false")
               << " ERROR CODE:" << errcode
               << std::endl;
 }

see get_plugin_input_data_multiplereference_selected_size() for details.