Debugging and diagnosis strategies

This section brings together resources of interest to debug and diagnose problems be it tools, tricks, or strategies.

Legacy code

Code_TYMPAN can still be run with the legacy code (i.e. without Python subprocess and without the solver data model) with the following option: –legacy-computation

Note

This is a temporary feature provided in order to ease the debugging and it should soon be removed.

Diagnose a computation failure

Look at the logs

Three logs are available:

  • A log is produced by TYMessageManager / OMessageManager: before the GUI starts it is displayed in the console (if it exists) and then it is displayed in the Messages frame of the GUI (on the left).

    This logger checks _DEBUG preprocessor macro to write Debug messages only in Debug.

    Warnings (from module warnings) and errors thrown by Python subprocess, also appear in Messages frame. When filter_out function parameter verbose is set to False, warnings are filtered out from Messages frame, and errors still appear.

  • While solving the acoustic problem, the Python subprocess also generates a log. It is written in the file “tympan.log” and created in the current directory (which is the directory containing the XML project in the case of the computation of an existing project).

    The elements logged in this file comes from logging python package. So the file contains elements logged by python Tympan code, but also by other python packages, like shapely or matplotlib. This log is configured in “solve_tympan_project.py” and in “process_site_altimetry.py”. Currently, the logging level is set to DEBUG. It would be interesting to configure the log level by a configuration file as “bin/logging.conf” for instance. That way, the log level could be changed at run time. The default logging level should be INFO.

  • Still while running the subprocess, the log emitted by the C++ libraries (produced by OMessageManager) is kept but redirected to the console. It would be interesting to redirect these logs to python logging system rather than directly to the console.

stdout filter_output:

  • The python ContextManager filter_output, redirects outputs to stdout to os.devnull, thus filtering them out. This ContextManager takes a parameter verbose. When verbose is set to False, outputs are filtered, when it is set to True, outputs are displayed on stdout.

    As it is using a low-level redirection, it is very important to define the environment variable PYTHONLEGACYWINDOWSSTDIO.

    When launching a python tympan script like solve_tympan_projet.py, verbose should be by default set to : False in Release GUI mode, True in Debug GUI mode and in Python API mode.

    This parameter verbose could also be deduced from the “bin/logging.conf” file rather than being hard-coded.

    Finally, if all the logs from C++, Cython and Python were correctly redirected to Python logging system and were correctly handled by it, we could go without filter_output.

Did you correctly generate your build files ?

A good practice is to make a directory per build configuration (Debug/Release), and not to compile in both configurations in the same directory. Under Windows, when you use cmake-gui to generate Code_TYMPAN.sln, choose whether your build will be a Debug or a Release one, and then stick to it (don’t change this option from Visual Studio).

It is important because this CMake parameter is used to configure environment variables, that will reference the debug or release version of the generated libraries.

Is the environment correctly configured ?

The following environment variables are needed by Code_TYMPAN, and some of them are directly set in the code (see Tympan/gui/app/EnvironmentUtils.h):

  • PYTHONPATH: should contain the directory of cython library pytam.so/ pytam.pyd (i.e. cython in release mode, cython_d in debug mode). It is set by TYMPAN executable when running it from the install directory, and by CMake when running the tests with ctest from the build directory

  • Path to libraries:

    • Under Windows, as TYMPAN libraries are statically linked to the executable, there is nothing to do regarding this point. However, this is not the case of the 3rd party libraries. When running Code_TYMPAN legacy code, as these libraries are in the same directory as Tympan.exe, they are found. But when trying to access them through cython library which is located in another directory it is not the case. That is why the PATH environment variable must contain this directory. It is set by TYMPAN executable when running it from the install directory, and by CMake when running the tests with ctest from the build directory

    • Under Linux, TYMPAN libraries are dynamically linked to the executable and therefore the LD_LIBRARY_PATH environment variable must indicate where to find them. This is not done in Code_TYMPAN and must be set by the user.

  • Path to Python interpreter (Windows specific): to run the Python script, the complete path to the Python interpreter is needed (python solve_tympan_project.py is not interpreted). Yet, there is no standard under Windows regarding where to install python, so this path cannot be known from Code_TYMPAN. That is why TYMPAN_PYTHON_INTERP environment variable must be set by the user (for example: “C:\Python27\python.exe”). If it is not set, this error will appear in the TYMPAN log: “Can’t access python interpreter. TYMPAN_PYTHON_INTERP environment variable is not set.” If the environment variable exists but does not lead to the python interpreter, the following message will be logged: “Can’t access python interpreter. TYMPAN_PYTHON_INTERP environment variable is not correctly set.”

  • Path to CGAL bindings python libraries (used in altimetry computations): it must be whether in the PYTHONPATH or in the CGAL_BINDINGS_PATH dedicated environment variable.

Tympan debugging options

The ‘TYMPAN_DEBUG’ environment variable is read from both python and C++ code, and can be used to enable some debug options (format: TYMPAN_DEBUG=opt1;opt2;opt3). The following options are taken into account:

  • interactive : when solve_tympan_project.py is called from an interactive terminal, pdb (python debugger) is invoked in this script and the ID of the python process running the script is displayed in the terminal. The script execution is therefore paused, waiting for an user entry. It makes it possible to attach the python process to a debugger (MSVC debugger under Windows, for example), and then enter run in the terminal to start the script execution and thus C++ code debugging.

  • keep_tmp_files: when Tympan executable is run, the input and output temporary files used to communicate with the subprocesses running python scripts (in charge of running an acoustic simulation or of computing the site altimetry) are not removed when the subprocess returns, and their paths are displayed by Code_TYMPAN logging system.

  • monothread : disables the multithreading, computations will be run with just one thread.

Known bugs

  • If Pythonx,y - mingw is in the path under Windows, it corrupts the environment and Code_TYMPAN’s behaviour isn’t guaranteed (more particularly, the Python scripts may crash).