Documentation for phase shift transformer (PST)

[scud-soptim]

Fixes #1484

Changes proposed in this PR include

• added documentation how to use a pst by using a generic branch
  For discussion see: Phase shifter transformer #188

Could you please pay extra attention to the points below when reviewing the PR

For discussion see: #188

[mgovers]

Hi @scud-soptim,

Thanks again for the PR. I see, however, that this PR has some duplication with #1485 by another external (first time) contributor.

Both PRs contain useful information. Would it be alright with you to rebase this PR off that PR (or merging it into this one) and combine the two?

In particular, we now have non-pgm-components.md which is intended to contain documentation on any grid components that are not natively supported by PGM (or at least not in name) but can be modeled with PGM components. I think it makes sense to move this documentation there, as per #1485 .

[nitbharambe]

nitpicks:

Suggested change

	| `PhaseTapChangerLinear` | $\alpha = m \cdot \delta$ (`stepPhaseShiftIncrement`) | constant |
	| `PhaseTapChangerLinear` | $\alpha = m \cdot \delta$ \theta_{\text{step}} | constant (k_{\text{off-nominal}}) |

By constant, it would then be equal to off nominal tap and right?
Also can you add stepPhaseShiftIncrement = theta_step above for consistency.

[Welthulk]

Thanks @nitbharambe — to answer the question itself: yes, your reading is
correct. For PhaseTapChangerLinear only the angle scales with the tap step;
the magnitude ratio stays fixed at the configured off-nominal ratio, i.e. the
same k as in the generic_branch model (N = k · e^{jθ}), independent of tap
position. That is exactly what distinguishes it from PhaseTapChangerAsymmetrical.

Your naming suggestion makes sense. As I noted above, with the content now
living in non-pgm-components.md via #1485 I don't see much left for this PR
to add, so please go ahead and apply the rename directly there — I'll leave it
in your hands. Two things to watch when you do: \theta_{\text{step}} and
k_{\text{off-nominal}} need their $ delimiters to render, and
stepPhaseShiftIncrement = θ_step should go into the symbol legend above the
table.

[nitbharambe]

Thanks for sharing this. It's a useful addition for users. And it's good that we can link directly to the ENTSO-E modelling guidelines as a reference.
If you come across similar guidelines for other components, feel free to open an issue for it. This kind of standards-referenced documentation seems like some of the most impactful work we can do for the project.

[scud-soptim]

Thanks @mgovers and @nitbharambe for the thorough review! I appreciate the feedback. I put together this documentation in response to the request in #1484 and the discussion in #188. However, I don't have the capacity right now to handle rebasing or coordinating with #1485. I'm confident you'll make the best decision about how to integrate the two PRs and which documentation structure serves the project best. Please feel free to make any adjustments you think are appropriate. Thanks for your understanding!