Implied heat transport new diagnostic

[mo-abodas]

Description

• Closes New diagnostics of implied heat transports from TOA fluxes #2472
• Link to documentation: https://esmvaltool--3177.org.readthedocs.build/en/3177/recipes/recipe_iht_toa.html

This recipe implements the analysis documented in Pearce and Bodas-Salcedo (2023). If CERES-EBAF is used as input dataset then it produces the results in that paper, albeit with small differences. The differences are due to the Edition of the dataset. The paper uses the latest edition (Ed4.1), whereas the recipe uses an older edition available in obs4MIPs (Ed2.7).

---

Before you get started

• ☝ Create an issue to discuss what you are going to do

Checklist

It is the responsibility of the author to make sure the pull request is ready to review. The icons indicate whether the item will be subject to the 🛠 Technical or 🧪 Scientific review.

• 🛠 This pull request has a descriptive title
• 🛠 Code is written according to the code quality guidelines
• 🛠 Documentation is available
• 🛠 Tests run successfully
• 🛠 The list of authors is up to date
• 🛠 Any changed dependencies have been added or removed correctly
• 🛠 All checks below this pull request were successful

New or updated recipe/diagnostic

• 🧪 Recipe runs successfully
• 🧪 Recipe is well documented
• 🧪 Figure(s) and data look as expected from literature
• 🛠 Provenance information has been added

---

To help with the number of pull requests:

• 🙏 We kindly ask you to review two other open pull requests in this repository

[mo-abodas]

@ehogan @bouweandela thanks for your reviews! I believe I've addressed all your comments, please let me know if you think anything else is needed.

@ehogan , please see below specific responses to your general comments:

Would you consider using more explicit variable names? There are many three letter variable names (e.g. efp, nnn, vvv, zzz, etc.) that do not mean anything to a technical person like me! Also, I would recommend using the more readable point rather than pnt (which I assume means point!) in favour of saving 2 characters (readability counts!)

I've done this in commits 3a56318, ee0a670, 6306ff2. I've expanded most of the three-letter names with more meaningful names. However, there are a couple of exceptions where I think it's better to keep the original names. I've kept efp and mht as variable names and defined the acronyms in the docstring of the ImpliedHeatTransport class. In poisson_solver.py, I've kept the original names in the methods SphericalPoisson.set_matrices and SphericalPoisson.solve. The reason for this is that the short names are more traceable to the names in the paper that describes the numerical algorithm.

There are a number of calls to print() within the single_model_diagnostics.py diagnostic file; given you have initialised a logger, would it be worth using the logger instead?

Done in 449e2e9.

Would it be possible for you to expand your docstrings to include a description of the arguments, please? (There are examples on how to do this in the radiation budget recipe).

Done in 4b44c60, 417f0a4.

"The preferred way of wrapping long lines is by using Python’s implied line continuation inside parentheses, brackets and braces. Long lines can be broken over multiple lines by wrapping expressions in parentheses. These should be used in preference to using a backslash for line continuation.", see PEP8. You can use something like Black to auto-format the diagnostic files to see how to do this (if you use black on the whole file, the ESMValTool pre-commit hooks will make changes / the checks will require some changes).

Done in 2f54ae3.

I noticed there are a number of occurances of cube.data; running this command will realise the data. Is it possible to use cube instead to enable the benefits of Dask?

Done in f4f8c58. Exceptions are calls to matplotlib plotting functions that require numpy arrays as arguments.

There are a number of "magic numbers" used in the diagnostic files; would it be possible to clarify what they are, please? Adding a comment or a descriptive variable are a couple of examples of how to achieve this 😊 (I have commented on two examples)

Done in 000206c, 015eec3, 40b6081.

There are a number of copys used in the diagnostic files; are they all necessary?

Only the one in the poisson solver. I've replaced the others.
Done in 9c64e8e.

Is it possible to use an already existing Poisson solver, for example, the one in SciPy: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.poisson.html?

That is something completely different, it provides samples of a Poisson distribution. The solver in this recipe solves the Poisson differential equation over the sphere.

[valeriupredoi]

refreshing my stale review - my worries were just numba-related, all good, serious heavy-lifting review done by others 🍺

[ehogan]

@ehogan @bouweandela thanks for your reviews! I believe I've addressed all your comments, please let me know if you think anything else is needed.

Nice work @alejandrobodas! 🥳

There are a number of calls to print() within the single_model_diagnostics.py diagnostic file; given you have initialised a logger, would it be worth using the logger instead?

Done in 449e2e9.

Should the print on L986 also be updated?

[ehogan]

Many thanks for all your hard work on addressing our review comments, @alejandrobodas! 🥳 I spotted a few minor things 😊

[mo-abodas]

@ehogan thanks for spotting a few mistakes! I've fixed them as suggested. I've deleted the print statement because it didn't really provide any useful information.

[ehogan]

Thanks @alejandrobodas! 🥳

[alistairsellar]

🥳 Well done @mo-abodas and everyone who helped with this!

[mo-abodas]

Thanks everyone for your help!