Small documentation improvements and fix warnings (#812)

* Fix documentation warnings

* More fixes

* More fixes

* More API docs

* More fixes

* More fixes

* Fix one more link

* Fix issues with Input Files page

* More detail about how to reference each data file

Author: tsmbland

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
 ~~~~~~~~~
 

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`
 

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 ----------------------------------

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, ...

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

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

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
 ------------

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.
 

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

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