Merge branch 'develop' into demand_path

Author: tsmbland

.vscode/launch.json

@@ -11,6 +11,13 @@
             "module": "muse",
             "args": ["--model", "default"]
         },
+        {
+            "name": "Model: default_retro",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "muse",
+            "args": ["--model", "default_retro"]
+        },
         {
             "name": "Model: multiple_agents",
             "type": "debugpy",

CITATION.cff

@@ -8,6 +8,6 @@ authors:
     - family-names: Hawkes
       given-names: Adam
 
-title: SGIModel/MUSE_OS
+title: MUSE_OS
 version: v1.0.1
 date-released: 2022-03-25

docs/advanced-guide/extending-muse.ipynb

@@ -169,7 +169,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, we  first copy the default model provided with muse to a local subfolder called \"model\". Then we read the `settings.toml` file and modify it using python. You may prefer to modify the `settings.toml` file using your favorite text editor. However, modifying the file programmatically allows us to\n",
+    "Next, we  first copy the `default_retro` model provided with muse to a local subfolder called \"model\". Then we read the `settings.toml` file and modify it using python. You may prefer to modify the `settings.toml` file using your favorite text editor. However, modifying the file programmatically allows us to\n",
     "routinely run this notebook as part of MUSE's test suite and check that the tutorial it is still up\n",
     "to date."
    ]
@@ -185,7 +185,7 @@
     "from muse import examples\n",
     "from toml import dump, load\n",
     "\n",
-    "model_path = examples.copy_model(overwrite=True)\n",
+    "model_path = examples.copy_model(name=\"default_retro\", overwrite=True)\n",
     "settings = load(model_path / \"settings.toml\")\n",
     "new_output = {\n",
     "    \"quantity\": \"consumption_zero\",\n",
@@ -204,7 +204,7 @@
    "source": [
     "We can now run the simulation. There are two ways to do this. From the command-line, where we can do:\n",
     "\n",
-    "    python3 -m muse data/commercial/modified_settings.toml \n",
+    "    python3 -m muse model/modified_settings.toml \n",
     "\n",
     "(note that slashes may be the other way on Windows). Or directly from the notebook:"
    ]
@@ -366,7 +366,7 @@
     "from muse import examples\n",
     "from toml import dump, load\n",
     "\n",
-    "model_path = examples.copy_model(overwrite=True)\n",
+    "model_path = examples.copy_model(name=\"default_retro\", overwrite=True)\n",
     "settings = load(model_path / \"settings.toml\")\n",
     "new_output = {\n",
     "    \"quantity\": \"capacity\",\n",
@@ -509,7 +509,7 @@
     "from muse import examples\n",
     "from toml import dump, load\n",
     "\n",
-    "model_path = examples.copy_model(overwrite=True)\n",
+    "model_path = examples.copy_model(name=\"default_retro\", overwrite=True)\n",
     "settings = load(model_path / \"settings.toml\")\n",
     "settings[\"sectors\"][\"residential\"][\"outputs\"] = [\n",
     "    {\n",

docs/advanced-guide/further-extending-muse.ipynb

@@ -217,7 +217,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.18"
+   "version": "3.12.3"
   },
   "vscode": {
    "interpreter": {

docs/conf.py

@@ -6,7 +6,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "MUSE"
-copyright = "2022, Sustainable Gas Institute"
+copyright = "2024, Imperial College London"
 author = "Imperial College London"
 release = "1.1.0"
 version = ".".join(release.split(".")[:2])

docs/example-output.ipynb

@@ -33,7 +33,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.18"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/inputs/toml.rst

@@ -70,7 +70,7 @@ a whole.
    whether equilibrium of `demand` or `prices` should be sought. Defaults to `demand`.
 
 *maximum_iterations*
-   Maximum number of iterations when searching for equilibrium. Defaults to 3.
+   Maximum number of iterations when searching for equilibrium. Defaults to 100.
 
 *tolerance*
    Tolerance criteria when checking for equilibrium. Defaults to 0.1. 0.1 signifies that 10% of a deviation is allowed among the iterative value of either demand or price over a year per region.
@@ -544,6 +544,10 @@ to define the timeslice simply by referring to the slices it will use at each le
           how much the capacity can grow during each investment event.
         - :py:func:`~muse.constraints.search_space`: a binary (on-off) constraint
           specifying which technologies are considered for investment.
+        - :py:func:`~muse.constraints.minimum_service`: a lower constraint for
+          production for those technologies that need to keep a minimum production.
+        - :py:func:`~muse.constraints.demand_limiting_capacity`: limits the combined
+          capacity to be installed to the demand of the peak timeslice.
 
 
 *output*
@@ -668,15 +672,15 @@ The following attributes are accepted:
    The CSV format should follow the following format:
 
    .. csv-table:: Consumption
-      :header: " ", "RegionName", "ProcessName", "TimeSlice", "electricity", "diesel", "algae"
+      :header: " ", "RegionName", "ProcessName", "Timeslice", "electricity", "diesel", "algae"
       :stub-columns: 4
 
       0,USA,fluorescent light,1,1.9, 0, 0
       1,USA,fluorescent light,2,1.8, 0, 0
 
 
-   The index column as well as "RegionName", "ProcessName", and "TimeSlice" must be
-   present. Further columns are reserved for commodities. "TimeSlice" refers to the
+   The index column as well as "RegionName", "ProcessName", and "Timeslice" must be
+   present. Further columns are reserved for commodities. "Timeslice" refers to the
    index of the timeslice. Timeslices should be defined consistently to the sectoral
    level timeslices.
    The column "ProcessName" needs to be present and filled in, in order for the data

docs/installation/pipx-based.rst

@@ -17,7 +17,7 @@ In the following sections, we will guide you step by step in configuring your sy
     The next sections will explain in detail the appropriate steps as well as commenting on possible caveats. **We strongly encourage you to read through the sections below** to understand what these steps entitle, but in the end, what we are going to do to install MUSE is the following:
 
     - Open a terminal
-    - Install `pyenv <https://github.com/pyenv/pyenv>`_ (Linux and MacOS) or `pyenv-win <https://pyenv-win.github.io/pyenv-win/>`_ (Windows) and make sure it works.
+    - Install `pyenv <https://github.com/pyenv/pyenv>`_ (Linux and MacOS) or `pyenv-win <https://pyenv-win.github.io/pyenv-win/>`_ (Windows) and make sure it works by invoking `pyenv --version` in the terminal.
     - Run the following commands in the terminal:
 
         .. code-block::
@@ -28,14 +28,14 @@ In the following sections, we will guide you step by step in configuring your sy
             python -m pipx ensurepath
             python -m pipx install muse-os
 
-    - After this, MUSE will be available to use system wide simply by invoking ``muse`` in the terminal, for example ``muse --model default``.
+    - After this, MUSE will be available to use system wide simply by invoking muse in the terminal. To illustrate this and to test your installation, run muse --model default. You should then see a a list of outputs printed to the terminal showing the computations going on in the background.
 
 .. _launch-terminal:
 
 Launching a terminal
 ~~~~~~~~~~~~~~~~~~~~
 
-All operating systems have a Terminal application that let you run commands. You will need to use it extensively when using MUSE, so we strongly suggest you get familiar with it. For now, let's just figure out how to launch it:
+All operating systems have a Terminal application that let you run commands. You will need to use it extensively when using MUSE, so we strongly suggest you get familiar with it. For now, let's just figure out how to launch one:
 
 - **Linux**: Depending on the distribution, you might have a shortcut in your tasks bar already or it should be easily found in the menu. Look for ``Console`` or ``Terminal`` to lunch the application.
 - **MacOS**: Press ``Super key + Space`` to open the search box. There, type ``Terminal`` and press ``Enter``.
@@ -107,13 +107,43 @@ Installing ``pyenv``
 
 To install ``pyenv``, follow these steps:
 
-- **Linux**: In this case, you will need to clone the GitHub repository using ``git``. Most Linux distributions come with ``git`` installed, so this should work out of the box:
+- **Linux**: In this case, you will need to clone the GitHub repository using ``git``. Most Linux distributions come with ``git`` installed, so this should work out of the box.
+Then, complete the setup by adding ``pyenv`` to your profile, so the executable can be found. You can `check the instructions in the official webpage <https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv>`_,
+or follow the below commands that were tested on `Ubuntu 22.04 LTS` using its popular `bash shell` and `z-shell`. To be specific, we tested them
+on `GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)` and `zsh 5.8.1 (x86_64-ubuntu-linux-gnu)`.
 
-    .. code-block:: bash
+Now, we go through the installation procedure of ``pyenv`` on Linux, step-by-step:
 
-        git clone https://github.com/pyenv/pyenv.git ~/.pyenv
+ .. code-block::
+
+            # Step 1: Install essential libraries needed for pyenv
+            sudo apt install -y make build-essential libssl-dev zlib1g-dev \
+                libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev \
+                libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python3-openssl \
+                git
+
+
+            # Step 2: Clone the `pyenv` repository for Linux
+            git clone https://github.com/pyenv/pyenv.git ~/.pyenv
+
+
+            # Step 3: Run one code block in this step only, depending on what shell you use:
+
+            # If you are on the bash shell run the following:
+            echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
+            echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
+            echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
+            source ~/.bashrc
+
+            # If you are on the z-shell, run the following:
+            echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
+            echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
+            echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
+            source ~/.zshrc
+
+            # Step 4: Confirm successful installation of `pyenv` upon invoking the following command in the terminal. You should be returned something similar to `pyenv 2.4.1-10-g2e0bb023`
+            pyenv --version
 
-    Then, complete the setup by adding ``pyenv`` to your profile, so the executable can be found. `Check the instructions in the official webpage <https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv>`_.
 
 - **MacOS**: The simplest option is to use Homebrew:
 
@@ -124,12 +154,20 @@ To install ``pyenv``, follow these steps:
 
     Then, complete the setup by adding ``pyenv`` to your profile, so the executable can be found. `Check the instructions in the official webpage <https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv>`_.
 
-- **Windows**: ``pyenv-win`` is a separate project but it has the same functionality and it is also simpler to setup. Just run the following command and you should be ready to go:
+- **Windows**: ``pyenv-win`` is a separate project but it has the same functionality and it is also simpler to setup.
+You can read the detailed installation instructions `from the official pyenv-win website <https://github.com/pyenv-win/pyenv-win/tree/master>`_,
+but the easiest way is to run the following command in the ``powershell`` and, upon closing and launching a new shell, you should be ready to go:
 
     .. code-block:: powershell
 
+        # Step 1: In your powershell, invoke the following command:
         Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
 
+        # Step 2: close the shell you invoked in the command from Step 1 and re-launch powershell
+
+        # Step 3: Confirm success; you should be returned something similar to `pyenv 3.1.1`
+        pyenv --version
+
     .. note::
 
         If you are getting any ``UnauthorizedAccess`` error, then start Windows PowerShell with the “Run as administrator” option (see figure above) and run:
@@ -140,19 +178,8 @@ To install ``pyenv``, follow these steps:
 
         Finally open a normal PowerShell and re-run the above installation command.
 
-After completing the above steps, you will need to close the terminal and re-open it again. After that, to check if things work run:
-
-.. code-block:: bash
-
-    pyenv --version
-
-You should get something similar to:
-
-.. code-block:: output
-
-    pyenv 3.1.1
 
-Actually installing Python
+Installing your chosen Python version
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 With ``pyenv`` installed and correctly configured, it is now easy to install any Python version we want. To see the versions available run:
@@ -161,20 +188,20 @@ With ``pyenv`` installed and correctly configured, it is now easy to install any
 
     pyenv install -l
 
-You should see a very long list of versions to choose from. Let's install the latest version of the 3.9 family:
+You should see a long list of versions to choose from. Let's install one of the later versions of the 3.9 family:
 
 .. code-block:: bash
 
     pyenv install 3.9.13
 
-The command will take a minute or two to complete, depending on your internet connection, and show an output similar to the following (this is just an example for Windows):
+The command will take a minute or two to complete, depending on your internet connection, and show an output similar to the following (this is an example from Windows):
 
 .. code-block:: output
 
     :: [Info] ::  Mirror: https://www.python.org/ftp/python
     :: [Downloading] ::  3.9.13 ...
     :: [Downloading] ::  From https://www.python.org/ftp/python/3.9.13/python-3.9.13-amd64.exe
-    :: [Downloading] ::  To   C:\Users\your_username\.pyenv\pyenv-win\install_cache\python-3.9.13-amd64.exe
+    :: [Downloading] ::  To C:\Users\your_username\.pyenv\pyenv-win\install_cache\python-3.9.13-amd64.exe
     :: [Installing] ::  3.9.13 ...
     :: [Info] :: completed! 3.9.13
 
@@ -197,7 +224,9 @@ In both cases, if you run ``python --version`` afterwards, you should get ``Pyth
 Installing ``pipx``
 ~~~~~~~~~~~~~~~~~~~
 
-Next we need to install ``pipx``, a Python application manager that facilitates installing, keeping applications updated and run them in their own isolated environments. We could skip this step and install MUSE directly, but that will risk to have conflicting dependencies in the future if you install any other application, breaking your MUSE installation, and we do not want that to happen.
+Next we need to install ``pipx``, a Python application manager that facilitates installing, keeping applications updated and running them in their own isolated environments.
+More specifically, ``pipx`` will create a virtual environment to run the tools it installs based on the python version that was used to install pipx to start with, unless you specify another version and that other version is system wide available.
+We could skip this step and install MUSE directly, but that will risk to have conflicting dependencies in the future if you install any other application, breaking your MUSE installation, and we do not want that to happen.
 
 The installation instructions for ``pipx`` can be found in the `official webpage <https://pypa.github.io/pipx/installation/>`_ specific for the three operating systems. The following instructions, however, should work for the three cases:
 

docs/installation/virtual-env-based.rst

@@ -48,6 +48,9 @@ Later, to recover the system-wide "normal" python, deactivate the environment wi
 
     conda deactivate
 
+
+.. _python_venv:
+
 Creating a virtual environment with ``venv``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -87,8 +90,24 @@ Later, to recover the system-wide "normal" python, deactivate the environment wi
 
     deactivate
 
-Installing MUSE in a virtual environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Creating a virtual environment with ``pyenv + venv``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively to creating virtual environments in ``conda``, you can also make use of two well-tested and maintained libraries.
+We met the first one, ``pyenv``, already in the :ref:`pipx-based <pipx-based>` under the section :ref:`Installing pyenv <pipx-based-installing-pyenv>` and the installation procedure is exactly the same.
+If you go down that route, please follow the steps outlined there and chose a recent version ``Python``, say 3.9.
+
+The second package we need to create virtual environments for any specific ``Python`` version is called
+``venv``, and it ships with ``Python`` by default. To create such an environment, we first need to ensure that the
+``Python`` version we wish to use is indeed the one we want. To do this, open the terminal and invoke ``pyenv versions``.
+To install different versions or set them to local or global scope, please refer again to
+:ref:`Installing pyenv <pipx-based-installing-pyenv>`.
+
+We can now create virtual environments using ``Python`` directly as explained in :ref:`python_venv`.
+
+
+Installing standalone MUSE in a virtual environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Regardless of the method used, **once it has been created and activated**, you can install ``MUSE`` within using: