.. role:: raw-html-m2r(raw) :format: html geopmplotter(1) -- visualize reports and traces =============================================== SYNOPSIS -------- ``geopmplotter`` [\ *OPTIONS*\ ] [\ *PATH*\ ] DESCRIPTION ----------- Used to produce plots and other analysis files from report and/or trace files. The *PATH* argument is the input path to be searched for report/trace files. If *PATH* is not provided, the current working directory is used. OPTIONS ------- * ``-h``\ , ``--help``\ : show help message and exit. * ``-r``\ , ``--report_base`` _REPORT\ *BASE*\ : The base report string to be searched. All files that are located in the *PATH* directory that begin with _REPORT\ *BASE* will be selected and interpreted as report files. If this option is not specified then all files with the ".report" extension in *PATH* are selected. * ``-t``\ , ``--trace_base`` _TRACE\ *BASE*\ : The base trace string to be searched. All files that are located in the *PATH* directory that begin with _TRACE\ *BASE* will be selected and interpreted as trace files. If this option is not specified then all files with the ".trace" extension in *PATH* are selected. If 'None' is specified as the trace base then no trace files will be parsed. * ``-p``\ , ``--plot_type`` *bar*\ |\ *box*\ |\ *power*\ |\ *epoch*\ |\ *freq*\ |\ *debug*\ : The type of plot to be generated (default: *bar*\ ). Multiple plots can be specified by providing a comma separated list (e.g. -p bar,box). The debug plot can be used to explore parsed data from a Python command prompt. * ``-s``\ , ``--shell``\ : Drop to a python shell after plotting. Useful for data analysis. * ``-c``\ , ``--csv``\ : Generate CSV files for the plotted data. * ``--normalize``\ : Normalize the data that is plotted. For per-node plots this will also use uniform node names in the legend. * ``-o``\ , ``--output_dir`` _OUTPUT\ *DIR*\ : The output directory where files generated from the plotter will go. (default: *figures*\ ) * ``-O``\ , ``--output_types`` *svg*\ |\ *png*\ |\ *pdf*\ |\ *eps*\ |\ *ps*\ : The file type(s) for the plot file output. Multiple file types can be created simultaneously if a comma separated list of types is provided (e.g. -o svg,eps,png). (default: *svg*\ ) * ``-n``\ , ``--profile_name`` _PROFILE\ *NAME*\ : Name of the profile to be used in file names / plot titles. (default: *"Test Data"*\ ) * ``-m``\ , ``--misc_text`` _MISC\ *TEXT*\ : Text to be appended to the plot title. * ``-v``\ , ``--verbose``\ : Print debugging information. * ``--speedup``\ : When a user requests barplots, plot the speedup instead of the raw data value. * ``--ref_version`` *VERSION*\ : Use this version string as the reference dataset to compare the target against. * ``--ref_profile_name`` _PROFILE\ *NAME*\ : Use this profile name as the reference dataset to compare the target against. * ``--ref_plugin`` _PLUGIN\ *NAME*\ : Use this tree decider plugin as the reference dataset to compare the target against. (default: _power\ *governing*\ ) * ``--tgt_version`` *VERSION*\ : Use this version string as the target dataset to compare the reference against. * ``--tgt_name`` _PROFILE\ *NAME*\ : Use this profile name as the target dataset to compare the reference against. * ``--tgt_plugin`` _PLUGIN\ *NAME*\ : Use this tree decider plugin as the target dataset to compare the reference against. (default: _power\ *balancing*\ ) * ``--datatype`` *runtime*\ |\ *energy*\ |\ *frequency*\ |\ *count*\ : The datatype to be plotted. Only used for report file plots presently. (default: *runtime*\ ) * ``--smooth`` _NUM\ *SAMPLES*\ : Perform a _NUM\ *SAMPLES* moving average on on the Y-axis data. Only used for trace file plots presently. (default: *1*\ ) * ``--analyze``\ : Perform a basic analysis of the data plotted and save the statistics to a file. This applies to all trace plots, and additionally does the following to these specific plots: *power*\ : Plot the power cap and the aggregate power for all the nodes.\ :raw-html-m2r:`
` *epoch*\ : Adjust the Y-axis bounds to drop outlier data. * ``--min_drop`` _BUDGET\ *WATTS*\ : The minimum power budget for data to be included in the plot. All data below this threshold will be dropped. * ``--max_drop`` _BUDGET\ *WATTS*\ : The maximum power budget for data to be included in the plot. All data above this threshold will be dropped. * ``--base_clock`` _FREQ\ *GHZ*\ : The base clock frequency in GHz to be used when making calculations from the CLK counter data. * ``--focus_node`` _NODE\ *NAME*\ : The name of a node to focus on when generating per node plots. This node's data will be highlighted in red and will be drawn on top the other nodes. Analysis data will still be drawn on top of this line if enabled with ``--analyze``. * ``--show``\ : This will display an interactive plot using the default Matplotlib backend. * ``--cache`` _FILE\ *NAME*\ : Use _FILE\ *NAME* as the prefix for data cache files to try to load. If no files are found, data will be parsed and cache files will be written in the CWD. Glob patterns for report and trace files will be ignored if the cache files do not exist. In this case, all report files matching the "*report" pattern and all trace files matching the "*trace-*" pattern will be parsed. When used properly this drastically speeds up the time taken to create plots. WARNING: If the data used to generate the cache files changes, you must manually delete the corresponding .p files. That is, if _FILE\ *NAME* is "data", remove data_report.p and data_trace.p from the CWD. ENVIRONMENT ----------- * ``DISPLAY``\ : Because the geopmplotter relies on Matplotlib backends for creating plots, you may have to manually set this variable for proper functionality even if you are not displaying the interactive plot with ``-s``. E.g.: DISPLAY=:0 geopmplotter -v data * ``MPLBACKEND``\ : As an alternative to the above, you can set your backend to "Agg" using either: MPLBACKEND="Agg" geopmplotter -v data Or you may make the change permanently in your matplotlibrc file as described here:\ :raw-html-m2r:`
` _https://matplotlib.org/faq/usage_faq.html#what-is-a-backend_. The plotter will try to use the default backend (TkAgg), and fall back to Agg automatically if the default is not supported. Additional backends can be used by setting MPLBACKEND in the environment. Using either of these options will prevent ``--show`` from working properly. EXAMPLES -------- Once the geopmpy modules are installed, you can invoke this utility directly from the command line. You can either run the utility from inside a directory containing data, or from a remote directory. Some examples follow: Running the utility from the CWD plot the bar and box plots for the current dataset. By default, this assumes you have data utilizing the "static_policy" and "power_balancing" plugins. The verbose flag is added to show progress when parsing or plotting. .. code-block:: geopmplotter -vp box,bar Plot the epoch loop time comparison, frequency, and power plots. Note that this will parse all the trace files present in the CWD. This could take a considerable amount of time for a large dataset. Similar to the bar plot, the epoch plot assumes the data contains output from both the "static_policy" and "power_balancing" plugins. .. code-block:: geopmplotter -vp epoch,freq,power To plot a single plugin, use the ``--ref_plugin`` and ``--tgt_plugin`` options: .. code-block:: geopmplotter -vp epoch --ref_plugin static_policy --tgt_plugin static_policy Plot the trace based plots, though only parsing a subset of the trace files. In this instance, the trace files are named based on the global power budget that was set at the beginning of the run (e.g. 160-...-trace-\ :raw-html-m2r:``\ ). This can be significantly faster to parse for large datasets. .. code-block:: geopmplotter -vp epoch,freq,power -t "160*trace" The ``--cache`` flag can be used to save any parsed data into a Pickle file for expedited data loading on subsequent runs. Since the plotter will only parse data based on the requested plots, to parse and cache all the report and trace data you must request a set of plots that require both types of files. Presently the reports are needed for the bar and box plots while all other plots are based on the trace data. The following requests the bar and frequency plots, and saves the parsed data in all_report.p and all_trace.p. .. code-block:: geopmplotter -vp bar,freq --cache all If all_report.p or all_trace.p exist, they will be loaded and used. Otherwise, the data will be parsed as usual and then saved in these files. Utilizing the cache will dramatically speed up the time needed to create plots. If you need to re-parse your data, remove these files. Plot everything utilizing the cache. .. code-block:: geopmplotter -vp box,bar,epoch,freq,power --cache all Plot the speedup bar plot from 190W to 210W utilizing the cache. .. code-block:: geopmplotter -vp bar --speedup --min_drop 190 --max_drop 210 --cache all Use ``--analyze`` with the power plot to include the aggregate power and the power cap line. .. code-block:: geopmplotter -vp power --cache all --analyze SEE ALSO -------- `geopm(7) `_\ , `geopmpy(7) `_\ , **geopmanalysis(1)**\ , `geopmlaunch(1) `_\ ,