EnergySystemsModellingLab · tsmbland · Jan 6, 2026 · Jan 6, 2026 · Jan 6, 2026 · Jan 6, 2026
diff --git a/docs/api.rst b/docs/api.rst
@@ -75,8 +75,7 @@ Agents and associated functionalities
 -------------------------------------
 
 .. automodule:: muse.agents.factories
-   :members: agents_factory, create_agent, create_retrofit_agent, create_newcapa_agent,
-       factory
+   :members: agents_factory, create_agent, create_retrofit_agent, create_newcapa_agent
 
 
 .. autoclass:: muse.agents.agent.AbstractAgent
@@ -129,9 +128,11 @@ Constraints:
 ~~~~~~~~~~~~
 
 .. automodule:: muse.constraints
-    :members: demand, factory, max_capacity_expansion, max_production, lp_costs,
-        lp_constraint, lp_constraint_matrix, register_constraints, search_space,
-        ScipyAdapter
+   :members: demand, factory, max_capacity_expansion, max_production,
+      register_constraints, search_space, minimum_service, demand_limiting_capacity
+
+.. automodule:: muse.lp_adapter
+   :members: lp_costs, lp_constraint, lp_constraint_matrix, ScipyAdapter
 
 Initial and Final Asset Transforms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -150,9 +151,6 @@ Reading the inputs
 .. automodule:: muse.readers.csv
    :members:
 
-.. automodule:: muse.decorators
-   :members:
-
 ---------------
 Writing Outputs
 ---------------
@@ -170,6 +168,18 @@ Sectorial Outputs
 .. automodule:: muse.outputs.sector
    :members:
 
+Global Outputs
+~~~~~~~~~~~~~~
+
+.. automodule:: muse.outputs.mca
+   :members:
+
+Cache
+~~~~~
+
+.. automodule:: muse.outputs.cache
+   :members:
+
 
 ----------
 Quantities
@@ -215,6 +225,12 @@ Functionality Registration
 .. automodule:: muse.registration
    :members:
 
+Costs
+~~~~~
+
+.. automodule:: muse.costs
+   :members:
+
 Utilities
 ~~~~~~~~~
 

diff --git a/docs/application-flow.rst b/docs/application-flow.rst
@@ -1,7 +1,7 @@
 Application Flow
 ================
 
-While not essential to be able to use MUSE, it is useful to know the sequence of events that a run of MUSE will follow in a bit more detail that the brief overview of the :ref:`MUSE Overview` section. Let's start with the big picture.
+While not essential to be able to use MUSE, it is useful to know the sequence of events that a run of MUSE will follow in a bit more detail than the brief overview of the :doc:`MUSE Overview <overview>` section. Let's start with the big picture.
 
 .. note::
 
@@ -245,7 +245,7 @@ The sequence of steps related to the carbon budget control are as follows:
             single_year [label="Single year\niteration", fillcolor="lightgrey", style="rounded,filled"]
             emissions [label="Calculate emissions\nof carbon comodities"]
             comparison [label="Emissions\n> budget\n", shape=diamond, style=""]
-            new_price [label="Calculate new\ncarbon price", fillcolor="lightgrey", style="rounded,filled"]
+            new_price_node [label="Calculate new\ncarbon price", fillcolor="lightgrey", style="rounded,filled"]
 
 
             subgraph cluster_1 {
@@ -255,8 +255,8 @@ The sequence of steps related to the carbon budget control are as follows:
 
             start -> single_year
             comparison -> end [label="No", constraint=false]
-            comparison -> new_price [label="Yes"]
-            new_price -> end
+            comparison -> new_price_node [label="Yes"]
+            new_price_node -> end
         }
 
 The **method used to calculate the new carbon price** can be selected by the user. There are currently only two options for this method, ``fitting`` and ``bisection``, however this can be expanded by the user with the ``@register_carbon_budget_method`` hook in ``muse.carbon_budget``.
@@ -440,15 +440,15 @@ The following graph summarises the process.
             input_search[label="SearchRule\n(Agents.csv)", fillcolor="#ffb3b3", style="rounded,filled"]
             input_objectives[label="Objective\n(Agents.csv)s", fillcolor="#ffb3b3", style="rounded,filled"]
             input_decision[label="DecisionMethod\n(Agents.csv)", fillcolor="#ffb3b3", style="rounded,filled"]
-            input_constrains[label="Constrains\n(settings.toml)", fillcolor="#ffb3b3", style="rounded,filled"]
+            input_constraints[label="Constraints\n(settings.toml)", fillcolor="#ffb3b3", style="rounded,filled"]
             input_solver[label="lpsolver\n(settings.toml)", fillcolor="#ffb3b3", style="rounded,filled"]
 
-            start ->  demand_share -> search -> objectives -> decision -> constrains -> invest -> end
+            start ->  demand_share -> search -> objectives -> decision -> constraints -> invest -> end
             input_demand -> demand_share
             input_search -> search
             input_objectives -> objectives
             input_decision -> decision
-            input_constrains -> constrains
+            input_constraints -> constraints
             input_solver -> invest
         }
 
@@ -463,7 +463,7 @@ For those selected replacement technologies, an objective function is computed.
 
 Then, a decision is computed. Decision methods reduce multiple objectives into a single scalar objective per replacement technology. The decision method to use is selected in the ``Agents.csv`` file. They allow combining several objectives into a single metric through which replacement technologies can be ranked. See :py:mod:`muse.decisions`.
 
-The final step of preparing the investment process is to compute the constrains, e.g. factors that will determine how much a technology could be invested in and include things like matching the demand, the search rules calculated above, the maximum production of a technology for a given capacity or the maximum capacity expansion for a given time period. Available constrains are set in the subsector section of the ``settings.toml`` file and described in :py:mod:`muse.constrains`. By default, all of them are applied. Note that these constrains might result in unfeasible situations if they do not allow the production to grow enough to match the demand. This is one of the common reasons for a MUSE simulation not converging.
+The final step of preparing the investment process is to compute the constraints, e.g. factors that will determine how much a technology could be invested in and include things like matching the demand, the search rules calculated above, the maximum production of a technology for a given capacity or the maximum capacity expansion for a given time period. Available constraints are set in the subsector section of the ``settings.toml`` file and described in :py:mod:`muse.constraints`. By default, all of them are applied. Note that these constraints might result in unfeasible situations if they do not allow the production to grow enough to match the demand. This is one of the common reasons for a MUSE simulation not converging.
 
 With all this information, the investment process can proceed. This is done per sector using the method described by the ``lpsolver`` in the ``settings.toml`` file. Available solvers are described in :py:mod:`muse.investments`
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -50,14 +50,19 @@
 add_module_names = False
 nbsphinx_allow_errors = True
 autosectionlabel_prefix_document = True
+nitpicky = True
+
+# Suppress warnings for documents not included in any toctree (e.g. release notes)
+suppress_warnings = ["toc.not_included"]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "numpy": ("http://docs.scipy.org/doc/numpy/", None),
-    "pandas": ("http://pandas.pydata.org/pandas-docs/dev", None),
-    "xarray": ("http://xarray.pydata.org/en/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "xarray": ("https://xarray.pydata.org/en/stable/", None),
 }
 
+
 bibtex_bibfiles: list[str] = []
 
 # -- GraphViz configuration ----------------------------------

diff --git a/docs/inputs/agents.rst b/docs/inputs/agents.rst
@@ -7,7 +7,11 @@ Agents
 Agents are defined using a CSV file, with
 one agent per row, using a format meant specifically for retrofit and new-capacity agent pairs.
 
-For instance, we have the following CSV table:
+Each sector should have an agents file, which should follow the structure
+reported in the table below, and be referenced from the TOML settings file using the
+``agents`` key.
+
+This is an example of what an agents file could look like:
 
 .. csv-table::
    :header: name, type, agent_share, region, objective1, search_rule, decision_method, ...

diff --git a/docs/inputs/commodities.rst b/docs/inputs/commodities.rst
@@ -6,7 +6,8 @@ Global Commodities
 
 MUSE handles a configurable number and type of commodities which are primarily used to
 represent energy, services, pollutants/emissions. The commodities for the simulation as
-a whole are defined in a csv file with the following structure.
+a whole are defined in a csv file with the following structure, which is referenced from
+the TOML settings file using the ``global_commodities`` key.
 
 .. csv-table:: Global commodities
    :header: commodity, description, commodity_type, unit

diff --git a/docs/inputs/commodities_io.rst b/docs/inputs/commodities_io.rst
@@ -1,8 +1,8 @@
 .. _inputs-iocomms:
 
-=================
+=========================
 Commodity Inputs/Outputs
-=================
+=========================
 
 **Input**
 
@@ -37,8 +37,10 @@ to cover space heating and water heating energy service demands.
    :alt: Electric boilers input output commodities
 
 
-Below it is shown the generic structure of the input commodity file for the electric
-heater.
+Each sector in MUSE should have two separate CSV files for commodity inputs and outputs,
+each of which should follow the structure reported in the table below. These should be
+referenced from the TOML settings file using the ``commodities_in`` and ``commodities_out`` keys
+respectively.
 
 .. csv-table:: Commodities used as consumables - Input commodities
    :header: technology, region, year, level, electricity

diff --git a/docs/inputs/correlation_files.rst b/docs/inputs/correlation_files.rst
@@ -1,3 +1,5 @@
+.. _correlation-files:
+
 Correlation Demand Files
 ========================
 
@@ -11,7 +13,9 @@ To do this, a minimum of three files are required:
 
 #. A file which dictates how the demand per benchmark year is split across the timeslices.
 
-We will go into the details of each of these files below.
+These files (explained in more detail below) should be referenced from the TOML settings
+file using the ``macrodrivers_path``, ``regression_path``, and ``timeslice_shares_path``
+keys respectively.
 
 Macrodrivers
 ------------

diff --git a/docs/inputs/existing_capacity.rst b/docs/inputs/existing_capacity.rst
@@ -4,20 +4,19 @@
 Existing Capacity
 ==========================
 
-For each technology, the decommissioning profile should be given to MUSE.
-
-The csv file which provides the installed capacity in base year and the decommissioning
-profile in the future periods for each technology in a sector, in each region, should
-follow the structure reported in the table.
+This file provides the installed capacity in base year and the decommissioning
+profile in the future periods for each technology in a sector, in each region.
 
+Each sector should have an existing capacity file, which should follow the structure
+reported in the table below, and be referenced from the TOML settings file using the
+``existing_capacity`` key.
 
 .. csv-table:: Existing capacity of technologies: the residential boiler example
    :header: technology, region, 2010, 2020, 2030, 2040, 2050
 
    resBoilerElectric, region1, 5, 0.5, 0, 0, 0
    resBoilerElectric, region2, 39, 3.5, 1, 0.3, 0
 
-
 ``technology``
    represents the technology ID and needs to be consistent across all the data inputs.
 

diff --git a/docs/inputs/index.rst b/docs/inputs/index.rst
@@ -4,7 +4,30 @@
 Input Files
 ===========
 
-In this section we detail each of the files required to run MUSE. We include information based on how these files should be used, as well as the data that populates them.
+In this section we detail each of the files required to run MUSE.
+We include information based on how these files should be used, as well as the data that populates them.
+
+All MUSE simulations require a settings file in TOML format (see :ref:`toml-primer` and :ref:`simulation-settings`), as well as a set of CSV files that provide the simulation data.
+
+Whilst file names and paths are fully flexible and can be configured via the settings TOML,
+a typical minimal file layout might look something like this:
+
+model_name/
+    - :ref:`settings.toml <simulation-settings>`
+    - :ref:`GlobalCommodities.csv <inputs-commodities>`
+    - :ref:`Projections.csv <inputs-projection>`
+    - sector1/
+        - :ref:`Technodata.csv <inputs-technodata>`
+        - :ref:`CommoditiesIn.csv <inputs-iocomms>`
+        - :ref:`CommoditiesOut.csv <inputs-iocomms>`
+        - :ref:`ExistingCapacity.csv <inputs-existing-capacity>`
+        - :ref:`Agents.csv <inputs-agents>`
+    - presets/
+        - :ref:`Consumption2020.csv <preset-consumption-file>`
+        - etc.
+
+Note, however, that this is just a convention for simple models, and more complex models may benefit from or require a different file structure.
+See full documentation below for more details on the settings TOML and all the different types of data file.
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/inputs/inputs_csv.rst b/docs/inputs/inputs_csv.rst
@@ -2,6 +2,8 @@
 Simulation Data Files
 =====================
 
+.. _inputs_csv:
+
 This section details the CSV files that are used to populate the simulation data.
 
 .. toctree::
@@ -15,4 +17,5 @@ This section details the CSV files that are used to populate the simulation data
    commodities_io
    existing_capacity
    agents
+   preset_commodity_demands
    correlation_files
diff --git a/docs/inputs/preset_commodity_demands.rst b/docs/inputs/preset_commodity_demands.rst
@@ -0,0 +1,33 @@
+.. _preset-consumption-file:
+
+Preset Commodity Demands
+=============================
+
+
+This document describes the CSV files used to supply pre-set commodity consumption
+profiles to MUSE. These files are referenced from the TOML setting ``consumption_path``
+and are typically provided one file per year (file names must include the year, e.g.
+``Consumption2015.csv``). Wildcards are supported in the path (for example
+``{cwd}/Consumption*.csv``).
+
+The CSV format should follow the structure shown in the example below.
+
+.. csv-table:: Consumption
+   :header: "RegionName", "Timeslice", "electricity", "diesel", "algae"
+   :stub-columns: 2
+
+   USA,1,1.9,0,0
+   USA,2,1.8,0,0
+
+``RegionName``
+   The region identifier. Must match region IDs used across other inputs.
+
+``Timeslice``
+   Index of the timeslice, according to the timeslice definition in the settings TOML.
+   Indexing starts at 1 (i.e. the first timeslice defined in
+   the global timeslices definition is 1, the second is 2, etc).
+
+Commodities (one column per commodity)
+   Any additional columns represent commodities. Column names must match the
+   commodity identifiers defined in the global commodities file. Values are the
+   consumption quantities for that timeslice and region.
diff --git a/docs/inputs/projections.rst b/docs/inputs/projections.rst
@@ -1,8 +1,7 @@
 .. _inputs-projection:
 
-=========================
 Commodity Price Projections
-=========================
+===========================
 
 This file can be used to supply pre-set prices for commodities.
 The interpretation of these prices depends on the type of commodity:
@@ -25,7 +24,8 @@ The interpretation of these prices depends on the type of commodity:
   Lack of a price trajectory will be interpreted as a price of 0 for all periods (i.e. no levy on production),
   again with the exception of the carbon budget mode.
 
-The price trajectory should follow the structure shown in the table below.
+Price trajectories should be stored in a CSV file with the structure shown in the
+table below, and referenced from the TOML settings file using the ``projections`` key.
 
 .. csv-table:: Initial market projections
    :header: region, attribute, year, com1, com2, com3

diff --git a/docs/inputs/technodata.rst b/docs/inputs/technodata.rst
@@ -5,7 +5,9 @@ Technodata
 ===========
 The technodata includes the techno-economic characteristics of each technology such
 as capital, fixed and variable cost, lifetime, utilization factor.
-The technodata should follow the structure reported in the table below.
+Models should have one technodata file for each sector, which is referenced
+in the TOML settings file using the ``technodata`` key.
+Technodata files should follow the structure reported in the table below.
 In this example, we show an electric boiler for a generic region, region1:
 
 .. csv-table:: Technodata

diff --git a/docs/inputs/technodata_timeslices.rst b/docs/inputs/technodata_timeslices.rst
@@ -6,6 +6,8 @@ Technodata Timeslices
 The techno-data timeslices is an optional file which allows technology utilization factors and minimum service factors to be specified for each timeslice.
 For instance, if you were to model solar photovoltaics, you would probably want to specify that they can not produce any electricity at night, or if you're modelling a nuclear power plant, that they must generate a minimum amount of electricity.
 
+Technodata timeslice files, if present, should follow the structure reported in the table below, and be referenced from the TOML settings file using the ``technodata_timeslices`` key.
+
 .. csv-table:: Techno-data
    :header: technology,region,year,month,day,hour,utilization_factor,minimum_service_factor