============================
Price Elasticity Module
============================

By default, the load parts are firm. Meaning that they represent a constant demand that is independent of price. 
The price elasticity module allows us to model the :class:`loads <trident.domain.LoadPart>` as price elastic loads.

A price elastic load has a nominal value and a demand function, :math:`W(\pi)`, which gives the proportion of the nominal value that is the actual demand. Here :math:`\pi` is the energy price. 

The exponential demand function is given by 

.. math::
   W(\pi) = \Bigr( \frac{\pi} {\pi_{n}} \Bigr)^{e},

where :math:`\pi_n` is the nominal price, at which the demand is equal to the nominal value, and :math:`e` is a negative exponent. 
It is illustrated in the figure below. Note the upper and lower price variables :math:`\overline{\pi}` and :math:`\underline{\pi}`.

.. figure:: resources/exponential_price_elasticity.svg
   :align: center

   Exponential demand function.

The linear demand function is given as a piece-wise linear curve, consisting of pairs of price and demand. This is illustrated in the figure below, 
where :math:`W(\pi)` is created from three input pairs. 

.. figure:: resources/linear_price_elasticity.svg
   :align: center

   Linear demand function.

**Example:**
The nominal load is 100 GW, the energy price is 10 mu/GWh and :math:`W(10) = 0.7`. This gives the actual demand :math:`100 \textrm{ GW} * 0.7 = 70 \textrm{ GWh}`.

See the :ref:`model documentation <model_doc_price_elasticity>` for more mathematical details on how the price elasticity is modeled,

----------------------------
Usage
----------------------------
In addition to setting the nominal load value using the firm_load time series, either the property :attr:`~trident.domain.LoadPart.exponential_price_elasticity` or :attr:`~trident.domain.LoadPart.piecewise_linear_price_elasticity` must be set using
:meth:`~trident.domain.LogicalModelView.set_exponential_price_elasticity` or :meth:`~trident.domain.LogicalModelView.set_piecewise_linear_price_elasticity`. 

See the :ref:`Python Module API <modulepriceelasticity>` for descriptions of the input time series and configuration parameters. 

It is also possible to set a dynamic response to changes in the demand. This is similar to the similar :ref:`dynamic capacity feature <thermal_module_guide_dynamic_capacity>` in the thermal module. Setting the response to :attr:`~trident.domain.DynamicResponseType.ASYMPTOTIC` or :attr:`~trident.domain.DynamicResponseType.LINEAR` models that changes in the demand do not happen instantly.

----------------------------
Example
----------------------------
An example of how to set up and use the price elasticity module can be found in the :ref:`example notebooks <example_notebooks>`.