More clarity in the documentation about optional parameters

Author: tsmbland

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

@@ -21,13 +21,14 @@ Commodity
 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
    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.
 

docs/inputs/technodata.rst

@@ -114,22 +114,22 @@ TechnicalLife
 UtilizationFactor
    represents the *maximum* actual output of the technology in a year, divided by the theoretical maximum output if the technology were operating at full capacity for the whole year. Must be between 0 and 1.
 
-MinimumServiceFactor
+MinimumServiceFactor (optional, default = 0)
    Is the *minimum* output of the technology in a year, divided by the theoretical maximum output if the technology were operating at full capacity for the whole year. Must be between 0 and 1 and be smaller or equal than the `UtilizationFactor`. It is used to define the minimum service level that a technology must provide due to, typically, technical or efficiency constraints.
 
-ScalingSize
-   represents the reference capacity at which capital costs are estimated when used as agents' objective as described in :ref:`inputs-agents`.
+ScalingSize (optional)
+   required when using the "capital_costs" agent objective. Represents the reference capacity at which capital costs are estimated when using this objective (see :ref:`inputs-agents`).
 
-efficiency
-   represents the technology efficiency used as agents' objective to sort investment according to their energy or material efficiency (see :ref:`inputs-agents`).
+efficiency (optional)
+   represents the technology efficiency. Required when using the "efficiency" agent objective, which ranks investment options according to their energy or material efficiency (see :ref:`inputs-agents`).
 
-Type
-   defines the type of a technology. This variable is used for the search space in the agents csv file. It allows for the agents to filter for technologies of a similar type, for example.
+Type (optional)
+   defines the type of a technology. Required when using the "similar_technology" search space, which allows agents to filter for technologies of a similar type (see :ref:`inputs-agents`).
 
-Fuel
-   defines the fuel used by a technology, defined to restrict the new investments of each agent to selected technologies using selected fuels (see :ref:`inputs-agents`).
+Fuel (optional)
+   defines the fuel used by a technology. Required when using the "fueltype" search space, which allows agents to filter for technologies using the same fuel (see :ref:`inputs-agents`).
 
-EndUse
+EndUse (optional)
    defines the end use of a technology, defined to restrict the new investments of each agent to selected technologies using selected end uses (see :ref:`inputs-agents`).
 
 InterestRate

src/muse/filters.py

@@ -239,7 +239,6 @@ def same_enduse(
     search_space: xr.DataArray,
     technologies: xr.Dataset,
     *args,
-    enduse_label: str = "service",
     **kwargs,
 ) -> xr.DataArray:
     """Only allow for technologies with at least the same end-use."""