iiasa / message_doc Goto Github PK

As identified by @OFR-IIASA in this discussion on #25:

The suggested publication, rogelj_indc_2017, is already part of the description; this describes the methodology.

The second publication is a reference we require for "which" policies we have implemented. This was supposed to be part of a paper published by a colleague at PBL. The paper is still not out, so I was wondering if there is another source we can quote. @volker-krey Possibly we can link to http://www.climatepolicydatabase.org/

All tables throughout the files

On the website (http://ienecat.iiasa.ac.at:8787/message_doc/message_globiom/) a page called Refences is visible, however it is not linked to the actual bibliography site. How can we do this?

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 #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.

As suggested here in #27:

We may want to refer to the original GDP trajectories (Dellink probably?) and just say that we supplied these trajectories to calibration [routines].

As discussed here in #25.

On #28, @volker-krey wrote in this review (lightly edited and emphasis added).

[U]sing the example of coal methanol-to-gasoline with CCS (meth_coal_ccs in AFR for 2030)[…] I can reproduce the 85% capture rate for the residual emissions, i.e. the emissions excluding the carbon that remains in the fuel produced. My suggestion would be to provide two capture rates with a clear definition in this table:

i. the current capture rate as a fraction of the process CO2 emissions and
ii. the capture rate relative to the carbon content of the feedstock.

For the above example, the latter is about 55% as a significant share of carbon remains in the fuel. The former number is interesting from an engineering point of view and describes the efficiency of the capture process. The latter number is particularly relevant for the biomass-based CDR technologies as it describes the potential to sequester carbon from the atmosphere. Obviously for processes that produce carbon-free energy carriers like electricity of hydrogen the two are the same.

That PR was assigned to @OFR-IIASA, but I leave this follow-up issue unassigned.

there are a few issues right now in the latex writing that will need to be updated to support latex writing

• change all unicode characters to their math equivalents (tau, sigma)
• update all linebreaks using \left.and \right. around line breaks (\\)
• fix figure caption indentation

An example of all the lines that need to be fixed are in #7

As suggested by @gidden on #27 by @volker-krey:

A lot of this text [describing MACRO per se] can be moved to the core message_ix docs, given that many of the operations are consistent across any implemented MESSAGE[-MACRO] model.

This will require two linked PRs:

• One on this repo, removing these sections and replacing with an intersphinx link to the correct section of the message_ix docs. —#51
• One on message_ix, adding the corresponding sections.

Per this helpful comment @Ruslana22, address the following issues by:

• one or more PRs, and
• opening new issues, if needed.

General

1.1 It is not clear (to me:-)) whether the model is MESSAGEix or MESSAGE? Maybe a clarification should be added

• Use 'MESSAGE' or 'MESSAGEix' consistently throughout; add to the style guide #10 so future authors do the same.

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.

• Add an early, paragraph-long description of model data sources.

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.

• Change this section title.

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.

• Move the figure.

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?

• Update prefatory text to clarify this issue.

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

• Consider w.r.t. item 1.3 above.

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

• Add/move the figure.
• Add two intersphinx references to the message_ix core.

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

• Fix the table.

3.5. add hyperlink from Energy conversion description to sub section on conversion in math documentation

• Add the link.

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.

• Add text.

And, if possible add the link to mathematical representation of the scenario generator.

• Add the link.

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?

• Address this comment.

Once linking directly to specific references is possible (via Sphinx), add links from all citations to respective references

How to get more detail information about "scenario generator" and use it to extrapolate energy demand into the future

As identified here in #27. This pertains to the heading "Macro-economic parameters" in source/annex/macro.rst.

To keep individual sections concise/to prevent over-cluttering throughout the documentation, while still having enough detail, it might be worthwhile adding a separate section that features an overview with more detailed technology descriptions.
(Previously proposed e.g. here)

It should include:

• Do not hard-wrap text in .rst files.
• Every sentence begins on a new line.
• Use headings in the order *** (first in any file), ===, ---, ~~~.
• Spell-check all added text.

Until now these tables are in energy/other and energy/electricity