Merge branch 'develop' into new-data-input

Author: tsmbland

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.1.0
+current_version = 1.2.0rc1
 commit = True
 tag = True
 

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.0
+    rev: v0.5.2
     hooks:
       - id: ruff-format
         types_or: [python, pyi, jupyter]
@@ -31,7 +31,7 @@ repos:
       - id: prettier
         types_or: [yaml, json]
   - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
-    rev: v2.13.0
+    rev: v2.14.0
     hooks:
       - id: pretty-format-toml
         args: [--autofix, --indent, "4", --no-sort]

CITATION.cff

@@ -9,5 +9,5 @@ authors:
       given-names: Adam
 
 title: MUSE_OS
-version: v1.0.1
-date-released: 2022-03-25
+version: v1.2.0rc1
+date-released: 2024-07-29

docs/advanced-guide/extending-muse.ipynb

@@ -340,7 +340,6 @@
     "quantity = \"capacity\"\n",
     "sink = \"aggregate\"\n",
     "filename = \"{cwd}/{default_output_dir}/Cache{Quantity}.csv\"\n",
-    "index = false\n",
     "```"
    ]
   },

docs/conf.py

@@ -8,7 +8,7 @@
 project = "MUSE"
 copyright = "2024, Imperial College London"
 author = "Imperial College London"
-release = "1.1.0"
+release = "1.2.0rc1"
 version = ".".join(release.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------

docs/inputs/toml.rst

@@ -270,7 +270,6 @@ See section on `Timeslices_`.
       quantity = "production"
       sink = "aggregate"
       filename = "{cwd}/{default_output_dir}/Cache{Quantity}.csv"
-      index = false
 
 ----------------
 Standard sectors
@@ -519,18 +518,17 @@ to define the timeslice simply by referring to the slices it will use at each le
 
     *demand_share*
         A method used to split the MCA demand into separate parts to be serviced by
-        specific agents. A basic distinction is between *new* and *retrofit* agents: the
-        former asked to respond to an increase of commodity demand investing in new
-        assets; the latter asked to invest in new asset to balance the decommissined
-        assets.
-
-        There are currently two options:
-
-        - :py:func:`~muse.demand_share.new_and_retro`: the demand is split into a
-          retrofit demand corresponding to demand that used to be serviced by
-          decommisioned assets, and the *new* demand.
-        - :py:func:`~muse.demand_share.market_demand`: simply the consumption for the
-          forecast year.
+        specific agents. The appropriate choice depends on the type of agents being used
+        in the simulation. There are currently two options:
+
+        - :py:func:`~muse.demand_share.standard_demand` (default): The input demand is
+          split amongst *new* agents. *New* agents get a share of the increase in demand
+          for the forecast years, as well as the demand that occurs from decommissioned
+          assets.
+        - :py:func:`~muse.demand_share.new_and_retro`: The input demand is split amongst
+          both *new* and *retrofit* agents. *New* agents get a share of the increase in
+          demand for the forecast year, whereas *retrofit* agents are assigned a share
+          of the demand that occurs from decommissioned assets.
 
     *constraints*
         The list of constraints to apply to the LP problem solved by the sector. By
@@ -672,27 +670,19 @@ The following attributes are accepted:
    The CSV format should follow the following format:
 
    .. csv-table:: Consumption
-      :header: " ", "RegionName", "ProcessName", "Timeslice", "electricity", "diesel", "algae"
-      :stub-columns: 4
+      :header: "RegionName", "Timeslice", "electricity", "diesel", "algae"
+      :stub-columns: 2
 
-      0,USA,fluorescent light,1,1.9, 0, 0
-      1,USA,fluorescent light,2,1.8, 0, 0
+      USA,1,1.9,0,0
+      USA,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 "RegionName" and "Timeslice" columns 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
-   to be read properly but it does not affect the simulation.
-
-
-*supply_path*
-   CSV file, one per year, indicating the amount of a commodities produced. It follows
-   the same format as :ref:`consumption_path <preset-consumption>`.
 
 *supply_path*
-   CSV file, one per year, indicating the amount of a commodities produced. It follows
+   CSV file, one per year, indicating the amount of commodities produced. It follows
    the same format as :ref:`consumption_path <preset-consumption>`.
 
 *prices_path*

docs/installation/developers.rst

@@ -3,7 +3,9 @@
 Installation for developers
 ---------------------------
 
-Developers of MUSE will need to have the version control tool ``git`` installed in their system and be familiar with its usage. The `Introduction to Git and GitHub for software development <https://imperialcollegelondon.github.io/introductory_grad_school_git_course/>`_ course created by `Imperial RSE Team <https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/>`_ can be a good place to start.
+Developers of MUSE will need to have the version control tool ``git`` installed in their system and be familiar with its usage.
+The `Introduction to Git and GitHub for software development <https://imperialcollegelondon.github.io/introductory_grad_school_git_course/>`_ and `Further Git and GitHub for effective collaboration <https://imperialcollegelondon.github.io/intermediate_grad_school_git_course/index.html/>`_ courses by the `Imperial RSE Team <https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/>`_ are excellent starting points.
+
 
 Installing MUSE source code in editable mode
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -14,20 +16,27 @@ Once you have ``git`` in your system, clone the MUSE repository with:
 
     git clone https://github.com/EnergySystemsModellingLab/MUSE_OS.git
 
+For developing MUSE, **it is highly recommended to do so in a virtual Python environment**. This is to isolate dependencies and to avoid version conflicts on other Python libraries.
+Moreover, this allows for unconstrained experimentation with the code without breaking system dependencies, which, as least as far as ``Linux`` is concerned, is an issue.
 
-For developing MUSE, **it is highly recommended to use virtual environments**, so that you have more control on the versions of the dependencies being used, making easy to change them without affecting other tools using Python, or even to have several environments in parallel for different purposes (Eg. new features, bug fixing...). You can either use ``conda`` or ``venv`` as explained in :ref:`virtual-environments`.
+Also, any operating system allows for multiple Python versions being installed in parallel for different purposes like creating new features and bug fixing.
+You can either use ``conda`` or ``pyenv`` in conjunction with ``venv`` as explained in :ref:`virtual-environments`.
 
 Once you have your environment created, **activate it** and install MUSE within the environment:
 
 .. code-block:: bash
 
     cd MUSE_OS
-    # 1- Create virtual environment
-    # 2- Activate virtual environment
-    # 3- Finally, install MUSE in editable mode with:
-    python -m pip install -e .[dev,doc]
+    # 1 - Create a virtual environment
+    # 2 - Activate that virtual environment
+    # 3 - Install MUSE in editable mode with: python -m pip install -e .[dev,doc]
+
+.. note::
+
+    Depending on your system, you might need to add quotation marks around ``[dev,doc]`` as in ``"[dev,doc]"``.
 
-Depending on your system, you might need to add quotation marks around ``[dev,doc]`` as in ``"[dev,doc]"``. This will install MUSE and all the dependencies required for its development. The downloaded code can be modified and the changes will be automatically reflected in the environment.
+    For example on ``Windows``, the command will read `python -m pip install -e .[dev,doc]`. On Ubuntu Linux, it will be `python -m pip install -e ."[dev,doc]"`.
+    This will install MUSE including its dependencies for development. The downloaded code can be modified and the changes will be automatically reflected in the virtual environment.
 
 .. note::
 
@@ -48,9 +57,11 @@ To ensure the consistency of the code with other developers, install the pre-com
 Running tests
 ~~~~~~~~~~~~~
 
-In the developing phase, MUSE can also be used to run test cases to check that the model would reproduce expected results from a defined set of input data. Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), from the testing framework of the same name.
+If you followed the **Installation for developers** guide, you are likely developing your own tests for MUSE.
+These tests ensure that a model produces reproducible results for a defined set of input data.
+Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), using the testing framework of the same name.
 
-Within the ``MUSE-OS`` directory, just run:
+To run tests, within the ``MUSE-OS`` directory, activate the virtual environment where you installed ``MUSE`` and run:
 
 .. code-block:: bash
 

docs/running-muse-example.ipynb

@@ -20,7 +20,7 @@
    "source": [
     "## Running MUSE\n",
     "\n",
-    "Once MUSE have been installed, we can run an example. To start with, we will run one of the built-in MUSE examples. We will focus on the terminal version of MUSE as the GUI version should be largely self-explanatory. If you are using MUSE within a virtual environment, make sure you have it activated.\n",
+    "Once MUSE have been installed, we can run an example. To start with, we will run one of the built-in MUSE examples. We will focus on the terminal version of MUSE as the GUI version should be largely self-explanatory. If you are using MUSE within a virtual environment, make sure you have it activated. \n",
     "\n",
     "In all cases, if the installation instructions were followed, you should be able to run the default `muse` example running the following command in the terminal:\n",
     "\n",
@@ -48,15 +48,29 @@
     "\n",
     "### Programmatic use of MUSE\n",
     "\n",
-    "It is also possible to run one of the built-in MUSE models directly in Python using the following code:\n",
-    "\n",
-    "```python\n",
+    "It is also possible to run one of the built-in MUSE models directly in Python using the following code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%capture\n",
     "from muse import examples\n",
+    "\n",
     "model = examples.model(\"default\")\n",
-    "model.run()\n",
-    "```\n",
+    "model.run()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note: `%%capture` is a Jupyter magic method that suppresses the output of a cell. Otherwise, one would see an output [like this](example-output.ipynb).\n",
     "\n",
-    "The output will be produced in the current working directory, within a `Results` folder. For the case of a custom settings file:\n",
+    "The results files will be produced in the current working directory, within a `Results` folder. For the case of a custom settings file:\n",
     "\n",
     "```python\n",
     "from logging import getLogger\n",

docs/tutorial-code/0-new-decision-metric/Results/MCACapacity.csv

@@ -1,56 +1,63 @@
-,agent,capacity,dst_region,index,installed,region,sector,technology,type,year
-0,A1,10.00000000000,R1,0,2020,R1,residential,gasboiler,newcapa,2020
-0,A1,1.00000000000,R1,0,2020,R1,power,gasCCGT,newcapa,2020
-0,A1,15.00000000000,R1,0,2020,R1,gas,gassupply1,newcapa,2020
-1,A1,5.00000000000,R1,1,2020,R1,residential,gasboiler,newcapa,2025
-2,A1,19.00000000000,R1,11,2020,R1,residential,heatpump,newcapa,2025
-1,A1,1.00000000000,R1,2,2020,R1,power,gasCCGT,newcapa,2025
-11,A1,10.00000000000,R1,26,2020,R1,power,solarPV,newcapa,2025
-24,A1,6.00000000000,R1,49,2020,R1,power,windturbine,newcapa,2025
-1,A1,15.00000000000,R1,1,2020,R1,gas,gassupply1,newcapa,2025
-3,A1,19.00000000000,R1,16,2020,R1,residential,heatpump,newcapa,2030
-4,A1,10.00000000000,R1,17,2025,R1,residential,heatpump,newcapa,2030
-2,A1,2.00000000000,R1,5,2025,R1,power,gasCCGT,newcapa,2030
-14,A1,10.00000000000,R1,34,2020,R1,power,solarPV,newcapa,2030
-15,A1,9.00000000000,R1,35,2025,R1,power,solarPV,newcapa,2030
-35,A1,6.00000000000,R1,72,2020,R1,power,windturbine,newcapa,2030
-2,A1,7.50000000000,R1,4,2020,R1,gas,gassupply1,newcapa,2030
-7,A1,10.00000000000,R1,28,2025,R1,residential,heatpump,newcapa,2035
-8,A1,26.00000000000,R1,29,2030,R1,residential,heatpump,newcapa,2035
-3,A1,2.00000000000,R1,7,2025,R1,power,gasCCGT,newcapa,2035
-16,A1,10.00000000000,R1,40,2020,R1,power,solarPV,newcapa,2035
-17,A1,9.00000000000,R1,41,2025,R1,power,solarPV,newcapa,2035
-18,A1,6.00000000000,R1,42,2030,R1,power,solarPV,newcapa,2035
-45,A1,6.00000000000,R1,87,2020,R1,power,windturbine,newcapa,2035
-3,A1,3.38700000000,R1,7,2030,R1,gas,gassupply1,newcapa,2035
-11,A1,26.00000000000,R1,45,2030,R1,residential,heatpump,newcapa,2040
-12,A1,16.00000000000,R1,46,2035,R1,residential,heatpump,newcapa,2040
-4,A1,2.00000000000,R1,9,2025,R1,power,gasCCGT,newcapa,2040
-19,A1,10.00000000000,R1,52,2020,R1,power,solarPV,newcapa,2040
-20,A1,9.00000000000,R1,53,2025,R1,power,solarPV,newcapa,2040
-21,A1,6.00000000000,R1,54,2030,R1,power,solarPV,newcapa,2040
-22,A1,6.00000000000,R1,55,2035,R1,power,solarPV,newcapa,2040
-56,A1,6.00000000000,R1,116,2020,R1,power,windturbine,newcapa,2040
-4,A1,3.38700000000,R1,9,2030,R1,gas,gassupply1,newcapa,2040
-15,A1,16.00000000000,R1,66,2035,R1,residential,heatpump,newcapa,2045
-16,A1,32.00000000000,R1,67,2040,R1,residential,heatpump,newcapa,2045
-5,A1,2.00000000000,R1,16,2025,R1,power,gasCCGT,newcapa,2045
-35,A1,10.00000000000,R1,90,2020,R1,power,solarPV,newcapa,2045
-36,A1,9.00000000000,R1,91,2025,R1,power,solarPV,newcapa,2045
-37,A1,6.00000000000,R1,92,2030,R1,power,solarPV,newcapa,2045
-38,A1,6.00000000000,R1,93,2035,R1,power,solarPV,newcapa,2045
-39,A1,6.00000000000,R1,94,2040,R1,power,solarPV,newcapa,2045
-79,A1,6.00000000000,R1,190,2020,R1,power,windturbine,newcapa,2045
-5,A1,3.38700000000,R1,16,2030,R1,gas,gassupply1,newcapa,2045
-19,A1,32.00000000000,R1,91,2040,R1,residential,heatpump,newcapa,2050
-20,A1,22.00000000000,R1,92,2045,R1,residential,heatpump,newcapa,2050
-7,A1,2.00000000000,R1,22,2025,R1,power,gasCCGT,newcapa,2050
-8,A1,1.00000000000,R1,23,2045,R1,power,gasCCGT,newcapa,2050
-47,A1,9.00000000000,R1,116,2025,R1,power,solarPV,newcapa,2050
-48,A1,6.00000000000,R1,117,2030,R1,power,solarPV,newcapa,2050
-49,A1,6.00000000000,R1,118,2035,R1,power,solarPV,newcapa,2050
-50,A1,6.00000000000,R1,119,2040,R1,power,solarPV,newcapa,2050
-51,A1,10.00000000000,R1,120,2045,R1,power,solarPV,newcapa,2050
-93,A1,10.00000000000,R1,235,2045,R1,power,windturbine,newcapa,2050
-6,A1,3.38700000000,R1,19,2030,R1,gas,gassupply1,newcapa,2050
-7,A1,1.64630000000,R1,20,2045,R1,gas,gassupply1,newcapa,2050
+agent,capacity,dst_region,installed,region,sector,technology,type,year
+A1,10.00000000000,R1,2020,R1,residential,gasboiler,newcapa,2020
+A1,1.00000000000,R1,2020,R1,power,gasCCGT,newcapa,2020
+A1,15.00000000000,R1,2020,R1,gas,gassupply1,newcapa,2020
+A1,5.00000000000,R1,2020,R1,residential,gasboiler,newcapa,2025
+A1,19.00000000000,R1,2020,R1,residential,heatpump,newcapa,2025
+A1,2.00000000000,R1,2020,R1,power,gasCCGT,newcapa,2025
+A1,10.00000000000,R1,2020,R1,power,solarPV,newcapa,2025
+A1,4.00000000000,R1,2020,R1,power,windturbine,newcapa,2025
+A1,15.00000000000,R1,2020,R1,gas,gassupply1,newcapa,2025
+A1,19.00000000000,R1,2020,R1,residential,heatpump,newcapa,2030
+A1,10.00000000000,R1,2025,R1,residential,heatpump,newcapa,2030
+A1,1.00000000000,R1,2020,R1,power,gasCCGT,newcapa,2030
+A1,3.00000000000,R1,2025,R1,power,gasCCGT,newcapa,2030
+A1,10.00000000000,R1,2020,R1,power,solarPV,newcapa,2030
+A1,7.00000000000,R1,2025,R1,power,solarPV,newcapa,2030
+A1,4.00000000000,R1,2020,R1,power,windturbine,newcapa,2030
+A1,7.50000000000,R1,2020,R1,gas,gassupply1,newcapa,2030
+A1,10.00000000000,R1,2025,R1,residential,heatpump,newcapa,2035
+A1,26.00000000000,R1,2030,R1,residential,heatpump,newcapa,2035
+A1,1.00000000000,R1,2020,R1,power,gasCCGT,newcapa,2035
+A1,3.00000000000,R1,2025,R1,power,gasCCGT,newcapa,2035
+A1,10.00000000000,R1,2020,R1,power,solarPV,newcapa,2035
+A1,7.00000000000,R1,2025,R1,power,solarPV,newcapa,2035
+A1,6.00000000000,R1,2030,R1,power,solarPV,newcapa,2035
+A1,4.00000000000,R1,2020,R1,power,windturbine,newcapa,2035
+A1,6.68000000000,R1,2030,R1,gas,gassupply1,newcapa,2035
+A1,26.00000000000,R1,2030,R1,residential,heatpump,newcapa,2040
+A1,16.00000000000,R1,2035,R1,residential,heatpump,newcapa,2040
+A1,1.00000000000,R1,2020,R1,power,gasCCGT,newcapa,2040
+A1,3.00000000000,R1,2025,R1,power,gasCCGT,newcapa,2040
+A1,10.00000000000,R1,2020,R1,power,solarPV,newcapa,2040
+A1,7.00000000000,R1,2025,R1,power,solarPV,newcapa,2040
+A1,6.00000000000,R1,2030,R1,power,solarPV,newcapa,2040
+A1,5.00000000000,R1,2035,R1,power,solarPV,newcapa,2040
+A1,4.00000000000,R1,2020,R1,power,windturbine,newcapa,2040
+A1,6.68000000000,R1,2030,R1,gas,gassupply1,newcapa,2040
+A1,0.16290000000,R1,2035,R1,gas,gassupply1,newcapa,2040
+A1,16.00000000000,R1,2035,R1,residential,heatpump,newcapa,2045
+A1,32.00000000000,R1,2040,R1,residential,heatpump,newcapa,2045
+A1,1.00000000000,R1,2020,R1,power,gasCCGT,newcapa,2045
+A1,3.00000000000,R1,2025,R1,power,gasCCGT,newcapa,2045
+A1,10.00000000000,R1,2020,R1,power,solarPV,newcapa,2045
+A1,7.00000000000,R1,2025,R1,power,solarPV,newcapa,2045
+A1,6.00000000000,R1,2030,R1,power,solarPV,newcapa,2045
+A1,5.00000000000,R1,2035,R1,power,solarPV,newcapa,2045
+A1,7.00000000000,R1,2040,R1,power,solarPV,newcapa,2045
+A1,4.00000000000,R1,2020,R1,power,windturbine,newcapa,2045
+A1,6.68000000000,R1,2030,R1,gas,gassupply1,newcapa,2045
+A1,0.16290000000,R1,2035,R1,gas,gassupply1,newcapa,2045
+A1,32.00000000000,R1,2040,R1,residential,heatpump,newcapa,2050
+A1,22.00000000000,R1,2045,R1,residential,heatpump,newcapa,2050
+A1,1.00000000000,R1,2020,R1,power,gasCCGT,newcapa,2050
+A1,3.00000000000,R1,2025,R1,power,gasCCGT,newcapa,2050
+A1,7.00000000000,R1,2025,R1,power,solarPV,newcapa,2050
+A1,6.00000000000,R1,2030,R1,power,solarPV,newcapa,2050
+A1,5.00000000000,R1,2035,R1,power,solarPV,newcapa,2050
+A1,7.00000000000,R1,2040,R1,power,solarPV,newcapa,2050
+A1,10.00000000000,R1,2045,R1,power,solarPV,newcapa,2050
+A1,8.00000000000,R1,2045,R1,power,windturbine,newcapa,2050
+A1,6.68000000000,R1,2030,R1,gas,gassupply1,newcapa,2050
+A1,0.16290000000,R1,2035,R1,gas,gassupply1,newcapa,2050
+A1,0.09400000000,R1,2045,R1,gas,gassupply1,newcapa,2050