[lukelowry]

Description

Adds an output_layout solver option for monitor output. With "output_layout": "long", each row of output_file holds one variable at one sample instead of one column per variable, so results load straight into SQL tables no matter how many variables are monitored.

Closes #597.

Wide output is unchanged, and printing is faster:

Format	develop	This PR
CSV	0.199 s	0.156 s
JSON	0.377 s	0.179 s
YAML	0.310 s	0.181 s

Print time only, 2000 monitors × 4 variables over 500 samples.

Proposed changes

• Add VariableMonitorLayout (WIDE, LONG) to SinkSpec, set by output_layout next to output_file in the solver file. It defaults to wide, and long is not supported with reference_file.
• Long rows are sample, t, class, id, variable, value rather than the t, id, value sketched in the issue:
  • class and id are the device's class and id from the case file, since an id alone can repeat across classes.
  • variable gets its own column, so queries can filter or group by variable without parsing names.
  • sample is needed for a unique key, since the samples just before and after an event share the same t.
• Monitors hand their variables to the controller once (appendEntries), and the controller writes every format and layout from that list. This replaces the per-format virtuals in VariableMonitorBase and the formatting code in VariableMonitor.
• The layout is a template parameter of each sink (Sink<FormatT, Layout>), resolved at compile time.
• Monitored getters must return a real value (static_assert in set()); every existing getter does.
• Remove the unused VariableMonitorController::addVariable.
• Add a DynamicSimulation/PostgreSQL example that runs an ACTIVSg2000 bus fault and loads the long output into PostgreSQL with Docker Compose or Podman.
• Mark case-file monitors for removal in a follow-up PR.

Checklist

• All tests pass.
• 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.
• The CHANGELOG.md has been updated to reflect the changes.

Further comments

@pelesh Feedback on PR length/scope

@tsybinae Thank you for the suggestion and guidance.

[tsybinae]

Hi. I am reviewing the code. It builds, runs, and produces the csv. The timestamp looks a bit odd, for instance, row 569215 looks like this

1704,7.0916666666666668e+00,Genrou,5281_1_genrou,omega,2.2408284627934353e-05

This effectively means that t = 7.09 something. Is this thing going to merge on t if I need to left join?

Thank you.

[lukelowry]

@tsybinae Thanks! Join on sample, since t repeats at events (before and after). Also, the time just has a rounding issue due to floating point precision, so joining on t is not recommended.

Let me know if you have any othr issues!

[tsybinae]

This functionality is not specific to the csv task, so the merge can go ahead. There may be more precision related questions within a few month.

[tsybinae]

Builds and runs cleanly.

[superwhiskers]

core idea seems like the right approach. just some comments on implementation of formatting that should be addressed before this goes further.

[lukelowry]

@nkoukpaizan @superwhiskers feedback greatly appreciated! the example I hope is much better. And hopfully the template parameter approach is cleaner, please LMK

[read-the-docs-community]

Documentation build overview

📚 GridKit | 🛠️ Build #35533600 | 📁 Comparing 60a7b81 against latest (c9a6497)

  🔍 Preview build  

168 files changed · + 99 added · ± 64 modified · - 5 deleted

+ Added

• api/reference/classAnalysisManager_1_1SteadyState_1_1IpoptInterface.html
• api/reference/classGridKit_1_1Model_1_1OptimizationEvaluator.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Branch.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Bus.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Component.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Generator.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Load.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1SystemModel.html
• api/reference/dir_GridKit_Model_OptimalPowerFlow.html
• api/reference/dir_GridKit_Model_OptimalPowerFlow_Branch.html
• and 89 more...

± Modified

• genindex.html
• cases/README.html
• development/CHANGELOG.html
• examples/README.html
• api/reference/classGridKit_1_1Model_1_1ParameterReader.html
• api/reference/classGridKit_1_1Model_1_1VariableMonitorBase.html
• api/reference/classGridKit_1_1Model_1_1VariableMonitorController.html
• api/reference/classGridKit_1_1PhasorDynamics_1_1Component.html
• api/reference/classGridKit_1_1PhasorDynamics_1_1Controller_1_1Reecb.html
• api/reference/classGridKit_1_1PhasorDynamics_1_1Controller_1_1Repca.html
• and 54 more...

- Deleted

• api/reference/function_namespaceGridKit_1_1Model_1_1VariableMonitorDetail_1a3739d7ddea33e27e0a5c6a24cb5a6e25.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorBase_1_1Csv.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorBase_1_1Json.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorBase_1_1Yaml.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorController_1_1Variable.html

[lukelowry]

@nkoukpaizan @superwhiskers This should be ready for final approval/review!

[superwhiskers]

if we're going to blanket reject special characters inside these, we should do it at the point of parsing them, not later on when we construct the writer.

[pelesh]

Good to merge provided comment by @superwhiskers is addressed. Reject malformed bus labels at the point of inputing the data.

[lukelowry]

Ready