Joss submission

.github/workflows/draft-pdf.yml

@@ -22,7 +22,7 @@ jobs:
           # This should be the path to the paper within your repo.
           paper-path: docs/joss-paper/paper.md
       - name: Upload
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled

.zenodo.json

@@ -10,6 +10,16 @@
             "affiliation": "School of Earth Science, The University of Sydney",
             "orcid": "0000-0003-4515-9296"
         },
+        {
+            "name": "Matt Knepley",
+            "orcid": "0000-0002-2292-0735",
+            "affiliation": "Computer Science and Engineering, University at Buffalo",
+        },
+        {
+            "name": "Romain Beucher",
+            "affiliation": "Research School of Earth Sciences, The Australian National University",
+            "orcid": "0000-0003-3891-5444"
+        },
         {
             "name": "Thyagarajulu Gollapalli",
             "orcid": "0000-0001-9394-4104",
@@ -20,11 +30,6 @@
             "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": "School of Earth, Atmospheric & Environmental Science, Monash University",

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+This page provides information about contributing to Underworld3's (aka Underworld’s) codebase.
+
+For contributions of Underworld models or workflows, please see https://github.com/underworld-community
+
+----
+
+We welcome contributions to Underworld’s codebase in the form of:
+
+  * Code changes.
+  * Bug reports.
+  * Suggestions / Requests.
+  * Documentation modifications.
+
+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.
+
+[Click here](https://github.com/underworldcode/underworld3/issues) to submit an Issue.
+
+For Code / Documentation changes please submit a GitHub Pull Request (PR). This allows us to review and discuss the contributions before merging it into our ``development`` branch. For creating Pull Request (PR) we recommend following the workflow outlined on [GitHub]( https://guides.github.com/activities/forking).
+
+More specifically:
+
+  1. Fork Underworld via GitHub and clone it to your machine.
+
+    ```bash
+        git clone https://github.com/YOUR_GITHUB_ACCOUNT/underworld3
+    ```
+
+  2. Add the original Underworld repository as an additional remote source (named `upsteam`) for your local repo and pull down its latest changesets. Checkout to the upstream/development repo state, and then create a new local branch which will contain your forthcoming changes.
+
+    ```bash
+        git remote add upstream https://github.com/underworldcode/underworld3
+        git pull upstream
+        git checkout upstream/development
+        git checkout -b newFeature
+    ```
+
+  3. Make your changes! Remember to write comments, write a test if applicable and follow the [coding style](/docs/developer/CodingStyle.md) of the project for details).
+
+  4. Push your changes to your GitHub fork and then submit a PR to the ``development`` branch of Underworld via Github.

LICENCE.md

@@ -5,7 +5,7 @@ top level `README.md` for further information.
 
 ### Licensing
 
-1) All Underworld source code is released under the LGPL-3 (See the file LICENCE in his repository). This covers all files in `underworld` constituting the Underworld3 Python module (library), and any other material not explicitly identified under (2) below.
+1) All Underworld source code is released under the LGPL-3 (See the file LGPLv3.txt in this repository). This covers all files in `underworld` constituting the Underworld3 Python module (library), and any other material not explicitly identified under (2) below.
 
 2) Notebooks, stand-alone documentation and Python scripts which show how the code is used and run are licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.  We offer this licence to encourage you to modify and share the examples and use them to help you in your research. Where no individual creator is identified in these files, the appropriate attribution is "The Underworld Team". All the files covered by this license are found in the `UserGuide` directory.
 

README.md

@@ -8,8 +8,7 @@ Welcome to `Underworld3`, a mathematically self-describing, finite-element code
 
 All `Underworld3` source code is released under the LGPL-3 open source licence. This covers all files in `underworld3` constituting the Underworld3 Python module. Notebooks, stand-alone documentation and Python scripts which show how the code is used and run are licensed under the Creative Commons Attribution 4.0 International License.
 
-HTML: <a href="https://joss.theoj.org/papers/4f7a1ed76bde560968c246fa8eff778d"><img src="https://joss.theoj.org/papers/4f7a1ed76bde560968c246fa8eff778d/status.svg"></a>
-Markdown: [![status](https://joss.theoj.org/papers/4f7a1ed76bde560968c246fa8eff778d/status.svg)](https://joss.theoj.org/papers/4f7a1ed76bde560968c246fa8eff778d)
+[![Build and test UW3](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml/badge.svg?branch=main)](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml)
 
 ## Documentation
 
@@ -19,6 +18,8 @@ The `underworld3` module (API) documentation can be found online:
   - [stable version](https://underworldcode.github.io/underworld3/main_api/underworld3/index.html)
   - [development version](https://underworldcode.github.io/underworld3/development_api/underworld3/index.html)
 
+
+
 ## Binder demonstration version
 
  - [Main Branch on Binder](https://mybinder.org/v2/gh/underworld-community/uw3-demo-launcher/HEAD?labpath=underworld3%2Fdocs%2Fuser%2FNotebooks%2FNotebook_Index.ipynb)

docs/developer/CodingStyle.md

@@ -18,11 +18,11 @@ def rank2_to_voigt(
     r"""Convert rank 2 tensor ($v_{ij}$) to Voigt (vector) form ($V_I$)"""
 ```
 
-We do not enforce this formatting at the `git commit` level, but it is strongly encouraged that you set up your code editor to adopt the `black` style. 
+We do not enforce this formatting at the `git commit` level, but it is strongly encouraged that you set up your code editor to adopt the `black` style.
 
 ## Variable / function names
 
-Underworld3 leans heavily on the `petsc4py` and `sympy` packages. `petsc4py` wraps the `C` / `Fortran` layers of the `PETSc` ecosystem and tends to inherit CamelCase/camelCase variable naming everywhere whereas `sympy`, like other python packages, *favours* snake_case for variables and CamelCase for classes. 
+Underworld3 leans heavily on the `petsc4py` and `sympy` packages. `petsc4py` wraps the `C` / `Fortran` layers of the `PETSc` ecosystem and tends to inherit CamelCase/camelCase variable naming everywhere whereas `sympy`, like other python packages, *favours* snake_case for variables and CamelCase for classes.
 
 In Underworld3, we prefer to use snake_case naming for functions, properties and variables, camelCase for classes. We also know that we are not completely consistent at present. Sorry !
 
@@ -34,17 +34,17 @@ We use `typing` for this.
 
 ## Cython considerations
 
-Many `underworld3` objects carry underlying `C` objects that they manage and there is usually some `cython` code that handles the interaction between the two. We use `cython` explicitly for some of this wrapper code and it is present implictly because we make heavy use of the `petsc4py` module. 
+Many `underworld3` objects carry underlying `C` objects that they manage and there is usually some `cython` code that handles the interaction between the two. We use `cython` explicitly for some of this wrapper code and it is present implictly because we make heavy use of the `petsc4py` module.
 
 `cython` objects may require explicit deletion (because python cannot always drill down to the `C` layer to find objects that are ready for automatic deletion). We strongly encourage the use of the `destroy()` method that is available for many `petsc4py` objects when you are sure the object is no longer required by you. Be aware that lists of pointers to `PETSc` objects may prevent them being automatically deleted and use the `weakref` module to avoid this problem.
 
 Where possible, keep pure python functions in separate source files from `cython` functions as this improves our ability to run the `pdoc` automatic documentation correctly. Generally speaking, the `cython` level of the API is the furthest from the end-user and the least likely to need continual updating. Let's work to keep this code concise, precise, and rarely changed.
 
 ## API-level Documentation
 
-The best way to develop `Underworld3` python programs is within the [`jupyter`](jupyter.org) notebook environment. The documentation of the `Underworld3` API assumes that rendered markdown formatting will be available for code highlighting and mathematical equations when the user asks (interactively) for help. 
+The best way to develop `Underworld3` python programs is within the [`jupyter`](jupyter.org) notebook environment. The documentation of the `Underworld3` API assumes that rendered markdown formatting will be available for code highlighting and mathematical equations when the user asks (interactively) for help.
 
-We use `pdoc` to produce API documentation from the python source code. The `pdoc` configuration assumes all docstrings are markdown and may include mathematics and code snippets. `pdoc` automatically documents arguments to functions and classes, so we do not require these to be described unless there is a need for clarification. 
+We use `pdoc` to produce API documentation from the python source code. The `pdoc` configuration assumes all docstrings are markdown and may include mathematics and code snippets. `pdoc` automatically documents arguments to functions and classes, so we do not require these to be described unless there is a need for clarification.
 
 In the `jupyter` environment `Underworld3` objects display `help` documentation and their internal state through their `self.view()` methods. Many classes have equivalent documentation available before they have been instantiated so a notebook user can progressively construct a model.
 
@@ -65,7 +65,7 @@ once the following criteria are met:
    3. All tests pass
    4. Blog post update for significant changes
    5. Update CHANGES.md
-   
+
 ## Version Numbering
 
 Underworld follows PEP440 for versioning:
@@ -86,20 +86,19 @@ Z = Micro/Patch version. Backwards compatible bug fixes.
 The version number may also be appended with pre-release type designations, for
 example 3.0.0b.
 
-Development software will be have the 'dev' suffix, e.g. 3.0.0-dev, and should 
+Development software will be have the 'dev' suffix, e.g. 3.0.0-dev, and should
 represent the version the development is working towards, so 3.1.0-dev is working
-towards release 3.1.0. 
+towards release 3.1.0.
 
 ## Testing
 
-The 'test.sh' script  can be used to execute the pytest framework. 
+The 'test.sh' script  can be used to execute the pytest framework.
 Individual tests are found in the `tests` directory. These are small collections
-of unit tests that address parcels of functionality in the code. Tests need to be 
-small and fast, and should be orthogonal to other tests as far as possible. 
+of unit tests that address parcels of functionality in the code. Tests need to be
+small and fast, and should be orthogonal to other tests as far as possible.
 In the testing framework, we test the deeper levels of the code first (e.g. mesh building)
 so that we can use those features for subsequent tests.
 
-We strongly encourage testing to be fine grained with as little as possible additional code that
-can go wrong. Please do not just paste in your example notebooks in the hope that `pytest` will 
-sort things out. It won't. Somebody else will need to figure out why the test broke sometime in the
-future and we don't want that somebody to discover that the problem is not in the unit testing part of the code.
+We strongly encourage testing to be fine grained with as little as possible additional code that can go wrong. Please do not just paste in your example notebooks in the hope that `pytest` will sort things out. It won't. Somebody else will need to figure out why the test broke sometime in the future and we don't want that somebody to discover that the problem is not in the unit testing part of the code.
+
+Although `pytest` tests should be independent, there are some issues with the PETSc subsystem removing objects correctly at the end of a test. This is why we break up the testing suite into multiple files which rebuild the PETSc layer each time.

docs/joss-paper/JOSS_Checklist.md

@@ -5,33 +5,33 @@ Following the [Submission requirements](https://joss.readthedocs.io/en/latest/su
 ## Repository format / content
 
     - [ ] README.md
-      - [ ] Links to uw web page
-      - [ ] Binder launch link for Quick-start
-      - [ ] Acknowledgements
+      - [x] Links to uw web page
+      - [x] Binder launch link for Quick-start
+      - [x] Acknowledgements
 
-    - [ ] paper.md
-    - [ ] paper.bib
+    - [x] paper.md
+    - [x] paper.bib
     - [x] Install GitHub workflow
     - [x] Validate workflow
     - [x] Open source licence file
     - [?] Publication branch (this is acceptable, must be kept up to date on submission).
-    - [ ] Check Insights / Community Standards for GitHub repo / put into line with UW2
+    - [x] Check Insights / Community Standards for GitHub repo / put into line with UW2
     - [x] Check authors and .zenodo creators align
 
-    - [ ] Quickstart Guide for users (deployable on binder)
+    - [x] Quickstart Guide for users (deployable on binder)
       - [x] Installation details
-      - [ ] Notebook examples (ipynb)
-      - [ ] Links to API docs
-      - [ ] Links to Github
-      - [ ] Links to Underworld Community
+      - [x] Notebook examples (ipynb)
+      - [x] Links to API docs
+      - [x] Links to Github
+      - [x] Links to Underworld Community
 
 ## Clean up checklist
 
-    - [ ] Audit GitHub issues / clear where possible
-    - [ ] Clear outdated PRs
-    - [ ] Merge dev into main
-        - [ ] create joss-submission branch from main at submission time
-        - [ ] joss-submission branch may need restructuring in order to build (e.g. paper in the root directory)
+    - [x] Audit GitHub issues / clear where possible
+    - [x] Clear outdated PRs
+    - [x] Merge dev into main
+        - [x] create joss-submission branch from main at submission time
+        - [x] joss-submission branch may need restructuring in order to build (e.g. paper in the root directory)
 
 ## Software checklist