GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP
These four subroutines are used to completely define a GSE (C++ or FORTRAN). Recall that the constitutive equations for a GSE have the explicit form:
 | (1) |
 | (2) |
 | (3) |
and in implicit form equations (1) and (3) are replaced by equations (4) and (5), respectively, below:
 | (4) |
 | (5) |
■GSE_DERIV defines the function fc(), shown in Equation (1) or (4) above. In the explicit case GSE_DERIV need to provide the partial derivatives:
and in implicit case following three partial derivatives should be provided:
■GSE_OUTPUT defines the function g(), shown in Equation (3) or (5) above. In the explicit case GSE_OUTPUT need to provide the partial derivatives:
and in the implicit case following three partial derivatives should be provided:
■GSE_UPDATE defines the function fd(), shown in Equation (2) above. It defines the derivative of the states that the GSE introduces. GSE_UPDATE does not return any partial derivatives.
■GSE_SAMP defines the sampling period associated with Equation (2). The sampling period is the time between two consecutive updates. It does not need to be a constant.
Note: | Use mixed case names for the Adams subroutine names when using the C style interface. For the default subroutine name capitalize the first letter and have the remaining letters lower case. Doing this ensures that Adams Solver correctly distinguishes a C style subroutine from Fortran and calls with the appropriate interface. |
Use
Corresponding Statement
GSE_DERIV
Calling Sequence and Structure
SUBROUTINE GSE_DERIV (ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, XDOT)
Input Arguments
id | An integer variable containing the ID of the GSE statement requesting information from the GSE subroutine. From the identifier, Adams Solver automatically recognizes other information (such as the PAR argument) that is associated with that GSE statement. |
time | A double-precision variable containing the current simulation time. |
par | A double-precision array containing the constant parameters taken in order from the USER parenthetical list in the GSE statement. |
npar | An integer variable containing the number of constants in the Function=USER(...) parenthetical list in the GSE statement. The primary purpose is to provide the subroutine with the number of entries in the par array. |
dflag | The DFLAG argument should be ignored. It is present only to provide backward compatibility for the GSE API. Do not use this argument as a logical flag for computing partial derivatives. Instead, always use the utility subroutine ADAMS_NEEDS_PARTIALS. Using DFLAG will give incorrect results. |
iflag | An integer variable that Adams Solver sets to indicate why the routine is being called:  When iflag is 0 Adams Solver calling to compute the value of the user-written variable. When iflag is set to 1 or 3 do any initializations that your subroutine requires. When your user-defined subroutine has static data that needs to be saved and restored to support the Adams Solver commands Save and Reload, then call the serialization functions for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9. Note: In simple subroutines where serializing data is not needed, you can declare iflag as a logical variable. In this case you can do any initializations when Adams Solver sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag to false. |
ns | An integer variable containing the number of continuous states in the GSE; taken from the NS argument to the GSE statement. |
Output Arguments
xdot | A double-precision array of dimension NS, containing the derivatives of the state xc. |
Examples
For an example of this subroutine, see gse_deriv.f
GSE_UPDATE
Calling Sequence
SUBROUTINE GSE_UPDATE (ID, TIME, PAR, NPAR, DFLAG, IFLAG, ND, XDplus1)
Input Arguments
id | An integer variable containing the ID of the GSE statement requesting information from the GSE subroutine. From the identifier, Adams Solver automatically recognizes other information (such as the PAR argument) that is associated with that GSE statement. |
time | A double-precision variable containing the current simulation time. |
par | A double-precision array containing the constant parameters taken in order from the USER parenthetical list in the GSE statement. |
npar | An integer variable containing the number of constants in the Function=USER(...) parenthetical list in the GSE statement. The primary purpose is to provide the subroutine with the number of entries in the Par array. |
dflag | The DFLAG argument should be ignored. It is present only to provide backward compatibility for the GSE API. |
iflag | An integer variable that Adams Solver sets to indicate why the routine is being called:  Adams Solver sets iflag to 3 when it needs the functional dependency of the user-defined variable. The functional dependencies are set with the same calls to the SYSARY and SYSFNC utility subroutines that are made to compute the value of the user-defined variable. If iflag is 0, Adams Solver computes the value of the user-written variable. When your user-defined subroutine has static data that needs to be saved and restored to support the Adams Solver commands Save and Reload, then call the serialization functions for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9. Note: In simple subroutines where serializing data is not needed, you can declare iflag as a logical variable. In this case you declare your dependencies when Adams Solver sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag to false. |
nd | An integer variable containing the number of discrete states in the GSE; taken from the ND argument to the GSE statement. |
Output Arguments
XdPlus1 | A double-precision array of dimension ND, containing the value of the GSE discrete states at time T=Tn+1. |
Examples
For an example of this subroutine, see gse_update.f.
GSE_OUTPUT
Calling Sequence and Structure
SUBROUTINE GSE_OUTPUT (ID, TIME, PAR, NPAR, DFLAG, IFLAG, NO, Y)
Input Arguments
id | An integer variable containing the ID of the GSE statement requesting information from the GSE subroutine. From the identifier, Adams Solver automatically recognizes other information (such as the par argument) that is associated with that GSE statement. |
time | A double-precision variable containing the current simulation time. |
par | A double-precision array containing the constant parameters taken in order from the USER parenthetical list in the GSE statement. |
npar | An integer variable containing the number of constants in the Function=USER(...) parenthetical list in the GSE statement. The primary purpose is to provide the subroutine with the number of entries in the PAR array. |
dflag | The DFLAG argument should be ignored. It is present only to provide backward compatibility for the GSE API. Do not use this argument as a logical flag for computing partial derivatives. Instead, always use the utility subroutine ADAMS_NEEDS_PARTIALS. Using DFLAG will give incorrect results. |
iflag | An integer variable that Adams Solver sets to indicate why the routine is being called:  Adams Solver sets iflag to 3 when it needs the functional dependency of the user-defined variable. The functional dependencies are set with the same calls to the SYSARY and SYSFNC utility subroutines that are made to compute the value of the user-defined variable. If iflag is 0, Adams Solver computes the value of the user-written variable. When your user-defined subroutine has static data that needs to be saved and restored to support the Adams Solver commands Save and Reload, then call the serialization functions for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9. Note: In simple subroutines where serializing data is not needed, you can declare iflag as a logical variable. In this case you declare your dependencies when Adams Solver sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag to false. |
no | An integer variable containing the number of outputs in the GSE; taken from the NO argument to the GSE statement. |
Output Arguments
Y | A double-precision array of dimension NO, containing the value of the GSE at the current simulation time. |
Example
For an example of this subroutine, see gse_output.f.
GSE_SAMP
Calling Sequence and Structure
SUBROUTINE GSE_SAMP (ID, TIME, PAR, NPAR, IFLAG, Sample_Step)
Input Arguments
id | An integer variable that gives the identifier of the GSE statement requesting information from the GSE subroutine. From the identifier, Adams Solver automatically recognizes other information (such as the Par argument) that is associated with that GSE statement. |
time | A double-precision variable containing the current simulation time. |
par | A double-precision array containing the constant parameters taken in order from the USER parenthetical list in the GSE statement. |
npar | An integer variable containing the number of constants in the Function=USER(...) parenthetical list in the GSE statement. The primary purpose is to provide the subroutine with the number of entries in the Par array. |
iflag | An integer variable that Adams Solver sets to indicate why the routine is being called:  Adams Solver sets iflag to 3 when it needs the functional dependency of the user-defined variable. The functional dependencies are set with the same calls to the SYSARY and SYSFNC utility subroutines that are made to compute the value of the user-defined variable. If iflag is 0, Adams Solver computes the value of the user-written variable. When your user-defined subroutine has static data that needs to be saved and restored to support the Adams Solver commands Save and Reload, then call the serialization functions for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9. Note: In simple subroutines where serializing data is not needed, you can declare iflag as a logical variable. In this case you declare your dependencies when Adams Solver sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag to false. |
Output Arguments
sample_step | A double-precision scalar, containing the sample step (that is, the difference between the next sample time, and the current simulation). |
Calling schedule of GSE_UPDATE and GSE_SAMP subroutines
GSE objects defining discrete states must be defined with a GSE_UPDATE subroutine that defines Equation (2) above. Moreover, either a SAMPLE_PERIOD expression or a GSE_SAMP subroutine must be included to define the sampling times, for example, the times when the call to GSE_UPDATE is made (see GSE statement for more details). Adams Solver (C++) will call GSE_UPDATE only when time is increasing and the current simulation time coincides with the current sampling time. Therefore, no calls to GSE_UPDATE are made during simulations where the simulation time does not change. In other words, calls to GSE_UPDATE are made only when the simulation mode is 4 or 6 (see GETMOD utility.)
If the SAMPLE_OFFSET is bigger than zero, the calling sequence is as follows. Adams Solver (C++) will start simulating the model up to the SAMPLE_OFFSET time. Notice that no calls to the GSE_UPDATE subroutine are made while the simulation time is smaller than SAMPLE_OFFSET. Upon reaching the SAMPLE_OFFSET time, Adams Solver (C++) will either evaluate the SAMPLE_PERIOD expression or it will make the first call to the GSE_SAMP subroutine to determine the time of the first sampling time, before proceeding with the simulation. Upon reaching the first sampling time, the first call to GSE_UPDATE is made. At this point, the next sampling time is computed by either computing the value of the SAMPLE_PERIOD expression or the getting the next value from the GSE_SAMP subroutine. With the next sampling time computed, Adams Solver (C++) will simulate the model up to that time, it will call GSE_UPDATE, it will compute the next sampling time, and so on.
If the SAMPLE_OFFSET is zero, Adams Solver (C++) will evaluate the first sampling time by evaluating the SAMPLE_PERIOD expression or by making a call to the GSE_SAMP subroutine. The simulation then will proceed up to the first sampling time. Upon reaching the first sampling time, the first call to GSE_UPDATE is made. Also at this point, the next sampling time is computed (by evaluating the SAMPLE_PERIOD expression or by calling GSE_SAMP), and so on.
Example
For an example of this subroutine, see gse_samp.f.
C Style - Prototype
typedef void adams_c_GSESUB(const struct sAdamsGSE* gse, double TIME, int DFLAG, int IFLAG, int NSTATE, const double* STATES, int NINPUT, const double* INPUTS, int NPUTPUT, double* STATED, double* OUTPUT);
typedef void adams_c_GSEXU(const struct sAdamsGSE* gse, double TIME, int IFLAG, int NSTATE, const double* STATES, int NINPUT, const double* INPUTS, int NOUTPUTS, double* DERIVS);
typedef void adams_c_GSEXX(const struct sAdamsGSE* gse, double TIME, int IFLAG, int NSTATE, const double* STATES, int NINPUT, const double* INPUTS, int NOUTPUTS, double* DERIVS);
typedef void adams_c_GSEYU(const struct sAdamsGSE* gse, double TIME, int IFLAG, int NSTATE, const double* STATES, int NINPUT, const double* INPUTS, int NOUTPUTS, double* DERIVS);
typedef void adams_c_GSEYX(const struct sAdamsGSE* gse, double TIME, int IFLAG, int NSTATE, const double* STATES, int NINPUT, const double* INPUTS, int NOUTPUTS, double* DERIVS);
typedef void STDCALL adams_f77_GSESUB(const int* ID, const double* TIME, const double* PAR, const int* NPAR, const int* DFLAG, const int* IFLAG, const int* NSTATE, const double* STATES, const int* NINPUT, const double* INPUTS, const int* NOUTPUT, double* STATED, double* OUTPUT);
typedef void adams_c_GSEDERIV(const struct sAdamsGSE* gse, double TIME, int DFLAG, int IFLAG, int, double*);
typedef void adams_c_GSEOUTPUT(const struct sAdamsGSE* gse, double TIME, int DFLAG, int IFLAG, int, double*);
typedef void adams_c_GSEUPDATE(const struct sAdamsGSE* gse, double TIME, int DFLAG, int IFLAG, int, double*);
typedef void adams_c_GSESAMPLE(const struct sAdamsGSE* gse, double TIME, int IFLAG, double* OUTPUT);
typedef void adams_c_GSESETNS(int NS, int* ERR);
typedef void adams_c_GSESETND(int ND, int* ERR);
typedef void adams_c_GSESETIMPLICIT(int FLAG, int* ERR);
typedef void adams_c_GSESETSTATICHOLD(int FLAG, int* ERR);
typedef void adams_c_GSESETSAMPLEOFFSET(int UNTNUM, double* LOGERR);
/*
* GSE
*/
struct sAdamsGSE
{
int ID;
int NPAR;
const double* PAR;
int NI;
int NO;
int U;
int Y;
int NS;
int X;
int IC;
int STATIC_HOLD;
int IMPLICIT;
int ND;
int XD;
int ICD;
double SAMPLE_OFFSET;
};