====== Model Debugging in SAMM ======
Sometimes when you are evaluating your model in SAMM the process is taking a very long time or the results that are produced are incorrect or not what you were expecting. Fortunately TOOL has a number of debugging options available that allow yo tou see which tools are currently be evaluated, display intermediary data and even ignore errors.

===== SAMM Preferences =====

To access the debugging options in SAMM:

  - Selecting the Preferences option in the File menu. This displays the Preferences window.
  - Click on the TOOL tab.

{{:howtos:debugging:samm_preferences_tool.gif|}}

The debugging options are found in the options group as seen in the image above

  * **verbose** - displays the parser output before it is sent to TOOL in the TOOL console. This option is mainly a developer tool and not really useful for the average user. 
  * **debug** - displays the name of each tool being executed as well as the temporary file path in the TOOL console
  * **ignore error** - ignores any errors that occur allowing you to complete the model evaluation. This option can be useful if you want to test portions of your model know that you model is not complete. However you need to be cautious when using this option. Remember to always inspect the results of your model.
  * **single step** - displays each line of tool code that is about to be executed in the TOOL console and waits for user input before proceeding. Currently the user input option is to proceed to the next line by pressing the ENTER key.
  * **display output objects** - displays the output of each line of tool code executed in either Table or Graph. The model will pause execution while Table or Graph is open and resume execution once it has been closed. The medium of display is specified by including the following in the tool.links file for the model account being used:
<code>
displayOutObj :
  table
</code>

OR

<code>
displayOutObj :
  graph
</code>

Note that each of these options can be used alone or in combination with one another depending on your requirements.

===== TOOL Code =====

You can also programatically incorporate debugging features in your Documeter code. This method is more flexible than setting the SAMM Preferences as you can pick and choose what code you want to debug. However you need to remember to when using this method you need to [[howtos:update_code_diagram|re-load any calculators that you have modified beck into SAMM]].

==== single step and display output objects ====

You can activate the **single step** and **display output objects** debug features in your Documenter code by adding the following lines of code around the section you are interested in debugging.

<code>
$singleStep = on
$displayOutObj = on
  start of buggy code
  .
  .
  .
  end of buggy code
$singleStep = off
$displayOutObj = off
</code>

Note:
  * you need to ensure that the tool.links is properly configured to call Table or Graph as shown above.
  * once you change the code in Documenter you will need to [[howtos:update_code_diagram|re-load the calculator into SAMM]]

==== seeshape, table and display ====


There are also a number of tools that are useful for debugging your model.

  * **seeshape** - many of the model errors that occur are the result of objects that are misshaped (i.e. the object has to many dimensions, not enough dimensions, the dimensions are out of order, the units of measure is inconsistent and/or the data type is inconsistent). As the name implies the seeshape tool displays the shape of the specified object allowing you to see how the object has been defined and track down any inconsistencies.
  * **table** - sometimes the results produced are empty, unexpected or wrong. The table tool is useful for tracking the path data takes through a procedure by examining the inputs and outputs of a line of code. By visualizing how the data is being manipulated you can easily examine the formulas and logic you are trying to apply to your model.
  * **display** - The display tool is similar to the table tool, however the display tool produces its output to the TOOL console and therefore does not stop the evaluation of the model. This tool can be particularly useful for debugging feedback views where pausing the model through each iteration would be slow and cumbersome.

Remember once you change the code in Documenter you will need to [[howtos:update_code_diagram|re-load the calculator into SAMM]]