1. S3-1 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation SECTION 3 UTILITY SUBROUTINES

2. S3-2 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation WHAT IS IN THIS SECTION Utility subroutines overview Querying system states Mathematics and messaging Interfacing and file input/output Additional parameters in utility subroutines

3. S3-3 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation UTILITIES SUBROUTINE OVERVIEW Adams/Solver provides additional subroutines for common tasks such as querying state values during a simulation, accessing built-in Adams/Solver functions and general interaction with the environment The Adams/Solver subroutines documentation has a section listing all of the Utility subroutines These can be broken down into three general categories –Querying system states –Mathematics and messaging –Interfacing and file input/output Figure: Utility subroutines listing in documentation

4. S3-4 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation QUERYING SYSTEM STATES System states such as part displacement, part velocity, and force magnitudes can be queried from within a subroutine Adams/Solver provides two ‘utility’ subroutines that will return states of interest at the current simulation time: –SYSFNC() – returns a single system state at the current time –SYSARY() – returns an array of system states for a particular element The SYSFNC() and SYSARY() documentation list the different states that can be queried. For the most part the list of states is similar to what is presented in standard Adams/Solver function expressions and naming conventions for these quantities is also similar. Examples of states that can be queried are: –DX, DY, DZ, DM –VX, VY, VZ, VR –FX, FY, FZ, FM –BEAM, BUSH, FIELD, DIF

5. S3-5 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation QUERYING SYSTEM STATES (CONT.) Using SYSFNC within a Fortran subroutine to determine the velocity of marker 33 with respect to marker 42, in marker 42’s coordinate reference frame, could be done with the following code example: Figure: Finding relative velocity with SYSFNC() C --- Relative velocity in Y-direction: IPAR(1) = 33 IPAR(2) = 42 IPAR(3) = 42 NSIZE = 3 CALL SYSFNC(’VY’, IPAR, NSIZE, DISP_Y, ERRFLG)

6. S3-6 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation MATHEMATICS AND MESSAGING Accessing the built-in Adams/Solver function expressions is also possible Examples of function expressions that can be called for mathematics include: –STEP(), STEP5() –IMPACT(), BISTOP() –CUBSPL(), AKISPL() –FORCOS(), SHF() These save the user from re-creating commonly-used Adams/Solver function expressions. An example of calling STEP5() is the following: –CALL STEP5(x,x0,h0,x1,iord,value,errflg) –Note the three additional parameters in this call, as compared to the standard ADAMS/Solver function expression STEP5() implementation.

7. S3-7 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation MATHEMATICS AND MESSAGING Helper routines also exist for providing messaging feedback to the user during simulation. A subroutine could, for example, issue a warning to the.msg file and to the console during interactive simulation: –CALL USRMES(.TRUE., ’Exceeding linear!’, 0, ’WARN’) Another example that will display an error message to the console and to the message file, if the logical variable ERRFLG is true: –CALL ERRMES(ERRFLG, ’Error: Wrong input’, 0, ’STOP’) –Note that this call will stop the solver, if ERRFLG is true. This is a very common subroutine to call to do error checking on inputs and other utility function calls such as SYSFNC, CUBSPL, STEP, etc.

8. S3-8 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation INTERFACING AND FILE INPUT/OUTPUT Other help subroutines facilitate reading data from either a file (PUT_SPLINE()) or from other elements in the dataset: –GTARAY() – read an ARRAY element into memory –GTCURV() – read a CURVE element into memory –GTSTRG() – read a STRING element into memory To determine which Adams version is running, which integrator setting is being used, and what the current simulation mode is (statics, dynamics, assembly, etc), the following helper subroutines would be used: –GETVER() – which version of Adams/Solver is running –GETINT() – which integrator setting is being used –GETMOD() – current simulation mode

9. S3-9 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation ADDITIONAL PARAMETERS IN UTILITY SUBROUTINES All of the Utility subroutines that provide access to standard Adams/Solver function expressions contain additional parameters that don’t appear in the typical function expression implementation For example, using the STEP5() function in a standard function expression might look like this: –STEP5(x,x0,h0,x1,h1) Whereas the same call from within a user subroutine would look like this: –CALL STEP5(x,x0,h0,x1,h1,iord,value,errflg) –Two of these additional parameters are common to the other Utility subroutines they are: value – most Utility subroutines must return a calculated value. Pass in a variable here that will get over-written with the result. errflg – most Utility subroutines have an “exit status” variable to indicate success (TRUE) or failure (FALSE). It is good practice to check this variable value after each Utility subroutine call. If the Utility subroutine fails for any reason then it is likely that the returned value is not meaningful. The other parameter, iord, is specific to the STEP5() function, instructing STEP5() to return either the value, the first derivative or the second derivative of the function at that point.

10. S3-10 ADM703c, Section 3, February 2013 Copyright  2013 MSC.Software Corporation EXERCISE Perform Workshop 3 “Variable Damper Element” in your exercise workbook