Allow bi-directional freq. headband in PVD2 and ESD1

[jinningwang]

• Models PVD2 and ESD1 support bi-directional deadband for frequency regulation.
• Mention DAETimeSeries.get_data() in ex2
• Format references in docstring

[jinningwang]

Hold a sec, this model does not work as expected. I might need two more days to double check it.

[jinningwang]

After consideration, this model does not help much.

[cuihantao]

Can you elaborate?

[jinningwang]

Summary

This PR explores the need for a revised solar generation model capable of providing both up and down regulation capacity for secondary frequency regulation (SFR).

Reference:

X. Fang, H. Yuan and J. Tan, "Secondary Frequency Regulation from Variable Generation Through Uncertainty Decomposition: An Economic and Reliability Perspective," in IEEE Transactions on Sustainable Energy, vol. 12, no. 4, pp. 2019-2030, Oct. 2021, doi: 10.1109/TSTE.2021.3076758.

---

Initial Attempt (Did Not Work)

The first implementation is excerpted here for future reference. The issue lies in the redefinition of DB.upper after self.DB = DeadBand1(...) is instantiated in PVD1, which has no effect.

class PVD2(...):
    def __init__(...):
        ...
        PVD1Data.__init__(self)
        PVD1Model.__init__(self, system, config)
        self.DB.upper = "-fdbd"

---

Quick Fix (Works, But Not Optimal)

This functions as expected but is inefficient. The original DB1 is defined but never used, leading to unnecessary overhead.

class PVD2(...):
    def __init__(...):
        ...
        self.fdbdn = ConstService(v_str='-fdbd',
                                  info='-fdbd')

        self.DB2 = DeadBand1(u=self.Fdev, center=0.0, lower=self.fdbd, upper=self.fdbdn,
                             gain=self.ddn,
                             info='frequency deviation deadband with gain',
                             )  # outputs   `Pdrp`
        self.Psum.v_str = 'u * (Pext + Pref + DB2_y)'
        self.Psum.e_str = 'u * (Pext + Pref + DB2_y) - Psum'

---

Next Steps

1. Define a parameter fdbdu in PVD1, set default to be 999, and used as DB1.upper. Leave a note in doc to notify users never change it in PVD1
2. In PVD2 and derived ESD1, change the fdbdu's default value to -fdbd to allow bi-directional frequency droop response.

[jinningwang]

@cuihantao I add a clarification on example 2 to mention the use of get_data. You might need to run ex2 again on your end.