diff --git a/.binder/apt.txt b/.binder/apt.txt index d94234676..ba2938060 100644 --- 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 index 8d8fe6528..ca03de1c0 100644 --- 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 index d08b453f6..c438dc502 100644 --- a/.binder/postBuild +++ b/.binder/postBuild @@ -1,6 +1,5 @@ #!/bin/bash -v - # echo # echo Install uw3_env during postBuild phase # echo @@ -15,16 +14,16 @@ 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 @@ -32,6 +31,7 @@ echo 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 \ No newline at end of file +echo diff --git a/.github/.devcontainer/uw_environment.yml b/.github/.devcontainer/uw_environment.yml index 8d8fe6528..ca03de1c0 100644 --- 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 index 4b1331594..d49979b0a 100644 --- 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 -4. Push your changes to your GitHub fork and then submit a PR to the `development` branch of Underworld via Github. \ No newline at end of file +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 index d7e842738..ae089a91b 100644 --- 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 index 7e5993682..d70797349 100644 --- 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 index 7a808d53b..f77cc8f5f 100644 --- 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 index f72a436d1..227b863bb 100644 --- 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 \ No newline at end of file + path: joss-paper/paper.pdf diff --git a/.github/workflows/envs/build_uw_docs.yml b/.github/workflows/envs/build_uw_docs.yml index 753c7dca9..03d65ad75 100644 --- 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 index 02f28c7b1..a7f9ce8dc 100644 --- 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 index 7fcefc0dd..520a81b4b 100644 --- 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" -} \ No newline at end of file +} diff --git a/CHANGES.md b/CHANGES.md index a5ec43d7d..2cc0f69a5 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,19 +1,26 @@ # CHANGES: Underworld3 +## 2024-09-01 + + - Add Notebooks for the quickstart guide (quarto backend for rendering) + - html5 embedded renders for 3D examples (low res, can be checked in) + - Update the version numbering to match 3.x.x (consistent with UW1 and UW2) + - uw expressions - updated interface + - many bug fixes including advection-diffusion (fixed severe error in parallel implementation) + ## 2024-06-15 - - Add JOSS submission information + - Add JOSS submission information - Add licence file (licensing code and documentation in line with UW1 and UW2) - Add quickstart guide (and test on binder) - Clean up repository files - - Update the version numbering to match 3.x.x (consistent with UW2) ## 2024-04-30 - uw expressions (sympy symbols that contain other expressions / functions) - use uw expressions for viscoplastic / viscoelastic constitutive models. -## 2024-01-31 +## 2024-01-31 - Introduce particle sub-steps along path to improve accuracy in advection schemes - Bug fixes associated with benchmarking @@ -38,7 +45,7 @@ ## 2023-03-29 - Swarm reading using kd-tree to speed up locations - - Swarm cycling now reverts to positions defined on the mesh and uses randomness to avoid + - Swarm cycling now reverts to positions defined on the mesh and uses randomness to avoid unexpected jamming of particles in stagnant regions - viscoplasticity seems to be doing the right thing @@ -62,7 +69,7 @@ ## 2022-09-01 - - Release 0.3.0 + - Release 0.3.0 - Quarterly tidy up ## 2021-08-12 @@ -75,48 +82,48 @@ * Added a mesh-variable proxy for swarm variables. This variable is automatically kept in sync with the swarm variable. Currently we use the SciPy - kdtree methods to map from swarm variables to - mesh variable nodes. + kdtree methods to map from swarm variables to + mesh variable nodes. -* Added the `Stateful` mixin which helps to keep - track of the state of objects. +* Added the `Stateful` mixin which helps to keep + track of the state of objects. ## 2021-03-11 * Added `MeshVariable.coord` attribute. Mesh variables - now record their vertex coordinates array directly. -* Added `parse_cmd_line_options()` routine which + now record their vertex coordinates array directly. +* Added `parse_cmd_line_options()` routine which ingests PETSc command line options. ## Release 0.0.2 [] -* Addition of `underworld3.maths.Integral` class for calculating integrals via PETSc & UW3 JIT method. +* Addition of `underworld3.maths.Integral` class for calculating integrals via PETSc & UW3 JIT method. * Rearrangement of UW3 classes to closer align with UW2. * Addition of Rayleigh-Taylor model. ## Release 0.0.1 [] -* Big rework of PETSc API usage. Now all +* Big rework of PETSc API usage. Now all systems create their own private solve PETSc variables, and all user facing variables (as encapsulated by the MeshVariable class) - are effectively Aux variables. + are effectively Aux variables. * Systems retain public versions of their solution - variables (stokes.u, stokes.p, poisson.u). These + variables (stokes.u, stokes.p, poisson.u). These are copies of the actual solution variables - (which are private). + (which are private). * All variable read access must be done within - the `mesh.access()` context manager. Write - access is achieved by supplying a list of - writeable variables (`mesh.access(stokes.u)`). - Let's have a play with this and see if it feels + the `mesh.access()` context manager. Write + access is achieved by supplying a list of + writeable variables (`mesh.access(stokes.u)`). + Let's have a play with this and see if it feels like the way forward. It is a bit cumbersome - for read access. + for read access. * Stokes velocity variable is now a vector instead of being a flat array. -* Swarm variable `project_from()` function. Not +* Swarm variable `project_from()` function. Not sure if we'll retain this one, but it's there for now. It uses a least squares approach. * Documention updates. @@ -124,9 +131,9 @@ for testing. * Model updates for interface changes. * Update lavavu/plot prototype for swarm. -* Init commit of RT example. WIP. Need to fix +* Init commit of RT example. WIP. Need to fix fix interpolation routines which currently take - 20x the solve time. + 20x the solve time. * Updates for dockerfile and setup.py. * Added `CHANGES.md` @@ -146,16 +153,16 @@ Reproduce the existing UW2 examples and extend to spherical / cylindrical - [x] Advection/diffusion (swarm) - [x] Constant viscosity convection - [x] Convection, strongly temp-dep viscosity (stagnant lid) -- [x] Non-linear viscosity convection +- [x] Non-linear viscosity convection - [ ] Quantitative Convection benchmarks (various geometries) -- [ ] Viscoelasticity (linear) benchmarks +- [ ] Viscoelasticity (linear) benchmarks - [x] Inertial terms (Navier-Stokes benchmarks) - [x] Anisotropic viscosity ## Repository milestones - - [x] pip install - - [ ] conda install + - [x] pip install + - [ ] conda install - [x] auto-formatting (e.g. black) - [x] pytest setup - [ ] pytest full-coverage @@ -184,17 +191,17 @@ Outcomes of Dec 22 Canberra Catch up [[T](https://github.com/underworldcode/underworld3/blob/master/src/ex1.c#L174)] Topology & Meshing -- [x] spherical, annulus +- [x] spherical, annulus - [x] Cartesian - [x] Different element types (at least Linear / Quadratic & Hex, Tet) - [ ] Sandbox-style deforming mesh - - [ ] Sandbox-style deforming mesh *with particles* + - [ ] Sandbox-style deforming mesh *with particles* - [ ] Remeshing examples / adaptivity - [ ] Earth topography / plate boundary adapted mesh -[[D](https://github.com/underworldcode/underworld3/blob/master/src/ex1.c#L268)] Disc +[[D](https://github.com/underworldcode/underworld3/blob/master/src/ex1.c#L268)] Disc -- [x] Cont Galerkin +- [x] Cont Galerkin - [ ] ~Disc Galerkin~ - [x] Semi-lagrangian - [x] Free-slip BC on surface @@ -224,7 +231,7 @@ Outcomes of Dec 22 Canberra Catch up PIC for composition -- [x] Viscosity, buoyancy, ... +- [x] Viscosity, buoyancy, ... - [x] Nearest neighbour (k-d tree ? 🌳 ) - [ ] ~2D - L2 projection into FEM space (Petsc shall provide)~ - [ ] ~3D - L2 projection into FEM space (Petsc shall provide but not in 3D)~ @@ -239,7 +246,7 @@ PIC for composition [[V](https://github.com/underworldcode/underworld3/blob/master/src/ex1.c#L35)] Exact solutions - [ ] MMS -- [ ] Analytical +- [ ] Analytical - https://www.solid-earth-discuss.net/se-2017-71/se-2017-71.pdf -https://www.researchgate.net/publication/304784132_Benchmark_solutions_for_Stokes_flows_in_cylindrical_and_spherical_geometry diff --git a/LICENCE.md b/LICENCE.md index dfe4bee7d..7a83ba969 100644 --- a/LICENCE.md +++ b/LICENCE.md @@ -1,12 +1,11 @@ ### Summary Underworld is an open-source, parallel, particle-in-cell, finite element geodynamics code. Please refer to repository -top level `README.md` for further information. +top level `README.md` for further information. ### Licensing -1) All Underworld source code is released under the LGPL-3 (See 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. +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. 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. @@ -32,7 +31,3 @@ Copyright VPAC, 2003-2009 1. Beucher, R., Moresi, L., Giordani, J., Mansour, J., Sandiford, D., Farrington, R., et al. (2019). UWGeodynamics: A teaching and research tool for numerical geodynamic modelling. Journal of Open Source Software. https://doi.org/10.21105/joss.01136 1. Mansour, J., Giordani, J., Moresi, L., Beucher, R., Kaluza, O., Velic, M., et al. (2020). Underworld2: Python Geodynamics Modelling for Desktop, HPC and Cloud. Journal of Open Source Software, 5(47), 1797. https://doi.org/10.21105/joss.01797 - - - - diff --git a/build_api_docs.sh b/build_api_docs.sh index 0e4e7c618..82242aa87 100755 --- a/build_api_docs.sh +++ b/build_api_docs.sh @@ -5,5 +5,5 @@ export LOGO="https://github.com/underworldcode/underworld3/blob/main/Jupyterbook # echo "PYTHON: " `which python3` # echo "PDOC: " `which pdoc` -pdoc --math --mermaid -o uw3_api_docs -d markdown --logo $LOGO src/underworld3 # --force - +# pdoc --math --mermaid -o uw3_api_docs -d markdown --logo $LOGO src/underworld3 # --force +pdoc3 -o uw3_api_docs --config "latex_math=True" src/underworld3 --html --force diff --git a/environment.yml b/environment.yml new file mode 120000 index 000000000..01cf7601a --- /dev/null +++ b/environment.yml @@ -0,0 +1 @@ +.binder/environment.yml \ No newline at end of file diff --git a/joss-paper/JOSS_Checklist.md b/joss-paper/JOSS_Checklist.md index e89164896..c3a1d950e 100644 --- a/joss-paper/JOSS_Checklist.md +++ b/joss-paper/JOSS_Checklist.md @@ -4,6 +4,11 @@ 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 + - [ ] paper.md - [ ] paper.bib - [x] Install GitHub workflow @@ -11,6 +16,14 @@ Following the [Submission requirements](https://joss.readthedocs.io/en/latest/su - [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 authors and .zenodo creators align + + - [ ] Quickstart Guide for users (deployable on binder) + - [x] Installation details + - [ ] Notebook examples (ipynb) + - [ ] Links to API docs + - [ ] Links to Github + - [ ] Links to Underworld Community ## Clean up checklist @@ -23,13 +36,11 @@ Following the [Submission requirements](https://joss.readthedocs.io/en/latest/su ## Software checklist Can I submit ? - - [x] The software must have an obvious research application. - [x] You must be a major contributor to the software you are submitting, and have a GitHub account to participate in the review process. - [x] Your paper must not focus on new research results accomplished with the software. The software associated with your submission must: - - [x] Be stored in a repository that can be cloned without registration. - [x] Be stored in a repository that is browsable online without registration. - [x] Have an issue tracker that is readable without registration. diff --git a/joss-paper/paper.md b/joss-paper/paper.md index 559479b39..8d16890a9 100644 --- a/joss-paper/paper.md +++ b/joss-paper/paper.md @@ -14,11 +14,9 @@ authors: corresponding: true # (This is how to denote the corresponding author) affiliation: "1" # (Multiple affiliations must be quoted) - name: John Mansour - equal-contrib: true orcid: 0000-0001-5865-1664 affiliation: "2" - name: Julian Giordani - equal-contrib: true orcid: 0000-0003-4515-9296 affiliation: "3" - name: Matt Knepley @@ -120,6 +118,12 @@ contains material / time derivatives of the unknowns which are not present in th # Discussion +Aim to provide strong support to users to develop sophisticated mathematical models and to be able to interrogate those models during development and at run-time. + +Seemless parallelism + +Resuable documentation that is accessible in rich-text format in jupyter notebooks for model development and analysis but is also incorporated into the API documentation in the same rich format. +