The CBKSUB statement is used to register an optional user-written subroutine that Adams Solver C++ calls at a predefined set of milestones (also known as events) during the code execution. CBKSUB stands for "callback subroutine". Typical events are the following: end of reading the Adams model, the start of a command, the start of an iteration, the end of an iteration, the start of static simulation, a sensor triggered and so on. A complete list of supported events is provided in the documentation of the user-written CBKSUB (Adams Solver Subroutines)
Users can write a callback subroutine using FORTRAN or C or C++. The overhead of having a callback subroutine is negligible unless the user performs lengthy numerical calculations therein.
The callback framework is intended for advanced users customizing numerical intensive Adams models performing custom solutions. The callback framework helps writing code to initialize memory, make computations that generate results to be shared by other user-written subroutines or to optimize custom models.
Format
CBKSUB/id, PRIORITY=i, FUNCTION=USER(0), ROUTINE=libname::subname
Arguments
PRIORITY=i | In case there is more than one callback subroutine, this option defines the order in which callback subroutines are called. Callbacks with higher priority are called first. If two or more callbacks have the same priority, the order is not defined.
The priority has no default and it can be set to any integer value. |
FUNCTION=USER(0) | Adams Solver C++ does not pass user parameters to the callback subroutines. Set this option to USER(0). |
ROUTINE=libname::subname | Specifies an alternative library and name for the user written callback subroutine CBKSUB. Learn more about the ROUTINE Argument. |
Extended definition
A callback subroutine is called every predefined milestone during the code execution. Within a callback subroutine user may write code to prepare computations, run custom solutions and so on in order to optimize complex Adams models.
The main specifications of a callback subroutine are the following:
1. Callback subroutines are always called from the main thread.
2. Callback subroutines are called at every predefined set of events during the code execution.
3. Three parameters are passed on each call: the current simulation time, an event identifier, and an array with data that depends on the type of event.
Example
CBKSUB/99, PRIORITY=10, FUNC=USER(0), ROUTINE=mylib::mycbksub