improve tutorials and ci and docs

Author: Francesco Rizzi

.github/workflows/test-all.yml

@@ -103,3 +103,10 @@ jobs:
         run: |
           cd $BUILD_DIR
           ctest
+
+      - name: Run demos
+        run: |
+          cd $BUILD_DIR/ode-using-eigen-types
+          bash runall_for_ci.sh
+          cd ../nonlinearsolvers-using-eigen-types
+          bash runall_for_ci.sh

CMakeLists.txt

@@ -17,5 +17,5 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 
 enable_testing()
 add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/end-to-end-roms)
-add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ode-eigen)
-add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/solvers-eigen)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ode-using-eigen-types)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/nonlinearsolvers-using-eigen-types)

docs/source/build.rst

@@ -2,9 +2,19 @@
 Build instructions
 ##################
 
-The pressio tutorials are designed to be easy and quick to build.
-Thefore, all C++ dependencies **are already snapshotted inside the repo**,
-and to build the code you ONLY need **CMake > 3.18.0** and a **C++14 compliant compiler**.
+These tutorials should be easy and quick to build, follow below.
+
+What you need
+-------------
+
+- **CMake > 3.18.0**
+
+- **C++14 compiler**: `our CI <https://github.com/Pressio/pressio-tutorials/blob/develop/.github/workflows/test-all.yml>`__ is currently testing both GCC and Clang
+
+- Python 3.x with specific packages listed `here <../../py_requirements.txt>`__
+
+Steps
+-----
 
 .. code-block:: bash
 
@@ -16,29 +26,32 @@ and to build the code you ONLY need **CMake > 3.18.0** and a **C++14 compliant c
    cmake -DCMAKE_BUILD_TYPE=Release -S <path-to-your-cloned-repo> -B $BUILDDIR
    cd $BUILDDIR && make -j4
 
-Executables for all tutorials and the end-to-end demos
-can be found inside the build directory.
+   # if needed, the Python packages can be installed as
+   pip3 install <path-to-your-cloned-repo>/py_requirements.txt
+
+
+Then what?
+----------
+
+Individual executables and the end-to-end demos can be found inside the build directory.
 
 .. tip::
 
-   To verify the build, you can enable the tests using ``-DPRESSIOTUTORIALS_ENABLE_TESTS=ON``,
+   If you want to verify the build, you can enable tests via ``-DPRESSIOTUTORIALS_ENABLE_TESTS=ON``,
    and then do:
 
    .. code-block:: cpp
 
       cd $BUIlDDIR
       ctest
 
-The Python requirements can be found `here <../../end-to-end-roms/requirements.txt>`__
-and can be installed via ``pip3 install end-to-end-roms/requirements.txt``
-
 
-Dependencies
-------------
+More details on dependencies
+----------------------------
 
 The tutorials have the following dependencies:
 
-- pressio: contains the C++ code that this tutorials repo convers
+- pressio C++ library: contains the C++ code that this tutorials repo convers
 - pressio-demoapps: provides a suite of physics problems that are used in the tutorials to demonstrate the functionalities of pressio
-- Eigen: is the data structure library that pressio-demoapps rely on
+- Eigen: is the library used by pressio-demoapps
 - Python: is used in pressio-demoapps to implement all the ROM workflow drivers

docs/source/index.rst

@@ -15,9 +15,10 @@ reduced-order models (ROMs), which is a strongly multidisciplinary topic.
 Working on a production-level ROM capability inevitably means touching
 multiple fields, ranging from, e.g., linear algebra, nonlinear solvers
 and optimization, to distributed computing, HPC and time integration.
-This is clearly reflected in the `structure of pressio <https://pressio.github.io/pressio/html/index.html>`__,
-where several components (all usable independently) offer different capabilities,
-but as a whole constitute the stack foundation of the ``pressio/rom`` component.
+This is clearly reflected in the `structure of pressio <https://pressio.github.io/pressio/html/index.html>`__
+which display a "stacked" design: each component handles a specific capability and depends
+on the ones below it such that you can use it directly, but, as a whole, the stack constitutes
+the foundation of the top-level ``pressio/rom`` component.
 
 Describing how to use pressio for ROMs cannot be simply reduced to presenting the API.
 Several steps are involved, and the best way to understand them is via examples.
@@ -102,6 +103,8 @@ Find us on `Slack <https://pressioteam.slack.com>`_.
    :caption: 2. self-contained tutorials using Eigen data types
 
    ./using_eigen/ode1
+   ./using_eigen/ode2
+   ./using_eigen/ode3
    ./using_eigen/nonlinsolvers1
 
 .. toctree::

docs/source/using_eigen/nonlinsolvers1.rst

@@ -1,7 +1,7 @@
-nonlinear solvers tutorial 1
-============================
+nonlinear solvers: tutorial 1
+=============================
 
-.. literalinclude:: ../../../solvers-eigen/main1.cc
+.. literalinclude:: ../../../nonlinearsolvers-using-eigen-types/main1.cc
    :language: cpp
-   :lines: 1-100
+   :lines: 1-99
    :linenos:

docs/source/using_eigen/ode1.rst

@@ -1,7 +1,6 @@
-ode tutorial 1
-==============
+ode: tutorial 1
+===============
 
-.. literalinclude:: ../../../ode-eigen/main1.cc
+.. literalinclude:: ../../../ode-using-eigen-types/main1.cc
    :language: cpp
-   :lines: 1-86
-   :linenos:
+   :lines: 1-85

docs/source/using_eigen/ode2.rst

@@ -0,0 +1,20 @@
+ode: tutorial 2
+===============
+
+.. literalinclude:: ../../../ode-using-eigen-types/tutorial2/main.cc
+   :language: cpp
+   :lines: 1-96
+
+
+Process results
+---------------
+
+.. code-block:: bash
+
+   # from within $BUILDDIR/ode-using-eigen-types/tutorial2
+   python3 plot.py
+
+.. image:: ../../../ode-using-eigen-types/tutorial2/plot.png
+  :width: 50 %
+  :align: center
+  :alt: Lorenz

docs/source/using_eigen/ode3.rst

@@ -0,0 +1,20 @@
+ode: tutorial 3
+===============
+
+.. literalinclude:: ../../../ode-using-eigen-types/tutorial3/main.cc
+   :language: cpp
+   :lines: 1-158
+
+
+Process results
+---------------
+
+.. code-block:: bash
+
+   # from within $BUILDDIR/ode-using-eigen-types/tutorial3
+   python3 plot.py
+
+.. image:: ../../../ode-using-eigen-types/tutorial3/plot.png
+  :width: 50 %
+  :align: center
+  :alt: Lorenz

solvers-eigen/CMakeLists.txt …solvers-using-eigen-types/CMakeLists.txtsolvers-eigen/CMakeLists.txt renamed to nonlinearsolvers-using-eigen-types/CMakeLists.txt solvers-eigen/CMakeLists.txt renamed to nonlinearsolvers-using-eigen-types/CMakeLists.txt

@@ -4,5 +4,6 @@ include_directories(
   ${CMAKE_CURRENT_SOURCE_DIR}/../tpls
   ${CMAKE_CURRENT_SOURCE_DIR}/../tpls/pressio/include)
 
-set(EXENAMEROOT solvers_eigen)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/runall_for_ci.sh runall_for_ci.sh COPYONLY)
+set(EXENAMEROOT nonlinear_solvers_eigen)
 add_executable(${EXENAMEROOT}_exe1 main1.cc)

solvers-eigen/main1.cc …linearsolvers-using-eigen-types/main1.ccsolvers-eigen/main1.cc renamed to nonlinearsolvers-using-eigen-types/main1.cc solvers-eigen/main1.cc renamed to nonlinearsolvers-using-eigen-types/main1.cc

@@ -78,18 +78,18 @@ int main()
   auto gnSolver = pnonls::create_gauss_newton(problem, linearSolver);
   gnSolver.setTolerance(1e-5);
 
-  auto state = problem.createState();
-  state(0) = -0.05; state(1) = 1.1; state(2) = 1.2; state(3) = 1.5;
-  gnSolver.solve(problem, state);
+  auto x = problem.createState();
+  x(0) = -0.05; x(1) = 1.1; x(2) = 1.2; x(3) = 1.5;
+  gnSolver.solve(problem, x);
 
   // check solution
   std::cout << "Computed solution: \n "
 	    << "["
 	    << std::setprecision(14)
-	    << state(0) << " "
-	    << state(1) << " "
-	    << state(2) << " "
-	    << state(3) << " " << "] \n"
+	    << x(0) << " "
+	    << x(1) << " "
+	    << x(2) << " "
+	    << x(3) << " " << "] \n"
 	    << "Expected solution: \n "
 	    << "[1.0000000156741, 0.99999999912477, 0.99999999651993, 0.99999998889888]"
 	    << std::endl;