The following sections provide an overview of the arguments in TYRSUB based on their function, and then describes each argument in order of calling sequence:
TYRSUB Calling Sequence
The following sample code shows the calling sequence for arguments in TYRSUB:
Subroutine TYRXXX(
+ NDEV, ISWTCH, JOBFLG, IDTYRE,
+ TIME, DIS, TRAMAT, ANGTWC, VEL, OMEGA, OMEGAR,
+ NDEQVR, DEQVAR, NTYPAR, TYPARR,
+ NCHTDS, CHTDST, ROAD, IDROAD,
+ NROPAR, ROPAR, NCHRDS, CHRDST,
+ FORCES, TORQUE, DEQINI, DEQDER, TYRMOD,
+ NVARS, VARINF, NWORK, WRKARR,
+ NIWORK, IWRKAR, IERR)
TYRSUB Input Arguments
The types of input arguments are:
Job Control
There is only one job control argument: JOBFLG. The value of JOBFLG determines the task that TYRSUB performs, such as reading the tire property file or evaluating the tire forces and moments.
Subroutine TYRXXX(
+ NDEV, ISWTCH, JOBFLG, IDTYRE,
+ TIME, DIS, TRAMAT, ANGTWC, VEL, OMEGA, OMEGAR,
+ NDEQVR, DEQVAR, NTYPAR, TYPARR,
+ NCHTDS, CHTDST, ROAD, IDROAD,
+ NROPAR, ROPAR, NCHRDS, CHRDST,
+ FORCES, TORQUE, DEQINI, DEQDER, TYRMOD,
+ NVARS, VARINF, NWORK, WRKARR,
+ NIWORK, IWRKAR, IERR)
States
The tire states contain the displacement, orientation, and velocity information about the wheel and wheel carrier (hub). The state arguments are:
Subroutine TYRXXX(
+ NDEV, ISWTCH, JOBFLG, IDTYRE,
+ TIME, DIS, TRAMAT, ANGTWC, VEL, OMEGA, OMEGAR,
+ NDEQVR, DEQVAR, NTYPAR, TYPARR,
+ NCHTDS, CHTDST, ROAD, IDROAD,
+ NROPAR, ROPAR, NCHRDS, CHRDST,
+ FORCES, TORQUE, DEQINI, DEQDER, TYRMOD,
+ NVARS, VARINF, NWORK, WRKARR,
+ NIWORK, IWRKAR, IERR)
Tire Properties
The tire properties arrays (TYPARR) contain the data that your TYRSUB reads from the tire property file during initialization and returns to Adams Tire. Adams Tire stores this array statically.
The integer NTYPAR is the size of the TYPARR array, which is currently limited to 300.
Subroutine TYRXXX(
+ NDEV, ISWTCH, JOBFLG, IDTYRE,
+ TIME, DIS, TRAMAT, ANGTWC, VEL, OMEGA, OMEGAR,
+ NDEQVR, DEQVAR, NTYPAR, TYPARR,
+ NCHTDS, CHTDST, ROAD, IDROAD,
+ NROPAR, ROPAR, NCHRDS, CHRDST,
+ FORCES, TORQUE, DEQINI, DEQDER, TYRMOD,
+ NVARS, VARINF, NWORK, WRKARR,
+ NIWORK, IWRKAR, IERR)
TYRSUB Output Arguments
The types of output arguments are:
Forces and Moments
The arguments FORCES and TORQUE return the forces and moments on the wheel at the wheel center. TYRSUB returns the forces and moments in units of Newtons and Newton-meters, respectively, according to the TYDEX ISO-C coordinate system. For more information on the TYDEX axis systems, see
Tire Axis Systems.
Subroutine TYRXXX(
+ NDEV, ISWTCH, JOBFLG, IDTYRE,
+ TIME, DIS, TRAMAT, ANGTWC, VEL, OMEGA, OMEGAR,
+ NDEQVR, DEQVAR, NTYPAR, TYPARR,
+ NCHTDS, CHTDST, ROAD, IDROAD,
+ NROPAR, ROPAR, NCHRDS, CHRDST,
+ FORCES, TORQUE, DEQINI, DEQDER, TYRMOD,
+ NVARS, VARINF, NWORK, WRKARR,
+ NIWORK, IWRKAR, IERR)
Information
TYDEX STI supports the output of tire information, such as contact patch forces and slip angle, through the variable information array (VARINF).
Subroutine TYRXXX(
+ NDEV, ISWTCH, JOBFLG, IDTYRE,
+ TIME, DIS, TRAMAT, ANGTWC, VEL, OMEGA, OMEGAR,
+ NDEQVR, DEQVAR, NTYPAR, TYPARR,
+ NCHTDS, CHTDST, ROAD, IDROAD,
+ NROPAR, ROPAR, NCHRDS, CHRDST,
+ FORCES, TORQUE, DEQINI, DEQDER, TYRMOD,
+ NVARS, VARINF, NWORK, WRKARR,
+ NIWORK, IWRKAR, IERR)
Error Handling
TYDEX STI states that the TYRSUB may not terminate execution of the calling program, but rather should return an error code (IERR) and message text (TYRMOD). Adams Tire modifies the standard and allows TYRSUB to call the Adams Solver utilities
USRMES or
ERRMES for purposes of error handling and stopping execution, if desired.
Subroutine TYRXXX(
+ NDEV, ISWTCH, JOBFLG, IDTYRE,
+ TIME, DIS, TRAMAT, ANGTWC, VEL, OMEGA, OMEGAR,
+ NDEQVR, DEQVAR, NTYPAR, TYPARR,
+ NCHTDS, CHTDST, ROAD, IDROAD,
+ NROPAR, ROPAR, NCHRDS, CHRDST,
+ FORCES, TORQUE, DEQINI, DEQDER, TYRMOD,
+ NVARS, VARINF, NWORK, WRKARR,
+ NIWORK, IWRKAR, IERR)
TYRSUB Argument Descriptions
The following TYRSUB argument descriptions are listed in order of calling sequence:
NDEV
An integer variable that contains the value of the logical output device number for error messages. We recommend calling the Adams Solver utilities USRMES or ERRMES rather than writing directly to the NDEV device. This ensures proper handling of the error message. For more information, see USRMES and ERRMES in the Adams Solver Subroutines online help.
ISWTCH
An integer variable that contains the value of the USE_MODE control switch. Adams Tire sets the ISWTCH variable to zero in all cases except dynamic and quasi-static simulations (for example, Adams Solver modes 4 and 6). For dynamic and quasi-static simulations, ISWTCH = TYPARR(1).
JOBFLG - (Job Control Flag)
An integer variable whose value determines the action TYRSUB should take. Table below shows the values and meaning of JOBFLG.
JOBFLG Values and Descriptions:
Description: | Value: | Parameter in ac_sti_jobflg.inc: |
|---|
INITIALIZE | JOBFLG = 2 | INIT |
RESET | JOBFLG = 3 | RESET |
END SIMULATION | JOBFLG = ENDSIM = 99 | ENDSIM |
NORMAL EVALUATION | JOBFLG = NORMAL = 0 | NORMAL |
DERIVATIVE EVALUATION | JOBFLG = DIFF = 5 | DIFF |
Each value is explained below.
■INITIALIZE (JOBFLG = 2)
The first call to a TYRSUB always has JOBFLG=init=1. TYRSUB opens and reads any files necessary to process the tire data before the actual simulation begins.
■RESET (JOBFLG = 3)
The TYRSUB is called with JOBFLG=reset=3 after the first initialization while IFLAG=true. You can ignore reset mode in Adams Tire. This deviates from the TYDEX STI definition stating that the tire parameters array may have changed.
■END SIMULATION (JOBFLG = endsim = 99)
The TYRSUB is called with JOBFLG=endsim=99 just before Adams Solver is excited. The TYRSUB should close any open files and free any memory allocated. Message handling is not available at this point during execution. Therefore, calls to
ERRMES or
USRMES do not function.
■NORMAL EVALUATION (JOBFLG =normal = 0)
When called with JOBFLG = normal = 0, TYRSUB returns the tire forces and torques based on the inputs.
■DERIVATIVE EVALUATION
(JOBFLG = diff = 5)
When called with JOBFLG = diff = 5, TYRSUB should return tire forces and torques based on the inputs. Adams Solver uses the returned value to estimate the partial derivatives of the forces and torques with respect to the inputs.
IDTYRE
An integer variable that provides the ID of the GFORCE statement that applies the tire forces and moments to the wheel.
TIME
A double-precision variable that provides the current simulation time.
DIS
A double-precision array of dimension three, which specifies the values of the wheel carrier translational displacement (x, y, z) at the wheel center with respect to the road reference marker expressed in the road reference marker's axis system in units of meters.
TRAMAT
A double-precision array of dimension 3 x 3, which specifies a transformation matrix used to transform data from the wheel carrier axis system to the road reference marker axis system.
ANGTWC
A double-precision variable, which specifies the rotational angle of the wheel with respect to the wheel carrier in radian.
VEL
A double-precision array of dimension three, which specifies the values of the wheel carrier translational velocities (x, y, z) at the wheel center with respect to the road reference marker expressed in the wheel carrier (ISO-C) axis system in units of meters/second.
OMEGA
A double-precision array of dimension three, which specifies the wheel carrier angular velocity at the wheel center with respect to the road reference marker expressed in the wheel carrier (ISO-C) axis system in units of radian/second.
OMEGAR
A double-precision variable that specifies the value of the rotational speed of the rim with respect to the wheel carrier about the wheel's (rim's) spin axis in radian/second.
NDEQVR
An integer variable the dimension of DEQVAR, default is two, which means that Adams Tire supports tire models using two differential equations.
The number of states can be set by adding N_TIRE_STATES in the [MODEL] section of the tire property file:
[MODEL]
N_TIRE_STATES = <number of required stated>
DEQVAR
A double-precision array that provides the values of the differential equations associated with the tire. Note that to determine the values in the DEQVAR array, Adams Tire integrates the derivatives that the tire model returns in the DEQDER array.
NTYPAR
An integer variable that represents the dimension of the tire parameters array (TYPARR). If NTYPAR equals zero, TYPARR contains no values.
TYPARR
The tire parameters array. A double-precision array of dimension NTYPAR that contains the values of the tire model parameters. If the PROPERTY_FILE_FORMATin the tire property file is set to 'USER', NTYPAR is set to zero and the tire property file name is passed to the STI in the CHTDSTstring. The maximum size of TYPARR is 300.
NCHTDS
An integer variable that gives the number of characters in the tire property file name (CHTDST).
CHTDST
The tire property file name. A character variable of length 256 that provides the tire property file name and path (for example: "/usr/people/cjones/tire.tpf ").
ROAD
The external symbol name that provides the road contact subroutine that TYRSUB calls to determine the local road normal and tire-road contact point.
IDROAD
An integer that specifies the branch flag for the road contact model method. The value is set according to the contents of the road property file (.rdf). The values in the range 900 until and including 920 are reserved by the current Adams Tire internal road code.
For more information, see
Creating Road Models (STI).
NROPAR
An integer variable that gives the dimension of ROPAR. If NROPAR equals zero, ROPAR contains no values.
ROPAR
The road parameters array. A double-precision array of dimension NROPAR, which contains the values of the road contact model parameters. If the method is set to 'USER' in the [MODEL] block of the road property file, then NROPAR is set to zero, and the road property file name is passed to the STI in character variable CHRDST. For more information, see
Creating Road Models (STI).
NCHRDS
An integer variable that provides the number of characters (length) of the road property file name.
CHRDST
The road property file name. A character variable of length 256 that holds the road property file name and path, for example: /usr/people/cjones/road.dat.
FORCE
The tire force vector. A double-precision array of dimension three, that TYRSUB outputs. It provides tire forces at the wheel center in Newtons expressed in the TYDEX-C (ISO-C) axis system.
TORQUE
The tire moment vector. A double-precision array of dimension three that the TYRSUB outputs. It provides the tire moments at the wheel center in Newton-Meters expressed in the TYDEX-C (ISO-C) axis system.
DEQINI
A double-precision array of dimension NDEQVR. It specifies the initial values of the differential equations (DEQVAR) associated with the tire. When JOBFLG = inquire = 1, TYRSUB returns the initial values of the differential equations. For other values of JOBFLG, the values returned in DEQINI are ignored. Currently, Adams Tire does not use values returned in DEQINI. The initial values of differential equations are always set to zero.
DEQDER
A double-precision array of dimension NDEQVR. It provides the time derivative of the differential equations (DEQVAR) associated with the tire. When JOBFLG = normal = 0 or JOBFLG = diff = 5, TRYSUB must return values for DEQDER. For other values of JOBFLG, any values returned in DEQINI are ignored.
TYRMOD
A character variable of length 256 containing a descriptive error message. Adams Tire outputs the message to the screen and message file (.msg) when the value of IERR is not equal to zero.
NVARS
An integer parameter giving the maximum size, currently 40, of the VARINF array. A TYRSUB must not assign a value to NVARS.
VARINF
The tire-variable information array. A double-precision array of dimension NVARS for outputting information, such as tire contact patch forces and slip angle, which the simulation does not use directly. TYDEX STI specifies that the first six values of the VARINF array should hold the contact patch forces and moments in the TYDEX-H (ISO-W) axis system.
NWORK
An integer parameter giving the dimension of the working array (WRKARR), currently one. A TYRSUB must not assign a value to NWORK.
WRKARR
The working array. A static double-precision array of dimension NWORK the tire model may use as desired. Currently, the working array is limited to a dimension of one. Adams Tire stores these values for each tire between calls to TYRSUB.
NIWORK
An integer parameter giving the dimension of the integer working array (IWRKAR), currently one. A TYRSUB must not assign a value to NIWORK. As specified in TYDEX STI, when Adams Tire adds support for the JOBFLG = inquire = 1, TYRSUB can return the actual dimension of IWRKAR using NIWORK.
IWRKAR
The integer working array. A static integer array of dimension NIWORK, which is currently limited to one, that TYRSUB can use as needed. Adams Tire stores these values for each tire between calls to the TYRSUB.
IERR
The integer variable giving an error value. Valid values are:
■0 No error
■1 Warning: Calling program should print message contained in TYRMOD
■2 Error: Calling program must not use the outputs
■3 Fatal Error: Calling program should stop execution.