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 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

enum WallLayerProperty

It holds the possible wall layer property that can be obtained from ALFAsim’s solver. This Enum is used by The #set_wall_layer_property API function.

Values:

enumerator THICKNESS

Wall layer tickness

enumerator DENSITY

Wall layer material density

enumerator THERMAL_CONDUCTIVITY

Wall layer material thermal conductivity

enumerator HEAT_CAPACITY

Wall layer material specifc heat capacity

enumerator INNER_EMISSIVITY

Wall layer material inner emissivity

enumerator OUTER_EMISSIVITY

Wall layer material outer emissivity

enumerator EXPANSION

Wall layer material thermal expansion coefficient

enumerator VISCOSITY

Wall layer material viscosity (if it is a deposit layer)

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.

int alfasim_sdk_open(ALFAsimSDK_API *api)
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

Return

An error_code value.

Parameters

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

  • [out] out: Retrieved variable value.

  • [in] plugin_id: Plugin ID.

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

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.

Return

An error_code value.

Parameters

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

  • [out] out: Retrieved variable value.

  • [in] plugin_id: Plugin ID.

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

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.

Return

An error_code value.

Parameters

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

  • [out] out: Retrieved variable value.

  • [in] plugin_id: Plugin ID.

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

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.

Return

An error_code value.

Parameters

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

  • [out] out: Retrieved variable value.

  • [in] plugin_id: Plugin ID.

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

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

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.

Return

An error_code value.

Parameters

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

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

  • [in] plugin_id: Plugin ID.

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

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

Return

An error_code value.

Parameters

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

  • [out] out: Retrieved variable value.

  • [in] plugin_id: Plugin ID.

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

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

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.

Return

An error_code value.

Parameters

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

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

  • [in] plugin_id: Plugin ID.

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

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];
}

Return

An error_code value.

Parameters

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

  • [out] out: Variable values array.

  • [out] size: Size of variable values array.

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

  • [in] plugin_id: Plugin ID.

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

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);

Return

An error_code value.

Parameters

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

  • [out] out: ALFAsim data reference.

  • [in] plugin_id: Plugin ID.

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

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());
    }
}

Return

An error_code value.

Parameters

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

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

  • [in] plugin_id: Plugin ID.

  • [in] var_name: Name of the variable.

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.

Return

An error_code value.

Parameters

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

  • [in] plugin_id: Plugin ID.

  • [in] data: Plugin internal data.

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

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.

Return

An error_code value.

Parameters

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

  • [out] out: Plugin internal data.

  • [in] plugin_id: Plugin ID.

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

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.

Return

An error_code value.

Parameters

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

  • [out] n_threads: Number of threads.

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.

Return

An error_code value.

Parameters

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

  • [out] thread_id: Thread ID.

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.

Return

An error_code value.

Parameters

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

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

  • [in] variable_name: Name of the secondary variable.

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

  • [in] ts_scope: A TimestepScope value.

  • [out] size: 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.

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

Gets the field ID of the given name. Althought 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.

Return

An error_code value.

Parameters

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

  • [out] out: Field ID.

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

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.

Return

An error_code value.

Parameters

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

  • [out] out: Field ID.

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

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

Gets the phase ID of the given name. Althought 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.

Return

An error_code value.

Parameters

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

  • [out] out: Phase ID.

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

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

Gets the layer ID of the given name. Althought 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.

Return

An error_code value.

Parameters

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

  • [out] out: Layer ID.

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

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);

Return

An error_code value.

Parameters

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

  • [out] out: State Variable values array.

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

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

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

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]

  • "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.

Return

An error_code value.

Parameters

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

  • [out] out: Variable values array.

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

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

  • [in] line_index: 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.

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

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]

Return

An error_code value.

Parameters

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

  • [out] out: Variable values array.

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

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

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

  • [in] line_index: 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.

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

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]

Return

An error_code value.

Parameters

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

  • [out] out: Variable value.

  • [in] ts_scope: TimestepScope value.

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

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).

Return

An error_code value.

Parameters

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

  • [out] tracer_id: Tracer ID.

  • [in] reference: Tracer reference.

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).

Return

An error_code value.

Parameters

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

  • [out] tracer_name_size: Size of tracer name string.

  • [in] reference: Tracer reference.

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);

Return

An error_code value.

Parameters

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

  • [out] out: String with tracer name.

  • [in] reference: Tracer reference.

  • [in] size: Size of out string.

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.

Return

An error_code value.

Parameters

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

  • [out] reference: Tracer reference.

  • [in] tracer_name: Tracer name.

  • [in] plugin_id: Plugin ID.

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).

Return

An error_code value.

Parameters

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

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

  • [in] reference: Tracer reference.

  • [in] phase_id: Phase ID.

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.

Return

An error_code value.

Parameters

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

  • [out] out: Wall interfaces temperature values array.

  • [in] control_volume: Control Volume ID.

  • [in] ts_scope: TimestepScope value.

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

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

Return

An error_code value.

Parameters

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

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

  • [in] grid_scope: A GridScope value.

  • [in] ts_scope: A TimestepScope value.

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

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 id is 0 (zero) and Liquid id (sum of all liquid phases) is 1 (One). 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]

Return

An error_code value.

Parameters

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

  • [out] out: Variable value.

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

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

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).
Return

An error_code value.

Parameters

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

  • [out] S_w: Wetted Perimeters [m].

  • [out] S_i: Interface Perimeter [m].

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

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

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

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.

Full API Reference Application API