Simulator.hpp

00001 //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
00002 //
00003 //        This file is part of E-Cell Simulation Environment package
00004 //
00005 //                Copyright (C) 1996-2002 Keio University
00006 //
00007 //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
00008 //
00009 //
00010 // E-Cell is free software; you can redistribute it and/or
00011 // modify it under the terms of the GNU General Public
00012 // License as published by the Free Software Foundation; either
00013 // version 2 of the License, or (at your option) any later version.
00014 // 
00015 // E-Cell is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00018 // See the GNU General Public License for more details.
00019 // 
00020 // You should have received a copy of the GNU General Public
00021 // License along with E-Cell -- see the file COPYING.
00022 // If not, write to the Free Software Foundation, Inc.,
00023 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
00024 // 
00025 //END_HEADER
00026 //
00027 // written by Koichi Takahashi <shafi@e-cell.org>,
00028 // E-Cell Project.
00029 //
00030 
00031 
00032 #ifndef __SIMULATOR_HPP
00033 #define __SIMULATOR_HPP
00034 
00035 #include "libecs/libecs.hpp"
00036 #include "libecs/EntityType.hpp"
00037 #include "libecs/Polymorph.hpp"
00038 #include "libecs/DataPointVector.hpp"
00039 
00040 #include "libemc.hpp"
00041 #include "SimulatorImplementation.hpp"
00042 
00043 
00044 #include <stdio.h>
00045 namespace libemc
00046 {
00047   
00048   /** @defgroup libemc_module The Libemc Module 
00049    * This is the libemc module 
00050    * @{ 
00051    */ 
00052   
00053 
00054   /**
00055      The interface to the simulator.
00056 
00057      Simulator class provides a unified API to the libecs, 
00058      C++ library for cell modeling and simulation.
00059 
00060      Unlike libecs::Model class, this API does involve only standard
00061      C++ types/classes, and doesn't depend on libecs classes.  An only
00062      exception is Polymorph class.
00063 
00064      The public API methods are classified into these four groups:
00065 
00066      - Entity methods
00067      - Stepper methods
00068      - Logger methods, and
00069      - Simulator methods
00070      
00071      @see libecs
00072      @see Model
00073      @see SimulatorImplementation
00074   */
00075 
00076   class ECELL_API Simulator
00077   {
00078 
00079   public:
00080 
00081     Simulator();
00082     virtual ~Simulator() {}
00083 
00084 
00085     /**
00086        @name Stepper methods.
00087     */
00088 
00089     //@{
00090 
00091     /**
00092        Create a new Stepper in the model.
00093 
00094        @param aClassname a classname of the Stepper to create.
00095        @param anID       an ID of the Stepper.
00096        @param aParameterList a list of parameters to give to the Stepper
00097     */
00098 
00099     void createStepper( libecs::StringCref          aClassname,
00100                         libecs::StringCref          anId )
00101     {
00102       theSimulatorImplementation->createStepper( aClassname, anId );
00103     }
00104 
00105     /**
00106        Delete a Stepper.  This method is not supported yet.
00107 
00108     */
00109 
00110     void deleteStepper( libecs::StringCref anID )
00111     {
00112       theSimulatorImplementation->deleteStepper( anID );
00113     }
00114 
00115     /**
00116        List Steppers in the model.
00117 
00118        @returh a list of Steppers.
00119     */
00120 
00121     const libecs::Polymorph getStepperList() const
00122     {
00123       return theSimulatorImplementation->getStepperList();
00124     }
00125 
00126     /**
00127        List names of properties of a Stepper.
00128     
00129        @return a list of properties of a Stepper.
00130     */
00131 
00132     const libecs::Polymorph 
00133     getStepperPropertyList( libecs::StringCref aStepperID ) const
00134     {
00135       return theSimulatorImplementation->getStepperPropertyList( aStepperID );
00136     }
00137 
00138 
00139     /**
00140        Get attributes of a property of a Stepper.
00141 
00142        The attributes are returned as a form of boolean 2-tuple 
00143        ( setable, getable ).  ( 1, 0 ) means that the property is setable but
00144        not getable,,, and so on.
00145 
00146        @return Stepper property attributes.
00147     */
00148 
00149     const libecs::Polymorph 
00150     getStepperPropertyAttributes( libecs::StringCref aStepperID, 
00151                                   libecs::StringCref aPropertyName ) const
00152     {
00153       return theSimulatorImplementation->
00154         getStepperPropertyAttributes( aStepperID, aPropertyName );
00155     }
00156 
00157   
00158     /**
00159        Set a property value of a Stepper.
00160 
00161        @param aStepperID    the Stepper ID.
00162        @param aValue        the value to set as a Polymorph.
00163     */
00164 
00165     void setStepperProperty( libecs::StringCref          aStepperID,
00166                              libecs::StringCref          aPropertyName,
00167                              libecs::PolymorphCref aValue )
00168     {
00169       theSimulatorImplementation->setStepperProperty( aStepperID,
00170                                                       aPropertyName,
00171                                                       aValue );
00172     }
00173 
00174     /**
00175        Get a value of a property from a Stepper.
00176 
00177        @param aStepperID the Stepper ID.
00178        @param aPropertyName the name of the property.
00179        @return the property value as a reference counted pointor of a 
00180        Polymorph.
00181     */
00182 
00183     const libecs::Polymorph
00184     getStepperProperty( libecs::StringCref aStepperID,
00185                         libecs::StringCref aPropertyName ) const
00186     {
00187       return theSimulatorImplementation->getStepperProperty( aStepperID,
00188                                                              aPropertyName );
00189     }
00190 
00191 
00192     /**
00193        Load a property value of a Stepper.
00194 
00195        @param aStepperID    the Stepper ID.
00196        @param aValue        the value to set as a Polymorph.
00197     */
00198 
00199     void loadStepperProperty( libecs::StringCref          aStepperID,
00200                               libecs::StringCref          aPropertyName,
00201                               libecs::PolymorphCref aValue )
00202     {
00203       theSimulatorImplementation->loadStepperProperty( aStepperID,
00204                                                        aPropertyName,
00205                                                        aValue );
00206     }
00207 
00208     /**
00209        Get a value of a property from an Stepper.
00210 
00211        @param aStepperID the Stepper ID.
00212        @param aPropertyName the name of the property.
00213        @return the property value as a reference counted pointor of a 
00214        Polymorph.
00215     */
00216 
00217     const libecs::Polymorph
00218     saveStepperProperty( libecs::StringCref aStepperID,
00219                          libecs::StringCref aPropertyName ) const
00220     {
00221       return theSimulatorImplementation->saveStepperProperty( aStepperID,
00222                                                               aPropertyName );
00223     }
00224 
00225     /**
00226        Get class name of a Stepper.
00227 
00228        @param aStepperID the Stepper ID.
00229 
00230        @return the class name.
00231     */
00232 
00233     const libecs::String
00234     getStepperClassName( libecs::StringCref aStepperID ) const
00235     {
00236       return theSimulatorImplementation->getStepperClassName( aStepperID );
00237     }
00238 
00239 
00240     //@}
00241 
00242     const libecs::PolymorphMap getClassInfo( libecs::StringCref aClasstype,
00243                                            libecs::StringCref aClassname) 
00244     {
00245 
00246             return theSimulatorImplementation->getClassInfo( aClasstype, aClassname, 0 );
00247     }
00248 
00249     const libecs::PolymorphMap getClassInfo( libecs::StringCref aClasstype,
00250                                            libecs::StringCref aClassname, 
00251                                            const libecs::Integer forceReload ) 
00252     {
00253             return theSimulatorImplementation->getClassInfo( aClasstype, aClassname, forceReload );
00254     }
00255 
00256     
00257     /**
00258        @name Entity methods.
00259     */
00260 
00261     //@{
00262 
00263 
00264     /**
00265        Create a new Entity in the model.
00266 
00267        @param aClassname a classname of the Entity to create.
00268        @param aFullIDString FullID of the Entity.
00269        @param aName      a name of the Entity.
00270     */
00271 
00272     void createEntity( libecs::StringCref           aClassname, 
00273                        libecs::StringCref           aFullIDString )
00274     {
00275       theSimulatorImplementation->createEntity( aClassname,
00276                                                 aFullIDString );
00277     }
00278 
00279     /**
00280        Delete an Entity. This method is not supported yet.
00281 
00282     */
00283 
00284     void deleteEntity( libecs::StringCref aFullIDString )
00285     {
00286       theSimulatorImplementation->deleteEntity( aFullIDString );
00287     }
00288 
00289     /**
00290        Get a list of Entities in a System.
00291 
00292        @param anEntityTypeString an EntityType as a string
00293        @param aSystemPathString a SystemPath of the System.
00294        @return the list of IDs of Entities.
00295     */
00296 
00297     const libecs::Polymorph 
00298     getEntityList( libecs::StringCref anEntityTypeString,
00299                    libecs::StringCref aSystemPathString ) const
00300     {
00301       return theSimulatorImplementation->getEntityList( anEntityTypeString,
00302                                                         aSystemPathString );
00303     }
00304 
00305 
00306     /**
00307        List names of properties of an Entity. 
00308     
00309        @return a list of properties of an Entity.
00310     */
00311 
00312     const libecs::Polymorph 
00313     getEntityPropertyList( libecs::StringCref aFullIDString ) const
00314     {
00315       return theSimulatorImplementation->
00316         getEntityPropertyList( aFullIDString );
00317     }
00318 
00319     /**
00320        Check if an Entity object specified by a FullID exists in the model.
00321 
00322        @param aFullIDString a FullID string to be checked.
00323        @return true if the Entity exists, false if not.
00324     */
00325 
00326     const bool isEntityExist( libecs::StringCref         aFullIDString ) const
00327     {
00328       return theSimulatorImplementation->isEntityExist( aFullIDString );
00329     }
00330 
00331     /**
00332        Set a property value of an Entity.
00333 
00334        @param aFullPNString a FullPN of the Property to set.
00335        @param aValue        the value to be set.
00336     */
00337 
00338     void setEntityProperty( libecs::StringCref      aFullPNString,
00339                             libecs::PolymorphCref   aValue )
00340     {
00341       theSimulatorImplementation->setEntityProperty( aFullPNString,
00342                                                      aValue );
00343     }
00344 
00345     /**
00346        Get a value of a property from an Entity.
00347 
00348        @param aFullPNString a FullPN of the property.
00349        @return the property value.
00350     */
00351 
00352     const libecs::Polymorph
00353     getEntityProperty( libecs::StringCref aFullPNString ) const
00354     {
00355       return theSimulatorImplementation->getEntityProperty( aFullPNString );
00356     }
00357 
00358 
00359     /**
00360        Load a property value of an Entity.
00361 
00362        @param aFullPNString a FullPN of the Property to set.
00363        @param aValue        the value to be set.
00364     */
00365 
00366     void loadEntityProperty( libecs::StringCref      aFullPNString,
00367                              libecs::PolymorphCref   aValue )
00368     {
00369       theSimulatorImplementation->loadEntityProperty( aFullPNString,
00370                                                       aValue );
00371     }
00372 
00373     /**
00374        Save a value of a property from an Entity.
00375 
00376        @param aFullPNString a FullPN of the property.
00377        @return the property value.
00378     */
00379 
00380     const libecs::Polymorph
00381     saveEntityProperty( libecs::StringCref aFullPNString ) const
00382     {
00383       return theSimulatorImplementation->saveEntityProperty( aFullPNString );
00384     }
00385 
00386     /**
00387        Get attributes of a property of an Entity.
00388 
00389        The attributes are returned as a form of boolean 2-tuple 
00390        ( setable, getable ).  ( 1, 0 ) means that the property is setable but
00391        not getable,,, and so on.
00392 
00393        @return Entity property attributes.
00394     */
00395 
00396     const libecs::Polymorph
00397     getEntityPropertyAttributes( libecs::StringCref aFullPNString ) const
00398     {
00399       return theSimulatorImplementation->
00400         getEntityPropertyAttributes( aFullPNString );
00401     }
00402 
00403     /**
00404        Get class name of an Entity.
00405 
00406        @param aFullIDString a FullID of the Entity.
00407        @return the class name.
00408     */
00409 
00410     const libecs::String
00411     getEntityClassName( libecs::StringCref aFullIDString ) const
00412     {
00413       return theSimulatorImplementation->getEntityClassName( aFullIDString );
00414     }
00415 
00416 
00417     //@}
00418 
00419 
00420 
00421     /**
00422        @name Logger methods.
00423     */
00424 
00425     //@{
00426 
00427 
00428     /**
00429        Create a Logger.
00430 
00431        If the Logger already exists, this method does nothing.
00432 
00433        @param aFullPNString a FullPN of the PropertySlot which the Logger is
00434        observing, as a String 
00435 
00436        @return a borrowed pointer to the Logger
00437     */
00438 
00439     void createLogger( libecs::StringCref aFullPNString ) 
00440     {
00441                 
00442       return theSimulatorImplementation->createLogger( aFullPNString );
00443     }
00444 
00445     /**
00446        Create a Logger with parameters.
00447                 First parameter - minimum log interval dimension 0 - none, 1 - by step, 2 - by time
00448                 Second parameter - behaviour when run out of disk - 0 - throw exception, 1 - overwrite data
00449                 Third parameter - minimum log interval
00450 
00451        If the Logger already exists, this method does nothing.
00452 
00453        @param aFullPNString a FullPN of the PropertySlot which the Logger is
00454        observing, as a String 
00455 
00456        @return a borrowed pointer to the Logger
00457     */
00458 
00459     void createLogger( libecs::StringCref aFullPNString, libecs::Polymorph aParamList ) 
00460     {
00461         
00462       return theSimulatorImplementation->createLogger( aFullPNString, aParamList );
00463     }
00464 
00465     /**
00466        List Loggers in the simulator.
00467 
00468        @return a list of Loggers.
00469     */
00470 
00471     const libecs::Polymorph getLoggerList() const
00472     {
00473       return theSimulatorImplementation->getLoggerList();
00474     }
00475 
00476     const libecs::DataPointVectorSharedPtr 
00477     getLoggerData( libecs::StringCref aFullPNString ) const
00478     {
00479       return theSimulatorImplementation->getLoggerData( aFullPNString );
00480     }
00481 
00482     const libecs::DataPointVectorSharedPtr
00483     getLoggerData( libecs::StringCref aFullPNString, 
00484                    libecs::RealCref aStartTime, 
00485                    libecs::RealCref anEndTime ) const 
00486     {
00487       return theSimulatorImplementation->
00488         getLoggerData( aFullPNString, aStartTime, anEndTime );
00489     }
00490 
00491     const libecs::DataPointVectorSharedPtr
00492     getLoggerData( libecs::StringCref aFullPNString,
00493                    libecs::RealCref aStartTime, libecs::RealCref anEndTime,
00494                    libecs::RealCref anInterval ) const
00495     {
00496       return theSimulatorImplementation->getLoggerData( aFullPNString,
00497                                                         aStartTime, anEndTime, 
00498                                                         anInterval );
00499     }
00500 
00501     const libecs::Real 
00502     getLoggerStartTime( libecs::StringCref aFullPNString ) const 
00503     {
00504       return theSimulatorImplementation->getLoggerStartTime( aFullPNString );
00505     }
00506 
00507     const libecs::Real 
00508     getLoggerEndTime( libecs::StringCref aFullPNString ) const
00509     {
00510       return theSimulatorImplementation->getLoggerEndTime( aFullPNString );
00511     }
00512 
00513     void setLoggerMinimumInterval( libecs::StringCref aFullPNString, 
00514                                    libecs::RealCref anInterval )
00515     {
00516       return theSimulatorImplementation->
00517         setLoggerMinimumInterval( aFullPNString, anInterval );
00518     }
00519 
00520     const libecs::Real 
00521     getLoggerMinimumInterval( libecs::StringCref aFullPNString ) const
00522     {
00523       return theSimulatorImplementation->
00524         getLoggerMinimumInterval( aFullPNString );
00525     }
00526 
00527     void setLoggerPolicy( libecs::StringCref aFullPNString, 
00528                                    libecs::Polymorph aParamList )
00529     {
00530       return theSimulatorImplementation->setLoggerPolicy( aFullPNString, aParamList );
00531     }
00532 
00533     libecs::Polymorph
00534     getLoggerPolicy( libecs::StringCref aFullPNString ) const
00535     {
00536       return theSimulatorImplementation->getLoggerPolicy( aFullPNString );
00537     }
00538 
00539     const libecs::Integer getLoggerSize( libecs::StringCref aFullPNString ) const
00540     {
00541       return theSimulatorImplementation->getLoggerSize( aFullPNString );
00542     }
00543 
00544     //@}
00545 
00546 
00547 
00548     /**
00549        @name Simulator methods.
00550     */
00551 
00552     //@{
00553 
00554     /**
00555        Conduct a step of the simulation.
00556 
00557     */
00558 
00559     void step( const libecs::Integer aNumSteps = 1 )
00560     {
00561 
00562       theSimulatorImplementation->step( aNumSteps );
00563     }
00564 
00565     const libecs::Polymorph getNextEvent() const
00566     {
00567       return theSimulatorImplementation->getNextEvent();
00568     }
00569 
00570     /**
00571        Get current time of the simulator.
00572 
00573        @return current time of the simulator
00574     */
00575 
00576     const libecs::Real getCurrentTime() const
00577     {
00578       return theSimulatorImplementation->getCurrentTime();
00579     }
00580 
00581     /**
00582        Run the simulation.
00583 
00584        @note Both the EventChecker and the EventHandler must be set 
00585        before calling this method.
00586 
00587        @see setEventChecker
00588        @see setEventHandler
00589     */
00590 
00591     void run()
00592     {
00593       theSimulatorImplementation->run();
00594     }
00595 
00596     /**
00597        Run the simulation with a duration.
00598 
00599        @param a duration of the simulation run.
00600     */
00601 
00602     void run( const libecs::Real aDuration )
00603     {
00604       theSimulatorImplementation->run( aDuration );
00605     }
00606 
00607     /**
00608        Stop the simulation.
00609 
00610        Usually this is called from the EventHandler.
00611     */
00612 
00613     void stop()
00614     {
00615       theSimulatorImplementation->stop();
00616     }
00617 
00618     /**
00619        Set a pending event checker.
00620 
00621        The event checker must be a subclass of EventChecker class.
00622 
00623        This is usually used to set to form a mainloop of GUI toolkit.
00624        If you are using gtk, the event checker would call gtk_events_pending()
00625        function.
00626 
00627        While the simulation is running by the run() method, the function
00628        object given by this method is called once in several simulation 
00629        steps.  If it returns true, the EventHandler given by setEventHandler()
00630        method is called.
00631 
00632        @param aEventChecker a function object of the event checker
00633        @see EventChecker
00634        @see setEventHandler
00635     */
00636 
00637     void setEventChecker( EventCheckerSharedPtr aEventChecker )
00638     {
00639        theSimulatorImplementation->setEventChecker( aEventChecker );
00640     }
00641 
00642     /**
00643        Set an event handler.
00644 
00645        The event handler must be a subclass of EventHandler class.
00646 
00647        If you are using gtk, it would call gtk_main_iteration() function.
00648 
00649        @param anEventHandler a function object of the event handler
00650        @see EventHandler
00651        @see setEventChecker
00652     */
00653 
00654     void setEventHandler( EventHandlerSharedPtrCref anEventHandler )
00655     {
00656        theSimulatorImplementation->setEventHandler( anEventHandler );
00657     }
00658 
00659     const libecs::Polymorph getDMInfo()
00660     {
00661       return theSimulatorImplementation->getDMInfo();
00662     }
00663 
00664   //@}
00665 
00666   private:
00667 
00668     SimulatorImplementation* theSimulatorImplementation;
00669 
00670   };
00671 
00672 
00673 
00674 
00675   /** @} */ //end of libemc_module 
00676 
00677 } // namespace libemc
00678 
00679 #endif   /* __SIMULATOR_HPP */
00680 
00681 
00682 
00683 
00684 

Generated on Fri Aug 31 18:42:39 2007 for E-CELL C++ libraries (libecs and libemc) 3.1.105 by  doxygen 1.5.3