The CBKSUB subroutine is an optional user-written subroutine that Adams Solver C++ calls at a predefined set of events during the code execution. The CBKSUB only passes input values announcing the type of event, the current simulation time, and a data array.

An event can be seen as a milestone reached during the code execution. An event is triggered when certain conditions occur, for example, a SENSOR triggers or an error condition is detected. Most of the time a milestone is reached naturally by the code, for example, a simulation command is about to be executed, a corrector iteration is about to start and so on.

The CBKSUB is a true callback function designed for advanced users only.

    include 'slv_cbksub_util.inc'

    SUBROUTINE CBKSUB ( time, event, data )

    include 'slv_cbksub.inc'

    DOUBLE PRECISION time

    INTEGER event, data(3)

 

    include "slv_cbksub.h"

    include "slv_cbksub_util.h"

    void Cbksub( const struct sAdamsCbksub *cbk, double time, int event, int *data )

 

    include "slv_cbksub.h"

    include "slv_cbksub_util.h"

    extern "C" void Cbksub( const struct sAdamsCbksub *cbk, double time, int event, int *data )

Currently, only the Adams Solver C++ supports the CBKSUB.

The overhead (CPU time) is negligible.

Providing this subroutine is optional.

All utility subroutines are allowed to be called from within the CBKSUB except ADAMS_DECLARE_THREADSAFE, ANALYS, DATOUT, GTCMAT, MODIFY, PUT_SPLINE and UCOVAR. Calling any of these subroutines makes the behavior of the Adams Solver C++ undefined. No guards have been implemented.

None of the user-written subroutines are allowed to be called. The forbidden set includes CFFSUB, CNFSUB, CONSUB, COUSUB, COUXX, COUXX2, CURSUB, DIFSUB, DMPSUB, FIESUB, GFOSUB, GSE_DERIV, GSE_UPDATE, GSE_OUTPUT, GSE_SAMP, MFSUB, MOTSUB, RELSUB, REQSUB, SAVSUB, SENSUB, SEVSUB, SFOSUB, SPLINE_READ, SURSUB, TIRSUB, VARSUB, VFOSUB and VTOSUB. Calling forbidden subroutines makes the behavior of the Adams Solver C++ undefined. No guards have been implemented.

Both SYSFNC and SYSARY are allowed to be called from within the CBKSUB. Notice however, that no dependencies are registered. This feature makes possible to compute some desired quantities without creating dependencies. Usually, users will compute and cache values at specific events.

Forty four (44) events have been implemented. Below is the list of current supported events.

Most of the events shown above provide the current simulation mode and analysis mode stored in the input array data. The current simulation mode is the main simulation being executed as a response to a simulation command. The value of the simulation mode is the same value obtained making calls to the GETMOD utility subroutine or the value computed with the MODE function.

The analysis mode is a temporary numerical solution required to honor the simulation requested by the user. For example, when Adams Solver C++ starts a dynamic simulation it first checks whether an initial conditions is required. If the initial-conditions job is required, an ev_ITERATION_BEG event will provide “Dynamics” and “Initial conditions” as the simulation mode and analysis mode respectively if the iteration is performed from within the temporary initial-conditions job.

Table 1 below shows the simulation/analysis modes provided in the input array data.

This section describes a simplified CBKSUB call sequence during a dynamic simulation. The call sequence for other simulations is similar.

When executing a dynamic simulation, Adams Solver C++ divides the time span between the current simulation time and the final simulation time into a number of so called "output steps". The state of the system is advanced up to the end of each output step at which a request for output generation is triggered from within the innermost code layer. However, to reach the end of each output step, the solver may require to perform a set of smaller "time steps" in order to reach the end of the current output step. Figure 1 and Figure 2 depict a simplified version of the overall program flow showing the calls to the CBKSUB subroutine.

Highlights related to Figure 1 are the following. First, the block labeled "Process SIM/DYN command" stands for the code where the input parameters of the simulation command are read. The command information is used to determine the number of output steps required to be made by the solver. Also notice that in case an initial conditions job is required, no details of the calling sequence to the CBKSUB are presented.

Finally, the block corresponding to the function output_step() is presented in Figure 2.

The flowchart presented in Figure 2 consists of two loops. The outer loop controls the number of "time steps" made by the dynamic integration until an "output step" is reached. The inner loop controls the number of corrector iterations required to advance the state of the simulation.

Figure 1 and Figure 2 are simplified versions of the calling sequence of the CBKSUB subroutine. For the sake of clarity, several calls have been omitted.

Let’s assume an Adams model has a set of VFORCEs defined by VFOSUB subroutines. Let’s assume the function expression for these VFORCEs is very complex and requires several SYSFNC or SYSARY calls in order to properly compute the magnitude of each component. For example, the x component of the forces couold have this expression:

where is a non linear function and and are measurable states of the model that can be computed with the help of SYSFNC and SYSARY calls. If the computation of is common to all VFORCEs then it is possible to cache the value of at the beginning of each corrector iteration and then return the value:

At every subsequent VFOSUB call. This can be done safely by creating a CBKSUB where the ITERATION_BEG event is monitored to compute the cache value and set an internal flag ON. Both the cache and the flag will be defined in a COMMON block which the VFOSUBs share. For all other events, the flag is turned OFF.

Listings nocallback.acf, nocallback.adm and nocallback.f (see Appendix) correspond to a simple model with a VFOSUB. The model is a spring-mass system shown in Figure 3. A VFOSUB computes the value of DX(16,1,1) and applies it to one of the masses. A dynamic simulation is run for 5.0 seconds.

A partial listing of the message file is shown below.

Listings yescallback.acf, yescallback.adm and yescallback.f correspond to the same model shown above. However, this time a CBKSUB is included. The CBKSUB prints a message at every event announcing the event, the simulation mode, the analysis mode, and the current time when available.

The CBKSUB is interested only in the ev_ITERATION_BEG event at which a FLAG is raisde and a cache VALUE is computed to be used in the subsequent VFOSUB calls. The same dynamic simulation is run and Figure 4 shows the plots of the results comparing the runs with and without a CBKSUB. A partial listing of the message file when using a CBKSUB is shown below. Notice the CBKSUB prints a a message every time an iteration begins.

 

The fundamental question concerns the quality of the results. For the particular example presented above, the results with and without a CBKSUB will differ depending on the error tolerance set by the INTEGRATOR statement/command. In this case, using an error tolerance of 1.0E-04 shows indistinguisable results. If usinng a default INTEGRATION settings (error tolerance 1.0E-03) some differences appear but below the prescribed integration error nonetheless.

In general, using the strategy presented above ought to provide correct results (errors are under the prescribed integration error tolerance). However, the speed of convergence may be affected.