Clean up documentation for input files (#761)

* Clean up documentation for input files

* Update settings documentation

* Further adjustments

* Add horizontal lines to break up page

* Add extra details to close issues

* Remove incorrect parameter

Author: tsmbland

docs/inputs/agents.rst

@@ -4,14 +4,8 @@
 Agents
 ======
 
-In MUSE, an agent-based formulation was originally introduced for the residential and
-commercial building sectors (`Sachs et al. (2019) <https://doi.org/10.1016/j.energy.2019.01.161>`_).  Agents are defined using a CSV file, with
-one agent per row, using a format meant specifically for retrofit
-and new-capacity agent pairs. This CSV file can be read using
-:py:func:`~muse.readers.csv.read_agent_parameters`. The data is also
-interpreted to some degree in the factory functions
-:py:func:`~muse.agent.create_retrofit_agent` and
-:py:func:`~muse.agent.create_newcapa_agent`.
+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:
 
@@ -29,38 +23,36 @@ The columns have the following meaning:
 
 .. _name:
 
-Name
+``Name``
    Name shared by a retrofit and new-capacity agent pair.
 
-Type
-   One of "New" or "Retrofit". "New" and "Retrofit" agents make up a pair with a given
+``Type``
+   One of **New** or **Retrofit**. **New** and **Retrofit** agents make up a pair with a given
    :ref:`name <Name>`. The demand is split into two, with one part coming from
    decommissioned assets, and the other coming from everything else. "Retrofit" agents
    invest only to make up for decommissioned assets. They are often limited in the
-   technologies they can consider (by :ref:`SearchRule <SearchRule>`). "New" agents
+   technologies they can consider (by :ref:`SearchRule <SearchRule>`). **New** agents
    invest on the rest of the demand, and can often consider more general sets of
-   technologies. If only "New" agents are included, they will also invest to make up for
+   technologies. If only **New** agents are included, they will also invest to make up for
    decommissioned assets, but the end mix might be different than using a specialised
-   "Retrofit" agent for that.
-   *Note: Retrofit agents will be deprecated in a future release.*
+   **Retrofit** agent for that.
+   **Note: Retrofit agents will be deprecated in a future release.**
 
-AgentShare
+``AgentShare``
    Name used to assign a fraction of existing capacity to the agent in the :ref:`inputs-technodata` file.
    If using "New" and "Retrofit" agents, you should create a column with the name of each "Retrofit" agent share (e.g. "Agent1Retro", "Agent2Retro" etc.) in the :ref:`inputs-technodata` file,
    with values summing to 1 for each technology.
    If only using "New" agents, you should create a column with the name of each "New" agent share in the :ref:`inputs-technodata` file,
    with values summing to 1 for each technology.
    See documentation for the :ref:`inputs-technodata` file for more details.
 
-RegionName
+``RegionName``
    Region where an agent operates.
 
 .. py:currentmodule:: muse.objectives
 
-.. _Objective1:
-
-Objective1
-   First objective that an agent will try and maximize or minimize during investment.
+``Objective1``
+   Objective that an agent will try and maximize or minimize during investment.
    This objective should be one registered with
    :py:func:`@register_objective <register_objective>`. The following objectives are
    available with MUSE:
@@ -104,50 +96,27 @@ Objective1
    :ref:`Objsort1 <Objsort1>`. Multiple objectives are combined using the
    :ref:`DecisionMethod <DecisionMethod>`
 
-.. _Objective2:
-
-Objective2 (optional)
-   Second objective. See :ref:`Objective1 <Objective1>`.
-
-.. _Objective3:
-
-Objective3 (optional)
-   Third objective. See :ref:`Objective1 <Objective1>`.
 
-.. _ObjData1:
+``ObjData1``
+   A weight associated with the objective.
+   Whether it is used will depend in large part on the :ref:`decision method <DecisionMethod>`.
 
-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 (optional)
-   A weight associated with the :ref:`second objective <Objective2>`. See :ref:`ObjData1
-   <ObjData1>`.
+``Objsort1``
+   Determines whether the objective is maximized or minimized.
+   This should be set to "True" for minimization and "False" for maximisation.
 
-ObjData3 (optional)
-   A weight associated with the :ref:`third objective <Objective3>`. See :ref:`ObjData1
-   <ObjData1>`.
+Additional objectives
+   For certain decision methods you can use more than one objective.
+   In this case, additional objectives can be specified with additional columns (e.g. ``Objective2``, ``ObjData2``, ``Objsort2`` etc.)
+   For example, when using the weighted sum decision method, the ``ObjDataX`` column for each objective defines the weight of the objective in the weighted sum calculation.
 
-.. _Objsort1:
-
-Objsort1
-   Sets whether :ref:`first objective <Objective1>` 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 (optional)
-   Objsort parameter for :ref:`third objective <Objective3>`. See :ref:`Objsort1
-   <Objsort1>`.
 
 .. py:currentmodule:: muse.filters
 
 .. _SearchRule:
 
-SearchRule
+``SearchRule``
    The search rule allows users to par down the search space of technologies to those an
    agent is likely to consider.
    The search rule is any function with a given signature, and registered with MUSE via
@@ -186,7 +155,7 @@ SearchRule
 
 .. _DecisionMethod:
 
-DecisionMethod
+``DecisionMethod``
    Decision methods reduce multiple objectives into a single scalar objective per
    replacement technology. They allow combining several objectives into a single metric
    through which replacement technologies can be ranked.
@@ -217,18 +186,21 @@ DecisionMethod
    The functions allow for any number of objectives. However, the format described here
    allows only for three.
 
-Quantity
+``Quantity``
    Represents the fraction of new demand that is assigned to the agent
    (e.g. if 0.2, 20% of new demand in each year will be assigned to the agent).
    Must sum to 1 across all "New" agents.
    When using both "Retrofit" agents and "New" agents, this only applies to the "New" agents.
 
-MaturityThreshold (optional)
+Additional optional columns
+   Certain columns may also be required when using certain search rules. These are:
+
+  ``MaturityThreshold``
    Only applies when using the :py:func:`maturity <muse.filters.maturity>` search rule.
    Allows agents to only consider technologies that have achieved a certain market share
    (e.g. if 0.5, the agent will only invest in technologies that have a current market share of 50% or more).
 
-SpendLimit (optional)
+  ``SpendLimit``
    Only applies when using the :py:func:`spend_limit <muse.filters.spend_limit>` search rule.
    Allows agents to only consider technologies with a unit capital cost (`cap_par`) lower than the spend limit.
    (e.g. if 10, the agent will only invest in technologies with a `cap_par` of 10 or lower, as listed in the :ref:`inputs-technodata` file).

docs/inputs/commodities.rst

@@ -9,33 +9,38 @@ represent energy, services, pollutants/emissions. The commodities for the simula
 a whole are defined in a csv file with the following structure.
 
 .. csv-table:: Global commodities
-   :header: Commodity, CommodityType, CommodityName, CommodityEmissionFactor_CO2, HeatRate, Unit
+   :header: CommodityName, Description, CommodityType, Unit
 
+   hardcoal, Coal, Energy, PJ
+   agires, Agricultural-residues, Energy, PJ
 
-   Coal, Energy, hardcoal, 94.6, 29, PJ
-   Agricultural-residues, Energy, agrires, 112, 15.4, PJ
-
-CommodityName
+``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.
 
-Description
+``Description`` (optional)
    an extended name/description of a commodity (e.g. "Heating" or "Electricity").
 
-CommodityType
-   defines the type of a commodity (i.e. Energy, Service, Material, or Environmental).
+``CommodityType``
+   defines the type of a commodity:
 
-   The "energy" type includes 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
+   The **service** type includes commodities such as space heating or hot water which correspond to selected
    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 **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,
+   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.
 
-Unit (optional)
+``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.
+   This parameter does not need to be included, as it isn't used in the model, but is
+   highly recommended for documentation purposes.
+   In any case, care should be taken to ensure that units are consistent across all input files.
+
+Additional optional columns
+   Users can provide additional columns for extra information about the commodity (e.g. ``heat_rate``).
+   These will be ignored by the model, but can be useful for documentation purposes.

docs/inputs/commodities_io.rst

@@ -1,17 +1,16 @@
 .. _inputs-iocomms:
 
 =================
-Commodities
+Commodity inputs/outputs
 =================
 
-Input
+**Input**
 
 Input commodities are the commodities consumed by each
 technology.  They are defined in a csv file which describes the commodity inputs to each
-technology, calculated per unit of technology activity, Where the unit is defined by the user (e.g. petajoules).
-
-Output
+technology, calculated per unit of technology activity.
 
+**Output**
 
 Output commodities are the commodities produced by each
 technology.  They are defined in a csv file which describes the commodity outputs from
@@ -20,11 +19,10 @@ each technology, defined per unit of technology activity. Emissions, such as CO2
 for in this file.
 
 
-General features
-
+**General features**
 
-To illustrate the data required for a generic technology in MUSE, the *electric boiler
-technology* is used as an example. The commodity flow for the electric boiler, capable
+To illustrate the data required for a generic technology in MUSE, the *electric boiler*
+technology is used as an example. The commodity flow for the electric boiler, capable
 to cover space heating and water heating energy service demands.
 
 .. figure:: commodities_io.png
@@ -49,17 +47,17 @@ heater.
    resBoilerElectric, region1, 2030, fixed, 290
 
 
-ProcessName
+``ProcessName``
    represents the technology ID and needs to be consistent across all the data inputs.
 
-RegionName
+``RegionName``
    represents the region ID and needs to be consistent across all the data inputs.
 
-Time
+``Time``
    represents the period of the simulation to which the value applies; it needs to
    contain at least the base year of the simulation.
 
-Level (for **input** commodities only)
+``Level`` (for **input** commodities only)
    characterises inputs as either "fixed" or "flexible".
    Fixed inputs are always used by a technology in a fixed proportion.
    Flexible inputs allow a technology to choose amongst several alternative fuels,
@@ -70,10 +68,17 @@ Level (for **input** commodities only)
    If a process has a mix of fixed and flexible inputs, these should be split over two rows.
    Defaults to "fixed".
 
-The remaining columns should contain the full list of commodities.
-
+Commodities (one column per commodity)
+   Any further columns represent commodities, with names matching those
+   defined in the global commodities file.
+   The values in these columns represent the quantity of the commodity consumed or produced by the technology per unit of activity.
+   You do not need to specify all commodities,
+   only those that are consumed or produced by the technologies in the sector
 
+--------------------------------
 
-The input data has to be provided for the base year. Additional years within the time
-framework of the overall simulation can be defined. In this case, MUSE would interpolate
-the values between the provided periods and assume a constant value afterwards.
+The input data has to be provided for the base year, after which MUSE will assume
+that values are constant for all subsequent years, if no further data is provided.
+If users wish to vary parameters by year, they can provide rows for additional years.
+In this case, MUSE would interpolate the values between the provided periods and assume
+a constant value afterwards.

docs/inputs/correlation_files.rst

@@ -41,16 +41,16 @@ An example of a shortened macrodriver file is shown below. This file contains th
      - 81.82599
      - ...
 
-Variable
+``Variable``
     This is the variable that you would like to use in the regression for the service demand.
 
-RegionName
+``RegionName``
     This is the region that the data applies to. This must correlate with the regions set in the rest of your input files, as well as the toml file.
 
-Unit
+``Unit``
     This unit can be whatever you like, however they must be consistent across all input files.
 
-2010, 2011, ...
+Years (one column per year)
     This is the quantity of the variable per year of the simulation.
 
 
@@ -69,10 +69,10 @@ An example file is shown below:
    Residential,logistic-sigmoid,GDPscaleLess,R1,0,0,753.1068725,0
    Residential,logistic-sigmoid,GDPscaleGreater,R1,0,0,672.9316672,0
 
-SectorName
+``SectorName``
     This is the sector name in which these parameters apply to.
 
-FunctionType
+``FunctionType``
     This is the function type you would like to MUSE to use. MUSE allows these to be:
 
         - Exponential
@@ -85,13 +85,13 @@ FunctionType
 
     Your own functions can be created using the `@register_regression` hook, from the `regressions.py` file.
 
-Coeff
+``Coeff``
     This is the coefficient for the respective function type. These are explicitly defined within the `regressions.py` file, as they differ between functions.
 
-RegionName
+``RegionName``
     This is the region in which these parameters apply to.
 
-Energy service (electricity, gas, heat, CO2f)
+Commodities (one column per commodity)
     Here you can specify the coefficients for the expected demand for the respective commodity.
 
 
@@ -112,11 +112,11 @@ An example file is shown below:
     5,R1,0,0,0.014145,0,0
     6,R1,0,0,0.085783,0,0
 
-SN
+``SN``
     This is the timeslice index.
 
-RegionName
+``RegionName``
     This is the region in question for this data.
 
-Energy service (electricity, gas, heat, CO2f, wind)
+Commodities (one column per commodity)
     Here you specify the proportion of each energy service for each timeslice.

docs/inputs/existing_capacity.rst

@@ -18,11 +18,11 @@ follow the structure reported in the table.
    resBoilerElectric, region2, 39, 3.5, 1, 0.3, 0
 
 
-ProcessName
+``ProcessName``
    represents the technology ID and needs to be consistent across all the data inputs.
 
-RegionName
+``RegionName``
    represents the region ID and needs to be consistent across all the data inputs.
 
-2010,..., 2050
+Years (one column per year)
    represent the simulated periods.