### Install and Run pre-commit Hooks

Source: https://docs.messageix.org/en/latest/_sources/contributing.rst.txt

Installs pre-commit using uv and then installs the git hooks for the local repository. Run pre-commit run --all-files to test the tools on all files.

```bash
uv tool install --with=pre-commit-uv pre-commit
pre-commit install -f

# Run the tools on all files to confirm they are working
pre-commit run --all-files
```

--------------------------------

### Configuration Example for message_ix

Source: https://docs.messageix.org/en/latest/api.html

Example configuration file for message_ix, demonstrating settings for platform, model directory, and solve options.

```json
{
  "platform": {
    "default": "my-platform",
    "my-platform": {"backend": "jdbc", "etc": "etc"},
  },
  "message model dir": "/path/to/custom/gams/source/files",
  "message solve options": {"lpmethod": 4},
}

```

--------------------------------

### Check pip Installation

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Verifies that pip is installed and shows its version. If pip is not installed, follow the provided link for installation instructions.

```bash
pip --version
```

--------------------------------

### Show message-ix and dependency versions

Source: https://docs.messageix.org/en/latest/install-adv.html

Display the installed versions of message_ix, ixmp, and their key dependencies to verify the installation.

```bash
# Show versions of message_ix, ixmp, and key dependencies
message-ix show-versions
```

--------------------------------

### Show MESSAGE ix installation versions

Source: https://docs.messageix.org/en/latest/install.html

Verifies the installation by displaying the versions of message_ix, ixmp, and key dependencies. The output should match the latest versions available.

```bash
message-ix show-versions

```

--------------------------------

### Install MESSAGE ix from GitHub

Source: https://docs.messageix.org/en/latest/install-adv.html

Install a specific version or branch from the repository using SSH or HTTPS.

```bash
pip install git+ssh://git@github.com:iiasa/message_ix.git@<ref>[tests]
```

```bash
pip install git+https://github.com/iiasa/message_ix.git@<ref>[tests]
```

--------------------------------

### Example Tutorial Filenames

Source: https://docs.messageix.org/en/latest/_sources/contrib/tutorial.rst.txt

Illustrative filenames for tutorials, categorized by group and type (baseline, basic, advanced, renewables).

```text
:file:`tutorial/example/example_baseline.ipynb`
```

```text
:file:`tutorial/example/example_basic.ipynb`
```

```text
:file:`tutorial/example/example_emmission_bounds.ipynb`
```

```text
:file:`tutorial/example/example_emission_taxes.ipynb`
```

```text
:file:`tutorial/example/example_fossil_resources.ipynb`
```

```text
:file:`tutorial/example/example_adv.ipynb`
```

```text
:file:`tutorial/example/example_addon_technologies.ipynb`
```

```text
:file:`tutorial/example/example_share_constraints.ipynb`
```

```text
:file:`tutorial/example/example_renewables.ipynb`
```

```text
:file:`tutorial/example/example_firm_capacity.ipynb`
```

```text
:file:`tutorial/example/example_flexible_generation.ipynb`
```

```text
:file:`tutorial/example/example_renewable_resources.ipynb`
```

--------------------------------

### Install conda-libmamba-solver

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Installs the conda-libmamba-solver, which is a faster and more reliable solver for conda environments.

```bash
conda install conda-libmamba-solver
```

--------------------------------

### Install mamba solver and set it as default

Source: https://docs.messageix.org/en/latest/install.html

Installs the mamba solver for faster and more reliable conda installations, and configures conda to use it by default.

```bash
conda install conda-libmamba-solver
conda config --set solver libmamba

```

--------------------------------

### Launch Jupyter notebook

Source: https://docs.messageix.org/en/latest/tutorials.html

Start the Jupyter notebook server from the command line.

```bash
$ jupyter notebook
```

--------------------------------

### Troubleshoot Database Configuration Errors

Source: https://docs.messageix.org/en/latest/whatsnew.html

Example error log indicating missing properties in the configuration file during platform initialization.

```text
usr/local/lib/python2.7/site-packages/jpype/_jclass.py:111: at.ac.iiasa.ixmp.exceptions.IxExceptionPyRaisable
---------------------------- Captured stdout setup -----------------------------
2018-11-13 08:15:17,410 ERROR at.ac.iiasa.ixmp.database.DbConfig:357 - missing property 'config.server.config' in /tmp/hhvE1o/test.properties
2018-11-13 08:15:17,412 ERROR at.ac.iiasa.ixmp.database.DbConfig:357 - missing property 'config.server.password' in /tmp/hhvE1o/test.properties
2018-11-13 08:15:17,412 ERROR at.ac.iiasa.ixmp.database.DbConfig:357 - missing property 'config.server.username' in /tmp/hhvE1o/test.properties
2018-11-13 08:15:17,413 ERROR at.ac.iiasa.ixmp.database.DbConfig:357 - missing property 'config.server.url' in /tmp/hhvE1o/test.properties
------------------------------ Captured log setup ------------------------------
core.py                     80 INFO     launching ixmp.Platform using config file at '/tmp/hhvE1o/test.properties'
_________________ ERROR at setup of test_add_spatial_multiple __________________

    @pytest.fixture(scope="session")
    def test_mp():
        test_props = create_local_testdb()

        # start jvm
        ixmp.start_jvm()

        # launch Platform and connect to testdb (reconnect if closed)
>       mp = ixmp.Platform(test_props)
```

--------------------------------

### Install message_ix with tests extra from PyPI

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Installs the latest release of message_ix from PyPI, including the packages required for the test suite.

```bash
pip install message_ix[tests]
```

--------------------------------

### Install MESSAGEix with Optional Dependencies

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Installs MESSAGEix using pip, including optional dependencies specified in brackets (e.g., '[tests]'). This is applicable when not using conda.

```bash
pip install "message_ix[tests]"
```

--------------------------------

### Install message_ix from GitHub using HTTPS

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Installs a specific version of message_ix from a GitHub repository using HTTPS and personal access tokens. Replace <ref> with a Git reference like a branch name, tag, or commit hash.

```bash
pip install git+https://github.com/iiasa/message_ix.git@<ref>[tests]
```

--------------------------------

### Install message_ix from GitHub using SSH

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Installs a specific version of message_ix from a GitHub repository using SSH authentication. Replace <ref> with a Git reference like a branch name, tag, or commit hash.

```bash
pip install git+ssh://git@github.com:iiasa/message_ix.git@<ref>[tests]
```

--------------------------------

### Install message_ix in editable mode

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Installs message_ix from a local source directory in editable mode, including the 'tests' extra. Changes to the source code will be reflected immediately without reinstallation.

```bash
pip install --editable .[tests]
```

--------------------------------

### List Configured MESSAGEix Platforms

Source: https://docs.messageix.org/en/latest/_sources/contrib/video/install.rst.txt

This command lists all configured platforms on your system, including the default 'local' platform if MESSAGEix was just installed.

```bash
message-ix platform list
```

--------------------------------

### ReST markup for release notes - Before editing

Source: https://docs.messageix.org/en/latest/contrib/release.html

Example of the ReST markup in RELEASE_NOTES.rst before editing for a new release.

```rst
Next release
============

All changes
-----------

- Description of a change (:pull:`9999`).
```

--------------------------------

### Total Capacity Bounds

Source: https://docs.messageix.org/en/latest/model/MESSAGE/model_core.html

Upper and lower bounds for total installed capacity summed over all vintages.

```math
∑yV≤yCAPn,t,y,yV≤bound_total_capacity_upn,t,y∀ t ∈ TINV
```

```math
∑yV≤yCAPn,t,y,yV≥bound_total_capacity_lon,t,y∀ t ∈ TINV
```

--------------------------------

### Get start and end indices for variable

Source: https://docs.messageix.org/en/latest/tools/sankey.html

Retrieves the indices corresponding to the source and target within a variable name string.

```python
message_ix.tools.sankey.get_start_and_end_index(_variable : str_) → tuple[list[int], list[int]][source]
```

--------------------------------

### Download tutorial files

Source: https://docs.messageix.org/en/latest/tutorials.html

Use the command-line interface to download tutorial notebooks to a specified local directory.

```bash
$ message-ix dl /path/to/tutorials
```

--------------------------------

### Navigate to tutorial directory

Source: https://docs.messageix.org/en/latest/tutorials.html

Change the working directory to the location where tutorial files were downloaded.

```bash
$ cd /path/to/tutorials
```

--------------------------------

### Check installed message-ix version using conda

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

If message-ix was installed using conda, use this command to check the installed version.

```bash
conda list message-ix
```

--------------------------------

### Check installed message-ix version using conda

Source: https://docs.messageix.org/en/latest/install-adv.html

If message-ix was installed using conda, use 'conda list' to check the installed version.

```bash
# If installed using conda
conda list message-ix
```

--------------------------------

### Check installed message-ix version using pip

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

If message-ix was installed using pip, use this command to directly check the installed version.

```bash
pip show message-ix
```

--------------------------------

### Grouped Example Notebook Naming Convention

Source: https://docs.messageix.org/en/latest/contrib/tutorial.html

Organize related tutorial notebooks into groups within 'tutorial/example/'. Each notebook should be prefixed with the group name, followed by an underscore and a descriptive name. This convention is useful for tutorials sharing a common RES.

```text
tutorial/example/example_baseline.ipynb
```

```text
<group>_baseline.ipynb
```

```text
<group>_basic.ipynb  # Basic modeling features, e.g.:
```

```text
<group>_emmission_bounds.ipynb
```

```text
<group>_emission_taxes.ipynb
```

```text
<group>_fossil_resources.ipynb
```

```text
<group>_adv.ipynb  # Advanced modeling features, e.g.:
```

```text
<group>_addon_technologies.ipynb
```

```text
<group>_share_constraints.ipynb
```

```text
<group>_renewables.ipynb  # Features related to renewable energy, e.g.:
```

```text
<group>_firm_capacity.ipynb
```

```text
<group>_flexible_generation.ipynb
```

```text
<group>_renewable_resources.ipynb
```

--------------------------------

### Create Key Instances

Source: https://docs.messageix.org/en/latest/reporting.html

Demonstrates creating and manipulating Key objects for quantity dimensionality.

```python
k1 = Key("foo:a-b-c:t1", drop="b", append="d", tag="t2")
k2 = Key("foo:a-b-c:t1").drop("b").append("d)"
```

--------------------------------

### Install MESSAGEix Package

Source: https://docs.messageix.org/en/latest/_sources/contrib/video/install.rst.txt

Installs the 'message-ix' package and its required dependencies into the currently active conda environment. This command triggers the download and installation process.

```bash
conda install message-ix
```

--------------------------------

### Download MESSAGEix Tutorials

Source: https://docs.messageix.org/en/latest/_sources/contrib/video/install.rst.txt

Download tutorial files to a specified directory using the 'message-ix dl' command. Ensure your MESSAGEix environment is active before running.

```bash
message-ix dl "<path_to_your_directory>"
```

--------------------------------

### List configured platforms and ixmp config path

Source: https://docs.messageix.org/en/latest/install-adv.html

Show the list of configured platforms and the path to the ixmp configuration file. By default, only the 'local' platform should appear.

```bash
# Show the list of platforms (~databases) that have been configured
# and the path to the ixmp config file. By default, only the "local"
# platform, backed by a local database, should appear in the list
message-ix platform list
```

--------------------------------

### Install nb_conda package

Source: https://docs.messageix.org/en/latest/tutorials.html

Install the nb_conda package if it is missing from the Anaconda distribution.

```bash
$ conda install nb_conda
```

--------------------------------

### Create a text file for video concatenation

Source: https://docs.messageix.org/en/latest/_sources/contrib/video.rst.txt

Prepare a .txt file listing video files to be concatenated. Each line should specify 'file' followed by the path to the video in single quotes.

```text
file '~/video_1.mp4'
file '~/video_2.mp4'
file '~/video_3.mp4'
```

--------------------------------

### Install and Uninstall pyam

Source: https://docs.messageix.org/en/latest/install-adv.html

Commands to manage the pyam package installation via Anaconda or pip.

```bash
# If message_ix is installed using Anaconda (see note below)
conda install pyam
```

```bash
# If installed using pip
pip uninstall pyam
```

--------------------------------

### POST /configure

Source: https://docs.messageix.org/en/latest/reporting.html

Configures the Computer using a path to a configuration file or keyword arguments.

```APIDOC
## POST /configure

### Description
Configure the Computer. Accepts a path to a configuration file and/or keyword arguments. Configuration keys loaded from file are superseded by keyword arguments.

### Method
POST

### Endpoint
/configure

### Parameters
#### Request Body
- **path** (Path | str) - Optional - Path to a configuration file in JSON or YAML format.
- **fail** (str | int) - Optional - Passed to add_queue(). If not 'raise', log messages are generated for config handlers that fail.
- **config** (Mapping[str, Any]) - Optional - Configuration keys/sections and values as a mapping.
- **config_kw** (Any) - Optional - Configuration keys/sections and values as keyword arguments.
```

--------------------------------

### Stand-alone Tutorial Location

Source: https://docs.messageix.org/en/latest/_sources/contrib/tutorial.rst.txt

Specifies the file path for a stand-alone tutorial notebook.

```text
:file:`tutorial/name.ipynb`
```

--------------------------------

### message_ix.util.tutorial.prepare_plots

Source: https://docs.messageix.org/en/latest/tutorials.html

Prepares a Reporter object to generate plots for tutorial energy models. It makes several plotting keys available, such as 'plot activity', 'plot demand', and 'plot prices'. Use set_filters() on the reporter to control plot contents.

```APIDOC
## message_ix.util.tutorial.prepare_plots

### Description
Prepare rep to generate plots for tutorial energy models. Makes available several keys:
  * `plot activity`
  * `plot demand`
  * `plot extraction`
  * `plot fossil supply curve`
  * `plot capacity`
  * `plot new capacity`
  * `plot prices`

To control the contents of each plot, use `set_filters()` on rep.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Install pyam-iamc directly using pip

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Alternatively, install the 'pyam-iamc' package directly using pip if you need its reporting capabilities.

```bash
pip install pyam-iamc
```

--------------------------------

### Create a virtual environment

Source: https://docs.messageix.org/en/latest/install-adv.html

Commands to initialize a virtual environment directory named message_env.

```bash
python -m venv message_env
```

```bash
virtualenv message_env
```

--------------------------------

### Display Conda Information

Source: https://docs.messageix.org/en/latest/_sources/contrib/video/install.rst.txt

Use this command to find the directories where Anaconda, your environment, and MESSAGEix are installed. This can be helpful for locating installation files.

```bash
conda info
```

--------------------------------

### Initialize Reporter with Scenario

Source: https://docs.messageix.org/en/latest/_sources/reporting.rst.txt

Use `Reporter.from_scenario` to initialize a reporter with a specific scenario. This sets up the reporter to access scenario data.

```python
k = rep.full_key("share:*:in+historical")
rep.add(k, ...)  # Some task that returns share values, e.g. from file
```

--------------------------------

### Install pyam using conda

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

If using Anaconda, install the 'pyam' package from conda-forge. Note the different package name compared to PyPI.

```bash
conda install pyam
```

--------------------------------

### Install message-ix with 'report' extra dependencies

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Install the 'report' extra dependencies for message-ix, which includes the 'pyam-iamc' package. This is necessary if you need reporting functionalities.

```bash
pip install message_ix[report]
```

--------------------------------

### Stand-alone Notebook Location

Source: https://docs.messageix.org/en/latest/contrib/tutorial.html

Place individual tutorial notebooks in the 'tutorial/' directory.

```text
tutorial/name.ipynb
```

--------------------------------

### Start Docker Compose for PostgreSQL

Source: https://docs.messageix.org/en/latest/install-adv.html

Utilize a Docker Compose file to manage PostgreSQL container startup, combining pull and run steps. This method can simplify environment variable management.

```bash
docker-compose -f docker-compose.yml up

```

--------------------------------

### Install MESSAGE ix using conda

Source: https://docs.messageix.org/en/latest/install.html

Installs the latest release of MESSAGE ix from the conda-forge channel into your current environment. Ensure conda is configured with the conda-forge channel.

```bash
conda install message-ix

```

--------------------------------

### Install MESSAGE ix using pip

Source: https://docs.messageix.org/en/latest/install.html

Installs the latest release of MESSAGE ix and its optional dependencies from PyPI. Ensure you have Python 3.9+ and a virtual environment activated.

```bash
pip install message_ix[docs,report,tests,tutorial]

```

--------------------------------

### List configured MESSAGE ix platforms

Source: https://docs.messageix.org/en/latest/install.html

Displays the list of configured platforms (databases) for message_ix and the path to the ixmp configuration file. This helps in verifying the setup.

```bash
message-ix platform list

```

--------------------------------

### Python Docstring Example

Source: https://docs.messageix.org/en/latest/contributing.html

Example of a Python docstring following numpydoc style, including type hints and special formatting for arguments and emphasis. Docstrings should be wrapped at 88 characters.

```python
def func(foo: str, bar: str) -> float:
    """Perform some action.

    If `foo` and `bar` have the same value, ``42.1`` is returned. *Nice!*
    """


```

--------------------------------

### Add Tutorial to Test Suite

Source: https://docs.messageix.org/en/latest/_sources/contrib/tutorial.rst.txt

Ensure new tutorials are run by the test suite by adding a line to the test file.

```python
Add a line to :file:`message_ix/tests/test_tutorials.py`, so that the parametrized test function runs the tutorial (as noted at :pull:`196`).
```

--------------------------------

### Explicit Model and Solve Options in Python

Source: https://docs.messageix.org/en/latest/_sources/api.rst.txt

Demonstrates how to explicitly pass model directory and solve options to the scen.solve() method in Python, equivalent to using a configuration file.

```python
# Model options given explicitly
scen.solve(
    model_dir="/path/to/custom/gams/source/files",
    solve_options=dict(lpmethod=4),
)
```

--------------------------------

### Install message_ix with tests extra from PyPI (zsh shell)

Source: https://docs.messageix.org/en/latest/_sources/install-adv.rst.txt

Installs the latest release of message_ix from PyPI, including the packages required for the test suite. This version is quoted for use with the zsh shell, which interprets [...] as a glob operator.

```bash
pip install -e '.[tests]'
```

--------------------------------

### Initializing Platform and Scenario in R

Source: https://docs.messageix.org/en/latest/_sources/rmessageix.rst.txt

Create global variables to interact with the Platform and Scenario objects using the $ operator.

```R
mp <- ixmp$Platform(name = "default")
scen <- message_ix$Scenario(mp, "model name", "scenario name")
# etc.
```

--------------------------------

### GET /timeseries

Source: https://docs.messageix.org/en/latest/api.html

Retrieve time series data from the scenario.

```APIDOC
## GET /timeseries

### Description
Retrieve time series data.

### Method
GET

### Parameters
#### Query Parameters
- **region** (str/list) - Optional - Regions to include.
- **variable** (str/list) - Optional - Variables to include.
- **unit** (str/list) - Optional - Units to include.
- **year** (int/list) - Optional - Years to include.
- **iamc** (bool) - Optional - Return data in wide/IAMC format.
- **subannual** (bool/str) - Optional - Whether to include column for sub-annual specification.

### Response
#### Success Response (200)
- **data** (pandas.DataFrame) - The requested time series data.
```

--------------------------------

### Register compatibility modules with require_compat

Source: https://docs.messageix.org/en/latest/reporting.html

Demonstrates how to register external modules for use as operators within a Computer instance.

```python
>>> c = Computer()
>>> c.require_compat("pyam")
```

```python
>>> c.require_compat("ixmp.reporting.computations")
```

```python
>>> import ixmp.reporting.computations as mod
>>> c.require_compat(mod)
```

--------------------------------

### Prepare and Use Reporter for Scenario Reporting

Source: https://docs.messageix.org/en/latest/_sources/reporting.rst.txt

This code demonstrates the basic workflow for reporting on a MESSAGEix Scenario. It involves obtaining a Scenario object, preparing a Reporter instance using from_scenario, and then executing tasks using the get method.

```python
from ixmp import Platform
from message_ix import Scenario, Reporter

mp = Platform()
scen = Scenario(scen)
rep = Reporter.from_scenario(scen)
rep.get("all")
```

--------------------------------

### Get Unit Registry

Source: https://docs.messageix.org/en/latest/reporting.html

Accesses the pint.UnitRegistry used by the Computer.

```APIDOC
## GET /unit_registry

### Description
The `pint.UnitRegistry` used by the Computer.

### Method
GET

### Endpoint
/unit_registry
```

--------------------------------

### Invoke the calibration process

Source: https://docs.messageix.org/en/latest/macro.html

Use the add_macro method on a baseline scenario to initiate the calibration process across the optimization horizon.

```python
Scenario.add_macro()
```

--------------------------------

### Get Category List

Source: https://docs.messageix.org/en/latest/api.html

Returns a list of all categories for a mapping set.

```python
>>> s.cat_list(_name : str_) → list[str][source]
```