ROUTINE Argument

Many Adams Solver statements and commands feature the construct FUNCTION=USER(r1,r2,...,r30), which specifies that Adams Solver is to obtain element characteristics by loading and calling a specific user subroutine from a specific library of user subroutines. For example, Adams Solver calls the SFOSUB subroutine for the SFORCE statement.

The ROUTINE argument allows you to optionally specify an alternative library and user subroutine name for some or all elements.

The ROUTINE argument takes a string argument:

The delimiter, ::, is required to separate the library name from the subroutine name. Both the libname and the subname are optional, but the :: delimiter is required to distinguish the library name. For example, to specify that a different subroutine name, mysfo, is to be loaded from the default subroutine library (the library that was mentioned when Adams Solver was run in run-user mode), you should write:

or

If the default name (for example SFOSUB for SFORCE) is acceptable but the user subroutine is to be loaded from a library 'mylib', you must write:

The table below lists the default names for user subroutines for Adams Solver statements and commands.

Just like many elements of a particular type can share the default user subroutine, many elements may share an alternative user subroutine. In other words, a group of your SFORCE elements may use the SFOSUB in the default library while a different group of SFORCE elements is using mylib::mysfo.

You can either fully qualify the name and location of the library or rely on Adams Solver to search for the library using predefined rules. For example, ROUTINE argument can specify absolute paths:

or relative paths with abbreviated library names:

In the latter case, you would be relying on Adams Solver knowing to search in /home/jdoe (see the PREFERENCES statement for details about the library search path) and built-in search-rules that first look for the specified name, and failing that, try to prepend the lib prefix and an architecture specific suffix (.dll on the Microsoft Windows platform, .sl on the HP-UX platform and .so on other Linux platforms and Linux).

The COUPLER and GSE elements deserve special mention because they require more than one user subroutine.

The COUPLER element requires that three subroutines be provided. This is handled by providing a comma separated list of three libname::subname pairs, for example:

where lib1, lib2, and lib3 can be three different libraries. The default names for these subroutines are COUSUB,COUXX,COUXX2, in that order.

The GSE case is further complicated by the fact that the GSE subroutine interface has recently been redesigned and the ROUTINE argument had been previously reserved to address the now deprecated GSESUB interface. To specify the new GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP, GSE_SET_NS, GSE_SET_ND, GSE_SET_IMPLICIT, GSE_SET_STATIC_HOLD, GSE_SET_SAMPLE_OFFSET subroutines for GSE, use the INTERFACE argument:

to specify the subroutines that default to GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP, GSE_SET_NS, GSE_SET_ND, GSE_SET_IMPLICIT, GSE_SET_SATIC_HOLD, GSE_SET_SAMPLE_OFFSET in that order. Note that not all of these routines need to be supplied. For example, if only GSE_DERIV and GSE_OUTPUT are being used, then gse::lib pairs 3-9 can be omitted. However, these gse::lib pairs must be listed in order and dummy interfaces need to be created to preserve the order even if they are not being used. For example, if the GSE_SET_IMPLICIT interface is being specified, then all of the preceeding interfaces need to be speciefied (if only in dummy form) also.

You can specify deprecated GSE subroutine interface using:

to specify the subroutines that default to GSESUB, GSEXX, GSEXU, GSEYX, GSEYU, in that order.