MESSAGEix manuscript reference update iiasa#107 (iiasa#140)

* update references to MESSAGEix manuscript in readme's and documentation

* update the bibliography file

* fix formatting of references in NOTICE

* add missing link to tutorials page

* fix error for including ixmp/message_ix docs

* escaping `&` in LaTeX bib file

NOTICE.rst

@@ -46,14 +46,19 @@ A) Reference to the scientific publication and online resources
 Please cite the following manuscript when using the |MESSAGEix| framework and/or the ix modeling platform 
 for scientific publications or technical reports:
 
- Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, 
- Clara Orthofer, Michael Pimmer, Adriano Vinca, Alessio Mastrucci, Keywan Riahi, and Volker Krey. 
- "The |MESSAGEix| Integrated Assessment Model and the ix modeling platform". 2018, submitted. 
- Electronic pre-print available at `pure.iiasa.ac.at/15157/`_.
+ | Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer,
+ Michael Pimmer, Nikolay Kushin, Adriano Vinca, Alessio Mastrucci,
+ Keywan Riahi, and Volker Krey.
+ | "The MESSAGEix Integrated Assessment Model and the ix modeling platform".
+ | *Environmental Modelling & Software* 112:143-156, 2019. 
+ | doi: `10.1016/j.envsoft.2018.11.012`_
+ | electronic pre-print available at `pure.iiasa.ac.at/15157/`_.
 
 Also, please include a hyperlink to the online resource `MESSAGEix.iiasa.ac.at`_
 in any publication/report, or on a website describing your model
-or scientific analysis using the |MESSAGEix| framework.
+or scientific analysis using the MESSAGEix framework.
+
+.. _`10.1016/j.envsoft.2018.11.012` : https://doi.org/10.1016/j.envsoft.2018.11.012
 
 .. _`pure.iiasa.ac.at/15157/` : https://pure.iiasa.ac.at/15157/
 
@@ -87,7 +92,9 @@ Please refer to `Contributor Guidelines`_ for details.
 References
 ----------
 
-[1] Clara Orthofer, Daniel Huppmann, and Volker Krey. "South Africa's shale gas resources - chance or challenge?"
-2018, submitted. Electronic pre-print available at `pure.iiasa.ac.at/15085/`_.
+[1] | Clara Orthofer, Daniel Huppmann, and Volker Krey.
+ | "South Africa's shale gas resources - chance or challenge?"
+ | 2018, submitted. 
+ electronic pre-print available at `pure.iiasa.ac.at/15085/`_
 
 .. _`pure.iiasa.ac.at/15085/` : https://pure.iiasa.ac.at/15085/

README.md

@@ -46,12 +46,14 @@ master branch of the repository
 Please cite the following manuscript when using the MESSAGEix framework and/or
 the ix modeling platform for scientific publications or technical reports:
 
- Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer,
- Michael Pimmer, Adriano Vinca, Alessio Mastrucci, Keywan Riahi, and Volker
- Krey. "The |MESSAGEix| Integrated Assessment Model and the ix modeling
- platform". 2018, submitted. Electronic pre-print available at
- [pure.iiasa.ac.at/15157/](https://pure.iiasa.ac.at/15157/).
-
+> Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer,
+ Michael Pimmer, Nikolay Kushin, Adriano Vinca, Alessio Mastrucci,
+ Keywan Riahi, and Volker Krey. 
+ "The |MESSAGEix| Integrated Assessment Model and the ix modeling platform". 
+ *Environmental Modelling & Software* 112:143-156, 2019. 
+ doi: [10.1016/j.envsoft.2018.11.012](https://doi.org/10.1016/j.envsoft.2018.11.012) 
+ electronic pre-print available at
+ [pure.iiasa.ac.at/15157/](https://pure.iiasa.ac.at/15157/)
 
 
 ## Install from Conda (New Users)

doc/source/bibs/main.bib

@@ -1,19 +1,15 @@
-%% This BibTeX bibliography file was created using BibDesk.
-%% https://bibdesk.sourceforge.net/
-
-%% Created for Daniel Huppmann at 2018-03-09 15:33:09 +0100 
-
-
-%% Saved with string encoding Unicode (UTF-8) 
-
-
-
-@misc{huppmann_messageix_2018,
- Author = {Huppmann, Daniel and Gidden, Matthew and Fricko, Oliver and Kolp, Peter and Orthofer, Clara and Pimmer, Michael and Vinca, Adriano and Mastrucci, Alessio and Riahi, Keywan and Krey, Volker},
- Date-Modified = {2018-03-09 14:33:06 +0000},
- Title = {{The MESSAGEix Integrated Assessment Model and the ix modeling platform}},
- Url = {https://pure.iiasa.ac.at/15157/},
- Year = {submitted}}
+@article{huppmann_messageix_2018,
+ author = {Huppmann, Daniel and Gidden, Matthew and Fricko, Oliver and
+ Kolp, Peter and Orthofer, Clara and Pimmer, Michael and
+ Kushin, Nikolay and Vinca, Adriano and Mastrucci, Alessio and
+ Riahi, Keywan and Krey, Volker},
+ title = {{The MESSAGEix Integrated Assessment Model and the ix modeling platform (ixmp): An open framework for integrated and cross-cutting analysis of energy, climate, the environment, and sustainable development}},
+ journal = {Environmental Modelling \& Software},
+ volume = {112},
+ pages = {143-156},
+ year = {2019},
+ doi = {10.1016/j.envsoft.2018.11.012}
+}
 
 @article{johnson_VRE_2016,
  Abstract = {Abstract In many climate change mitigation scenarios, integrated assessment models of the energy and climate systems rely heavily on renewable energy technologies with variable and uncertain generation, such as wind and solar PV, to achieve substantial decarbonization of the electricity sector. However, these models often include very little temporal resolution and thus have difficulty in representing the integration costs that arise from mismatches between electricity supply and demand. The global integrated assessment model, MESSAGE, has been updated to explicitly model the trade-offs between variable renewable energy (VRE) deployment and its impacts on the electricity system, including the implications for electricity curtailment, backup capacity, and system flexibility. These impacts have been parameterized using a reduced-form approach, which allows \{VRE\} integration impacts to be quantified on a regional basis. In addition, thermoelectric technologies were updated to include two modes of operation, baseload and flexible, to better account for the cost, efficiency, and availability penalties associated with flexible operation. In this paper, the modeling approach used in \{MESSAGE\} is explained and the implications for \{VRE\} deployment in mitigation scenarios are assessed. Three important stylized facts associated with integrating high \{VRE\} shares are successfully reproduced by our modeling approach: (1) the significant reduction in the utilization of non-VRE power plants; (2) the diminishing role for traditional baseload generators, such as nuclear and coal, and the transition to more flexible technologies; and (3) the importance of electricity storage and hydrogen electrolysis in facilitating the deployment of VRE. },

doc/source/index.rst

@@ -34,7 +34,7 @@ to `GAMS`_ for numerical computation.
 This documentation provides an introduction and the mathematical formulation 
 of the |MESSAGEix| equations and auxiliary functions.
 For the scientific reference of the framework, 
-see Huppmann et al. (submitted) :cite:`huppmann_messageix_2018`.
+see Huppmann et al. (2019) :cite:`huppmann_messageix_2018`.
 The formulation of |MESSAGEix| is a re-implementation and extension of `'MESSAGE V'`
 (Messner and Strubegger, 1995 :cite:`messner_users_1995`),
 the Integrated Assessment model developed at IIASA since the 1980s.
@@ -84,7 +84,8 @@ API Documentation
 .. toctree::
  :maxdepth: 1
 
- api
+ api/ixmp
+ api/message_ix
 
 Using |MESSAGEix|
 -----------------

doc/source/model.rst

@@ -43,6 +43,8 @@ There are three methods to run the |MESSAGEix| model:
  The scenario name and other arguments can be passed as command line parameters, 
  e.g. :literal:`gams MESSAGE_run.gms --in="<data-file>" --out="<output-file>"`.
 
+.. _`tutorials`: tutorials.html
+
 .. _`auto-doc page`: model/MESSAGE_run.html
 
 Overview of model structure and includes files

message_ix/model/MESSAGE-MACRO_run.gms

@@ -23,10 +23,13 @@ and the ix modeling platform, please visit `MESSAGEix.iiasa.ac.at/`.
 
 When using the MESSAGEix framework, please cite as:
 
- Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, 
- Clara Orthofer, Michael Pimmer, Adriano Vinca, Alessio Mastrucci, Keywan Riahi, and Volker Krey.
- "The MESSAGEix Integrated Assessment Model and the ix modeling platform". 2018, submitted. 
- Electronic pre-print available at `pure.iiasa.ac.at/15157/`.
+ Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer,
+ Michael Pimmer, Nikolay Kushin, Adriano Vinca, Alessio Mastrucci,
+ Keywan Riahi, and Volker Krey.
+ "The |MESSAGEix| Integrated Assessment Model and the ix modeling platform".
+ Environmental Modelling & Software 112:143-156, 2019.
+ doi: 10.1016/j.envsoft.2018.11.012
+ electronic pre-print available at pure.iiasa.ac.at/15157/
 
 Please review the NOTICE at `MESSAGEix.iiasa.ac.at/notice.html`
 and included in the GitHub repository for further user guidelines.

message_ix/model/MESSAGE_run.gms

@@ -23,10 +23,13 @@ and the ix modeling platform, please visit `MESSAGEix.iiasa.ac.at/`.
 
 When using the MESSAGEix framework, please cite as:
 
- Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, 
- Clara Orthofer, Michael Pimmer, Adriano Vinca, Alessio Mastrucci, Keywan Riahi, and Volker Krey.
- "The MESSAGEix Integrated Assessment Model and the ix modeling platform". 2018, submitted. 
- Electronic pre-print available at `pure.iiasa.ac.at/15157/`.
+ Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer,
+ Michael Pimmer, Nikolay Kushin, Adriano Vinca, Alessio Mastrucci,
+ Keywan Riahi, and Volker Krey.
+ "The |MESSAGEix| Integrated Assessment Model and the ix modeling platform".
+ Environmental Modelling & Software 112:143-156, 2019.
+ doi: 10.1016/j.envsoft.2018.11.012
+ electronic pre-print available at pure.iiasa.ac.at/15157/
 
 Please review the NOTICE at `MESSAGEix.iiasa.ac.at/notice.html`
 and included in the GitHub repository for further user guidelines.

message_ix/model/templates/MESSAGE_master_template.gms

@@ -23,10 +23,13 @@ and the ix modeling platform, please visit `MESSAGEix.iiasa.ac.at/`.
 
 When using the MESSAGEix framework, please cite as:
 
- Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, 
- Clara Orthofer, Michael Pimmer, Adriano Vinca, Alessio Mastrucci, Keywan Riahi, and Volker Krey.
- "The MESSAGEix Integrated Assessment Model and the ix modeling platform". 2018, submitted. 
- Electronic pre-print available at `pure.iiasa.ac.at/15157/`.
+ Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer,
+ Michael Pimmer, Nikolay Kushin, Adriano Vinca, Alessio Mastrucci,
+ Keywan Riahi, and Volker Krey.
+ "The |MESSAGEix| Integrated Assessment Model and the ix modeling platform".
+ Environmental Modelling & Software 112:143-156, 2019.
+ doi: 10.1016/j.envsoft.2018.11.012
+ electronic pre-print available at pure.iiasa.ac.at/15157/
 
 Please review the NOTICE at `MESSAGEix.iiasa.ac.at/notice.html`
 and included in the GitHub repository for further user guidelines.

rmessageix/source/README.md

@@ -10,8 +10,11 @@ https://MESSAGEix.iiasa.ac.at
 
 References
 
-Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, 
- Clara Orthofer, Michael Pimmer, Adriano Vinca, Alessio Mastrucci, Keywan Riahi, and Volker Krey. 
- "The MESSAGEix Integrated Assessment Model and the ix modeling platform". 
- 2018, submitted. 
-
+Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer,
+ Michael Pimmer, Nikolay Kushin, Adriano Vinca, Alessio Mastrucci,
+ Keywan Riahi, and Volker Krey.
+ "The |MESSAGEix| Integrated Assessment Model and the ix modeling platform".
+ *Environmental Modelling & Software* 112:143-156, 2019. 
+ doi: [10.1016/j.envsoft.2018.11.012](https://doi.org/10.1016/j.envsoft.2018.11.012)
+ electronic pre-print available at
+ [pure.iiasa.ac.at/15157/](https://pure.iiasa.ac.at/15157/).