Non-Uniform CA Designer (C++, GAlib, Boost)

/*
 * Copyright (C) 2009 Kamil Dudka <xdudka00@stud.fit.vutbr.cz>
 *
 * This file is part of nucad (Non-Uniform CA Designer).
 *
 * nucad 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
 * any later version.
 *
 * nucad 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 nucad.  If not, see <http://www.gnu.org/licenses/>.
 */
 
/**
 * @file CaDesigner.h
 * Core class CaDesigner with its helpers and observers.
 */
 
#ifndef CA_DESIGNER_H
#define CA_DESIGNER_H
 
#include "Ca.h"
 
class GABinaryString;
class GAStatistics;
 
/**
 * @interface IObserver
 * @brief Simple observer's base class.
 * @note Design pattern @b observer.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class IObserver {
    public:
        virtual ~IObserver() { }
 
        /**
         * @brief Event notification, usually called by object implementing
         * ISubject interface.
         * @note Design pattern @b observer
         */
        virtual void notify() = 0;
};
 
/**
 * @interface ISubject
 * @brief Simple observer's subject base class.
 * @note Design pattern @b observer.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class ISubject {
    public:
        virtual ~ISubject() { }
 
        /**
         * @brief Add observer to list of listeners.
         * @param observer Observer object to add to list of listeners.
         * @note Observers are notified in the same order, as there are added to
         * lsit of listeners.
         * @note Design pattern @b observer
         */
        virtual void addObserver(IObserver *observer) = 0;
};
 
 
/**
 * @brief Simple subject's base class.
 * @note Design pattern @b observer.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class AbstractSubject: public ISubject {
    public:
        virtual ~AbstractSubject();
 
        // see ISubject dox
        virtual void addObserver(IObserver *);
    protected:
        AbstractSubject();
 
        /**
         * @brief Send notification to all observers (listeners).
         * @note Observers are notified in the same order, as there are added to
         * lsit of listeners.
         */
        void notify();
    private:
        struct Private;
        Private *d;
};
 
/**
 * @brief Base class of simple multi-step process.
 * @note Design pattern @b template @b method
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class AbstractProcess: public AbstractSubject {
    public:
        virtual ~AbstractProcess();
 
        /**
         * @brief Start process execution. This method returns control
         * after process ends (or after it is stopped by stop() or reset() method)
         */
        virtual void start();
 
        /**
         * @brief Stop currently executed process as soon as possible.
         */
        virtual void stop();
 
        /**
         * @brief Reset process to its initial state.
         * @note This implies stop() if process is running.
         */
        virtual void reset();
 
        /**
         * @brief Returns current step number.
         * @return Returns current step number.
         */
        virtual int getStepsCount();
 
    protected:
        AbstractProcess();
 
        /**
         * @brief Initialize process.
         * @note Design pattern @b template @b method
         */
        virtual void initialize() = 0;
 
        /**
         * @brief Do one step of process.
         * @note Design pattern @b template @b method
         */
        virtual void doStep() = 0;
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * @brief Multi-step process with time-watch extension.
 * @note Design pattern @b template @b method
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class AbstractProcessWatched: public AbstractProcess {
    public:
        virtual ~AbstractProcessWatched();
        virtual void start();
        virtual void stop();
        virtual void reset();
 
        /**
         * @brief Returns time elapsed by activity.
         * @return Returns time elapsed by activity.
         */
        virtual long getTimeElapsed();
 
    protected:
        AbstractProcessWatched();
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * ICaRules implementation which can be easily used by GAlib.
 * @attention This class does @b not adhere to the CA_CYCLIC_NEIGHBORHOOD
 * compile-time option. It might be subject to implement if we really need it.
 */
class GaCaRules: public ICaRules {
    public:
        /**
         * simple deserialization from string
         */
        GaCaRules(const std::string &);
 
        /**
         * Create ICaRules object from binary string (GAlib genome).
         * @param size CA's size in one @b direction.
         * @param bs GAlib binary string to initialize by.
         */
        GaCaRules(size_t size, const GABinaryString &bs);
        virtual ~GaCaRules();
        virtual GaCaRules* clone() const;
        virtual void getRuleAtPos(Pos, TRule5N &) const;
 
        /**
         * Return CA's size on @b one direction.
         */
        size_t size() const;
 
        /**
         * Return bit's value at given index.
         * @param index Index of bit to retrieve.
         */
        bool operator[] (unsigned index) const;
 
    protected:
        GaCaRules();
        GaCaRules(const GaCaRules &);
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * Simple serialization of GaCaRules object to string.
 * @param str Standard output stream to write to.
 * @param rules GaCaRules object ought to be serialized.
 */
std::ostream& operator<< (std::ostream &str, const GaCaRules &rules);
 
/**
 * Set container for GaCaRules objects (usually for solutions). This container
 * acts really as a set. It means each object's @b value can be stored only once
 * in this container.
 */
class GaCaRulesSet {
    public:
        GaCaRulesSet();
        ~GaCaRulesSet();
 
        /**
         * Return count of objects stored in the container
         */
        size_t size() const;
 
        /**
         * Add GaCaRules object to the container. The object is @b not added to
         * container if there is already object with the same value.
         * @attention Objects are deleted automatically by GaCaRulesSet in both
         * cases.
         * @param rules GaCaRules object ought to be added.
         */
        void add(GaCaRules *rules);
 
        //GaCaRulesVector* createVector();
 
        /**
         * Remove all bojects from container and @b destroy them.
         */
        void clear();
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * Non-uniform CA designer using GAlib library.
 * @note Design pattern @b simple @b factory
 * @note Mostly copy-pasted from FSS (Fast SAT Solver) project.
 */
class CaDesigner: public AbstractProcessWatched
{
    public:
        virtual ~CaDesigner();
 
        /**
         * Use this to create CaDesigner object instead of calling constructor
         * directly.
         * @param evaluator An instance of CaEvaluator object which has to be
         * valid until CaDesigner is destroeyd.
         */
        static CaDesigner* create(CaEvaluator *evaluator);
 
        /**
         * Return useful statistic data managed by GAStatistics class.
         */
        const GAStatistics& getStatistics() const;
 
        /**
         * Return total count of solutions alredy found by designer.
         */
        int getSolutionsCount();
 
        /**
         * Return current limit for count of generations.
         */
        int stopAtGeneration() const;
 
        float minFitness();
        float avgFitness();
        float maxFitness();
 
    protected:
        /**
         * Non-public constructor. Use static method create() instead.
         */
        CaDesigner (CaEvaluator *evaluator);
 
        virtual void initialize();
        virtual void doStep();
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * @brief Observer which stops process after specified time.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class TimedStop: public IObserver {
    public:
        /**
         * @param process Observed process.
         * @param msec Time in milliseconds to stop process after.
         */
        TimedStop(AbstractProcessWatched *process, long msec);
        virtual ~TimedStop();
        virtual void notify();
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * @brief Observer which write out progress percentage when it is changed.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class ProgressWatch: public IObserver {
    public:
        /**
         * @param process Observed process.
         * @param stepsTotal Count of steps corresponding to 100% of progress.
         * @param streamTo Standard output stream to write to.
         */
        ProgressWatch(
                AbstractProcess   *process,
                int               stepsTotal,
                std::ostream      &streamTo);
 
        virtual ~ProgressWatch();
        virtual void notify();
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * @brief Observer which stop solver after specified count of solutions is
 * found.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class SolutionsCountStop: public IObserver {
    public:
        /**
         * @param solver Observed solver.
         * @param minCountOfSolutions Count of solutions to stop solver after.
         */
        SolutionsCountStop(CaDesigner *solver, int minCountOfSolutions);
        virtual ~SolutionsCountStop();
        virtual void notify();
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * @brief Observer which write out message when maxFitness value is increased.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class FitnessWatch: public IObserver {
    public:
        /**
         * @param solver Observed solver.
         * @param streamTo Standard output stream to write to.
         */
        FitnessWatch(CaDesigner *solver, std::ostream &streamTo);
        virtual ~FitnessWatch();
        virtual void notify();
        void reset();
 
    private:
        struct Private;
        Private *d;
};
 
/**
 * @brief Observer which write out message when solution is found.
 * @note This code was copy-pasted from FSS (Fast SAT Solver) project.
 */
class ResultsWatch: public IObserver {
    public:
        /**
         * @param solver Observed solver.
         * @param streamTo Standard output stream to write to.
         */
        ResultsWatch(CaDesigner *solver, std::ostream &streamTo);
        virtual ~ResultsWatch();
        virtual void notify();
 
    private:
        struct Private;
        Private *d;
};
 
#endif // CA_DESIGNER_H