5.7. Advanced Topics

5.7.1. How ecell3-session runs

ecell3-session command runs on ecell3-python interpreter command. ecell3-python command is a thin wrapper to the Python interpreter. ecell3-python command simply invokes a Python interpreter command specified at compile time. Before executing Python, ecell3-python sets some environment variables to ensure that it can find necessary E-Cell Python extension modules and the Standard DM Library. After processing the commandline options, ecell3-session command creates an ecell.ecs.Simulator object, and then instantiate a ecell.Session object for the simulator object.

Thus basically ecell3-python is just a Python interpreter, and frontend components of E-Cell SE run on this command. To use the E-Cell Python Library from ecell3-python command, use

import ecell
statement from the prompt:

$ ecell3-python 
Python 2.2.2 (#1, Feb 24 2003, 19:13:11)
[GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-4)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import ecell
>>> 

or, (on UNIX-like systems) execute a file starting with:
#!/usr/bin/env ecell3-python
import ecell
[...]

5.7.2. Getting information about execution environment

To get the current configuration of ecell3-python command, invoke ecell3-python command with a -h option. This will print values of some variables as well as usage of the command.

$ ecell3-python -h
[...]

Configurations:
 
        PACKAGE         = ecell
        VERSION         = 3.2.0
        PYTHON          = /usr/bin/python
        PYTHONPATH      = /usr/lib/python2.2/site-packages:
        DEBUGGER        = gdb
        LD_LIBRARY_PATH = /usr/lib:
        prefix          = /usr
        pythondir       = /usr/lib/python2.2/site-packages
        ECELL3_DM_PATH  =

[...]

The 'PYTHON =' line gives the path of the Python interpreter to be used.

5.7.3. Debugging

To invoke ecell3-python command in debugging mode, set ECELL_DEBUG environment variable. This runs the command on a debugger software. If found, GNU gdb is used as the debugger. ECELL_DEBUG can be used for any commands which run on ecell3-python, including ecell3-session and gecell. For example, to run ecell3-session in debug mode on the shell prompt:

$ ECELL_DEBUG=1 ecell3-session -f foo.eml
gdb --command=/tmp/ecell3.0mlQyE /usr/bin/python
GNU gdb Red Hat Linux (5.3post-0.20021129.18rh)
Copyright 2003 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "i386-redhat-linux-gnu"...
[New Thread 1074178112 (LWP 7327)]
ecell3-session [ E-Cell SE Version 3.2.0, on Python Version 2.2.2 ]
Copyright (C) 1996-2003 Keio University.
Send feedback to Koichi Takahashi <shafi@e-cell.org>
<foo.eml, t=0>>> Ctrl+C
Program received signal SIGINT, Interrupt.
[Switching to Thread 1074178112 (LWP 7327)]
0xffffe002 in ?? ()
(gdb)

It automatically runs the program with the commandline options with '--command=' option of gdb. The gdb prompt appears when the program crashes or interrupted by the user by pressing Ctrl+C.

ECELL_DEBUG runs gdb, which is operates at the level of C++ code. For debugging of Python layer scripts, see Python Library Reference Manual for Python Debugger.

5.7.4. Profiling

It is possible to run ecell3-python command in profiling mode, if the operating system has GNU sprof command, and its C library supports LD_PROFILE environmental variable. Currently it only supports per-shared object profiling. (See GNU C Library Reference Manual)

To run ecell3-python in profiling mode, set ECELL_PROFILE environment variable to SONAME of the shared object. SONAME of a shared object file can be found by using objdump command, with, for example, -p option.

For example, the following commandline takes a performance profile of Libecs:

$ ECELL_PROFILE=libecs.so.2 ecell3-session [...]

After running, it creates a profiling data file with a filename SONAME.profile in the current directory. In this case, it is libecs.so.2.profile. The binary profiling data can be converted to a text format by using sprof command. For example:

$ sprof -p libecs.so.2 libecs.so.2.profile