README

Quilë  is  a  C++20  header-only general  purpose  genetic  algorithms
library  with  no  external  dependencies  supporting   floating-point,
integer, binary and permutation  representations. It is released under
the terms of the MIT License (please see LICENSE file).

The name  of this library  origins from fictional  language Neo-Quenya
and means “color”.

This software strives to be minimal.

List of contents

  doc/          Documentation.
    examples/     Short examples of the library features use.

  examples/     Examples.
    benchmark/    Benchmark programs and benchmark results.
    common/       Common files.
    evenstar/     Crystal structure prediction of nanowires.
    example_1/    Floating-point representation example.
    example_2/    Permutation representation example.
    mithril/      Crystal structure prediction of nanotubes.

  logo/         Logo artwork.
  paper/        Paper to The Journal of Open Source Software.
  quile/        The Quilë library itself.
  tutorial/     Tutorial.

Installation

  The library  is header-only,  therefore  installation  on the user's
  system  is done  by  copying  the library  source code.   In case of
  GNU/Linux operating system  it can be achieved by invoking following
  command in terminal in some directory,  e.g. in  /home/${USER}/repos
  directory:

    git clone https://github.com/ttarkowski/quile.git

  Please see the tutorial for more details.

  The latest stable release is v1.0.0 available for download at:

    https://github.com/ttarkowski/quile/releases/tag/v1.0.0

  and described in following paper:

    Tomasz Tarkowski, Quilë: C++ genetic algorithms scientific library,
    Journal  of  Open  Source  Software,  8 (82),  4902  (2023).   doi:
    10.21105/joss.04902

List of dependencies

  The library  does not  depend  on any other software.  The user only
  need  C++  compiler  supporting  C++20 standard of  the language  to
  compile programs  written with use of  the library.  The software is
  known to work with both GCC and Clang compilers   (the  library  was
  tested on GCC 10.2.1 and Clang 13.0.1).

Compilation

  To compile programs written with use of the library,  please use the
  following command:

    g++ -std=c++20 -DNDEBUG -O3 -Wall -Wextra -pedantic \
      -I/home/${USER}/repos/quile/ -pthread your_program.cc

  or similar. Please see documentation and tutorial for more details.

Documentation

  Documentation for the library  can be generated from the source code
  with use of  the Doxygen  tool.  Please  see  the tutorial for  more
  details.

  Autogenerated  library  documentation  for  v1.0.0  is  available at
  https://doi.org/10.5281/zenodo.7603809 .

Tutorial

  If you need an easy introduction to the library, please see tutorial/
  tutorial.txt file.

Support

  If you need support, please visit:

    https://github.com/ttarkowski/quile/discussions

  and ask a question there.

Reporting issues or problems

  If you find a bug in the library, please visit:

    https://github.com/ttarkowski/quile/issues

  and create an issue.

Contributing to the software & Feature requests

  The Quilë library does not support  code contributions.  However, if
  you need some feature to be implemented in code, please visit:

    https://github.com/ttarkowski/quile/discussions

  and describe your  feature request.  However,  please note that your
  request  might be declined  or  permanently unresolved  due  to many
  reasons———including the facts that the library strives to be minimal
  and is intentionally developed as an one-person project.

Test suite

  Test suite in form of the short examples of the library features use
  is located in doc/examples/ directory. The Makefile for GCC compiler
  is provided, so tests execution can be performed with make command.

Code statistics

  * https://github.com/ttarkowski/quile/pulse
  * https://www.openhub.net/p/quile

                                 * * *

This work  is a result of  the project funded  by the National Science
Centre  of Poland   (Twardowskiego 16,   PL-30312 Kraków,       Poland,
http://www.ncn.gov.pl/) under the grant number UMO-2016/23/B/ST3/03575.