Quick start docs (#248)

Updated the quick-start guide so it actually has some content and synched information with the joss paper. Want to get this into dev and then to main so we can push to JOSS very soon. All tests pass and all QuickStart notebook examples now run.
underworldcode · Oct 4, 2024 · 4935c37 · 4935c37
2 parents 2e9ed15 + 60b02aa
commit 4935c37
Show file tree

Hide file tree

Showing 28 changed files with 239 additions and 169 deletions.
diff --git a/.binder/apt.txt b/.binder/apt.txt
@@ -1,8 +1,8 @@
 libgl1-mesa-glx
 libxcursor-dev
-libglu1 
-libxft2 
-libxinerama1 
-libfltk1.3-dev  
-libfreetype6-dev  
-libgl1-mesa-dev 
+libglu1
+libxft2
+libxinerama1
+libfltk1.3-dev
+libfreetype6-dev
+libgl1-mesa-dev
diff --git a/.binder/environment.yml b/.binder/environment.yml
@@ -2,28 +2,30 @@ name: uw3
 channels:
   - conda-forge
 dependencies:
-  - petsc=3.21.0
-  - petsc4py=3.21.0
+  - python=3.11
+  - compilers
+  - openmpi
+  - openmpi-mpicc
+  - openmpi-mpicxx
+  - petsc=3.21.5 # Fix for now (errors with hdf5 / uw3)
+  - petsc4py=3.21.5
   - cython=3.*
   - mpmath<=1.3
   - mesalib
   - numpy
   - scipy
-  - mpich-mpicc
-  - mpich-mpicxx
   - mpi4py
   - h5py
   - sympy
   - pytest
-  - ipython 
+  - ipython
   - pyvista
-  - quarto
   - pip
-  - pip:  
-    - gmsh
-    - jupyterlab>=4.1
-    - jupytext>=1.16.1
-    - pygments>=2.17.0
-    - trame-vtk
-    - trame-vuetify
-
+  - pip:
+      - gmsh
+      - gmsh-api
+      - jupyterlab
+      - jupytext
+      - pygments
+      - trame-vtk
+      - trame-vuetify
diff --git a/.binder/postBuild b/.binder/postBuild
@@ -1,6 +1,5 @@
 #!/bin/bash -v
 
-
 # echo
 # echo Install uw3_env during postBuild phase
 # echo
@@ -15,23 +14,24 @@ echo
 echo Install jupyter extensions
 echo
 
-# install required python packages
+# install required python packages for jupyter
 python3 -m pip install "jupyter-server-proxy"
-python3 -m pip install "jupyterlab-quarto>=0.3.3"
+# python3 -m pip install "jupyterlab-quarto>=0.3.3"
 python3 -m pip install "jupytext>=1.16.1"
 python3 -m pip install "trame_jupyter_extension"
 
-# We install the local code "properly" - no point in a dev build here
+# We install the local code "properly" - no point in an in-place build here
 
 echo
-echo Install local UW3 
+echo Install local UW3
 echo
 
 # Note: we would be better to find a way to access this directly
 # CONDA_PREFIX=`conda run -n notebook bash -c "echo \${CONDA_PREFIX}"`
 
 export CONDA_PREFIX=/srv/conda/envs/notebook/
 export PYTHONPATH=$CONDA_PREFIX/lib
+export CC=`which mpicc`
 
 # debugging if required
 # python -c "import petsc4py; print(petsc4py.get_config())"
@@ -41,7 +41,6 @@ export PYTHONPATH=$CONDA_PREFIX/lib
 
 pip install .
 
-
 echo
 echo Completed
-echo
+echo
diff --git a/.github/.devcontainer/uw_environment.yml b/.github/.devcontainer/uw_environment.yml
@@ -2,28 +2,30 @@ name: uw3
 channels:
   - conda-forge
 dependencies:
-  - petsc=3.21.0
-  - petsc4py=3.21.0
+  - python=3.11
+  - compilers
+  - openmpi
+  - openmpi-mpicc
+  - openmpi-mpicxx
+  - petsc=3.21.5 # Fix for now (errors with hdf5 / uw3)
+  - petsc4py=3.21.5
   - cython=3.*
   - mpmath<=1.3
   - mesalib
   - numpy
   - scipy
-  - mpich-mpicc
-  - mpich-mpicxx
   - mpi4py
   - h5py
   - sympy
   - pytest
-  - ipython 
+  - ipython
   - pyvista
-  - quarto
   - pip
-  - pip:  
-    - gmsh
-    - jupyterlab>=4.1
-    - jupytext>=1.16.1
-    - pygments>=2.17.0
-    - trame-vtk
-    - trame-vuetify
-
+  - pip:
+      - gmsh
+      - gmsh-api
+      - jupyterlab
+      - jupytext
+      - pygments
+      - trame-vtk
+      - trame-vuetify
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1,8 +1,7 @@
 This page provides information about contributing to Underworld’s codebase.
+For contributions of Underworld models please go https://github.com/underworld-community
 
-For contributions to Underworld models please go https://github.com/underworld-community
-
----- 
+----
 
 We welcome contributions to Underworld’s codebase in the form of:
 
@@ -11,8 +10,8 @@ We welcome contributions to Underworld’s codebase in the form of:
   * Suggestions / Requests
   * Documentation modifications (including docstrings)
 
-For Bug reports and Suggestions / Requests please submit an Issue on the Underworld GitHub Issue Tracker. 
-Please tag the Issue with a given Label to help us assess the issue and provide simple scripts that explain how to 
+For Bug reports and Suggestions / Requests please submit an Issue on the Underworld GitHub Issue Tracker.
+Please tag the Issue with a given Label to help us assess the issue and provide simple scripts that explain how to
 reproduce the problem.
 
 Click here to submit an Issue https://github.com/underworldcode/underworld3/issues
@@ -30,14 +29,14 @@ More specifically:
 2. Add the master Underworld repository as an additional remote source (named `uwmaster`) for your local repo and pull down its latest changesets. Checkout to the master/development repo state, and then create a new local branch which will contain your forthcoming changes.
 
 ``` bash
-  
+
     git remote add uw3 https://github.com/underworldcode/underworld3
     git pull uw3
     git checkout uw3/development
     git checkout -b newFeature
 
 ```
-     
+
 3. Make your changes! Remember to write comments, a test if applicable and follow the code style of the project<!-- (see `./docs/development/guidelines.md` for details). NB: this is on the todo list for uw3 -->
 
-4. Push your changes to your GitHub fork and then submit a PR to the `development` branch of Underworld via Github.
+4. Push your changes to your GitHub fork and then submit a PR to the `development` branch of Underworld via Github.
diff --git a/.github/workflows/build_deploy_pdoc.yml b/.github/workflows/build_deploy_pdoc.yml
@@ -8,6 +8,7 @@ on:
     branches:
       - main # Occurs on protected branch through PR
       - development
+      - Quick_Start_Docs
 
   workflow_dispatch:
 
@@ -18,7 +19,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Install Conda environment with Micromamba
-        uses: mamba-org/provision-with-micromamba@main
+        uses: mamba-org/setup-micromamba@v1
         with:
           environment-file: ./.github/workflows/envs/build_uw_docs.yml
           cache-downloads: true

diff --git a/.github/workflows/build_uw3_and_test.yml b/.github/workflows/build_uw3_and_test.yml
@@ -1,13 +1,14 @@
 name: Build and test UW3
 
-# We should trigger this from an upload event. Note that pdoc requires us to import the 
+# We should trigger this from an upload event. Note that pdoc requires us to import the
 # built code, so this is a building test as well as documentation deployment
 
 on:
-  push:      
+  push:
     branches:
-      - main 
+      - main
       - development
+      - Quick_Start_Docs
 
   pull_request:
 
@@ -39,7 +40,7 @@ jobs:
         run: |
           pip install gmsh
 
-      - name: Build UW3 
+      - name: Build UW3
         shell: bash -l {0}
         run: |
           export PETSC_DIR="/home/runner/micromamba/envs/uw3_test/lib"

diff --git a/.github/workflows/docker-image.yml b/.github/workflows/docker-image.yml
@@ -2,26 +2,24 @@ name: Docker Image CI
 
 on:
   push:
-    branches: [ "VEP-preliminary-implementation" ]
+    branches: ["development"]
 jobs:
-
   build:
-
     runs-on: ubuntu-latest
 
-    steps:    
+    steps:
       - name: Checkout repository
         uses: actions/checkout@v3
-      
+
       - name: Exact branch name
         run: echo "BRANCH=${GITHUB_REF##*/}" >> $GITHUB_ENV
-      
+
       - name: Login to DockerHub
-        uses: docker/login-action@v2 
+        uses: docker/login-action@v2
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PWORD }}
-          
+
       - name: Build and push Docker image
         uses: docker/build-push-action@v4.1.1
         with:

diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml
@@ -1,12 +1,12 @@
-name: Draft PDF
-on: 
-    push:
-        paths:
-            - joss-paper/paper.md
-            - joss-paper/paper.bib
-            # - assets/img1.png
-            # - assets/img2.png
-            - .github/workflows/draft-pdf.yml
+name: Draft PDF (JOSS)
+on:
+  push:
+    paths:
+      - joss-paper/paper.md
+      - joss-paper/paper.bib
+      # - assets/img1.png
+      # - assets/img2.png
+      - .github/workflows/draft-pdf.yml
 
 jobs:
   paper:
@@ -28,4 +28,4 @@ jobs:
           # This is the output path where Pandoc will write the compiled
           # PDF. Note, this should be the same directory as the input
           # paper.md. In the case we have (symlink), the paper is in the subdir
-          path: joss-paper/paper.pdf
+          path: joss-paper/paper.pdf
diff --git a/.github/workflows/envs/build_uw_docs.yml b/.github/workflows/envs/build_uw_docs.yml
@@ -15,4 +15,5 @@ dependencies:
   - gmsh
   - pdoc>=14
   - pip
-
+  - pip:
+      - pdoc3
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -6,7 +6,6 @@ on:
     branches:
       - main # Occurs on protected branch through PR
       - development
-      - advection_updates
 
 name: Quarto Publish
 

diff --git a/.zenodo.json b/.zenodo.json
@@ -20,9 +20,14 @@
             "orcid": "0000-0003-0817-354X",
             "affiliation": "Research School of Earth Sciences, The Australian National University",
         },
+        {
+            "name": "Matt Knepley",
+            "orcid": "0000-0002-2292-0735"
+            "affiliation": "Computer Science and Engineering, University at Buffalo",
+        },
         {
             "name": "Ben Knight",
-            "affiliation": "Monash University",
+            "affiliation": "School of Earth, Atmospheric & Environmental Science, Monash University",
             "orcid": "0000-0001-7919-2575"
         },
         {
@@ -32,7 +37,7 @@
         },
         {
             "name": "John Mansour",
-            "affiliation": "TBD",
+            "affiliation": "School of Earth, Atmospheric & Environmental Science, Monash University",
             "orcid": "0000-0001-5865-1664"
         },
         {
@@ -45,4 +50,4 @@
     "title": "Underworld3: Mathematically Self-Describing Modelling in Python for Desktop, HPC and Cloud",
     "upload_type": "software",
     "access_right": "open"
-}
+}
-Original file line number
+Diff line change
@@ Expand Up / @@ -15,4 +15,5 @@ dependencies: @@
       - gmsh
       - pdoc>=14
       - pip
+      - pip:
+          - pdoc3