Update API docs (5c4bd3f).

facebookresearch · Aug 31, 2023 · 058fde7 · 058fde7
1 parent 366b4a4
commit 058fde7
Show file tree

Hide file tree

Showing 14 changed files with 522 additions and 438 deletions.
diff --git a/xml/Clustering_8h.xml b/xml/Clustering_8h.xml
diff --git a/xml/MatrixStats_8h.xml b/xml/MatrixStats_8h.xml
diff --git a/xml/index.xml b/xml/index.xml
@@ -398,7 +398,6 @@
     <member refid="structfaiss_1_1ClusteringParameters_1a993e0a035248faad6e292a5ef9af1953" kind="variable"><name>max_points_per_centroid</name></member>
     <member refid="structfaiss_1_1ClusteringParameters_1a509c65e2ebe6ecabebd163ecb03c5579" kind="variable"><name>seed</name></member>
     <member refid="structfaiss_1_1ClusteringParameters_1a46448d2ab0341faedc18a613264ad44f" kind="variable"><name>decode_block_size</name></member>
-    <member refid="structfaiss_1_1ClusteringParameters_1a86c8802261041f5d49b1a0d296da60be" kind="function"><name>ClusteringParameters</name></member>
   </compound>
   <compound refid="structfaiss_1_1CMax" kind="struct"><name>faiss::CMax</name>
     <member refid="structfaiss_1_1CMax_1a4b83239e1d9b4aced927ba7ff4173d00" kind="typedef"><name>T</name></member>
@@ -6145,6 +6144,7 @@
     <member refid="structfaiss_1_1MatrixStats_1a494ebb8acad6fc220fe80f8fd37f939e" kind="variable"><name>n0</name></member>
     <member refid="structfaiss_1_1MatrixStats_1af5c803ddc5c517af17711fde8538eb3a" kind="variable"><name>min_norm2</name></member>
     <member refid="structfaiss_1_1MatrixStats_1ad6486a75bcbaf34af5312adac36f7252" kind="variable"><name>max_norm2</name></member>
+    <member refid="structfaiss_1_1MatrixStats_1ae2023f2b43cecf40aee729283d0195c7" kind="variable"><name>hash_value</name></member>
     <member refid="structfaiss_1_1MatrixStats_1a00f2d2a3ea1ed81ff4a36b5cbdbe218b" kind="variable"><name>per_dim_stats</name></member>
     <member refid="structfaiss_1_1MatrixStats_1ae072d04f76165117f77bec53aa24fd1a" kind="variable"><name>occurrences</name></member>
     <member refid="structfaiss_1_1MatrixStats_1a29fd8accddea0e4ba5773c7a4353292b" kind="variable"><name>buf</name></member>
@@ -6549,7 +6549,6 @@
     <member refid="structfaiss_1_1MatrixStats_1_1PerDimStats_1a12c78f5ef7c6ffd2287f1184a03a88fe" kind="variable"><name>n_valid</name></member>
     <member refid="structfaiss_1_1MatrixStats_1_1PerDimStats_1a78d220cd08414efb1fb31c5181472a57" kind="variable"><name>mean</name></member>
     <member refid="structfaiss_1_1MatrixStats_1_1PerDimStats_1a4a8222891e00c0a34cf8c415d85b3034" kind="variable"><name>stddev</name></member>
-    <member refid="structfaiss_1_1MatrixStats_1_1PerDimStats_1a0974f23063edde22b5934008196b9c5b" kind="function"><name>PerDimStats</name></member>
     <member refid="structfaiss_1_1MatrixStats_1_1PerDimStats_1aa375fcebcf96dd460552e8a415d1d1b2" kind="function"><name>add</name></member>
     <member refid="structfaiss_1_1MatrixStats_1_1PerDimStats_1ab2b27edb089cbe1d2faca98cc82d2aa0" kind="function"><name>compute_mean_std</name></member>
   </compound>

diff --git a/xml/namespacefaiss.xml b/xml/namespacefaiss.xml
@@ -1073,7 +1073,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="185" column="7" declfile="faiss/Clustering.h" declline="185" declcolumn="7"/>
+        <location file="faiss/Clustering.h" line="195" column="7" declfile="faiss/Clustering.h" declline="195" declcolumn="7"/>
       </memberdef>
       <memberdef kind="function" id="namespacefaiss_1a9ea277840d6448e42b304287257de0b7" prot="public" static="no" const="no" explicit="no" inline="yes" virt="non-virtual">
         <templateparamlist>
@@ -9244,6 +9244,8 @@
 <para>Copyright (c) Facebook, Inc. and its affiliates.</para>
 <para>This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree.</para>
 <para>Copyright (c) Facebook, Inc. and its affiliates.</para>
+<para>This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. Implementation of k-means clustering with many variants.</para>
+<para>Copyright (c) Facebook, Inc. and its affiliates.</para>
 <para>This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. <ref refid="structfaiss_1_1IDSelector" kindref="compound">IDSelector</ref> is intended to define a subset of vectors to handle (for removal or as subset to search)</para>
 <para>Copyright (c) Facebook, Inc. and its affiliates.</para>
 <para>This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree. PQ4 SIMD packing and accumulation functions</para>

diff --git a/xml/structfaiss_1_1Clustering.xml b/xml/structfaiss_1_1Clustering.xml
diff --git a/xml/structfaiss_1_1Clustering1D.xml b/xml/structfaiss_1_1Clustering1D.xml
diff --git a/xml/structfaiss_1_1ClusteringIterationStats.xml b/xml/structfaiss_1_1ClusteringIterationStats.xml
@@ -15,7 +15,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="44" column="11" bodyfile="faiss/Clustering.h" bodystart="44" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="54" column="11" bodyfile="faiss/Clustering.h" bodystart="54" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringIterationStats_1a5e705d865d7e3c9ea224d1b7fb25c55e" prot="public" static="no" mutable="no">
         <type>double</type>
@@ -29,7 +29,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="45" column="12" bodyfile="faiss/Clustering.h" bodystart="45" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="55" column="12" bodyfile="faiss/Clustering.h" bodystart="55" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringIterationStats_1a4f851c82080b3ac7dfa70f84900c7e04" prot="public" static="no" mutable="no">
         <type>double</type>
@@ -43,7 +43,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="46" column="12" bodyfile="faiss/Clustering.h" bodystart="46" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="56" column="12" bodyfile="faiss/Clustering.h" bodystart="56" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringIterationStats_1a49d02abe2f1a02839461e58bf0819b01" prot="public" static="no" mutable="no">
         <type>double</type>
@@ -57,7 +57,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="47" column="12" bodyfile="faiss/Clustering.h" bodystart="47" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="57" column="12" bodyfile="faiss/Clustering.h" bodystart="57" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringIterationStats_1abd83b0cdd436033c0d93ddeebf0ff05f" prot="public" static="no" mutable="no">
         <type>int</type>
@@ -71,14 +71,14 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="48" column="9" bodyfile="faiss/Clustering.h" bodystart="48" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="58" column="9" bodyfile="faiss/Clustering.h" bodystart="58" bodyend="-1"/>
       </memberdef>
       </sectiondef>
     <briefdescription>
     </briefdescription>
     <detaileddescription>
     </detaileddescription>
-    <location file="faiss/Clustering.h" line="43" column="1" bodyfile="faiss/Clustering.h" bodystart="43" bodyend="49"/>
+    <location file="faiss/Clustering.h" line="53" column="1" bodyfile="faiss/Clustering.h" bodystart="53" bodyend="59"/>
     <listofallmembers>
       <member refid="structfaiss_1_1ClusteringIterationStats_1a49d02abe2f1a02839461e58bf0819b01" prot="public" virt="non-virtual"><scope>faiss::ClusteringIterationStats</scope><name>imbalance_factor</name></member>
       <member refid="structfaiss_1_1ClusteringIterationStats_1abd83b0cdd436033c0d93ddeebf0ff05f" prot="public" virt="non-virtual"><scope>faiss::ClusteringIterationStats</scope><name>nsplit</name></member>

diff --git a/xml/structfaiss_1_1ClusteringParameters.xml b/xml/structfaiss_1_1ClusteringParameters.xml
@@ -11,169 +11,164 @@
         <definition>int faiss::ClusteringParameters::niter</definition>
         <argsstring></argsstring>
         <name>niter</name>
+        <initializer>= 25</initializer>
         <briefdescription>
-<para>clustering iterations </para>
+<para>number of clustering iterations </para>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="22" column="9" bodyfile="faiss/Clustering.h" bodystart="22" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="23" column="9" bodyfile="faiss/Clustering.h" bodystart="23" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1a11a049c40c376c57ac6cc3b8d5d1d58b" prot="public" static="no" mutable="no">
         <type>int</type>
         <definition>int faiss::ClusteringParameters::nredo</definition>
         <argsstring></argsstring>
         <name>nredo</name>
+        <initializer>= 1</initializer>
         <briefdescription>
-<para>redo clustering this many times and keep best </para>
         </briefdescription>
         <detaileddescription>
+<para>redo clustering this many times and keep the clusters with the best objective </para>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="23" column="9" bodyfile="faiss/Clustering.h" bodystart="23" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="26" column="9" bodyfile="faiss/Clustering.h" bodystart="26" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1a932139ba9b62b37d9121b4c6a4518b52" prot="public" static="no" mutable="no">
         <type>bool</type>
         <definition>bool faiss::ClusteringParameters::verbose</definition>
         <argsstring></argsstring>
         <name>verbose</name>
+        <initializer>= false</initializer>
         <briefdescription>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="25" column="10" bodyfile="faiss/Clustering.h" bodystart="25" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="28" column="10" bodyfile="faiss/Clustering.h" bodystart="28" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1ad997fb511f574f7ddc69938c21612f8d" prot="public" static="no" mutable="no">
         <type>bool</type>
         <definition>bool faiss::ClusteringParameters::spherical</definition>
         <argsstring></argsstring>
         <name>spherical</name>
+        <initializer>= false</initializer>
         <briefdescription>
-<para>do we want normalized centroids? </para>
         </briefdescription>
         <detaileddescription>
+<para>whether to normalize centroids after each iteration (useful for inner product clustering) </para>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="26" column="10" bodyfile="faiss/Clustering.h" bodystart="26" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="31" column="10" bodyfile="faiss/Clustering.h" bodystart="31" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1ae01573d8d4cbff7c3d6eaded883537a4" prot="public" static="no" mutable="no">
         <type>bool</type>
         <definition>bool faiss::ClusteringParameters::int_centroids</definition>
         <argsstring></argsstring>
         <name>int_centroids</name>
+        <initializer>= false</initializer>
         <briefdescription>
-<para>round centroids coordinates to integer </para>
+<para>round centroids coordinates to integer after each iteration? </para>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="27" column="10" bodyfile="faiss/Clustering.h" bodystart="27" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="33" column="10" bodyfile="faiss/Clustering.h" bodystart="33" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1a27d6192097920fa981cff0acedfaac91" prot="public" static="no" mutable="no">
         <type>bool</type>
         <definition>bool faiss::ClusteringParameters::update_index</definition>
         <argsstring></argsstring>
         <name>update_index</name>
+        <initializer>= false</initializer>
         <briefdescription>
 <para>re-train index after each iteration? </para>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="28" column="10" bodyfile="faiss/Clustering.h" bodystart="28" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="35" column="10" bodyfile="faiss/Clustering.h" bodystart="35" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1ad142063e035f2a0414233f9711e16215" prot="public" static="no" mutable="no">
         <type>bool</type>
         <definition>bool faiss::ClusteringParameters::frozen_centroids</definition>
         <argsstring></argsstring>
         <name>frozen_centroids</name>
+        <initializer>= false</initializer>
         <briefdescription>
         </briefdescription>
         <detaileddescription>
-<para>use the centroids provided as input and do not change them during iterations </para>
+<para>Use the subset of centroids provided as input and do not change them during iterations </para>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="29" column="10" bodyfile="faiss/Clustering.h" bodystart="29" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="39" column="10" bodyfile="faiss/Clustering.h" bodystart="39" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1a5af907901147a9b1e748b13305839924" prot="public" static="no" mutable="no">
         <type>int</type>
         <definition>int faiss::ClusteringParameters::min_points_per_centroid</definition>
         <argsstring></argsstring>
         <name>min_points_per_centroid</name>
+        <initializer>= 39</initializer>
         <briefdescription>
-<para>otherwise you get a warning </para>
         </briefdescription>
         <detaileddescription>
+<para>If fewer than this number of training vectors per centroid are provided, writes a warning. Note that fewer than 1 point per centroid raises an exception. </para>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="32" column="9" bodyfile="faiss/Clustering.h" bodystart="32" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="43" column="9" bodyfile="faiss/Clustering.h" bodystart="43" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1a993e0a035248faad6e292a5ef9af1953" prot="public" static="no" mutable="no">
         <type>int</type>
         <definition>int faiss::ClusteringParameters::max_points_per_centroid</definition>
         <argsstring></argsstring>
         <name>max_points_per_centroid</name>
+        <initializer>= 256</initializer>
         <briefdescription>
-<para>to limit size of dataset </para>
+<para>to limit size of dataset, otherwise the training set is subsampled </para>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="33" column="9" bodyfile="faiss/Clustering.h" bodystart="33" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="45" column="9" bodyfile="faiss/Clustering.h" bodystart="45" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1a509c65e2ebe6ecabebd163ecb03c5579" prot="public" static="no" mutable="no">
         <type>int</type>
         <definition>int faiss::ClusteringParameters::seed</definition>
         <argsstring></argsstring>
         <name>seed</name>
+        <initializer>= 1234</initializer>
         <briefdescription>
 <para>seed for the random number generator </para>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="35" column="9" bodyfile="faiss/Clustering.h" bodystart="35" bodyend="-1"/>
+        <location file="faiss/Clustering.h" line="47" column="9" bodyfile="faiss/Clustering.h" bodystart="47" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structfaiss_1_1ClusteringParameters_1a46448d2ab0341faedc18a613264ad44f" prot="public" static="no" mutable="no">
         <type>size_t</type>
         <definition>size_t faiss::ClusteringParameters::decode_block_size</definition>
         <argsstring></argsstring>
         <name>decode_block_size</name>
+        <initializer>= 32768</initializer>
         <briefdescription>
-<para>how many vectors at a time to decode </para>
-        </briefdescription>
-        <detaileddescription>
-        </detaileddescription>
-        <inbodydescription>
-        </inbodydescription>
-        <location file="faiss/Clustering.h" line="37" column="12" bodyfile="faiss/Clustering.h" bodystart="37" bodyend="-1"/>
-      </memberdef>
-      </sectiondef>
-      <sectiondef kind="public-func">
-      <memberdef kind="function" id="structfaiss_1_1ClusteringParameters_1a86c8802261041f5d49b1a0d296da60be" prot="public" static="no" const="no" explicit="no" inline="no" virt="non-virtual">
-        <type></type>
-        <definition>faiss::ClusteringParameters::ClusteringParameters</definition>
-        <argsstring>()</argsstring>
-        <name>ClusteringParameters</name>
-        <briefdescription>
-<para>sets reasonable defaults </para>
+<para>when the training set is encoded, batch size of the codec decoder </para>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="faiss/Clustering.h" line="40" column="5"/>
+        <location file="faiss/Clustering.h" line="50" column="12" bodyfile="faiss/Clustering.h" bodystart="50" bodyend="-1"/>
       </memberdef>
       </sectiondef>
     <briefdescription>
@@ -211,9 +206,8 @@
         <link refid="structfaiss_1_1ClusteringParameters"/>
       </node>
     </inheritancegraph>
-    <location file="faiss/Clustering.h" line="21" column="1" bodyfile="faiss/Clustering.h" bodystart="21" bodyend="41"/>
+    <location file="faiss/Clustering.h" line="21" column="1" bodyfile="faiss/Clustering.h" bodystart="21" bodyend="51"/>
     <listofallmembers>
-      <member refid="structfaiss_1_1ClusteringParameters_1a86c8802261041f5d49b1a0d296da60be" prot="public" virt="non-virtual"><scope>faiss::ClusteringParameters</scope><name>ClusteringParameters</name></member>
       <member refid="structfaiss_1_1ClusteringParameters_1a46448d2ab0341faedc18a613264ad44f" prot="public" virt="non-virtual"><scope>faiss::ClusteringParameters</scope><name>decode_block_size</name></member>
       <member refid="structfaiss_1_1ClusteringParameters_1ad142063e035f2a0414233f9711e16215" prot="public" virt="non-virtual"><scope>faiss::ClusteringParameters</scope><name>frozen_centroids</name></member>
       <member refid="structfaiss_1_1ClusteringParameters_1ae01573d8d4cbff7c3d6eaded883537a4" prot="public" virt="non-virtual"><scope>faiss::ClusteringParameters</scope><name>int_centroids</name></member>