************************************************************************ -- THIS README WAS UPDATED: 2009 July 21 -- The following README briefly describes the basic structures and functions from SOSlib (SBML ODE Solver Library) for which Python wrappers have been generated (using SWIG). It also provides basic instructions for running soslibPy examples provided with the installation. As of the writing of this README, Python wrappers have been generated for all functions and data structures in the following SOSlib header files: -- odeModel.h -- integratorSettings.h -- integratorInstance.h -- cvodedata.h -- variableIndex.h -- sbmlResults.h Please refer to the online API documentation for the SBML ODE Solver library (SOSlib) found at the following location: http://www.tbi.univie.ac.at/~raim/odeSolver/doc/api/index.html The API documentation contains links to all of the SOSlib header and source files. Refer to the above-listed header files to know what functionality is available in soslibPy (Python wrapper library for SOSlib). ************************************************************************ The following document is divided into two sections: (1) Getting Started (2) Overview of the Core SOSlib Data Structures #### SECTION 1: Getting Started #### If you selected only the basic installation of soslibPy (without binaries and headers for SOSlib, libSBML and Sundials), you will have two folders, 'soslibPy' and 'examples'. ** NOTE --> Depending on your version of Windows, you may need libsbml.dll and its dependencies (i.e. xerces-c_2_7.dll, bzip2.dll) to run the examples. If, when you run the examples, you receive an error message indicating that libsbml.dll was not found, install the full version (with binaries for libsbml and its dependencies). ** NOTE --> If you do not have Visual C++ installed on your machine, attempting to run the examples may give rise to an error indicating that _soslibPy.pyd could not be loaded. If this occurs, try installing a free version of Visual C++ from the following: http://www.microsoft.com/express/vc/. Alternatively, if you do not wish to install a full version of Visual C++, you may install the Microsoft Visual C++ 2008 Redistributable Package from http://www.microsoft.com/downloads/ details.aspx?FamilyID=9b2da534-3e03-4391-8a4d-074b9f2bc1bf&displaylang=en In the 'soslibPy' folder, there are two files, _soslibPy.pyd and soslibPy.py, that together constitute the Python wrapper library for SOSlib. If you set your current working directory in Python to '${INSTALL_PATH}/soslibPy' (where ${INSTALL_PATH} must be replaced with the path to the installation directory), you may load soslibPy: import os os.chdir("${INSTALL_PATH}/soslibPy") import soslibPy as slpy Note, if you are already in ${INSTALL_PATH} (check this using os.getcwd() after you have typed: import os), you may simply type os.chdir("soslibPy"). A different namespace (instead of 'slpy') may be used, but the examples included with the installation use 'slpy'. In Section 1 of the tutorial (see soslibPy_TUTORIAL.txt), we provide a demonstration of the basic usage of soslibPy. Below, we provide only one sample function from SOSlib. Please refer to the tutorial for a more extensive illustration of its use. If soslibPy is used directly, the function names, arguments and usage are as indicated in the SOSlib API. However, also found in the soslibPy folder is a facility Python script, SLPyObjects.py, that contains definitions for four classes, ODEModel, CVODESettings, IntegrInstance and SBMLResults. These four classes essentially wrap the most useful data structures and basic functionality of SOSlib necessary for loading models and numerically solving the associated ODEs. These data structures include odeModel_t, cvodeSettings_t and integratorInstance_t, all of which are described, below, in section 2 (Overview of the Core SOSlib Data Structures). The Python classes defined in SLPyObjects.py provide simpler access to and usage of SOSlib data structures and functions. In the 'examples' folder, two Python scripts are provided, soslibPyTest.py and SLPyObjectsTest.py. The soslibPyTest example uses soslibPy directly rather than using the utility classes defined in SLPyObjects.py. This script imports soslibPy within the namespace 'slpy' (with the import command shown above) and calls SOSlib functions directly. For example, the command shown below reads in an SBML file, 'testModel.xml', creates an odeModel_t SOSlib data structure, and returns a pointer to it (which it stores as 'model'). Note, before calling the following command, you must be in the 'examples' folder. The argument "sbmlModels/testModel.xml" is interpreted relative to your current working directory. In this case, your working directory must be ${INSTALL_PATH}/examples. model = slpy.ODEModel_createFromFile("sbmlModels/testModel.xml") If the odeModel_t data structure was properly created and a pointer returned, typing 'model' and pressing Enter should provide output similar to the following (with a different address in memory): > If there is no output when you type 'model' and press Enter, the SBML model did not load and you may want to ensure that the argument string you provided has no errors and that you are in the appropriate working directory. In the other example found in the examples folder (SLPyObjectsTest.py), the equivalent command for loading an SBML file and creating an odeModel_t data structure is as follows (after first loading the Python script by typing 'from SLPyObjects import *'): model = ODEModel("sbmlModels/testModel.xml") Now if you type 'model' and press Enter, the output should be something similar to the following (with a different address in memory): In this case, though, the variable 'model' is a Python object of type ODEModel (for which the class definition is given in SLPyObjects.py) and not a Python wrapper object that serves as a proxy for the SOSlib odeModel_t data structure. The tutorial (soslibPY_TUTORIAL) goes into more detail on this and also provides a more in depth discussion of both examples, soslibPyTest.py and SLPyObjectsTest.py. To run these two examples, start Python and be sure that the current working directory is ${INSTALL_PATH}/examples. Use the following commands: import os os.chdir("${INSTALL_PATH}/examples") Or if you are already in the directory ${INSTALL_PATH}, simply type: os.chdir("examples"). Now you can run both examples with the following commands: from soslibPyTest import * from SLPyObjectsTest import * In each case, the results will be written to the console. Notice that the output provides a brief description of each task carried out. You may also open up both files (soslibPyTest.py and SLPyObjectsTest.py) and look directly at the Python script for more information since both scripts are well commented. In the tutorial, we provide an in depth discussion of these scripts. Together, they provide a good demonstration of the core functionality of soslibPy and SLPyObjects. Finally, within the examples folder there are two folders 'sbmlModels' and 'cc3d'. The first simply contains some SBML models that can be loaded and run as simulations. The other folder, 'cc3d', contains Python scripts for two Compucell3D simulations wherein soslibPy is used to extend the multicellular modeling capabilities of Compucell3D to include intracellular dynamics that can be coupled to properties at the cellular level. Specifically, both examples use information at the subcellular level to continuously update inter-cellular adhesion properties at the multicellular level. For more details, see the tutorial and the comments within the Python scripts themselves (see SLPyIntegratorSteppables.py and SLPyIntegrElowitz2000Steppable.py). If you wish to run the examples in the cc3d folder, first install Compucell3D 3.3.1 from the following site: http://www.compucell3d.org/Download/. Be sure that you have copied the following files from your soslibPy installation directory into the Compucell3D root installation directory: -- soslibPy/SLPyObjects.py -- soslibPy/addPaths.py -- soslibPy/_soslibPy.pyd -- soslibPy/soslibPy.py -- examples/sbmlModels/testModel.xml -- examples/sbmlModels/Elowitz2000_Repressilator.xml You may also need to copy the DLL files from 'sbml\bin' (libsbml.dll and its dependencies) to your CompuCell3D installation directory. Alternatively, you may open SLPyIntegrator.py and SLPyIntegrElowitz2000.py in a text editor and add the following lines *after* 'import sys': sys.path.append("{soslibPy_installation_path}\soslibPy") sys.path.append("{soslibPy_installation_path}\sbml\bin") Where {soslibPy_installation_path} is replaced by the full path to the root installation directory of soslibPy on your machine. You must still, however, copy testModel.xml and Elowitz2000_Repressilator.xml from 'examples/sbmlModels' into your CompuCell installation directory. Once you have done this, start Compucell3D and open either of the following Python scripts: examples/cc3d/SLPyIntegrator.py or examples/cc3d/SLPyIntegrElowitz2000.py. Start the simulation by pressing the play button. #### SECTION 2: Overview of the Core SOSlib Data Structures #### The SBML ODE Solver Library (SOSlib) API documentation can be found at the following location: http://www.tbi.univie.ac.at/~raim/odeSolver/doc/api/index.html The primary data structures necessary for (1) loading an SBML model, (2) numerically solving the corresponding system of ODEs and (3) accessing and modifying parameter values are the following: -- odeModel (see odeModel.h for API) -- cvodeSettings (see integratorSettings.h for API) -- integratorInstance (see integratorInstance.h for API) Python wrappers were generated (using SWIG) for the APIs of these essential data structures. In addition, wrappers were created for other data structures (variableIndex_t, cvodeData_t and cvodeResults_t) for which some wrapped functions return pointers. The following header files were included in the SWIG interface file to generate wrappers for these data structures: variableIndex.h and cvodedata.h. Note that, in instances where a called function (in Python) returns a pointer to a structure for which a wrapper has not been created, one must assign the returned value to a variable. If the returned value is directed to the console to be printed, Python has no information about the type of object to which the pointer refers. The result is that Python crashes. On the other hand, if the returned value (a pointer) is stored in a variable, this variable can then be passed as an argument to a function that expects a pointer to the data structure type in question. ---- odeModel ---- An odeModel_t data structure can be created from an sbml file using the following function in odeModel.h: odeModel_t *ODEModel_createFromFile(char *) This function takes the name of an sbml file (including a path, if necessary) as a string (or, technically, a char *) and returns a pointer to an odeModel_t. This data structure stores structural information about the model (such as number of variables and parameters, variable/parameter names and numerical values, etc.) that can be accessed through the functions provided in odeModel.h. Note, that information about variables and parameters is stored in and passed as variableIndex_t data structures. This data structure is defined in variableIndex.h for which Python wrappers were also generated. ---- cvodeSettings ---- A cvodeSettings_t data structure can be created with default values using the following function in integratorSettings.h: cvodeSettings_t *CvodeSettings_create() This function returns a pointer to a cvodeSettings_t which stores information specific to numerical integration. This includes: stop time, number of output steps between time 0 and the stop time for which the system of ODEs should be solved, the nonlinear solver method, and other information. Default values for stop time and the number of output steps are 1.0 and 10, respectively. Although separate functions are available for setting these values, a cvodeSettings_t data structure can be created with specified stop time and output steps (passed in as arguments) using the following function declared in integratorSettings.h: cvodeSettings_t * CvodeSettings_createWithTime(double Time, int PrintStep) ---- integratorInstance ---- An integratorInstance_t data structure is created from (1) an odeModel_t, specifying the ODE model structure, and (2) a cvodeSettings_t, specifying numerical integration settings, using the following function in integratorInstance.h: integratorInstance_t *IntegratorInstance_create(odeModel_t *, cvodeSettings_t *) This function returns a pointer to an integratorInstance_t which stores pointers to the odeModel_t and cvodeSettings_t passed in as arguments as well as pointers to three other SOSlib data structures (cvodeData_t, cvodeSolver_t, and cvodeResults_t) that store information related to the outcome of numerical integration.