5.8. E-Cell Python Library API

This section provides a list of some commonly used classes in E-Cell Python library and their APIs.

5.8.1. Session Class API

Methods of Session class has the following five groups.

Table 5-1. Methods and properties of Session class

Session class methods 
SynopsisReturn
Description
Session methods
loadModel( file )
None

Load an EML file, and create a cell model as described in the file.

file can be either a filename or a file object.

loadScript( filename )
None

Load a ESS file. Usually this is not used in ESS.

FIXME: what happens then? need to check if this can be called recursively.

FIXME: need to describe about the locals()

message( message )
None

Output message. By default the message is printed to stdout.

The way the message is handled can be changed by using setMessageMethod method. For example, GUI frontend software may give a method to steal the message for its message printing widget.

setMessageMethod( method )
None

This method changes what happens when message method is called.

method must be a Python callable object which takes just one string parameter.

See also: message

Simulation methods
getCurrentTime()
The current time as a float

This method returns the current time of the simulator.

getNextEvent()
A Python 2-tuple ( float, string )

This method returns the next scheduled event as a Python 2-tuple consisting of a scheduled time and a StepperID. The event will be processed in the next time whe step() or run() is called.

The time is usually different from one that getCurrentTime() returns. This method returns the scheduled time of the next event, while getCurrentTime() returns the time of the last event. These methods can return the same number if more than one events are scheduled at the same point in time.

run( [sec] )
None

Run the simulation for sec seconds.

When this method is called, the simulator internally calls step() method repeatedly until the equation tcurrent > tstart + sec holds. That means, the simulator stops immediately after the simulation step in which the time exceeds the specified point. The time can be far after the specified time point if all step sizes taken by Steppers in the model are very long.

If event checker event handler object are set, sec can be omitted.

See also: setEventChecker and setEventHandler

setEventChecker( eventchecker )
None

If the event checker and an event handler are correctly set, and the run method is called with or without time duration, the simulator checks if the event checker returns true once in n simulation steps , where n is a positive integer number set by using setEventCheckInterval (default n= 20 steps). If it happens, the simulator then calls the event handler. If the event handler calls stop method of Session, the simulator stops before the next step. This is the only way to quit from the simulation loop when run is called without an argument.

This mechanism is used to implement, mainly but not limited to, GUI frontend components to the Session class.

event checker and event handler must be Python callable objects. event checker must return an object which can be evaluated as either true or false.

setEventCheckInterval( n )
None

See setEventChecker.

This method is NOT IMPLEMENTED YET.

setEventHandler( eventhandler )
None

See setEventChacker

step( [numsteps] )
None

Perform a step of the simulation. If the optional integer numsteps parameter is given, the simulator steps that number. If it is omitted, it steps just once.

stop()
None

Stop the simulation. Usually this is called from the event handler, or other methods called by the event handler.

See also: setEventChacker, setEventHandler

initialize()
None

Do preparation of the simulation. Usually there is no need to call this method because this is automatically called before executing step and run.

Stepper methods
getStepperList()
A Python tuple of ID strings.

This method returns a Python tuple which contains ID strings of Stepper objects in the simulator.

createStepperStub( id )
A new StepperStub object

This method returns a StepperStub object bound to this Session object and the given id.

Entity methods
getEntityList( entitytype, systempath )
A Python tuple of FullID strings.

This method returns a Python tuple which contains FullID strings of Entity objects of entitytype existing in the System pointed by the systempath argument

entitytype must be one of VARIABLE, PROCESS, or SYSTEM defined in ecell.ECS module. systempath must be a valid SystemPath string.

createEntityStub( fullid )
A new EntityStub object

This method returns an EntityStub object bound to this Session object and the given fullid.

Logger methods
getLoggerList()
A Python tuple of FullPN strings.

This method returns a Python tuple which contains FullPN strings of all the Logger objects in the simulator.

createLoggerStub( fullpn )
A new LoggerStub object

This method returns a LoggerStub object bound to this Session object and the given fullpn.

fullpn must be a valid FullPN string.

Session class properties
NameType 
Description
theSimulator Simulator 

theSimulator variable holds this Session's Simulator object.

Usually ESS users should rarely have need to get into details of the Simulator class because almost all simulation jobs can be done with the Session API and the ObjectStub classes, which were in fact developed to make it easier by providing a simple and consistent object-oriented appearance to the lower level flat Simulator API. For the details of Simulator class, consult E-Cell C++ library reference manual and the sourcecode of the system, especially ecell3/ecell/libemc/Simulator.hpp.

theMainWindow MainWindow 

theMainWindow variable may exist when the Session is executed within Osogo Session Monitor. This variable is optional, and it should be checked if this exists before using.

5.8.2. ObjectStub Classes API

There are three subclasses of ObjectStub

Some methods are common to these subclasses.

Table 5-2. ObjectStub classes method list

Methods of ObjectStub classes. 
SynopsisReturn
Description
Common methods of EntityStub, StepperStub, and LoggerStub
create()
None

Create the object. For example, if this is a StepperStub, it attempts to create a Stepper object with the name specified when this ObjectStub is created.

exists()
boolean

This method returns true if the object this ObjectStub points to exists, or false otherwise.

getName()
The name as a string

This method returns the name of the object this ObjectStub points to. The name is typically a string identifier used inside the simulator. EntityStub returns a FullID, StepperStub returns a StepperID, and LoggerStub returns a FullPN the Logger is recording.

Methods common to EntityStub and StepperStub
getClassName()
The classname as a string

This method can be used to get the classname of the Entity or the Stepper.

getProperty( propertyname )
A property value as one of int, float, string, or a Python tuple of these types mixed.

This method returns a value of the Entity or the Stepper object's property of name propertyname.

The value can be either an int, a float, a string, or a tuple of these types mixed. The tuple can be nested.

This method is also available via __getitem__ special method, which means that;

value = stub.getProperty( propertyname )
and
value = stub[ propertyname ]
have the same consequence.

getPropertyAttributes( propertyname )
Attributes as a Python tuple.

This method returns property attributes of the property named propertyname as a Python tuple. Currently the contents of the tuple is a pair of boolean values which mean ( setable, getable ). For example, if you get a tuple ( false, true ), the property is read-only.

Attempts to set a value to a read-only propertiy and to get a value from a write-only property raise exceptions.

getPropertyList()
Names of properties of the Entity or the Stepper as a Python tuple.
This method is used to get the list of all the properties of the Entity or the Stepper object.
setProperty( propertyname, value )
None

Set the property propertyname of the Entity or Stepper object to value.

The value can be an object of one of int, float, string, a Python tuple, or a Python list. These types can be mixed in the sequence types.

This method can be used via __setitem__ special method. That is;

stub.setProperty( propertyname, value )
and
stub[ propertyname ] = value
are equivalent.

Methods available only in LoggerStub
getData( [starttime], [endtime], [interval]  )
A Numeric array

This method is used get the data of the Logger. Returned data is a rank-2 array object of Numeric Python. Each row of the data can be either a 5-tuple or a 2-tuple. A row of the data represents a logged data point or a logged time inteval. The 5-tuple format has the following form: ( time, value, average, min, max ), and the 2-tuple format has the form of: ( time, value ). time is the time when the last data point is logged, value is the value of the last data logged in this data interval, average is an weighted average of the value of this data interval ignoring zero-intervals, and min and max are the minimum and the maximum values in this data interval. The data interval is either an aggregation of data points or a data point. (see setMinimumInterval() for data point aggregation.) If the data aggregation is disabled, average, min, and max have the same value as value in the 5-tuple data format.

If this method is called without an argument, (i.e. getData() ), it returns whole data stored in the Logger.

If this method is called only with starttime, (i.e. getData( starttime ) ), it returns a slice of the data at and after starttime.

If this method is called with starttime and endtime, (i.e. getData( starttime, endtime ) ), it returns a slice of the data in an interval [ starttime, endtime ].

If this method is called with all the optional parameters starttime, endtime and interval, (i.e. getData( starttime, endtime, interval ) ), it returns a slice of the data in an interval [ starttime, endtime ]. It omits a data interval d(n) if |d(n-1)-d(n+1)| > interval. Be careful about using this feature because the returned data can differ even with the same interval, if starttime is different. Therefore this is not suitable for scientific data analysis, but can be useful for real-time GUI frontends.

getStartTime()
A float

This method returns the time when the Logger is created, or the time the first data is logged by the Logger, either one later. Usually these two times are the same.

getStartTime()
A float

This method returns the last time when data is appended to the Logger.

getSize()
A float

This method is used to get the number of data points this Logger.

getMinimumInterval()
A float

Get the current minimum logging interval of the Logger object.

See setMinimumInterval.

setMinimumInterval( interval )
None

The interval must be a zero or positive real number.

If zero is set, the Logger logs data at every simulation step. In this case data point aggregation is disabled.

If a positive number is set, the Logger can perform datapoint aggregation logging interval is shorter than the specified interval. (FIXME: need to explain more about datapoint aggregation.)

5.8.3. ECDDataFile Class API

ECDDataFile class has the following set of methods.

Table 5-3. ECDDataFile class method list

ECDDataFile methods. 
SynopsisReturn
Description
ECDDataFile( data = None)
None

Constructor. data must be a rank-2 array object of Numeric Python or an equivalent object. If data is not given, an empty matrix ([[]]) is set.

getData()
An array

This method returns the data as a rank-2 array of Numeric Python.

getDataName()
A string

This method returns a name of the data. The default value of the name is an empty string ('').

getFileName()
A string

If either loading or saving of the data from a file is succeeded, this method returns the name of the file. Otherwise this method returns an empty string ('').

getLabel()
A tuple

This method returns the list of axis names as a tuple containing string objects. The default value is ( 't', 'value', 'avg', 'min', 'max' ).

getNote()
A string

This method returns a note field of this ECDDataFile object. The return value is either a single line or a multiline string object.

load( filename )
None

This method loads data from a file filename.

save( filename )
None

This method saves the data to a file filename.

setData( data )
None

This method replaces the data of this ECDDataFile object by data. data must be a rank-2 array of Numeric Python or an equivalent object.

setDataName( name )
None

This method sets the name of this data. name must be a string without a newline.

setLabel( labels)
None

This method names axes of the data. labels must be a Python Sequence containing the name of the axes as strings.

setNote( note )
None

This method sets the note field of this ECDDataFile object. note must be a string object. It can be either a single- or multi-line.