Rename function of torus cpp version and import it with sphere in points

Change documentation accordingly

4 files changed, 31 insertions, 24 deletions

diff --git a/src/python/doc/datasets_generators.rst b/src/python/doc/datasets_generators.rst
index e63dde82..c0bbb973 100644
--- a/src/python/doc/datasets_generators.rst
+++ b/src/python/doc/datasets_generators.rst
@@ -13,10 +13,12 @@ We provide the generation of different customizable datasets to use as inputs fo
 Points generators
 ------------------
 
+The module **points** enables the generation of random points on a sphere, random points on a torus and as a grid.
+
 Points on sphere
 ^^^^^^^^^^^^^^^^
 
-The module **_points** enables the generation of random i.i.d. points uniformly on a (d-1)-sphere in :math:`R^d`.
+The function **sphere** enables the generation of random i.i.d. points uniformly on a (d-1)-sphere in :math:`R^d`.
 The user should provide the number of points to be generated on the sphere :code:`n_samples` and the ambient dimension :code:`ambient_dim`.
 The :code:`radius` of sphere is optional and is equal to **1** by default.
 Only random points generation is currently available.
@@ -28,28 +30,28 @@ Example
 
 .. code-block:: python
 
-   from gudhi.datasets.generators import _points
+   from gudhi.datasets.generators import points
    from gudhi import AlphaComplex
 
    # Generate 50 points on a sphere in R^2
-   gen_points = _points.sphere(n_samples = 50, ambient_dim = 2, radius = 1, sample = "random")
+   gen_points = points.sphere(n_samples = 50, ambient_dim = 2, radius = 1, sample = "random")
 
    # Create an alpha complex from the generated points
    alpha_complex = AlphaComplex(points = gen_points)
    
-.. autofunction:: gudhi.datasets.generators._points.sphere
+.. autofunction:: gudhi.datasets.generators.points.sphere
 
 Points on torus
 ^^^^^^^^^^^^^^^^
 
 You can also generate points on a torus.
 
-Two modules are available and give the same output: the first one depends on **CGAL** and the second does not and consists of full python code.
+Two functions are available and give the same output: the first one depends on **CGAL** and the second does not and consists of full python code.
 
 On another hand, two sample types are provided : you can either generate i.i.d. points on a d-torus in :math:`R^{2d}` *randomly* or on a *grid*.
 
-First module : **_points**
-""""""""""""""""""""""""""
+First function : **ctorus**
+"""""""""""""""""""""""""""
 
 The user should provide the number of points to be generated on the torus :code:`n_samples`, and the dimension :code:`dim` of the torus on which points would be generated in :math:`R^{2dim}`.
 The :code:`sample` argument is optional and is set to **'random'** by default.
@@ -67,18 +69,18 @@ Example
 """""""
 .. code-block:: python
 
-   from gudhi.datasets.generators import _points
+   from gudhi.datasets.generators import points
 
    # Generate 50 points randomly on a torus in R^6
-   gen_points = _points.torus(n_samples = 50, dim = 3)
+   gen_points = points.ctorus(n_samples = 50, dim = 3)
    
    # Generate 27 points on a torus as a grid in R^6
-   gen_points = _points.torus(n_samples = 50, dim = 3, sample = 'grid')
+   gen_points = points.ctorus(n_samples = 50, dim = 3, sample = 'grid')
 
-.. autofunction:: gudhi.datasets.generators._points.torus
+.. autofunction:: gudhi.datasets.generators.points.ctorus
 
-Second module : **points**
-""""""""""""""""""""""""""
+Second function : **torus**
+"""""""""""""""""""""""""""
 
 The user should provide the number of points to be generated on the torus :code:`n_samples` and the dimension :code:`dim` of the torus on which points would be generated in :math:`R^{2dim}`.
 The :code:`sample` argument is optional and is set to **'random'** by default.
diff --git a/src/python/gudhi/datasets/generators/_points.cc b/src/python/gudhi/datasets/generators/_points.cc
index 3d38ff90..536fa949 100644
--- a/src/python/gudhi/datasets/generators/_points.cc
+++ b/src/python/gudhi/datasets/generators/_points.cc
@@ -96,10 +96,10 @@ PYBIND11_MODULE(_points, m) {
           :returns: the generated points on a sphere.
           )pbdoc");
 
-    m.def("torus", &generate_points_on_torus,
+    m.def("ctorus", &generate_points_on_torus,
           py::arg("n_samples"), py::arg("dim"), py::arg("sample") = "random",
           R"pbdoc(
-          Generate random i.i.d. points on a d-torus in R^2d
+          Generate random i.i.d. points on a d-torus in R^2d or as a grid
 
           :param n_samples: The number of points to be generated.
           :type n_samples: integer
@@ -107,7 +107,10 @@ PYBIND11_MODULE(_points, m) {
           :type dim: integer
           :param sample: The sample type. Available values are: `"random"` and `"grid"`. Default value is `"random"`.
           :type sample: string
-          :rtype: numpy array of float
+          :rtype: numpy array of float.
+          The shape of returned numpy array is :
+              if sample is 'random' : (n_samples, 2*dim).
+              if sample is 'grid' : ([n_samples**(1./dim)]**dim, 2*dim).
           :returns: the generated points on a torus.
           )pbdoc");
 }
diff --git a/src/python/gudhi/datasets/generators/points.py b/src/python/gudhi/datasets/generators/points.py
index daada486..1995f769 100644
--- a/src/python/gudhi/datasets/generators/points.py
+++ b/src/python/gudhi/datasets/generators/points.py
@@ -10,6 +10,9 @@
 import numpy as np
 import itertools
 
+from ._points import ctorus
+from ._points import sphere
+
 def _generate_random_points_on_torus(n_samples, dim):
 
     # Generate random angles of size n_samples*dim
diff --git a/src/python/test/test_datasets_generators.py b/src/python/test/test_datasets_generators.py
index 656c30ee..4c087c57 100755
--- a/src/python/test/test_datasets_generators.py
+++ b/src/python/test/test_datasets_generators.py
@@ -9,25 +9,24 @@
 """
 
 from gudhi.datasets.generators import points
-from gudhi.datasets.generators import _points
 
 import pytest
 
 def test_sphere():
-    assert _points.sphere(n_samples = 10, ambient_dim = 2, radius = 1., sample = 'random').shape == (10, 2)
+    assert points.sphere(n_samples = 10, ambient_dim = 2, radius = 1., sample = 'random').shape == (10, 2)
 
     with pytest.raises(ValueError):
-        _points.sphere(n_samples = 10, ambient_dim = 2, radius = 1., sample = 'other')
+        points.sphere(n_samples = 10, ambient_dim = 2, radius = 1., sample = 'other')
 
 def test_torus():
-    assert _points.torus(n_samples = 64, dim = 3, sample = 'random').shape == (64, 6)
-    assert _points.torus(n_samples = 64, dim = 3, sample = 'grid').shape == (64, 6)
+    assert points.ctorus(n_samples = 64, dim = 3, sample = 'random').shape == (64, 6)
+    assert points.ctorus(n_samples = 64, dim = 3, sample = 'grid').shape == (64, 6)
     
-    assert _points.torus(n_samples = 10, dim = 4, sample = 'random').shape == (10, 8)
-    assert _points.torus(n_samples = 10, dim = 4, sample = 'grid').shape == (1, 8)
+    assert points.ctorus(n_samples = 10, dim = 4, sample = 'random').shape == (10, 8)
+    assert points.ctorus(n_samples = 10, dim = 4, sample = 'grid').shape == (1, 8)
 
     with pytest.raises(ValueError):
-        _points.torus(n_samples = 10, dim = 4, sample = 'other')
+        points.ctorus(n_samples = 10, dim = 4, sample = 'other')
 
 def test_torus_full_python():
     assert points.torus(n_samples = 64, dim = 3, sample = 'random').shape == (64, 6)