/*!

@mainpage Chameleon, a dense linear algebra library for scalable multi-core architectures and GPGPUs

This document aims at describing Chameleon's API, internal functions,
as well as the source code organization.

To get information about the Chameleon project, installation guide and
usage examples please refer to the [user's
guide](https://solverstack.gitlabpages.inria.fr/chameleon/users_guide.html).

Chameleon user's API is mostly composed of linear algebra routines of
the form **CHAMELEON_name[_Tile[_Async]]** where *name* follows the
[LAPACK naming scheme](http://www.netlib.org/lapack/lug/node24.html)
that can be used with the Chameleon library. These routines are
described individually in the section \ref sec_linalg.

In addition to the algorithmic routines Chameleon provides a set of
functions to control the overall process, see \ref sec_auxiliary

@section sec_linalg Linear algebra routines

- @ref CHAMELEON_Complex64_t "LAPACK matrix layout" : the simplest
  Chameleon interface which is equivalent to CBLAS/LAPACKE

- @ref CHAMELEON_Complex64_t_Tile "Tile matrix layout" : interface to
  be used with **Descriptors**, the Chameleon specific structure to
  handle the data as a set of tiles, see \ref Descriptor and \ref Tile

- @ref CHAMELEON_Complex64_t_Tile_Async "Tile matrix layout, asynchronous interface" :
  same as the tile interface but without waiting for the termination of
  tasks, see \ref Sequences

@section sec_auxiliary Auxiliary and control routines

- @ref Control : to initialize/finalize Chameleon, functions that must
  be called to use any routines, pause/resume task executions, etc

- @ref Options : to set/get some parameters such as the number of CPUs
  and GPUs to use

- @ref Descriptor : to handle the data structure used with the
  **Tile** interface

- @ref Tile : to convert (copy) LAPACK type data into *Descriptor* one
  and conversely

- @ref Sequences : to handle asynchronous tasks execution, to be used
  with the **Tile_Async** interface

- @ref Workspace : to handle specific workspace to be used with some
  of the algorithms

- @ref Auxiliary : to get some extra information such as the version,
  the data byte size, the mpi rank


@section sec_src_code_structure Libraries and source code organization

Chameleon's project is made of some C libraries and executables whose
compilation is optional (examples and testing).

The libraries are organized as follows :

- __chameleon__ : user's API and task based algorithms, depends on
  "chameleon_quark|openmp|parsec|starpu", "coreblas", "hqr"

- __chameleon_quark|openmp|parsec|starpu__ : interface to the
  different runtimes, depends on "coreblas" and optionally on
  "cudablas" and on a runtime system library

- __coreblas__ and __cudablas__ : interfaces to the CPU and GPU
  kernels

- __hqr__ : HQR is a C library providing tools to generate hierachical
  trees adapted to 2D block-cyclic data distribution and algorithms
  based on tiled QR/algorithms

Lets have a look to the source code organization in directories.

- __cmake_modules__ : CMakes scripts for setting
  variables. [morse_cmake](https://gitlab.inria.fr/solverstack/morse_cmake)
  is used for system introspection.

- __compute__ : the task based algorithms as well as the different
  interfaces (Lapack, Tile, Async) to call them

- __control__ : some Chameleon general routines to control the library,
  initialize, finalize, set options, descriptors and sequences handling,
  etc

- __coreblas__ : the Chameleon interface to CPU linear algebra kernels

- __cudablas__ : the Chameleon interface to GPU linear algebra kernels

- __distrib__ : some hints to install Chameleon's dependencies

- __doc__ : users and developers documentations

- __example__ : couple of C files to show how to use Chameleon

- __hqr__ : [HQR](https://gitlab.inria.fr/solverstack/hqr) is a C
library providing tools to generate hierachical trees adapted to 2D
block-cyclic data distribution and algorithms based on tiled
QR/algorithms

- __include__ : Chameleon's headers file necessary for users

- __lib__ : material related to the distribution

- __plasma-conversion__ : scripts to convert plasma task based
algorithms into chameleon's ones

- __runtime__ : interfaces to runtime systems

- __simucore__ : data to be able to simulate chameleon executions
  through StarPU+SimGrid

- __testing__ : source files for testing executables (timing and numerical checks)

- __tools__ : other scripts for testing (software development quality)

*/
