Metadata-Version: 1.1
Name: PGAPy
Version: 0.3
Summary: Python wrapper for pgapack, the parallel genetic algorithm library
Home-page: http://pgapy.sourceforge.net/
Author: Ralf Schlatterbeck
Author-email: rsc@runtux.com
License: UNKNOWN
Description: 
        .. |--| unicode:: U+2014   .. em dash
        
        :Author: Ralf Schlatterbeck <rsc@runtux.com>
        
        PGAPy is a wrapper for pgapack, the parallel genetic algorithm library
        (see `pgapack Readme`_), a powerfull genetic algorithm library by
        D. Levine, Mathematics and Computer Science Division Argonne National
        Laboratory. The library is written in C. PGAPy wraps this library for
        use with Python. The original pgapack library is already quite old but
        is one of the most complete and accurate (and fast, although this is not
        my major concern when wrapping it to python) genetic algorithm
        implementations out there with a lot of bells and whistles for
        experimentation. It also has shown a remarkably small number of bugs
        over the years. It supports parallel execution via the message
        passing interface MPI_ in addition to a normal "serial" version. That's
        why I wanted to use it in Python, too.
        
        There currently is not much documentation for PGAPy.
        You really, absolutely need to read the documentation that comes
        with pgapack |--| and of course you need the pgapack library.
        
        The original pgapack library can still be downloaded from the pgapack_
        ftp site, it is written in ANSI C and therefore *should* run on most
        platforms. Note that this version is not very actively maintained. I've
        started a `pgapack fork on github`_ where I've ported the library to the
        latest version of the MPI_ standard and have fixed some minor
        inconsistencies in the documentation.
        
        I have tested pgapy on Linux only and I'll currently not provide Windows
        versions.  You also can find my `pgapack fork on github`_ this
        repository has the three upstream releases as versions in git and
        contains some updates concerning support of newer MPI_ versions and
        documentation updates.  I've also included patches in the git repository
        of the Debian maintainer of the package, Dirk Eddelbuettel.
        
        .. _`pgapack Readme`: http://ftp.mcs.anl.gov/pub/pgapack/README
        .. _pgapack:          http://ftp.mcs.anl.gov/pub/pgapack/
        .. _`pgapack fork on github`: https://github.com/schlatterbeck/pgapack
        .. _MPI: http://mpi-forum.org/
        
        For the Debian Linux distribution, pgapack is included in oldstable
        (jessie), you can still install this in the current stable release
        (stretch). This version does not yet include the fixes for newer MPI_
        versions and documentation updates.
        
        For debian the pre-built documentation is in
        ``/usr/share/doc/pgapack/user_guide.ps.gz``
        
        To get you started, I've included some very simple examples in
        ``examples``, e.g., ``one-max.py`` implements the "Maxbit" example
        similar to one in the pgapack documentation. The examples were inspired
        by the book "Genetic Algorithms in Python" but are written from scratch
        and don't include any code from the book. The examples illustrates
        several points:
        
         - Your class implementing the genetic algorithm needs to inherit from
           pga.PGA (pga is the PGAPy wrapper module).
         - You need to define an evaluation function called ``evaluate`` that
           returns a number indicating the fitness of the gene given with the
           parameters ``p`` and ``pop`` that can be used to fetch allele values from
           the gene using the ``get_allele`` method, for more details refer to the
           pgapack documentation.
         - You *can* define additional functions overriding built-in functions
           of the pgapack library, illustrated by the example of
           ``print_string``.  Note that we could call the original print_string
           method of our PGA superclass.  In the same way you can implement,
           e.g., your own crossover method.
         - The constructor of the class needs to define the Gene type, in the
           examples we use int and bool built-in datatypes.
         - The length of the gene needs to be given in the constructor.
         - We often want to maximize the numbers returned by our evaluation
           function, set the parameter ``maximize`` to False if you want to
           minimize.
         - We can define an array of init values, each entry containing a sequence
           with lower and upper bound. The array has to have the length of the
           gene. Note that the upper bound is *included* in the range of
           possible values (unlike the python range operator but compatible with
           the pgapack definition).
         - In the constructor of the class we can add parameters of the genetic
           algorithm. Not all parameters of pgapack are wrapped yet, currently
           you would need to consult the sourcecode of PGAPy to find out which
           parameters are wrapped. In the example we define several print
           options.
         - Finally the genetic algorithm is started with the ``run`` method.
        
        Naming conventions in PGAPy
        ---------------------------
        
        When you extend PGAPy |--| remember not all functions of pgapack are
        wrapped yet and you may need additional functions |--| you should stick to
        my naming conventions when making changes.
        The following naming conventions were used for the wrapper:
        
         - Constants of pgapack like ``PGA_REPORT_STRING`` are used as-is in
           uppercase. These constants can be directly imported from the wrapper
           module. Not all constants are wrapped so far, if you need more, add
           them to the constdef array in pgamodule.c and send_ me a patch.
         - For methods of the pga.PGA class I've removed the ``PGA`` prefix used
           throughout pgapack and converted the method to lowercase with
           underscores between uppercase words in the original function name, so
           ``PGARun`` becomes ``run``, ``PGACheckStoppingConditions`` becomes
           ``check_stopping_conditions``.
         - Where possible I've made a single class method where pgapack needs a
           separate function for each datatype, so ``PGAGetBinaryAllele``,
           ``PGAGetCharacterAllele``, ``PGAGetIntegerAllele``, ``PGAGetRealAllele`` all
           become ``get_allele``. Same holds true for ``set_allele``.
         - Internal method names in the wrapper program have a leading PGA\_ |--| so
           the class method ``set_allele`` is implemented by the C-function
           ``PGA_set_allele`` in ``pgamodule.c``.
        
        Missing Features
        ----------------
        As already mentioned, not all functions and constants of pgapack are
        wrapped yet |--| still for many applications the given set should be
        enough. If you need additional functions, you may want to wrap these and
        send_ me a patch.
        
        Another feature of pgapack is currently not implemented in the wrapper,
        the usage of custom datatypes. With pgapack you can define your own
        datatypes complete with their custom implementations of the genetic
        algorithm functionality like crossover, mutation, etc. I don't expect
        problems implementing these, though.
        
        Reporting Bugs
        --------------
        Please use the `Sourceforge Bug Tracker`_  or the `Github Bug Tracker`_ and
        
         - give a short description of what you think is the correct behaviour
         - give a description of the observed behaviour
         - tell me exactly what you did.
         - if you can publish your source code this makes it a lot easier to
           debug for me
        
        .. _`Sourceforge Bug Tracker`:
            http://sourceforge.net/tracker/?group_id=152022&atid=782852
        .. _`Github Bug Tracker`:
            https://github.com/schlatterbeck/pgapy/issues
        .. _send: mailto:rsc@runtux.com
        
        Resources
        ---------
        
        Project information and download from `Sourceforge main page`_
        
        .. _`Sourceforge main page`: http://sourceforge.net/projects/pgapy/
        
        or checkout from Github_
        
        .. _`Github`: http://github.com/schlatterbeck/pgapy
        
        or directly install via pypi.
        
        Changes
        -------
        
        Version 0.3: Feature enhancements, Bug fixes
        
        Port to Python3, Python2 is still supported, license change.
        
          - C-Code of wrapper updated to support both, Python2 and Python3
          - Update documentation
          - Fix some memory leaks that could result when errors occurred during
            some callback methods
          - License change: We now have the 2-clause BSD license (similar to the
            MPICH license of pgapack), this used to be LGPL.
        
        Version 0.2: Feature enhancements, Bug fixes
        
        64 bit support, more pgapack functions and attributes wrapped,
        Readme-update: Sourceforge logo, Changes chapter.
        
         - Bug-fixes for 64 bit architectures
         - More functions and attributes of pgapack wrapped
         - Add a build-rule to setup.py to allow building for standard-install
           of pgapack |--| this currently needs editing of setup.py |--| should use
           autodetect here but this would require that I set up a machine with
           standard install of pgapack for testing.
         - Add Sourceforge logo as required
         - Add Changes chapter for automagic releases
        
        Version 0.1: Initial freshmeat announcement
        
        PGAPy is a wrapper for pgapack, the parallel genetic algorithm library,
        a powerful genetic algorithm library. PGAPy wraps this library for use
        with Python. Pgapack is one of the most complete and accurate genetic
        algorithm implementations out there with a lot of features for
        experimentation.
        
         - Initial Release
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: C
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
