Implement initial storage support (pvlib#1333)

Author: Peque

docs/sphinx/source/user_guide/index.rst

@@ -14,6 +14,7 @@ User Guide
    timetimezones
    clearsky
    forecasts
+   storage
    comparison_pvlib_matlab
    variables_style_rules
    singlediode

docs/sphinx/source/user_guide/storage.rst

@@ -0,0 +1,131 @@
+.. _storage:
+
+Storage
+=======
+
+Storage is a way of transforming energy that is available at a given instant,
+for use at a later time. The way in which this energy is stored can vary
+depending on the storage technology. It can be potential energy, heat or
+chemical, among others. Storage is literally everywhere, in small electronic
+devices like mobile phones or laptops, to electric vehicles, to huge dams.
+
+While humanity shifts from fossil fuels to renewable energy, it faces the
+challenges of integrating more energy sources that are not always stable nor
+predictable. The energy transition requires not only to replace current
+electricity generation plants to be renewable, but also to replace heating
+systems and combustion engines in the whole transportation sector to be
+electric.
+
+Unfortunately, electrical energy cannot easily be stored so, if electricity is
+becoming the main way of generating and consuming energy, energy storage
+systems need to be capable of storing the excess electrical energy that is
+produced when the generation is higher than the demand. Storage sysems need to
+be:
+
+- Efficient: in the round-trip conversion from electrical to other type of
+  energy, and back to electrical again.
+
+- Capable: to store large quantities of energy.
+
+- Durable: to last longer.
+
+There are many specific use cases in which storage can be beneficial. In all of
+them the underlying effect is the same: to make the grid more stable and
+predictable.
+
+Some use cases are not necessarily always coupled with PV. For instance, with
+power peak shaving, storage can be fed from the grid without a renewable energy
+source directly connected to the system. Other use cases, however, are tightly
+coupled with PV and hence, are of high interest for this project.
+
+Power versus energy
+-------------------
+
+Module and inverter models in pvlib compute the power generation (DC and AC
+respectively). This means the computation happens as an instant, without taking
+into account the previous state nor the duration of the calculated power. It
+is, in general, the way most models work in pvlib, with the exception of some
+cell temperature models. It also means that time, or timestamps associated to
+the power values, are not taken into consideration for the calculations.
+
+When dealing with storage systems, state plays a fundamental role. Degradation
+and parameters like the state of charge (SOC) greatly affect how the systems
+operates. This means that power computation is not sufficient. Energy is what
+really matters and, in order to compute energy, time needs to be well defined.
+
+Conventions
+***********
+
+In order to work with time series pvlib relies on pandas and pytz to handle
+time and time zones. See "Time and time zones" section for a brief
+introduction.
+
+Also, when dealing with storage systems and energy flow, you need to take into
+account the following conventions:
+
+- Timestamps are associated to the beginning of the interval
+
+- The time series frequency needs to be well defined in the time series
+
+- Values represent power throughout the interval, in W
+
+- Positive values represent power provided by the storage system (i.e.:
+  discharging), hence negative values represent power into the storage system
+  (i.e.: charging) NOTE: should we use values representing the energy instead?
+  sounds more intuitive to me but if NREL chose to use power instead there may
+  be a good reason
+
+The left-labelling of the bins can be in conflict with energy meter series data
+provided by the electricity retailer companies, where the timestamp represents
+the time of the reading (the end of the interval). However, using labels at the
+beginning of the interval eases typical group operations with time series like
+resampling, where Pandas will assume by default that the label is at the
+beginning of the interval.
+
+As an example, here you can see 15-minutes-period time series representing 1000
+W power throughout all the periods:
+
+.. ipython:: python
+
+    from pandas import date_range
+    from pandas import Series
+
+    index = date_range(
+        "2022-01",
+        "2022-02",
+        closed="left",
+        freq="15T",
+        tz="Europe/Madrid",
+    )
+    power = Series(1000.0, index=index)
+    power[0:2]
+
+Energy series
+*************
+
+You can convert the power series into energy series very easily:
+
+.. ipython:: python
+
+    from pvlib.battery import power_to_energy
+
+    energy = power_to_energy(power)
+    energy[0:2]
+
+And just as easily, you can resample the energy series to use a different
+period thanks to Pandas built-in methods:
+
+.. ipython:: python
+
+   daily = energy.resample("D").sum()
+   daily[0:2]
+
+Batteries
+---------
+
+TODO
+
+Energy flow
+-----------
+
+TODO