The |MESSAGEix| framework ************************* |MESSAGEix| is a versatile, dynamic systems-optimization modelling framework developed by the |IIASA| Energy, Climate, and Environment (ECE) Program [#rename]_ since the 1980s. This is the documentation for :mod:`message_ix`, a Python package that ties together all components of the framework. :mod:`message_ix` and :mod:`ixmp` are free and open source software, licensed under the `APACHE 2.0 license`_. - For the scientific reference of the framework, see Huppmann et al. (2019) :cite:`Huppmann-2018`. - For an overview and recent publications related to the specific |MESSAGEix|-GLOBIOM global model instance used at the IIASA ECE Program, see the `MESSAGEix-GLOBIOM documentation`_. .. _getting-started: Getting started =============== .. NB this ReST pattern is repeated throughout this file: 1. List of :doc:`...` links, followed by 2. .. toctree:: directive with :hidden:, containing the same links. This overcomes limitations of toctree, allowing introductory paragraphs, and different titles in this page than in the sidebar. Modeling using |MESSAGEix| requires domain knowledge, understanding of certain research methods, and scientific computing skills. - :doc:`prereqs` gives a list of these items for formal and self-guided learning. Then, continue with the: - :doc:`framework` detailed description and feature list. - :doc:`install` of the software and essential dependencies. - :doc:`tutorials` for new users that demonstrate the basic features of the framework. - :doc:`Usage <usage>` of |MESSAGEix| in academic publications, research projects, and derived tools. .. toctree:: :hidden: :caption: Getting started prereqs framework install tutorials Publications, projects, and tools <usage> .. figure:: _static/ix_features.svg :width: 360px :align: center Features of ``ixmp``, ``message_ix``, and related packages :cite:`Huppmann-2018` .. _core: Mathematical specification ========================== These pages provide comprehensive description of the variables and equations in the core MESSAGEix mathematical implementation. - :doc:`model/MESSAGE/sets_maps_def` - :doc:`time` - :doc:`model/MESSAGE/parameter_def` - :doc:`model/MESSAGE/model_core` - :doc:`model/MESSAGE/model_solve` - :doc:`model/MESSAGE/reporting` - :doc:`model/MESSAGE/scaling_investment_costs` - :doc:`model/MACRO/macro_core` .. toctree:: :hidden: :caption: Mathematical specification model/MESSAGE/sets_maps_def time model/MESSAGE/parameter_def model/MESSAGE/model_core model/MESSAGE/model_solve model/MESSAGE/reporting model/MESSAGE/scaling_investment_costs model/MACRO/macro_core .. _guide: Developing |MESSAGEix| models ============================= Everyone is encouraged to use |MESSAGEix| to develop energy system and integrated assessment models! Developing a valid, scientific model requires careful use of the framework features. This section provides guidelines for how to make some common model design choices. - :doc:`efficiency` - :doc:`tools/add_year` - :doc:`reporting` - :doc:`debugging` - :doc:`macro` - :doc:`notice` describes how to cite the framework and software in published research. - :doc:`sharing` explains how to add your |MESSAGEix| applications to the :doc:`Usage <usage>` page in these docs. .. toctree:: :hidden: :caption: Developing MESSAGEix models :glob: efficiency tools/* reporting debugging macro notice sharing Reference and development ========================= - :doc:`api` - :doc:`rmessageix` - :doc:`whatsnew` —release history and migration/upgrade notes. - :doc:`contributing` —we welcome enhancements to the framework itself that enable new features across all models. You can learn more about how we handle these contributions in :file:`GOVERNANCE.md` (`on GitHub <https://github.com/iiasa/message_ix/blob/main/GOVERNANCE.md>`__ or included with the source code) [#osguides]_ - :doc:`bibliography` .. toctree:: :hidden: :caption: Reference & development api rmessageix whatsnew contributing bibliography .. _help: Community and support ===================== We aim to maintain a healthy community for developers and users of MESSAGEix; thus we expect everyone to follow our **Code of Conduct**, which you can find in :file:`CODE_OF_CONDUCT.md` (`on GitHub <https://github.com/iiasa/message_ix?tab=coc-ov-file>`__ or included with the source code). [#osguides]_ You can also: .. _newsletter: - Read or join existing `discussions <https://github.com/iiasa/message_ix/discussions>`_ on GitHub, or start a new one with your MESSAGEix usage question. - Search `current issues <https://github.com/iiasa/message_ix/issues?q=is:issue>`_, or open a new one to report a bug in the code. - Subscribe to the **MESSAGEix Community Newsletter** by filling `this form <https://iiasa.ac.at/signup>`__ and ticking the box for "MESSAGEix-Community". At least once a year, we update all subscribers on the latest research and ongoing projects regarding MESSAGEix and invite you to our annual `Community Meeting <https://iiasa.ac.at/search?search_api_fulltext=MESSAGEix+Community+Meeting>`__. - See our security policy in :file:`SECURITY.md` (`on GitHub <https://github.com/iiasa/message_ix?tab=security-ov-file>`_ or included with the source code). [#osguides]_ - Read answers to some not-so-:doc:`‘frequently’ asked questions <faq>`. - Check the older message_ix Google Group, either `online <https://groups.google.com/d/forum/message_ix>`_ or via e-mail at <message_ix@googlegroups.com>. .. toctree:: :hidden: :caption: Community & support Code of conduct <https://github.com/iiasa/message_ix?tab=coc-ov-file#readme> Discussions <https://github.com/iiasa/message_ix/discussions> faq .. _`MESSAGEix-GLOBIOM documentation`: http://data.ene.iiasa.ac.at/message-globiom/ .. _`APACHE 2.0 open-source license`: https://github.com/iiasa/message_ix/blob/main/LICENSE .. [#rename] Known as the “Energy Program” until 2020-12-31. .. [#osguides] `Our usage <https://github.com/iiasa/message_ix/community>`_ of files like CODE_OF_CONDUCT, GOVERNANCE, SECURITY, and SUPPORT follows the `Open Source Guides <https://opensource.guide/>`_ recommendations.