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 _REPORTBASE: The base report string to be searched. All files that are located in the PATH directory that begin with _REPORTBASE 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 _TRACEBASE: The base trace string to be searched. All files that are located in the PATH directory that begin with _TRACEBASE 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 _OUTPUTDIR: 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 _PROFILENAME: Name of the profile to be used in file names / plot titles. (default: "Test Data")

  • -m, --misc_text _MISCTEXT: 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 _PROFILENAME: Use this profile name as the reference dataset to compare the target against.

  • --ref_plugin _PLUGINNAME: Use this tree decider plugin as the reference dataset to compare the target against. (default: _powergoverning)

  • --tgt_version VERSION: Use this version string as the target dataset to compare the reference against.

  • --tgt_name _PROFILENAME: Use this profile name as the target dataset to compare the reference against.

  • --tgt_plugin _PLUGINNAME: Use this tree decider plugin as the target dataset to compare the reference against. (default: _powerbalancing)

  • --datatype runtime|energy|frequency|count: The datatype to be plotted. Only used for report file plots presently. (default: runtime)

  • --smooth _NUMSAMPLES: Perform a _NUMSAMPLES 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.
     epoch: Adjust the Y-axis bounds to drop outlier data.

  • --min_drop _BUDGETWATTS: The minimum power budget for data to be included in the plot. All data below this threshold will be dropped.

  • --max_drop _BUDGETWATTS: The maximum power budget for data to be included in the plot. All data above this threshold will be dropped.

  • --base_clock _FREQGHZ: The base clock frequency in GHz to be used when making calculations from the CLK counter data.

  • --focus_node _NODENAME: 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 _FILENAME: Use _FILENAME 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 _FILENAME 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:
     _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.

 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.

 geopmplotter -vp epoch,freq,power


To plot a single plugin, use the ``--ref_plugin`` and ``--tgt_plugin`` options:

 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:`<NODENAME>`\ ).  This can be significantly
faster to parse for large datasets.

 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.

 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.

 geopmplotter -vp box,bar,epoch,freq,power --cache all


Plot the speedup bar plot from 190W to 210W utilizing the cache.

 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.

geopmplotter -vp power --cache all --analyze

SEE ALSO

geopm(7), geopmpy(7), geopmanalysis(1), geopmlaunch(1),