Add a simple transformer effficiency model to pvlib

docs/sphinx/source/reference/index.rst

@@ -20,3 +20,4 @@ API reference
    bifacial
    scaling
    location
+   transformer

docs/sphinx/source/reference/transformer.rst

@@ -0,0 +1,11 @@
+.. currentmodule:: pvlib
+
+Transformer losses
+==================
+
+Methods to account for losses in transformers
+
+.. autosummary::
+   :toctree: generated/
+
+   transformer.simple_efficiency

docs/sphinx/source/whatsnew/v0.11.0.rst

@@ -15,7 +15,9 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-
+* Add a simple transformer efficiency model :py:func:`pvlib.transformer.simple_efficiency`
+  (:issue:`1269`, :pull:`2053`)
+
 
 Bug fixes
 ~~~~~~~~~
@@ -36,3 +38,4 @@ Requirements
 Contributors
 ~~~~~~~~~~~~
 * Cliff Hansen (:ghuser:`cwhanse`)
+* Kurt Rhee (:ghuser:`kurt-rhee`)

pvlib/tests/test_transformer.py

@@ -0,0 +1,40 @@
+import pandas as pd
+
+from numpy.testing import assert_allclose
+
+from pvlib import transformer
+
+
+def test_simple_efficiency():
+
+    # define test inputs
+    input_power = pd.Series([
+        -800.0,
+        436016.609823837,
+        1511820.16603752,
+        1580687.44677249,
+        1616441.79660171
+    ])
+    no_load_loss = 0.002
+    load_loss = 0.007
+    transformer_rating = 2750000
+
+    # define expected test results
+    expected_output_power = pd.Series([
+        -6300.10103234071,
+        430045.854892526,
+        1500588.39919874,
+        1568921.77089526,
+        1604389.62839879
+    ])
+
+    # run test function with test inputs
+    calculated_output_power = transformer.simple_efficiency(
+        input_power=input_power,
+        no_load_loss=no_load_loss,
+        load_loss=load_loss,
+        transformer_rating=transformer_rating
+    )
+
+    # determine if expected results are obtained
+    assert_allclose(calculated_output_power, expected_output_power)

pvlib/transformer.py

@@ -0,0 +1,126 @@
+"""
+This module contains functions for transformer modeling.
+
+Transformer models calculate AC power output and losses at a given input power.
+"""
+
+import numpy as np
+
+
+def simple_efficiency(
+        input_power, no_load_loss, load_loss, transformer_rating
+):
+    r'''
+    Calculate the energy at the output terminal of the transformer
+    after taking into account efficiency using a simple calculation.
+
+    The equation used in this function can be derived from [1]_.
+
+
+    Parameters
+    ----------
+    input_power : numeric
+        The real power input to the transformer. [W]
+
+    no_load_loss : numeric
+        The constant losses experienced by a transformer, even
+        when the transformer is not under load. Fraction of transformer rating,
+        value from 0 to 1. [unitless]
+
+    load_loss:  numeric
+        The load dependent losses experienced by the transformer.
+        Fraction of transformer rating, value from 0 to 1. [unitless]
+
+    transformer_rating: numeric
+        The nominal output power of the transformer. [VA]
+
+    Returns
+    -------
+    output_power : numeric
+        Real power output. [W]
+
+    Notes
+    -------
+    First, assume that the load loss is proportional to the square of output
+    power.
+
+    .. math::
+
+       L_{load}(P_{out}) &= L_{load}(P_{rated}) \times P^2_{out}
+
+       L_{load}(P_{out}) &= L_{full, load} \times P^2_{out}
+
+    Total loss is the variable load loss, plus a constant no-load loss:
+
+    .. math::
+
+       L_{total}(P_{out}) &= L_{no, load} + L_{load}(P_{out})
+
+       L_{total}(P_{out}) &= L_{no, load} + L_{full, load} \times P^2_{out}
+
+
+    Conservation of energy:
+
+    .. math::
+
+       P_{in} &= P_{out} + L_{total}(P_{out})
+
+       P_{in} &= P_{out} + L_{no, load} + L_{full, load} \times P^2_{out}
+
+    Now use quadratic formula to solve for :math:`P_{out}` as a function of
+    :math:`P_{in}`.
+
+    .. math::
+
+       P_{out} &= \frac{-b +- \sqrt{b^2 - 4ac}}{2a}
+
+       a &= L_{full, load}
+
+       b &= 1
+
+       c &= L_{no, load} - P_{in}
+
+    Therefore:
+
+    .. math::
+
+       P_{out} = \frac{-1 \pm \sqrt{1 - 4 L_{full, load}
+
+       \times L_{no, load} - P_{in}}}{2 L_{full, load}}
+
+    Note that the positive root must be the correct one if the output power is
+    positive.
+
+
+    References
+    ----------
+    .. [1] Central Station Engineers of the Westinghouse Electric Corporation,
+       "Electrical Transmission and Distribution Reference Book" 4th Edition.
+       pg. 101.
+
+    '''
+
+    # calculate the load loss in terms of VA instead of percent
+    loss_at_full_load = (
+        (no_load_loss + load_loss) * transformer_rating
+    )
+    no_load_loss = no_load_loss * transformer_rating
+    load_loss = loss_at_full_load - no_load_loss
+
+    # calculate how much power is lost
+    combined_loss = (
+        (1 / (2 * load_loss)) *
+        (
+            (transformer_rating ** 2) +
+            (2 * load_loss * input_power) -
+            (transformer_rating * np.sqrt(
+                (transformer_rating ** 2) +
+                (4 * load_loss) * (input_power - no_load_loss)
+            ))
+        )
+    )
+
+    # calculate final output power given calculated losses
+    output_power = input_power - combined_loss
+
+    return output_power