GENSAL Machine Model + Doc Cleanup for Machines

[lukelowry]

Description

Implementation and documentation for the GENSAL model.

Proposed changes

• Saturation model adjustments
• GENSAL Documentation
• GENSAL Implementation
• GENSAL Validation against reference solution
• GENSAL Tests
• Added GENSAL unit tests and a PowerWorld validation example.
• Improved synchronous machine base handling and documentation for system base vs machine MVA base behavior.
• Updated GENROU and GenClassical docs/tests for consistency with the shared machine-base conventions.

Checklist

• All tests pass (except for one known error in PowerElectronics)
• Code compiles cleanly with flags -Wall -Wpedantic -Wconversion -Wextra.
• The new code follows GridKit™ style guidelines.
• There are unit tests for the new code.
• The new code is documented.
• The feature branch is rebased with respect to the target branch.
• I have updated CHANGELOG.md to reflect the changes in this PR. If this is a minor PR that is part of a larger fix already included in the file, state so.

Further comments

Some consistency improvements with GENROU and GenClassical documentation align with the implementation. GenClassical needs a pretty heavy polish. These were some of the first models, so I am not surprised. The GenClassical does not wire up the exciter and governor correctly, and the port names are not consistent with the genrou.

This work includes validation of GENSAL, which I used to collect data for plots of the machine models for the upcoming conference paper.

[abirchfield]

This is good to do. It would be better if there were a 2-bus case matching PowerWorld to make sure it's right.

[lukelowry]

This is good to do. It would be better if there were a 2-bus case matching PowerWorld to make sure it's right.

I will add that to this PR because I agree here

[nkoukpaizan]

Looks good to me! Just a couple of structural comments.

I'll defer approval for the domain-specific aspects.

[nkoukpaizan]

I like the idea of including .png files for validation. I would link to them in a documentation file (e.g. README.md), so they render by default when viewing the folder online.

Is the plan to add these for most of the examples we have? If so, please create a GH issue to track. Only having them for once case may lead to some confusion.

This also has implications for placing this example in examples/PhasorDynamics/Validation versus. examples/PhasorDynamics/Tiny/TwoBus.

[lukelowry]

There was no plan to do so, but I agree it's helpful to visualize and good practice to keep a .png just for human intuition to catch any glaring issues that would otherwise go unnoticed.

The validation of a single model like GENSAL will look different from the validation of a case (i.e. Texas).

Preference on where the Component model validation should live? I agree the case validations should go in the respective example (as a subfolder). Is the examples/PhasorDynamics/Validation okay for individual model verification?

[nkoukpaizan]

In that case, I recommend putting the case in examples/PhasorDynamics/Tiny/TwoBus for now.

We can discuss documenting validations separately. Feel free to create an issue to track that.