Added tons of doc

doc/source/pythonmodule.rst

@@ -1,6 +1,38 @@
 The CosmoToolbox python module
 ==============================
 
-.. automodule:: cosmotool
+.. module:: cosmotool
-   :members: loadRamses, loadRamsesAll
 
+
+Simulation handling
+^^^^^^^^^^^^^^^^^^^
+
+The simulation data
+-------------------
+
+.. autoclass:: PySimulationBase
+   :members:
+
+.. autoclass:: SimulationBare
+   :members:
+
+.. autoclass:: Simulation
+   :members:
+
+.. autoclass:: PySimulationAdaptor
+   :members:
+
+The simulation loaders
+----------------------
+
+.. autofunction:: loadRamses
+.. autofunction:: loadRamsesAll
+.. autofunction:: loadGadget
+.. autofunction:: loadParallelGadget
+
+Timing
+------
+
+.. autofunction:: time_block
+.. autofunction:: timeit
+.. autofunction:: timeit_quiet 

python/_cosmotool.pyx

@@ -49,37 +49,120 @@ cdef extern from "loadRamses.hpp" namespace "CosmoTool":
 
 
 class PySimulationBase(object):
+  """
+  This is the base class to representation Simulation in CosmoTool/python.
+  """
+  
   def getPositions(self):
+    """
+    getPositions(self)
+    
+    Returns:
+        A list of three arrays holding the positions of the particles. 
+        The i-th element is the i-th coordinate of each particle.
+        It may be None if the positions were not requested.
+    """
     raise NotImplementedError("getPositions is not implemented")
     
   def getVelocities(self):
+    """
+    getVelocities(self)
+    
+    Returns:
+        A list of three arrays holding the velocities of the particles. 
+        The i-th element is the i-th coordinate of each particle.
+        It may be None if the velocities were not requested.
+    """
     raise NotImplementedError("getVelocities is not implemented")
     
   def getIdentifiers(self):
+    """
+    getIdentifiers(self)
+    
+    Returns:
+        Returns an integer array that hold the unique identifiers of
+        each particle. 
+        It may be None if the identifiers were not requested.
+    """
     raise NotImplementedError("getIdentifiers is not implemented")
 
   def getTypes(self):
+    """
+    getTypes(self)
+    
+    Returns:
+        Returns an integer array that hold the type of
+        each particle. 
+        It may be None if the types were not requested.
+    """
     raise NotImplementedError("getTypes is not implemented")
 
   def getOmega_M(self):
+    """
+    getOmega_M(self)
+    
+    Returns:
+        the mean matter density in the simulation, with respect
+        to the critical density.
+    """ 
     raise NotImplementedError("getOmega_M is not implemented")
   
   def getOmega_Lambda(self):
+    """
+    getOmega_Lambda(self)
+    
+    Returns:
+        the mean dark energy density in the simulation, with respect
+        to the critical density.
+    """ 
     raise NotImplementedError("getOmega_Lambda is not implemented")
 
   def getTime(self):
+    """
+    getTime(self)
+    
+    Returns:
+        the time the snapshot was taken in the simulation. It can
+        have various units depending on the file format.
+    """
     raise NotImplementedError("getTime is not implemented")
 
   def getHubble(self):
+    """
+    getHubble(self)
+    
+    Returns:
+        the hubble constant in unit of 100 km/s/Mpc
+    """
     raise NotImplementedError("getHubble is not implemented")
 
   def getBoxsize(self):
+    """
+    getBoxsize(self)
+    
+    Returns:
+        the size of the simulation box. The length unit is not fixed,
+        though it is customary to have it in Mpc/h if the loader has
+        access to the unit normalization.
+    """
     raise NotImplementedError("getBoxsize is not implemented")
 
   def getMasses(self):
+    """
+    getMasses(self)
+    
+    Returns:
+        an array with the masses of each particles, in unspecified unit that
+        depend on the loader.
+    """
     raise NotImplementedError("getMasses is not implemented")
 
 cdef class Simulation:
+    """
+    Simulation()
+    
+    Class that directly manages internal loaded data obtained from a loader
+    """
 
     cdef list positions
     cdef list velocities
@@ -147,8 +230,16 @@ cdef class Simulation:
           del self.data
 
 
-class _PySimulationAdaptor(PySimulationBase):
+class PySimulationAdaptor(PySimulationBase):
+  """
+  PySimulationAdaptor(PySimulationBase_)
   
+  This class is an adaptor for an internal type to the loader. It defines
+  all the methods of PySimulationBase.
+  
+  Attributes:
+    simu: a Simulation_ object
+  """
   def __init__(self,sim):
     self.simu = sim
 
@@ -189,17 +280,12 @@ cdef class ArrayWrapper:
     
     cdef set_data(self, np.uint64_t size, int type_array, void* data_ptr):
         """ Set the data of the array
-
             This cannot be done in the constructor as it must recieve C-level
             arguments.
 
-Parameters:
+            Args:
------------
+                size (int): Length of the array.
-size: int
+                data_ptr (void*): Pointer to the data
-Length of the array.
-data_ptr: void*
-Pointer to the data
-
         """
         self.data_ptr = data_ptr
         self.size = size
@@ -275,8 +361,27 @@ cdef object wrap_simudata(SimuData *data, int flags):
   return simu
 
 def loadGadget(str filename, int snapshot_id, bool loadPosition = True, bool loadVelocity = False, bool loadId = False, bool loadType = False, bool loadMass=False):
-  """loadGadget(filename, cpu_id, loadPosition=True, loadVelocity=False, loadId=False, loadType=False)
+    """loadGadget(filename, snapshot_id, loadPosition=True, loadVelocity=False, loadId=False, loadType=False)
-It loads a gadget-1 snapshot and return a PySimulationBase object. If cpu_id is negative then the snapshot is considered not to be part of a set of snapshots written by different cpu. Otherwise the filename is modified to reflectt this cpu_id.
+
+    This function loads Gadget-1 snapshot format.
+    
+    If snapshot_id is negative then the snapshot is considered not to be part of
+    a set of snapshots written by different cpu. Otherwise the filename is modified
+    to reflect the indicated snapshot_id.
+
+    Arguments:
+        filename (str): input filename
+        snapshot_id (int): identifier of the gadget file if it is a multi-file snapshot
+    
+    Keyword arguments:
+        loadPosition (bool): whether to load positions
+        loadVelocity (bool): whether to load velocities
+        loadId (bool): whether to load unique identifiers
+        loadType (bool): whether to set types to particles
+        loadMass (bool): whether to set the mass of particles
+    
+    Returns:
+        an PySimulationAdaptor instance. 
 """
 
     cdef int flags
@@ -299,21 +404,22 @@ It loads a gadget-1 snapshot and return a PySimulationBase object. If cpu_id is
     if data == <SimuData*>0:
         return None
 
-  return _PySimulationAdaptor(wrap_simudata(data, flags))
+    return PySimulationAdaptor(wrap_simudata(data, flags))
 
 def loadParallelGadget(object filename_list, bool loadPosition = True, bool loadVelocity = False, bool loadId = False, bool loadType = False, bool loadMass=False):
-  """loadGadget(filename list, loadPosition=True, loadVelocity=False, loadId=False, loadType=False)
+  """loadParallelGadget(filename list, loadPosition=True, loadVelocity=False, loadId=False, loadType=False)
 
   Arguments:
-    - filename list: a list or tuple of filenames to load in parallel
+    filename (list): a list or tuple of filenames to load in parallel
   
-  Keywords:
+  Keyword arguments:
-    - loadPosition: indicate to load positions
+    loadPosition (bool): indicate to load positions
-    - loadVelocity: indicate to load velocities
+    loadVelocity (bool): indicate to load velocities
-    - loadId: indicate to load id
+    loadId (bool): indicate to load id
-    - loadType: indicate to load particle types
+    loadType (bool): indicate to load particle types
     
-It loads a gadget-1 snapshot and return a PySimulationBase object.
+  Returns:
+    It loads a gadget-1 snapshot and return a cosmotool.PySimulationBase_ object.
   """
   cdef int flags, i, num_files
   cdef list out_arrays
@@ -351,14 +457,22 @@ It loads a gadget-1 snapshot and return a PySimulationBase object.
     if data[i] == <SimuData*>0:        
       out_arrays.append(None)
     else:
-      out_arrays.append(_PySimulationAdaptor(wrap_simudata(data[i], flags)))
+      out_arrays.append(PySimulationAdaptor(wrap_simudata(data[i], flags)))
 
   del_simudata(data)
 
   return out_arrays
 
 def writeGadget(str filename, object simulation):
+  """writeGadget(filename, simulation)
   
+  This function attempts to write the content of the simulation object into 
+  a file named `filename` using a Gadget-1 file format.
+  
+  Arguments:
+    filename (str): output filename
+    simulation (PySimulationBase): a simulation object
+  """
   cdef SimuData simdata
   cdef np.ndarray[np.float32_t, ndim=1] pos, vel
   cdef np.ndarray[np.int64_t, ndim=1] ids
@@ -408,7 +522,7 @@ def loadRamses(str basepath, int snapshot_id, int cpu_id, bool doublePrecision =
     loadVelocity (bool): Whether to load velocities
     
   Returns:
-    An object derived from PySimulationBase. 
+    An object derived from PySimulationBase_. 
 """
   cdef int flags
   cdef SimuData *data
@@ -424,5 +538,5 @@ def loadRamses(str basepath, int snapshot_id, int cpu_id, bool doublePrecision =
   if data == <SimuData*>0:
     return None
 
-  return _PySimulationAdaptor(wrap_simudata(data, flags))
+  return PySimulationAdaptor(wrap_simudata(data, flags))
   

python/cosmotool/timing.py

@@ -3,35 +3,50 @@ from contextlib import contextmanager
 
 @contextmanager
 def time_block(name):
+    """
+    This generator measure the time taken by a step, and prints the result
+    in second to the console.
+    
+    Arguments:
+        name (str): prefix to print
+    """
     ts = time.time()
     yield
     te = time.time()
  
-    print '%s %2.2f sec' % \
+    print ('%s %2.2f sec' %  (name, te-ts))
-              (name, te-ts)
 
 def timeit(method):
+    """This decorator add a timing request for each call to the decorated function.
+    
+    Arguments:
+        method (function): the method to decorate
+    """
 
     def timed(*args, **kw):
         ts = time.time()
         result = method(*args, **kw)
         te = time.time()
 
-        print '%r (%r, %r) %2.2f sec' % \
+        print ('%r (%r, %r) %2.2f sec' % (method.__name__, args, kw, te-ts))
-              (method.__name__, args, kw, te-ts)
         return result
 
     return timed
 
 def timeit_quiet(method):
+    """This decorator add a timing request for each call to the decorated function.
+    Same as cosmotool.timeit_ but is quieter by not printing the values of the arguments.
+    
+    Arguments:
+        method (function): the method to decorate
+    """
 
     def timed(*args, **kw):
         ts = time.time()
         result = method(*args, **kw)
         te = time.time()
 
-        print '%r %2.2f sec' % \
+        print ('%r %2.2f sec' % (method.__name__, te-ts))
-              (method.__name__, te-ts)
         return result
 
     return timed