Skip to content

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 contains the signal definitions that describe which time-series columns each workbook sheet requires. Source and output directories are runtime paths passed to prepare_bus_data(...), so they do not need to be duplicated in the template.

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 contain runtime directories or say which generated bus should use which source file. Use prepare_bus_data(...) after the workbook exists to produce a self-contained resolved assignment and materialize the case-specific bus CSVs.

What The User Provides

The user controls:

  • source_data_dir argument: 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 argument: directory where GridForge writes the case-specific bus_<BUS_IDX>.csv files.
  • signals template: 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 resolved mapping: generated by prepare_bus_data(...) after the workbook exists. See Prepare Bus Data 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:

  1. reads the assigned source CSV's load column,
  2. finds the generated bus's load.PMAX value in the workbook,
  3. scales the source profile so max(load) equals PMAX,
  4. 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.

Prepare Bus Data

The user can use prepare_bus_data(...) to generate a resolved assignment, optionally save it, and write the case-specific bus_<BUS_IDX>.csv files. A complete example is shown below:

from gridforge.data import prepare_bus_data

# 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 suggests a mapping and materializes the required bus CSVs.
assignment, materialized = prepare_bus_data(
    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",
    resolved_assignment_path="examples/14bus_uc/14bus_data_assignment_resolved.yaml",
    random_seed=404,
)

The saved resolved assignment records source_data_dir, output_data_dir, signals, and the generated buses mapping. It can therefore be inspected, edited, and materialized later without referring back to the template.

Materialize A Saved Assignment

If you want to inspect or edit a resolved assignment before writing bus CSVs, use the lower-level suggest_bus_data_assignment(...) and materialize_bus_data_assignment(...) helpers separately.

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

The resolved assignment's output_data_dir is used by default. Pass output_data_dir=... here only when writing the bus CSVs somewhere else.

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.