diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml index 3a735ccd7..dc0164501 100644 --- a/.github/workflows/draft-pdf.yml +++ b/.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 diff --git a/.zenodo.json b/.zenodo.json index 4a1de1057..c319cf7ea 100644 --- a/.zenodo.json +++ b/.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", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..095da2cd1 --- /dev/null +++ b/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. diff --git a/LICENCE.md b/LICENCE.md index 7a83ba969..dc475cb1e 100644 --- a/LICENCE.md +++ b/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. diff --git a/README.md b/README.md index 88f43fbd3..f4f939a86 100644 --- a/README.md +++ b/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: -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) diff --git a/docs/developer/CodingStyle.md b/docs/developer/CodingStyle.md index f62d1f5bb..2aa443eec 100644 --- a/docs/developer/CodingStyle.md +++ b/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,7 +34,7 @@ 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. @@ -42,9 +42,9 @@ Where possible, keep pure python functions in separate source files from `cython ## 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. diff --git a/docs/joss-paper/JOSS_Checklist.md b/docs/joss-paper/JOSS_Checklist.md index c3a1d950e..4391b0709 100644 --- a/docs/joss-paper/JOSS_Checklist.md +++ b/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 diff --git a/docs/joss-paper/paper.bib b/docs/joss-paper/paper.bib index fa73546f1..ae44ba211 100644 --- a/docs/joss-paper/paper.bib +++ b/docs/joss-paper/paper.bib @@ -1,4 +1,4 @@ -@techreport{balay.etal.PETSc.2024, +@techreport{balayPETScTAOUsers2024, title = {{{PETSc}}/{{TAO Users Manual V}}.3.21}, author = {Balay, S. and Abhyankar, S. and Adams, M. and Benson, S. and Brown, J. and Brune, P. and Buschelman, K. and Constantinescu, E. and Dalcin, L. and Dener, A. and Eijkhout, V. and Faibussowitsch, J. and Gropp, W. and Hapla, V. and Isaac, T. and Jolivet, P. and Karpeev, D. and Kaushik, D. and Knepley, M. and Kong, F. and Kruger, S. and May, D. and McInnes, L. and Mills, R. and Mitchell, L. and Munson, T. and Roman, J. and Rupp, K. and Sanan, P. and Sarich, J. and Smith, B. and Zampini, S. and Zhang, H. and Zhang, H. and Zhang, J.}, year = {2024}, @@ -10,6 +10,22 @@ @techreport{balay.etal.PETSc.2024 file = {/Users/lmoresi/Zotero/storage/FTX49W6P/Balay et al. - 2024 - PETScTAO Users Manual V.3.21.pdf} } +@incollection{batheFiniteElementMethod2008, + title = {Finite {{Element Method}}}, + booktitle = {Wiley {{Encyclopedia}} of {{Computer Science}} and {{Engineering}}}, + author = {Bathe, Klaus-J{\dbend}{\dbend}rgen}, + editor = {Wah, Benjamin W.}, + year = {2008}, + month = jun, + pages = {ecse159}, + publisher = {John Wiley \& Sons, Inc.}, + address = {Hoboken, NJ, USA}, + doi = {10.1002/9780470050118.ecse159}, + urldate = {2022-04-27}, + isbn = {978-0-470-05011-8}, + langid = {english} +} + @article{behnel2011cython, title = {Cython: {{The}} Best of Both Worlds}, author = {Behnel, Stefan and Bradshaw, Robert and Citro, Craig and Dalcin, Lisandro and Seljebotn, Dag Sverre and Smith, Kurt}, @@ -18,11 +34,11 @@ @article{behnel2011cython volume = {13}, number = {2}, pages = {31--39}, - doi = {10.1109/MCSE.2010.118}, - publisher = {IEEE} + publisher = {IEEE}, + doi = {10.1109/mcse.2010.118} } -@article{beucher.etal.UWGeodynamics.2019, +@article{beucherUWGeodynamicsTeachingResearch2019, title = {{{UWGeodynamics}}: {{A}} Teaching and Research Tool for Numerical Geodynamic Modelling}, shorttitle = {{{UWGeodynamics}}}, author = {Beucher, Romain and Moresi, Louis and Giordani, Julian and Mansour, John and Sandiford, Dan and Farrington, Rebecca and Mondy, Luke and Mallard, Claire and Rey, Patrice and Duclaux, Guillaume and Kaluza, Owen and Laik, Arijit and Mor{\'o}n, Sara}, @@ -39,6 +55,38 @@ @article{beucher.etal.UWGeodynamics.2019 file = {/Users/lmoresi/Zotero/storage/G5UVAHXM/Beucher et al. - 2019 - UWGeodynamics A teaching and research tool for nu.pdf} } +@misc{boriskausLaMEM2024, + title = {{{LaMEM}}}, + shorttitle = {{{UniMainzGeo}}/{{LaMEM}}}, + author = {Boris Kaus and Anton Popov and Garrett\_Ito and Arne Spang and {greuber} and Iskander Ibragimov and {xinxinwang01} and {thomasAmorrow} and Adina Pusok and APiccolo89 and ChristianSchuler and Patrick Sanan and {sasbrune} and YangJianfeng2015 and Arthur Bauville and {birand-zz}}, + year = {2024}, + month = feb, + doi = {10.5281/ZENODO.10718860}, + urldate = {2025-04-17}, + abstract = {What's Changed PhaseTransitions - fix for problems with phase==0 by @boriskaus in https://github.com/UniMainzGeo/LaMEM/pull/15 Bugfix upon restart by @APiccolo89 in https://github.com/UniMainzGeo/LaMEM/pull/16 Plasticity regularisation by @boriskaus in https://github.com/UniMainzGeo/LaMEM/pull/17 New Contributors @APiccolo89 made their first contribution in https://github.com/UniMainzGeo/LaMEM/pull/16 Full Changelog: https://github.com/UniMainzGeo/LaMEM/compare/2.1.3...v2.1.4}, + copyright = {Creative Commons Attribution 4.0 International}, + howpublished = {Zenodo} +} + +@article{dabrowskiMILAMINMATLABbasedFinite2008, + title = {{{MILAMIN}}: {{MATLAB}}-based Finite Element Method Solver for Large Problems}, + shorttitle = {{{MILAMIN}}}, + author = {Dabrowski, M. and Krotkiewski, M. and Schmid, D. W.}, + year = {2008}, + month = apr, + journal = {Geochem Geophys Geosyst}, + volume = {9}, + number = {4}, + pages = {2007GC001719}, + issn = {1525-2027, 1525-2027}, + doi = {10.1029/2007GC001719}, + urldate = {2025-04-17}, + abstract = {The finite element method (FEM) combined with unstructured meshes forms an elegant and versatile approach capable of dealing with the complexities of problems in Earth science. Practical applications often require high-resolution models that necessitate advanced computational strategies. We therefore developed ``Million a Minute'' (MILAMIN), an efficient MATLAB implementation of FEM that is capable of setting up, solving, and postprocessing two-dimensional problems with one million unknowns in one minute on a modern desktop computer. MILAMIN allows the user to achieve numerical resolutions that are necessary to resolve the heterogeneous nature of geological materials. In this paper we provide the technical knowledge required to develop such models without the need to buy a commercial FEM package, programming compiler-language code, or hiring a computer specialist. It has been our special aim that all the components of MILAMIN perform efficiently, individually and as a package. While some of the components rely on readily available routines, we develop others from scratch and make sure that all of them work together efficiently. One of the main technical focuses of this paper is the optimization of the global matrix computations. The performance bottlenecks of the standard FEM algorithm are analyzed. An alternative approach is developed that sustains high performance for any system size. Applied optimizations eliminate Basic Linear Algebra Subprograms (BLAS) drawbacks when multiplying small matrices, reduce operation count and memory requirements when dealing with symmetric matrices, and increase data transfer efficiency by maximizing cache reuse. Applying loop interchange allows us to use BLAS on large matrices. In order to avoid unnecessary data transfers between RAM and CPU cache we introduce loop blocking. The optimization techniques are useful in many areas as demonstrated with our MILAMIN applications for thermal and incompressible flow (Stokes) problems. We use these to provide performance comparisons to other open source as well as commercial packages and find that MILAMIN is among the best performing solutions, in terms of both speed and memory usage. The corresponding MATLAB source code for the entire MILAMIN, including input generation, FEM solver, and postprocessing, is available from the authors ( http://www.milamin.org ) and can be downloaded as auxiliary material.}, + copyright = {http://onlinelibrary.wiley.com/termsAndConditions\#vor}, + langid = {english}, + file = {/Users/lmoresi/Zotero/storage/2L6VENKN/Dabrowski et al. - 2008 - MILAMIN MATLAB‐based finite element method solver for large problems.pdf} +} + @article{dalcinpazklercosimo2011, title = {Parallel Distributed Computing Using {{Python}}}, author = {Dalcin, Lisandro D. and Paz, Rodrigo R. and Kler, Pablo A. and Cosimo, Alejandro}, @@ -51,13 +99,49 @@ @article{dalcinpazklercosimo2011 doi = {10.1016/j.advwatres.2011.04.013} } -@article{granger.perez.Jupyter.2021, +@article{daviesAutomaticFiniteelementMethods2022, + title = {Towards Automatic Finite-Element Methods for Geodynamics via {{Firedrake}}}, + author = {Davies, D. Rhodri and Kramer, Stephan C. and Ghelichkhan, Sia and Gibson, Angus}, + year = {2022}, + month = jul, + journal = {Geosci. Model Dev.}, + volume = {15}, + number = {13}, + pages = {5127--5166}, + issn = {1991-9603}, + doi = {10.5194/gmd-15-5127-2022}, + urldate = {2025-04-17}, + abstract = {Abstract. Firedrake is an automated system for solving partial differential equations using the finite-element method. By applying sophisticated performance optimisations through automatic code-generation techniques, it provides a means of creating accurate, efficient, flexible, easily extensible, scalable, transparent and reproducible research software that is ideally suited to simulating a wide range of problems in geophysical fluid dynamics. Here, we demonstrate the applicability of Firedrake for geodynamical simulation, with a focus on mantle dynamics. The accuracy and efficiency of the approach are confirmed via comparisons against a suite of analytical and benchmark cases of systematically increasing complexity, whilst parallel scalability is demonstrated up to 12\,288 compute cores, where the problem size and the number of processing cores are simultaneously increased. In addition, Firedrake's flexibility is highlighted via straightforward application to different physical (e.g. complex non-linear rheologies, compressibility) and geometrical (2-D and 3-D Cartesian and spherical domains) scenarios. Finally, a representative simulation of global mantle convection is examined, which incorporates 230\,Myr of plate motion history as a kinematic surface boundary condition, confirming Firedrake's suitability for addressing research problems at the frontiers of global mantle dynamics research.}, + copyright = {https://creativecommons.org/licenses/by/4.0/}, + langid = {english}, + file = {/Users/lmoresi/Zotero/storage/NYDXUW75/Davies et al. - 2022 - Towards automatic finite-element methods for geodynamics via Firedrake.pdf} +} + +@article{daviesFluidityFullyUnstructured2011a, + title = {Fluidity: {{A}} Fully Unstructured Anisotropic Adaptive Mesh Computational Modeling Framework for Geodynamics: {{FLUIDITY-MODELING GEODYNAMICAL FLOWS}}}, + shorttitle = {Fluidity}, + author = {Davies, D. Rhodri and Wilson, Cian R. and Kramer, Stephan C.}, + year = {2011}, + month = jun, + journal = {Geochem. Geophys. Geosyst.}, + volume = {12}, + number = {6}, + pages = {n/a-n/a}, + issn = {15252027}, + doi = {10.1029/2011GC003551}, + urldate = {2025-04-17}, + copyright = {http://doi.wiley.com/10.1002/tdm\_license\_1.1}, + langid = {english}, + file = {/Users/lmoresi/Zotero/storage/7CUESFPV/Davies et al. - 2011 - Fluidity A fully unstructured anisotropic adaptive mesh computational modeling framework for geodyn.pdf} +} + +@article{grangerJupyterThinkingStorytelling2021, title = {Jupyter: {{Thinking}} and {{Storytelling With Code}} and {{Data}}}, shorttitle = {Jupyter}, author = {Granger, Brian E. and Perez, Fernando}, year = {2021}, month = mar, - journal = {Computing in Science \& Engineering}, + journal = {Comput. Sci. Eng.}, volume = {23}, number = {2}, pages = {7--14}, @@ -68,7 +152,37 @@ @article{granger.perez.Jupyter.2021 file = {/Users/lmoresi/Zotero/storage/HB3LE5Q2/Granger and Perez - 2021 - Jupyter Thinking and Storytelling With Code and D.pdf} } -@article{knepley.etal.Achieving.2013, +@article{heisterHighAccuracyMantle2017, + title = {High Accuracy Mantle Convection Simulation through Modern Numerical Methods -- {{II}}: Realistic Models and Problems}, + shorttitle = {High Accuracy Mantle Convection Simulation through Modern Numerical Methods -- {{II}}}, + author = {Heister, Timo and Dannberg, Juliane and Gassm{\"o}ller, Rene and Bangerth, Wolfgang}, + year = {2017}, + month = aug, + journal = {Geophysical Journal International}, + volume = {210}, + number = {2}, + pages = {833--851}, + issn = {0956-540X, 1365-246X}, + doi = {10.1093/gji/ggx195}, + urldate = {2025-04-16}, + langid = {english}, + file = {/Users/lmoresi/Zotero/storage/VZUZJ736/Heister et al. - 2017 - High accuracy mantle convection simulation through modern numerical methods – II realistic models a.pdf} +} + +@book{hughesFiniteElementMethod1987, + title = {The Finite Element Method: Linear Static and Dynamic Finite Element Analysis}, + shorttitle = {The Finite Element Method}, + author = {Hughes, Thomas J. R.}, + year = {1987}, + edition = {1. Dr.}, + publisher = {Prentice Hall}, + address = {Englewood Cliffs, N.J.}, + doi = {10.1016/0045-7825(87)90013-2}, + isbn = {978-0-13-317017-7 978-0-13-317025-2}, + langid = {english} +} + +@article{knepleyAchievingHighPerformance2013, title = {Achieving {{High Performance}} with {{Unified Residual Evaluation}}}, author = {Knepley, Matthew G. and Brown, Jed and Rupp, Karl and Smith, Barry F.}, year = {2013}, @@ -85,13 +199,29 @@ @article{knepley.etal.Achieving.2013 file = {/Users/lmoresi/Zotero/storage/7H2PC7HT/Knepley et al. - 2013 - Achieving High Performance with Unified Residual E.pdf} } -@article{mansour.etal.Underworld2.2020, +@book{loggAutomatedSolutionDifferential2012, + title = {Automated {{Solution}} of {{Differential Equations}} by the {{Finite Element Method}}: {{The FEniCS Book}}}, + shorttitle = {Automated {{Solution}} of {{Differential Equations}} by the {{Finite Element Method}}}, + editor = {Logg, Anders and Mardal, Kent-Andre and Wells, Garth}, + year = {2012}, + series = {Lecture {{Notes}} in {{Computational Science}} and {{Engineering}}}, + volume = {84}, + publisher = {Springer Berlin Heidelberg}, + address = {Berlin, Heidelberg}, + doi = {10.1007/978-3-642-23099-8}, + urldate = {2025-04-16}, + copyright = {https://www.springernature.com/gp/researchers/text-and-data-mining}, + isbn = {978-3-642-23098-1 978-3-642-23099-8}, + langid = {english} +} + +@article{mansourUnderworld2PythonGeodynamics2020, title = {Underworld2: {{Python Geodynamics Modelling}} for {{Desktop}}, {{HPC}} and {{Cloud}}}, shorttitle = {Underworld2}, author = {Mansour, John and Giordani, Julian and Moresi, Louis and Beucher, Romain and Kaluza, Owen and Velic, Mirko and Farrington, Rebecca and Quenette, Steve and Beall, Adam}, year = {2020}, month = mar, - journal = {Journal of Open Source Software}, + journal = {JOSS}, volume = {5}, number = {47}, pages = {1797}, @@ -104,7 +234,7 @@ @article{mansour.etal.Underworld2.2020 file = {/Users/lmoresi/Zotero/storage/K3FPTFCQ/Mansour et al. - 2020 - Underworld2 Python Geodynamics Modelling for Desk.pdf} } -@article{meurer.etal.SymPy.2017, +@article{meurerSymPySymbolicComputing2017, title = {{{SymPy}}: Symbolic Computing in {{Python}}}, shorttitle = {{{SymPy}}}, author = {Meurer, Aaron and Smith, Christopher P. and Paprocki, Mateusz and {\v C}ert{\'i}k, Ond{\v r}ej and Kirpichev, Sergey B. and Rocklin, Matthew and Kumar, {\relax Am}iT and Ivanov, Sergiu and Moore, Jason K. and Singh, Sartaj and Rathnayake, Thilina and Vig, Sean and Granger, Brian E. and Muller, Richard P. and Bonazzi, Francesco and Gupta, Harsh and Vats, Shivam and Johansson, Fredrik and Pedregosa, Fabian and Curry, Matthew J. and Terrel, Andy R. and Rou{\v c}ka, {\v S}t{\v e}p{\'a}n and Saboo, Ashutosh and Fernando, Isuru and Kulal, Sumith and Cimrman, Robert and Scopatz, Anthony}, @@ -122,7 +252,23 @@ @article{meurer.etal.SymPy.2017 file = {/Users/lmoresi/Zotero/storage/SEV8M2E6/Meurer et al. - 2017 - SymPy symbolic computing in Python.pdf} } -@article{moresi.etal.Computational.2007, +@incollection{moresiChapter23Literate2023, + title = {Chapter 23 - {{Literate}}, {{Reusable}}, {{Geodynamic Modeling}}}, + booktitle = {Dynamics of {{Plate Tectonics}} and {{Mantle Convection}}}, + author = {Moresi, Louis}, + editor = {Duarte, Jo{\~a}o C.}, + year = {2023}, + month = jan, + pages = {573--582}, + publisher = {Elsevier}, + doi = {10.1016/B978-0-323-85733-8.00010-X}, + copyright = {All rights reserved}, + isbn = {978-0-323-85733-8}, + keywords = {Finite element models,Geodynamics,Literate computing,Reproducible research,Symbolic algebra}, + file = {/Users/lmoresi/Zotero/storage/2KKSG2LD/Moresi - 2023 - Chapter 23 - Literate, Reusable, Geodynamic Modeli.pdf} +} + +@article{moresiComputationalApproachesStudying2007, title = {Computational Approaches to Studying Non-Linear Dynamics of the Crust and Mantle}, author = {Moresi, L. and Quenette, S. and Lemiale, V. and M{\'e}riaux, C. and Appelbe, B. and M{\"u}hlhaus, H. -B.}, year = {2007}, @@ -143,7 +289,7 @@ @article{moresi.etal.Computational.2007 file = {/Users/lmoresi/Zotero/storage/WVUEQZMD/Moresi et al. - 2007 - Computational approaches to studying non-linear dy.pdf} } -@article{moresi.etal.Lagrangian.2003, +@article{moresiLagrangianIntegrationPoint2003, title = {A {{Lagrangian}} Integration Point Finite Element Method for Large Deformation Modeling of Viscoelastic Geomaterials}, author = {Moresi, L. and Dufour, F. and M{\"u}hlhaus, H.-B.}, year = {2003}, @@ -157,3 +303,55 @@ @article{moresi.etal.Lagrangian.2003 296 citations (Crossref) [2022-04-28]}, file = {/Users/lmoresi/Zotero/storage/UZGHI342/Moresi et al. - 2003 - A Lagrangian integration point finite element meth.pdf} } + +@article{wilsonTerraFERMARansparent2017, + title = {Terra {{{\textsc{FERMA}}}} : {{The}} {{{\textsc{T}}}} Ransparent {{{\textsc{F}}}} Inite {{{\textsc{E}}}} Lement {{{\textsc{R}}}} Apid {{{\textsc{M}}}} Odel {{{\textsc{A}}}} Ssembler for Multiphysics Problems in {{{\textsc{E}}}} Arth Sciences}, + shorttitle = {Terra}, + author = {Wilson, Cian R. and Spiegelman, Marc and Van Keken, Peter E.}, + year = {2017}, + month = feb, + journal = {Geochem Geophys Geosyst}, + volume = {18}, + number = {2}, + pages = {769--810}, + issn = {1525-2027, 1525-2027}, + doi = {10.1002/2016GC006702}, + urldate = {2025-04-17}, + abstract = {Abstract We introduce and describe a new software infrastructure TerraFERMA, the Transparent Finite Element Rapid Model Assembler , for the rapid and reproducible description and solution of coupled multiphysics problems. The design of TerraFERMA is driven by two computational needs in Earth sciences. The first is the need for increased flexibility in both problem description and solution strategies for coupled problems where small changes in model assumptions can lead to dramatic changes in physical behavior. The second is the need for software and models that are more transparent so that results can be verified, reproduced, and modified in a manner such that the best ideas in computation and Earth science can be more easily shared and reused. TerraFERMA leverages three advanced open-source libraries for scientific computation that provide high-level problem description (FEniCS), composable solvers for coupled multiphysics problems (PETSc), and an options handling system (SPuD) that allows the hierarchical management of all model options. TerraFERMA integrates these libraries into an interface that organizes the scientific and computational choices required in a model into a single options file from which a custom compiled application is generated and run. Because all models share the same infrastructure, models become more reusable and reproducible, while still permitting the individual researcher considerable latitude in model construction. TerraFERMA solves partial differential equations using the finite element method. It is particularly well suited for nonlinear problems with complex coupling between components. TerraFERMA is open-source and available at http://terraferma.github.io , which includes links to documentation and example input files. , Key Points We present new software for more reproducible and reusable solutions of multiphysics problems The software leverages advanced parallel computational libraries TerraFERMA is open source and available at http://terraferma.github.io}, + copyright = {http://onlinelibrary.wiley.com/termsAndConditions\#am}, + langid = {english}, + file = {/Users/lmoresi/Zotero/storage/QVZF4T5G/Wilson et al. - 2017 - Terra FERMA The span style=font-variantsmall-caps.pdf;/Users/lmoresi/Zotero/storage/UYI47HE6/Wilson et al. - 2017 - Terra FERMA The span style=font-variantsmall-caps.pdf} +} + +@incollection{zhong705NumericalMethods2015, + title = {7.05 - {{Numerical Methods}} for {{Mantle Convection}}}, + booktitle = {Treatise on {{Geophysics}} ({{Second Edition}})}, + author = {Zhong, S. J. and Yuen, D. A. and Moresi, L. N. and Knepley, M. G.}, + editor = {Schubert, Gerald}, + year = {2015}, + month = jan, + pages = {197--222}, + publisher = {Elsevier}, + address = {Oxford}, + doi = {10.1016/B978-0-444-53802-4.00130-5}, + urldate = {2019-10-11}, + abstract = {Over the past 40 years, numerical methods used to model mantle convection have matured significantly and now occupy a distinctive niche in computational fluid dynamics. The central issue for the partial differential equations governing mantle dynamics concerns the rheology governing the flow of mantle rocks under relevant temperature and pressure conditions. The momentum equation is the most computationally intensive portion of this coupled system because of its strongly nonlinear, elliptical character. We review the various discretization methods, ranging from finite differences to finite elements, which have been employed. We present in detail finite-element implementations of the Uzawa algorithm for the momentum equation and of the streamline Petrov--Galerkin algorithm for the energy equation. We review the application of modern techniques such as the Schur complement solvers and least-squares commutator preconditioners in the solution of the elliptical equation. We discuss the computational libraries available for massively parallel simulation and their application to this system of equations and give a preview of approaches suitable for exascale computing, which is a major challenge for the decade ahead.}, + copyright = {All rights reserved}, + isbn = {978-0-444-53803-1}, + keywords = {Finite element,High-performance computing,Mantle convection,Multigrid,Non-Newtonian rheology,Nonlinear elliptical equations,Nonlinear rheology,Nonlinear solvers,Saddle point system,Variable viscosity}, + annotation = {ZSCC: NoCitationData[s0]} +} + +@book{zienkiewiczFiniteElementMethod2013, + title = {The Finite Element Method: Its Basis and Fundamentals}, + shorttitle = {The Finite Element Method}, + author = {Zienkiewicz, O. C. and Taylor, Robert L. and Zhu, J. Z.}, + year = {2013}, + edition = {Seventh edition}, + publisher = {Elsevier, Butterworth-Heinemann}, + address = {Amsterdam}, + doi = {10.1016/b978-1-85617-633-0.00019-7}, + isbn = {978-1-85617-633-0}, + lccn = {TA640.2 .Z5 2013}, + keywords = {Engineering mathematics,Finite element method,Fluid dynamics} +} diff --git a/docs/joss-paper/paper.crossref b/docs/joss-paper/paper.crossref index f7489679f..424e66541 100644 --- a/docs/joss-paper/paper.crossref +++ b/docs/joss-paper/paper.crossref @@ -6,8 +6,8 @@ version="5.3.1" xsi:schemaLocation="http://www.crossref.org/schema/5.3.1 http://www.crossref.org/schemas/crossref5.3.1.xsd"> - 20241013162733-b69e4fcdb92ad9bd087cfbdeff82a67b2a9a6732 - 20241013162733 + 20250512120715-b69e4fcdb92ad9bd087cfbdeff82a67b2a9a6732 + 20250512120715 JOSS Admin admin@theoj.org @@ -37,61 +37,87 @@ - Underworld3: Mathematically Self-Describing Modelling -in Python for Desktop, HPC and Cloud + Underworld3: Mathematically Self-Describing Modelling in Python for Desktop, HPC and Cloud Louis Moresi + + Research School of Earth Sciences, Australian National University, Canberra, Australia + https://orcid.org/0000-0003-3685-174X John Mansour + + School of Earth, Atmospheric & Environmental Science, Monash University + https://orcid.org/0000-0001-5865-1664 Julian Giordani + + University of Sydney, Sydney, Australia + https://orcid.org/0000-0003-4515-9296 Matt Knepley + + Computer Science and Engineering, University at Buffalo + https://orcid.org/0000-0002-2292-0735 Ben Knight + + Curtin University, Perth, Australia + https://orcid.org/0000-0001-7919-2575 Juan Carlos Graciosa + + Research School of Earth Sciences, Australian National University, Canberra, Australia + https://orcid.org/0000-0003-0817-354X Thyagarajulu Gollapalli + + School of Earth, Atmospheric & Environmental Science, Monash University + https://orcid.org/0000-0001-9394-4104 Neng Lu + + Research School of Earth Sciences, Australian National University, Canberra, Australia + https://orcid.org/0000-0001-9424-2315 Romain Beucher + + Research School of Earth Sciences, Australian National University, Canberra, Australia + https://orcid.org/0000-0003-3891-5444 @@ -131,36 +157,52 @@ in Python for Desktop, HPC and Cloud - + PETSc/TAO Users Manual V.3.21 Balay 10.2172/2337606 2024 - Balay, S., Abhyankar, S., Adams, M., -Benson, S., Brown, J., Brune, P., Buschelman, K., Constantinescu, E., -Dalcin, L., Dener, A., Eijkhout, V., Faibussowitsch, J., Gropp, W., -Hapla, V., Isaac, T., Jolivet, P., Karpeev, D., Kaushik, D., Knepley, -M., … Zhang, J. (2024). PETSc/TAO Users Manual V.3.21 -(ANL–21/39-Rev-3.21, 2337606, 188499; pp. ANL-21/39-Rev-3.21, 2337606, -188499). https://doi.org/10.2172/2337606 + Balay, S., Abhyankar, S., Adams, M., Benson, S., Brown, J., Brune, P., Buschelman, K., Constantinescu, E., Dalcin, L., Dener, A., Eijkhout, V., Faibussowitsch, J., Gropp, W., Hapla, V., Isaac, T., Jolivet, P., Karpeev, D., Kaushik, D., Knepley, M., … Zhang, J. (2024). PETSc/TAO Users Manual V.3.21 (ANL–21/39-Rev-3.21, 2337606, 188499; pp. ANL-21/39-Rev-3.21, 2337606, 188499). https://doi.org/10.2172/2337606 + + + Finite Element Method + Bathe + Wiley Encyclopedia of Computer Science and Engineering + 10.1002/9780470050118.ecse159 + 978-0-470-05011-8 + 2008 + Bathe, K.-J. (2008). Finite Element Method. In B. W. Wah (Ed.), Wiley Encyclopedia of Computer Science and Engineering (p. ecse159). John Wiley & Sons, Inc. https://doi.org/10.1002/9780470050118.ecse159 - Cython: The best of both -worlds + Cython: The best of both worlds Behnel - Computing in Science & -Engineering + Computing in Science & Engineering 2 13 + 10.1109/mcse.2010.118 2011 - Behnel, S., Bradshaw, R., Citro, C., -Dalcin, L., Seljebotn, D. S., & Smith, K. (2011). Cython: The best -of both worlds. Computing in Science & Engineering, 13(2), -31–39. + Behnel, S., Bradshaw, R., Citro, C., Dalcin, L., Seljebotn, D. S., & Smith, K. (2011). Cython: The best of both worlds. Computing in Science & Engineering, 13(2), 31–39. https://doi.org/10.1109/mcse.2010.118 + + + LaMEM + Kaus + 10.5281/ZENODO.10718860 + 2024 + Kaus, B., Popov, A., Garrett_Ito, Spang, A., greuber, Ibragimov, I., xinxinwang01, thomasAmorrow, Pusok, A., APiccolo89, ChristianSchuler, Sanan, P., sasbrune, YangJianfeng2015, Bauville, A., & birand-zz. (2024). LaMEM. Zenodo. https://doi.org/10.5281/ZENODO.10718860 + + + MILAMIN: MATLAB-based finite element method solver for large problems + Dabrowski + Geochem Geophys Geosyst + 4 + 9 + 10.1029/2007GC001719 + 1525-2027 + 2008 + Dabrowski, M., Krotkiewski, M., & Schmid, D. W. (2008). MILAMIN: MATLAB-based finite element method solver for large problems. Geochem Geophys Geosyst, 9(4), 2007GC001719. https://doi.org/10.1029/2007GC001719 - Parallel distributed computing using -Python + Parallel distributed computing using Python Dalcin Advances in Water Resources 9 @@ -168,55 +210,105 @@ Python 10.1016/j.advwatres.2011.04.013 0309-1708 2011 - Dalcin, L. D., Paz, R. R., Kler, P. -A., & Cosimo, A. (2011). Parallel distributed computing using -Python. Advances in Water Resources, 34(9), 1124–1139. -https://doi.org/10.1016/j.advwatres.2011.04.013 - - - Achieving High Performance with Unified -Residual Evaluation + Dalcin, L. D., Paz, R. R., Kler, P. A., & Cosimo, A. (2011). Parallel distributed computing using Python. Advances in Water Resources, 34(9), 1124–1139. https://doi.org/10.1016/j.advwatres.2011.04.013 + + + Towards automatic finite-element methods for geodynamics via Firedrake + Davies + Geosci. Model Dev. + 13 + 15 + 10.5194/gmd-15-5127-2022 + 1991-9603 + 2022 + Davies, D. R., Kramer, S. C., Ghelichkhan, S., & Gibson, A. (2022). Towards automatic finite-element methods for geodynamics via Firedrake. Geosci. Model Dev., 15(13), 5127–5166. https://doi.org/10.5194/gmd-15-5127-2022 + + + Fluidity: A fully unstructured anisotropic adaptive mesh computational modeling framework for geodynamics: FLUIDITY-MODELING GEODYNAMICAL FLOWS + Davies + Geochem. Geophys. Geosyst. + 6 + 12 + 10.1029/2011GC003551 + 2011 + Davies, D. R., Wilson, C. R., & Kramer, S. C. (2011). Fluidity: A fully unstructured anisotropic adaptive mesh computational modeling framework for geodynamics: FLUIDITY-MODELING GEODYNAMICAL FLOWS. Geochem. Geophys. Geosyst., 12(6), n/a–n/a. https://doi.org/10.1029/2011GC003551 + + + High accuracy mantle convection simulation through modern numerical methods – II: Realistic models and problems + Heister + Geophysical Journal International + 2 + 210 + 10.1093/gji/ggx195 + 0956-540X + 2017 + Heister, T., Dannberg, J., Gassmöller, R., & Bangerth, W. (2017). High accuracy mantle convection simulation through modern numerical methods – II: Realistic models and problems. Geophysical Journal International, 210(2), 833–851. https://doi.org/10.1093/gji/ggx195 + + + The finite element method: Linear static and dynamic finite element analysis + Hughes + 10.1016/0045-7825(87)90013-2 + 978-0-13-317025-2 + 1987 + Hughes, T. J. R. (1987). The finite element method: Linear static and dynamic finite element analysis (1. Dr.). Prentice Hall. https://doi.org/10.1016/0045-7825(87)90013-2 + + + Achieving High Performance with Unified Residual Evaluation Knepley arXiv:1309.1204 [cs] 2013 - Knepley, M. G., Brown, J., Rupp, K., -& Smith, B. F. (2013). Achieving High Performance with Unified -Residual Evaluation. arXiv:1309.1204 [Cs]. -https://arxiv.org/abs/1309.1204 - - - SymPy: Symbolic computing in -Python - Meurer - PeerJ Computer Science - 3 - 10.7717/peerj-cs.103 - 2376-5992 - 2017 - Meurer, A., Smith, C. P., Paprocki, -M., Čertík, O., Kirpichev, S. B., Rocklin, M., Kumar, A., Ivanov, S., -Moore, J. K., Singh, S., Rathnayake, T., Vig, S., Granger, B. E., -Muller, R. P., Bonazzi, F., Gupta, H., Vats, S., Johansson, F., -Pedregosa, F., … Scopatz, A. (2017). SymPy: Symbolic computing in -Python. PeerJ Computer Science, 3, e103. -https://doi.org/10.7717/peerj-cs.103 - - - A Lagrangian integration point finite element -method for large deformation modeling of viscoelastic -geomaterials + Knepley, M. G., Brown, J., Rupp, K., & Smith, B. F. (2013). Achieving High Performance with Unified Residual Evaluation. arXiv:1309.1204 [Cs]. https://arxiv.org/abs/1309.1204 + + + Underworld2: Python Geodynamics Modelling for Desktop, HPC and Cloud + Mansour + JOSS + 47 + 5 + 10.21105/joss.01797 + 2475-9066 + 2020 + Mansour, J., Giordani, J., Moresi, L., Beucher, R., Kaluza, O., Velic, M., Farrington, R., Quenette, S., & Beall, A. (2020). Underworld2: Python Geodynamics Modelling for Desktop, HPC and Cloud. JOSS, 5(47), 1797. https://doi.org/10.21105/joss.01797 + + + Computational approaches to studying non-linear dynamics of the crust and mantle + Moresi + Physics of the Earth and Planetary Interiors + 1 + 163 + 10.1016/j.pepi.2007.06.009 + 0031-9201 + 2007 + Moresi, L., Quenette, S., Lemiale, V., Mériaux, C., Appelbe, B., & Mühlhaus, H.-B. (2007). Computational approaches to studying non-linear dynamics of the crust and mantle. Physics of the Earth and Planetary Interiors, 163(1), 69–82. https://doi.org/10.1016/j.pepi.2007.06.009 + + + A Lagrangian integration point finite element method for large deformation modeling of viscoelastic geomaterials Moresi - Journal of Computational -Physics + Journal of Computational Physics 2 184 10.1016/S0021-9991(02)00031-1 2003 - Moresi, L., Dufour, F., & -Mühlhaus, H.-B. (2003). A Lagrangian integration point finite element -method for large deformation modeling of viscoelastic geomaterials. -Journal of Computational Physics, 184(2), 476–497. -https://doi.org/10.1016/S0021-9991(02)00031-1 + Moresi, L., Dufour, F., & Mühlhaus, H.-B. (2003). A Lagrangian integration point finite element method for large deformation modeling of viscoelastic geomaterials. Journal of Computational Physics, 184(2), 476–497. https://doi.org/10.1016/S0021-9991(02)00031-1 + + + Terra FERMA : The T ransparent F inite E lement R apid M odel A ssembler for multiphysics problems in E arth sciences + Wilson + Geochem Geophys Geosyst + 2 + 18 + 10.1002/2016GC006702 + 1525-2027 + 2017 + Wilson, C. R., Spiegelman, M., & Van Keken, P. E. (2017). Terra FERMA : The T ransparent F inite E lement R apid M odel A ssembler for multiphysics problems in E arth sciences. Geochem Geophys Geosyst, 18(2), 769–810. https://doi.org/10.1002/2016GC006702 + + + The finite element method: Its basis and fundamentals + Zienkiewicz + 10.1016/b978-1-85617-633-0.00019-7 + 978-1-85617-633-0 + 2013 + Zienkiewicz, O. C., Taylor, R. L., & Zhu, J. Z. (2013). The finite element method: Its basis and fundamentals (Seventh edition). Elsevier, Butterworth-Heinemann. https://doi.org/10.1016/b978-1-85617-633-0.00019-7 diff --git a/docs/joss-paper/paper.md b/docs/joss-paper/paper.md index 9c66ffd53..148742c2c 100644 --- a/docs/joss-paper/paper.md +++ b/docs/joss-paper/paper.md @@ -56,36 +56,41 @@ bibliography: paper.bib # Summary -`Underworld3` is a finite element, geophysical-fluid-dynamics modelling framework designed to be both straightforward to use and highly scalable to peak high-performance computing environments. It implements the Lagrangian-particle finite element methodology outlined in @moresi.etal.Lagrangian.2003. +`Underworld3` is a finite element, geophysical-fluid-dynamics modelling framework designed to be both straightforward to use and highly scalable to peak high-performance computing environments. It implements the Lagrangian-particle finite element methodology outlined in @moresiLagrangianIntegrationPoint2003. - `Underworld3` inherits the design patterns of earlier versions of `underworld` including: (1) A python user interface that is inherently safe for parallel computation. (2) A symbolic interface based on `sympy` that allows users to construct and simplify combinations of mathematical functions, unknowns and the spatial gradients of unknowns on the fly. (3) Interchangeable Lagrangian, Semi-Lagrangian and Eulerian time derivatives with symbolic representations wrapping the underlying implementation. (4) Fast, robust, parallel numerical solvers based on `PETSc` [@balay.etal.PETSc.2024] and `petsc4py` [@dalcinpazklercosimo2011], (5) Flexible, Lagrangian "particle" swarms for handling transport-dominated unknowns that are fully interchangeable with other data-types and can also be treated as symbolic quantities. (6) Unstructured and adaptive meshing that is fully compatible with the symbolic framework. + `Underworld3` inherits the design patterns of earlier versions of `underworld` including: (1) A python user interface that is inherently safe for parallel computation. (2) A symbolic interface based on `sympy` that allows users to construct and simplify combinations of mathematical functions, unknowns and the spatial gradients of unknowns on the fly. (3) Interchangeable Lagrangian, Semi-Lagrangian and Eulerian time derivatives with symbolic representations wrapping the underlying implementation. (4) Fast, robust, parallel numerical solvers based on `PETSc` [@balayPETScTAOUsers2024] and `petsc4py` [@dalcinpazklercosimo2011], (5) Flexible, Lagrangian "particle" swarms for handling transport-dominated unknowns that are fully interchangeable with other data-types and can also be treated as symbolic quantities. (6) Unstructured and adaptive meshing that is fully compatible with the symbolic framework. The symbolic forms in (2,3) are used to construct a finite element representation using `sympy` [@meurer.etal.SymPy.2017] and `cython` [@behnel2011cython]. These forms are just-in-time (JIT) compiled as `C` functions libraries and pointers to these libraries are given to PETSc to describe the finite element weak forms (surface and volume integrals), Jacobian derivatives and boundary conditions. Users of `underworld3` typically develop python scripts within `jupyter` notebooks and, in this environment, `underworld3` provides introspection of its native classes both as python objects as well as mathematical ones. This allows symbolic prototyping and validation of PDE solvers in scripts that can immediately be deployed in a parallel HPC environment. + # Statement of need -The problems in global planetary dynamics and tectonics that `underworld3` is designed to address have a number of defining characteristics: geomaterials are non-linear, viscoelastic/plastic and have a propensity for strain-dependent softening during deformation; strain localisation is very common as a consequence. Geological structures that we seek to understand are often emergent over the course of loading and are observed in the very-large deformation limit. Material properties have strong spatial gradients arising from pressure and temperature dependence and jumps of several orders of magnitude resulting from material interfaces. +Underworld is built around a general, symbolic partial differential equation solver but provides template forms to solve common geophysical fluid dynamics problems such as the Stokes equation for mantle convection, subduction-zone evolution, lithospheric deformation, glacial isostatic adjustment, ice flow; Navier-Stokes equations for finite Prandtl number fluid flow and short-timescale, viscoelastic deformation; and Darcy Flow for porous media problems including groundwater flow and contaminant transport. + +These problems have a number of defining characteristics: geomaterials are non-linear, viscoelastic/plastic and have a propensity for strain-dependent softening during deformation; strain localisation is very common as a consequence. Geological structures that we seek to understand are often emergent over the course of loading and are observed in the very-large deformation limit. Material properties have strong spatial gradients arising from pressure and temperature dependence and jumps of several orders of magnitude resulting from material interfaces. `underworld3` automatically handles much of the complexity of combining the non-linearities in rheology, boundary conditions and time-discretisation, forming their derivatives, and simplifying expressions to generate an efficient, parallel `PETSc` script. `underworld3` provides a textbook-like mathematical experience for users who are confident in understanding physical modelling. A number of equation-system templates are provided for typical geophysical fluid dynamics problems such as Stokes-flow, Navier-Stokes-flow, and Darcy flow which provide both usage and mathematical documentation at run-time. ## Mathematical Framework -`PETSc` provides a template form for the automatic generation of weak forms [see @knepley.etal.Achieving.2013]. The strong-form of the problem is defined through the functional $\mathcal{F}$ that expresses the balance between fluxes, forces, and unknowns: +The symbolic layer of `underworld3` works with the "strong form" of a problem which is typically how the governing equations are derived and disseminated in publications and textbooks. The finite element method is based on a corresponding weak or variational form [e.g. 'standard' finite element textbooks such as @hughesFiniteElementMethod1987, @batheFiniteElementMethod2008, @zienkiewiczFiniteElementMethod2013]. + +`PETSc` provides a template form for the automatic generation of weak forms [see @knepleyAchievingHighPerformance2013]. We start from the strong-form of the problem which is defined through the functional $\mathcal{F}_s$ that expresses the balance between fluxes ($F(u, \nabla u)$), forces, $f(u, \nabla u)$, and unknowns $u$: \begin{equation}\label{eq:petsc-strong-form} -\mathcal{F}(u) \sim \nabla \cdot F(u, \nabla u) - f(u, \nabla u) = 0 +\mathcal{F}_s(u) \sim \nabla \cdot F(u, \nabla u) - f(u, \nabla u) = 0 \end{equation} -The discrete weak form and its Jacobian derivative can be expressed as follows +The discrete weak form and its Jacobian derivative would then be expressed through the related functional $\mathcal{F}_w$ as follows: \begin{equation}\label{eq:petsc-weak-form} - \mathcal{F}(u) \sim \sum_e \epsilon_e^T \left[ B^T W f(u^q, \nabla u^q) + \sum_k D_k^T W F^k (u^q, \nabla u^q) \right] = 0 + \mathcal{F}_w(u) \sim \sum_e \epsilon_e^T \left[ B^T W f(u^q, \nabla u^q) + \sum_k D_k^T W F^k (u^q, \nabla u^q) \right] = 0 \end{equation} \begin{equation}\label{eq:petsc-jacobian} - \mathcal{F}'(u) \sim \sum _e \epsilon _{e^T} + \mathcal{F}_w'(u) \sim \sum _e \epsilon _{e^T} \left[ \begin{array}{cc} B^T & D^T \\ \end{array} \right] @@ -104,17 +109,29 @@ The discrete weak form and its Jacobian derivative can be expressed as follows \epsilon _{e} \end{equation} + +Here $\epsilon$ is the element restriction operator; $B$ is the matrix of basis function derivatives and $D$ is the constitutive matrix that, together, describe the relation between the unknowns and the flux. $q$ indicates that the values are determined at a set of quadrature points, and $W$ is a diagonal matrix of weights for these points. + The symbolic representation of the strong-form that is encoded in `underworld3` is: \begin{equation}\label{eq:sympy-strong-form} -\underbrace{ \Bigl[ {D u}/{D t} \Bigr]}_{\dot{u} } --\nabla \cdot \underbrace{\Bigl[ \mathrm{F}(u, \nabla u) \Bigr]}_{\mathbf{F}} --\underbrace{\Bigl[ \mathrm{H}(\mathbf{x},t) \Bigr]}_{\mathbf{h}} + \Bigl[ {D u}/{D t} \Bigr] +-\nabla \cdot \Bigl[ \sigma(u, \nabla u, \mathbf{x}, t) \Bigr] +-\Bigl[ \mathrm{H}(u, \nabla u, \mathbf{x},t) \Bigr] = 0 \end{equation} -This symbolic form (\ref{eq:sympy-strong-form}) -contains material / time derivatives of the unknowns which are not present in the `PETSc` template because, after discretisation, these simplify to produce terms that are combinations of fluxes and flux history terms (which modify $F$) and forces (which modify $h$). In `underworld3`, the user interacts with the time derivatives themselves and `sympy` combines all the flux-like terms and all the force-like terms just prior to forming the Jacobians and compiling the `C` functions. +Here $\mathrm{H}$ represents sources and sinks of $u$, and ${D u}/{D t}$ is the material time derivative of $u$. The time derivatives of the unknowns are not present in the `PETSc` template but, after time-discretisation, they produce terms that are combinations of fluxes and flux history terms (which combine with $\boldsymbol{\sigma}$ to contribute to $F$) and forces (which combine with $\mathbf{h}$ to contribute to $f$). The explicit time / position dependence in $\sigma$ is to highlight potential changes to boundary conditions or constitutive properties. + +In `underworld3`, the user interacts with the time derivatives explicitly, and provides strong-form expressions for the template \ref{eq:sympy-strong-form}. `Sympy` automatically gathers all the flux-like terms and all the force-like terms into the form required by the `PETSc` template. All evaluations, derivatives and simplifications of functions in the `underworld3` symbolic layer are deferred until final assembly of the `PETSc` template and the compilation of the `C` functions. + +The main benefits of combining `sympy` with the `PETSc` weak form template is a user environment that 1) provides symbolic, mathematical introspection, particularly in the context of Jupyter notebooks; 2) eliminates much of the `python` or `C` coding required for complex constitutive models; 3) eliminates any need for users to compute derivatives for the Newton solvers in `PETSc`. + +# State of the Field + +`Underworld3` is one among a small number of codes for studying Earth deformation on medium to long geological time-scales. Early geodynamics codes, of which there were too many to recite individually, were highly specialised for specific tasks with little flexibility for user-defined problems. A subsequent generation of codes, currently in use, was built around generic partial differential equation solvers with scriptable interfaces. These include: Aspect [C++ plugin architecture: @heisterHighAccuracyMantle2017], Underworld 1 and 2 [xml object composition / python scripting respectively, @mansourUnderworld2PythonGeodynamics2020; @moresiComputationalApproachesStudying2007], Fluidity [xml combined with python scripting, @daviesFluidityFullyUnstructured2011a], Milamin [Matlab front end, @dabrowskiMILAMINMATLABbasedFinite2008], LaMEM [julia scripting @boriskausLaMEM2024], TerraFERMA [Unified Form Language, @wilsonTerraFERMARansparent2017], GAdopt [Unified Form Language / python @daviesAutomaticFiniteelementMethods2022]. + +`Underworld3` uses python and the python package `sympy` as the scripting interface that overlies the generic partial differential equation layer. The advantage of `sympy` is that it is a fully featured symbolic algebra package which allows much of the logic of the mathematical problem description to be defined symbolically and dynamically rather than as static relationships between objects. It also provides deep, mathematical introspection when developing and debugging models. # Discussion diff --git a/docs/joss-paper/paper.pdf b/docs/joss-paper/paper.pdf index 352ca8583..3acb67b5a 100644 Binary files a/docs/joss-paper/paper.pdf and b/docs/joss-paper/paper.pdf differ diff --git a/docs/user/NextSteps.qmd b/docs/user/NextSteps.qmd index 6f1ee7b5d..87afc58b1 100644 --- a/docs/user/NextSteps.qmd +++ b/docs/user/NextSteps.qmd @@ -16,9 +16,8 @@ In addition to the notebooks in this brief set of examples, there are a number o - [The Underworld Website / Blog](https://www.underworldcode.org) - - [The API documentation](https://underworldcode.github.io/underworld3/main_api/underworld3/index.html) - (all the modules and functions and their full sets of arguments) is automatically generated from the source code and uses the same rich markdown content as the notebook help text. - There is also a set of [API docs](https://underworldcode.github.io/underworld3/development_api/underworld3/index.html) for the development branch. + - [The API documentation](https://underworldcode.github.io/underworld3/main_api/underworld3/index.html) + (all the modules and functions and their full sets of arguments) is automatically generated from the source code and uses the same rich markdown content as the notebook help text. - The [`underworld3` GitHub repository](https://github.com/underworldcode/underworld3) is the most active development community for the code. diff --git a/paper.bib b/paper.bib new file mode 120000 index 000000000..10e8d0263 --- /dev/null +++ b/paper.bib @@ -0,0 +1 @@ +docs/joss-paper/paper.bib \ No newline at end of file diff --git a/paper.md b/paper.md new file mode 120000 index 000000000..1bc2d8cfe --- /dev/null +++ b/paper.md @@ -0,0 +1 @@ +docs/joss-paper/paper.md \ No newline at end of file diff --git a/setup.py b/setup.py index 6066b7c3f..d78de5d22 100644 --- a/setup.py +++ b/setup.py @@ -168,7 +168,8 @@ def get_version(filename): if line.startswith("__version__"): # extract the version string and strip it version = line.split('"')[1].strip().strip('"').strip("'") - return version + break + return version except FileNotFoundError: print( f"Cannot get version information from {filename}" ) except: diff --git a/src/underworld3/_version.py b/src/underworld3/_version.py index bed1ac788..51fa72078 100644 --- a/src/underworld3/_version.py +++ b/src/underworld3/_version.py @@ -1 +1,2 @@ +## On initial, official release, let __version__ for underworld3 move to 3.0 (of underworld) __version__ = "0.99.0b" diff --git a/test.sh b/test.sh index 41114573e..7218a5f81 100755 --- a/test.sh +++ b/test.sh @@ -26,8 +26,9 @@ $PYTEST tests/test_100[0-9]*py || status=1 $PYTEST tests/test_1010*py tests/test_1011*py tests/test_1050*py || status=1 # Diffusion / Advection tests -# $PYTEST tests/test_1100*py || status=1 -# $PYTEST tests/test_1110*py # Annulus version || status=1 + +$PYTEST tests/test_1100*py || status=1 +$PYTEST tests/test_1110*py # Annulus version || status=1 # if [ $status -ne 0 ]; then echo "Some test failed."