|
1 | | -Code Performance Diagnostics |
2 | | -############################ |
| 1 | +Code Debugging and Diagnostics |
| 2 | +############################## |
3 | 3 |
|
4 | | -Spheral uses Caliper to preform code diagnostics, such as timing. To enable this functionality in the code, Spheral needs to be configured with ``ENABLE_TIMER=ON``. Otherwise, the timing regions are no-ops for improved preformance. |
| 4 | +Valgrind |
| 5 | +======== |
| 6 | + |
| 7 | +We advise using Valgrind to check memory leaks when doing development on Spheral. |
| 8 | +When using Valgrind to check Spheral, be sure to use the provided suppression file |
5 | 9 | :: |
6 | 10 |
|
7 | | - ./scripts/devtools/host-config-build.py <sys_type>-<spec>.cmake -DENABLE_TIMER=ON |
| 11 | + valgrind --suppressions=./scripts/devtools/valgrind_python_suppression ./spheral |
8 | 12 |
|
9 | 13 |
|
10 | | -Querying using Caliper |
11 | | -====================== |
| 14 | +Using Caliper |
| 15 | +============= |
| 16 | + |
| 17 | +Spheral uses Caliper to preform code diagnostics, such as timing. To enable this functionality in the code, Spheral needs to be configured with ``ENABLE_TIMER=ON``. Otherwise, the timing regions are no-ops for improved preformance. |
| 18 | +:: |
| 19 | + |
| 20 | + ./scripts/devtools/host-config-build.py <sys_type>-<spec>.cmake -DENABLE_TIMER=ON |
12 | 21 |
|
13 | 22 | Caliper is configured and started through the ``cali::ConfigManager``. |
14 | 23 | The ``cali::ConfigManager`` is wrapped in a ``TimerMgr`` singleton class, which has a python interface. |
15 | 24 |
|
16 | 25 | .. note:: |
17 | | - ``TimerMgr`` is initialized and started during ``commandLine()`` in ``src/SimulationControl/SpheralOptionParser.py``. This is because ``commandLine()`` is almost always invoked directly near the start of a problem. However, if ``commandLine()`` is not called, the timers would need to be configured and started directly using the ``TimerMgr`` class. See :ref:`below <manual_caliper>` for more details. |
| 26 | + ``TimerMgr`` is initialized in ``src/SimulationControl/SpheralTimingParser.py`` which is called during ``commandLine()`` in ``src/SimulationControl/SpheralOptionParser.py``. This is because ``commandLine()`` is almost always invoked directly near the start of a problem. However, if ``commandLine()`` is not called, the timer manager would need to be configured and started directly using the ``TimerMgr`` class. See :ref:`below <manual_caliper>` for more details. |
18 | 27 |
|
19 | 28 | By default, the Caliper configuration is set to ``spot`` and outputs Caliper files (``.cali``). |
20 | | -For the default configuration, the Caliper files are named based on what file is being run, for example: |
21 | | -:: |
22 | 29 |
|
23 | | - python Noh-cylindrical-2d.py |
| 30 | +There are many different Caliper configurations to view various information. Here are some extra links for those who want to read or experiment with other features in Caliper that can be incorporated into Spheral: |
24 | 31 |
|
25 | | -will produce a timing file called ``Noh-cylindrical-2d_YEAR_MONTH_DATE_TIME.cali`` where the file name includes the current date and time. |
| 32 | + * `Configuration basics <https://software.llnl.gov/Caliper/CaliperBasics.html#more-on-configurations>`_ |
| 33 | + * `Builtin Configuration <https://software.llnl.gov/Caliper/BuiltinConfigurations.html>`_ |
| 34 | + * `Manual Configuration <https://software.llnl.gov/Caliper/configuration.html>`_ |
| 35 | + * `Output Format <https://software.llnl.gov/Caliper/OutputFormats.html>`_ |
26 | 36 |
|
27 | | -The Caliper file name can be specified using the command line |
28 | | -:: |
| 37 | +Caliper and Adiak Options |
| 38 | +------------------------- |
29 | 39 |
|
30 | | - python Noh-cylindrical-2d.py --caliperFilename 'new_test_name.cali' |
| 40 | +.. option:: --caliperFilename |
31 | 41 |
|
32 | | -Different Caliper configurations can be set at the command line using ``--caliperConfig`` like so |
33 | | -:: |
| 42 | + Name of Caliper timing file. Should include file extensions. Optional, default: ``name_of_file_YEAR_MONTH_DATE_TIME.cali``. |
34 | 43 |
|
35 | | - python Noh-cylindrical-2d.py --caliperConfig 'runtime-report(output=time.txt),calc.inclusive,region.count' |
| 44 | +.. option:: --caliperConfig CONFIG_STR |
36 | 45 |
|
37 | | -.. note:: |
38 | | - The above configuration produces timing results similar to the previous ``Spheral::Timer`` method. This results in a file named ``time.txt`` with cumulative times for the nested regions as well as a count of how many times each region ran. |
| 46 | + Specify a built-in Caliper configuration or turn off timers with ``none``. Optional, default: ``spot``. |
39 | 47 |
|
40 | | -Similarly, a non-default Caliper configuration can be read in from a JSON file using ``--caliperConfigJSON`` and providing the file name. |
41 | | -Lastly, Caliper timers can be turned off using ``--caliperConfig none``. |
| 48 | + **Example**: |
| 49 | + :: |
42 | 50 |
|
43 | | -There are many different Caliper configurations to view various information. Here are some extra links for those who want to read or experiment with other features in Caliper that can be incorporated into Spheral: |
| 51 | + ./spheral ex_prog.py --caliperConfig 'runtime-report(output=time.txt),calc.inclusive,region.count' |
44 | 52 |
|
45 | | - * `Configuration basics <https://software.llnl.gov/Caliper/CaliperBasics.html#more-on-configurations>`_ |
46 | | - * `Builtin Configuration <https://software.llnl.gov/Caliper/BuiltinConfigurations.html>`_ |
47 | | - * `Manual Configuration <https://software.llnl.gov/Caliper/configuration.html>`_ |
48 | | - * `Output Format <https://software.llnl.gov/Caliper/OutputFormats.html>`_ |
| 53 | +.. note:: |
| 54 | + The configuration in the example above produces timing results similar to the previous ``Spheral::Timer`` method. This results in a file named ``time.txt`` with cumulative times for the nested regions as well as a count of how many times each region ran. |
49 | 55 |
|
| 56 | +.. option:: --caliperConfigJSON JSON_FILE |
50 | 57 |
|
51 | | -Adding Region Timers in C++ |
52 | | -=========================== |
| 58 | + Specify a JSON file containing a non-default Caliper configuration. Optional. |
53 | 59 |
|
54 | | -So far there are two different types of regions in Spheral, using the following macros: |
55 | | -:: |
| 60 | +.. option:: --adiakData ADIAK_DATA_STR |
56 | 61 |
|
57 | | - TIME_FUNCTION |
| 62 | + Specify any Adiak data directly in the command line. Must be a string in key:value format, separated by commas. Optional. |
58 | 63 |
|
59 | | -or |
| 64 | + **Example**: |
| 65 | + :: |
60 | 66 |
|
61 | | -:: |
| 67 | + ./spheral ex_prog.py --adiakData "test_name: the_cheat, test_num:10" |
62 | 68 |
|
63 | | - TIME_BEGIN("timer_name") |
64 | | - TIME_END("timer_name") |
| 69 | +.. note:: |
| 70 | + By default, all ``commandLine()`` inputs are added as Adiak metadata. ``--adiakData`` are for metadata that does not come through Spheral command line arguments. Adiak metadata can also be added through the python interface. See :ref:`below <python_adiak>` for more details. |
65 | 71 |
|
66 | 72 |
|
| 73 | +Adding Region Timers in C++ |
| 74 | +--------------------------- |
| 75 | + |
| 76 | +The following macros are used to create timing regions in the Spheral C++ interface: |
| 77 | + |
67 | 78 | - ``TIME_FUNCTION`` can be added to the very beginning of a function and creates a region for the entire function using the function's name. ``TIME_FUNCTION`` uses just the function name and no class or parameter information, so be careful when using this method with functions that could share names. |
68 | 79 |
|
69 | 80 | - ``TIME_BEGIN("timer_name")`` and ``TIME_END("timer_name")`` create a region between the two different calls and use the string (in this case ``timer_name``) as the name. |
70 | 81 |
|
71 | 82 |
|
72 | 83 | Adding Region Timers in Python |
73 | | -============================== |
| 84 | +------------------------------ |
74 | 85 |
|
75 | 86 | Region timers can be added inside the python code using the following function calls: |
76 | 87 | :: |
77 | 88 |
|
| 89 | + from SpheralUtilities import TimerMgr |
78 | 90 | TimerMgr.timer_start("timer_name") |
79 | 91 | some_function_call() |
80 | 92 | TimerMgr.timer_end("timer_name") |
81 | 93 |
|
82 | 94 | .. note:: |
83 | | - IMPORTANT: All timers must have both a start and end call. Otherwise, memory issues will occur. |
| 95 | + All timers must have both a start and end call. Otherwise, memory issues will occur. |
| 96 | + |
| 97 | +.. _python_adiak: |
| 98 | + |
| 99 | +Adding Adiak Metadata in Python |
| 100 | +------------------------------- |
| 101 | + |
| 102 | +Adiak metadata can be added inside python code using the following function calls: |
| 103 | + |
| 104 | +.. code-block:: python |
| 105 | +
|
| 106 | + adiak_values("value_name", value) |
84 | 107 |
|
85 | 108 | .. _manual_caliper: |
86 | 109 |
|
87 | 110 | Starting Caliper Manually |
88 | | -======================== |
| 111 | +========================= |
89 | 112 |
|
90 | | -As mentioned above, Caliper (not an individual Caliper timer) is normally configured and started in ``commandLine()`` python routine. However, Caliper can be directly configured and started through the python interface, if desired. This can be done by putting the following into the python file: |
| 113 | +As mentioned above, the Caliper timing manager is normally configured and started in the ``commandLine()`` routine. However, Caliper can be directly configured and started through the python interface, if desired. This can be done by putting the following into the python file: |
91 | 114 | :: |
92 | 115 |
|
| 116 | + from SpheralUtilities import TimerMgr |
93 | 117 | caliper_config = "some_configuration(output=some_filename.txt)" |
94 | 118 | TimerMgr.add(caliper_config) |
95 | 119 | TimerMgr.start() |
0 commit comments