Difference between revisions of "ISAT Troubleshooting Guide"

Revision as of 13:15, 25 August 2021

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:

1. 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.
2. 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.
3. 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.
4. 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

ISAT will display this error when a scenario file contains a model that is not recognized.

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.

To prevent problems:

1. run the ISC script - do not move or edit any elements added by the script.
2. save the scenario.
3. close the scenario.
4. re-open the scenario.

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

Group save, import

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

Follow the steps here to 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:

1. 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 reference scenario from a parent scenario file.
2. 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:
   1. 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.
   2. 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.
   3. 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.
   4. 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.

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

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.

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:

1. 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.
2. Syntax is correct but is evaluating the wrong thing; for example, typographic errors can prevent Expression Triggers from working as expected.
3. Embedded expressions; currently this is not possible. Re-structure the expression so that it can be evaluated.
4. Negative numbers; currently negative numbers have to be evaluated. 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 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.

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:

1. 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.
2. 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.)
3. the ADO has a creation radius and has travelled outside the visible radius specified
4. 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.

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.

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.

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

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.

My trigger works but I don't think it is working correctly

There are a number of things to consider regarding proper trigger operation:

1. Does the trigger work, but not as expected?
2. Does the trigger not do the tasks expected?