Skip to content

Add nexus module technical documentation #442

Draft
awais307 wants to merge 8 commits into
doc/2025-updatefrom
doc_water
Draft

Add nexus module technical documentation #442
awais307 wants to merge 8 commits into
doc/2025-updatefrom
doc_water

Conversation

@awais307

Copy link
Copy Markdown
Contributor

Required: This PR adds the technical documentation of nexus module

How to review

Required: describe specific things that reviewer(s) must do, in order to ensure that the PR achieves its goal.
If no review is required, write “No review:” and describe why.

PR checklist

  • Continuous integration checks all ✅
  • Add or expand tests; coverage checks both ✅
  • Add, expand, or update documentation.
  • Update doc/whatsnew.

@awais307 awais307 self-assigned this Oct 21, 2025
@awais307 awais307 added the doc Improvements or additions to documentation label Oct 21, 2025

@adrivinca adrivinca left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work @awais307 . this saves us a lot of time.
I will go through again demand again and keep in mind to update the desalination part soon.
@Wegatriespython could revise the water impacts part in index and climate_impacts. and please read-though the cooling file if anything should be changed

* Wastewater treatment coverage requirements
* Water use efficiency improvements

**SDG 7**: Affordable and clean energy

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should remove SDG7 as it is not in the water module. it was just in some NAVIGATE branches, but never migrated, and now obsolete


Basin-scale surface water availability is derived from global hydrological models that simulate the terrestrial water cycle:

* **PCR-GLOBWB 2** (Sutanudjaja et al., 2018 :cite:`sutanudjaja_2018_pcrglobwb`): A global hydrological model at 5 arcmin resolution (~10km at equator) that simulates river discharge, soil moisture, and groundwater recharge

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe here @Wegatriespython can jump in and directly update with what the state will be in a few months form now. basically using all the ISIMIP 3b ensemble, or just CWatM.

Vignesh can also add figures on seasonality or extremes

Current and Projected Capacity
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Historical desalination capacity (base year ~2020):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I need to review once we have updated numbers from Marina

* More frequent and severe droughts
* Changes in seasonal water availability

**Direct Impacts on Energy**:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we don't have changes in hydropower anymore, not on once-through cooling (maybe never had) or Increased cooling water requirements. also no Impacts on renewable energy resources


Climate change affects the water-energy-land nexus through multiple pathways:

**Direct Impacts on Water**:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Several of these things are on the hydrological model side and affect surface and groundwater.
maybe we could make it clear, and then mostly focus on the direct impacts in MESSAGE


The MESSAGEix-Nexus module is typically applied within the SSP-RCP scenario framework (O'Neill et al., 2014 :cite:`oneill_2014_ssp`; Riahi et al., 2017 :cite:`riahi_2017_ssp`):

* **SSP1-2.6**: Sustainability pathway with strong mitigation

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think from here on @Wegatriespython should edit it. not needed to repeat what is in index.rst (maybe one could be more synthetic there)

@khaeru khaeru changed the title [Draft] Add nexus module technical documentation Add nexus module technical documentation Oct 30, 2025
@Wegatriespython

Wegatriespython commented Mar 28, 2026

Copy link
Copy Markdown
Contributor

Thanks for the documentation PR @awais307. As it stands there have been significant changes since this PR and much will have to be redone. I think I can re-use some elements of this PR when filing an updated version. However as it stands I think there are a few critical issues with the PR here :

  1. Claims of model capabilities which do not exist—IBWT, compound events, hybrid cooling tech, the cooling temperature equation is misleading and the implementation is updated now anyway. The adaptation claims are over-stated. The climate impacts section is aspirational but non-existent as the model is and can be used as.
  2. Mixes paper results with documentation, paper results are from a very specific scenario protocol and research question. Second claims on adaptation costs and vulnerabilities are quite colourful. The paper is much more forthcoming with its limitations.
  3. Major model limitations omission. In general the model has a fundamental resolution mismatch—supply is orders of magnitude above demand. The effect on energy prices is marginal. The docs leave the impression that the module is delivering highly policy relevant insights, of the sort not supported by the model and what MESSAGE can resolve at its present capabilities.

@khaeru khaeru force-pushed the doc/2025-update branch from 9714ddb to ef70f12 Compare May 22, 2026 10:27
@khaeru khaeru added the water MESSAGEix-Nexus (water) variant label May 22, 2026
@khaeru khaeru force-pushed the doc/2025-update branch from cdcc4b2 to 1777d0f Compare June 2, 2026 12:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Improvements or additions to documentation water MESSAGEix-Nexus (water) variant

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants