doc updates

Author: cgcgcg

.flake8

@@ -2,6 +2,8 @@
 extend-ignore =
     # E402: module level import not at top of file
     E402,
+    # E741 ambiguous variable name
+    E741,
     # H301: one import per line
     H301,
     # H306: imports not in alphabetical order

.github/workflows/build.yml

@@ -44,17 +44,17 @@ jobs:
     steps:
     - name: Check out repo
       if: always()
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Pull ccache cache
       if: always()
       id: ccache-restore
-      uses: actions/cache/restore@v3
+      uses: actions/cache/restore@v4
       with:
         path: /home/runner/.cache/ccache
         key: ccache-${{ env.BUILD_IDENTIFIER }}
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       if: always()
       with:
         python-version: ${{ matrix.py-version }}
@@ -89,7 +89,7 @@ jobs:
 
     - name: Push ccache cache
       if: always()
-      uses: actions/cache/save@v3
+      uses: actions/cache/save@v4
       with:
         path: /home/runner/.cache/ccache
         key: ccache-${{ env.BUILD_IDENTIFIER }}
@@ -115,7 +115,7 @@ jobs:
         mv cython-lint.xml cython-lint-${{ env.BUILD_IDENTIFIER }}.xml
 
     - name: Archive results
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: always()
       with:
         name: Results (${{ env.BUILD_PRETTY_IDENTIFIER }})
@@ -154,20 +154,20 @@ jobs:
 
     steps:
     - name: Check out repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Pull ccache cache
       if: always()
       id: ccache-restore
-      uses: actions/cache/restore@v3
+      uses: actions/cache/restore@v4
       with:
         path: /Users/runner/Library/Caches/ccache
         key: ccache-${{ runner.os }}-${{ matrix.py-version }}
 
     - name: Setup GNU Fortran
       uses: fortran-lang/setup-fortran@v1
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.py-version }}
 
@@ -203,7 +203,7 @@ jobs:
 
     - name: Push ccache cache
       if: always()
-      uses: actions/cache/save@v3
+      uses: actions/cache/save@v4
       with:
         path: /Users/runner/Library/Caches/ccache
         key: ccache-${{ runner.os }}-${{ matrix.py-version }}
@@ -229,7 +229,7 @@ jobs:
         mv cython-lint.xml cython-lint-${{ runner.os }}-${{ matrix.py-version }}.xml
 
     - name: Archive results
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: always()
       with:
         name: Results ${{ github.job }}

.github/workflows/container.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
     - name: Check out
       if: always()
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 

Dockerfile

@@ -25,6 +25,7 @@ RUN sed -i 's/Components: main/Components: main contrib non-free/' /etc/apt/sour
         libmetis-dev libparmetis-dev \
         texlive texlive-extra-utils texlive-latex-extra ttf-staypuft dvipng cm-super \
         jupyter-notebook \
+        emacs-nox vim \
   --no-install-recommends \
   && rm -rf /var/lib/apt/lists/*
 
@@ -36,12 +37,10 @@ WORKDIR /pynucleus
 RUN make prereq PIP_FLAGS=--no-cache-dir && \
     make prereq-extra PIP_FLAGS=--no-cache-dir && \
     make install && \
+    make docs && \
     python -m pip install --no-cache-dir ipykernel && \
     rm -rf build packageTools/build base/build metisCy/build fem/build multilevelSolver/build nl/build
 
-RUN echo "alias ls='ls --color=auto -FN'" >> /root/.bashrc \
-    && echo 'set completion-ignore-case On' >> /root/.inputrc
-
 # allow running MPI as root in the container
 # bind MPI ranks to hwthreads
 ENV OMPI_MCA_hwloc_base_binding_policy=hwthread \
@@ -53,4 +52,6 @@ RUN python -m ipykernel install --name=PyNucleus
 
 COPY README.container.rst /README.container.rst
 # hadolint ignore=SC2016
-RUN echo '[ ! -z "$TERM" -a -r /README.container.rst ] && cat /README.container.rst' >> /etc/bash.bashrc
+RUN echo '[ ! -z "$TERM" -a -r /README.container.rst ] && echo -e "\e[32m" && cat /README.container.rst && echo -e "\e[0m"' >> /etc/bash.bashrc
+
+WORKDIR /root

Makefile

@@ -115,8 +115,8 @@ clean_package :
 
 .PHONY: docs
 docs :
-	cd docs && make
 	$(PYTHON) -m sphinx -b html docs docs/build
+	find docs/build/_downloads -name "*.ipynb" | xargs -I {} cp {} examples
 
 clean_docs :
 	cd docs; rm -rf build
@@ -169,7 +169,7 @@ prereq:
 	$(PYTHON) -m pip install $(PIP_FLAGS) $(PIP_INSTALL_FLAGS) scikit-sparse
 
 prereq-extra:
-	$(PYTHON) -m pip install $(PIP_FLAGS) pytest pytest-html pytest-xdist Sphinx sphinxcontrib-programoutput flake8 flake8-junit-report cython-lint
+	$(PYTHON) -m pip install $(PIP_FLAGS) pytest pytest-html pytest-xdist Sphinx sphinxcontrib-programoutput sphinx-gallery sphinx-rtd-theme flake8 flake8-junit-report cython-lint
 
 flake8:
 	$(PYTHON) -m flake8 --output-file=flake8.txt --exit-zero drivers examples packageTools base metisCy fem multilevelSolver nl tests

README.container.rst

@@ -1,6 +1,12 @@
 
 This is a container image for PyNucleus.
 
-The drivers and examples for PyNucleus can be found in /pynucleus/drivers and /pynucleus/examples
+The directory from which the container was launched on the host system is mapped to /root.
+PyNucleus is installed at /pynucleus.
+A copy of the drivers and examples for PyNucleus can be found in /root/drivers and /root/examples.
+The Jupyter notebook interface is available at https://localhost:8889 on the host.
+A quick way to check that everything works is to run
 
-The directory from which the container was launched on the host system is mapped to /user
+  /root/drivers/runFractional.py
+
+This should print some information about the solution of a fractional Laplacian problem and show several plots.

README.rst

@@ -73,55 +73,62 @@ and open ``docs/build/index.html`` in your browser.
 Possible ways to install and use PyNucleus
 ==================================
 
+There are several ways to install and run PyNucleus:
+
 * container image
 * Spack installation
 * manual installation
 
+The easiest way to get up and running is probably the container image.
+
 
 Container image
 ----------------
 
 The simplest way to use PyNucleus is to pull a container image from the GitHub Container Registry.
 This requires an installation of either
 
-* podman (https://podman.io/) and podman-compose (https://github.com/containers/podman-compose) or
-* Docker (https://www.docker.com/) and Docker Compose (https://docs.docker.com/compose/install/).
+* `podman <https://podman.io/>`_ and `podman-compose <https://github.com/containers/podman-compose?tab=readme-ov-file#installation>`_ or
+* `Docker <https://www.docker.com/>`_ and `Docker Compose <https://docs.docker.com/compose/install/>`_.
 
 For many Linux distributions these can be installed from the package repositories.
-In what follows we will assume that we are using podman.
+In what follows we will assume that we are using `podman`.
 All commands for Docker should be identical up to the substitution of `podman` with `docker`.
 
-For example, on Ubuntu podman can be installed with
+For example, on Ubuntu podman and podman-compose can be installed with
 
 .. code-block:: shell
 
    sudo apt-get install podman podman-compose
 
-Instructions for other platforms can be found here: https://podman.io/docs/installation
+Instructions for other platforms can be found `here <https://podman.io/docs/installation>`_.
+
+Once podman is installed, we download a copy of `compose.yaml <https://github.com/sandialabs/PyNucleus/blob/master/compose.yaml>`_ and save it to an empty directory.
+
+.. warning::
+   Please do not copy this file to your home directory and launch the container from there.
+   The container keeps its state in the directory where it is launched from.
 
-Once podman is installed, we can download a copy of https://github.com/sandialabs/PyNucleus/blob/master/compose.yaml and save it to an empty directory.
 In that directory we then run
 
 .. code-block:: shell
 
-   podman compose run pynucleus
+   podman-compose run pynucleus
+
+podman will download a container image for PyNucleus and then launch a shell in the container.
+
+.. note::
+   The download of the image will only happen once, but it could be several GB in size.
 
-This launches a shell on the container with PyNucleus.
 A simple way to test if things work is to run
 
 .. code-block:: shell
 
    drivers/runFractional.py
 
-This should print some information about the solution of a fractional Laplacian problem and open up several plots.
-
-For development using PyNucleus it can be useful to launch a Jupyter notebook server:
-
-.. code-block:: shell
-
-   podman compose up pynucleus-jupyter
+This should print some information about the solution of a fractional Laplacian problem and show several plots.
 
-and then open the Jupyter notebook interface at https://localhost:8889
+For development using PyNucleus there is the Jupyter notebook interface that is available while the container is running at https://localhost:8889 on the host system.
 
 
 Spack install

base/PyNucleus_base/LinearOperator_{SCALAR}.pxi

@@ -97,6 +97,7 @@ cdef class {SCALAR_label}LinearOperator:
         cdef:
             np.ndarray[{SCALAR}_t, ndim=1] y
             {SCALAR}_t[::1] x_mv
+            {SCALAR_label}TimeStepperLinearOperator tsOp
         try:
             x_mv = x
             y = np.zeros((self.num_rows), dtype={SCALAR})
@@ -107,6 +108,9 @@ cdef class {SCALAR_label}LinearOperator:
                 return {SCALAR_label}Product_Linear_Operator(self, x)
             elif isinstance(self, {SCALAR_label}LinearOperator) and hasattr(x, 'ndim') and x.ndim == 2:
                 return self.dotMV(x)
+            elif isinstance(self, {SCALAR_label}TimeStepperLinearOperator) and isinstance(x, (float, int, {SCALAR})):
+                tsOp = self
+                return {SCALAR_label}TimeStepperLinearOperator(self, tsOp.M, tsOp.S, tsOp.facS*x, tsOp.facM*x)
             elif isinstance(self, {SCALAR_label}LinearOperator) and isinstance(x, (float, int, {SCALAR})):
                 return {SCALAR_label}Multiply_Linear_Operator(self, x)
             elif isinstance(x, {SCALAR_label}LinearOperator) and isinstance(self, (float, int, {SCALAR})):
@@ -339,6 +343,35 @@ cdef class {SCALAR_label}TimeStepperLinearOperator({SCALAR_label}LinearOperator)
             assign3(y, y, 1.0, self.z, self.facM)
         return 0
 
+    cdef INDEX_t matvecTrans(self,
+                             {SCALAR}_t[::1] x,
+                             {SCALAR}_t[::1] y) except -1:
+        if self.facS != 0.:
+            self.S.matvecTrans(x, y)
+            if self.facS != 1.0:
+                scaleScalar(y, self.facS)
+        if self.facM == 1.0:
+            self.M.matvecTrans_no_overwrite(x, y)
+        else:
+            self.M.matvecTrans(x, self.z)
+            assign3(y, y, 1.0, self.z, self.facM)
+        return 0
+
+    cdef INDEX_t matvecTrans_no_overwrite(self,
+                                          {SCALAR}_t[::1] x,
+                                          {SCALAR}_t[::1] y) except -1:
+        if self.facS == 1.0:
+            self.S.matvecTrans_no_overwrite(x, y)
+        elif self.facS != 0.:
+            self.S.matvecTrans(x, self.z)
+            assign3(y, y, 1.0, self.z, self.facS)
+        if self.facM == 1.0:
+            self.M.matvecTrans_no_overwrite(x, y)
+        elif self.facM != 0.:
+            self.M.matvecTrans(x, self.z)
+            assign3(y, y, 1.0, self.z, self.facM)
+        return 0
+
     def get_diagonal(self):
         return (self.facM*np.array(self.M.diagonal, copy=False) +
                 self.facS*np.array(self.S.diagonal, copy=False))
@@ -413,6 +446,22 @@ cdef class {SCALAR_label}Multiply_Linear_Operator({SCALAR_label}LinearOperator):
             scaleScalar(y, self.factor)
         return 0
 
+    cdef INDEX_t matvecTrans(self,
+                             {SCALAR}_t[::1] x,
+                             {SCALAR}_t[::1] y) except -1:
+        self.A.matvecTrans(x, y)
+        scaleScalar(y, self.factor)
+        return 0
+
+    cdef INDEX_t matvecTrans_no_overwrite(self,
+                                          {SCALAR}_t[::1] x,
+                                          {SCALAR}_t[::1] y) except -1:
+        if self.factor != 0.:
+            scaleScalar(y, 1./self.factor)
+            self.A.matvecTrans_no_overwrite(x, y)
+            scaleScalar(y, self.factor)
+        return 0
+
     def isSparse(self):
         return self.A.isSparse()
 
@@ -472,17 +521,31 @@ cdef class {SCALAR_label}Product_Linear_Operator({SCALAR_label}LinearOperator):
     cdef INDEX_t matvec(self,
                         {SCALAR}_t[::1] x,
                         {SCALAR}_t[::1] y) except -1:
-        self.B(x, self.temporaryMemory)
-        self.A(self.temporaryMemory, y)
+        self.B.matvec(x, self.temporaryMemory)
+        self.A.matvec(self.temporaryMemory, y)
         return 0
 
     cdef INDEX_t matvec_no_overwrite(self,
                                      {SCALAR}_t[::1] x,
                                      {SCALAR}_t[::1] y) except -1:
-        self.B(x, self.temporaryMemory)
+        self.B.matvec(x, self.temporaryMemory)
         self.A.matvec_no_overwrite(self.temporaryMemory, y)
         return 0
 
+    cdef INDEX_t matvecTrans(self,
+                             {SCALAR}_t[::1] x,
+                             {SCALAR}_t[::1] y) except -1:
+        self.A.matvecTrans(x, self.temporaryMemory)
+        self.B.matvecTrans(self.temporaryMemory, y)
+        return 0
+
+    cdef INDEX_t matvecTrans_no_overwrite(self,
+                                          {SCALAR}_t[::1] x,
+                                          {SCALAR}_t[::1] y) except -1:
+        self.A.matvecTrans(x, self.temporaryMemory)
+        self.B.matvecTrans_no_overwrite(self.temporaryMemory, y)
+        return 0
+
     cdef void _residual(self,
                         {SCALAR}_t[::1] x,
                         {SCALAR}_t[::1] rhs,

base/PyNucleus_base/utilsFem.py

@@ -1376,6 +1376,8 @@ def runDriver(path, py, python=None, timeout=600, ranks=None, cacheDir='',
             cache += str(ranks)
             runOutput += str(ranks)
         py += ['--test', '--testCache={}'.format(cache)]
+        if 'OVERWRITE_CACHE' in os.environ:
+            overwriteCache = True
         if overwriteCache:
             py += ['--overwriteCache']
     else: