Improved documentation

Author: tsmbland

docs/inputs/toml.rst

@@ -90,8 +90,8 @@ a whole.
 Carbon market
 -------------
 
-This section contains the settings related to the modelling of the carbon market. If omitted, it defaults to not
-including the carbon market in the simulation.
+This section contains the settings related to the modelling of the carbon market.
+If omitted, it defaults to not including the carbon market in the simulation.
 
 Example
 
@@ -106,46 +106,49 @@ Example
    `time_framework` from the main section. If not given or an empty list, then the
    carbon market feature is disabled. Defaults to an empty list.
 
-*method*
-   Method used to equilibrate the carbon market. Available options are `fitting` and `bisection`, however this can be expanded with the `@register_carbon_budget_method` hook in `muse.carbon_budget`.
-
-   The market-clearing algorithm iterates over the sectors until the market reaches an equilibrium in the foresight period (the period next to the one analysed).
-   This is represented by a stable variation of a commodity demand (or price) between iterations below a defined tolerance.
-   The market-clearing algorithm samples a user-defined set of carbon prices.
-
-   When the `fitting` method is selected, this command builds a regression model of the emissions as a function of the carbon price.
-   It applies to a pool of emissions for all the modelled regions. Therefore, the estimated carbon price applies to all the modelled regions.
-   The regression model, the method calculates iteratively the emissions at pre-defined carbon price sample values.
-   The emissions-carbon price couples are used to used to fit the emission-carbon price relation, is uer-defined (ie. linear or exponential fitter).
-   The new carbon price is estimated as a root of the regression model estimated at the value of the emission equal to the user-defined emission cap in the foresight period.
-   Alongside the selection of the method, the user can define a `sample_size`, representing the magnitude of the sample for the fitter.
-
-   When the `bisection` method is selected, this command applies a bisection method to solve the carbon market.
-   Similarly to the `fitting` method, the carbon market includes a pool of all the modelled regions. The obtained carbon price
-   applies to all the regions, as above. This method solves as a typical bisection algorithm.
-   It is coded independently to use the internal signature of the `register_carbon_budget_method`. The algorithm aims to find a root of
-   the function emissions-carbon price, as for the carbon price at which the carbon budget is met.
-   The algorithm iteratively modifies the carbon price and estimates the corresponding emissions.
-   It stops when the convergence or stop criteria are met.
-   This happens for example either when the carbon budget or the maximum number of iterations are met.
-   Alongside the selection of the method, the user can define a `sample_size`, representing the number of iterations of the bisection method.
-
 *commodities*
    Commodities that make up the carbon market. Defaults to an empty list.
 
 *control_undershoot*
-   Whether to control carbon budget undershoots. This parameter allows for carbon tax credit from one year to be passed to the next in the case of less carbon being emitted than the budget. Defaults to True.
+   Whether to control carbon budget undershoots. This parameter allows for carbon tax credit from one year to be passed to the next in the case of less carbon being emitted than the budget. Defaults to False.
 
 *control_overshoot*
-   Whether to control carbon budget overshoots. If the amount of carbon emitted is above the carbon budget, this parameter specifies whether this deficit is carried over to the next year. Defaults to True.
+   Whether to control carbon budget overshoots. If the amount of carbon emitted is above the carbon budget, this parameter specifies whether this deficit is carried over to the next year. Defaults to False.
+
+*method*
+   Method used to equilibrate the carbon market. Available options are `fitting` and `bisection`, however this can be expanded with the `@register_carbon_budget_method` hook in `muse.carbon_budget`.
+
+   These methods solve the market with a number of different carbon prices, aiming to find the carbon price at which emissions (pooled across all regions) are equal to the carbon budget.
+   The obtained carbon price applies to all regions.
+
+   The `fitting` method samples a number of different carbon prices to build a regression model (linear or exponential) of emissions as a function of carbon price.
+   This regression model is then used to estimate the carbon price at which the carbon budget is met.
+
+   The `bisection` method uses an iterative approach to settle on a carbon price.
+   Starting with a lower and upper-bound carbon price, it iteratively halves this price interval until the carbon budget is met to within a user-defined tolerance, or until the maximum number of iterations is reached.
+   Generally, this method is more robust for markets with a complex, nonlinear relationship between emissions and carbon price, but may be slower to converge than the `fitting` method.
+
+   Defaults to `bisection`.
 
 *method_options*
-   Additional options for the specific carbon method. In particular, the `refine_price` activate a sanity check on the adjusted carbon price.
-   The sanity check applies an upper limit on the carbon price obtained from the algorithm (either `fitting` or `bisection`), called
-   `price_too_high_threshold`, a user-defined threshold based on heuristics on the values of the carbon price, reflecting typical historical trends.
+   Additional options for the specified carbon method.
+
+   Parameters for the `bisection` method:
+
+   - `max_iterations`: maximum number of iterations. Defaults to 5
+   - `tolerance`: tolerance for convergence. E.g. 0.1 means that the algorithm will terminate when emissions are within 10% of the carbon budget. Defaults to 0.1.
+   - `early_termination_count`: number of iterations with no change in the carbon price before the algorithm will terminate. Defaults to 5.
+
+   Parameters for the `fitting` method:
+
+   - `fitter`: the regression model used to approximate model emissions. Predefined options are `linear` (default) and `exponential`. Further options can be defined using the `@register_carbon_budget_fitter` hook in `muse.carbon_budget`.
+   - `sample_size`: number of price samples used. Defaults to 5.
+
+   Shared parameters:
+
+   - `refine_price`: If True, applies an upper limit on the carbon price. Defaults to False.
+   - `price_too_high_threshold`: upper limit on the carbon price. Defaults to 5.
 
-*fitter*
-   `fitter` specifies the regression model fit. The regression approximates the model emissions. Predefined options are `linear` and `exponential`. Further options can be defined using the `@register_carbon_budget_fitter` hook in `muse.carbon_budget`.
 
 ------------------
 Global input files

src/muse/carbon_budget.py

@@ -73,9 +73,9 @@ def fitting(
     equilibrium: Callable[[xr.Dataset], FindEquilibriumResults],
     carbon_budget: xr.DataArray,
     commodities: list,
-    sample_size: int = 5,
     refine_price: bool = False,
     price_too_high_threshold: float = 10,
+    sample_size: int = 5,
     fitter: str = "linear",
 ) -> float:
     """Used to solve the carbon market.
@@ -90,10 +90,10 @@ def fitting(
         equilibrium: Method for searching market equilibrium
         carbon_budget: limit on emissions
         commodities: list of commodities to limit (ie. emissions)
-        sample_size: sample size for fitting
         refine_price: Boolean to decide on whether carbon price should be capped, with
             the upper bound given by price_too_high_threshold
         price_too_high_threshold: threshold on carbon price
+        sample_size: sample size for fitting
         fitter: method to fit emissions with carbon price
 
     Returns:
@@ -292,9 +292,9 @@ def bisection(
     equilibrium: Callable[[xr.Dataset], FindEquilibriumResults],
     carbon_budget: xr.DataArray,
     commodities: list,
-    sample_size: int = 5,
     refine_price: bool = False,
     price_too_high_threshold: float = 10,
+    max_iterations: int = 5,
     tolerance: float = 0.1,
     early_termination_count: int = 5,
 ) -> float:
@@ -312,10 +312,10 @@ def bisection(
         equilibrium: Method for searching market equilibrium
         carbon_budget: DataArray with the carbon budget
         commodities: List of carbon-related commodities
-        sample_size: Maximum number of iterations for bisection
         refine_price: Boolean to decide on whether carbon price should be capped, with
             the upper bound given by price_too_high_threshold
         price_too_high_threshold: Upper limit for carbon price
+        max_iterations: Maximum number of iterations for bisection
         tolerance: Maximum permitted deviation of emissions from the budget
         early_termination_count: Will terminate the loop early if the last n solutions
             are the same
@@ -340,7 +340,7 @@ def bisection(
 
     # Bisection loop
     emissions_cache = EmissionsCache(market, equilibrium, commodities)
-    for _ in range(sample_size):  # maximum number of iterations before terminating
+    for _ in range(max_iterations):  # maximum number of iterations before terminating
         # Cap prices between 0.01 and price_too_high_threshold
         if refine_price:
             ub_price = min(ub_price, price_too_high_threshold)

src/muse/data/default_settings.toml

@@ -19,8 +19,6 @@ excluded_commodities = []
 # Carbon budget control
 [carbon_budget_control]
 budget = []  # Same length as time_framework
-commodities = []
-method = 'bisection'
 
 # Custom modules
 # Rather than a section, it can also be a list, e.g.:

src/muse/mca.py

@@ -100,8 +100,8 @@ def factory(cls, settings: str | Path | Mapping | Any) -> MCA:
             for k, v in settings.carbon_budget_control._asdict().items()
         }
         for key in {"budget", "commodities", "method"}:
-            carbon_kw[f"carbon_{key}"] = carbon_kw[key]
-            carbon_kw.pop(key)
+            if key in carbon_kw:
+                carbon_kw[f"carbon_{key}"] = carbon_kw.pop(key)
         return cls(
             sectors=sectors,
             market=market,
@@ -128,9 +128,9 @@ def __init__(
         carbon_price: Sequence | None = None,
         carbon_commodities: Sequence[str] | None = None,
         debug: bool = False,
-        control_undershoot: bool = True,
-        control_overshoot: bool = True,
-        carbon_method: str = "fitting",
+        control_undershoot: bool = False,
+        control_overshoot: bool = False,
+        carbon_method: str = "bisection",
         method_options: Mapping | None = None,
     ):
         """Market clearing algorithm class which rules the whole MUSE."""
@@ -242,14 +242,14 @@ def update_carbon_budget(self, market: Dataset, year_idx: int) -> float:
             self.control_undershoot,
         )
 
-    def update_carbon_price(self, market) -> float | None:
+    def update_carbon_price(self, market) -> float:
         """Calculates the updated carbon price.
 
         Arguments:
             market: Market with the prices, supply, consumption and demand.
 
         Returns:
-            The new carbon price. If None, the price is not updated.
+            The new carbon price.
         """
         new_carbon_price = self.carbon_method(  # type: ignore
             market,
@@ -301,18 +301,14 @@ def run(self) -> None:
             # If we need to account for the carbon budget, we do it now.
             if check_carbon_budget:
                 new_price = self.update_carbon_price(new_market)
-                if new_price is not None:
-                    future_price = DataArray(new_price, coords=dict(year=years[1]))
-
-                    new_market.prices.loc[dict(commodity=self.carbon_commodities)] = (
-                        future_propagation(
-                            new_market.prices.sel(commodity=self.carbon_commodities),
-                            future_price,
-                        )
-                    )
-                    self.carbon_price = future_propagation(
-                        self.carbon_price, future_price
+                future_price = DataArray(new_price, coords=dict(year=years[1]))
+                new_market.prices.loc[dict(commodity=self.carbon_commodities)] = (
+                    future_propagation(
+                        new_market.prices.sel(commodity=self.carbon_commodities),
+                        future_price,
                     )
+                )
+                self.carbon_price = future_propagation(self.carbon_price, future_price)
 
             _, new_market, self.sectors = self.find_equilibrium(new_market)