User-Defined Road Models

If the road data file has a file extension of urm, COSIN/road assumes a road evaluation routine was provided and compiled into a dynamically loadable library named:

urm.dll in Windows
liburm.so or liburm.sl in LINUX and UNIX, respectively

This library is searched for, according to the rules set by the respective operating system. To ensure this library is made available, place it into the working directory from which COSIN/road and its calling solver is invoked.

The library must contain a C or C++ function with the following prototype:

extern void urm (int ti, double t, double x, double y, double*z, double*vx, double*vy, double*vz, double*mu, int*ier, char*file);

The sole task of this routine is to provide:

Road height z
Road surface velocities v_x, v_y, v_z
Friction modification factor

All being functions of:

Time t
Location x, y

COSIN/road passes to this routine the name of the data file, with the extension urm as mentioned above, which is read and interpreted under the sole responsibility of the user-defined road model.

The meaning of the invocation parameters is as follows:

Parameter	C/C++ type	Data flow	Unit	Meaning
`ti`	`int`	in	-	Wheel index. Typically: 1 fl 2 fl 3 rl 4 rr , ..
`t`	`double`	in	s	Simulation time, provided by COSIN/road.
`x`	`double`	in	m	x comp. of location where road height is needed; provided by COSIN/road.
`y`	`double`	in	m	y comp. of location where road height is needed; provided by COSIN/road.
`z`	`double*`	out	m	Road height.
`vx`	`double*`	out	m/s	x comp. of road surface velocity relative to global coordinate system (non-zero, for example, in drum or flatbelt simulations).
`vy`	`double*`	out	m/s	y comp. of road surface velocity relative to global coordinate system.
`vz`	`double*`	out	m/s	z comp. of road surface velocity relative to global coordinate system (non-zero, for example, in hydraulic 4-poster simulations).
`mu`	`double*`	out	-	Friction characteristic modification factor (value is typically 1.0, which means no modification of the friction characteristic as defined by the tire model).
`ier`	`int*`	out	-	Error code, must be 0 if road evaluation (or file opening and reading) is successful, any value other than 0 else.
`file`	`char*`	in	string	Name of road data file (provided by COSIN/road). May or may not contain the path; the exact interpretation of the string is according to the rules of the respective operating system. The user routine decides when this file is to be opened and read. The name is provided in each call to `urm`. However, typically, it only needs to be read during the first call of `urm` with the respective wheel index. `urm` might have to save the information in the file in local, static variables.

Below, is a listing of a most simple example of such a C function. The code (urm.c) is contained in the sub folder sdk of the FTire/lib download:

/* place-holder for user-defined road model (URM) */

#include <stdio.h>

extern void urm (int ti, double t, double x, double y,
                 double*z, double*vx, double*vy, double*vz, double*mu, int*ier, char*file) {

  static int first=1;

  if (first) {
    printf("\nthis is the demo user road model, using data file %s..\n",file);
    first=0;
  }

  /* terminate road model */
  if (t>=0.9e60) {
    return;
  }

  *z=0.0;
  if (x>1.0 && x<1.2) *z=0.02;
  *vx=0.0;
  *vy=0.0;
  *vz=0.0;
  *mu=1.0;
  *ier=0;
}

In Windows, provided the Microsoft™ C/C++ compilers are installed, this function can be compiled and linked into a dynamical link library with the batch file makeum.bat, also contained in the sub folder sdk of the FTire/lib download. The file assumes the installation location of the compiler is contained in the respective search paths. This is true for regular installations.