Solver Configuration Hooks#
The solver configuration hooks allow plugins to configure internal settings from ALFAsim. To add a configuration hook it is necessary to implement the given hook in a python file that is already available on your plugin project folder.
As an example, if a plugin was created using alfasim-sdk new
command and named as myplugin
the necessary file to
be customized would be located on:
Additional Variables#
- alfasim_get_additional_variables()#
Allows plugins to register new additional variables on ALFAsim.
It can be used to store the internal variable from the plugin (on solver), or it can be used to expose as an output to the user in the plot window (on application). To calculate and update the registered variables the Solver hooks described on Update plugin variables section must be implemented.
This method expects to return a list of
SecondaryVariable
, for more details checkout the reference section with all details about variablesUsage example:
from alfasim_sdk import SecondaryVariable from alfasim_sdk import Visibility from alfasim_sdk import Location from alfasim_sdk import Scope @alfasim_sdk.hookimpl def alfasim_get_additional_variables(): return [ SecondaryVariable( name="dummy_variable", caption="Plugin 1", unit="m", visibility=Visibility.Internal, location=Location.Center, multifield_scope=Scope.Global, checked_on_gui_default=True, ) ]
Hydrodynamic Model#
ALFAsim provides a way to customize the hydrodynamic model available within the application, with the usage of the hook listed below, the plugin can:
Add new fields
Add/update phases
Add/update layers
Note
For each new added field
, an additional mass conservation equation is considered. For each new added layer
, an additional momentum equation is considered.
Depending on the energy model used at ALFAsim, an additional energy equation can be considered as well.
- alfasim_configure_fields(ctx)#
Allows plugins to configure new fields to be added in ALFAsim’s hydrodynamic model.
An added
field
must be associated with:Phase, defined by
AddPhase
orUpdatePhase
.Layer, defined by
AddLayer
orUpdateLayer
.
The
ctx
parameter is provided to retrieve information about the current state of the application and the current value of the models implemented by the user.Check out the full documentation of
Context
for more details.Example of usage:
@alfasim_sdk.hookimpl def alfasim_configure_fields(ctx): return [ AddField(name="plugin_continuous_field"), AddField(name="plugin_dispersed_field"), ]
- alfasim_configure_phases(ctx)#
Allows plugins to configure new phases or associate a new field with a existing phase from the application. In order to configure a new phase it is necessary to return an
AddPhase
object defining the required fields.The
ctx
parameter is provided to retrieve information about the current state of the application and the current value of the models implemented by the user.Check out the full documentation of
Context
for more details.Example of usage:
@alfasim_sdk.hookimpl def alfasim_configure_phases(ctx): return [ AddPhase( name="plugin_phase", fields=[ "plugin_continuous_field", "plugin_dispersed_field", ], primary_field="plugin_continuous_field", is_solid=False, ) ]
With this new phase, all existing hydrodynamic models from the application will have this additional phase. Notice that the
fields
parameter must be a field registered from the hookalfasim_configure_fields()
.Note
You can restrict the operation of your plugin in the application to certain settings by using the status monitor. For example, if your plugin does not work with the water phase you can block the simulation if the user is using a hydrodynamic model with water.
For more details check out the documentation of
alfasim_get_status()
The image below shows the new added phase on the application.
It is also possible to add additional fields to existent phases using the
UpdatePhase
.Example of usage:
@alfasim_sdk.hookimpl def alfasim_configure_phases(ctx): return [ UpdatePhase( name=OIL_PHASE, additional_fields=["plugin_dispersed_field"], ) ]
- alfasim_configure_layers(ctx)#
Allows plugins to configure new layers or associate a new field with a existing layer for ALFAsim’s hydrodynamic model
In order to configure a new layer, it is necessary to return an
AddLayer
object defining the required fields.The
ctx
parameter is provided to retrieve information about the current state of the application and the current value of the models implemented by the user.Check out the full documentation of
Context
for more details.Example of usage:
@alfasim_sdk.hookimpl def alfasim_configure_layers(ctx): return [ AddLayer( name="plugin_layer", fields=["plugin_continuous_field"], continuous_field="plugin_continuous_field", ), UpdateLayer( name=OIL_LAYER, additional_fields=["plugin_dispersed_field"], ), ]
The image below shows the new added phase on the application.
In order to complement the :py:class<alfasim-sdk.HydrodynamicModelType> customization, it is possible to inform ALFAsim which phases (added by the plugin or not) will have the state variables calculated by plugin.
- alfasim_get_phase_properties_calculated_from_plugin()#
Allows the plugin to calculate the properties (state variables) of a phase.
Must return a list of phase names in which state variables will be computed for. If the plugin implements this hook four C/C++ Solver hooks also must be implemented. They are:
The first and last hooks are called immediately before and after the state variables are calculated, respectively.
Example of usage:
from alfasim_sdk import GAS_PHASE @alfasim_sdk.hookimpl def alfasim_get_phase_properties_calculated_from_plugin(): return [GAS_PHASE, "solid"]
- alfasim_get_phase_interaction_properties_calculated_from_plugin()#
Allows the plugin to calculate the properties that are related to a pair of phases, like surface tension.
Must return a list of tuple of phases in which state variables will be computed for. In order to implement the properties,
HOOK_CALCULATE_PHASE_PAIR_STATE_VARIABLE
must be implemented on the C/C++ part of the plugin.Example of usage:
from alfasim_sdk import GAS_PHASE, OIL_PHASE, WATER_PHASE @alfasim_sdk.hookimpl def alfasim_get_phase_interaction_properties_calculated_from_plugin(): return [ (GAS_PHASE, OIL_PHASE), (GAS_PHASE, WATER_PHASE), ]
User Defined Tracers#
Warning
This is advanced customization. We strongly encourage the plugin developer to read the Tracers chapter of
ALFAsim’s Technical Report available on the Help menu at ALFAsim application.
- alfasim_get_user_defined_tracers_from_plugin()#
Allows the plugin to add new tracers in the ALFAsim’s Tracer Solver, in which the transport equation will be modified by Solver hooks listed below.
Must return a list of tracers in which the internal tracer model hooks will be implemented. The following C/C++ Solver hooks must be implemented:
Example of usage:
@alfasim_sdk.hookimpl def alfasim_get_user_defined_tracers_from_plugin(): return ["my_tracer"]
Note
The tracer added in the user-defined tracers from plugin list will not be considered as a standard tracer, which has an output of its mass fraction and appears in the tracer container at ALFAsim’s User Interface. The user-defined tracer is hidden (does not appear in the User Interface) and the plugin developer can modify the transport equation to use its results internally. However, the user-defined tracers will be solved together with the standard tracers (Added via User Interface).