Aux readers

docs/capabilities.md

@@ -4,17 +4,18 @@ This page summarizes the Python package surface documented for the current
 release. GridDyn's C++ application and optional libraries expose additional
 features that are selected at build time.
 
-| Workflow           | Current Python support                                                                                                 |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| Load a network     | Load extension-selected input formats. See the [reader list](python-interface.md#load-and-run-a-network).              |
-| Power flow         | Run the steady-state power-flow solver and inspect bus, generator, and other object collections.                       |
-| Dynamic simulation | Initialize and advance time-domain simulation; inspect recorder samples in memory or write them to files.              |
-| Network edits      | Read and set supported model parameters, including numeric values with unit conversion.                                |
-| File output        | Write PYPOWER/MATPOWER static cases and CSV/XML power-flow result summaries through `Simulation.write_file()`.         |
-| Optimal power flow | Run continuous DC OPF for supported polynomial costs through quadratic order when built with the optimization library. |
+| Workflow           | Current Python support                                                                                          |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| Load a network     | Load extension-selected input formats. See the [reader list](python-interface.md#load-and-run-a-network).       |
+| Power flow         | Run the steady-state power-flow solver and inspect bus, generator, and other object collections.                |
+| Dynamic simulation | Initialize and advance time-domain simulation; inspect recorder samples in memory or write them to files.       |
+| Network edits      | Read and set supported model parameters, including numeric values with unit conversion.                         |
+| File output        | Write PYPOWER/MATPOWER static cases and CSV/XML power-flow result summaries through `Simulation.write_file()`.  |
+| Optimal power flow | Run DC OPF with convex quadratic and piecewise-linear generator costs when built with the optimization library. |
 
 Current Python API boundaries include no AC OPF, integer unit commitment,
-piecewise-linear cost solution, or general network-construction API. The
+or general network-construction API. Nonconvex piecewise costs need the HiGHS
+backend; cubic polynomial costs remain unsupported. The
 static case exporters omit dynamic models, controls, relays, and events.
 Unsupported export data may be reported in the warnings returned by
 `Simulation.write_file()`.

docs/python-interface.md

@@ -234,8 +234,10 @@ The result dictionary includes `success`, `status`, `message`, `solver`,
 `objective_value`, iteration count, feasibility/stationarity diagnostics, and
 whether the dispatch was applied. This entry point handles DC OPF with
 polynomial costs through quadratic order. AC OPF and integer commitment are
-outside its current scope. Piecewise-linear curves are retained and exported;
-the current OPF solvers return an unsupported status for them.
+outside its current scope. Convex piecewise-linear generator costs are also
+supported by the native DC OPF; nonconvex piecewise curves require HiGHS because
+their formulation contains binary segment selectors. A nonzero cubic cost term
+remains unsupported by this DC OPF.
 
 ## Capability notes
 

src/fileInput/fileInput.h

@@ -12,7 +12,10 @@ define some functions and operations for configuring file reader operations and
 #include "../griddyn/gridDynDefinitions.hpp"
 #include "ReaderInfo.h"
 #include <memory>
+#include <optional>
 #include <string>
+#include <unordered_map>
+#include <vector>
 
 namespace griddyn {
 class Event;
@@ -114,6 +117,44 @@ void loadAux(CoreObject* parentObject,
              const std::string& fileName,
              const BasicReaderInfo& readerOptions = defInfo);
 
+/** Named PowerWorld object whose numeric ID can be referenced by other AUX rows. */
+struct AuxNamedRecord {
+    int mNumber = 0;
+    std::string mName;
+};
+
+struct AuxSubstationRecord {
+    int mNumber = 0;
+    std::string mName;
+    std::optional<double> mLatitude;
+    std::optional<double> mLongitude;
+};
+
+/** Geographic and organizational references from an AUX Bus row. */
+struct AuxBusMetadata {
+    int mBusNumber = 0;
+    int mAreaNumber = 0;
+    int mZoneNumber = 0;
+    int mOwnerNumber = 0;
+    int mSubstationNumber = 0;
+    int mBalancingAuthorityNumber = 0;
+    std::optional<double> mLatitude;
+    std::optional<double> mLongitude;
+};
+
+/** Metadata that does not have a direct GridDyn simulation object. */
+struct AuxCaseMetadata {
+    std::unordered_map<int, AuxNamedRecord> mOwners;
+    std::unordered_map<int, AuxNamedRecord> mZones;
+    std::unordered_map<int, AuxNamedRecord> mBalancingAuthorities;
+    std::unordered_map<int, AuxSubstationRecord> mSubstations;
+    std::unordered_map<int, AuxBusMetadata> mBuses;
+    std::vector<std::string> mSuperAreas;
+};
+
+/** Read PowerWorld case hierarchy and bus assignments without changing a simulation. */
+[[nodiscard]] AuxCaseMetadata readAuxCaseMetadata(const std::string& fileName);
+
 void loadDyr(CoreObject* parentObject,
              const std::string& fileName,
              const BasicReaderInfo& readerOptions = defInfo);