the Creative Commons Attribution 4.0 License.
the Creative Commons Attribution 4.0 License.
| 28 Aug 2024
The Earth Science Box Modeling Toolkit (ESBMTK)
Abstract. The Earth Science Box Modeling Toolkit (ESBMTK) is a Python library designed for building and analyzing box models in Earth science. It uses a modular, object-oriented approach to study topics like the long-term carbon cycle and the impact of atmospheric CO2 changes on seawater chemistry. ESBMTK allows users to define models in a straightforward and readable way, which also serves as documentation. These model definitions are then converted into equations and solved using standard numerical libraries. The toolkit includes features for common box modeling tasks such as gas exchange between the ocean and atmosphere, marine carbonate chemistry, and isotope calculations. ESBMTK has been effectively used in both teaching and research settings. While the library is continually being improved, its core interface is stable and comes with extensive documentation.
-
Notice on discussion status
The requested preprint has a corresponding peer-reviewed final revised paper. You are encouraged to refer to the final revised version.
-
Preprint
(732 KB)
-
The requested preprint has a corresponding peer-reviewed final revised paper. You are encouraged to refer to the final revised version.
- Preprint
(732 KB) - Metadata XML
- BibTeX
- EndNote
- Final revised paper
Journal article(s) based on this preprint
Interactive discussion
Status: closed
-
CEC1: 'Comment on egusphere-2024-1864', Astrid Kerkweg, 06 Sep 2024
Dear authors,
in my role as Executive editor of GMD, I would like to bring to your attention our Editorial version 1.2: https://www.geosci-model-dev.net/12/2215/2019/
This highlights some requirements of papers published in GMD, which is also available on the GMD website in the ‘Manuscript Types’ section: http://www.geoscientific-model-development.net/submission/manuscript_types.html
In particular, please note that for your paper, the following requirement has not been met in the Discussions paper:
- "The main paper must give the model name and version number (or other unique identifier) in the title."
Please add a version number for ESBMTK in the title upon your revised submission to GMD.
Yours, Astrid Kerkweg (GMD Executive Editor)
Citation: https://doi.org/10.5194/egusphere-2024-1864-CEC1 -
AC1: 'Reply on CEC1', Ulrich Wortmann, 06 Nov 2024
will do
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC1
-
RC1: 'Comment on egusphere-2024-1864', Anonymous Referee #1, 13 Nov 2024
Wortmann et al. present the Earth Science Box Modeling Toolkit (ESBMTK), which is a Python library designed for building and analyzing box models in Earth science. It uses a modular, object-oriented approach to study topics like the long-term carbon cycle and the impact of atmospheric CO2 changes on seawater chemistry. ESBMTK separates model geometry from the underlying numerical implementation, and thus allows users to focus on the conceptual challenges, rather than mathematical theory. Such a tool is very useful for teaching and research requiring fast conceptual models. In addition to predefined setup, the user can customize rather easily his/her own model such as the number and volume of boxes/reservoirs, the flux between them, the isotope species, ... This tool will be very useful for the climate community, and I therefore recommend publication after minor revisions.
General remarks
- Several species are already defined in species_definition.py such as stable water isotope 2H and 18O, 13C, ... I would recommend to add the 14C because it is quite usual to use ocean box modeling to model Δ14C, especially in the framework of IntCal. See for example Bard et al. (1997, https://doi.org/10.1016/S0012-821X(97)00082-4).
- In my opinion, it would be beneficial to give more details on the modeling of stable water isotopes 2H and 18O, and not only on the carbon-related species. The transport between the ocean box models are quite simple in that case (one to one), but the authors could mention how to set up a simulation when considering fractionation effect between atmosphere and ocean boxes e.g, the evaporation from the ocean to the atmosphere.
- The authors discuss the ESBMTK results with Boudreau et al. (2010a) model. They show the good ability of ESBMTK to replicate other models, which is important to encourage potential users to switch to ESBMTK. One other important aspect is to show how realistic model results are. Is there any way for the authors to compare the ESBMTK results with observations for a typical simulation (or with the setup of Boudreau et al. (2010a))?
Minor and technical comments
- Line 49: a point is missing.
- Legend of Figure 1: remove ". caption".
- Lines 62-63: In the following, we only describe the pertinent implementation details.
- Table 2: I would show the information for the all the fluxes, and in the order F1, F2, F3, ..., F9.
- Legend of Table 3: all parameters are after Boudreau et al. (2010a).
Citation: https://doi.org/10.5194/egusphere-2024-1864-RC1 -
AC2: 'Reply on RC1', Ulrich Wortmann, 02 Dec 2024
We would like to thank the anonymous referee for their time and thoughtful comments. Below is our response.
-
The idea to add 14C as species is a good one, and we can see the utility of it. We added Δ14C to the list of carbon species, however, that is different from a full implementation of how 14C fractionates relative to 12C during air-sea transfer, photosynthesis, and CO2 speciation. This would require that ESBMTK had the necessary data structures to express isotope systems with more than 2 components, as well as the necessary code to deal with radioactive decay. Given the universal nature of the library (as opposed to a specific model), this is no easy feat to implement. We are however grateful for the suggestion as this is something we have not thought about, but will keep in mind for future revisions.
-
There is no doubt that the current manual does a poor job in showcasing all aspects of the ESBMTK library. The idea to start the isotope chapter with a simple system like oxygen is however a good one, and we will add this to the isotope section in the manual.
-
We are not what the referee is asking since the MS provides a detailed comparison with the Boudreau model?
Much thanks is due for finding the editorial mishaps listed under technical comments, we will fix these in the revised version.
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC2 -
-
AC3: 'Reply on RC1', Ulrich Wortmann, 02 Dec 2024
Publisher’s note: this comment is a copy of AC2 and its content was therefore removed on 2 December 2024.
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC3 - AC5: 'Reply on RC1 - revised', Ulrich Wortmann, 12 Dec 2024
-
RC2: 'Comment on egusphere-2024-1864', Shihan li, 25 Nov 2024
This manuscript introduces the Earth Science Box Modeling Toolkit (ESBMTK), a Python library designed to streamline the build and operation of box models. The toolkit incorporates many commonly used processes such as air-sea exchange, marine carbonate chemistry, and isotope calculations. Its feasibility and robustness are validated through replicating the work by Boudreau et al., 2010.
Given the significant utility of box models in the Earth Science, ESBMTK has considerable potential for applications in both teaching and research settings. Below are several suggestions that, hopefully, could help further enhance the quality and impact of this project:
- The toolkit’s ability to separate model geometry from its underlying numerical implementation is highly convenient, particularly for users without extensive programming experience. However, this abstraction also hides the core functions, making debugging more challenging. One potential enhancement could be enabling the model to output the codes for governing equation it generates during runtime. Such a feature would not only improve the model transparency but also serve as a valuable resource for educational purposes, allowing users to better understand the mechanics of the model.
- Several processes and their parameterizations are described in Section 2. However, I found it somewhat challenging to clearly link these processes to the toolkit framework as depicted in Figure 1. It would be helpful if the authors could integrate these processes explicitly within the framework illustration or provide some example codes.
- I believe perturbation experiments are crucial for exploring system behavior under various conditions. I was happy to learn from the documentation that the model accepts external forcings. I suggest highlighting this feature more prominently and giving brief introduction on its implementation in the main text
- Several things might need further clarifications.
- Line 99, the authors state that “the above parameters at the beginning of each run and assumes that they are constant over the integration interval.” However, it is unclear what “the above parameters” specifically refer to. My interpretation is that this might relate to thermodynamic and kinetic constants. However, the carbonate system is typically time-dependent and calculated in each integration.
- Again, from the same paragraph, the authors state that modeling temperatures remain constant throughout the runtime. However, this seems inconsistent with examples where transient and long-term carbon cycles are simulated. Since temperature can affect thermodynamic constants in the carbon system, this assumption may not be realistic. If my understanding is incorrect, additional explanation would be appreciated to resolve this confusion.
- Line 105, It is noted that [H+] is initially calculated using thepyco2sys library, and subsequently, the iterative approach of Follows et al. (2006) is applied. I’m confused by the rationale behind using two different methods for this calculation.
- Carbon isotopes are crucial tracers in carbon cycle modeling. In Example 4 (https://github.com/uliw/ESBMTK-Examples/blob/main/Examples_from_the_manual/po4_4.png), the steady-state surface box δ¹³C reaches approximately 8‰, which is not realistic. Since the Boudreau et al. (2010) model does not incorporate isotope modeling, I recommend that the authors conduct additional validation work for this component.
Citation: https://doi.org/10.5194/egusphere-2024-1864-RC2 -
RC3: 'Reply on RC2', Shihan li, 25 Nov 2024
One thing I forgot to mention. The code provided in Listing 1 does not function as expected on my laptop (Macbook Pro 2019, 2.6 GHz 6-Core Intel Core i7), whereas the code for the same example in the online documentation works correctly.
Citation: https://doi.org/10.5194/egusphere-2024-1864-RC3 -
AC6: 'Reply on RC3 - revised', Ulrich Wortmann, 12 Dec 2024
The comment was uploaded in the form of a supplement: https://egusphere.copernicus.org/preprints/2024/egusphere-2024-1864/egusphere-2024-1864-AC6-supplement.pdf
-
AC6: 'Reply on RC3 - revised', Ulrich Wortmann, 12 Dec 2024
-
AC4: 'Reply on RC2', Ulrich Wortmann, 02 Dec 2024
We would like to thank Shihan Li for their time and thoughtful comments. Below is our response.
-
The ability to save the equations for debugging purposes already exists in the model, it is however not well documented. We are thankful for the suggestion and we will add a section to the manual explaining how to do this.
-
This is a good point. Splitting Fig 1 into two figures should allow for enough space to add this.
-
Good point as well. We will expand the section describing how to add external forcings and add an additional paragraph to the MS.
-
a & b) The language is indeed not clear, but the reviewers reading is correct. As stated in line 100, "In other words, models that require changes in temperature and pressure are currently beyond the scope of ESBMTK". We are aware that this is limitation, specifically for models that try to capture global warming, and thus need time dependent adjustments for changes in ocean temperature. We would like to point out however, that many, if not most of the published paleoceanography box-models have similar restrictions.
That being said, we are actively working to implement a feature that allows for time-dependent temperature changes, but it is unlikely that this will be ready before next summer.
4c) The carbonate system is fully defined if we know at least two of it components. If we, e.g., know the concentration of total alkalinity (TA) and dissolved organic carbon (DIC), we can calculate all other carbon species. This is however computationally expensive. Follows et al. 2006 showed that if we have a reasonable guess for the initial [H+] at time $i-1$, one can directly compute the concentration of all carbon species with sufficient precision based on the concentrations of TA and DIC at time $i$. This is computationally highly efficient, but relies on a suitable initial estimate for [H+] which we obtain from pyco2sys.
-
The carbon-isotope example in the manual was never meant to be realistic (for that matter neither is the P-cycle model), it was merely a demonstration on how to do it. We would like to note that the isotope calculations are covered by unit-tests and should be correct. That being said, both reviewers mentioned to improve the isotope examples and we will update the manual accordingly.
-
Thank you for noticing this. We will update the code in listing 1 accordingly.
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC4 -
Interactive discussion
Status: closed
-
CEC1: 'Comment on egusphere-2024-1864', Astrid Kerkweg, 06 Sep 2024
Dear authors,
in my role as Executive editor of GMD, I would like to bring to your attention our Editorial version 1.2: https://www.geosci-model-dev.net/12/2215/2019/
This highlights some requirements of papers published in GMD, which is also available on the GMD website in the ‘Manuscript Types’ section: http://www.geoscientific-model-development.net/submission/manuscript_types.html
In particular, please note that for your paper, the following requirement has not been met in the Discussions paper:
- "The main paper must give the model name and version number (or other unique identifier) in the title."
Please add a version number for ESBMTK in the title upon your revised submission to GMD.
Yours, Astrid Kerkweg (GMD Executive Editor)
Citation: https://doi.org/10.5194/egusphere-2024-1864-CEC1 -
AC1: 'Reply on CEC1', Ulrich Wortmann, 06 Nov 2024
will do
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC1
-
RC1: 'Comment on egusphere-2024-1864', Anonymous Referee #1, 13 Nov 2024
Wortmann et al. present the Earth Science Box Modeling Toolkit (ESBMTK), which is a Python library designed for building and analyzing box models in Earth science. It uses a modular, object-oriented approach to study topics like the long-term carbon cycle and the impact of atmospheric CO2 changes on seawater chemistry. ESBMTK separates model geometry from the underlying numerical implementation, and thus allows users to focus on the conceptual challenges, rather than mathematical theory. Such a tool is very useful for teaching and research requiring fast conceptual models. In addition to predefined setup, the user can customize rather easily his/her own model such as the number and volume of boxes/reservoirs, the flux between them, the isotope species, ... This tool will be very useful for the climate community, and I therefore recommend publication after minor revisions.
General remarks
- Several species are already defined in species_definition.py such as stable water isotope 2H and 18O, 13C, ... I would recommend to add the 14C because it is quite usual to use ocean box modeling to model Δ14C, especially in the framework of IntCal. See for example Bard et al. (1997, https://doi.org/10.1016/S0012-821X(97)00082-4).
- In my opinion, it would be beneficial to give more details on the modeling of stable water isotopes 2H and 18O, and not only on the carbon-related species. The transport between the ocean box models are quite simple in that case (one to one), but the authors could mention how to set up a simulation when considering fractionation effect between atmosphere and ocean boxes e.g, the evaporation from the ocean to the atmosphere.
- The authors discuss the ESBMTK results with Boudreau et al. (2010a) model. They show the good ability of ESBMTK to replicate other models, which is important to encourage potential users to switch to ESBMTK. One other important aspect is to show how realistic model results are. Is there any way for the authors to compare the ESBMTK results with observations for a typical simulation (or with the setup of Boudreau et al. (2010a))?
Minor and technical comments
- Line 49: a point is missing.
- Legend of Figure 1: remove ". caption".
- Lines 62-63: In the following, we only describe the pertinent implementation details.
- Table 2: I would show the information for the all the fluxes, and in the order F1, F2, F3, ..., F9.
- Legend of Table 3: all parameters are after Boudreau et al. (2010a).
Citation: https://doi.org/10.5194/egusphere-2024-1864-RC1 -
AC2: 'Reply on RC1', Ulrich Wortmann, 02 Dec 2024
We would like to thank the anonymous referee for their time and thoughtful comments. Below is our response.
-
The idea to add 14C as species is a good one, and we can see the utility of it. We added Δ14C to the list of carbon species, however, that is different from a full implementation of how 14C fractionates relative to 12C during air-sea transfer, photosynthesis, and CO2 speciation. This would require that ESBMTK had the necessary data structures to express isotope systems with more than 2 components, as well as the necessary code to deal with radioactive decay. Given the universal nature of the library (as opposed to a specific model), this is no easy feat to implement. We are however grateful for the suggestion as this is something we have not thought about, but will keep in mind for future revisions.
-
There is no doubt that the current manual does a poor job in showcasing all aspects of the ESBMTK library. The idea to start the isotope chapter with a simple system like oxygen is however a good one, and we will add this to the isotope section in the manual.
-
We are not what the referee is asking since the MS provides a detailed comparison with the Boudreau model?
Much thanks is due for finding the editorial mishaps listed under technical comments, we will fix these in the revised version.
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC2 -
-
AC3: 'Reply on RC1', Ulrich Wortmann, 02 Dec 2024
Publisher’s note: this comment is a copy of AC2 and its content was therefore removed on 2 December 2024.
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC3 - AC5: 'Reply on RC1 - revised', Ulrich Wortmann, 12 Dec 2024
-
RC2: 'Comment on egusphere-2024-1864', Shihan li, 25 Nov 2024
This manuscript introduces the Earth Science Box Modeling Toolkit (ESBMTK), a Python library designed to streamline the build and operation of box models. The toolkit incorporates many commonly used processes such as air-sea exchange, marine carbonate chemistry, and isotope calculations. Its feasibility and robustness are validated through replicating the work by Boudreau et al., 2010.
Given the significant utility of box models in the Earth Science, ESBMTK has considerable potential for applications in both teaching and research settings. Below are several suggestions that, hopefully, could help further enhance the quality and impact of this project:
- The toolkit’s ability to separate model geometry from its underlying numerical implementation is highly convenient, particularly for users without extensive programming experience. However, this abstraction also hides the core functions, making debugging more challenging. One potential enhancement could be enabling the model to output the codes for governing equation it generates during runtime. Such a feature would not only improve the model transparency but also serve as a valuable resource for educational purposes, allowing users to better understand the mechanics of the model.
- Several processes and their parameterizations are described in Section 2. However, I found it somewhat challenging to clearly link these processes to the toolkit framework as depicted in Figure 1. It would be helpful if the authors could integrate these processes explicitly within the framework illustration or provide some example codes.
- I believe perturbation experiments are crucial for exploring system behavior under various conditions. I was happy to learn from the documentation that the model accepts external forcings. I suggest highlighting this feature more prominently and giving brief introduction on its implementation in the main text
- Several things might need further clarifications.
- Line 99, the authors state that “the above parameters at the beginning of each run and assumes that they are constant over the integration interval.” However, it is unclear what “the above parameters” specifically refer to. My interpretation is that this might relate to thermodynamic and kinetic constants. However, the carbonate system is typically time-dependent and calculated in each integration.
- Again, from the same paragraph, the authors state that modeling temperatures remain constant throughout the runtime. However, this seems inconsistent with examples where transient and long-term carbon cycles are simulated. Since temperature can affect thermodynamic constants in the carbon system, this assumption may not be realistic. If my understanding is incorrect, additional explanation would be appreciated to resolve this confusion.
- Line 105, It is noted that [H+] is initially calculated using thepyco2sys library, and subsequently, the iterative approach of Follows et al. (2006) is applied. I’m confused by the rationale behind using two different methods for this calculation.
- Carbon isotopes are crucial tracers in carbon cycle modeling. In Example 4 (https://github.com/uliw/ESBMTK-Examples/blob/main/Examples_from_the_manual/po4_4.png), the steady-state surface box δ¹³C reaches approximately 8‰, which is not realistic. Since the Boudreau et al. (2010) model does not incorporate isotope modeling, I recommend that the authors conduct additional validation work for this component.
Citation: https://doi.org/10.5194/egusphere-2024-1864-RC2 -
RC3: 'Reply on RC2', Shihan li, 25 Nov 2024
One thing I forgot to mention. The code provided in Listing 1 does not function as expected on my laptop (Macbook Pro 2019, 2.6 GHz 6-Core Intel Core i7), whereas the code for the same example in the online documentation works correctly.
Citation: https://doi.org/10.5194/egusphere-2024-1864-RC3 -
AC6: 'Reply on RC3 - revised', Ulrich Wortmann, 12 Dec 2024
The comment was uploaded in the form of a supplement: https://egusphere.copernicus.org/preprints/2024/egusphere-2024-1864/egusphere-2024-1864-AC6-supplement.pdf
-
AC6: 'Reply on RC3 - revised', Ulrich Wortmann, 12 Dec 2024
-
AC4: 'Reply on RC2', Ulrich Wortmann, 02 Dec 2024
We would like to thank Shihan Li for their time and thoughtful comments. Below is our response.
-
The ability to save the equations for debugging purposes already exists in the model, it is however not well documented. We are thankful for the suggestion and we will add a section to the manual explaining how to do this.
-
This is a good point. Splitting Fig 1 into two figures should allow for enough space to add this.
-
Good point as well. We will expand the section describing how to add external forcings and add an additional paragraph to the MS.
-
a & b) The language is indeed not clear, but the reviewers reading is correct. As stated in line 100, "In other words, models that require changes in temperature and pressure are currently beyond the scope of ESBMTK". We are aware that this is limitation, specifically for models that try to capture global warming, and thus need time dependent adjustments for changes in ocean temperature. We would like to point out however, that many, if not most of the published paleoceanography box-models have similar restrictions.
That being said, we are actively working to implement a feature that allows for time-dependent temperature changes, but it is unlikely that this will be ready before next summer.
4c) The carbonate system is fully defined if we know at least two of it components. If we, e.g., know the concentration of total alkalinity (TA) and dissolved organic carbon (DIC), we can calculate all other carbon species. This is however computationally expensive. Follows et al. 2006 showed that if we have a reasonable guess for the initial [H+] at time $i-1$, one can directly compute the concentration of all carbon species with sufficient precision based on the concentrations of TA and DIC at time $i$. This is computationally highly efficient, but relies on a suitable initial estimate for [H+] which we obtain from pyco2sys.
-
The carbon-isotope example in the manual was never meant to be realistic (for that matter neither is the P-cycle model), it was merely a demonstration on how to do it. We would like to note that the isotope calculations are covered by unit-tests and should be correct. That being said, both reviewers mentioned to improve the isotope examples and we will update the manual accordingly.
-
Thank you for noticing this. We will update the code in listing 1 accordingly.
Citation: https://doi.org/10.5194/egusphere-2024-1864-AC4 -
Peer review completion
Journal article(s) based on this preprint
Viewed
| HTML | XML | Total | BibTeX | EndNote | |
|---|---|---|---|---|---|
| 423 | 105 | 43 | 571 | 11 | 10 |
- HTML: 423
- PDF: 105
- XML: 43
- Total: 571
- BibTeX: 11
- EndNote: 10
Viewed (geographical distribution)
| Country | # | Views | % |
|---|---|---|---|
| United States of America | 1 | 206 | 36 |
| Canada | 2 | 58 | 10 |
| Brazil | 3 | 37 | 6 |
| China | 4 | 34 | 6 |
| United Kingdom | 5 | 26 | 4 |
| Total: | 0 |
| HTML: | 0 |
| PDF: | 0 |
| XML: | 0 |
- 1
- 206
Ulrich Georg Wortmann
Tina Tsan
Mahrukh Niazi
Ruben Navasardyan
Magnus-Roland Marun
Bernardo S. Chede
Jingwen Zhong
Morgan Wolfe
The requested preprint has a corresponding peer-reviewed final revised paper. You are encouraged to refer to the final revised version.
- Preprint
(732 KB) - Metadata XML