Evolife documentation

     summary     

    

******************************************************************************************
Module Evolife.Ecology.Observer:        
===============================
EVOLIFE: Module Observer:
    Gets data from various modules and stores them for display and statistics
    
        Generic_Observer --> interface between simulation and window system
        Experiment_Observer --> idem + headers to store curves
    
        Storage --> stores vectors
        Examiner --> different Storages, one per slot
        Meta_Examiner --> stores similar Examiners with sames slots + statistics
    
        Observer --> Meta_Examiner + Experiment_Observer
        EvolifeObserver --> specific observer (knows about genomes, phenomes, ...)
******************************************************************************************


    **************************************************************************************
    Class Curve:        
    ===========
    Legend of a curve (color, text)
        for Experiment_Observer
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Curve.__init__        
        ----------------------------------------------------------------------------------
        Arguments:
            . Name
            . Color
            . Legend


    **************************************************************************************
    Class Curves:        
    ============
    Legend of a curves
        for Experiment_Observer
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Curves.__init__:        
        ======================
        merely calls reset
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Curves.reset:        
        ===================
        Defines Curves and their current Values
            Stores curves’ designation and legend
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Curves.append:        
        ====================
        Creates a new (local) curve and stores it
        ----------------------------------------------------------------------------------
        Arguments:
            . Name
            . Color
            . Legend


        ----------------------------------------------------------------------------------
        Method Curves.Color:        
        ===================
        returns the color of a curve
        ----------------------------------------------------------------------------------
        Arguments:
            . Name


        ----------------------------------------------------------------------------------
        Method Curves.Value:        
        ===================
        sets or returns a curve’s current value
        ----------------------------------------------------------------------------------
        Arguments:
            . Name
            . Value


        ----------------------------------------------------------------------------------
        Method Curves.legend:        
        ====================
        return legends
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Curves.CurveNames:        
        ========================
        returns curves’ designations
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Curves.Orders:        
        ====================
        Returns current curves’ values (at time x)
        ----------------------------------------------------------------------------------
        Arguments:
            . x


    **************************************************************************************
    Class Storage:        
    =============
    Kind of matrix. Stores raw data, typically vectors of integers
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Storage.__init__:        
        =======================
        calls reset
        ----------------------------------------------------------------------------------
        Arguments:
            . Name


        ----------------------------------------------------------------------------------
        Method Storage.reset:        
        ====================
        initializes the ‘storage’, ‘average’ and ‘best’ lists
        ----------------------------------------------------------------------------------
        Arguments:
            . length


        ----------------------------------------------------------------------------------
        Method Storage.open_:        
        ====================
        marks the storage as ‘open’
        ----------------------------------------------------------------------------------
        Arguments:
            . length


        ----------------------------------------------------------------------------------
        Method Storage.store:        
        ====================
        stores a vecor in the storage
        ----------------------------------------------------------------------------------
        Arguments:
            . vector


        ----------------------------------------------------------------------------------
        Method Storage.statistics:        
        =========================
        to be overloaded
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Storage.close_:        
        =====================
        sets the storage as ‘closed’
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Storage.get_data:        
        =======================
        returns a tuple of all the vectors in the storage
        ----------------------------------------------------------------------------------


    **************************************************************************************
    Class NumericStorage:        inherits from Evolife.Ecology.Observer.Storage
    ====================
    Storage + basic statistics
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method NumericStorage.statistics:        
        ================================
        computes best and average
        ----------------------------------------------------------------------------------


    **************************************************************************************
    Class Examiner:        
    ==============
    Groups several storages in different slots with different names.
        Use by calling in sequence:
        reset()
        open_(size)        size = number of slots
        store(Slotname, Value, Numeric)    any time  
        close_()    --> this performs statistics for each numeric slot
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Examiner.__init__:        
        ========================
        initializes a dict of storages
        ----------------------------------------------------------------------------------
        Arguments:
            . Name


        ----------------------------------------------------------------------------------
        Method Examiner.reset:        
        =====================
        resets all storages
        ----------------------------------------------------------------------------------
        Arguments:
            . length


        ----------------------------------------------------------------------------------
        Method Examiner.open_:        
        =====================
        opens all storages
        ----------------------------------------------------------------------------------
        Arguments:
            . length


        ----------------------------------------------------------------------------------
        Method Examiner.store:        
        =====================
        stores a data vector into a slot named StorageName
        ----------------------------------------------------------------------------------
        Arguments:
            . StorageName
            . vector
            . Numeric


        ----------------------------------------------------------------------------------
        Method Examiner.statistics:        
        ==========================
        performs statistics in all individual storages
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Examiner.close_:        
        ======================
        closes all storages
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Examiner.display:        
        =======================
        displays all storages as text, one per line
        ----------------------------------------------------------------------------------
        Arguments:
            . StorageName


        ----------------------------------------------------------------------------------
        Method Examiner.get_data:        
        ========================
        retrieves a data vector from slot named StorageName
        ----------------------------------------------------------------------------------
        Arguments:
            . StorageName


    **************************************************************************************
    Class Meta_Examiner:        inherits from Evolife.Ecology.Observer.Storage
    ===================
    Meta storage: stores several lower-level examiners
        having same slots and performs weighted statistics for each slot
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Meta_Examiner.__init__:        
        =============================
        Defines a storage that will contain various examiners (which are dicts of storages)
            All examiners are supposed to have the same slots (low-level storages)
        ----------------------------------------------------------------------------------
        Arguments:
            . Name


        ----------------------------------------------------------------------------------
        Method Meta_Examiner.statistics:        
        ===============================
        gathers data from the stored examiners
            and stores them as a dictionary of tuples (a tuple per slot)
            (number_of_instances, best_of_each_coordinate,
             average_of_each_coordinate, list_of_instances)
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Meta_Examiner.get_data:        
        =============================
        Performs statistics on storage ‘Slot’
        ----------------------------------------------------------------------------------
        Arguments:
            . Slot


    **************************************************************************************
    Class Generic_Observer:        
    ======================
    Minimal observer
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Generic_Observer.__init__:        
        ================================
        initializes ScenarioName, EvolifeMainDir, CurveNames, Title, Field_grid and Trajectory_grid
        ----------------------------------------------------------------------------------
        Arguments:
            . ObsName
            . TimeLimit


        ----------------------------------------------------------------------------------
        Method Generic_Observer.DisplayPeriod:        
        =====================================
        sets or retrieves display period
        ----------------------------------------------------------------------------------
        Arguments:
            . Per


        ----------------------------------------------------------------------------------
        Method Generic_Observer.season:        
        ==============================
        increments StepId
        ----------------------------------------------------------------------------------
        Arguments:
            . year


        ----------------------------------------------------------------------------------
        Method Generic_Observer.Visible:        
        ===============================
        decides whether the situation should be displayed
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.Over:        
        ============================
        Checks whether time limit has been reached
            and has not been manually bypassed
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.setOutputDir:        
        ====================================
        set output directory ('___Results’ by default)
        ----------------------------------------------------------------------------------
        Arguments:
            . ResultDir


        ----------------------------------------------------------------------------------
        Method Generic_Observer.recordInfo:        
        ==================================
        stores Value in Slot
        ----------------------------------------------------------------------------------
        Arguments:
            . Slot
            . Value


        ----------------------------------------------------------------------------------
        Method Generic_Observer.get_info:        
        ================================
        returns factual information previously stored in Slot
            returns ‘default’ (which is None by default) if Slot is not found
        ----------------------------------------------------------------------------------
        Arguments:
            . Slot
            . default
            . erase


        ----------------------------------------------------------------------------------
        Method Generic_Observer.inform:        
        ==============================
        Info is sent by the simulation -
            Typically a single char, corresponding to a key pressed
            Useful to customize action
        ----------------------------------------------------------------------------------
        Arguments:
            . Info


        ----------------------------------------------------------------------------------
        Method Generic_Observer.ResultHeader:        
        ====================================
        Parameter names are stored with the date in the result file header
            Header is just the string "Date" by default
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.record:        
        ==============================
        stores current position changes into the Window’s buffer ('Field’ by default, could be ‘Trajectories')
            ‘Position’ can also be the string "erase"
        ----------------------------------------------------------------------------------
        Arguments:
            . Position
            . Window
            . Reset


        ----------------------------------------------------------------------------------
        Method Generic_Observer.Field_grid:        
        ==================================
        returns initial drawing for ‘Field’
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.Trajectory_grid:        
        =======================================
        returns initial drawing for ‘Trajectories’
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.get_data:        
        ================================
        Retrieves data from Slot.
            Erases Slot’s content if Consumption is True
        ----------------------------------------------------------------------------------
        Arguments:
            . Slot
            . Consumption


        ----------------------------------------------------------------------------------
        Method Generic_Observer.displayed:        
        =================================
        Remembers that display occurred (to ensure that it answers once a year)
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.TextErase:        
        =================================
        Erases the text buffer
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.TextDisplay:        
        ===================================
        stores a string that will be displayed at appropriate time.
            Text is currently printed on the console (to be changed)
        ----------------------------------------------------------------------------------
        Arguments:
            . Str


        ----------------------------------------------------------------------------------
        Method Generic_Observer.curve:        
        =============================
        creates or retrieves a curve or return curve’s current value.
            If Name is None: resets all curves.
        ----------------------------------------------------------------------------------
        Arguments:
            . Name
            . Value
            . Color
            . Legend


        ----------------------------------------------------------------------------------
        Method Generic_Observer.legend:        
        ==============================
        returns curves’ legends
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.CurveNames:        
        ==================================
        returns curves’ names
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Generic_Observer.GetPlotOrders:        
        =====================================
        Returns current curves’ values if observer in visible state
        ----------------------------------------------------------------------------------


    **************************************************************************************
    Class Experiment_Observer:        inherits from Evolife.Ecology.Observer.Generic_Observer
    =========================
    Typical observer for an experiment with parameters
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Experiment_Observer.__init__:        
        ===================================
        Initializes ScenarioName, EvolifeMainDir, CurveNames, Title, Field_grid and Trajectory_grid
            Sets DisplayPeriod, TimeLimit, Icon, ... from values taken from ParameterSet
            ExperienceID is set to current date
            Sets ResultFile (appends ExperienceID in batch mode)
        ----------------------------------------------------------------------------------
        Arguments:
            . ParameterSet


        ----------------------------------------------------------------------------------
        Method Experiment_Observer.ResultHeader:        
        =======================================
        Relevant parameter names are stored into the result file header, juste after the string "Date"
            Parameter values are added just below the header
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method Experiment_Observer.get_info:        
        ===================================
        returns factual information previously stored in Slot.
            default value is None by default
        ----------------------------------------------------------------------------------
        Arguments:
            . Slot
            . default


    **************************************************************************************
    Class Observer:        inherits from Evolife.Ecology.Observer.Meta_Examiner, Evolife.Ecology.Observer.Experiment_Observer
    ==============
    Contains instantaneous data updated from the simulation
        for statistics and display
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method Observer.__init__:        
        ========================
        calls Experiment_Observer constructor if Scenario is not None, Generic_Observer otherwise
            calls Meta_Examiner constructor
        ----------------------------------------------------------------------------------
        Arguments:
            . Scenario


        ----------------------------------------------------------------------------------
        Method Observer.get_data:        
        ========================
        Retrieves data stored in Slot from Experiment_Observer (or, if None, from Meta_Examiner)
        ----------------------------------------------------------------------------------
        Arguments:
            . Slot
            . Consumption


    **************************************************************************************
    Class EvolifeObserver:        inherits from Evolife.Ecology.Observer.Observer
    =====================
    Evolife-aware observer based on the use of a scenario.
        Retrieves curves’ names and legends, and satellite window names, legends and wallpapers
        as provided by scenario
        Contains instantaneous data updated from the simulation
        for statistics and display
    **************************************************************************************

        ----------------------------------------------------------------------------------
        Method EvolifeObserver.__init__        
        ----------------------------------------------------------------------------------
        Arguments:
            . Scenario


        ----------------------------------------------------------------------------------
        Method EvolifeObserver.GetPlotOrders:        
        ====================================
        Gets the curves to be displayed from the scenario and
            returns intantaneous values to be displayed on these curves
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method EvolifeObserver.get_info:        
        ===============================
        returns factual information previously stored in Slot
        ----------------------------------------------------------------------------------
        Arguments:
            . Slot
            . default


        ----------------------------------------------------------------------------------
        Method EvolifeObserver.TextDisplay:        
        ==================================
        stores a string that will be displayed at appropriate time
        ----------------------------------------------------------------------------------
        Arguments:
            . Str


        ----------------------------------------------------------------------------------
        Method EvolifeObserver.Field_grid:        
        =================================
        returns initial drawing for ‘Field’
        ----------------------------------------------------------------------------------


        ----------------------------------------------------------------------------------
        Method EvolifeObserver.Trajectory_grid:        
        ======================================
        returns initial drawing for ‘Trajectories’
        ----------------------------------------------------------------------------------


    

    

    Back to Evolife