Reorganize (AMReX-Codes#22)

.editorconfig

@@ -0,0 +1,49 @@
+# http://EditorConfig.org
+#
+# precedence of rules is bottom to top
+
+# this is the top-most EditorConfig file
+root = true
+
+
+[*.{c,h,cpp,hpp,H,py}]
+# 4 space indentation
+indent_style = space
+indent_size = 4
+
+# setting it to true would result in too many white changes to amrex
+trim_trailing_whitespace = true
+
+# unix-style newlines
+end_of_line = lf
+
+# newline ending in files
+insert_final_newline = true
+
+
+[*.md]
+# two end of line whitespaces are newlines without a paragraph
+trim_trailing_whitespace = false
+
+
+[*.rst]
+# Enforce UTF-8 encoding
+charset = utf-8
+
+# Unix-style newlines
+end_of_line = lf
+
+# Newline ending in files
+insert_final_newline = true
+
+# 3 space indentation
+indent_style = space
+indent_size = 3
+
+# Clean up trailing whitespace
+trim_trailing_whitespace = true
+
+[Makefile]
+# TABs are part of its syntax
+indent_style = tab
+indent_size = unset

.github/workflows/linux.yml

@@ -15,6 +15,7 @@ jobs:
       run: .github/workflows/dependencies/dependencies.sh
     - name: Build & Install
       run: |
+        cd ExampleCodes
         mkdir build
         cd build
         cmake ..                        \
@@ -38,6 +39,7 @@ jobs:
       run: .github/workflows/dependencies/dependencies_gcc10.sh
     - name: Build & Install
       run: |
+        cd ExampleCodes
         mkdir build
         cd build
         cmake ..                        \
@@ -65,6 +67,7 @@ jobs:
       run: .github/workflows/dependencies/dependencies_clang6.sh
     - name: Build & Install
       run: |
+        cd ExampleCodes
         mkdir build
         cd build
         cmake ..                                      \
@@ -95,6 +98,7 @@ jobs:
       run: .github/workflows/dependencies/dependencies.sh
     - name: Build & Install
       run: |
+        cd ExampleCodes
         mkdir build
         cd build
         cmake ..                        \
@@ -119,6 +123,7 @@ jobs:
       run: .github/workflows/dependencies/dependencies_nofortran.sh
     - name: Build & Install
       run: |
+        cd ExampleCodes
         mkdir build
         cd build
         cmake ..                        \
@@ -144,6 +149,7 @@ jobs:
         export PATH=/usr/local/nvidia/bin:/usr/local/cuda/bin:${PATH}
         export LD_LIBRARY_PATH=/usr/local/nvidia/lib:/usr/local/nvidia/lib64:/usr/local/cuda/lib64:${LD_LIBRARY_PATH}
         which nvcc || echo "nvcc not in PATH!"
+        cd ExampleCodes
         mkdir build
         cd build
         cmake ..                                           \
@@ -175,7 +181,7 @@ jobs:
         export PATH=/usr/local/nvidia/bin:/usr/local/cuda/bin:${PATH}
         export LD_LIBRARY_PATH=/usr/local/nvidia/lib:/usr/local/nvidia/lib64:/usr/local/cuda/lib64:${LD_LIBRARY_PATH}
         which nvcc || echo "nvcc not in PATH!"
-
+        cd ExampleCodes
         cmake -S . -B build                              \
             -DCMAKE_VERBOSE_MAKEFILE=ON                  \
             -DAMReX_PARTICLES=ON                         \
@@ -209,6 +215,7 @@ jobs:
         set +e
         source /opt/intel/oneapi/setvars.sh
         set -e
+        cd ExampleCodes
         cmake -S . -B build                                \
             -DCMAKE_CXX_COMPILER_ID="Clang"                \
             -DCMAKE_CXX_COMPILER_VERSION=12.0              \
@@ -259,6 +266,7 @@ jobs:
         #   https://github.com/open-mpi/ompi/issues/9317
         export LDFLAGS="-lopen-pal"
 
+        cd ExampleCodes
         cmake -S . -B build_nofortran                     \
             -DCMAKE_VERBOSE_MAKEFILE=ON                   \
             -DAMReX_EB=ON                                 \

.github/workflows/macos.yml

@@ -16,6 +16,7 @@ jobs:
       run: .github/workflows/dependencies/dependencies_mac.sh
     - name: Build & Install
       run: |
+        cd ExampleCodes
         cmake -S . -B build             \
             -DBUILD_SHARED_LIBS=ON      \
             -DCMAKE_BUILD_TYPE=Debug    \

.github/workflows/windows.yml

@@ -11,6 +11,7 @@ jobs:
     - uses: actions/checkout@v2
     - name: Build & Install
       run: |
+        cd ExampleCodes
         cmake -S . -B build   `
               -DCMAKE_BUILD_TYPE=Debug      `
               -DBUILD_SHARED_LIBS=ON        `
@@ -33,6 +34,7 @@ jobs:
       shell: cmd
       run: |
         call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\vc\Auxiliary\build\vcvarsall.bat" x64
+        cd ExampleCodes
         cmake -S . -B build   ^
               -T "ClangCl"    ^
               -DCMAKE_BUILD_TYPE=Release    ^

.gitpod.dependencies.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -eu -o pipefail
+
+sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 2
+sudo update-alternatives --set python /usr/bin/python3
+python -m pip install --upgrade pip
+python -m pip install --upgrade wheel
+python -m pip install --upgrade cmake matplotlib==3.2.2 numpy yt

.gitpod.dockerfile

@@ -0,0 +1,3 @@
+FROM gitpod/workspace-full-vnc
+
+RUN sudo apt-get update  && sudo apt-get install -y --no-install-recommends build-essential g++ libopenmpi-dev openmpi-bin paraview python3-paraview ffmpeg python3 python3-pip python3-setuptools && sudo rm -rf /var/lib/apt/lists/*

.gitpod.yml

@@ -0,0 +1,30 @@
+# The Docker image to run your workspace in. Defaults to gitpod/workspace-full
+image:
+  file: .gitpod.dockerfile
+tasks:
+- init: /workspace/amrex-tutorials/.gitpod.dependencies.sh
+  command: cp -r /workspace/amrex-tutorials/.jupyter /home/gitpod/
+# Ports to expose on workspace startup (optional)
+ports:
+  - port: 8000
+    onOpen: open-preview
+  - port: 8888
+    onOpen: open-browser
+github:
+  prebuilds:
+    # enable for the master/default branch (defaults to true)
+    master: true
+    # enable for all branches in this repo (defaults to false)
+    branches: false
+    # enable for pull requests coming from this repo (defaults to true)
+    pullRequests: false
+    # enable for pull requests coming from forks (defaults to false)
+    pullRequestsFromForks: false
+    # add a check to pull requests (defaults to true)
+    addCheck: false
+    # add a "Review in Gitpod" button as a comment to pull requests (defaults to false)
+    addComment: false
+    # add a "Review in Gitpod" button to the pull request's description (defaults to false)
+    addBadge: false
+    # add a label once the prebuild is ready to pull requests (defaults to false)
+    addLabel: false

.jupyter/jupyter_notebook_config.py

@@ -0,0 +1,3 @@
+c.NotebookApp.ip = '0.0.0.0'
+c.NotebookApp.allow_origin = '*'
+c.NotebookApp.open_browser = False

Docs/source/AMR_Tutorial.rst

@@ -4,7 +4,9 @@
 .. role:: fortran(code)
    :language: fortran
 
-Tutorials/Amr
+.. _tutorials_amr:
+
+Amr
 =============
 
 For each of these tutorials,

Docs/source/Basic_Tutorial.rst

@@ -4,10 +4,15 @@
 .. role:: fortran(code)
    :language: fortran
 
-Tutorials/Basic
+.. include:: <isonum.txt>
+
+
+.. _tutorials_basic:
+
+Basic
 ==========================
 
-The tutorials in amrex/Tutorials/Basic demonstrate the most fundamental
+The tutorials in ``amrex_tutorials/ExampleCodes/Basic`` demonstrate the most fundamental
 operations supported by AMReX.
 
 **HelloWorld**
@@ -27,6 +32,7 @@ iterators.  Here, for example, rather than calling amrex::Print() in C++, we
 test on whether amrex_parallel_ioprocessor() is true, and if so, invoke
 the usual Fortran print call.
 
+
 **main**
 ----------------
 

Docs/source/Blueprint_Tutorial.rst

@@ -4,15 +4,17 @@
 .. role:: fortran(code)
    :language: fortran
 
-Tutorials/Blueprint
+.. _tutorials_blueprint:
+
+Blueprint
 ==========================
 
 These tests, ``AssignMultiLevelDensity`` and ``HeatEquation_EX1_C``,
 demonstrate how to convert AMReX Mesh data into an in-memory
 Conduit Mesh Blueprint description for consumption by the ALPINE Ascent
 in situ visualization and analysis tool.  These are variants, respectively, of
 ``amrex/Tests/Particles/AssignMultiLevelDensity`` and
-``amrex/Tutorials/Basic/HeatEquation_EX1_C``.
+``amrex-tutorials/ExampleCodes/Basic/HeatEquation_EX1_C``.
 
 For details about what mesh features are currently supported, see:
 amrex/Src/Base/AMReX_Conduit_Blueprint.H

Docs/source/EB_Tutorial.rst

@@ -4,16 +4,18 @@
 .. role:: fortran(code)
    :language: fortran
 
-Tutorials/EB
+.. _tutorials_eb:
+
+EB
 ==========================
 
-``amrex/Tutorials/EB/CNS`` is an AMR code for solving compressible
+``amrex-tutorials/ExampleCodes/EB/CNS`` is an AMR code for solving compressible
 Navier-Stokes equations with the embedded boundary approach.
 
-``amrex/Tutorials/EB/Poisson`` is a single-level code that is a proxy for
+``amrex-tutorials/ExampleCodes/EB/Poisson`` is a single-level code that is a proxy for
 solving the electrostatic Poisson equation for a grounded sphere with a point
 charge inside.
 
-``amrex/Tutorials/EB/MacProj`` is a single-level code that computes a divergence-free
+``amrex-tutorials/ExampleCodes/EB/MacProj`` is a single-level code that computes a divergence-free
 flow field around a sphere.  A MAC projection is performed on an initial velocity
-field of (1,0,0).
+field of :math:`(1,0,0)`.

Docs/source/ForkJoin_Tutorial.rst

@@ -4,7 +4,9 @@
 .. role:: fortran(code)
    :language: fortran
 
-Tutorials/Forkjoin
+.. _tutorials_forkjoin:
+
+Forkjoin
 ==================
 
 There are two examples in the Tutorials/ForkJoin directory.

Docs/source/GPU_Tutorial.rst

@@ -4,10 +4,12 @@
 .. role:: fortran(code)
    :language: fortran
 
-Tutorials/GPU
+.. _tutorials_gpu:
+
+GPU
 ==========================
 
-The tutorials in ``amrex/Tutorials/GPU`` demonstrate the implementation
+The tutorials in ``amrex-tutorials/ExampleCodes/GPU`` demonstrate the implementation
 of AMReX's GPU toolkit as well as provide GPU ported versions of CPU
 tutorials to help applications convert to GPUs.
 
@@ -54,12 +56,12 @@ preferred GPU launch methodologies.
 **CNS**
 -------
 
-CNS is a direct GPU port of the ``Tutorials/EB/CNS`` tutorial.
+CNS is a direct GPU port of the ``ExampleCodes/EB/CNS`` example.
 
 **AmrCore**
 -----------
 
-AmrCore is a direct GPU port of the ``Tutorials/Amr/Advection_AmrCore`` tutorial
+AmrCore is a direct GPU port of the ``ExampleCodes/Amr/Advection_AmrCore`` tutorial
 that advects a single scalar field with a velocity field specified on faces, using
 strategies similar to HeatEquation and CNS.
 

Docs/source/GuidedTutorials.rst

@@ -0,0 +1,55 @@
+
+
+Guided Tutorials
+================
+
+The source code for these tutorials can be found in the ``AMReX-Codes/amrex-tutorials``
+repo, under the parent directory ``amrex-tutorials/GuidedTutorials``.
+
+
+:ref:`Hello World<guided_hello_world>`
+--------------------------------------
+
+This tutorial explains how to build AMReX HelloWorld.
+
+
+.. _`Hello World`: HelloWorld.html
+
+
+---------
+
+:ref:`Heat Equation -- Simple<guided_heat_simple>`
+--------------------------------------------------
+
+A complete build-run-visualize workflow walk-through. This simplified introduction
+covers several basic components of AMReX while minimizing required knowledge of C++
+syntax.
+
+.. _`Heat Equation -- Simple`: HeatEquation_Simple.html
+
+|
+
+:ref:`Heat Equation<guided_heat>`
+---------------------------------
+
+This tutorial revisits AMReX's approach to heat equation in additional detail with
+preprocessor variables, scoped namespaces, and multiple source files
+to demonstrate additional convenience and functionality.
+
+.. _`Heat Equation`: HeatEquation_EX1_C.html
+
+
+-------------
+
+
+`Tutorials from the 2021 ECP Annual Meeting`_
+---------------------------------------------
+
+It's also possible to work through several tutorials on AMReX that were presented
+at the 2021 ECP Annual Meeting without needing to install any dependencies or
+download any code to your local machine. The tutorials are available in the GitHub repo,
+`ECP-Tutorials <https://github.com/atmyers/ecp-tutorials>`_ and use the GitPod
+cloud dev environment. For accompanying slides, see
+`tutorial_slides.pdf <https://amrex-codes.github.io/amrex/tutorial_slides.pdf>`_.
+
+.. _`Tutorials from the 2021 ECP Annual Meeting`: https://github.com/atmyers/ecp-tutorials