diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml new file mode 100644 index 000000000..8271cf3da --- /dev/null +++ b/.github/workflows/draft-pdf.yml @@ -0,0 +1,23 @@ +on: [push,pull_request] + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: doc/JOSS/1.0/paper.md + - name: Upload + uses: actions/upload-artifact@v1 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: doc/JOSS/1.0/paper.pdf \ No newline at end of file diff --git a/.typos.toml b/.typos.toml index 7bae93700..5925d13c5 100755 --- a/.typos.toml +++ b/.typos.toml @@ -13,6 +13,7 @@ ba = "ba" # Don't correct some other abbreviations FOT = "FOT" +OCE = "OCE" GWB = "GWB" NWO = "NWO" SEH = "SEH" diff --git a/doc/JOSS/1.0/paper.bib b/doc/JOSS/1.0/paper.bib new file mode 100644 index 000000000..21f0c65d3 --- /dev/null +++ b/doc/JOSS/1.0/paper.bib @@ -0,0 +1,205 @@ +@Article{Fraters_Thieulot_etal_2019, +AUTHOR = {Fraters, M. and Thieulot, C. and van den Berg, A. and Spakman, W.}, +TITLE = {The Geodynamic World Builder: a solution for complex initial conditions in numerical modeling}, +JOURNAL = {Solid Earth}, +VOLUME = {10}, +YEAR = {2019}, +NUMBER = {5}, +PAGES = {1785--1807}, +URL = {https://se.copernicus.org/articles/10/1785/2019/}, +DOI = {10.5194/se-10-1785-2019} +} + +@article{Bauville_Baumann_2019, +author = {Bauville, A. and Baumann, T. S.}, +title = {geomIO: An Open-Source MATLAB Toolbox to Create the Initial Configuration of 2-D/3-D Thermo-Mechanical Simulations From 2-D Vector Drawings}, +journal = {Geochemistry, Geophysics, Geosystems}, +volume = {20}, +number = {3}, +pages = {1665-1675}, +keywords = {3-D modeling, numerical simulation, MATLAB toolbox, 3-D temperature distribution}, +doi = {https://doi.org/10.1029/2018GC008057}, +url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2018GC008057}, +eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2018GC008057}, +abstract = {Abstract Creating the initial geometry and temperature configuration of 3-D numerical simulations is a challenging task. Professional tools are expensive. They often have a steep learning curve and do mostly not interface with the numerical simulation software used by the geodynamics and tectonics academic community. There, we developed geometry Input/Output (geomIO), a MATLAB toolbox to create the initial configuration of geological models regarding model geometry and temperature structure. geomIO allows users to create a geo-referenced 3-D volume by drawing multiple 2-D cross sections in a standard vector graphics editor. The volume is then used to assign material properties and set up initial temperature distribution on a set of vertices. In 2-D mode, polygons can also be used to create a triangular mesh. In addition to the standard functionality, the gravity anomaly of any geometry created with geomIO can be calculated. In this paper, we give an overview of the basic functionalities of geomIO. We illustrate the strength of our software with advanced tectonic and geodynamic applications that could not have been performed with currently available free software. Applications include the Himalayan orogen, the Japanese subduction zones, present-day salt diapirs, and small-scale tectonic structures. We describe algorithms and file formats in the supporting information. The toolbox is user-friendly and flexible. Users can use custom pipelines or preset data processing pipelines, so most applications require only a few lines of code. geomIO is distributed under the GNU General Public License and includes an online wiki with tutorials and additional examples.}, +year = {2019} +} + +@article{Spang_Baumann_2022, +author = {Spang, A. and Baumann, T. S. and Kaus, B. J. P.}, +title = {Geodynamic Modeling With Uncertain Initial Geometries}, +journal = {Geochemistry, Geophysics, Geosystems}, +volume = {23}, +number = {6}, +pages = {e2021GC010265}, +keywords = {geometry parameterization, variable geometry, salt tectonics, subduction velocity, inversion, subduction angle}, +doi = {https://doi.org/10.1029/2021GC010265}, +url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2021GC010265}, +eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2021GC010265}, +note = {e2021GC010265 2021GC010265}, +abstract = {Abstract Geodynamic codes have become fast and efficient enough to facilitate sensitivity analysis of rheological parameters. With sufficient data, they can even be inverted for. Yet, the geodynamic inverse problem is often regularized by assuming a constant geometry of the geological setting (e.g., shape, location and size of salt diapirs or magma bodies) or approximating irregular bodies with simple shapes like boxes, spheres or ellipsoids to reduce the parameter space. Here, we present a simple and intuitive method to parameterize complex 3D bodies and incorporate them into geodynamic inverse problems. The approach can automatically create an entire ensemble of initial geometries, enabling us to account for uncertainties in imaging data. Furthermore, it allows us to investigate the sensitivity of the model results to geometrical properties and facilitates inverting for them. We demonstrate the method with two examples. A salt diapir in an extending regime and free subduction of an oceanic plate under a continent. In both cases, small differences in the model's initial geometry lead to vastly different results. Be it the formation of faults or the velocity of plates. Using the salt diapir example, we demonstrate that, given an additional geophysical observation, we are able to invert for uncertain geometric properties. This highlights that geodynamic studies should investigate the sensitivity of their models to the initial geometry and include it in their inversion framework. We make our method available as part of the open-source software geomIO.}, +year = {2022} +} + +@article{Beucher_Moresi_etal_2019, +doi = {10.21105/joss.01136}, +url = {https://doi.org/10.21105/joss.01136}, +year = {2019}, +publisher = {The Open Journal}, +volume = {4}, +number = {36}, +pages = {1136}, +author = {Romain Beucher and Louis Moresi and Julian Giordani and John Mansour and Dan Sandiford and Rebecca Farrington and Luke Mondy and Claire Mallard and Patrice Rey and Guillaume Duclaux and Owen Kaluza and Arijit Laik and Sara Morón}, +title = {UWGeodynamics: A teaching and research tool for numerical geodynamic modelling}, +journal = {Journal of Open Source Software} +} + +@article{Moresi_Dufour_2002, +authors = {Moresi, L. and Dufour, F. and Mühlhaus, HB. }, +title = {Mantle Convection Modeling with Viscoelastic/Brittle Lithosphere: Numerical Methodology and Plate Tectonic Modeling.}, +journal = {Pure appl. geophys.}, +volume = {159}, +pages = {2335–2356}, +year = {2002}, +url = {https://doi.org/10.1007/s00024-002-8738-3} +} + +@article{Varga_Schaaf_2019, +AUTHOR = {de la Varga, M. and Schaaf, A. and Wellmann, F.}, +TITLE = {GemPy 1.0: open-source stochastic geological modeling and inversion}, +JOURNAL = {Geoscientific Model Development}, +VOLUME = {12}, +YEAR = {2019}, +NUMBER = {1}, +PAGES = {1--32}, +URL = {https://gmd.copernicus.org/articles/12/1/2019/}, +DOI = {10.5194/gmd-12-1-2019} +} + +@article{Schaaf_Varga_2021, +AUTHOR = {Schaaf, A. and de la Varga, M. and Wellmann, F. and Bond, C. E.}, +TITLE = {Constraining stochastic 3-D structural geological models with topology information using approximate Bayesian computation in GemPy 2.1}, +JOURNAL = {Geoscientific Model Development}, +VOLUME = {14}, +YEAR = {2021}, +NUMBER = {6}, +PAGES = {3899--3913}, +URL = {https://gmd.copernicus.org/articles/14/3899/2021/}, +DOI = {10.5194/gmd-14-3899-2021} +} + +@article{McKenzie_1970, + title = "Temperature and potential temperature beneath island arcs", + journal = "Tectonophysics", + volume = "10", + number = "1", + pages = "357 - 366", + year = "1970", + note = "Geothermal Problems", + issn = "0040-1951", + doi = "https://doi.org/10.1016/0040-1951(70)90115-0", + url = "http://www.sciencedirect.com/science/article/pii/0040195170901150", + author = "D.P. McKenzie" +} +@software{sebastien_jourdain_2024, + author = {Sebastien Jourdain (Kitware) and + Forrest Li and + Julien Finet and + Sankhesh Jhaveri and + Laurenn Lam and + Adnane Belmadiaf and + Matt McCormick and + Scott Wittenburg and + Alireza and + Thibault Bruyère and + Tom Birdsong and + Lucie Macron and + Shreeraj Jadhav and + JiayiXuu and + Patrick Avery and + rodrigobasilio2022 and + Jules BOURDAIS and + gandis and + Erik Ziegler and + RemiCecchinato and + Anne Haley and + Tom Suchel and + TristanWright and + David Thompson and + Mayeul Chassagnard and + Madison Dickson and + Aron Helser and + Paul Elliott and + ocrossi}, + title = {Kitware/vtk-js: v29.7.2}, + month = feb, + year = 2024, + publisher = {Zenodo}, + version = {v29.7.2}, + doi = {10.5281/zenodo.10680530}, + url = {https://doi.org/10.5281/zenodo.10680530} +} + +@article{Billen_Fraters_AGU_2023, + title={A New Method for Assigning Thermal Structure to 2D and 3D Present-day Geodynamic and Seismological Models of Subduction Zones}, + author={Billen, Magali I and Fraters, Menno}, + journal={AGU23}, + year={2023}, + publisher={AGU} +} + +@article{vanderWiel_Hinsbergen_etal_2024, + title = {Linking rates of slab sinking to long-term lower mantle flow and mixing}, + journal = {Earth and Planetary Science Letters}, + volume = {625}, + pages = {118471}, + year = {2024}, + issn = {0012-821X}, + doi = {https://doi.org/10.1016/j.epsl.2023.118471}, + url = {https://www.sciencedirect.com/science/article/pii/S0012821X23004843}, + author = {Erik {van der Wiel} and Douwe J.J. {van Hinsbergen} and Cedric Thieulot and Wim Spakman}, + keywords = {Mantle convection, Slab sinking rates, Mantle mixing, Modelling constraints}, +} + +@article{Sandiford_Craig_timothy_2023, + author = {Sandiford, Dan and Craig, Timothy J}, + title = "{Plate bending earthquakes and the strength distribution of the lithosphere}", + journal = {Geophysical Journal International}, + volume = {235}, + number = {1}, + pages = {488-508}, + year = {2023}, + month = {06}, + issn = {0956-540X}, + doi = {10.1093/gji/ggad230}, + url = {https://doi.org/10.1093/gji/ggad230}, + eprint = {https://academic.oup.com/gji/article-pdf/235/1/488/50659012/ggad230.pdf}, +} + +@ARTICLE{Gea_Negredo_etal_2023, + AUTHOR={Gea, Pedro J. and Negredo, Ana M. and Mancilla, Flor de Lis}, + TITLE={The Gibraltar slab dynamics and its influence on past and present-day Alboran domain deformation: Insights from thermo-mechanical numerical modelling}, + JOURNAL={Frontiers in Earth Science}, + VOLUME={11}, + YEAR={2023}, + URL={https://www.frontiersin.org/articles/10.3389/feart.2023.995041}, + DOI={10.3389/feart.2023.995041}, + ISSN={2296-6463}, + ABSTRACT={The origin and tectonic evolution of the Gibraltar Arc system is the result of a complex geodynamic evolution involving the convergence of the Eurasian and African plates and the dynamic impact of the Gibraltar slab. Although geologic and geophysical data collected in the last few years have increased our knowledge of the Gibraltar Arc region, it is still unclear which are the mechanical links between the Gibraltar slab and the past deformation of the overriding Alboran lithosphere, as well as to which degree this subduction system is presently active. In this study, we use 2D numerical modelling to investigate the impact of the Gibraltar slab dynamics on the deformation of the overriding Alboran lithosphere. Our model simulates a WE generic vertical section at an approximate latitude of 36°N and considers an initial setup at about Burdigalian times (∼20 Ma), when the subduction front position is relatively well constrained by recent tectonic reconstructions. Our modelling shows a switch in the overriding plate (OP) stress state from extensional stresses during the slab rollback to compressional stresses near the trench when the rollback velocity decreases, caused by the change in slab-induced mantle flow. We also find that much of the crustal and lithospheric deformation occur during fast slab rollback and OP extension in the first 10 Myr of evolution, while after that only moderate deformation associated with subduction is predicted. Finally, we find that despite the subduction rollback ceases, the ongoing motion of the deeper portion of the slab induces a mantle flow that causes some amount of west-directed basal drag of the Alboran lithosphere. This basal drag generates interplate compresional stresses compatible with the distribution of intermediate-depth earthquakes in western Alboran.} +} + +@article{Saxena_Dannberg_etal_2023, + author = {Saxena, Arushi and Dannberg, Juliane and Gassmöller, Rene and Fraters, Menno and Heister, Timo and Styron, Richard}, + title = {High-Resolution Mantle Flow Models Reveal Importance of Plate Boundary Geometry and Slab Pull Forces on Generating Tectonic Plate Motions}, + journal = {Journal of Geophysical Research: Solid Earth}, + volume = {128}, + number = {8}, + pages = {e2022JB025877}, + keywords = {global mantle flow models, plate driving forces, plate tectonics}, + doi = {https://doi.org/10.1029/2022JB025877}, + url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2022JB025877}, + eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2022JB025877}, + note = {e2022JB025877 2022JB025877}, + abstract = {Abstract Mantle convection models based on geophysical constraints have provided us with a basic understanding of the forces driving and resisting plate motions on Earth. However, existing studies computing the balance of underlying forces are contradicting, and the impact of plate boundary geometry on surface deformation remains unknown. We address these issues by developing global instantaneous 3-D mantle convection models with a heterogeneous density and viscosity distribution and weak plate boundaries prescribed using different geometries. We find that the plate boundary geometry of the Global Earthquake Model (GEM, Pagani et al., 2018, https://doi.org/10.1177/8755293020931866), featuring open plate boundaries with discrete lithospheric-depth weak zones in the oceans and distributed crustal faults within continents, achieves the best fit to the observed GPS data with a directional correlation of 95.1\% and a global point-wise velocity residual of 1.87 cm/year. A good fit also requires plate boundaries being 3 to 4 orders of magnitude weaker than the surrounding lithosphere and low asthenospheric viscosities between 5 × 1017 and 5 × 1018 Pa s. Models without asthenospheric and lower mantle heterogeneities retain on average 30\% and 70\% of the plate speeds, respectively. Our results show that Earth's plate boundaries are not uniform and better described by more discrete plate boundaries within the oceans and distributed faults within continents. Furthermore, they emphasize the impact of plate boundary geometry on the direction and speed of plate motions and reaffirm the importance of slab pull in the uppermost mantle as a major plate driving force.}, + year = {2023} +} diff --git a/doc/JOSS/1.0/paper.md b/doc/JOSS/1.0/paper.md new file mode 100644 index 000000000..9f327035b --- /dev/null +++ b/doc/JOSS/1.0/paper.md @@ -0,0 +1,135 @@ +--- +title: 'The Geodynamic World Builder: A planetary structure creator for the geosciences' +tags: + - C++ + - CPP + - C + - Fortran + - Python + - Geodynamics + - Earth science + - Tectonics + - Seismology +authors: + - name: Menno R. T. Fraters + orcid: 0000-0003-0035-7723 + affiliation: "1" # (Multiple affiliations must be quoted) + - name: Magali I. Billen + orcid: 0000-0002-7316-1791 + affiliation: "2" + - name: Rene Gassmöller + orcid: 0000-0001-7098-8198 + affiliation: "1" + - name: Arushi Saxena + orcid: 0000-0003-2930-3497 + affiliation: "3" + - name: Timo Heister + orcid: 0000-0002-8137-3903 + affiliation: "3" + - name: Haoyuan Li + orcid: 0000-0003-0676-9884 + affiliation: "2" + - name: Daniel Douglas + orcid: 0000-0002-7871-018X + affiliation: "4" + - name: Juliane Dannberg + orcid: 0000-0003-0357-7115 + affiliation: "1" + - name: Wolfgang Bangerth + orcid: 0000-0003-2311-9402 + affiliation: "5" + - name: Yijun Wang + orcid: 0000-0002-7637-3239 + affiliation: "6" +affiliations: + - name: Universiy of Florida, USA + index: 1 + - name: UC Davis, USA + index: 2 + - name: Clemson University, USA + index: 3 + - name: New Mexico Tech, USA + index: 4 + - name: Colorado State University, USA + index: 5 + - name: University of Oslo, Norway + index: 6 +date: 11 March 2024 +bibliography: paper.bib +--- + +# Summary + +Many Earth science applications require the discretization, parameterization, and/or visualization of complex geological features in a 3D geometry in global or regional settings. A prime example are geodynamic models that have to make assumptions about the Earth's thermal and chemical structure and the geometry of different features such as plates, subducted slabs, or mantle plumes. This structure is needed in instantaneous models, as model initial conditions, or to test different hypotheses and compare model predictions to observations. Other examples are the creation of an Earth velocity structure for seismic forward modeling and hypothesis-testing, or the visualization of tectonic features in structural geology. + +The Geodynamic World Builder (GWB) has been designed to make the creation of complex parameterized models significantly easier. It can also be used to design simple synthetic models and it supports the use of several types of datasets to set up models. Besides setting up initial conditions for geodynamic models, the GWB can also visualize complex 3D geologic, tectonic, and geodynamic settings. + +# Statement of need + +Today's computational resources, infrastructure, and numerical methods allow for the creation of complex numerical models that closely resemble specific locations on the Earth, using 3D geometries and high resolutions. However, the related increase in complexity has also made setting up these more detailed regional or global models exceedingly difficult, especially in three dimensions. Furthermore, investigating the model dynamics often requires testing different scenarios involving variations in model geometry, thermal, or chemical structure, or other model assumptions. Although studies with such complex models have been published, the practical realization of these model setups often have one or many of the following disadvantages: + +1. The configuration is not human-readable. +2. The software is not easily modifiable and extendable. +3. The model setup is not portable to other computing systems or reproducible in other software frameworks. +4. The model setup is not shareable with other users. + +These issues lead to a number of problems with the reproducibility and reliability of modeling studies, which threaten to undermine the predictive power and usefulness of modeling results, and highlighting the need for a way to describe model setups that is easy, efficient, and robust. The GWB has been designed to address these challenges, by creating human readable, parameterized, portable, reproducible, and shareable geodynamic model setups. Critically, the GWB comes with its own programs to visualize the constructed model through applications like Paraview. Creating the models requires no programming knowledge. Therefore, the GWB can be easily used to visualize tectonic and geodynamic settings for publications, teaching, and public outreach. + +![A workflow diagram for how a world builder file can be used to create and visualize a geodynamic model.](workflow_diagram.png) + +The GWB has been used in several published studies to model global fault patterns, plume, and plate dynamics (@Saxena_Dannberg_etal_2023, @Gea_Negredo_etal_2023, @Sandiford_Craig_timothy_2023, and @vanderWiel_Hinsbergen_etal_2024). Other tools to solve this problem have emerged at around the same time as the first GWB release (@Fraters_Thieulot_etal_2019). Examples include GeomIO (@Bauville_Baumann_2019 and @Spang_Baumann_2022), which uses an approach based on vector graphics; Easy (https://easyinit.readthedocs.io/), which uses a more generic function-based approach; UWGeodynamics (@Beucher_Moresi_etal_2019), which is specifically designed for Underworld (@Moresi_Dufour_2002); and GemPy (@Varga_Schaaf_2019 and @Schaaf_Varga_2021), which is designed for structural modeling. The GWB was designed to be a more general planetary structure creator, using the methods shown below. + +# Methods + +To address the challenges outlined in the previous section, the Geodynamic World Builder implements specific code and world parameterization principles. + +## GWB Code Principles +The GWB's software architecture is built around the following principles: + +1. A single text-based input file. +2. Code, language and platform independence: + 1. Support for **Linux**, **macOS** and **Windows**; + 2. Official interfaces for **C++**, **C**, **FORTRAN** and **Python**. +3. Safe parallel execution. +4. Readable and extensible software modules. +5. Strict version numbering to ensure reproducible results. + +These principles are implemented in an object-oriented C++ code with interfaces to other programming languages. All parts a user might want to modify are implemented as plugin systems using interface classes that decouple individual modules and allow the user to easily extend the code with new features. In addition, the GWB includes an extensive automated test suite with benchmarks, integration, and unit tests with high code coverage, memory checking, automatic code indentation, and a spell checker to keep the GWB in a healthy state. + +## GWB World Parameterization Principles + +The GWB's world parameterization principles are built around the idea that a complex model region can be split into individual tectonic features. These tectonic features can be parameterized by defining their location and geometry in terms of points, lines, or areas in a map view. For example, a continental plate can be represented as an area on a map, and the GWB user defines this area. A fault is a linear feature on a map, so the user can define the fault trace as a line at the surface. Users can also provide additional information for a feature, such as a spatially variable thickness or dip angle. The GWB then uses these parameters to create the 3D geometry of the feature, defining its volume. Furthermore, users can attach one or many models to those volumes to define additional properties such as thermal or chemical structure. These can be very simple models, such as a uniform temperature distribution; or follow a more complex distribution, such as a half space cooling model, or a McKenzie model [@McKenzie_1970], or a mass conserving slab temperature model [@Billen_Fraters_AGU_2023]. + +All these tectonic features are bundled in a single input file in standard JSON format, which is human readable, writeable, and editable. The main idea behind this design of the GWB is that users can easily create, modify, and visualize complex parameterized geodynamic or tectonic settings. + +## Example +Below we show an example input file for a Cartesian model that contains a single feature, namely a subducting plate. + +```json +{ + "version": "1.0", + "coordinate system": {"model":"cartesian"}, + "features": + [ + { + "model": "subducting plate", "name": "Slab", "dip point": [0,0], + "coordinates": [[1500e3,1000e3],[1600e3,350e3],[1500e3,0]], + "segments": [{"length":300e3, "thickness": [100e3], "angle": [0,60]}], + "temperature models": [{"model": "plate model", "plate velocity": 0.02}], + } + ] +} +``` + +A more complicated example (only requiring 85 lines, and can be found [here](https://github.com/GeodynamicWorldBuilder/WorldBuilder/blob/GWB-v1.0.0/doc/sphinx/_static/gwb_input_files/BST_19_spherical_models.wb)) features a spherical geometry, a spatially variable subducting plate, continental plate, oceanic plate and plume can be seen in Fig 2. + +![A schematic example of what can be built with 85 lines of a GWB input file formatted in the same way as in the example input file shown above. This includes a slab with variable dip and thickness along strike and down dip, subducting under an oceanic plate on the right side of the ridge, as well as a passive continental margin with layers of variable on the left side of the ridge, and a mantle plume beneath the ridge. The temperature of the continent is linear, the oceanic plates are defined by a half-space cooling model, the slab temperature is defined by a mass conserving temperature model and the plume adds heat based on a Gaussian around the center.\label{fig:example}](../../sphinx/_static/images/user_manual/basic_starter_tutorial/BST_19.png) + + +# Acknowledgements + +We would like to acknowledge all other contributors to the project, especially Lorraine Hwang, Rebecca Fildes, and John Naliboff for their advice and support for this project throughout the years. We would also like to acknowledge NSF for their funding and support through grants EAR-1620618, OCE-1948902, EAR-0949446, EAR-1550901, EAR-1925677, and EAR-2149126. + +# References + + diff --git a/doc/JOSS/1.0/workflow_diagram.png b/doc/JOSS/1.0/workflow_diagram.png new file mode 100644 index 000000000..7762c0e26 Binary files /dev/null and b/doc/JOSS/1.0/workflow_diagram.png differ