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

pvlib/battery.py

@@ -0,0 +1,122 @@
+"""
+This module contains functions for modeling batteries.
+
+TODO:
+
+- boc()  # Bag of coulombs
+- fit_boc_datasheet()
+- battwatts()  # Simplified battery storage model
+- fit_battwatts_datasheet()
+- sam_stateful()
+- fit_sam_stateful_datasheet()
+"""
+from pandas import DataFrame
+
+
+def power_to_energy(power):
+    '''
+    Converts a power series to an energy series.
+
+    Assuming Watts as the input power unit, the output energy unit will be
+    Watt Hours.
+
+    Parameters
+    ----------
+    power : Series
+        The input power series. [W]
+
+    Returns
+    -------
+    The converted energy Series. [Wh]
+    '''
+    if power.index.freq.name == "H":
+        return power * power.index.freq.n
+    if power.index.freq.name == "T":
+        return power * power.index.freq.n / 60
+    raise ValueError("Unsupported frequency {}".format(power.index.freq))
+
+
+def fit_sam_datasheet(datasheet):
+    '''
+    Determine the SAM BatteryStateful model mathing the given characteristics.
+
+    Parameters
+    ----------
+    datasheet : dict_like
+        The datasheet parameters of the battery.
+
+    Returns
+    -------
+    object
+        The SAM BatteryStateful object.
+
+    Notes
+    -----
+    This function does not really perform a fitting procedure. Instead, it just
+    calculates the model parameters that match the provided informatio from a
+    datasheet.
+    '''
+    try:
+        from PySAM.BatteryStateful import default
+        from PySAM.BatteryTools import battery_model_sizing
+    except ImportError:
+        raise ImportError("Requires NREL's PySAM package at "
+                          "https://pypi.org/project/NREL-PySAM/.")
+    datasheet = {
+        "brand": "BYD",
+        "model": "HVS 5.1",
+        "width": 0.585,
+        "height": 0.712,
+        "depth": 0.298,
+        "weight": 91,
+        "chemistry": "LFP",
+        "modules": 2,
+        "energy_wh": 5120,
+        "voltage": 204,
+        "max_power_w": 5100,
+    }
+    # TODO: validate/normalize datasheet
+    chemistry = {
+        "LFP": "LFPGraphite",
+    }
+    model = default(chemistry[datasheet["chemistry"]])
+    battery_model_sizing(
+        model=model,
+        desired_power=datasheet["max_power_w"] / 1000,
+        desired_capacity=datasheet["energy_wh"] / 1000,
+        desired_voltage=datasheet["voltage"],
+    )
+    model.ParamsCell.minimum_SOC = 10
+    model.ParamsCell.maximum_SOC = 90
+    model.ParamsCell.initial_SOC = 50
+    return model.export()
+
+
+def sam(model, power):
+    '''
+    '''
+    try:
+        from PySAM.BatteryStateful import new
+    except ImportError:
+        raise ImportError("Requires NREL's PySAM package at "
+                          "https://pypi.org/project/NREL-PySAM/.")
+    battery = new()
+    battery.assign(model)
+    if power.index.freq.name == "H":
+        battery.Controls.dt_hr = power.index.freq.n
+    elif power.index.freq.name == "T":
+        battery.Controls.dt_hr = power.index.freq.n / 60
+    battery.Controls.control_mode = 1
+    battery.Controls.input_power = 0
+    battery.setup()
+
+    states = []
+    for p in power:
+        battery.Controls.input_power = p
+        battery.execute(0)
+        states.append((battery.StatePack.P, battery.StatePack.SOC))
+
+    results = DataFrame(states, index=power.index, columns=["Power", "SOC"])
+    export = battery.export()
+
+    return (export, results * 1000)

pvlib/tests/test_battery.py

@@ -0,0 +1,46 @@
+from pandas import Series
+from pandas import date_range
+from pytest import approx
+from pytest import mark
+from pytest import raises
+
+from pvlib.battery import power_to_energy
+
+@mark.parametrize("power_value,frequency,energy_value", [
+    (1000, "H", 1000),
+    (1000, "2H", 2000),
+    (1000, "15T", 250),
+    (1000, "60T", 1000),
+])
+def test_power_to_energy(power_value, frequency, energy_value):
+    '''
+    The function should be able to convert power to energy for different power
+    series' frequencies.
+    '''
+    index = date_range(
+        start="2022-01-01",
+        periods=10,
+        freq=frequency,
+        tz="Europe/Madrid",
+        closed="left",
+    )
+    power = Series(power_value, index=index)
+    energy = power_to_energy(power)
+    assert approx(energy) == energy_value
+
+
+def test_power_to_energy_unsupported_frequency():
+    '''
+    When the power series' frequency is unsupported, the function raises an
+    exception.
+    '''
+    index = date_range(
+        start="2022-01-01",
+        periods=10,
+        freq="1M",
+        tz="Europe/Madrid",
+        closed="left",
+    )
+    power = Series(1000, index=index)
+    with raises(ValueError, match=r"Unsupported frequency") as error:
+        power_to_energy(power)