Docs update: c549877

[email protected] [doc] Clarified output modification for expand operation (#815)
intel · Dec 12, 2023 · 0f9fdf4 · 0f9fdf4
1 parent 00cc774
commit 0f9fdf4
Show file tree

Hide file tree

Showing 52 changed files with 27 additions and 11 deletions.
diff --git a/.doctrees/documentation/bench_docs/guide.doctree b/.doctrees/documentation/bench_docs/guide.doctree
diff --git a/.doctrees/documentation/contributing_docs/issue_reporting.doctree b/.doctrees/documentation/contributing_docs/issue_reporting.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/advanced/c_advanced_topics.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/advanced/c_advanced_topics.doctree
diff --git a/...es/documentation/dev_guide_docs/c_use_cases/advanced/c_advanced_topics_decompress.doctree b/...es/documentation/dev_guide_docs/c_use_cases/advanced/c_advanced_topics_decompress.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/advanced/c_advanced_topics_filter.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/advanced/c_advanced_topics_filter.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/c_asynchronous_execution.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/c_asynchronous_execution.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/c_huffman_only.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/c_huffman_only.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/c_job_structure.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/c_job_structure.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/c_use_huffman_tables.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/c_use_huffman_tables.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_compression.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_compression.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_decompression.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_decompression.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_dictionary.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_dictionary.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_indexing.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_indexing.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_indexing_format.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_indexing_format.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_indexing_usage.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_indexing_usage.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_multiple_jobs.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_multiple_jobs.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_zlib_gzip.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/deflate/c_deflate_zlib_gzip.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations.doctree
diff --git a/...trees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_aggregates.doctree b/...trees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_aggregates.doctree
diff --git a/...mentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_hw_path_optimization.doctree b/...mentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_hw_path_optimization.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_crc64.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_crc64.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_expand.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_expand.doctree
diff --git a/...trees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_extract.doctree b/...trees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_extract.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_scan.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_scan.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_select.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_select.doctree
diff --git a/...umentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_output_modification.doctree b/...umentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_output_modification.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_parsers.doctree b/.doctrees/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_parsers.doctree
diff --git a/.doctrees/documentation/dev_guide_docs/low_level_developer_guide.doctree b/.doctrees/documentation/dev_guide_docs/low_level_developer_guide.doctree
diff --git a/.doctrees/documentation/dev_ref_docs/c_ref/c_common_definitions.doctree b/.doctrees/documentation/dev_ref_docs/c_ref/c_common_definitions.doctree
diff --git a/.doctrees/documentation/dev_ref_docs/c_ref/c_huffman_table_apis.doctree b/.doctrees/documentation/dev_ref_docs/c_ref/c_huffman_table_apis.doctree
diff --git a/.doctrees/documentation/dev_ref_docs/c_ref/c_job_apis.doctree b/.doctrees/documentation/dev_ref_docs/c_ref/c_job_apis.doctree
diff --git a/.doctrees/documentation/dev_ref_docs/c_ref/c_status_codes.doctree b/.doctrees/documentation/dev_ref_docs/c_ref/c_status_codes.doctree
diff --git a/.doctrees/documentation/dev_ref_docs/low_level_api.doctree b/.doctrees/documentation/dev_ref_docs/low_level_api.doctree
diff --git a/.doctrees/documentation/get_started_docs/code_examples.doctree b/.doctrees/documentation/get_started_docs/code_examples.doctree
diff --git a/.doctrees/documentation/get_started_docs/compression_decompression.doctree b/.doctrees/documentation/get_started_docs/compression_decompression.doctree
diff --git a/.doctrees/documentation/get_started_docs/filter_and_other_operations.doctree b/.doctrees/documentation/get_started_docs/filter_and_other_operations.doctree
diff --git a/.doctrees/documentation/get_started_docs/installation.doctree b/.doctrees/documentation/get_started_docs/installation.doctree
diff --git a/.doctrees/documentation/get_started_docs/quick_start.doctree b/.doctrees/documentation/get_started_docs/quick_start.doctree
diff --git a/.doctrees/documentation/get_started_docs/testing.doctree b/.doctrees/documentation/get_started_docs/testing.doctree
diff --git a/.doctrees/documentation/introduction_docs/introduction.doctree b/.doctrees/documentation/introduction_docs/introduction.doctree
diff --git a/.doctrees/documentation/introduction_docs/legal.doctree b/.doctrees/documentation/introduction_docs/legal.doctree
diff --git a/.doctrees/environment.pickle b/.doctrees/environment.pickle
diff --git a/.doctrees/index.doctree b/.doctrees/index.doctree
diff --git a/.../documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_expand.rst b/.../documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_expand.rst
@@ -17,12 +17,16 @@ If you take the output of expand and perform a select operation on it
 (with the same bit vector as ``source-2``),
 then you get back the same data as the original ``source-1``.
 
+.. note::
+
+  The output of expand may not be in a format readable by the select operation
+  (for example, in the case mentioned in :ref:`analytics_output_modifications_nominal_bit_vector_reference_link`)
 
 In this operation, the bit-width of the output is the same as the bit
-width of ``source-1``, but the number of output elements is equal to the
-number of input elements on ``source-2``. So for this operation, the job
-field :c:member:`qpl_job.num_input_elements` actually contains the number of elements in
-``source-2`` rather than ``source-1``.
+width of ``source-1`` (unless explicitly changed by :c:member:`qpl_job.out_bit_width`)
+but the number of output elements is equal to the number of input elements on
+``source-2``. So for this operation, the job field :c:member:`qpl_job.num_input_elements`
+actually contains the number of elements in ``source-2`` rather than ``source-1``.
 
 Each 0-bit from ``source-2`` writes a zero to the output. Each 1-bit writes
 the next entry from ``source-1``.
diff --git a/...tion/dev_guide_docs/c_use_cases/filter_ops/c_operations_output_modification.rst b/...tion/dev_guide_docs/c_use_cases/filter_ops/c_operations_output_modification.rst
@@ -20,6 +20,8 @@ corresponds to no output modification. The other three values invoke
 output modification.
 
 
+.. _analytics_output_modifications_nominal_bit_vector_reference_link:
+
 Output Modification for Nominal Bit Vector Output
 *************************************************
 

diff --git a/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_expand.html b/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_op_expand.html
@@ -417,11 +417,16 @@ <h1>Expand</h1>
 If you take the output of expand and perform a select operation on it
 (with the same bit vector as <code class="docutils literal notranslate"><span class="pre">source-2</span></code>),
 then you get back the same data as the original <code class="docutils literal notranslate"><span class="pre">source-1</span></code>.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The output of expand may not be in a format readable by the select operation
+(for example, in the case mentioned in <a class="reference internal" href="c_operations_output_modification.html#analytics-output-modifications-nominal-bit-vector-reference-link"><span class="std std-ref">Output Modification for Nominal Bit Vector Output</span></a>)</p>
+</div>
 <p>In this operation, the bit-width of the output is the same as the bit
-width of <code class="docutils literal notranslate"><span class="pre">source-1</span></code>, but the number of output elements is equal to the
-number of input elements on <code class="docutils literal notranslate"><span class="pre">source-2</span></code>. So for this operation, the job
-field <a class="reference internal" href="../../../dev_ref_docs/c_ref/c_job_apis.html#c.qpl_job.num_input_elements" title="qpl_job.num_input_elements"><code class="xref c c-member docutils literal notranslate"><span class="pre">qpl_job.num_input_elements</span></code></a> actually contains the number of elements in
-<code class="docutils literal notranslate"><span class="pre">source-2</span></code> rather than <code class="docutils literal notranslate"><span class="pre">source-1</span></code>.</p>
+width of <code class="docutils literal notranslate"><span class="pre">source-1</span></code> (unless explicitly changed by <a class="reference internal" href="../../../dev_ref_docs/c_ref/c_job_apis.html#c.qpl_job.out_bit_width" title="qpl_job.out_bit_width"><code class="xref c c-member docutils literal notranslate"><span class="pre">qpl_job.out_bit_width</span></code></a>)
+but the number of output elements is equal to the number of input elements on
+<code class="docutils literal notranslate"><span class="pre">source-2</span></code>. So for this operation, the job field <a class="reference internal" href="../../../dev_ref_docs/c_ref/c_job_apis.html#c.qpl_job.num_input_elements" title="qpl_job.num_input_elements"><code class="xref c c-member docutils literal notranslate"><span class="pre">qpl_job.num_input_elements</span></code></a>
+actually contains the number of elements in <code class="docutils literal notranslate"><span class="pre">source-2</span></code> rather than <code class="docutils literal notranslate"><span class="pre">source-1</span></code>.</p>
 <p>Each 0-bit from <code class="docutils literal notranslate"><span class="pre">source-2</span></code> writes a zero to the output. Each 1-bit writes
 the next entry from <code class="docutils literal notranslate"><span class="pre">source-1</span></code>.</p>
 </section>

diff --git a/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_output_modification.html b/documentation/dev_guide_docs/c_use_cases/filter_ops/c_operations_output_modification.html
@@ -430,7 +430,7 @@ <h2> Contents </h2>
 corresponds to no output modification. The other three values invoke
 output modification.</p>
 <section id="output-modification-for-nominal-bit-vector-output">
-<h2>Output Modification for Nominal Bit Vector Output<a class="headerlink" href="#output-modification-for-nominal-bit-vector-output" title="Permalink to this heading">#</a></h2>
+<span id="analytics-output-modifications-nominal-bit-vector-reference-link"></span><h2>Output Modification for Nominal Bit Vector Output<a class="headerlink" href="#output-modification-for-nominal-bit-vector-output" title="Permalink to this heading">#</a></h2>
 <p>In case of nominal bit vector output, when the bit vector is expected to
 be sparse, it may be more efficient to represent the bit vector as a
 list of indices of those bits that are 1 rather than as a dense bit

diff --git a/documentation/get_started_docs/compression_decompression.html b/documentation/get_started_docs/compression_decompression.html
@@ -1223,6 +1223,8 @@ <h2><a class="toc-backref" href="#id6" role="doc-backlink">Compression with Dict
 <span class="k">constexpr</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">source_size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2048</span><span class="p">;</span>
 
 <span class="k">auto</span><span class="w"> </span><span class="n">main</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="kt">char</span><span class="o">**</span><span class="w"> </span><span class="n">argv</span><span class="p">)</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">{</span>
+<span class="w">    </span><span class="n">std</span><span class="o">::</span><span class="n">cout</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="s">&quot;Intel(R) Query Processing Library version is &quot;</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="n">qpl_get_library_version</span><span class="p">()</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="s">&quot;.</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">;</span>
+
 <span class="w">    </span><span class="c1">// Default to Software Path</span>
 <span class="w">    </span><span class="n">qpl_path_t</span><span class="w"> </span><span class="n">execution_path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">qpl_path_software</span><span class="p">;</span>
 
@@ -1271,10 +1273,13 @@ <h2><a class="toc-backref" href="#id6" role="doc-backlink">Compression with Dict
 <span class="w">        </span><span class="n">hw_compr_level</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">hw_compression_level</span><span class="o">::</span><span class="n">HW_LEVEL_1</span><span class="p">;</span>
 <span class="w">    </span><span class="p">}</span>
 
+<span class="w">    </span><span class="c1">// To build the dictionary, users must provide a raw dictionary.</span>
 <span class="w">    </span><span class="c1">// To better improve the compression ratio with dictionary, users should</span>
 <span class="w">    </span><span class="c1">// set raw_dict_size to the maximum size of the raw dictionary,</span>
 <span class="w">    </span><span class="c1">// refer to Intel® Query Processing Library (Intel® QPL) documentation.</span>
-<span class="w">    </span><span class="c1">// In this example, we use the source data as the raw dictionary</span>
+<span class="w">    </span><span class="c1">// The raw dictionary should contain pieces of data that are most likely to occur in the real</span>
+<span class="w">    </span><span class="c1">// datasets to be compressed.</span>
+<span class="w">    </span><span class="c1">// In this example, to make things simple, we just use the source data as the raw dictionary.</span>
 <span class="w">    </span><span class="n">raw_dict_size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">source</span><span class="p">.</span><span class="n">size</span><span class="p">();</span>
 <span class="w">    </span><span class="k">const</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="o">*</span><span class="n">raw_dict_ptr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">source</span><span class="p">.</span><span class="n">data</span><span class="p">();</span>
 <span class="w">    </span><span class="n">dictionary_buffer_size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">qpl_get_dictionary_size</span><span class="p">(</span><span class="n">sw_compr_level</span><span class="p">,</span>

diff --git a/objects.inv b/objects.inv
diff --git a/searchindex.js b/searchindex.js