tools ppa 工具
================

ppa 工具概述
::::::::::::::::

tools ppa 是 tools 工具包中用于解析 ppa 数据以分析两个不同 case PPA 数据集的性能变化趋势的工具.

其输入是两组 case 数据, 这两组数据是由用户指定的 RainaSynth 在指定 tag 下执行 case 后的输出. 用户可能
使用的是同一个 RainaSynth, 也可能使用的是两个不同的 RainaSynth, 故该工具可用于如下两种情况.

测试同一个版本的 RainaSynth 在不同优化指令下的性能差异
    使用 **同一版本 commit 的 RainaSynth**, 指定两组不同的 tag(synth level + opt level), 执行后将输出两组
    不同的 case 数据, 这两组数据之间的差异显示了 该版本的 RainaSynth 在不同的综合等级和优化等级下 PPA 的差异情况.

测试不同版本的 RainaSynth 在相同优化指令下的性能差异
    使用 **不同版本的 commit**, 此时将编译出 **两个版本的 RainaSynth** 并指定相同的 tag, 执行后将输出两组
    不同的 case 数据, 这两组数据之间的差异即两个 版本的 RainaSynth 之间的性能差异情况.

ppa 工具基础使用教程
:::::::::::::::::::::::::

Tools ppa 工具的要求输入两个版本 RainaSynth 的 ppa 数据, 因此, 在执行 tools ppa 工具之前, 需要先准备两个版本 RainaSynth 的 ppa 数据.

1. 获取新版本 RainaSynth 输出的 ppa 数据

.. code::

    # 以 2023-12-20 的 Nightly RainaSynth 为例
    export RAINA_PATH=/homecloud/public/Nightly_Raina/2023-12-20/release/bin/RainaSynth

    # 此时将生成一个带有时间戳的 case 目录文件 RegressionSystem_TempGit_xxxx
    nabu --remote --record

    # 可更名为 golden
    mv ./RegressionSystem_TempGit_xxxx golden

2. 获取新版本 RainaSynth 输出的 ppa 数据

.. code::

   # 假定此处使用的是用户自行编译的最新版本的 RainaSynth
   export RAINA_PATH={HOME}/Thor/bin/RainaSynth

   # 此时将生成一个带有时间戳的 case 目录文件 RegressionSystem_TempGit_xxxx
   nabu --remote --record

   # 可更名为 target
   mv ./RegressionSystem_TempGit_xxxx target

3. 执行 tools ppa 工具进行解析.

.. code:: 

   tools ppa golden target

tools ppa 工具输出效果图如下所示, 其输出分为两部分, 上部分为单个 case 的 PPA 数据的变化趋势和数值变化, 下部分
为总体 case 的 PPA 数据的变化趋势并按从坏到好的程度进行排序.

.. image:: ../images/ppa_result.png

ppa 工具进阶使用教程
:::::::::::::::::::::::::

tools ppa 工具的 help 文档如下:

.. code:: 

    [root@dev02 Thor]$ tools ppa --help
    Usage: tools ppa [OPTIONS] GOLDEN TARGET

    Perform ppa data analysis based on the case data generated by nabu, and the
    weight can be specified.

    Options:
    --no_detail       Whether to disalble display the details of a single case.
                        Defaults to True
    --weight TEXT     Custom weight file path
    --save_file TEXT  Specify the file to save the data of ppa tool.
    --help            Show this message and exit.

-\-no_detail
------------------------------

指定 tools ppa 分析工具不显示单个 case 的详细数据, 仅显示 case 数据汇总图. 效果图如下:

.. image:: ../images/ppa_result_without_detail.png

-\-weight
------------------------------

指定 ppa 分析工具使用自定义的 weight 文件, 可参考 :ref:`PPA weight 文件的使用 <ppa_weight>`.

.. code:: 

    # 使用用户自定义的权重文件 my_weight.json
    tools ppa golden target --weight my_weight.json

-\-save_file
------------------------------

指定用于保存 ppa 分析过程产生的中间数据的文件名, 一般用户不需要使用, 这些数据可用于 case-manager 或加速
现有的 case 的 ppa 数据分析.

-\-help
------------------------------

查看 help 文档, 其指令如下:

.. code:: 

   tools ppa --help

.. _ppa_weight:

PPA weight 文件使用
::::::::::::::::::::::::::::::

weight 文件是一个 json 文件, 用户可以通过 tools ppa-gen 指令先生成一个默认的 weight 文件, 在此基础上
进行修改. 未指定时, ppa 工具将使用默认的权重数据, 此时 ppa 工具将仅关注 PPA 数据中的 WNS / TNS 数据.

.. code:: 

    # 生成默认的 weight 数据, 生成 weight.json 文件
    tools ppa-gen

    # 也可以指定生成文件的名字
    tools ppa-gen --output my_weight.json

    # 更改 my_weight.json 文件中的权重.

1. 在权重文件中, 可按用户需求自定义修改权重, 当权重为 0 时, 该数据将不进行 ppa 数据分析.
2. 当某个数据越大表示性能越好时, 权重应该为正数, 如 WNS, TNS.
3. 当某个数据越小表示性能越好时, 权重应该为负数, 如 area, power 相关指标.

权重文件预览如下:

.. image:: ../images/ppa_weight.png