Refactoring XQuant_Extension_Tool Documents (#1646)

* refactoring XQuant_Extension_Tool.rst

Author: ueno-hiroshi002

docs/_sources/guidelines/XQuant_Extension_Tool.rst.txt

@@ -1,7 +1,7 @@
 .. _ug-index:
 
 ========================================================================================
-TroubleShooting Documentation (MCT XQuant Extension Tool)
+TroubleShooting Manual (MCT XQuant Extension Tool)
 ========================================================================================
 
 
@@ -12,8 +12,9 @@ The Model Compression Toolkit (MCT) offers numerous functionalities to compress
 
 Outlined below are a series of steps aimed at recovering lost accuracy resulting from compression with MCT. Some steps may be applicable to your model, while others may not.
 
+For overview of XQuant Extension Tool, see `About XQuant Extension Tool <https://sonysemiconductorsolutions.github.io/mct-model-optimization/guidelines/XQuant_Extension_Tool.html>`_ [1].
 
-Quantization Troubleshooting for MCT[1]
+Quantization Troubleshooting for MCT
 ============================================
 
 **1. Judgeable Troubleshoots**
@@ -48,6 +49,4 @@ If quantization accuracy of your model does not improve after reading Judgeable
 
 References
 ============================================
-[1] `Quantization Troubleshooting for MCT <https://github.com/SonySemiconductorSolutions/mct-model-optimization/tree/main/quantization_troubleshooting.md>`_
-
-[2] `PyTorch documentation (v2.5) <https://docs.pytorch.org/docs/2.5/index.html>`_
+[1] `XQuant Extension (MCT Document) <https://sonysemiconductorsolutions.github.io/mct-model-optimization/guidelines/XQuant_Extension_Tool.html>`_

docs/docs_troubleshoot/_sources/index.rst.txt

@@ -15,7 +15,7 @@ Such outliers can mess up the selection of quantization parameters.
 
 Trouble Situation
 ==============================
-The quantization accuracy may degrade when there are outlier activations in the quantized layers of your model.
+The quantization accuracy may degrade when there are outliers (activation values far from the average activation of representative dataset) in the quantized layers of your model.
 
 For example, you can check if activation tensors have outliers by visualizing the histograms in TensorBoard(**thresholds_selection** in the below image).
 
@@ -32,3 +32,22 @@ Set ``z_threshold`` to a value. Typical value range is between 5.0 and 20.0.
 
     core_config = mct.core.CoreConfig(mct.core.QuantizationConfig(z_threshold=8.0))
     quantized_model, _ = mct.ptq.pytorch_post_training_quantization(..., core_config=core_config)
+
+Appendix: How to Read the Outlier Histograms
+=======================================================
+After execution XQuant Extension Tool, it makes the histograms for the degraded layers containing the detected outliers.
+The histograms are saved in a directory named “outlier_histgrams” created in the path specified in XQuantConfig.report_dir.
+
+.. image:: ../images/outlier.png
+
+* **First X-axis(lower part)**: Indicates bins that finely divide the range of data values.
+* **Second X-axis(upper part)**: Shows the z-score values corresponding to the primary X-axis.
+* **Red dashed line**: The z-score threshold set in XQuantConfig.
+* **Black dashed line**
+
+  * **Lower zscore**: Indicates the maximum value on the lower side of the histogram.
+  * **Upper zscore**: Indicates the maximum value on the upper side of the histogram.
+
+An example of a histogram detected by Outlier Removal is shown.
+In this example, outliers appear in the range from about 3.9 to 5.3 on the lower end of the z-score.
+Therefore, setting the z-score threshold to 3.9 will allow these outliers to be removed.

docs/docs_troubleshoot/_sources/troubleshoots/outlier_removal.rst.txt

@@ -23,12 +23,6 @@ The quantization accuracy may degrade when your model contains the following lay
 * torch.nn.SiLU / torch.nn.functional.silu
 * torch.nn.GELU / torch.nn.functional.gelu
 
-Example: `PReLU <https://docs.pytorch.org/docs/2.5/generated/torch.nn.PReLU.html>`_ [2]
-
-
-.. image:: ../images/PReLU.png
-  :scale: 40%
-
 Solution
 =================================
 Shifting negative values to positive values can improve quantization error (saving an extra 1bit).

docs/docs_troubleshoot/_sources/troubleshoots/shift_negative_activation.rst.txt

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
 
-    <title>TroubleShooting Documentation (MCT XQuant Extension Tool) &#8212; TroubleShooting Documentation (MCT XQuant Extension Tool): ver 1.0</title>
+    <title>TroubleShooting Manual (MCT XQuant Extension Tool) &#8212; TroubleShooting Documentation (MCT XQuant Extension Tool): ver 1.0</title>
     <link rel="stylesheet" type="text/css" href="static/pygments.css?v=03e43079" />
     <link rel="stylesheet" type="text/css" href="static/bizstyle.css?v=5283bb3d" />
     <link rel="stylesheet" type="text/css" href="static/css/custom.css?v=01243f34" />
@@ -29,7 +29,7 @@ <h3>Navigation</h3>
           <a href="genindex.html" title="General Index"
              accesskey="I">index</a></li>
         <li class="nav-item nav-item-0"><a href="#">TroubleShooting Documentation (MCT XQuant Extension Tool): ver 1.0</a> &#187;</li>
-        <li class="nav-item nav-item-this"><a href="">TroubleShooting Documentation (MCT XQuant Extension Tool)</a></li> 
+        <li class="nav-item nav-item-this"><a href="">TroubleShooting Manual (MCT XQuant Extension Tool)</a></li> 
       </ul>
     </div>  
 
@@ -38,15 +38,16 @@ <h3>Navigation</h3>
         <div class="bodywrapper">
           <div class="body" role="main">
 
-  <section id="troubleshooting-documentation-mct-xquant-extension-tool">
-<span id="ug-index"></span><h1>TroubleShooting Documentation (MCT XQuant Extension Tool)<a class="headerlink" href="#troubleshooting-documentation-mct-xquant-extension-tool" title="Link to this heading">¶</a></h1>
+  <section id="troubleshooting-manual-mct-xquant-extension-tool">
+<span id="ug-index"></span><h1>TroubleShooting Manual (MCT XQuant Extension Tool)<a class="headerlink" href="#troubleshooting-manual-mct-xquant-extension-tool" title="Link to this heading">¶</a></h1>
 <section id="overview">
 <h2>Overview<a class="headerlink" href="#overview" title="Link to this heading">¶</a></h2>
 <p>The Model Compression Toolkit (MCT) offers numerous functionalities to compress neural networks with minimal accuracy lost. However, in some cases, the compressed model may experience a significant decrease in accuracy. Fear not, as this lost accuracy can often be reclaimed by adjusting the quantization configuration or setup.</p>
 <p>Outlined below are a series of steps aimed at recovering lost accuracy resulting from compression with MCT. Some steps may be applicable to your model, while others may not.</p>
+<p>For overview of XQuant Extension Tool, see <a class="reference external" href="https://sonysemiconductorsolutions.github.io/mct-model-optimization/guidelines/XQuant_Extension_Tool.html">About XQuant Extension Tool</a> [1].</p>
 </section>
-<section id="quantization-troubleshooting-for-mct-1">
-<h2>Quantization Troubleshooting for MCT[1]<a class="headerlink" href="#quantization-troubleshooting-for-mct-1" title="Link to this heading">¶</a></h2>
+<section id="quantization-troubleshooting-for-mct">
+<h2>Quantization Troubleshooting for MCT<a class="headerlink" href="#quantization-troubleshooting-for-mct" title="Link to this heading">¶</a></h2>
 <p><strong>1. Judgeable Troubleshoots</strong></p>
 <p>The following items are automatically identified by the XQuant Extension Tool.</p>
 <p>Please read the following items indicated by XQuant Extension Tool, especially the <strong>Solution</strong> section.</p>
@@ -76,8 +77,7 @@ <h2>Quantization Troubleshooting for MCT[1]<a class="headerlink" href="#quantiza
 </section>
 <section id="references">
 <h2>References<a class="headerlink" href="#references" title="Link to this heading">¶</a></h2>
-<p>[1] <a class="reference external" href="https://github.com/SonySemiconductorSolutions/mct-model-optimization/tree/main/quantization_troubleshooting.md">Quantization Troubleshooting for MCT</a></p>
-<p>[2] <a class="reference external" href="https://docs.pytorch.org/docs/2.5/index.html">PyTorch documentation (v2.5)</a></p>
+<p>[1] <a class="reference external" href="https://sonysemiconductorsolutions.github.io/mct-model-optimization/guidelines/XQuant_Extension_Tool.html">XQuant Extension (MCT Document)</a></p>
 </section>
 </section>
 
@@ -91,9 +91,9 @@ <h2>References<a class="headerlink" href="#references" title="Link to this headi
   <div>
     <h3><a href="#">Table of Contents</a></h3>
     <ul>
-<li><a class="reference internal" href="#">TroubleShooting Documentation (MCT XQuant Extension Tool)</a><ul>
+<li><a class="reference internal" href="#">TroubleShooting Manual (MCT XQuant Extension Tool)</a><ul>
 <li><a class="reference internal" href="#overview">Overview</a></li>
-<li><a class="reference internal" href="#quantization-troubleshooting-for-mct-1">Quantization Troubleshooting for MCT[1]</a></li>
+<li><a class="reference internal" href="#quantization-troubleshooting-for-mct">Quantization Troubleshooting for MCT</a></li>
 <li><a class="reference internal" href="#references">References</a></li>
 </ul>
 </li>
@@ -121,7 +121,7 @@ <h3>Navigation</h3>
           <a href="genindex.html" title="General Index"
              >index</a></li>
         <li class="nav-item nav-item-0"><a href="#">TroubleShooting Documentation (MCT XQuant Extension Tool): ver 1.0</a> &#187;</li>
-        <li class="nav-item nav-item-this"><a href="">TroubleShooting Documentation (MCT XQuant Extension Tool)</a></li> 
+        <li class="nav-item nav-item-this"><a href="">TroubleShooting Manual (MCT XQuant Extension Tool)</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">