FAQ

General questions:
==================

Q: What does "Geneva" stand for ?
A: Geneva stands for "Grid-enabled evolutionary algorithms". The library will ultimately
   implement a multitude of different optimization algorithms. However, as evolutionary
   algorithms were the first to be implemented, and as Geneva started life in conjunction
   with Grid computing and particle physics, which in turn are closely related to CERN in
   Geneva/Switzerland, the name still seems to be appropriate.

Q: There is the "Geneva library collection" and the "Geneva optimization library". What
   does that mean ?
A: When Geneva was first developed, a lot of functionality was needed that may be used
   in a wider context than "just" optimization. Hence we have split off several general
   purpose libraries. The whole of the library collection still carries the name "Geneva",
   as does the special purpose optimization library.

Q: Which sub-libraries exist in the Geneva library collection ?
A: - The COMMON library holds miscellaneous functionality needed in many contexts. This
   includes the creation and parsing of configuration files, visualization of results,
   logging and exception handling as well as some additional code for unit tests.
   - The COURTIER library holds a broker infrastructure with pluggable execution modules.
   E.g., networked execution of optimizations is based on the courtier library
   - The GENEVA library holds all code specific to parametric optimization
   - The GENEVA-INDIVIDUALS library holds some sample implementations of optimization
   problems (i.e. definition of parameters and their evaluation). See e.g. the GFunctionIndividual
   class. There are also some implementations that can be used in a wider context (e.g.
   neural networks and the execution of external evaluation code)
   - The HAP library holds code for the creation of random numbers. This is based on a
   random number factory running in the background, as well as random number proxies giving
   consumers the impression that they are dealing with local random number generators.

Q: Where do I find the documentation ?
A: There is a complete manual available in PDF format here:
   http://www.gemfony.eu/fileadmin/documentation/geneva-manual.pdf . Note that
   it might be lacking behind the development of the Geneva library. Hence it
   is also recommended to look at the examples shipped with the Geneva sources.
   These are also a good starting point for creating your own solutions.

Q: Which platforms does Geneva run on ?
A: Geneva is mainly being developed on Linux (particularly the Debian and Ubuntu brands,
   with tests also happening on CentOS and BSD, the latter with CLang). We have also
   succeeded to compile the Geneva/Boost 1.54 combo on MacOS X 10.8.4. Note, though, that
   support for MacOS is experimental at best. We would love to hear from you if you have
   ported Geneva to another platform (particularly Microsoft Windows with Visual Studio).

Q: Are there bugs ?
A: Yes.

Q: Ummmh -- so if there are bugs, why don't you fix them ?
A: We have done our best to check the Geneva library for all kinds of possible problems.
   Particularly, there is a comprehensive unit test framework for the core
   libraries. So the actual number of bugs should be quite low. However, we cannot test
   Geneva under all possible circumstances. This is where, in the best tradition of Open
   Source software, we rely on YOU to report the problems you have encountered. Also note
   that there may be known bugs that we are currently working on, that we currently consider
   to have such a low priority that we have chosen to work on other parts of Geneva first,
   or which are simply impossible to fix, as they are related to problems of a particular
   execution environment.

Q: Where to report bugs and warnings ?
A: https://bugs.launchpad.net/geneva

Q: What kind of reports should be sent to the bug tracker ?
A: General bugs (i.e. every situation, where Geneva does not behave as expected or
   where an exception is thrown). Please also let us know about any warning you encounter
   during the compilation process or when running Geneva. We do need to know the exact
   execution environment in this case.

Q: Where to post general questions about the Geneva usage or development ?
A: Please use the Geneva Usage or Development Forums:
   http://www.gemfony.eu/index.php?forums . Please also post feature requests
   here and let us know about errors or inaccuracies in the manual.

Q: How can I help ?
A: As in any other Open Source project, there are many options how you may help.
   The simplest way is to just report any problem you encounter through our bug tracker,
   and let us know about your experience or post feature requests to our forum. You
   could also do some stress testing of the library or port it to a new platform. In case
   you actually know a solution to a given problem, we would very much appreciate if
   you would let us know. The same applies to the implementation of new features.

Q: What happens to my contributions ?
A: Your contributions should be performed via a pull request, and will they will be
   reviewed by other project developers prior to be accepted into the source tree.
   Please see the manual for further details.


Technical questions:
====================

Q: Why do member functions of Geneva classes do not carry the "throw(...)" specifier ?
A: In former releases, throw() specifiers were used to list the exceptions a function
   could throw. A rationale for the decision to remove these specifiers can be found
   here: http://www.gotw.ca/publications/mill22.htm .

Q: When I run one of the examples in networked mode (either on the local box or over a LAN/WAN),
   the optimization stops reproducibly after a few hundred iterations. Is this a bug ?
A: The Geneva library assumes that evaluation functions run for a (possibly very) long time.
   Consequently clients disconnect from the server as soon as they have received a work item,
   and reconnect, once they have finished the calculation. The examples shipped with the
   library, in turn, mostly implement evaluation functions that run for a few milliseconds.
   This means that a lot of connections are opened and closed in a very short time. You might
   then quickly run out of ports, whose number is limited on Linux (you can find this out with
   the command "cat /proc/sys/net/ipv4/ip_local_port_range"). One remedy is explained here:
   http://www.speedguide.net/read_articles.php?id=121 (search for TCP_TW_REUSE). The command
   suggested there is "echo 1 > /proc/sys/net/ipv4/tcp_tw_reuse". NOTE THAT YOU NEED TO
   CAREFULLY EVALUATE THE EFFECTS OF SETTING THIS VARIABLE ON YOUR SYSTEM. See also a
   related 2007 discussion on the Boost.Asio Usenet forum (quoted e.g. here:
   http://osdir.com/ml/lib.boost.asio.user/2007-06/msg00101.html). *** The situation
   is actually very similar to a web server with a high volume of requests, and you will
   experience similar problems *** There are many more tuning options in the Linux kernel for
   you to play with. Google will give you further information (search e.g. for "Apache tuning"
   and possibly sysctl.conf -- there are examples of configuration files only which help
   you to tune the server system).

Q: Which CPP macro variables are used at build time and can be defined by the user ?
A: The following variables are available for deeper control of some aspects of the code
   at compile time:

     GEM_COMMON_PRINT_COMMANDLINE
        Enables the printing of the command line for debugging purposes when executing
        external commands (--> GExternalEvaluatorIndividual)

     GEM_TESTING
        Set by the Geneva build system for enabling the testing code

     GENEVA_VERSION
        Set by the Geneva build system with the full Geneva version string