Creating Road Models (STI)
You create a road model by writing a road evaluation function that tire models call to determine tire-road contact points, local road normal, and coefficient of friction. Learn about:
Instructing Adams Tire to Use Your Road Function
Similar to the methods for the user tire models, there are also two methods to instruct Adams Tire to call your user road model:
User Tire library plug-in method
Adams Tire is able to load an Adams user library containing the user tire and road code based on the instructions in the road property file:
[MODEL]
METHOD ='USER'
FUNCTION_NAME ='<roaduserlibname>::<arcsub>'
Note: | The keyword METHOD is not identical to the keyword in a tire property file. |
The <roaduserlibname> can include a path, while the <arcsub> can be any name, but the argument list should be fulfilling the requirements as stated in
Road Function Subroutine Calling Sequence.
Compiling and building the user library can be done with the Adams script in the command window:
■For Linux and Linux platforms:
adams2024_1 -c cr-user ..
■For windows platforms:
adams2024_1 cr-user ..
For example:
When the user road code is stored in the file arc501.f and the road calling function is called ARC501, the [MODEL] block of the road property file could read:
[MODEL]
PROPERTY_FILE_FORMAT = 'USER'
FUNCTION_NAME = 'userroad::ARC501'
In that case the building of the user library for the user road code can be done with (Windows):
adams2024_1 cr-user n arc501.f -n userroad.dll exit
Running the model (that is, model.acf) can be done in the standard way (Windows):
adams2024_1 ru-standard model.acf
or
adams2024_1 acar ru-solver model.acf
Adams User library method
When linking your road model against the solver, you instruct Adams Tire to call your user road model by defining a road property file that specifies the method in the following way:
[MODEL]
METHOD = 'USER'
FUNCTION_NAME = '<arcsub>'
Compiling and building an Adams Car or Adams Solver user library can be done with the Adams script in the command window:
■For Linux and Linux platforms:
adams2024_1 -c cr-user ..
■For windows platforms:
adams2024_1 cr-user ..
For example:
When the user road code is stored in the file arc501.f and the calling function is ARC501, then the [MODEL] block of the road property file could read:
[MODEL]
METHOD = 'USER'
FUNCTION_NAME = 'ARC501'
Then the user library for the road code can be created with (Windows):
adams2024_1 cr-user y arc501.f -n mysol.dll exit
Simulating the model (that is, model.acf) can be done with (Windows):
adams2024_1 ru-user mysol.dll model.acf exit
Tasks Your Road Function Must Perform
All road functions must perform these tasks:
1. Read any data it requires from the road property file.
2. Calculate the tire-road contact point, local road normal, and road coefficient of friction.
3. Handle errors. For example, report when needed data is missing from the road property file.
The value integer argument JOBFLG governs how and when your ARCSUB performs these tasks. The skeletal road function example, shown next, shows which tasks the road function performs based on JOBFLG. The arguments and their declarations are omitted here for brevity. For information on the ARCSUB arguments, see
Road Function Input Arguments.
Skeletal Road Function Example
SUBROUTINE ARC501(....)
include 'ac_sti_jobflg.inc'
IF ( JOBFLG .EQ. INIT .OR.
. JOBFLG .EQ. RESET ) THEN
c Read Road Property File
ENDIF
IF ( JOBFLG .EQ. NORMAL .OR.
. JOBFLG .EQ. DIFF ) THEN
c Calculate Tire-Road Contact Point, Road Normal, and
c Coefficient of Friction.
ENDIF
c Handle Errors
RETURN
END
Road Function Subroutine Calling Sequence
SUBROUTINE ARC501(JOBFLG, IDTYRE,
& TIME, DIS, TRAMAT,
& IDROAD, NROPAR, ROPAR, NCHRDS, CHRDST,
& NSHAPE, SHAPE, UNLDRD, WIDTH,
& NROAD, EFFVOL, EFFPEN, RCP,
& RNORM, SURFAC, IERR, ERRMSG )
Road Function Input Arguments
The input arguments are explained below in calling sequence order:
JOBFLG
An integer variable that contains the value of the initialization flag. JOBFLG takes the value:
■0 - Normal mode
■1 - Subroutine must return the actual dimensions of NTYPAR, NDEQVR, NVARS, NIWORK, NWORK(Not used in Adams Tire)
■2 - First initialization
■3 - Re-initialization during simulation
■4 - Successful step (not used in Adams Tire)
■5 - Adams Solver is differencing (unique to Adams Tire)
■99 - Final simulation step (not used in Adams Tire)
IDTYRE
An ID of the GFORCE statement that applies the tire forces and moments to the wheel.
TIME
A double-precision variable that contains the value of the current simulation time.
DIS
A double-precision array of dimension 3, which specifies the values of the wheel carrier translational displacement (x, y, z) at the wheel center with respect to the road reference marker.
TRAMAT
A double-precision array of dimension 3 x 3, which specifies a transformation matrix used to transform data from the wheel carrier coordinate system to the coordinate system of the road reference marker.
IDROAD
An integer that specifies the road model method (for example, 900 for ARC900).
NROPAR
An integer variable that represents the dimension of ROPAR. If NROPAR is equal to zero, ROPAR contains no available values.
ROPAR
A double-precision array of dimension NROPAR, which contains the values of the road model parameters. If [MODEL] -> METHOD in the road property file is set to 'USER', NROPAR is set to zero and the road property file name is passed to the STI in the CHRDST string.
NCHRDS
An integer that represents the dimension of CHRDST.
CHRDST
A character string of dimension NCHRDS, which contains the name of the road property file. The CHRDST string contains the full path of the file up to a maximum of 256 characters.
NSHAPE
An integer that represents the dimension of SHAPE. If NSHAPE = 0, then the cross section defaults to a cylindrical shape.
SHAPE
A double-precision array of dimension (2,NSHAPE) representing the shape of the tire carcass cross-section:
■1 = Radius [%]
■2 = Width [%]
Legal values for radius and length are:
■1.0 ≤ Radius ≤ 0.0
■0.0 ≤ Width ≤ 1.0
For example, the following shows how data is stored in the SHAPE array:
Shape (1) = First
fractional radius
Shape (2) = First
fractional width
Shape (3) = Second
fractional radius
Shape (4) = Second
fractional radius
NSHAPE
An integer that represents the dimension of SHAPE. If NSHAPE = 0, then the cross section defaults to a cylindrical shape.
SHAPE
A double-precision array of dimension (2,NSHAPE) representing the shape of the tire carcass cross-section:
■1 = Radius [%]
■2 = Width [%]
Legal values for radius and length are:
■1.0 ≤ Radius ≤ 0.0
■0.0 ≤ Width ≤ 1.0
UNLDRD
A double-precision variable that specifies the unloaded radius.
WIDTH
A double-precision variable that specifies the total width of the tire.
Road Function Output Arguments
The output arguments are listed below in calling sequence order:
NROAD
An integer value that is used to define the surface type. NROAD takes the following values:
■0 - No road data
■1 - In contact with the road
EFFVOL
A double-precision variable that contains the value of the effective penetrated volume between the tire carcass and the road.
EFFPEN
A double-precision variable that contains the value of the effective penetration between the tire carcass and the road.
RCP
A double-precision array of dimension three, which contains the values of the contact point location relative to the road reference marker.
RNORM
A double-precision array of dimension three, which contains the road normal vector. This vector is directed out (upward) from the road surface.
SURFAC
A double-precision variable that contains the value of the average surface friction.
IERR
An integer variable giving the error status of the road contact subroutine. IERR takes the following values:
■0 = No error
■1 = Warning
■2 = Error - Do not use the results
■3 = Fatal Error
ERRMSG
A character string of dimension 80 that contains descriptive error messaging that is passed to the main tire calling routine through TYRMOD.
Note: | Inside the road model, STOP statements are not allowed. |