docs: update documentation reference for phase mapping on simulation objects

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.

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,
 )

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

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]