From 7c7d5346190a9b2e16f76d6adb68d3a75714c5c2 Mon Sep 17 00:00:00 2001 From: mvelasqu Date: Thu, 27 Aug 2026 12:23:59 -0600 Subject: [PATCH] docs: update documentation reference for phase mapping on simulation objects --- docs/source/howtos/add_reports.md | 10 +++++----- docs/source/tutorial.md | 2 +- src/plexosdb/db.py | 3 ++- tests/test_plexosdb_reports.py | 26 ++++++++++++++++++++++++++ 4 files changed, 34 insertions(+), 7 deletions(-) diff --git a/docs/source/howtos/add_reports.md b/docs/source/howtos/add_reports.md index 4133b6fa..41592feb 100644 --- a/docs/source/howtos/add_reports.md +++ b/docs/source/howtos/add_reports.md @@ -27,7 +27,7 @@ db.add_report( collection=CollectionEnum.Generators, # Collection containing the property parent_class=ClassEnum.System, # Parent class for the collection child_class=ClassEnum.Generator, # Child class for the collection - phase_id=4, # Phase ID (4=LT, Long Term) + phase_id=4, # Phase ID (4=ST Schedule) report_period=True, # Include period data report_summary=True, # Include summary data report_statistics=False, # Don't include statistics @@ -93,9 +93,9 @@ for prop in ["Generation", "Available Capacity"]: The `phase_id` parameter specifies which simulation phase to create the report for: -- `1`: ST (Short Term) -- `2`: MT (Medium Term) -- `3`: PASA (Projected Assessment of System Adequacy) -- `4`: LT (Long Term) +- `1`: LT Plan (Long Term) +- `2`: PASA (Projected Assessment of System Adequacy) +- `3`: MT Schedule (Medium Term) +- `4`: ST Schedule (Short Term) Choose the appropriate phase for your simulation needs. diff --git a/docs/source/tutorial.md b/docs/source/tutorial.md index 511ab3b8..116b96a1 100644 --- a/docs/source/tutorial.md +++ b/docs/source/tutorial.md @@ -435,7 +435,7 @@ db.add_report( collection=CollectionEnum.Generators, parent_class=ClassEnum.System, child_class=ClassEnum.Generator, - phase_id=4, # Long-term phase + phase_id=4, # ST Schedule phase report_period=True, report_summary=True, ) diff --git a/src/plexosdb/db.py b/src/plexosdb/db.py index 5013a49b..3e302fab 100644 --- a/src/plexosdb/db.py +++ b/src/plexosdb/db.py @@ -1396,7 +1396,8 @@ def add_report( child_class : ClassEnum Child class enumeration for the collection phase_id : int, optional - Phase ID for the report (1=ST, 2=MT, 3=PASA, 4=LT), by default 4 (Long Term) + Phase ID for the report (1=LT Plan, 2=PASA, 3=MT Schedule, 4=ST Schedule), + by default 4 (ST Schedule) report_period : bool | None, optional Whether to report period data, by default None report_summary : bool | None, optional diff --git a/tests/test_plexosdb_reports.py b/tests/test_plexosdb_reports.py index d55e518e..0d346594 100644 --- a/tests/test_plexosdb_reports.py +++ b/tests/test_plexosdb_reports.py @@ -83,3 +83,29 @@ def test_add_report_property_to_existing_report(db_base: PlexosDB): ) assert [row[0] for row in configured_properties] == sorted((first_property, second_property)) + + +def test_add_report_preserves_phase_ids(db_base: PlexosDB): + from plexosdb import ClassEnum, CollectionEnum + + db: PlexosDB = db_base + report_object = "phase_report" + db.add_object(ClassEnum.Report, name=report_object) + + for phase_id in (1, 2, 3, 4): + db.add_report( + object_name=report_object, + property="Units", + collection=CollectionEnum.Generators, + parent_class=ClassEnum.System, + child_class=ClassEnum.Generator, + phase_id=phase_id, + ) + + report_id = db.get_object_id(ClassEnum.Report, name=report_object) + configured_phase_ids = db.query( + "SELECT phase_id FROM t_report WHERE object_id = ? ORDER BY phase_id", + (report_id,), + ) + + assert [row[0] for row in configured_phase_ids] == [1, 2, 3, 4]