simlpy.cc

// Copyright 2008 Michael Marsh, University of Maryland.
//
// This file is part of pydtn.
//
// pydtn 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 3 of the License, or
// (at your option) any later version.
//
// pydtn 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 pydtn.  If not, see <http://www.gnu.org/licenses/>.
//
// The views and conclusions contained in the software and documentation
// are those of the authors and should not be interpreted as representing
// official policies, either expressed or implied, of the University
// of Maryland.
//
// pydtn extends and embeds the Python interpreter, which is
// Copyright 2001-2006 Python Software Foundation, All Rights Reserved,
// and is released under the PSF License Agreement.
//
// RANLUX random number generation uses the Boost library,
// Copyright 1994-2006 by various authors (details in individual files),
// which is released under the Boost Software License, Version 1.0.

// Python is *so* *important* that its header *must* be loaded *before*
// *any* *other* headers.
#include "interpreter_defs.h"

#include "config.h"
#include "simlpy.h"

#include "Entity.h"
#include "Registry.h"
#include "Terminator.h"
#include "InterpreterEvent.h"
#include "InterpreterEntity.h"
#include "SimulationException.h"

#include "boost/random/ranlux.hpp"

#include <iostream>
#include <vector>
#include <queue>
#include <string>
#include <unistd.h>
#include <stdio.h>


#ifndef PyMODINIT_FUNC
#define PyMODINIT_FUNC extern "C" void
#endif

//==============================================================

typedef struct
{
      PyObject_HEAD
      PyObject* type; 
      Entity* e;      
      int id;         
} PySimEntity;

static char PySimEntity_doc[] = "Simulation entity.\n\
   \n\
   An Entity is created by calling\n\
   \n\
      sim.Entity(<type>)\n\
   \n\
   where <type> is a string corresponding to the unique identifier\n\
   registered for a particular subclass.\n\
   \n\
   The string representation of an Entity is an integer.  While the\n\
   Entity cannot be constructed using this value, it does provide a\n\
   usable handle within the simulator for retrieving the object\n\
   from within the C++ framework.\n";

static PyObject*
PySimEntity_id( PyObject* self )
{
   return PyString_FromFormat("%d",((PySimEntity*)self)->id);
}

static void
PySimEntity_dealloc( PySimEntity* self )
{
   Py_XDECREF( self->type );
   // WE DO NOT DEALLOCATE THE Entity!
   self->ob_type->tp_free((PyObject*)self);
}

void
clean_arglist( Entity::ArgList& alist )
{
   Entity::ArgList::iterator itr = alist.begin();
   Entity::ArgList::iterator end = alist.end();
   for ( ; itr != end ; ++itr )
   {
      Py_DECREF(*itr);
   }
}

void
build_arglist( Entity::ArgList& alist, PyObject* args )
{
   if ( 0 == args ) return;
   if ( ! PyTuple_Check( args ) )
   {
      PyErr_SetString(PyExc_TypeError,"config expects a list of arguments");
      throw SimulationException( __FILE__ , __LINE__ );
   }
   int n = PyTuple_Size( args );
   for ( int i = 0 ; i < n ; ++i )
   {
      PyObject* p = PyTuple_GetItem( args, i );
      if ( 0 == p )
      {
         PyErr_SetString(PyExc_TypeError,"missing argument in list");
         throw SimulationException( __FILE__ , __LINE__ );
      }
      Py_INCREF(p);
      alist.push_back(p);
   }
}

static char PySimEntity_config_doc[] = "Configure the Entity.\n\
   \n\
   Calling syntax for a sim.Entity e:\n\
      e.config(<arg1>,<arg2>,...)\n\
   \n\
   We perform no type checking on the arguments, other than that\n\
   they are in fact a list.  All Python objects passed to this\n\
   method are converted first to Python strings and then to C++\n\
   strings.  The latter are passed to Entity::configure() through\n\
   an Entity::ArgList.\n\
   \n\
   It is up to specific subclasses to interpret the argument list.\n\
   Modules that implement concrete subclasses will document valid\n\
   calls to e.config() for those classes.\n";

static PyObject*
PySimEntity_config( PySimEntity* self, PyObject* args )
{
   Entity::ArgList entityArgs;
   try
   {
      build_arglist( entityArgs, args );
      self->e->configure( entityArgs );
      clean_arglist(entityArgs);
   }
   catch ( ... )
   {
      PyErr_SetString(PyExc_ValueError,
                      "Bad argument list passed to sim.config");
      clean_arglist(entityArgs);
      return 0;
   }
   Py_INCREF(self);
   return (PyObject*)self;
}

static char PySimEntity_emit_doc[] = "Have the Entity emit an Event.\n\
   \n\
   Calling syntax for a sim.Entity e:\n\
      e.emit(<arg1>,<arg2>,...)\n\
   \n\
   We perform no type checking on the arguments, other than that\n\
   they are in fact a list.  All Python objects passed to this\n\
   method are converted first to Python strings and then to C++\n\
   strings.  The latter are passed to Entity::emit() through an\n\
   Entity::ArgList.\n\
   \n\
   It is up to specific subclasses to interpret the argument list.\n\
   Modules that implement concrete subclasses will document valid\n\
   calls to e.config() for those classes.\n";

static PyObject*
PySimEntity_emit( PySimEntity* self, PyObject* args )
{
   Entity::ArgList entityArgs;
   try
   {
      build_arglist( entityArgs, args );
      self->e->emit( entityArgs );
      clean_arglist(entityArgs);
   }
   catch ( ... )
   {
      PyErr_SetString(PyExc_ValueError,
                      "Bad argument list passed to sim.emit");
      clean_arglist(entityArgs);
      return 0;
   }
   Py_INCREF(self);
   return (PyObject*)self;
}

static char PySimEntity_get_doc[] = "Get Entity attributes.\n\
   \n\
   Calling syntax for a sim.Entity e:\n\
      e.get(<arg1>,<arg2>,...)\n\
   \n\
   The arguments are generally strings, specifying Entity\n\
   attributes to query.  The specific Entity subclass determines\n\
   how to interpret the arguments, so fairly complex behavior can\n\
   be implemented through this mechanism.\n\
   \n\
   This method returns something appropriate for the arguments\n\
   provided. The type of this return value is completely\n\
   subclass-dependent.\n\
   \n\
   Modules that implement concrete subclasses will document\n\
   valid calls to e.get() for those classes.\n";

static PyObject*
PySimEntity_get( PySimEntity* self, PyObject* args )
{
   Entity::ArgList entityArgs;
   PyObject* retval = 0;
   try
   {
      build_arglist( entityArgs, args );
      retval = self->e->get( entityArgs ); // New reference
      clean_arglist(entityArgs);
   }
   catch ( ... )
   {
      PyErr_SetString(PyExc_ValueError,
                      "Bad argument list passed to sim.config");
      clean_arglist(entityArgs);
      return 0;
   }
   return retval;
}

static PyMethodDef PySimEntity_methods[] =
{
   { "config",
     (PyCFunction)PySimEntity_config,
     METH_VARARGS,
     PySimEntity_config_doc },
   { "emit",
     (PyCFunction)PySimEntity_emit,
     METH_VARARGS,
     PySimEntity_emit_doc },
   { "get",
     (PyCFunction)PySimEntity_get,
     METH_VARARGS,
     PySimEntity_get_doc },
   {0} // sentinel
};

static PyMemberDef PySimEntity_members[] =
{
   {"type", T_OBJECT_EX, offsetof(PySimEntity, type), 0, "Entity type"},
   {0} // sentinel
};

static PyTypeObject sim_PySimEntity = {
   PyObject_HEAD_INIT(0)
   0,                         // ob_size
   "sim.Entity",              // tp_name
   sizeof(PySimEntity),       // tp_basicsize
   0,                         // tp_itemsize
   (destructor)PySimEntity_dealloc, // tp_dealloc
   0,                         // tp_print
   0,                         // tp_getattr
   0,                         // tp_setattr
   0,                         // tp_compare
   PySimEntity_id,            // tp_repr
   0,                         // tp_as_number
   0,                         // tp_as_sequence
   0,                         // tp_as_mapping
   0,                         // tp_hash
   0,                         // tp_call
   0,                         // tp_str
   0,                         // tp_getattro
   0,                         // tp_setattro
   0,                         // tp_as_buffer
   Py_TPFLAGS_DEFAULT,        // tp_flags
   PySimEntity_doc,           // tp_doc
   0,                         // tp_traverse
   0,                         // tp_clear
   0,                         // tp_richcompare
   0,                         // tp_weaklistoffset
   0,                         // tp_iter
   0,                         // tp_iternext
   PySimEntity_methods,       // tp_methods
   PySimEntity_members,       // tp_members
   0,                         // tp_getset
   0,                         // tp_base
   0,                         // tp_dict
   0,                         // tp_descr_get
   0,                         // tp_descr_set
   0,                         // tp_dictoffset
   0,                         // tp_init
   0,                         // tp_alloc
   0,                         // tp_new
};


//==============================================================

typedef std::vector< PySimEntity* > SimEntityVec;

static SimEntityVec entityList;

static Terminator kronos;

static InterpreterEntity iEntity;

static PyObject* sim_args;



static PyObject*
sim_entity( PyTypeObject* type, PyObject* args, PyObject* kwds )
{
   const char* eType;
   if ( ! PyArg_ParseTuple(args, "s", &eType) )
   {
      std::cerr << "Incorrect argument list" << std::endl;
      return 0;
   }
   const Entity* e = 0;
   try
   {
      e = Registry::lookup( eType );
   }
   catch ( ... )
   {
      std::string errString = "No entity type \"";
      errString += eType;
      errString += "\" registered";
      PyErr_SetString(PyExc_KeyError,errString.c_str());
      return 0;
   }
   Entity* newE = e->create();
   if ( 0 == newE )
   {
      std::cerr << "Could not allocate a new " << eType << std::endl;
      return PyErr_NoMemory();
   }

   return export_entity(newE);
}

//==============================================================

static char sim_time_doc[] = "Get the current simulator time.\n\
   \n\
   This function, which takes no arguments, returns a list of\n\
   the form:\n\
   \n\
      [ seconds , microseconds ]\n\
   \n\
   corresponding to the current time in the simulator.\n\
   \n\
   If no events have been processed since starting simlpy, this\n\
   will have the value\n\
   \n\
      [0L, 0L]\n\
   \n\
   Otherwise, it will typically return the time of the last-\n\
   scheduled sim.stopAt() call.\n";

static PyObject*
sim_time( PyObject* self, PyObject* args )
{
   return construct_time( Clock::time() );
}

static char sim_timeAsDouble_doc[] = "Get the current simulator time.\n\
   \n\
   This function, which takes no arguments, returns the current\n\
   time in seconds.\n\
   \n\
   If no events have been processed since starting simlpy, this\n\
   will have the value\n\
   \n\
      [0L, 0L]\n\
   \n\
   Otherwise, it will typically return the time of the last-\n\
   scheduled sim.stopAt() call.\n";

static PyObject*
sim_timeAsDouble( PyObject* self, PyObject* args )
{
   const Time& t = Clock::time();
   double dt = t.tv.tv_sec + 1.0*t.tv.tv_usec/Time::MILLION;
   return construct_double(dt);
}

static char sim_run_doc[] = "Start a simulation run.\n\
   \n\
   This is, in effect, the main loop of the simulator.  As long\n\
   as the simulator is still in its running state, this routine\n\
   will continue to consume simulation events.  The loop will exit\n\
   when there are no more events to process or when it processes\n\
   an event scheduled by calling sim.stopAt().\n";

static PyObject*
sim_run( PyObject* self, PyObject* args )
{
   Clock::setRunning( true );
   while ( Clock::running() )
   {
      Clock::tick();
   }
   Py_INCREF(Py_None);
   return Py_None;
}

static char sim_stopAt_doc[] = "Set an end time for the simulation.\n\
   \n\
   Calling syntax:\n\
      sim.stopAt( [<s>,<us>] )\n\
   \n\
   The list provided is a simulation time expressed in\n\
   seconds and microseconds.  Calling this function schedules\n\
   an event for this time that will cause the simulation to stop.\n\
   \n\
   Stopping the simulation does not cause simlpy to exit.  Rather,\n\
   it continues processing input.  A subsequent call to sim.run()\n\
   will resume the simulation from the point at which it stopped.\n\
   If there is no more input, and a sys.exit() or similar has not\n\
   been processed, control is returned to the user at an interactive\n\
   prompt.\n";

static PyObject*
sim_stopAt( PyObject* self, PyObject* args )
{
   try
   {
      kronos.stopAt(parse_time(PyTuple_GetItem(args,0)));
   }
   catch( ... )
   {
      return 0;
   }
   Py_INCREF(Py_None);
   return Py_None;
}

static char sim_collect_doc[] = "Collect information from Entitys.\n\
   \n\
   When called, this will loop over all Entitys created by the\n\
   sim module, and will run that object's collect() method\n\
   in C++.  The default behavior for an Entity is to do nothing.\n\
   \n\
   See the documentation for a specific module for the behavior\n\
   of its Entity subclasses when this is called.\n";

static PyObject*
sim_collect( PyObject* self, PyObject* args )
{
   SimEntityVec::iterator itr = entityList.begin();
   SimEntityVec::iterator end = entityList.end();
   for ( ; itr != end ; ++itr )
   {
      if ( 0 != (*itr)->e )
      {
         (*itr)->e->collect();
      }
   }
   Py_INCREF(Py_None);
   return Py_None;
}

static boost::ranlux3_01 sim_prng;

void
seed_prng( unsigned long int s )
{
   sim_prng.seed(s);
}

float
prng()
{
   return sim_prng();
}

static char sim_seed_doc[] = "Seed the random number generator.\n\
   \n\
   Calling syntax:\n\
      sim.seed( i )\n\
      sim.seed()\n\
   \n\
   When called, this will seed the random number generator\n\
   with the supplied integer i.  If no seed value is given,\n\
   one will be selected and reported on the console.\n";

static PyObject*
sim_seed( PyObject* self, PyObject* args )
{
   unsigned int s;
   Entity::ArgList alist;
   build_arglist( alist, args );
   if ( alist.empty() )
   {
      // not a perfect match, but if we have higher-order bytes, we
      // really don't care
      union time_int
      {
            int i;
            char c[4];
      };
      struct timeval tv;
      gettimeofday(&tv,0);
      time_int seconds;
      seconds.i = tv.tv_sec;
      time_int useconds;
      useconds.i = tv.tv_usec;
      time_int seed;
      seed.i = 0;
      // All bytes will change fairly quickly, though some of the bits
      // will be a little slower.  This really isn't a problem,
      // though.
      seed.c[0] = seconds.c[0] ^ seconds.c[3] ^ useconds.c[0];
      seed.c[1] = seconds.c[1] ^ seconds.c[2] ^ useconds.c[1];
      seed.c[2] = seconds.c[2] ^ seconds.c[1] ^ useconds.c[2];
      seed.c[3] = seconds.c[3] ^ seconds.c[0] ^ useconds.c[3];
      s = seed.i;
      seed_prng( s );
      std::cout << "Random number seed = " << s
                << " (" << std::hex << s << ")" << std::dec
                << std::endl;
   }
   else
   {
      try
      {
         s = parse_long(alist[0]);
         seed_prng( s );
      }
      catch ( ... )
      {
         std::cerr << "usage: sim.seed( i )" << std::endl;
         return 0;
      }
   }
   return construct_ulong(s);
}

static char sim_random_doc[] = "Call the random number generator.\n\
   \n\
   Calling syntax:\n\
      r = sim.random()\n\
   \n\
   When called, this will return the next pseudo-random number\n\
   in the sequence, as a float in the range [0,1).\n";

static PyObject*
sim_random( PyObject* self, PyObject* args )
{
   return construct_double( prng() );
}

static char sim_get_args_doc[] = "Get command-line arguments.\n\
   \n\
   Calling syntax:\n\
      l = sim.args()\n\
   \n\
   When called, this returns a list of the arguments supplied to\n\
   simlpy on the command line with the \"-a\" flag.  All arguments\n\
   are returned as strings, and must be converted to other types\n\
   as appropriate.\n";

static PyObject*
sim_get_args( PyObject* self, PyObject* args )
{
   Py_INCREF(sim_args);
   return sim_args;
}

static char sim_schedule_doc[] = "Schedule a python function.\n\
   \n\
   Calling syntax:\n\
      sim.schedule(t,f)\n\
   \n\
   This schedules the function f to be run at simulation time t.\n\
   For example:\n\
   \n\
   def f():\n\
      print sim.time()\n\
   sim.schedule(10,f)\n\
   sim.run()\n\
   \n\
   would produce the output:\n\
   \n\
   [10L, 0L]\n\
   \n\
   f may also be any callable python object.\n";

static PyObject*
sim_schedule( PyObject* self, PyObject* args )
{
   Entity::ArgList alist;
   try
   {
      build_arglist( alist, args );
      if ( 2 != alist.size() )
      {
         std::cerr << "sim.schedule() expected 2 arguments, "
                   << alist.size() << " provided"
                   << std::endl;
         throw SimulationException( __FILE__ , __LINE__ );
      }
      Time t = parse_time( alist[0] );
      InterpreterItem f = alist[1];
      if ( ! PyCallable_Check(f) )
      {
         throw SimulationException( __FILE__ , __LINE__ );
      }
      Clock::schedule( new InterpreterEvent( &iEntity, &iEntity, t, f ) );
      clean_arglist( alist );
   }
   catch ( ... )
   {
      PyErr_SetString(PyExc_ValueError,
                      "Bad argument list passed to sim.schedule");
      clean_arglist(alist);
      return 0;
   }
   Py_INCREF(Py_None);
   return Py_None;
}

static PyMethodDef SimMethods[] =
{
   {"time",sim_time,METH_NOARGS,sim_time_doc},
   {"timeAsDouble",sim_timeAsDouble,METH_NOARGS,sim_timeAsDouble_doc},
   {"run",sim_run,METH_NOARGS,sim_run_doc},
   {"stopAt",sim_stopAt,METH_VARARGS,sim_stopAt_doc},
   {"collect",sim_collect,METH_NOARGS,sim_collect_doc},
   {"seed",sim_seed,METH_VARARGS,sim_seed_doc},
   {"random",sim_random,METH_NOARGS,sim_random_doc},
   {"args",sim_get_args,METH_VARARGS,sim_get_args_doc},
   {"schedule",sim_schedule,METH_VARARGS,sim_schedule_doc},
   {0,0,0,0} // sentinel
};

static char SimDoc[] = "Simulator namespace.\n\
   \n\
   The sim module, which is imported into simlpy by default,\n\
   contains the classes and methods needed for basic simulation\n\
   control.  Specific functional simulator elements are added\n\
   by importing additional modules, such as pydtn, into simlpy.\n";



//==============================================================

PyMODINIT_FUNC
initsim()
{
   sim_PySimEntity.tp_new = sim_entity;
   if ( PyType_Ready(&sim_PySimEntity) < 0 )
   {
      return;
   }

   PyObject* m = Py_InitModule3("sim",SimMethods,SimDoc);
   Py_INCREF(&sim_PySimEntity);
   PyModule_AddObject(m, "Entity", (PyObject*)&sim_PySimEntity);
   if ( PyRun_SimpleString("import sim") < 0 )
   {
      std::cerr << "Error importing sim\n"
                << "exiting" << std::endl;
      ::exit(1);
   }
}



//==============================================================

// Python-specific version of hook
void
add_entity( Entity* e )
{
   try
   {
      Registry::insert( e );
   }
   catch ( ... )
   {
      std::cerr << "failed to register an Entity" << std::endl;
   }
}

unsigned int
num_entities()
{
   return entityList.size();
}

InterpreterItem
get_entity(unsigned int i)
{
   if ( i >= entityList.size() )
   {
      throw SimulationException( __FILE__ , __LINE__ );
   }
   return (PyObject*)(entityList[i]);
}

// Python-specific version of hook
ItemWrapper
resolve_symbol( InterpreterItem e )
{
   ItemWrapper retval;
   if ( ! PyObject_TypeCheck(e,&sim_PySimEntity) )
   {
      PyErr_SetString(PyExc_TypeError,"expected a sim.Entity");
      throw SimulationException( __FILE__ , __LINE__ );
   }
   unsigned int id = ((PySimEntity*)e)->id;
   if ( id >= entityList.size() )
   {
      PyErr_SetString(PyExc_IndexError,"unknown sim.Entity");
      throw SimulationException( __FILE__ , __LINE__ );
   }
   PySimEntity* pse = entityList[id];
   if ( 0 == pse )
   {
      PyErr_SetString(PyExc_KeyError,"unknown sim.Entity");
      throw SimulationException( __FILE__ , __LINE__ );
   }
   retval.type = PyString_AsString(pse->type);
   retval.id = e;
   retval.item = pse->e;
   return retval;
}

long int
parse_long( const InterpreterItem l )
{
   long int retval = 0;
   if ( PyLong_Check( l ) )
   {
      retval = PyLong_AsLong(l);
   }
   else if ( PyInt_Check( l ) )
   {
      retval = PyInt_AsLong(l);
   }
   else
   {
      PyErr_SetString(PyExc_TypeError,"an integer was expected");
      throw SimulationException( __FILE__ , __LINE__ );
   }
   return retval;
}

double
parse_double( const InterpreterItem d )
{
   double retval = 0;
   if ( PyFloat_Check(d) )
   {
      retval = PyFloat_AsDouble(d);
   }
   else if ( PyLong_Check(d) )
   {
      retval = PyLong_AsDouble(d);
   }
   else if ( PyInt_Check(d) )
   {
      retval = PyInt_AsLong(d); // not ideal, but the best we can do
   }
   else
   {
      PyErr_SetString(PyExc_TypeError,"a real number was expected");
      throw SimulationException( __FILE__ , __LINE__ );
   }
   return retval;
}

std::string
parse_string( const InterpreterItem s )
{
   if ( ! PyString_Check( s ) )
   {
      PyErr_SetString(PyExc_TypeError,"a string was expected");
      throw SimulationException( __FILE__ , __LINE__ );
   }
   // This is a bit more complicated than it might seem like it should
   // be.  The reason for this is that we have to consider cases where
   // there are meaninful NULs in the data.
   const char* sbuf = PyString_AsString(s);
   std::string retval;
   for ( int i = 0 ; i < PyString_Size(s) ; ++i )
   {
      retval += sbuf[i];
   }
   return retval;
}

// Python-specific version of hook
Time
parse_time( const InterpreterItem t )
{
   long sec=0;
   long usec=0;

   // Try to interpret it as a list, first.
   if ( PyList_Check( t ) )
   {
      int n = PyList_Size( t );
      if ( n < 2 )
      {
         PyErr_SetString(PyExc_TypeError,"a list [s,us] was expected");
         throw SimulationException( __FILE__ , __LINE__ );
      }

      sec = parse_long( PyList_GetItem( t, 0 ) );
      usec = parse_long( PyList_GetItem( t, 1 ) );
   }
   else
   {
      // Next, try as an integer or long int.
      try
      {
         sec = parse_long(t);
      }
      catch(...)
      {
         // Failing that, try as a double.
         PyErr_Clear(); // cancel the previous exception
         try
         {
            double d = parse_double(t);
            sec = (long int) ::floor(d);
            usec = (long int) ::floor( Time::MILLION * (d-sec) );
         }
         catch(...)
         {
            PyErr_SetString(PyExc_TypeError,
                            "could not interpret value as a time");
            throw SimulationException( __FILE__ , __LINE__ );
         }
      }
   }
   return Time(sec,usec);
}

InterpreterItem
construct_string( const std::string& s )
{
   return PyString_FromStringAndSize( s.data(), s.length() );
}

InterpreterItem
construct_double( double d )
{
   return PyFloat_FromDouble(d);
}

InterpreterItem
construct_long( long int l )
{
   return PyLong_FromLong(l);
}

InterpreterItem
construct_ulong( unsigned long int l )
{
   return PyLong_FromUnsignedLong(l);
}

InterpreterItem construct_list( Entity::ArgList& alist )
{
   PyObject* p = PyList_New(0);
   if ( 0 == p )
   {
      return 0;
   }
   Entity::ArgList::iterator itr = alist.begin();
   Entity::ArgList::iterator end = alist.end();
   for ( ; itr != end ; ++itr )
   {
      // Takes over reference.
      PyList_Append( p, *itr );
   }
   return p;
}

InterpreterItem construct_boolean( bool b )
{
   return PyBool_FromLong(b);
}

InterpreterItem construct_time( const Time& t )
{
   PyObject* p = PyList_New(0);
   if ( 0 == p )
   {
      return 0;
   }
   PyList_Append( p, PyLong_FromLong(t.tv.tv_sec) );
   PyList_Append( p, PyLong_FromLong(t.tv.tv_usec) );
   return p;
}

static unsigned char vlevel = 0;

unsigned char
verbosity()
{
   return vlevel;
}

PyObject*
export_entity( Entity* e )
{
   if ( 0 == e ) return 0;

   // Create the PyObject*
   PySimEntity* self =
      (PySimEntity*)sim_PySimEntity.tp_alloc(&sim_PySimEntity,0);
   if ( 0 == self )
   {
      std::cerr << "Could not allocate a new sim.Entity" << std::endl;
      return 0;
   }
   self->type = PyString_FromString( e->identifier().c_str() );
   if ( 0 == self->type )
   {
      Py_DECREF(self);
      return 0;
   }
   self->e = e;
   self->id = entityList.size();
   entityList.push_back(self);
   // Increment the reference count twice: once for the object returned
   // and once for entityList.
   Py_INCREF(self);
   Py_INCREF(self);

   return (PyObject*)self;
}



//==============================================================

void
cleanup()
{
   SimEntityVec::iterator itr = entityList.begin();
   SimEntityVec::iterator end = entityList.end();
   for ( ; itr != end ; ++itr )
   {
      if ( 0 != (*itr)->e )
      {
         (*itr)->e->finalize();
         delete (*itr)->e;
      }
      PySimEntity_dealloc( *itr );
   }
   Registry::clean();
}

int main(int argc, char** argv)
{
   typedef std::queue< std::string > StringQ;

   // Parse command-line flags using getopt(3).
   std::string python_path;
   StringQ module_path;
   StringQ import_files;
   Entity::ArgList alist;
   int arg = 0;
   while ( -1 != arg )
   {
      arg = getopt(argc,argv,"p:i:L:va:");
      switch(arg)
      {
         case 'p' :
            python_path = optarg;
            break;
         case 'i' :
            import_files.push( optarg );
            break;
         case 'L' :
            module_path.push( optarg );
            break;
         case 'v' :
            ++vlevel;
            break;
         case 'a' :
            alist.push_back( construct_string(optarg) );
            break;
         case ':' :
         case '?' :
            std::cerr << "Add usage string!!" << std::endl;
            ::exit(1);
      }
   }

   sim_args = construct_list(alist);

   // What remains (if anything) should be Python script files.
   StringQ script_files;
   for ( int i = optind ; i < argc ; ++i )
   {
      script_files.push( argv[i] );
   }

   // Start the interpreter, feeding it the above files.
   if ( python_path.length() > 0 )
   {
      Py_SetProgramName((char*)python_path.c_str());
   }
   else
   {
      // Stupid hack -- The embedded interpreter doesn't know where the
      // executable is, even though it's been compiled and linked with
      // files from the appropriate directory.  Consequently, sys.path
      // is completely buggered for non-standard python installation
      // directories.
      Py_SetProgramName((char*)PYEXE);
   }
   Py_AtExit( cleanup );
   Py_Initialize();
   PySys_SetArgv(argc,argv);

   // simulator configuration
   initsim();

   // HACK: we need to set up the module search path
   PyRun_SimpleString("import sys");
   PyRun_SimpleString("sys.path.append('"SHLIB_DIR"')");
   PyRun_SimpleString("sys.path.append('.')");
   while ( ! module_path.empty() )
   {
      std::string dir = module_path.front();
      module_path.pop();
      std::string cmd = "sys.path.append('";
      cmd += dir;
      cmd += "')";
      if ( PyRun_SimpleString((char*)cmd.c_str()) < 0 )
      {
         std::cerr << "Error adding " << dir << " to the path\n"
                   << "exiting" << std::endl;
         ::exit(1);
      }
   }

   // the modules to import
   while ( ! import_files.empty() )
   {
      std::string mod = import_files.front();
      import_files.pop();
      std::string cmd = "import ";
      cmd += mod;
      if ( PyRun_SimpleString((char*)cmd.c_str()) < 0 )
      {
         std::cerr << "Error importing " << mod << "\n"
                   << "exiting" << std::endl;
         ::exit(1);
      }
   }

   // the scripts to run
   while ( ! script_files.empty() )
   {
      std::string scr = script_files.front();
      script_files.pop();
      FILE* fp = fopen(scr.c_str(),"r");
      if ( 0 == fp )
      {
         std::cerr << "Could not open script file " << scr << "\n"
                   << "exiting" << std::endl;
         ::exit(1);
      }
      if ( PyRun_SimpleFile(fp,(char*)(scr.c_str())) < 0 )
      {
         std::cerr << "Error running file " << scr << "\n"
                   << "exiting" << std::endl;
         ::exit(1);
      }
      fclose(fp);
   }

   // If we've gotten this far, we're a candidate for successful completion.
   int retval = 0;

   // If we're still active when all files have been processed, drop
   // into the interactive interpreter.
   if ( Py_IsInitialized() )
   {
      PyRun_SimpleString("import readline");
      retval = PyRun_InteractiveLoop(stdin,"<stdin>");
   }

   // At this point, we might as well explicitly clean up allocated memory.
   Py_Exit( retval );

   return retval;
}

---