Bus Data Assignment¶

The visual app currently helps build the static grid YAML. Bus-data assignment is handled by this YAML/Python workflow. TX-123BT is one optional source-data example; see tx123bt.md.

GridForge separates static grid construction from time-series assignment.

The grid workbook decides which assets exist and which generated buses they are attached to. A bus-data assignment file then decides which source CSV profile is used for each generated bus that needs data.

This step happens after the Excel workbook has been generated. The assignment tools read the workbook to discover which generated BUS_IDX values need data. The output CSV files can contain more than asset profiles. For example, a bus CSV may also contain calendar, weather, or other contextual columns.

Assignment File¶

An assignment template has three parts:

where to find candidate source CSV files as source_data_dir,
which signals require time-series columns as signals,
optionally, where GridForge should write case-specific bus CSV files as output_data_dir.

source_data_dir: data/bus_data
output_data_dir: examples/14bus_uc/14bus_data
signals:
  load:
    workbook_sheet: load   # the data is related to the load sheet in the workbook
    source_column: load    # the column name in the source CSV file that contains the time-series data for the load
    output_column: load    # the column name in the output CSV file that contains the time-series data for the load
    scale_to:
      column: PMAX
      method: max
  solar:
    workbook_sheet: solar
    source_column: solar
    output_column: solar
    scale_to:
      column: PMAX
      method: max
  wind:
    workbook_sheet: wind
    source_column: wind
    output_column: wind
    scale_to:
      column: PMAX
      method: max

This template is not yet materializable because it does not say which generated bus should use which source file. Use suggest_bus_data_assignment(...) after the workbook exists to produce a resolved assignment with a buses mapping.

What The User Provides¶

The user controls:

source_data_dir: directory of candidate source CSV files. Each file is a time-series table with shape (T, n_features), where rows are time steps and columns are signals or context features such as load, solar, wind, weather, or calendar fields.
output_data_dir: directory where GridForge writes the case-specific bus_<BUS_IDX>.csv files.
signals: named time-series signals. Each signal states which workbook sheet supplies required BUS_IDX values, which source CSV column to read, and which output CSV column to write.
buses: optional mapping from generated GridForge BUS_IDX values to source CSV filenames. In the common workflow this is generated by suggest_bus_data_assignment(...) after the workbook exists. See suggest_bus_data_assignment(...) for more details.

How Required Buses Are Found¶

GridForge does not assume that every custom sheet needs time-series data. Only sheets referenced by signals.<name>.workbook_sheet are data-backed.

For each signal, GridForge reads BUS_IDX from the referenced workbook sheet. The union of those bus IDs becomes the set of buses that need source CSV assignments.

Scaling¶

For a signal like:

load:
  workbook_sheet: load
  source_column: load
  output_column: load
  scale_to:
    column: PMAX
    method: max

GridForge:

reads the assigned source CSV's load column,
finds the generated bus's load.PMAX value in the workbook,
scales the source profile so max(load) equals PMAX,
writes the scaled profile into the case-specific output CSV.

The current scaling method is max. This matches the peak of the source profile to a static workbook value such as peak demand or installed capacity.

More options will be supported in the future.

scale_to uses the signal's workbook_sheet by default.

Suggest A Mapping¶

The user can use suggest_bus_data_assignment(...) to generate a draft mapping. A complete example is shown below:

from gridforge.data import suggest_bus_data_assignment, save_bus_data_assignment

# Assignment config without buses mapping
signals = {
    "load": {
        "workbook_sheet": "load",
        "source_column": "load",
        "output_column": "load",
        "scale_to": {"column": "PMAX", "method": "max"},
    },
    "solar": {
        "workbook_sheet": "solar",
        "source_column": "solar",
        "output_column": "solar",
        "scale_to": {"column": "PMAX", "method": "max"},
    },
    "wind": {
        "workbook_sheet": "wind",
        "source_column": "wind",
        "output_column": "wind",
        "scale_to": {"column": "PMAX", "method": "max"},
    },
}

# GridForge will suggest a mapping for the buses that need time-series data based on the signals and the source data directory.
assignment = suggest_bus_data_assignment(
    grid_xlsx_path="examples/14bus_uc/14bus_config.xlsx",
    source_data_dir="data/bus_data",
    signals=signals,
    output_data_dir="examples/14bus_uc/14bus_data",
    random_seed=404,
)

# Save the resolved assignment if you want to inspect or reuse the generated mapping.
save_bus_data_assignment(
    assignment,
    "examples/14bus_uc/14bus_data_assignment_resolved.yaml",
)

Materialize The Assignment¶

from gridforge.data import materialize_bus_data_assignment

materialize_bus_data_assignment(
    grid_xlsx_path="examples/14bus_uc/14bus_config.xlsx",
    assignment_path="examples/14bus_uc/14bus_data_assignment_resolved.yaml",
    output_data_dir="examples/14bus_uc/14bus_data",
)

This reads the assigned source files, scales requested columns when configured, and writes files such as:

examples/14bus_uc/14bus_data/bus_2.csv
examples/14bus_uc/14bus_data/bus_3.csv
examples/14bus_uc/14bus_data/bus_8.csv

The output filenames use generated GridForge bus IDs. The source files can come from any CSV pool that contains the required columns.

Next Step¶

After materialization, load the generated bus_<BUS_IDX>.csv files with Data(...). For sheet-backed profile matrices and contextual CSV columns, see Grid And Data Access.