Merge pull request #503 from EnergySystemsModellingLab/develop

Update main branch

Author: tsmbland

.bumpversion.cfg

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

.github/workflows/pre-commit_autoupdate.yml

@@ -11,7 +11,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
       - uses: browniebroke/pre-commit-autoupdate-action@main
-      - uses: peter-evans/create-pull-request@v6
+      - uses: peter-evans/create-pull-request@v7
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           branch: update/pre-commit-hooks

.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.2
+    rev: v0.6.7
     hooks:
       - id: ruff-format
         types_or: [python, pyi, jupyter]

CITATION.cff

@@ -9,5 +9,5 @@ authors:
       given-names: Adam
 
 title: MUSE_OS
-version: v1.2.0
+version: v1.2.1
 date-released: 2024-08-13

docs/advanced-guide/extending-muse.ipynb

@@ -91,9 +91,10 @@
    "source": [
     "from typing import Optional\n",
     "\n",
-    "from muse.outputs.sector import market_quantity, register_output_quantity\n",
     "from xarray import DataArray, Dataset\n",
     "\n",
+    "from muse.outputs.sector import market_quantity, register_output_quantity\n",
+    "\n",
     "\n",
     "@register_output_quantity\n",
     "def consumption_zero(\n",
@@ -156,6 +157,7 @@
     "[[sectors.residential.outputs]]\n",
     "quantity = \"consumption_zero\"\n",
     "sink = \"txt\"\n",
+    "overwrite = true\n",
     "filename = \"{cwd}/{default_output_dir}/{Sector}{Quantity}{year}{suffix}\"\n",
     "```\n",
     "\n",
@@ -181,9 +183,10 @@
    "source": [
     "from pathlib import Path\n",
     "\n",
-    "from muse import examples\n",
     "from toml import dump, load\n",
     "\n",
+    "from muse import examples\n",
+    "\n",
     "model_path = examples.copy_model(name=\"default_retro\", overwrite=True)\n",
     "settings = load(model_path / \"settings.toml\")\n",
     "new_output = {\n",
@@ -192,7 +195,7 @@
     "    \"overwrite\": True,\n",
     "    \"filename\": \"{cwd}/{default_output_dir}/{Sector}{Quantity}{year}{suffix}\",\n",
     "}\n",
-    "settings[\"sectors\"][\"residential\"][\"outputs\"].append(new_output)\n",
+    "settings[\"sectors\"][\"residential\"].setdefault(\"outputs\", []).append(new_output)\n",
     "dump(settings, (model_path / \"modified_settings.toml\").open(\"w\"))\n",
     "settings"
    ]
@@ -289,6 +292,7 @@
     "\n",
     "import pandas as pd\n",
     "import xarray as xr\n",
+    "\n",
     "from muse.outputs.cache import consolidate_quantity, register_cached_quantity\n",
     "\n",
     "\n",
@@ -361,15 +365,15 @@
    "source": [
     "from pathlib import Path\n",
     "\n",
-    "from muse import examples\n",
     "from toml import dump, load\n",
     "\n",
+    "from muse import examples\n",
+    "\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",
     "    \"sink\": \"aggregate\",\n",
-    "    \"index\": False,\n",
     "    \"filename\": \"{cwd}/{default_output_dir}/Cache{Quantity}.csv\",\n",
     "}\n",
     "settings[\"outputs_cache\"] = []\n",
@@ -503,9 +507,10 @@
    "source": [
     "from pathlib import Path\n",
     "\n",
-    "from muse import examples\n",
     "from toml import dump, load\n",
     "\n",
+    "from muse import examples\n",
+    "\n",
     "model_path = examples.copy_model(name=\"default_retro\", overwrite=True)\n",
     "settings = load(model_path / \"settings.toml\")\n",
     "settings[\"sectors\"][\"residential\"][\"outputs\"] = [\n",
@@ -666,7 +671,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.3"
+   "version": "3.12.4"
   },
   "vscode": {
    "interpreter": {

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

@@ -20,9 +20,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from xarray import DataArray, Dataset\n",
+    "\n",
     "from muse.agents import Agent\n",
     "from muse.filters import register_filter\n",
-    "from xarray import DataArray, Dataset\n",
     "\n",
     "\n",
     "@register_filter\n",
@@ -100,9 +101,10 @@
    "source": [
     "from typing import Any\n",
     "\n",
-    "from muse.decisions import register_decision\n",
     "from xarray import DataArray, Dataset\n",
     "\n",
+    "from muse.decisions import register_decision\n",
+    "\n",
     "\n",
     "@register_decision\n",
     "def median_objective(objectives: Dataset, parameters: Any, **kwargs) -> DataArray:\n",
@@ -147,7 +149,7 @@
    "outputs": [],
    "source": [
     "logging.getLogger(\"muse\").setLevel(0)\n",
-    "mca = MCA.factory(\"../tutorial-code/0-new-decision-metric/settings.toml\")\n",
+    "mca = MCA.factory(\"../tutorial-code/new-decision-metric/settings.toml\")\n",
     "mca.run();"
    ]
   },
@@ -167,7 +169,7 @@
     "import pandas as pd\n",
     "\n",
     "mca_capacity = pd.read_csv(\n",
-    "    \"../tutorial-code/0-new-decision-metric/Results/MCACapacity.csv\"\n",
+    "    \"../tutorial-code/new-decision-metric/Results/MCACapacity.csv\"\n",
     ")\n",
     "power_capacity = (\n",
     "    mca_capacity[mca_capacity.sector == \"power\"]\n",

docs/conf.py

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

docs/inputs/agents.rst

@@ -103,12 +103,12 @@ Objective1
 
 .. _Objective2:
 
-Objective2
+Objective2 (optional)
    Second objective. See :ref:`Objective1 <Objective1>`.
 
 .. _Objective3:
 
-Objective3:
+Objective3 (optional)
    Third objective. See :ref:`Objective1 <Objective1>`.
 
 .. _ObjData1:
@@ -117,11 +117,11 @@ ObjData1
    A weight associated with the :ref:`first objective <Objective1>`. Whether it is used
    will depend in large part on the :ref:`decision method <DecisionMethod>`.
 
-ObjData2
+ObjData2 (optional)
    A weight associated with the :ref:`second objective <Objective2>`. See :ref:`ObjData1
    <ObjData1>`.
 
-ObjData3
+ObjData3 (optional)
    A weight associated with the :ref:`third objective <Objective3>`. See :ref:`ObjData1
    <ObjData1>`.
 
@@ -132,15 +132,13 @@ Objsort1
    "adhoc" and "scipy" solvers this should be set to "True" for minimization and
    "False" for maximisation.
 
-Objsort2
-   Sets whether :ref:`second objective <Objective2>` is maximized or minimized. For both
-   "adhoc" and "scipy" solvers this should be set to "True" for minimization and
-   "False" for maximisation.
+Objsort2 (optional)
+   Objsort parameter for :ref:`second objective <Objective2>`. See :ref:`Objsort1
+   <Objsort1>`.
 
-Objsort3
-   Sets whether :ref:`third objective <Objective3>` is maximized or minimized. For both
-   "adhoc" and "scipy" solvers this should be set to "True" for minimization and
-   "False" for maximisation.
+Objsort3 (optional)
+   Objsort parameter for :ref:`third objective <Objective3>`. See :ref:`Objsort1
+   <Objsort1>`.
 
 .. py:currentmodule:: muse.filters
 
@@ -161,7 +159,7 @@ SearchRule
 
    - :py:func:`similar_technology <similar_technology>`: Only allows technologies that
      have the same type as current crop of technologies in the agent, as determined by
-     "tech_type" in :ref:`inputs-technodata`. Aliased to "similar".
+     "Type" in :ref:`inputs-technodata`. Aliased to "similar".
 
    - :py:func:`same_fuels <same_fuels>`: Only allows technologies that consume the same
      fuels as the current crop of technologies in the agent. Aliased to
@@ -219,8 +217,8 @@ DecisionMethod
 Quantity
    A factor used to determine the demand share of "New" agents.
 
-MaturityThreshold
-   Parameter for the search rule :py:func:`maturity <muse.filters.maturity>`.
+MaturityThreshold (optional)
+   Required when using the :py:func:`maturity <muse.filters.maturity>` search rule.
 
-SpendLimit
-   Parameter for the search rule :py:func:`spend_limit <muse.filters.spend_limit>`.
+SpendLimit (optional)
+   Required when using the :py:func:`spend_limit <muse.filters.spend_limit>` search rule.

docs/inputs/commodities.rst

@@ -16,38 +16,36 @@ a whole are defined in a csv file with the following structure.
    Agricultural-residues, Energy, agrires, 112, 15.4, PJ
 
 Commodity
-   represents the extended name of a commodity
+   represents the extended name of a commodity (e.g. "Heating" or "Electricity").
+
+CommodityName
+   the internal name used for a commodity inside the model (e.g. "heat" or "elec").
+   Any references to commodities in other files must use these names.
 
 CommodityType
    defines the type of a commodity (i.e. Energy, Service, Material, or Environmental).
 
-   The "energy" type includes the energy commodities, such as biomass, electricity, gasoline, and hydrogen,
+   The "energy" type includes energy commodities, such as biomass, electricity, gasoline, and hydrogen,
    which are either extracted, transformed from one to another, or used in the energy system.
 
    The "service" type includes commodities such as space heating or hot water which correspond to selected
-   poples' needs whose fulfillment requires energy uses.
+   people's needs, and whose fulfillment requires energy uses.
 
    The "material" type represent non-energy inputs for energy technologies, such as limestone or oxygen.
+
    The "environmental" type refers to non-energy commodities whichare used to quantify an impact on the environment,
    such as greenhouse gases or CO2. They can be subjected to different types of environmental fees or taxes.
 
-CommodityName
-   is the internal name used for a commodity inside the model.
-
-CommodityEmissionFactor_CO2
+CommodityEmissionFactor_CO2 (optional)
    is CO2 emission per unit of commodity flow.
    This commodity property is not directly used in the MUSE core set of equations, but can be further referred to
    for any subsequent development of the code.
 
-HeatRate
+HeatRate (optional)
    represents the lower heating value of an energy commodity
    This commodity property is not directly used in the MUSE core set of equations, but can be further referred to
    for any subsequent development of the code.
 
-Unit
-   is the unit used as a basis for all the input data. More specifically the model allows
-   a totally flexible way of defining the commodities. CommodityName is currently the
-   only column used internally as it defines the names of commodities and needs to be
-   used consistently across all the input data files. The remaining columns of the file
-   are only relevant for the user internal reference for the original sets of
-   assumptions used.
+Unit (optional)
+   is the unit used to represent quantities of the commodity (e.g "PJ").
+   This parameter does not need to be included, as it isn't used in the model, but care should be taken to ensure that units are consistent across all input files.

docs/inputs/existing_capacity.rst

@@ -24,7 +24,7 @@ ProcessName
 RegionName
    represents the region ID and needs to be consistent across all the data inputs.
 
-Unit
+Unit (optional)
    reports the unit of the technology capacity; it is for the user internal reference only.
 
 2010,..., 2050