Update for current version of MESSAGEix-GLOBIOM

[khaeru]

We are updating the documentation of MESSAGEix-GLOBIOM. This is the master issue for all related issues/PRs.

• Revisions should be made by 2019-08-02.
• Each set of changes should be reviewed by another person by 2019-08-07. Review assignments (internal link).
• The Assignments file is in a SharePoint folder; please deposit any related extra files in this directory.
• Collect further suggestions for improvements by adding issues to message_doc repository (all)

Tasks/assignments

• General

  • Adjust overview section, introduce ixmp framework. @danielhuppmann
  • Adjust timesteps (remove 1990-2010 periods). @guofei2003
  • Update model application references to include latest publications. @gidden
  • More consistently add references to underlying data sources. @behnam2015
  • Adjust citation (incl. authors), obtain doi. @volker-krey

• Energy

  • Add description of add on technologies to relevant sections (e.g., CHP). @OFR-IIASA
  • Add description of how blending is modeled. @OFR-IIASA
  • Update CSP representation (SM1/SM3 variants) based on Johnson et al. (2016). @Jihoon
  • Add water for energy representation. @scparkinson add figures, text and refs for water4energy implementation #19
  • Add description of policy/NDC implementation. (OFR?, Add citation of relevant paper – which?)

• Mathematical appendix: 

  • remove and link to MESSAGEix documentation (release 1.2, incl. Add-on technologies).

• Other:

  • ensure that all sections can be referenced.

@danielhuppmann

• MACRO: adjust link to appendix. @volker-krey
• Adding sections on specific versions of MESSAGE (e.g. MESSAGE-Access, MESSAGE-Transport). @MiguelPobleteCazenave @khaeru
  Doesn't need to happen for this milestone, necessarily.

[gidden]

Should we automate the versioning here? E.g., could define a variable in conf.py like MESSAGE_VERSION=message_ix.__version__ and utilize it throughout..

[gidden]

Also, I note in the reviewer assignments, I am assigned to review "climate". Who is revising?

[adrivinca]

I went through the sessions I was assigned to revise (some related to GLOBIOM and water).
I do not have major comments, the explanation and reference look exhaustive.

Only comment perhaps is to increase the fonts of figure 19, which is not really readable.
But I cannot make the changes as I do not have the source image

[Ruslana22]

I read the documentation and have the following comments/remarks:

1. General
   1.1. It is not clear (to me:-)) whether the model is MESSAGEix or MESSAGE? Maybe a clarification should be added
   1.2. I think that the description of data sources for the model and the parameters should be stated in the beginning. I know that it’s not an easy task, but I think that a paragraph-long description that the model is based on the actual energy and economic data for the years 1960-2015 (is it so?)+ the official projections for economic development for the years 2020-2100 would be beneficial.
   1.3. In addition, the question of what is input and what is the output of the model is unclear. For instance, if socio –economic development from SSPs is an input, I would recommend titling this section differently, e. g. Input of drivers of future socio-econ development, or something more clear for external reader.

2. Overview
   2.1. I suggest to move Fig 1 up to appear just after the first paragraph, so that the structure is visualized from the first glance on the page
   2.2. In SSPs section, the 3 SSPs out of five are presented. Is MESSAGE run for all 3 SSPs? or only SSP2? is one of them so called "baseline scenario" and the other are alternatives?
   2.3 then the natural question of external reader is if the scenarios are plugged in as given to MESSAGE, what is its output? what is left to evaluate. I know that there is a lot to, but maybe it's worth to address briefly. and refer to latest papers

3. Energy
   3.1. Suggest putting the figure of MESSAGE structure after the first paragraph + the link to mathematical representation of the model.
   3.2. There is a mentioning of mathematical representation of MESSAGE in the end of this section. I recommend to add the hyperlink there too
   3.3. Energy resource endowments – this section is empty – only redirects to subsections. I would add, again that historical data of resource utilization until 2015 are based on official statistics, and the developments of reserves and resources are described in subsections to follow+add link to math representation in "3 Domestic Resources"
   3.4. Non-Biomass Renewable Resources- Title for row 1 in table 1 is missing
   3.5. add hyperlink from Energy conversion description to sub section on conversion in math documentation
   3.6. Energy demand – in this sub section of documentation, I would recommend to start from clear statement that the energy demand by 7 final users till the end of 21st century is generated based on forecasts for GDP and population. And, if possible add the link to mathematical representation of the scenario generator. In addition, the last paragraph before table 21 states that “final energy is converted to useful energy in each region by using the average final-to-useful energy efficiencies used in the MESSAGE”. is it possible to report these final-to-useful energy efficiencies – what are the values or reference where they come from?