Documentation

.github/workflows/documentation.yml

@@ -0,0 +1,37 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    name: sphinx-doc
+    runs-on: ubuntu-latest
+    container: arcaneframework/alien-base:ubuntu20.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Configure CMake
+        run:
+          cmake -B build -DCMAKE_BUILD_TYPE=Debug -DALIEN_PLUGIN_HYPRE:BOOL=ON -DALIEN_PLUGIN_PETSC:BOOL=ON -G Ninja -DCMAKE_INSTALL_PREFIX=/opt/alien -DALIEN_DEFAULT_OPTIONS:BOOL=ON -DALIENDEV_EMBEDDED:BOOL=ON -DALIEN_GENERATE_DOCUMENTATION:BOOL=ON -DCMAKE_PREFIX_PATH="/opt/arccon;/opt/arccore"
+
+      - name: Build documentation
+        run:
+          cmake --build build --target alien_doc
+
+      - name: Install deploy dependencies 📚
+        if: github.ref == 'refs/heads/main'
+        run: |
+          apt-get update && apt-get install -y rsync git
+
+      - name: Deploy Docs
+        if: github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@364c31d33bb99327c77b3a5438a83a357a6729ad # v3.4.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./build/alien_doc
+          force_orphan: true

CMakeLists.txt

@@ -108,10 +108,21 @@ if (ALIEN_DEFAULT_OPTIONS)
     set(ALIEN_USE_LIBXML2 ${LibXml2_FOUND})
 endif ()
 
-add_subdirectory(docs)
-
 enable_testing()
 
+if (ALIEN_GENERATE_DOCUMENTATION)
+    find_package(Doxygen REQUIRED)
+
+    # doxygen settings can be set here, prefixed with "DOXYGEN_"
+    set(DOXYGEN_SOURCE_BROWSER YES)
+    set(DOXYGEN_EXTRACT_PRIVATE YES)
+    set(DOXYGEN_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
+
+    # For sphinx
+    set(DOXYGEN_GENERATE_HTML NO)
+    set(DOXYGEN_GENERATE_XML YES)
+endif(ALIEN_GENERATE_DOCUMENTATION)
+
 add_subdirectory(src)
 
 if (ALIEN_PLUGIN_HYPRE)
@@ -127,6 +138,7 @@ if (ALIEN_PLUGIN_TRILINOS)
     add_subdirectory(plugins/trilinos)
 endif (ALIEN_PLUGIN_TRILINOS)
 
+add_subdirectory(docs)
 
 # ----------------------------------------------------------------------------
 # Local Variables:

docs/CMakeLists.txt

@@ -1,15 +1,5 @@
 if (ALIEN_GENERATE_DOCUMENTATION)
-    find_package(Doxygen REQUIRED)
-
-    # doxygen settings can be set here, prefixed with "DOXYGEN_"
-    set(DOXYGEN_SOURCE_BROWSER YES)
-    set(DOXYGEN_EXTRACT_PRIVATE YES)
-    set(DOXYGEN_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
-
-    # For sphinx
-    set(DOXYGEN_GENERATE_HTML NO)
-    set(DOXYGEN_GENERATE_XML YES)
-    find_package(Sphinx REQUIRED breathe)
+    find_package(Sphinx REQUIRED breathe exhale)
 
     set(SPHINX_COPYRIGHT "CEA, IFPEN")
     set(SPHINX_AUTHOR "CEA, IFPEN")
@@ -23,7 +13,7 @@ if (ALIEN_GENERATE_DOCUMENTATION)
 
     sphinx_add_docs(
             alien_doc
-            BREATHE_PROJECTS doxygen_api_docs_movesemantic
+            BREATHE_PROJECTS doxygen_api_docs_movesemantic doxygen_api_docs_core_data
             BUILDER html
             SOURCE_DIRECTORY sphinx
             OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/alien_doc"

docs/sphinx/developer/API.rst

@@ -12,7 +12,7 @@ Alien User API aims at:
     - performing *algebraic* operations,
     - performing *computer related* operations.
 
-Alien's design allows to create new APIs to give access to previously listed functiunalities.
+Alien's design allows to create new APIs to give access to previously listed functionalities.
 
 
 Alien layout for header files

docs/sphinx/user/concepts.rst

@@ -0,0 +1,91 @@
+.. _user_concepts:
+
+=========================
+Alien's high level design
+=========================
+
+Alien's design key objective is to provide a robust interface for linear algebra users in the context of distributed
+memory computations.
+
+Robustness is achieved relying on well defined concepts to ensure a mathematically correct code, as well as a valid
+parallel code.
+
+Mathematical Choices
+====================
+
+We will present quickly important mathematical aspects of Alien. First we will introduce the scope of Alien, and then we will
+describe more precisely how Alien uses mathematical objects such as matrices.
+
+Linear Algebra
+--------------
+
+Alien focuses on linear algebra, dealing with matrices and vectors. We do not support nonlinear solvers,
+such as non-linear Newton algorithms.
+
+Alien provides access to solvers for linear equations: for given matrix :math:`A` and right hand side vector :math:`b`,
+find vector :math:`x` which satisfies :eq:`linear_eq`.
+
+.. math:: A x = b
+   :label: linear_eq
+
+Alien also provides access to linear algebra basic computations such as matrix-vector products, linear combinations, ...
+
+Spaces
+------
+
+In Alien, we chose to view linear algebra objects as defined on generic indexed *spaces*.
+
+Indeed, there are several ways to define a matrix, and we retain the following:
+given three sets :math:`(I,J,K)`, a matrix :math:`M` is a family of elements of :math:`K`,
+indexed by the cartesian product :math:`I \times J`; i.e. an application :math:`M : I \times J \mapsto K`, see
+[bourbaki_matrix]_ for more details.
+
+Most common indexed space are :math:`\{0,..,n-1\}` or :math:`\{1,..,n\}`.
+
+Using named spaces allow us to ensure strict compatibility checks when computing.
+For example, if :math:`u_I` and :math:`u_J` are two vectors defined on :math:`I` and :math:`J`,
+we can detect that computing matrix-vector product :math:`M . u_I` is invalid while :math:`M . u_J` is valid.
+
+If :math:`I` and :math:`J` have the same size, as it is the case for square matrices, it is impossible to distinguish
+mathematically valid operations from invalid without using set's names.
+
+Another advantage of using these named spaces is that we can unambiguously define sub-matrices.
+
+Trilinos [trilinos]_ uses something similar but less formalized with its `maps <https://docs.trilinos.org/dev/packages/epetra/doc/html/classEpetra__Map.html>`_.
+
+Software design
+===============
+
+Multiple representations
+------------------------
+
+Alien is mainly a wrapper over external linear algebra libraries. The idea is to not reimplement linear solvers.
+However, we focus on interoperability between libraries and functionalities.
+
+Alien's main idea is to allow dynamic (runtime) change of linear solver implementation. For example, one can try to solve
+a linear system using a fast but not numerically robust algorithm, but yet be able to switch to a slow and robust one
+if the former has failed.
+
+Alien will convert data structures between libraries and deal with the distributed memory aspects.
+
+
+Stateless objects
+-----------------
+
+To ensure easier of Alien, as well as more robust code, we have chosen to not rely on state for our objects.
+That means that we do not want the user to deal with notions liked, is my matrix correctly finalized before computing with it ?
+
+To enable that idea, we heavily rely on a converter pattern. That means we will have a lot of specific objects, that can only
+perform one task, such as filling in or compute linear expression. To perform different operations, user has to
+*explicitly* convert between types.
+
+
+Coherent APIs
+-------------
+
+
+References
+==========
+
+.. [bourbaki_matrix]  N. Bourbaki, Algèbre, Chapitres 1 à 3, Springer, 2006, 2e éd.
+.. [trilinos] The Trilinos Project Website, https://trilinos.github.io

docs/sphinx/user/index.rst

@@ -5,4 +5,5 @@ Alien user documentation
 
 .. toctree::
     :maxdepth: 2
+   concepts
    move

docs/sphinx/user/move.rst

@@ -3,15 +3,32 @@
 Building with move semantic
 ===========================
 
-.. doxygenclass:: Alien::DirectMatrixBuilder
+DirectMatrixBuilder
+-------------------
+
+.. doxygenclass:: Alien::Move::DirectMatrixBuilder
    :project: doxygen_api_docs_movesemantic
    :members:
+   :undoc-members:
 
-.. doxygenclass:: Alien::ProfiledMatrixBuilder
-   :project: doxygen_api_docs_movesemantic
+ProfiledMatrixBuilder
+---------------------
 
-.. doxygenclass:: Alien::VectorReader
+.. doxygenclass:: Alien::Move::ProfiledMatrixBuilder
    :project: doxygen_api_docs_movesemantic
 
-.. doxygenclass:: Alien::VectorWriter
+MatrixData
+----------
+
+.. doxygenclass:: Alien::Move::MatrixData
    :project: doxygen_api_docs_movesemantic
+   :members:
+   :undoc-members:
+
+IMatrix
+-------
+
+.. doxygenclass:: Alien::IMatrix
+   :project: doxygen_api_docs_core_data
+   :members:
+   :undoc-members:

src/modules/core/src/alien/data/CMakeLists.txt

@@ -14,20 +14,23 @@
 # 
 # SPDX-License-Identifier: Apache-2.0
 
-add_library(alien_data OBJECT
-        CompositeMatrix.cc
+set(alien_core_data_public_headers
         CompositeMatrix.h
-        CompositeVector.cc
         CompositeVector.h
         IMatrix.h
-        ISpace.h
         IVector.h
-        Space.cc
         Space.h
         Universal.h
-        Universe.cc
-        UniverseDataBase.h
         Universe.h
+        UniverseDataBase.h
+        )
+
+add_library(alien_data OBJECT
+        ${alien_core_data_public_headers}
+        CompositeMatrix.cc
+        CompositeVector.cc
+        Space.cc
+        Universe.cc
         utils/ExtractionIndices.cc
         utils/ExtractionIndices.h
         utils/MatrixElement.h
@@ -37,6 +40,15 @@ add_library(alien_data OBJECT
         utils/VectorElementT.h
         )
 
+if (ALIEN_GENERATE_DOCUMENTATION)
+    set(DOXYGEN_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
+    doxygen_add_docs(doxygen_api_docs_core_data
+            ${alien_core_data_public_headers}
+            USE_STAMP_FILE
+            COMMENT "Generate API-documents for Alien."
+            )
+endif(ALIEN_GENERATE_DOCUMENTATION)
+
 target_include_directories(alien_data PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../..)
 target_include_directories(alien_data PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/../..)
 target_include_directories(alien_data PRIVATE ${PROJECT_BINARY_DIR})

src/modules/movesemantic/CMakeLists.txt

@@ -38,6 +38,7 @@ add_library(alien_semantic_move
         )
 
 if (ALIEN_GENERATE_DOCUMENTATION)
+  set(DOXYGEN_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
   doxygen_add_docs(doxygen_api_docs_movesemantic
           ${alien_semantic_public_header}
           USE_STAMP_FILE