Starting a new SmartAHS project

In this section it is explained how to create a new project. A step-by-step description follows
the creation of a new sample project.

SmartAHS directory structure

To install the SmartAHS library follow these steps:

1 - Go to the main SmartAHS directory (the one where you unpacked).
2 - Run the command 'configure' (if '.' - dot - is not in your path, run ' ./configure');
       this will check a few things and set up the environment for your work.
      Normally, 'configure' will set up '/usr/local' as the installation directory.
      You can override this behavior by using the '--prefix' command line switch to 'configure',
       as in

$ configure --prefix=$HOME/my-smartahs-dir

3 - Run 'make install'.

The SmartAHS framework is now installed.

The core set of the SmartAHS building blocks is contained within the following directory structure

smart-ahs directory contains SmartAHS libraries written in SHIFT programming language. A detailed description of these libraries is provided in the AHS Model Description section.
smart-ahs-data directory contains data set files to be used by SmartAHS libraries. Those files should not be modified.
c-src directory contains a set of external routines written in C language. These routines provide additional functions not available in SHIFT (e.g. numerical routines).
include directory contains various "include" files used by both SHIFT and C source files.
lib library files (usually *.a format under UNIX).
doc extended documentation of SmartAHS.
misc a few sample models which can be taken as examples for program development.
man UNIX style manual pages.

The files contained herein are provided by the SmartAHS development team at PATH and should not
be modified by the user.

Highway configuration

The highway topology might be an important feature of the simulation being constructed.
While it is possible to write the SHIFT code for a highway manually, you are advised not to do so.
Instead, you should prepare a Smart PATH compliant highway description (Smart PATH is a different
modeling tool built at PATH). The Smart PATH highway description scheme is very easy to understand
and to use. The next step is to use the Highway Compiler, called hwyc, which will produce the SHIFT
code for you. A detailed description of hwyc and a Smart PATH highway representation is available.

Let us create a highway specification as follows:

SECTION HIGHWAY

LANEWIDTH 4

HIGHWAY SEC1
LANE 1
GEOMETRY LINE 300

HIGHWAY SEC2
LANE 1
GEOMETRY ARC 100 500 L
GEOMETRY ARC 100 500 R

HIGHWAY SEC3
LANE 1
GEOMETRY LINE 100

PIN SEC1 0 0 0 0

CONNECT SEC1 (1 1) SEC2 (1 1)
CONNECT SEC2 (1 1) SEC3 (1 1)

Save it in a file myroad.inp. Note that hwyc requires an *.inp sufix for an input file. Compile the file:

%> hwyc myroad.inp The file myroad.out will be created. Copy or move this file to myroad.hs. This file should be included into
your main file:

#include "myroad.hs"

The weather description generated by default is a sunny condition with
excellent visibility. The weather conditions could be edited manually for
different parts of the road.

Origin-Destination Specification

In order to populate the road specified above with instances of vehicles the source and sink types
should be used to specify the Origin-Destination patterns. Here is an example (file od.hs):

global Sink sink1 := create(Sink, exitSpeed := 10,

lane := _sec3_l1, // lane name

availableSpace := 100,

maxAvailableSpace := 100);

global Source source1 := create(Source,
                                gxp := 0,
                                gyp := 2,
                                gzp := 0,
                                section := sec1,        // original section name
                                segment := _sec1_sg1,   // derived segment name
                                lane := _sec1_l1,       // derived lane name
                                rxp := 0,
                                ryp := 2,
                                rzp := 0,
                                lyp := 0,
                                vgam11 := 1,
                                vgam12 := 0,
                                vgam13 := 0,
                                vgam21 := 0,
                                vgam22 := 1,
                                vgam23 := 0,
                                vgam31 := 0,
                                vgam32 := 0,
                                vgam33 := 1,
                                sink := sink1,
                                vehiclesToCreate := 10,
                                duration := 0,
                                period := 1);

Note how the exact location of an arbitrary source and sink is specified. For the source type variable
the section, segment and lane name should be specified. For the sink type the lane name should be given.
The hwyc compiler creates the derivative names for the segments and lanes within a given section.
It does so by expanding the <the_section> name in the following manner:

_<the_section>_sg<number>

_<the_section>_l<number>

where <number> is the number of the segment or of the lane respectively.

The file od.hs should be included into your main file:

#include "od.hs"

A detailed description of the sink and source types is provided in the AHS Model Description section.
The road is populated by the instances of vehicles of vehicle type by default. It is advised to
copy the sink and source files from the SmartAHS directory structure to your project directory
for a modification if necessary (e.g. to populate with your vehicle type, derived from vehicle type).

Controller Implementation.

Controller implementation is the most serious step in constructing your simulation. At this time detailed
models of a passenger vehicle dynamics are provided in SmartAHS. this library will be extended by heavy
truck models in the future. The part which represents the driver is the actual control module which gets some
predefined inputs (e.g. visual and motion feedbacks) and outputs the values for steering, accelerator and
braking into the vehicle dynamics module.
These building blocks could be borrowed from the SmartAHS library, or designed by a third party for
a particular scenario. It is advised to follow the outline of the Standard Project while creating your own simulation.
The VREP module is the only link between the vehicle and the road. Its interface should be understood and
closely followed (see AHS Model Description).

You should create a file myvehicle.hs - it will contain the type description for your vehicle:

type StandardProjectVehicle : Vehicle

{

// specify your inputs here

input continuous number desired_speed, desired_acceleration, . . .

           // specify the vehicle model and controller
output VehicleDynamics vehicle_dynamics;
         VehicleDynamics_2D vd2d;
         Controller controller;
         HDM_engine_controller human_tsb_controller;

          . . . . .

          // attach to a particular source / sink
         Source source;
         Sink   sink;

// link the vehicle to the road
VREP vrep;

          // vehicle parameters
         continuous number gxp, gyp, gzp;
         continuous number xDot, yDot, zDot;
         continuous number xDDot, yDDot, zDDot;
         continuous number heading, pitch, roll;
         number length, width;

. . . . . .

In the setup clause of this type the controllers and VREP components of your vehicle should be initialized.
The connect clause of the setup establishes the connection between the controller and the vehicle dynamics
modules.

setup

// initialize vehicle dynamics, controller and VREP

define

{

VehicleDynamics_2D tvehicle_dynamics := create(VehicleDynamics_2D,

parameters := hybridcar,

Ics := init_conditions);

Controller tcontroller := create (HDM_engine_controller,
vehicle := self);

        VREP tvrep := create(VREP,
                              rzp := rzp(source),
                             lyp := lyp(source),
                             vgam11 := vgam11(source),
                               . . . .
                             vehicle := self);

Trajectory ttraj := create(Trajectory, v := self);
}

        // assign the above created instances to the state variables
     do
      {
        vehicle_dynamics := tvehicle_dynamics;
        controller := tcontroller;
        vrep := tvrep;
        traj := ttraj;
      }

      // establish the connections between modules
    connect
   {
          // link the position/velocity of the vehicle to the VREP
        xDot(tvrep) <- xDot(tvehicle_dynamics);
          . . . .
        followLane(tvrep) <- followLane(tcontroller);

          // link the control lines
        throttle(tvehicle_dynamics) <- throttle(tcontroller);
        brake(tvehicle_dynamics) <- brake(tcontroller)
        steering(tvehicle_dynamics) <- steering(tcontroller);
          . . . .

          // additional connections required by the model
        rxp(tcontroller) <- rxp(tvrep);
        lyp(tcontroller) <- lyp(tvrep);
           . . . .
        section(tcontroller) <- section(tvrep);
        lane(tcontroller) <- lane(tvrep);
        segment(tcontroller) <- segment(tvrep);
            . . . .
        desired_speed(tcontroller) <- desired_speed;
        range(tcontroller) <- range;
        range_rate(tcontroller) <- range_rate;
            . . . .

If you are using the Smart-AHS modules make sure all the supporting files are included into your main file.

Monitors.

Monitor types could be added to the simulation in order to provide a convenient way to gather, aggregate and otherwise process the simulation data. Alternatively, vehicle parameters could be direct output for each vehicle instance. However, on the roadway part it is virtually impossible to gather useful data (e.g traffic flow parameters) without introducing the monitors. A traffic flow monitor is provided as an example below:

type FlowChecker {

input
/** Starting section */
Section section;

/** Cell number */
number cellN;

/** Sampling time */
timer sample_timer;

state
set(Vehicle) cell;

/** Vehicles which passed the flow check point */
set(Vehicle) passedVehicles := {};

    /** Vehicles which passed the flow check point in the last timer
     * click and wich didn't leave the cell yet
     */
    set(Vehicle) oldPassedVehicles := {};
    continuous number period := 0;
    number vehCount := 0;

output
/** The flow is calculated at the entrance of the cell */
number vehFlow;

setup
    do {
      cell := cells(section)[cellN];
    };

flow
    default {
      period' = 1;
    };

discrete
s;

transition
    /** This happens when a new vehicle enters the cell */
    s -> s {} when exists v in cell :
      not (v in passedVehicles) and (not (v in oldPassedVehicles))
    do {
      passedVehicles +:= v;
      vehCount +:= 1;
    },

    /** This calculates the flow */
    s -> s {sample_timer:timer_tick}
    do {
      vehFlow := if vehCount > 0
        then
          period / vehCount
        else
          0;
      oldPassedVehicles := {v : v in passedVehicles, v in cell};
      passedVehicles := {};
      period := 0;
      vehCount := 0;
    };
}

Data Processing.

The easiest way to collect data from your simulation is to run the simulation in the batch mode, preferrably from a UNIX script, and to dump the data to a file using the SHIFT tty-debugger commands. The resulting files could be further processed using the usual UNIX script programming techniques, including PERL, AWK, GREP, SED, etc.