=======================================================================
Release notes for E-Cell Simulation Environment Version 3 (E-Cell SE 3)
=======================================================================

Koichi Takahashi <shafi@e-cell.org>

What is E-Cell System?
======================
E-Cell is a generic software package for cellular modeling and simulation.  

Files and directories
=====================
In the package, files are organized as follows::

  -+- README:    This file
   |
   +- INSTALL:   Installation instructions
   |
   +- ChangeLog: Automatically generated cvs log 
   |
   +- NEWS:      Project log
   |
   +- COPYING:   License
   |
   +- AUTHORS:   List of authors
   |
   +- ecell/ --> Core portion of E-Cell SE 3, or Hekkoro
   |  |
   |  +- libecs/       --> Koyurugi: Class library for cell modeling and
   |  |                    simulation (E-Cell SE 3's innermost core)
   |  +- libemc/       --> E-Cell Micro Core (EMC): C++ Facade API of Koyurugi
   |  |
   |  +- pyecs/        --> Python binding of EMC and Koyurugi
   |  |
   |  +- pyecell/      --> Python E-Cell library
   |  |
   |  +- session-monitor/  --> GUI session monitor (gecell)
   |  |
   |  +- model-editor/ --> GUI model editor (ecell3-modeleditor)
   |  |
   |  +- toollauncher/ --> GUI tool launcher 
   |
   +- dmtool/          --> C++ class library for dynamic loading of object
   |
   +- doc/             --> Documentations 
   |  |
   |  +- users-manual/ --> Users manual
   |  |
   |  +- samples/      --> Sample models
   |
   +- libltdl/         --> Libtool's dynamic module loader library

And installed in the following structure::

 PREFIX -+- bin/       --> E-Cell system toolsuite
         |
         +- include/   --> Header files (for developers)
         |  |
         |  +- dmtool/
         |  |
         |  +- ecell-3.1/
         |     |
         |     +- libecs/
         |     |
         |     +- libemc/
         |
         +- lib/       --> Shared libraries and python modules
         |  |
         |  +- python?.?/  --> Python modules
         |  |
         |  +- ecell-3.1/
         |     |
         |     +- dms      --> Standard dynamic modules
         |     |
         |     +- model-editor     --> Scripts and data for Model Editor
         |     |
         |     +- session-monitor  --> Scripts and data for Session Monitor
         |     |
         |     +- toollauncher     --> Scripts and data for Tool Launcher
         |
         +- share/
            |
            +- ecell-3.1/
            |  |
            |  +- dms/     --> Sources for the standard dynamic modules.
            |
            +- doc/
               |
               +- ecell/   --> E-Cell Documents
                  |
                  +- samples/      --> Sample models
                  |
                  +- users-manual* --> Users manual
                  |
                  +- api           --> API reference
                  |
                  +- model-editor  --> Model Editor documentation


About the code names
--------------------
Hekkoro
    Code name for E-Cell SE Version 3 (libecs, libemc and pyecs)
Koyurugi
    Code name for the libecs class library
Osogo
    Code name for the GUI Session monitor (gecell)

Documentation
=============
E-Cell 3 users manual is placed under ``{PREFIX}/share/doc/users-manual``.

If you have doxygen, API reference will be built and installed in
``{PREFIX}/share/doc/api`` .

Basic Usage
===========

1. Using E-Cell from python interpreter
---------------------------------------
By default a python binding (pyecs) is built.

To invoke a E-Cell Session Script interpreter in interactive mode, use ``ecell3-sesion`` script. Note that the script expects {PREFIX}/bin is included in PATH environment, where {PREFIX} is the directory path that was specified to configure. 
(If you have not specified it, it falls back to ``/usr/local``.)

A typical command-line session is as follows::

   $ ecell3-session
   ecell3-session [ E-Cell SE Version 3.1.106, on Python Version 2.3.4 ]
   Copyright (C) 1996-2010 Keio University.
   Send feedback to Koichi Takahashi <shafi@e-cell.org>
   ecell3-session>>>

In the above output, ``ecell3-session>>>`` is the prompt of ecell3-session. That accepts almost everything of interactive Python.

The below example first loads a model that is stored in simple.eml, and then run it for 10 seconds in simulation time::

   ecell3-session>>> loadModel( 'simple.eml' )
   <simple.eml, t=0>>> run( 10 )
   <simple.eml, t=10.001>>>

2. Using E-Cell from Session Monitor GUI
----------------------------------------
If you have python, and pygtk2 installed, a GUI session monitor, is built.

To use Session Monitor, type::

   $ ecell3-session-monitor

Sample Models
=============

Sample models are installed under {PREFIX}/share/doc/samples.  Each model is
stored as a EM script, while ecell toolsuite only accept XML-based EML files.

EM scripts can be converted to EML files through the program ``ecell3-em2eml``::

   $ ecell3-em2eml Drosophila.em

This will create Drosophila.eml in the current working directory.

Some samples require that the accompanying dynamic modules (DM's) be
built before running simulation.  These modules are provided as C++ sources
which can be compiled using ``ecell3-dmc``::

   $ ecell3-dmc SomeModule.cpp

For more information about the dynamic module, refer to the users manual.


Copyright Notice
================
E-Cell System is distributed under the GNU General Public License
version 2.

  Copyright (C) 1996-2010 Keio University
  Copyright (C) 2005-2010 The Molecular Sciences Institute

  E-Cell System is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public
  License as published by the Free Software Foundation; either
  version 2 of the License, or (at your option) any later version.
  
  E-Cell System is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  See the GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public
  License along with E-Cell System -- see the file COPYING.
  If not, write to the Free Software Foundation, Inc.,
  59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 
It should be mentioned this package contains the following softwares
for convenience.  Please note that these are not covered by the license
under which a copy of E-Cell System is licensed to you, while neither
composition nor distribution of any derivative work of E-Cell System with
these software violates the terms of each license, provided that it meets
every condition of the respective licenses.

* PLY

  PLY is written by David M. Beazley and distributed under the GNU
  Lesser General Public License.  See COPYING.LGPLv2 or COPYING.LGPLv3 for the
  full license terms of the LGPL(s).

    Author: David M. Beazley (beazley@cs.uchicago.edu)
            Department of Computer Science
            University of Chicago
            Chicago, IL  60637
    
    Copyright (C) 2001, David M. Beazley
    
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.
    
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.
    
    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  The website for this software is located at:

    http://www.dabeaz.com/ply/

* EmPy 

  EmPy is written by Erik Max Francis and distributed under the GNU Lesser
  General Public License.  See COPYING.LGPLv2 or COPYING.LGPLv3 for the full
  license terms of the LGPL(s).

    Copyright (C) 2002-2003 Erik Max Francis <max@alcyone.com>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.
    
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.
    
    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  The website for this software is located at:

    http://www.alcyone.com/software/empy/

* libltdl

  libltdl is part of libtool, whose copyright is held by Free Software
  Foundation.  See COPYING.LGPLv2 or COPYING.LGPLv3 for the full license terms
  of the LGPL(s).

    Copyright (C) 1998, 1999, 2000 Free Software Foundation, Inc.
    Originally by Thomas Tanner <tanner@ffii.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.
     
    As a special exception to the GNU Lesser General Public License,
    if you distribute this file as part of a program or library that
    is built using GNU libtool, you may include it under the same
    distribution terms that you use for the rest of that program.
       
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

  The website for this software is located at:

    http://www.gnu.org/software/libtool/

* The Loki Library

  Libecs contains part of The Loki Library, which is writen by Andrei 
  Alexandrescu and the contributors.

    Copyright (c) 2001 by Andrei Alexandrescu

    This code accompanies the book:
    Alexandrescu, Andrei. "Modern C++ Design: Generic Programming and Design 
    Patterns Applied". Copyright (c) 2001. Addison-Wesley.

    Permission to use, copy, modify, distribute and sell this software for any 
    purpose is hereby granted without fee, provided that the above copyright 
    notice appear in all copies and that both that copyright notice and this 
    permission notice appear in supporting documentation.

    The author or Addison-Wesley Longman make no representations about the 
    suitability of this software for any purpose. It is provided "as is" 
    without express or implied warranty.

  The website for this software is located at:

    http://loki-lib.sourceforge.net/

* TableIO

   Table IO is a module for reading ASCII tables from files to Python lists
   written by Michael A. Miller and distributed under the GNU General Public
   License.  See COPYING.GPLv2 or COPYING.GPLv3 for the full license terms of
   the GPL(s).

     Copyright (C) 2000 Michael A. Miller <mmiller@debian.org>

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License as
     published by the Free Software Foundation; either version 2 of the
     License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
     USA. 

  The website for this software is located at:

     http://php.iupui.edu/~mmiller3/python/

$Id: README 3644 2010-01-03 02:25:31Z moriyoshi $

