SSAM 2.1.6 Release Notes

The Surrogate Safety Assessment Model (SSAM) software has been recently updated, and the most recent version may be obtained by visiting and clicking on the download registration link.

The SSAM software has been distributed (free of charge) to the public beginning in 2007. Since that initial release (SSAM Version 2.0), minor features have been added, and a number of issues reported by users have been resolved in subsequent versions. These changes are described in sections organized as follows:

New Features in SSAM 2.1.6

New features in SSAM, from the perspective of version 2.1.5 users, are as follows:

The Map View in SSAM displays conflict locations on a map, and clicking on a conflict produces a pop-up window with detailed information about the
conflict, as shown in the following screenshot. This dialog visualizes the trajectory of the two conflicting vehicles and provides the values of various
surrogate safety measures. A bug is revealed in this screenshot is that the MaxS value is labeled in ft/sec units, whereas the underlying TRJ file was
using metric, not English units. This issue has been corrected in SSAM 2.1.6, such that the units for MaxS will be properly displayed as m/sec
when using metric units.

Analysts have recently begun to use SSAM to analyze VISSIM simulations with pedestrians, and have noted that SSAM identifies vehicle-to-pedestrian
conflicts and pedestrian-to-pedestrian conflicts. PTV (producer of VISSIM) has stated that all traffic (vehicles, pedestrians, buses, bicycles, etc.) will
appear in the TRJ file that is used by SSAM. Thus, conflicts between these entities can be identified by SSAM. We note that SSAM was not explicitly designed
and has not been explicitly validated for pedestrian-conflict analysis. Pedestrians tend to change trajectory speed-wise and laterally much more
erratically than vehicles. As such, we feel the pedestrian-pedestrian conflicts should be filtered out of the conflict results, although
vehicle-to-pedestrian conflicts may be credible and useful (we have not validated this hypothesis). There is no "vehicle" or entity type
available in the TRJ file format by which to identify pedestrians and thus filter them out. In general, pedestrians have length and width of less
than 1 m; however, SSAM does not support filtering based on "vehicle" length. The most practical course is to filter out any conflict where MaxS
< 5 mph (7.3 ft/sec) (which is beyond the natural walking pace of pedestrians). This technique would effectively eliminate virtually all
pedestrian-pedestrian conflicts (unless running pedestrians are simulated), but not pedestrian-vehicle conflicts. An interesting issue was reported
where SSAM aborted the analysis of a TRJ file due to an incredibly unrealistic value it obtained. This occurred in the context of a pedestrian-pedestrian
conflict, where one pedestrian in VISSIM had a deceleration rate of -1838 ft/sec2 (or -1253 mph/sec). This is clearly an invalid value; however, it
only occurred in one of a very large number of simulations with the same model. We have extended the range of values that SSAM will tolerate before aborting
analysis to a very wide range of -9999 units to +9999 units on all surrogate measures on the Filter tab. Thus, SSAM will no longer "abort" in
such scenarios; however, it is now necessary to apply care to set filters to reasonable minimum and maximum limits, to eliminate unrealistic conflict events
from the results.

When analysis of a trajectory file by SSAM yields no conflicts, prior versions of SSAM provided "abort" and "error" messages
which, without further insight, would imply that the software failed in some way. And, to some extent, it did fail. After a "no conflict" scenario
where SSAM issued its error messages, the Configuration tab stopped working properly in the following way. If the user attempted to Analyze the case again
(perhaps to enabled CSV output of the TRJ file), the Analyze button was not enabled to be pressed. If the user pressed Edit to change the
configuration, the Apply button would not work. Thus, the case became unusable. This has been corrected in Version 2.1.6, such that if no
conflicts are found in course of the analysis, SSAM will now indicate, "No conflicts found." The summary tab will now indicate, "No
conflicts available." The Edit, Apply, and Analyze buttons on the Configuration tab will still work properly after a "no conflict" analysis
result. However, this will only work properly for new cases created with version 2.1.6.Cases from version 2.1.5 and earlier, that were saved to disk,
with still exhibit the faulty behavior. Delete such old cases, and create a new case in version 2.1.6 to overcome the problem.

Many users have requested a sample simulation model and/or trajectory file in order to more easily get familiar with the features of SSAM, so in
determining whether they want to use SSAM, they can initially bypass the additional effort of obtaining compatible simulation software and configuring it to
output trajectory files. We are thus now providing sample files—a VISSIM input (.INP) file and corresponding trajectory (.TRJ) file—on the
SSAM web page that users can download to process with SSAM, and see the analysis results, surrogate measures, and map view features of SSAM.

New Features in SSAM 2.1.5

New features in SSAM, from the perspective of version 2.1.4 users, are as follows:

The Map View in SSAM allows input (.INP) files from VISSIM to be imported, to render a network map that displays icons where conflicts have occurred.
VISSIM has recently released version 5.10, which incorporates slight modification to their input file format. Users of SSAM version 2.1.4 will receive the
error message: "Links information is not available," when important .INP files from versions of VISSIM later than 5.00. SSAM version 2.1.5 has
been updated to resolve this issue.

New Features in SSAM 2.1.4

New features in SSAM, from the perspective of version 2.0 users, are as follows:

The Map View allows conflict icons to be chosen from wider selection of shapes, including crosses (e.g., plus symbol and X symbol) and unfilled shapes
(e.g., unfilled circles, squares, triangles, and diamonds) that allow easier discrimination of locations on the map view where clusters of several conflicts
are occurring. These symbols are "more informative" relative to the looking at a series of solid (filled-in) squares all in the same lane, which
would tend to appear as one large solid mass.

The Map View allows users to select icon colors from a full spectrum of colors.

The Map View allows conflicts icons on the map to be color coded by conflict type (crossing, lane-change, or rear-end).

The Map View allows conflict icons on the map be rescaled incrementally larger or smaller, independently of the map zoom level.

The Configuration tab allows users to override default angle thresholds used to classify conflict by type (crossing, lane-change, or rear-end).

The maximum permitted analysis area has been increased from 100 square miles to 500 square miles, though there is no guarantee that analysis of
such large networks will be successful.

The Analysis Progress window displayed while SSAM is analyzing TRJ files has been updated as shown below indicate the ratio of used memory to
maximum memory available to SSAM. In this analysis of extremely large files, SSAM may exhaust available resources and fail to complete analysis. The used
memory indicator may provide useful feedback in this scenario.

The Help has been updated to reflect recent modifications.

The About screen has been updated to incorporate an FHWA Terms of Use and Disclaimer.

Resolved Issues

When loading .INP files over 600 KB, SSAM reported an out of heap space error while attempting to generate a map image. This was resolved
in version 2.1.3.

When zooming in on the Map View, the map was re-centering to the middle of the map instead to the middle of the current view area. This was resolved
in version 2.1.3.

The imported map image or image corresponding to an imported .INP file failed to display in the Map View. This was resolved in version 2.1.3.

Fixed an incompatibility issue with VISSIM .INP files, posed in some cases by .INP files from VISSIM versions later than 5.0. This was resolved in
version 2.1.5.

Fixed erroneous display of MaxS value in English units when metric units were appropriate. This bug appeared on the detailed information pop-up window,
accessible by clicking conflict icons on the Map View.

SSAM aborted analysis when the filtering mechanism encountered unrealistic values for surrogate measures. Revised the range of values accepted by the
filter to -9999 to +9999 units for all units, which is an exceedingly forgiving range, to prevent the analysis from aborting.

After a "no conflicts" analysis result, the Apply and Analyze buttons on the Configuration tab did not work properly. This now works
properly for cases created with version 2.1.6, but will not overcome issues with saved problem cases from earlier versions. Delete and older problem cases
and create a new case to overcome the issue.

Known Issues

The following list of known issues may affect use of SSAM version 2.1.6 (and earlier versions):

Software Limitation: SSAM is not cognizant of grade separations in the roadway/rail network, and thus a vehicle on an overpass may
be identified as conflicting with a vehicle on an underpass, which is not truly a valid conflict. The TRJ file does not have a vertical (Z) dimension.
Workaround: One approach is to remove overpasses or underpasses from the network if they are not essential to the analysis. Another workaround
is to filter out underpass and overpass links with the Filter tool. That would remove all conflicts associated with these
links—not just the invalid conflicts between a vehicle on the overpass and a vehicle on the underpass. Another option is to export the conflict table
to a CSV file and manually filter out conflicts between overpass links and underpass links. However, once the data has been exported, the built in Map View,
Filter and t-test tools in SSAM are no longer applicable.

Software Limitation: SSAM was initially designed from the perspective of conducting comparative analysis of single intersection or
interchange traffic facilities. However, users have also applied SSAM to very large scale models, spanning over 100 square miles, including 20 miles of
interstate freeway and adjacent freeway interchange or tolling facilities. It has been empirically determined that SSAM seems to run out of memory and fail
analysis (generally in a silent and uninformative "hanging" manner) when analyzing files in excess of 30GB, though it has reportedly successfully
processed a 30GB trajectory file. Workaround: It is possible to manually increase the memory available to SSAM, such that if might be able
to processor slightly larger models. See the (following) FAQ for the procedure.

Usage Issue: The VISSIM simulation has been capable of producing TRJ output files for SSAM analysis since version 4.1. VISSIM also
allows users to choose between metric units (e.g., meters and kilometers per hour) and English (Imperial) units (e.g., feet and miles per hour) for input or
display purposes within the VISSIM software. However, VISSIM only outputs TRJ files in metric units, regardless of what units are selecting in VISSIM for
input or display purposes. SSAM can display data in English or metric units; however, this setting is not user-selectable. SSAM displays data using the
system of units specified within the TRJ file. Thus, it is often perceived to be a bug in SSAM that it does not display English units, when English units
have been specified in VISSIM. This is not a bug, as VISSIM only produces TRJ files in metric units, or at least in all versions of VISSIM tested to date,
which include versions 4.1 through 5.0. PTV verified that VISSIM 4.30-05 and prior will produce erroneous TRJ files if non-metric units are specified in
VISSIM. Workaround: Users should use all metric units or upgrade VISSIM to version 5.00-08 or later.

Usage Issue: This issue is related to the previous VISSIM note. The use of non-metric units with in the VISSIM input file may produce
a side effect pertaining to the VISSIM input (.INP) file import feature on the Map View in SSAM. Regardless of the input file units in VISSIM, the resulting
TRJ files are in metric units. If the .INP file uses different units, then the location of conflicts determined by SSAM (using metric X-Y coordinates) may
not be compatible with the non-metric link coordinates imported from the VISSIM input file, and thus the conflict icons on the Map View may not matchup
properly with the corresponding roadway map, drawn based on the imported .INP file. Workaround: If using versions of VISSIM prior to 5.x,
then (as mentioned in the previous issue) ensure that all units in VISSIM are specified in metric units. One user reported this same issue with version
5.00-01 of VISSIM, and alleged that it occurred whether using metric or English units. We have verified that the conflicts and roadway match up properly on
the Map View for VISSIM 5.00-08, regardless of the units used in VISSIM. We suggest upgrading VISSIM to that version or a later version to overcome the Map
View mismatch issue.

Unreplicated Issue: One user has reported that the SSAM InstallShield application launches every time SSAM is launched. No other
users have reported this issue, and The contractor has been unable to replicate this problem.

Legacy Bug: Saved cases from SSAM 2.1.5 or earlier which found no conflicts may exhibit problems with the Apply and Analyze button
on the Configuration tab, potentially making reconfiguration and reanalysis impossible. Workaround: Upgrade to SSAM 2.1.6 and create a new
case with the same configuration, and it should not have any issues. Old cases exhibiting these issues that have been saved with version 2.1.5 or prior may
still exhibit issues, even when loaded into a newer version of SSAM (2.1.6). Discard the old cases, and create a new case with the same configuration in 2.1.6
to overcome the issue.

SSAM Frequently Asked Questions (FAQ)

The following questions have been asked by multiple users, and responses are listed here for convenience:

Can CORSIM be used with SSAM?
No, CORSIM does not output the proper TRJ files required by SSAM, and the time resolution and physical vehicle location in the intersection are not modeled with adequate resolution in CORSIM to provide a valid basis for conflict analysis. We did write a run-time extension (RTE) for CORSIM to produce TRJ files for crude testing purposes; however, it is not a valid basis for surrogate safety analysis. It is our understanding that FRESIM has its own conflict analysis capability for the freeway portion of networks; however, these features are independent of- and not compatible with SSAM.

Can we use SSAM with grade separated networks?
Yes and no. SSAM will not handle grade separations appropriately. The TRJ file format does not currently accommodate a vertical- or Z- coordinate. The TRJ file provides SSAM with only a two-dimensional perspective of the road network. Thus, a vehicle driving on an overpass may appear to SSAM to overlap with the X-Y space occupied by a vehicle driving on the underpass, and thus SSAM will currently record many erroneous conflicts in this area as a result. You may still apply SSAM to such models; however, it will be your own burden at this time to manually filter out the erroneous overpass-to-underpass conflicts. (See Known Issues section for more guidance.)

How do I get AIMSUN to export TRJ files?
This capability requires a special plug-in, which can be obtained by inquiring directly from the makers of AIMSUN.

Can SSAM be used with Windows Vista, Windows 7, Linux or Mac?
The short answer is: Yes.

How to run SSAM on these other operating systems requires a longer answer (for the average user).

The SSAM software is currently developed in Java, and therefore is presumably very portable to different operating systems including newer 64-bit processors, subject to Java support on the desired platform. SSAM has been tested on Windows Vista, Windows 7, and Linux. However, the SSAM install program available for download is specific to Windows XP. SSAM can be successfully run on other platforms, though a little extra effort may be necessary to workaround the lack of an installer native to each platform. The following paragraphs describe the issues and workarounds.

Since the SSAM install program was written for Windows XP, we expect it will only work on Windows platforms. This is currently the only form in which SSAM is available to the public, in order to require users to read and accept the terms of a legal disclaimer from FHWA (a feature enforced by the installer). Of course, the installer works fine on Windows XP. The installer has worked successfully on Windows Vista and Windows 7 operating systems, though the installation may appear relatively awkward.

Note that users of other operating systems (Solaris, Linux, Mac) who are relatively savvy with computers can obtain the SSAM software by first installing it on a Windows machine, and then copying the JAR files (those with a .jar extension) and the tables subfolder from the SSAM installation folder on a Windows computer to your alternate computer. Install Java on your alternate computer. (You can obtain Java from the internet at http://www.java.com). Then, from a command prompt (having navigated to the folder where you’ve put your jar files), type the command: java –jar SSAM.jar

Running SSAM from the Windows start menu, or launching the SSAM.exe program directly from the installation program will likely result in awkward behavior on Windows Vista and Windows 7. Depending on user settings, these newer Windows operating systems may display a warning such as:

"An unidentified program wants to access your computer."

If this warning appears, click the Allow button to proceed. Windows may then display a warning, such as:

"The color scheme has been change to Windows Vista Basic. A running program isn’t compatible with certain visual element of Windows."

After these warnings, the SSAM software will launch, and on newer Windows operating systems will likely present a relatively antiquated look and feel, as shown in the following screenshot.

On Windows Vista, the SSAM software can run and process trajectory files as is; however, the user interface may not look like a normal Windows Vista program, and it may not run as smoothly as it would on Windows XP. On Vista, we have noticed that the Map View is particular awkward while scrolling or zooming; and, the analysis of trajectory files seems to run take about three times longer than it would on a comparable Windows XP system. On Windows 7, the user interface is reportedly (via second-hand account) very disorganized. "The menu bars and options were overlapping and nearly illegible." These issues have to do with underlying Java framework, and can be overcome to achieve normal operation as described in the following text.

SSAM is a Java-based program, which requires a Java Virtual Machine (JVM) to run. A JVM can be obtained by going to the website http://www.java.com, which allows users to download and install a JVM. When SSAM was initially distributed, many users were excessively challenged by the task of independently obtaining and installing Java (a JVM) on their own in order to run the SSAM software. In response to this, the SSAM installer was revised to automatically install the JVM on the machine. However, the version of Java (the JVM) provided by the SSAM installer is specific to the Windows XP operating system. It is only partially compatible with newer Windows operating systems (newer than XP) and is not compatible with other operating systems (e.g., Mac, Solaris, Linux). However, SSAM can be run properly on these other operating systems if the user installs a JVM more appropriate for their particular operating system, and then launches the SSAM application in such a way as to use the newer JVM, instead of the JVM provided by the (Windows XP based) installer program.

Here are the steps to getting SSAM to run properly on other platforms, or perhaps to improve the performance even on Windows XP.

Determine whether an appropriate version of Java is installed on your computer.

Upgrade to a more appropriate or newer version of Java if necessary.

Launch the SSAM application in such a manner as to utilize the newer version of Java (and not the version provided by the installer).

There general steps are described in greater detail as follows:

Determine whether an appropriate version of Java is installed on your computer.

One approach is to visit the web site http://www.java.com. This web page will likely present an intuitive and easy
to follow path to determine if you have Java currently installed on your computer, or if there is a more recent version of Java that could be installed on
your computer. As of May 2010, the page (as shown below) displays a link labeled Do I have Java?

Following the Do I have Java? link currently points to the page (
http://java.com/en/download/installed.jsp), where (as of May 2010) there is a red button labeled Verify Java Version, as shown in the
following screenshot. Click this button.

The browser will run a check to tell you what version of Java is installed on your computer, and whether there is a newer version available for download,
as shown in the following screenshot.

Upgrade to a more appropriate or newer version of Java if necessary.

If Java is not installed on your computer, downloading the most recent version of Java using the button provided from this web page and following
the installation instructions.

If Java is already installed on your computer, you may not need to upgrade; however, you may want to consider upgrading. The current SSAM installer is
designed to check if Java is already installed on the computer, and only install Java if it is not already installed on the computer. It will install Java
(a JVM) in the _jvm subdirectory of the SSAM installation directory (which by default is typically C:\Program Files\FHWA\SSAM
\). A poor SSAM software experience occurs particularly on Windows Vista and Windows 7 operating systems, when the SSAM installer installs its
own JVM, which was appropriate for Windows XP (the most common platform), but not necessary for the needs of Windows Vista or Windows 7.

Another way to determine the Java version (other than the Java website) is to obtain a Windows command prompt. From the Start menu in Windows XP,
you can select Run and type cmd (and click Enter) to launch a command (console) window. If you have Windows Vista, then from the
Start menu click in the Start Search field and type cmd (and click Enter) to launch a command (console) window. Below is an example
of a command window from Windows Vista (as evident by the partially transparent window frame style used in Vista). From the command prompt, type java
–version (and click Enter) to determine your Java version, as shown in the following screenshot. This computer (running Windows Vista) has
Java 1.6.0_oem-b104 installed.

To determine if SSAM is running its own, older JVM, obtain a command prompt as in the previous step, and navigate to the SSAM installation folder
(typically C:\Program Files\FHWA\SSAM) as shown in the following screenshot. Type dir (and click Enter) to list the
directory contents. If the SSAM installer installed its own JVM, there will be _jvm subfolder (as shown in the directory listing
below) which is where that JVM is installed. If you change directories (as shown) to the _jvm\bin\ folder, and type the command
java –version (and click Enter), it will show that the version of the JVM that SSAM has installed, as shown in the following
screenshot (in this case, 1.5.0-b64). Note that before changing to the _jvm\bin\ folder, the command prompt session checked the
java version and obtained a different version (1.6.0_oem-b104).

Launch the SSAM application in such a manner as to utilize the newer version of Java (and not the version provided by the installer).

If SSAM has not installed its own JVM in the _jvm subdirectory, then it should launch with the default Java (JVM) installed on the
computer, and there will be no need for "custom" effort. However, if SSAM has installed its own JVM in the _jvm
subdirectory, then launching SSAM.exe (or starting SSAM from the start menu) will result in SSAM being launching using the JVM it installed
in the _jvm\bin subdirectory, which for newer Windows operating systems will be undesirable.

To launch SSAM with your updated JVM, which you’ve installed as your computer’s new default Java JVM, obtain a command prompt and (
as shown in the following screenshot) navigate to the SSAM installation folder, and type the command: java –jar SSAM.jar

You will then see SSAM launch without warnings and with the appropriate look and feel of the newer operating system, as demonstrated in the following screenshot from Windows Vista, which features a partially transparent application window frame.

This is a slightly tedious process, to use the command prompt to launch SSAM with the appropriate JVM each time you which to start the application. SSAM.exe will continue to explicitly look for the JVM in the _jvm subdirectory, and simply deleting that subdirectory will not alleviate that issue (it will say it could not find java in the _jvm directory and fail). It is possible to place the java –jar SSAM.jar command in a batch file to create a clickable launch option; or alternatively, create a shortcut which you modify to execute an equivalent command.

It is worth noting that the SSAM installer has not been updated to a newer JVM because Java introduced some incompatibility issues between the current JVM (1.5.0) and newer versions. Most of our users have been Windows XP users, and many of them are upgrading prior versions of SSAM, which they have already used over many hours/days of computer time to process trajectory files. The incompatibility problem is in the SSAM case files (which store all the configuration and conflict results), where SSAM case files written with Java 1.5.0 are not compatible with SSAM running under Java 1.6.0. This is due to a change in the way Java encodes (serializes) data to a file. If opening these older case files is important, it may be desirable to stick with the older JVM (1.5.0) installed by the SSAM installer. However, if backwards compatibility is not necessary, or you are will to reprocess trajectory files, then it is probably better to install an up to date version of Java yourself before installing SSAM, so that you have the latest JVM, and not and older one.

We have seen SSAM run on a Linux operating system (this is the platform for the open-source TEXAS simulation). Please let us know if you succeed in running SSAM on other operating systems (e.g., Solaris or Mac). The trajectory (.TRJ) files used by SSAM are not platform specific, and should not pose any limitations.

SSAM is exhausting the maximum memory and hanging during analysis. Is there a way to increase the memory?

Yes. SSAM is a Java application, and instead of using the SSAM.exe executable to launch SSAM, you can manually launch it from a command prompt in such a manner that increases the available memory to SSAM.

Note that Java is already installed on your computer, the SSAM installation program will note install it, and the above command should work. If so,
skip to the next step. However, if Java was not installed on your computer, or an older version of Java was used, then the SSAM installation program may have
installed a Java Virtual Machine (JVM) of the appropriate version just for use with SSAM in a subfolder of the SSAM installation directory. This subdirectory,
if present, is labeled _jvm. In this case, environment variables may not be configured (or overwritten) such that the Windows knows
where to find java.exe when you type javaon the command-line. In this case, more complete information must be entered on
the command line than given in step 3. Type the command .\_jvm\bin\java –Xmx1024 –jar SSAM.jar

You will notice when analyzing TRJ files that the progress bar dialog window now reports a greater maximum memory constraint, such as in the screenshot
shown below where the above command resulted in a maximum available memory of 1016 MB.

Note that increasing the memory in this manner does not guarantee that SSAM will be able to process very large scale TRJ files.

I am a simulation vendor. How do go about adding support for SSAM?

Contact Clayton Chen (see contact information below) for a copy trajectory (TRJ) file format used by SSAM, which is an open, universal format. It is a very easy format conceptually, though your specific simulation implementation will dictate how challenging it might be to use.

Technical Support

If you have any additional questions, you may contact Clayton Chen using the following contact information. However, please recognize that SSAM is free software and the contract with FHWA to provide users with technical support for SSAM ended in June 2010.