Adams Basic Package > Adams Solver > Welcome to Adams Solver Subroutines > Utility Subroutines > GSE

GSE

The following defines a set of utility subroutines which are to be used in the GSE_DERIV and GSE_OUTPUT user subroutines that are associated with the GSE element.  
These utilities supplement and enhance the SYSARY and SYSPAR utility subroutines that are used in Adams Solver (FORTRAN) to access the input and state arrays of the GSE, and provide the derivatives of the GSE.  
If you are using Adams Solver (C++), you should use the utility subroutines described here rather than SYSARY and SYSPAR because they are more efficient and they permit access to enhanced GSE capabilities (sparse GSE and implicit GSE).
The utility subroutines can be grouped into the following categories:  
■Dimension query utilities (GSE_NS, GSE_ND, GSE_NI, GSO_NO)
■Array query utilities (GSE_X, GSE_XDOT, GSE_XD, GSE_U)
■Partial-derivative entry utilities (GSEPAR_X, GSEPAR_U, GSEPAR_XDOT)
■Partial-derivative mapping utilities (GSEMAP_X, GSEMAP_U, GSEMAP_XDOT)
Note that none of the utility subroutines require that the ID of the GSE be provided. Adams Solver knows which GSE is being referred to.

Dimension Query Utilities: GSE_NS, GSE_ND, GSE_NI, GSE_NO

The dimension query utility subroutines are called to obtain information about the dimension of the various arrays associated with the GSE. Access to this information allows proper dimensioning of arrays. The dimensions obtained from these utilities must be passed to other utility subroutines as verification that the subroutine developer is aware of the required array dimension.
Each of the dimension query utility subroutines takes a single integer argument. After the call to the subroutine, the integer contains the associated dimension.

Called By

GSE_DERIV, GSE_OUTPUT

Prerequisite

None

Calling Sequence

CALL GSE_NS(NS)
CALL GSE_ND(ND)
CALL GSE_NI(NI)
CALL GSE_NO(NO)

Arguments

 
NS
Output integer - the number of states
ND
Output integer - the number of discrete states
NI
Output integer - the number of inputs
NO
Output integer - the number of outputs

Array query utility subroutines: GSE_X, GSE_XDOT, GSE_XD, GSE_U

The array query utility subroutines are called to obtain information about the values of:
■Continuous states, X
■Time derivative of the continuous states, XDOT
■Discrete states, XD
■GSE inputs, U

Called By

GSE_DERIV and GSE_OUTPUT

Prerequisite

Require input values, which must be obtained by a previous call to the dimension query utility subroutines.
Calling Sequence
CALL GSE_X(X,NS)
CALL GSE_XDOT(XDOT,ND)
CALL GSE_XD(XD,ND)
CALL GSE_U(U,NI)

Input Arguments

 
NS
Integer - the number of continuous states (used for validation)
ND
Integer - the number of discrete states (used for validation)
NI
Integer - the number of outputs (used for validation)

Output Arguments

 
X
Double-precision array of dimension NS, the continuous states
XDOT
Double-precision array of dimension NS, the time derivative of the continuous states (IMPLICIT GSE only)
XD
Double-precision array of dimension ND, the discrete states
U
Double-precision array of dimension NI, the inputs
 
Caution:  
If the incorrect validation integer value is provided, Adams Solver (C++) will stop with an error message.

Partial derivative entry utility subroutines: GSEPAR_X, GSEPAR_XDOT, GSEPAR_U

The partial derivative entry utility subroutines are used to provide Adams Solver with:
■The partial derivative of  the GSE_DERIV and GSE_OUTPUT with respect to the continuous states, X
■The time derivative of the continuous states, XDOT (implicit GSE only)
■The inputs, U
A call to GSEPAR_X from GSE_DERIV is understood to provide the partial derivative of GSE_DERIV with respect to X, and so on.
The GSEPAR utility subroutines are assumed to provide full partials unless one or more calls were made to the corresponding GSEMAP when the GSE_DERIV or the GSE_OUTPUT user subroutine was called with IFLAG set. When full partials are provided with the GSEPAR utility subroutines, the order of the entries should be such that all the partial derivatives with respect to the first state or input should be provided in order before the partial derivatives with respect to the second state or input. If sparse partial derivatives are used, the entries to GSEPAR should be in the same order as was defined by GSEMAP.

Called By

GSE_DERIV and GSE_OUTPUT

Prerequisite

Calls may be dependent on calls made to GSEMAP utility subroutines when IFLAG was set.

Calling Sequence

CALL GSEPAR_X(D,N)
CALL GSEPAR_XDOT(D,N)
CALL GSEPAR_U(D,N)

Input Arguments

 
D
Double-precision array of partial derivatives in the appropriate order
N
Integer - the number of partials being provided (used for validation)
 
Caution:  
If N does not validate, Adams Solver (C++) stops with an error message. For full partials it is expected to be the product of the corresponding dimensions. For example, the call to GSEPAR_X from a GSE_OUTPUT should have N = NI * NS, where NI and NS are  the return values of GSE_NI and GSI_NS respectively. For sparse partials, the value of N should equal the number of calls made to the corresponding GSEMAP utility subroutine.

Partial derivative mapping utility subroutines: GSEMAP_X, GSEMAP_XDOT, GSEMAP_U

The partial derivative mapping utility subroutines may optionally be used to configure the GSE to have sparse entries. For a GSE with a large number of states, inputs and/or outputs, the computational savings can be significant.
GSEMAP_X, GSEMAP_XDOT, and GSEMAP_U register dependencies with respect to state, the time derivative of state (implicit GSE only) and input, respectively.
If Adams Solver (C++) detects calls to the GSEMAP utility subroutines during calls to GSE_DERIV or GSE_OUTPUT, when IFLAG is set, then the corresponding partial derivative is taken to be sparse.  GSEMAP utility subroutine calls may be made for one or more of the families of partial derivaties. For example, if GSEMAP_X is called from GSE_DERIV, this particular partial derivative is taken to be sparse while the other families of partial derivatives, for example the partial derivative of GSE_DERIV with respect to U, is taken to be full.
Multiple calls are made to GSEPAR utility subroutines, one per dependency. For example, a call GSEMAP_X(1,1) from GSE_OUTPUT indicates to Adams Solver (C++) that the first output depends on the first state. The order of the calls to GSEMAP utility subroutines is significant because entries in the array subsequently passed to the corresponding GSEPAR utility subroutines is assumed to be in this order.  

Called By

GSE_DERIV and GSE_OUTPUT

Prerequisite

None

Calling Sequence

CALL GSEMAP_X(I,J)
CALL GSEMAP_XDOT(I,J)
CALL GSEMAP_U(I,J)

Input Arguments

 
I
Integer - the row index (the index of the state derivative or the output which has a functional dependency)
J
Integer - the column index (the index of the state or the input with respect to which the functional dependency is being registered)