doc sinkhorn

Author: rflamary

docs/source/conf.py

@@ -118,7 +118,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to POT's documentation!
+POT's documentation!
 ===============================
 
 Contents:

examples/demo_OT_1D.py

@@ -8,7 +8,7 @@
 import numpy as np
 import matplotlib.pylab as pl
 import ot
-
+from ot.datasets import get_1D_gauss as gauss
 
 
 #%% parameters
@@ -19,8 +19,8 @@
 x=np.arange(n,dtype=np.float64)
 
 # Gaussian distributions
-a=ot.datasets.get_1D_gauss(n,m=20,s=20) # m= mean, s= std
-b=ot.datasets.get_1D_gauss(n,m=60,s=60)
+a=gauss(n,m=20,s=20) # m= mean, s= std
+b=gauss(n,m=60,s=60)
 
 # loss matrix
 M=ot.dist(x.reshape((n,1)),x.reshape((n,1)))

ot/bregman.py

@@ -26,7 +26,7 @@ def sinkhorn(a,b, M, reg,numItermax = 1000,stopThr=1e-9):
     - :math:`\Omega` is the entropic regularization term :math:`\Omega(\gamma)=\sum_{i,j} \gamma_{i,j}\log(\gamma_{i,j})`
     - a and b are source and target weights (sum to 1)
     
-    The algorithm used for solving the problem is the Sinkhorn-Knopp matrix scaling algorithm as proposed in [1]_
+    The algorithm used for solving the problem is the Sinkhorn-Knopp matrix scaling algorithm as proposed in [2]_
     
              
     Parameters
@@ -46,10 +46,22 @@ def sinkhorn(a,b, M, reg,numItermax = 1000,stopThr=1e-9):
     gamma: (ns x nt) ndarray
         Optimal transportation matrix for the given parameters
         
+
+    Examples
+    --------
+        
+    >>> a=[.5,.5]
+    >>> b=[.5,.5]
+    >>> M=[[0.,1.],[1.,0.]]
+    >>> ot.sinkhorn(a,b,M,1)
+    array([[ 0.36552929,  0.13447071],
+           [ 0.13447071,  0.36552929]])
+      
+        
     References
     ----------
     
-    .. [1] M. Cuturi, Sinkhorn Distances : Lightspeed Computation of Optimal Transport, Advances in Neural Information Processing Systems (NIPS) 26, 2013
+    .. [2] M. Cuturi, Sinkhorn Distances : Lightspeed Computation of Optimal Transport, Advances in Neural Information Processing Systems (NIPS) 26, 2013
         
         
     See Also
@@ -58,6 +70,16 @@ def sinkhorn(a,b, M, reg,numItermax = 1000,stopThr=1e-9):
     ot.optim.cg : General regularized OT
         
     """    
+    
+    a=np.asarray(a,dtype=np.float64)
+    b=np.asarray(b,dtype=np.float64)
+    M=np.asarray(M,dtype=np.float64)
+    
+    if len(a)==0:
+        a=np.ones((M.shape[0],),dtype=np.float64)/M.shape[0]
+    if len(b)==0:
+        b=np.ones((M.shape[1],),dtype=np.float64)/M.shape[1]    
+    
     # init data
     Nini = len(a)
     Nfin = len(b)

ot/lp/__init__.py

@@ -7,7 +7,6 @@ def emd(a,b,M):
     """
         Solves the Earth Movers distance problem and returns the optimal transport matrix
         
-        gamm=emd(a,b,M)
     
     .. math::
         \gamma = arg\min_\gamma <\gamma,M>_F 
@@ -21,6 +20,8 @@ def emd(a,b,M):
     
     - M is the metric cost matrix
     - a and b are the sample weights
+    
+    Uses the algorithm proposed in [1]_
              
     Parameters
     ----------
@@ -31,27 +32,40 @@ def emd(a,b,M):
     M : (ns,nt) ndarray, float64
         loss matrix        
         
+    Returns
+    -------
+    gamma: (ns x nt) ndarray
+        Optimal transportation matrix for the given parameters
+         
+        
     Examples
     --------
     
-    Simple example with obvious solution. The function :func:emd accepts lists and
-    perform automatic conversion tu numpy arrays 
+    Simple example with obvious solution. The function emd accepts lists and
+    perform automatic conversion to numpy arrays 
     
     >>> a=[.5,.5]
     >>> b=[.5,.5]
     >>> M=[[0.,1.],[1.,0.]]
     >>> ot.emd(a,b,M)
     array([[ 0.5,  0. ],
            [ 0. ,  0.5]])
+           
+    References
+    ----------
     
-    Returns
-    -------
-    gamma: (ns x nt) ndarray
-        Optimal transportation matrix for the given parameters
- 
+    .. [1] Bonneel, N., Van De Panne, M., Paris, S., & Heidrich, W. (2011, December).  Displacement interpolation using Lagrangian mass transport. In ACM Transactions on Graphics (TOG) (Vol. 30, No. 6, p. 158). ACM.
+        
+    See Also
+    --------
+    ot.bregman.sinkhorn : Entropic regularized OT
+    ot.optim.cg : General regularized OT           
+    
+
     """
     a=np.asarray(a,dtype=np.float64)
     b=np.asarray(b,dtype=np.float64)
+    M=np.asarray(M,dtype=np.float64)
 
     if len(a)==0:
         a=np.ones((M.shape[0],),dtype=np.float64)/M.shape[0]