View source for ISAT Troubleshooting Guide

This document is intended to provide guidance how to resolve some common issues using ISAT and running scenarios on the NADS miniSim™.

Issues have been sorted based on if the issue is related most to ISAT operation and function vs. scenario operation and function.

==ISAT Operation and Function ==

===Unable to open scenario file===

There are four reasons why ISAT might not be able to open a scenario file:

# The BLI roadmap file is an obsolete format and cannot be processed.  This is not usual, and can be determined by reviewing the size of the BLI file for the scenario.  If the file size is less than 70,000k then it is an obsolete BLI.  To correct, re-generate the BLI using the TMT procedures for Generating Output.
# The BLI roadmap is missing from the folder where ISAT expects to find scenarios.  To correct, locate the BLI and copy it to the NADSSDC_SCN folder location.
# The scenario uses an external reference and that reference file cannot be opened.  To correct, locate the external reference file and copy it to the same location as the scenario file.
# The BLI roadmap changed since the scenario was created.  Scenario elements that use a pad (ADOs with paths, roadpad, time to arrival, follow triggers) can be invalidated if the roads they reference are removed from the BLI by altering the road network or tile layout.  The scenario can be salvaged by restoring the original BLI and removing the pads.  The pads can be re-created on the new BLI.

=== Model X not found when opening a scenario file ===
ISAT will display this error when a scenario file contains a model that is not recognized.

[[File:2021-08-13_11h44_25.png|400px]]

The cause of this error is the scenario being opened contains a model that ISAT cannot find within any of the sol2 files available.

This can happen if the scenario originates with some other laboratory, or if the scenario was authored with a different sol2 file than the one in use.

ISAT uses a system variable to identify sol2 file locations:
NADSSDC_SCN=C:\NADS\Isat\data\

'''To correct the missing model error, use Task Manager to exit the ISAT application and locate the sol2 file used to create the scenario.  Either replace the ISAT\data sol2 with the scenario sol2 file, or use a text editor to transplant the model from the source sol2 into your working sol2 file.'''

It is also possible to create a new sol2 file using the prefix sol2_aux.xxx.txt, where xxx is some unique number.  Note that sol2 files begin with the keyword '''SOL2''' as the first line.  Copy the missing model into this file, and place it into the folder location specified by NADSSDC_SCN.

If ISAT is running when you create a new sol2 or copy over the current one, exit and re-launch.  ISAT reads sol2 data only at startup.

'''NOTE: Model names and IDs must be unique within the entire set of sol2 and sol2_aux files.'''

'''Also Note:''' You could also edit the scenario in a text editor and remove the model reference so that ISAT can open the scenario.  Doing this will of course change the scenario, potentially causing other problems if that model is used as a trigger predicate.

=== ISAT crashes after running an ISC script ===

Running an ISC script can cause ISAT to become unstable.  The theory goes that new objects added via script exist only in memory - this may explain why it's possible to move multiple objects away from a single scripted object location.

[[File:isat_isc_objects.jpg|400px]]

To prevent problems:
# run the ISC script - do not move or edit any elements added by the script.
# save the scenario.
# close the scenario.
# re-open the scenario.

At this point scripted elements should operate the same as elements inserted manually.

=== Group Save or Group Import Failure ===

ISAT will save group files only to ISAT\data, irrespective of any other location chosen in the file browser.

Follow the steps here to [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Define_a_Group|define and save a group] from your scenario.

If the group fails to import, try exiting ISAT and then re-launch it and try again.

*Note: It may be necessary to provide some information into the summary page that is presented during the Save Group operation.  In the case of abnormal performance, try this.

*Note: ISAT will not import any group into a scenario that already contains a group with the same name.  In those cases you will need to edit the .grp file in a text editor and change the name of the group to some unique value, then try reading it into ISAT again.

==== Alternatives to Using Group Files ====
In the case of problems saving or reading Group files with ISAT, there are two alternatives:
# Use scenario as an external reference; Since you likely have already assigned groups to objects, you can save the scenario and then reference it as an '''[https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#External_Reference| external reference scenario]''' from a parent scenario file.
# Transplant group objects into another scenario; this requires the use of a text editor.  Ideally the text editor has macro capability, allowing for some automation of tasks.   This process could take place in two stages:
## search for all objects in the scenario; they can be identified by the keyword '''IsNewObj'''.  Go to the start of that object, select to the end of that object, and cut it.
## insert a marker element at the cursor location, go to the top of the file, past the object there, then search for the marker and remove it.
## repeat for all objects; at the end of this process all objects will be located at the top of the file.  You can then copy them all as a unit, rename the group name, etc. and paste into the destination scenario.
## Be sure to open any text modified scenario in ISAT to be sure the file remains readable.  Any mistake can invalidate the scenario and ISAT will not be able to open it.

It is unclear if these copy/pasted objects will be truly duplicated since they are defined twice, or if ISAT will 'clean up' duplicates behind the scenes.

== Scenario Operation and Function ==

This list is not comprehensive, as there are a vast number of ways to construct a scenario.

Some general problem solving steps are common to many scenario related issues.  These can be summarized as incorporating some form of reporting in the scenario triggers to 'tell' when problem triggers are activated.  It may also be useful to review the DAQ file from drives that exhibit problems.

If triggers contain some form of self-reporting that is visible in Rehearsal mode and during simulation on miniSim then it becomes possible to isolate when things go wrong or happen out of sequence.

Since Rehearsal mode does not show Visual Display Text, use either a Create or Write to Cell action or set a LogStream.

For rehearsal mode the cell name can be anything, it does not have to be an actual cell.  During rehearsal status information will be printed to the Debug window.

A Create action can be used to create some noticeable element in the simulation, that will indicate the trigger has fired.

These troubleshooting elements can be removed from the scenario once the issues have been resolved.

== Driver is sitting in the middle of nowhere or off-road when miniSim goes to Drive==
All scenarios that are driven (i.e., not an external reference) must include a start location.

A start location is created when you insert the External Driver (XD) into a scenario.  If the eyepoint is wrong (somewhere off in space), this happens when there is no scenario start location defined.

To check if there is a start location defined in ISAT, press CTRL-D (the Ctrl and D keys) while editing a scenario.  The camera should snap to the XD location.  If the view does not change then no start location has been defined for the scenario.

To correct this issue, insert an external driver using ISAT, save the scenario and try to drive again.

==My trigger doesn't work at all==

If you suspect a trigger hasn't fired, you can conduct an investigation by running ISAT Rehearsal.  Rehearsal mode activates some of the simulator behaviors and you can visualize if the trigger is activated or not.

*Note: in some cases ISAT may be unable to rehearse a scenario.  In that case proceed to drive the scenario, then review the DAQ playback for insights into the issue.

Check the trigger  predicate (RMB on trigger >> Settings) or DBL-Click trigger to open the trigger 

[[File:2021-08-24_13h50_30.png|400px]]

Notice the different options in the upper left corner.  A minimum of one must be enabled.
A trigger without a predicate has no means of activation.

'''Note:''' This does not apply to Expression or Time triggers.

'''Also note:''' Using the By Road option means you must also enable one of the other options as shown in the figure above.

If the trigger has a predicate, check if a roadpad was defined (roadpad, Time to Arrival, Follow) and if necessary, add it.

*Note: Copied roadpads may dislocate the trigger relative to the pad.  If the pad is not located where you expect it, the simplest thing to do to address this is to delete the existing pad and re-create it where you want it.

To delete the pad, RMB on the trigger and choose Delete Road Pad from the context menu.

In some cases the XD can miss the trigger roadpad if it is short.  This issue will be easy to identify when viewing the DAQ playback.

In these cases the solution may be as simple as extending the roadpad, or adjusting the location of the pad slightly to ensure the XD will activate the trigger.

=== Roadpad Trigger Lane Mismatch ===
If you have a roadpad trigger with the '''By Road''' filter (this is actually a LANE filter) enabled then it can only be activated by the predicate object when that object is in the proper lane when it 'steps on' the pad.

[[File:2021-08-25_12h38_34.png|400px]]

In the figure the Road (lane) filter has been assigned to the left-most lane for traffic driving North.  That lane is highlighted in the upper right preview window.

===Expression Triggers===
Expression triggers activate only when their expression evaluates to True.  Therefore it makes sense to confirm the expression evaluates to True:

# Syntax is not correct; ISAT Rehearsal will complain if the expression cannot be evaluated.  This is generally a syntax error.  Try to locate any scenario with a similar known working expression and compare it to yours to identify syntax errors.
# Syntax is correct but is evaluating the wrong thing; for example, typographic errors can prevent Expression Triggers from working as expected.
# Embedded expressions; currently this is not possible.  Re-structure the expression so that it can be evaluated.
# Negative numbers; currently negative numbers have to be calculated.  It is not possible to look for negative numbers directly.


This expression will '''fail''' because it contains a negative number directly:

'''Expression "ReadCell('CFS_Auto_Transmission_Mode', 1) = -2"'''


This expression will '''succeed''' because the negative number is a calculated value:

'''Expression "ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )"'''

== My trigger doesn't work completely ==


Partial completion is what happens when the trigger fires but it does not execute all the actions it contains.

Review the actions within the trigger, and see if there is a [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Scenario_Authoring:_Action_Types| persistent action] that is not the last action.

Action execution stops on a persistent action and no actions after it in the list will work.

If you cannot shift the persistent action to the end of the action stack, then create a time trigger to separate it from the other actions.

'''Note: multiple persistent actions would require one time trigger per action.'''

[[File:2021-08-24_14h26_32.png|400px]]

The figure illustrates the selected roadpad trigger contains a '''create action''' as the last action (only one create action per trigger is allowed).  This is used to create two time triggers in order to assign a persistent action to two objects using unique parameters.

Another way a trigger may not execute all actions is when an action operates on a scenario element that no longer exists.  

This can happen if an ADO that is key to an event is removed from simulation, either because the ADO went unstable or otherwise was deleted.  You will need to work backward from the point that ADO disappeared and try to identify the cause for the deletion.

== I see cars in the simulation disappear==

There are a number of reasons why ADOs might disappear from the scenario:

# some action is forcing the ADO to attempt something it is not capable of doing; the most common being forcing an ADO to navigate a turn too fast for it to drive through the turn without crashing.  Instead of visualizing the crash the ADO is deleted from the scene.
# the ADO is being removed by a scenario action (this only happens when the delete is explicitly specified in an action '''Remove Element''' or is of a  category or name specified in a delete action, i.e. '''Ado''' or '''Type: Vehicle'''.)
# the ADO has a creation radius and has travelled outside the visible radius specified
# the roadmap contains  an anomaly that the ADO cannot resolve

The most common roadmap anomaly is when the road network is created in TMT and two tiles are forced together.  Although this is an allowed operation, it does not guarantee the resulting road network will be drivable by simulated traffic.

TMT will alert the author of incompatible edges by highlighting the edge in red as shown below.

[[File:2021-08-24_14h56_26.png|400px]]

The author has the option of forcing the connection anyway, overriding the alert.  There are no visible means to identify forced edges in the TMT as shown below.

[[File:2021-08-24_14h56_33.png|400px]]

If the forced edges cannot be processed during the creation of the LRI file, an error to that effect will be reported.  Note the road merge error below:

 Using 'E:\Nads\ProjectData\TMT\ProjectData\Tiles' for TMT_TILE_LIB_DIR
 Using 'C:\Users\sallen\AppData\Local\Temp' for TMP
 Processing Tile Model: '2ln_city_02_day'
 Processing Tile Model: '4ln_4way_ind_day_02'
 Processing Tile Model: '4ln_4way_ind_day_03'
 Processing Tile Model: '4ln_comm_straight_02'
 Processing Tile Model: '4ln_comm_straight_03'
 Processing Tile Model: 'urban_3way'
 Processing Tile Model: 'urban_4ln_arterial_04'
 Using adjacency file '_dev.cd2'
 Adjacency: ERROR: Invalid Number of LANES in Adjacent Tiles 
 4ln_comm_straight_02_-6600x_-3300y_0r/urban_3way_-5940x_-3300y_0r
 Road R1_-6600_-3300/R3_-5940_-3300 #Lanes 4/5- SKIPPING ROAD MERGER: INFO: # MATCHES FOUND 10

The resulting BLI will contain a discontinuity at the forced tile edge.  In this example the differences between the roads is obvious due to the number of lanes present in the forced tile.  This condition may not always be so obvious.  If you suspect a road network discontinuity you can review the area in ISAT and watch the status area for the road name under the cursor.  Road names do not change along the length of a road.  If you see two different road names, you can confirm the discontinuity by placing an ADO near the area and trying to extend a path across it.

[[File:2021-08-24_15h13_47.png|400px]]

Paths cannot be constructed to bridge the different road segments.  ISAT will not permit paths to cross this region.

[[File:2021-08-24_15h14_42.png|400px]]

In most cases the XD will be able to navigate, but ADOs will disappear when they try to cross the tile edge where road A meets road B.

== Collision Management ==
Collision management on the Nads miniSim involves elements from the miniSim startup command, the scenario object library, the scenario file and the Audio Engine subsystem as the following diagram shows:

[[File:2021-08-25_13h33_27.png|400px]]

=== Collision Calculation ===
Collisions are based on object bounding volumes, which is a 3D 'box' enclosing the object as shown in the following diagram:

[[File:collisions_bbox_08232021.jpg|400px]]

The size of each bounding volume is defined within the sol2 or sol2_aux files as Width, Height and Length properties defined for each object.

By convention object models are located at the local origin XYZ (0.00, 0.00, 0.00).

'''Note:''' Because objects are represented as bounding volumes it is not possible for the simulator driver to drive over an object - for example on the roadway - without colliding with that object.

Some elements, such as street signs, are typically positioned above the roadway so these objects cannot be collided with.

=== Nads miniSim Settings ===
Collisions can be disabled in the miniSim startup command in the file
NadsMiniSim_x.x\bin.x64\VisualServer.bat

-logbehav 0 -mirrorRender fbo -useEphemerisModel 0 -syncondyna 1 -predicteyepos 0 ''' -collisioneffects 1 ''' -blockonvsync 0 -titler 4 -virtualDials 1 -threadingModel ThreadPerViewport

collisioneffects = 0 ''' off '''

collisioneffects = 1 ''' on '''

'''Note: ''' The collisioneffects flag does not affect collisions during simulation, it controls if the cab shakes or not.  '''This is a global setting per miniSim installation.'''

''' Also note:''' The collisioneffects flag will override the Scenario Initial Conditions flag.

=== Audio Engine Settings ===
The sound configuration file NadsMiniSim_x.x\data\sound\DefaultCabSound\config.txt contains a '''collision sound section.'''  All collision sounds are located here.

[[File:2021-08-25_13h49_53.png|400px]]

To disable one or more collision sounds change the volume as needed.  1.0 means the sound will play at maximum recorded volume for that sound.  0.0 will disable the sound.

'''Note:''' changing the collision sound volume does not affect collisions during simulation.  This is also a global setting per miniSim installation.

=== Scenario Settings ===
Collision effects are managed in scenario through the Initial Conditions dialog in ISAT.
Isat >> Edit >> Initial Conditions

[[File:2021-08-25_13h53_19.png|400px]]

'''Note:''' this setting is unique per scenario.  Disabling the collision effects does not affect collisions during simulation.

=== Scenario Object Library (SOL2) ===
The scenario object library files begin with 'sol2' and consist of files in Nads_ISAT\data and Nads_miniSim_x.x\data.  Only the files located under miniSim are used during simulation, although it is strongly recommended that files in both locations match.

Each object has a collision sound ID associated with it.  

[[File:sol2_collisionSoundID_08252021.jpg|400px]]

The CollisionSoundID is an integer that corresponds to a sound.wav file as specified within Nads_miniSim_x.x\data\sound\DefaultCabSound\Instructs\instructions.txt

[[File:collision_instruct_08252021.jpg|400px]]

The file is organized by unique sound ID in the first column, a file name in the 2nd column (spaces in the file names are not supported) and a volume in the 3rd column.  The valid range is 0.00 (effectively off or silent) and 1.0, or maximum volume as present in the .wav file specified.

There are 2 ways to remove the collision sound effect using the sol2 and audio engine subsystem:

# assign a sound to the collision sound ID for each object you wish to "disable" the collision sound for - that is, a sound that plays with no audible cues.
# disable the collision sound be setting the ID to ''' -1'''

'''Note:''' disabling the collision sound ID '''will disable collisions for that object during simulation.'''

'''Also note:''' This is a system-wide setting and it will affect all scenarios using the objects so edited.

== Road Sounds ==
Road sounds can be considered a scenario element in the sense that they play during simulation.

In some cases it may be desirable to disable road sounds which are present by default.
For example, during a simulation designed to study drowsy driver performance, a sharp change in the ambient sound may startle the driver (when driving from asphalt onto a gravel shoulder).

Sounds are associated with road surfaces through '''surface material codes''' or SMCs.  

Sounds associated with road surfaces are specified in the '''LRI file'''.  This is the name of a file that is created by the Tile Mosaic Tool during database output procedures.

The LRI file can be edited so that disruptive sounds can be changed.  For example, by changing all road shoulder SMCs to match standard roads, the gravel sound can be removed from simulator drives.

This change is global for all scenarios using that database world.

For detailed information relating to road sounds please see the following Road Surface documentation:
[https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=File:Addendum_RoadSurfaceModificationsToLRI.pdf]