PrologMethods/Geometry/kfn.md

@@ -2,26 +2,42 @@
 
 An implementation of k-furthest-neighbor search using single-tree and dual-tree algorithms. Given a set of reference points and query points, this can find the k furthest neighbors in the reference set of each query point using trees.
 
+```prolog
+:- use_module('path/to/.../src/methods/kfn/kfn.pl').
+
+%% usage example
+TrainData = [5.1,3.5,1.4, 4.9,3.0,1.4, 4.7,3.2,1.3, 4.6,3.1,1.5],
+TestData = [3,2,0, 5,1,4, 0,0,4, 3,3,5, 0,5,5, 2,5,5],
+kfn_initAndBuildModel(kd, dual_tree, 0, 20, 0.0, TrainData, 3),
+kfn_searchWithQuery(TestData, 3, 2, NeighborsList, _, DistancesList, _).
+```
+
 # Available Predicates
 
-* [initAndBuildModel/8](/PrologMethods/Geometry/kfn#initandbuildmodel8)
-* [searchWithQuery/10](/PrologMethods/Geometry/kfn#searchwithquery10)
-* [searchNoQuery/7](/PrologMethods/Geometry/kfn#searchnoquery7)
+* [kfn_initAndBuildModel/7](/PrologMethods/Geometry/kfn#kfn_initandbuildmodel7)
+* [kfn_searchWithQuery/7](/PrologMethods/Geometry/kfn#kfn_searchwithquery7)
+* [kfn_searchNoQuery/5](/PrologMethods/Geometry/kfn#kfn_searchnoquery5)
 
 ---
 
 [links/resources](/PrologMethods/Geometry/kfn#connected-linksresources)
 
-## **_initAndBuildModel/8_**
+## **_kfn_initAndBuildModel/7_**
 
 Initialize the Model and build it.
 
 ```prolog
-%% part of the predicate definition
-initAndBuildModel(  +string, +string,
-                    +integer, 
-                    +integer, +float32,
-                    +pointer(float_array), +integer, +integer).
+%% predicate definition 
+kfn_initAndBuildModel(TreeType, SearchMode, RandomBasis, LeafSize, Epsilon, ReferenceList, ReferenceRows) :-
+        LeafSize >= 1,
+        Epsilon >= 0,
+        convert_list_to_float_array(ReferenceList, ReferenceRows, array(Xsize, Xrownum, X)),
+        initAndBuildModelI(TreeType, SearchMode, RandomBasis, LeafSize, Epsilon, X, Xsize, Xrownum).
+
+%% foreign c++ predicate definition 
+foreign(initAndBuildModel, c, initAndBuildModelI( +string, +string,
+                                                  +integer, +integer, +float32,
+                                                  +pointer(float_array), +integer, +integer)).
 ```
 
 ### Parameters
@@ -36,16 +52,24 @@ initAndBuildModel(  +string, +string,
 
 ---
 
-## **_searchWithQuery/10_**
+## **_kfn_searchWithQuery/7_**
 
 Perform neighbor search on the queryset.
 
 ```prolog
-%% part of the predicate definition
-searchWithQuery(  +pointer(float_array), +integer, +integer,
+%% predicate definition 
+kfn_searchWithQuery(QueryList, QueryRows, K, NeighborsList, YCols, DistancesList, ZCols) :-
+        K > 0,
+        convert_list_to_float_array(QueryList, QueryRows, array(Xsize, Xrownum, X)),
+        searchWithQueryI(X, Xsize, Xrownum, K, Y, YCols, YRows, Z, ZCols, ZRows),
+        convert_float_array_to_2d_list(Y, YCols, YRows, NeighborsList),
+        convert_float_array_to_2d_list(Z, ZCols, ZRows, DistancesList).
+
+%% foreign c++ predicate definition 
+foreign(searchWithQuery, c, searchWithQueryI( +pointer(float_array), +integer, +integer,
                                               +integer,
                                               -pointer(float_array), -integer, -integer,
-                  -pointer(float_array), -integer, -integer)
+                                              -pointer(float_array), -integer, -integer)).
 ```
 
 ### Parameters
@@ -58,15 +82,22 @@ searchWithQuery(  +pointer(float_array), +integer, +integer,
 
 ---
 
-## **_searchNoQuery/7_**
+## **_kfn_searchNoQuery/5_**
 
 Perform monochromatic neighbor search.
 
 ```prolog
-%% part of the predicate definition
-searchNoQuery(  +integer,
+%% predicate definition 
+kfn_searchNoQuery(K, NeighborsList, YCols, DistancesList, ZCols) :-
+        K > 0,
+        searchNoQueryI(K, Y, YCols, YRows, Z, ZCols, ZRows),
+        convert_float_array_to_2d_list(Y, YCols, YRows, NeighborsList),
+        convert_float_array_to_2d_list(Z, ZCols, ZRows, DistancesList).
+
+%% foreign c++ predicate definition 
+foreign(searchNoQuery, c, searchNoQueryI( +integer,
                                           -pointer(float_array), -integer, -integer,
-                -pointer(float_array), -integer, -integer)
+                                          -pointer(float_array), -integer, -integer)).
 ```
 
 ### Parameters
@@ -82,8 +113,8 @@ searchNoQuery(  +integer,
 
 If you want a more detailed explanation, then go to the python documentation. There is most of the time a good explanation on how the methods work and what the parameters do.
 
-* [**MLpack::kfn_C++\_documentation**](https://www.mlpack.org/doc/stable/doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html)
-* [**MLpack::kfn_Python_documentation**](https://www.mlpack.org/doc/stable/python_documentation.html#kfn)
+* [**MLpack::kfn_C++\_documentation**](https://www.mlpack.org/doc/mlpack-3.4.2/doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html)
+* [**MLpack::kfn_Python_documentation**](https://www.mlpack.org/doc/mlpack-3.4.2/python_documentation.html#kfn)
 
 added some of the links from the python documentation