10.3. User Plugins
Similarly to user-defined subroutines, user plugins are a functionality shared by Adagio and Presto that supports extending the in-built capabilities. Currently, this extension is limited to the subroutine capability discussed in Section 10.2, however there are some advantages to using plugins as opposed to subroutines which are discussed in the following. Additional requirements for user plugin definition and use are also described.
10.3.1. User Plugin Advantages
User plugins provide several advantages over user subroutines; primarily they are faster to build and can be shared more easily than SIERRA applications rebuilt with the user subroutine. User plugins in Adagio and Presto remain a nascent capability, but continued development can support greater extensibility of capabilities such as element and material model formulations. A high-level list of advantages to using the plugin approach over subroutines is provided below.
Plugins can support programming languages other than Fortran
Plugins build faster than subroutines
Built plugins can be shared among users/platforms allowing greater re-use
Plugins do not generate a new executable that must be managed/versioned
10.3.2. User Plugin Usage
Currently in Sierra/SM, user plugins only support the current capabilities of user subroutines but with the advantages listed in the previous section. There are two requirements for converting an existing subroutine to a plugin:
The user subroutine input file command line
USER SUBROUTINE FILE = file.F
must be replaced with
LOAD USER PLUGIN FILE file.so
where file.so is the name of the shared object file generated from the source file.F.
The source file must define the function dl_register(), which registers callable functions/subroutines used in the analysis (see Section 10.3.2.1).
Currently, only SUBROUTINE line command capabilities are supported by user plugins in Sierra/SM. These capabilities currently require FORTRAN interfaces, and the current release requires that the plugin source be written in FORTRAN as well. If you are interested in converting existing user subroutines to C/C++ or developing new ones in C/C++, please file a support request with sierra-help@sandia.gov.
Upon addition of the dl_register() function and updating the line command in the input file to use
LOAD USER PLUGIN FILE file.so
the plugin is built and the analysis is executed with the following commands (similarly as in Section 10.2.3). Note that there is no need to specify the path to a different executable.
sierra --make adagio -i <string>sierra_input_file
sierra -j N adagio -i <string>sierra_input_file
10.3.2.1. Definition of dl_register()
The dl_register() function must be implemented in the same file as the plugin and using the same programming language. The registration function must take no arguments and have no return value. An example FORTRAN definition of the registration function is shown in Listing 10.1. Note that if multiple Sierra/SM-callable subroutines are defined in the file, they should all be registered in the single dl_register() function or subroutines called by dl_register.
subroutine dl_register()
implicit none
external fmwkusersub ! this is the registration function
!
! Different function types for the associated input line command.
!
! It is only necessary to declare the used subroutine types, all
! supported types are listed below.
!
external apub_element_type ! ELEMENT BLOCK SUBROUTINE
external apub_mount_force ! MOUNT FORCE SUBROUTINE
external apub_mount_init ! MOUNT INIT SUBROUTINE
external apub_mount_size ! MOUNT SIZE SUBROUTINE
external apub_node_set_type ! NODE SET SUBROUTINE
external apub_surface_type ! SURFACE SUBROUTINE
external vumat_subroutine_type ! VUMAT SUBROUTINE
! register the subroutine(s)
call fmwkusersub(apub_element_type, my_element_subroutine, &
'my_element_subroutine')
end
subroutine my_element_subroutine(...)
...
end