Continuation to PR #308 (#340)

* Fixed docstrings of some functions.

* Fixed attribute tests.

Author: dilawar

pymoose/moosemodule.cpp

@@ -1765,10 +1765,12 @@ PyObject * moose_exists(PyObject * dummy, PyObject * args)
     return Py_BuildValue("i", Id(path) != Id() || string(path) == "/" || string(path) == "/root");
 }
 
-PyDoc_STRVAR(moose_loadModel_documentation,
-             "loadModel(filename, modelpath, solverclass) -> vec\n"
+PyDoc_STRVAR(moose_loadModelInternal_documentation,
+             "loadModelInternal(filename, modelpath, solverclass) -> vec\n"
              "\n"
              "Load model from a file to a specified path.\n"
+             "Note: This function should not be used by users. It is meants for developers. \n"
+             "Please see `moose.loadModel` function.\n"
              "\n"
              "Parameters\n"
              "----------\n"
@@ -1785,11 +1787,11 @@ PyDoc_STRVAR(moose_loadModel_documentation,
              "    loaded model container vec.\n"
             );
 
-PyObject * moose_loadModel(PyObject * dummy, PyObject * args)
+PyObject * moose_loadModelInternal(PyObject * dummy, PyObject * args)
 {
     char * fname = NULL, * modelpath = NULL, * solverclass = NULL;
 
-    if(!PyArg_ParseTuple(args, "ss|s:moose_loadModel", &fname, &modelpath, &solverclass))
+    if(!PyArg_ParseTuple(args, "ss|s:moose_loadModelInternal", &fname, &modelpath, &solverclass))
     {
         cout << "here in moose load";
         return NULL;
@@ -1812,7 +1814,8 @@ PyObject * moose_loadModel(PyObject * dummy, PyObject * args)
     PyObject * ret = reinterpret_cast<PyObject*>(model);
     return ret;
 }
-/*
+
+#if 0
 PyDoc_STRVAR(moose_saveModel_documentation,
              "saveModel(source, filename) -> None\n"
              "\n"
@@ -1869,7 +1872,8 @@ PyObject * moose_saveModel(PyObject * dummy, PyObject * args)
     SHELLPTR->doSaveModel(model, filename);
     Py_RETURN_NONE;
 }
-*/
+#endif 
+
 PyObject * moose_setCwe(PyObject * dummy, PyObject * args)
 {
     PyObject * element = NULL;
@@ -3013,7 +3017,7 @@ static PyMethodDef MooseMethods[] =
     {"stop", (PyCFunction)moose_stop, METH_VARARGS, "Stop simulation"},
     {"isRunning", (PyCFunction)moose_isRunning, METH_VARARGS, "True if the simulation is currently running."},
     {"exists", (PyCFunction)moose_exists, METH_VARARGS, "True if there is an object with specified path."},
-    {"loadModel", (PyCFunction)moose_loadModel, METH_VARARGS, moose_loadModel_documentation},
+    {"loadModelInternal", (PyCFunction)moose_loadModelInternal, METH_VARARGS, moose_loadModelInternal_documentation},
     //{"saveModel", (PyCFunction)moose_saveModel, METH_VARARGS, moose_saveModel_documentation},
     {"connect", (PyCFunction)moose_connect, METH_VARARGS, moose_connect_documentation},
     {"getCwe", (PyCFunction)moose_getCwe, METH_VARARGS, "Get the current working element. 'pwe' is an alias of this function."},

pymoose/moosemodule.h

@@ -234,7 +234,7 @@ PyObject * moose_reinit(PyObject * dummy, PyObject * args);
 PyObject * moose_stop(PyObject * dummy, PyObject * args);
 PyObject * moose_isRunning(PyObject * dummy, PyObject * args);
 PyObject * moose_exists(PyObject * dummy, PyObject * args);
-PyObject * moose_loadModel(PyObject * dummy, PyObject * args);
+PyObject * moose_loadModelInternal(PyObject * dummy, PyObject * args);
 //PyObject * moose_saveModel(PyObject * dummy, PyObject * args);
 PyObject * moose_setCwe(PyObject * dummy, PyObject * args);
 PyObject * moose_getCwe(PyObject * dummy, PyObject * args);

python/moose/__init__.py

@@ -5,13 +5,15 @@
 # related module is imported.
 LOGGING_FORMAT = '%(asctime)s %(message)s'
 
-# Bring everything from moose.py to global namespace.
-from moose.moose import *
-
 # Bring everything from c++ module to global namespace. Not everything is
 # imported by the pervios import statement.
 from moose._moose import *
 
+# Bring everything from moose.py to global namespace. It will overwrite any c++
+# function with the same name.
+from moose.moose import *
+
+
 # create a shorthand for version() call here.
 __version__ = version()
 

python/moose/moose.py

@@ -5,9 +5,9 @@
 # Maintainer: Dilawar Singh, Harsha Rani, Upi Bhalla
 
 import warnings
+import os
 import pydoc
 from io import StringIO
-from os.path import splitext
 from contextlib import closing
 
 # Import function from C++ module into moose namespace.
@@ -58,35 +58,53 @@
     mergechemImport_ = False
     mergechemError_ = '%s' % e
 
-def loadModel(filename, target,method=None):
-    solverClass = 'Neutral'
-    if method != None:
-        solverClass = method
-    try:
-        f = open(filename,'r')
-        f.close()
-    except IOError as e:
-        print (e)
-        return
-    else:
-        file_name,extension = splitext(filename)
-        if extension in [".swc",".p"]:
-            ret = _moose.loadModel(filename,target,"Neutral")
-        elif extension in [".g",".cspace"]:
-            #only if genesis or cspace file, then mooseAddChemSolver is called
-            ret = _moose.loadModel(filename,target,"ee")
-          
+def loadModel(filename, modelpath, solverclass="gsl"):
+    """loadModel: Load model from a file to a specified path.
+
+    Parameters
+    ----------
+    filename: str
+        model description file.
+    modelpath: str
+        moose path for the top level element of the model to be created.
+    method: str 
+        solver type to be used for simulating the model.
+        TODO: Link to detailed description of solvers?
+
+    Returns
+    -------
+    object
+        moose.element if succcessful else None.
+    """
+
+    if not os.path.isfile( os.path.realpath(filename) ):
+        mu.warn( "Model file '%s' does not exists or is not readable." % filename )
+        return None
+
+    extension = os.path.splitext(filename)[1]
+    if extension in [".swc", ".p"]:
+        return _moose.loadModelInternal(filename, modelpath, "Neutral" )
+
+    if extension in [".g", ".cspace"]:
+        # only if genesis or cspace file and method != ee then only
+        # mooseAddChemSolver is called.
+        ret = _moose.loadModelInternal(filename, modelpath, "ee")
+        sc = solverclass.lower()
+        if sc in ["gssa","gillespie","stochastic","gsolve"]:
+            method = "gssa"
+        elif sc in ["gsl","runge kutta","deterministic","ksolve","rungekutta","rk5","rkf","rk"]:
+            method = "gsl"
+        elif sc in ["exponential euler","exponentialeuler","neutral"]:
+            method = "ee"
+        else:
             method = "ee"
-            if solverClass.lower() in ["gssa","gillespie","stochastic","gsolve"]:
-                method = "gssa"
-            elif solverClass.lower() in ["gsl","runge kutta","deterministic","ksolve","rungekutta","rk5","rkf","rk"]:
-                method = "gsl"
-            elif solverClass.lower() in ["exponential euler","exponentialeuler","neutral"]:
-                method = "ee"
-            
-            if method != 'ee':
-                chemError_ = _chemUtil.add_Delete_ChemicalSolver.mooseAddChemSolver(target,method)
+
+        if method != 'ee':
+            chemError = _chemUtil.add_Delete_ChemicalSolver.mooseAddChemSolver(modelpath, method)
         return ret
+    else:
+        mu.error( "Unknown model extenstion '%s'" % extension)
+        return None
 
 # Version
 def version( ):
@@ -123,36 +141,42 @@ def version( ):
 def mooseReadSBML(filepath, loadpath, solver='ee',validate="on"):
     """Load SBML model.
 
-    keyword arguments: \n
-
-    filepath -- filepath to be loaded \n
-    loadpath -- Root path for this model e.g. /model/mymodel \n
-    solver   -- Solver to use (default 'ee' ) \n
-
+    Parameter
+    --------
+    filepath: str
+        filepath to be loaded.
+    loadpath : str 
+        Root path for this model e.g. /model/mymodel
+    solver : str
+        Solver to use (default 'ee').
+        Available options are "ee", "gsl", "stochastic", "gillespie"
+            "rk", "deterministic" 
+            For full list see ??
     """
     global sbmlImport_
     if sbmlImport_:
-        return _readSBML.mooseReadSBML( filepath, loadpath, solver,validate )
+        return _readSBML.mooseReadSBML(filepath, loadpath, solver, validate)
     else:
         print( sbmlError_ )
         return False
 
-
 def mooseWriteSBML(modelpath, filepath, sceneitems={}):
-    """Writes loaded model under modelpath to a file in SBML format.
-
-    keyword arguments:\n
-
-    modelpath -- model path in moose e.g /model/mymodel \n
-    filepath -- Path of output file. \n
-    sceneitems -- dictlist (UserWarning: user need not worry about this) \n
-                    layout position is saved in Annotation field of all the moose Object (pool,Reaction,enzyme)\n
-                    If this function is called from \n
-                        -- GUI, the layout position of moose object is passed \n
-                        -- command line, \n
-                            ---if genesis/kkit model is loaded then layout position is taken from the file \n
-                            --- else, auto-coordinates is used for layout position and passed
-
+    """mooseWriteSBML: Writes loaded model under modelpath to a file in SBML format.
+    
+    Parameters
+    ----------
+    modelpath : str 
+        model path in moose e.g /model/mymodel \n
+    filepath : str
+        Path of output file. \n
+    sceneitems : dict 
+        UserWarning: user need not worry about this layout position is saved in 
+        Annotation field of all the moose Object (pool,Reaction,enzyme).
+        If this function is called from 
+        * GUI - the layout position of moose object is passed 
+        * command line - NA
+        * if genesis/kkit model is loaded then layout position is taken from the file 
+        * otherwise auto-coordinates is used for layout position.
     """
     if sbmlImport_:
         return _writeSBML.mooseWriteSBML(modelpath, filepath, sceneitems)
@@ -161,13 +185,15 @@ def mooseWriteSBML(modelpath, filepath, sceneitems={}):
         return False
 
 
-def mooseWriteKkit(modelpath, filepath,sceneitems={}):
+def mooseWriteKkit(modelpath, filepath, sceneitems={}):
     """Writes  loded model under modelpath to a file in Kkit format.
 
-    keyword arguments:\n
-
-    modelpath -- model path in moose \n
-    filepath -- Path of output file.
+    Parameters
+    ----------
+    modelpath : str 
+        Model path in moose.
+    filepath : str 
+        Path of output file.
     """
     global kkitImport_, kkitImport_err_
     if not kkitImport_:
@@ -178,10 +204,14 @@ def mooseWriteKkit(modelpath, filepath,sceneitems={}):
 
 
 def mooseDeleteChemSolver(modelpath):
-    """ deletes solver on all the compartment and its children.
-        This is neccesary while created a new moose object on a pre-existing modelpath,\n
-        this should be followed by mooseAddChemSolver for add solvers on to compartment to simulate else
-        default is Exponential Euler (ee)
+    """mooseDeleteChemSolver
+    deletes solver on all the compartment and its children.
+
+    Notes
+    -----
+    This is neccesary while created a new moose object on a pre-existing modelpath,
+    this should be followed by mooseAddChemSolver for add solvers on to compartment 
+    to simulate else default is Exponential Euler (ee)
     """
     if chemImport_:
         return _chemUtil.add_Delete_ChemicalSolver.mooseDeleteChemSolver(modelpath)
@@ -191,15 +221,17 @@ def mooseDeleteChemSolver(modelpath):
 
 
 def mooseAddChemSolver(modelpath, solver):
-    """ Add solver on chemical compartment and its children for calculation
+    """mooseAddChemSolver:
+    Add solver on chemical compartment and its children for calculation
 
-    keyword arguments:\n
-
-    modelpath -- model path that is loaded into moose \n
-    solver -- "Exponential Euler" (ee) (default), \n
-              "Gillespie"         ("gssa"), \n
-              "Runge Kutta"       ("gsl")
+    Parameters
+    ----------
 
+    modelpath : str
+        Model path that is loaded into moose.
+    solver : str 
+        Exponential Euler "ee" is default. Other options are Gillespie ("gssa"),
+        Runge Kutta ("gsl") etc. Link to documentation?
     """
     if chemImport_:
         chemError_ = _chemUtil.add_Delete_ChemicalSolver.mooseAddChemSolver(modelpath, solver)
@@ -209,9 +241,8 @@ def mooseAddChemSolver(modelpath, solver):
         return False
 
 def mergeChemModel(src, des):
-    """ Merges two chemical model, \n
-        File or filepath can be passed
-        source is merged to destination
+    """mergeChemModel: Merges two chemical model.
+    File or filepath can be passed source is merged to destination
     """
     #global mergechemImport_
     if mergechemImport_:
@@ -279,7 +310,6 @@ def le(el=None):
 
 ce = _moose.setCwe  # ce is a GENESIS shorthand for change element.
 
-
 def syncDataHandler(target):
     """Synchronize data handlers for target.
 
@@ -358,7 +388,6 @@ def showfield(el, field='*', showtype=False):
 
 def showfields(el, showtype=False):
     """Convenience function. Should be deprecated if nobody uses it.
-
     """
     warnings.warn(
         'Deprecated. Use showfield(element, field="*", showtype=True) instead.',
@@ -372,7 +401,6 @@ def showfields(el, showtype=False):
               ('sharedFinfo', 'shared message field'),
               ('lookupFinfo', 'lookup field')]
 
-
 def listmsg(el):
     """Return a list containing the incoming and outgoing messages of
     `el`.

tests/python/test_moose_attribs.py

@@ -44,15 +44,15 @@
         'element', 'exists', 'finfotypes', 'fixXreacs', 'genesis', 'getCwe',
         'getField', 'getFieldDict', 'getFieldNames', 'getfielddoc',
         'getmoosedoc', 'isRunning', 
-        'known_types', 'le', 'listmsg', 'loadModel', 'melement',
+        'known_types', 'le', 'listmsg', 'loadModelInternal', 'melement',
         'mergeChemModel', 'moose',
         'mooseAddChemSolver', 'mooseDeleteChemSolver', 'mooseReadNML2',
         'mooseReadSBML', 'mooseWriteKkit', 'mooseWriteNML2', 'mooseWriteSBML',
         'moose_constants', 'moose_test', 'move',
         'nml2Import_', 'pager', 'print_utils',
         'pwe', 'pydoc', 'rand', 'reinit', 
         'seed', 'sequence_types', 'setClock', 'setCwe', 'showfield',
-        'showfields', 'showmsg', 'splitext', 'start', 'stop', 'syncDataHandler',
+        'showfields', 'showmsg', 'start', 'stop', 'syncDataHandler',
         'test', 'testSched', 'toUnicode', 'useClock', 'utils', 'vec', 'version',
         'warnings', 'wildcardFind']