flextool 4.0.0__py3-none-any.whl

flextool/process_outputs/out_group.py

@@ -0,0 +1,475 @@
+"""Output functions for node group results."""
+import pandas as pd
+
+from flextool.process_outputs._annualize import annualize_dt_to_d
+
+
+def _get_group_nodes_with_inflow(s, g: str) -> list[str]:
+    """Return nodes in group g that have an inflow method (not 'no_inflow')."""
+    group_nodes = (
+        s.group_node[s.group_node.get_level_values('group') == g]
+        .get_level_values('node')
+        .tolist()
+    )
+    if hasattr(s, 'node__inflow_method'):
+        no_inflow_nodes = {n for (n, method) in s.node__inflow_method if method == 'no_inflow'}
+        return [n for n in group_nodes if n not in no_inflow_nodes]
+    return group_nodes
+
+
+def nodeGroup_indicators(par, s, v, r, debug):
+    """Node group indicator results by period and time"""
+
+    results = []
+
+    if not list(s.nodeGroupIndicators):
+        return results
+
+    # Get time steps
+    dt_index = s.dt_realize_dispatch  # Should be MultiIndex with (period, time)
+
+    # Calculate timestep-level results first
+    results_dt = []
+
+    for g in s.nodeGroupIndicators:
+        group_nodes = (
+            s.group_node[s.group_node.get_level_values('group').isin([g])]
+            .get_level_values('node')
+            .tolist()
+        )
+        group_nodes_with_inflow = _get_group_nodes_with_inflow(s, g)
+
+        # 1. pdtNodeInflow (negative sum)
+        if group_nodes_with_inflow:
+            group_inflow = -par.node_inflow[group_nodes_with_inflow].sum(axis=1)
+        else:
+            group_inflow = pd.Series(0, index=dt_index)
+
+        # 2. Sum of annualized inflows [MWh].  Weight each (d, t) by
+        # par.timestep_weight (=1.0 with no/uniform timeset_weights →
+        # byte-identical) so the annualized inflow matches the cost-weighted
+        # objective.  group_inflow itself stays unweighted: it feeds the
+        # intensive VRE/slack *shares* below where the weight would cancel
+        # anyway, and the raw '5. Timestep inflow' output.
+        annualized_inflow = group_inflow.mul(par.timestep_weight, axis=0).div(par.complete_period_share_of_year)
+
+        # Flow-derived quantities (r.flow_dt, potentialVREgen_dt) and q_state
+        # slacks are MW at the timestep.  Multiply by step_duration so the
+        # stored timestep value is MWh/step — matching '5. Timestep inflow'
+        # (par.node_inflow is already MWh/step).  This keeps all columns in
+        # consistent energy units so shares and period aggregations work for
+        # any step_duration.
+        step_dur = par.step_duration
+
+        # 3. VRE share (actual flow)
+        vre_processes = s.process_VRE.get_level_values('process')
+        vre_cols = r.flow_dt.columns[
+            r.flow_dt.columns.get_level_values('sink').isin(group_nodes) &
+            r.flow_dt.columns.get_level_values('process').isin(vre_processes) &
+            r.flow_dt.columns.isin(s.process_source_sink_alwaysProcess)
+        ]
+        vre_flow_sum = r.flow_dt[vre_cols].mul(step_dur, axis=0).sum(axis=1)
+
+        # VRE share calculation (avoid division by zero)
+        vre_share = vre_flow_sum / group_inflow.where(group_inflow != 0, pd.NA)
+
+        # 4. Curtailed VRE share
+        potential_cols = r.potentialVREgen_dt.columns[
+            r.potentialVREgen_dt.columns.get_level_values(1).isin(group_nodes) &
+            r.potentialVREgen_dt.columns.get_level_values(0).isin(vre_processes)
+        ]
+        potential_sum = r.potentialVREgen_dt[potential_cols].mul(step_dur, axis=0).sum(axis=1)
+        curtailed_vre = (potential_sum - vre_flow_sum).clip(lower=0)
+        curtailed_vre_share = curtailed_vre / group_inflow.where(group_inflow != 0, pd.NA)
+        curtailed_vre / potential_sum
+
+        # Filter balance nodes directly from the sets
+        balance_set = set(s.node_balance) | set(s.node_balance_period)
+        balance_nodes = [n for n in group_nodes if n in balance_set]
+
+        # 5. Upward slack (MWh/step)
+        if balance_nodes and not v.q_state_up.empty:
+            # node_capacity_for_scaling is complete over nodeBalance ∪
+            # nodeBalancePeriod (⊇ q_state nodes), so direct column indexing
+            # is safe.
+            upward_slack = v.q_state_up.mul(par.node_capacity_for_scaling[v.q_state_up.columns]).sum(axis=1).clip(lower=0)
+            upward_slack = upward_slack.mul(step_dur)
+        else:
+            upward_slack = pd.Series(0, index=dt_index)
+
+        # 6. Downward slack (MWh/step)
+        if balance_nodes and not v.q_state_down.empty:
+            downward_slack = v.q_state_down.mul(par.node_capacity_for_scaling[v.q_state_down.columns]).sum(axis=1).clip(lower=0)
+            downward_slack = downward_slack.mul(step_dur)
+        else:
+            downward_slack = pd.Series(0, index=dt_index)
+
+        # Multi-solve handoff: v.* / r.flow_dt span the full union of
+        # sub-solve dt axes, while ``dt_realize_dispatch`` is the
+        # post-roll "realized" subset.  Reindex every component series
+        # to ``dt_index`` so the per-(period, time) DataFrame below
+        # never raises "All arrays must be of the same length".
+        upward_slack = upward_slack.reindex(dt_index, fill_value=0)
+        downward_slack = downward_slack.reindex(dt_index, fill_value=0)
+        vre_flow_sum = vre_flow_sum.reindex(dt_index, fill_value=0)
+        curtailed_vre = curtailed_vre.reindex(dt_index, fill_value=0)
+        curtailed_vre_share = curtailed_vre_share.reindex(dt_index, fill_value=0)
+        vre_share = vre_share.reindex(dt_index, fill_value=0)
+        group_inflow = group_inflow.reindex(dt_index, fill_value=0)
+        annualized_inflow = annualized_inflow.reindex(dt_index, fill_value=0)
+
+        # Combine timestep results for this group
+        group_result_dt = pd.DataFrame({
+            'group': g,
+            'period': dt_index.get_level_values('period'),
+            'time': dt_index.get_level_values('time'),
+            '1. Loss of load': upward_slack.fillna(0).values,
+            '2. VRE generation': vre_flow_sum.values,
+            '3. Excess load': downward_slack.fillna(0).values,
+            '4. Curtailed VRE': curtailed_vre.values,
+            '5. Timestep inflow': group_inflow.values,
+            '6. Curtailed VRE of potential VRE': curtailed_vre_share.fillna(0).values,
+            '7. Annualized inflow': annualized_inflow.values,
+            '8. VRE share of demand': vre_share.fillna(0).values,
+        })
+        results_dt.append(group_result_dt)
+
+    # Combine all groups for timestep level
+    result_flat_dt = pd.concat(results_dt, ignore_index=True)
+
+    # Create multi-index version for timestep level
+    results_dt_indexed = result_flat_dt.set_index(['group', 'period', 'time'])[
+        ['1. Loss of load', '2. VRE generation', '3. Excess load', '4. Curtailed VRE',
+         '5. Timestep inflow', '6. Curtailed VRE of potential VRE', '7. Annualized inflow', '8. VRE share of demand']
+    ]
+    results_dt_indexed.columns.name = "parameter"
+
+    results.append((results_dt_indexed, 'nodeGroup_gdt_p'))
+
+    # Aggregate to period level
+    # For shares, we need to recalculate properly:
+    # Sum the numerators and denominators separately, then divide
+    inflow_d = results_dt_indexed['5. Timestep inflow'].groupby(level=['group', 'period']).sum()
+    annualized_inflow_d = results_dt_indexed['7. Annualized inflow'].groupby(level=['group', 'period']).sum()
+
+    # For VRE share: need to sum absolute flows and recalculate
+    # Since we have vre_share * inflow = vre_flow, we can recover vre_flow
+    vre_flow_dt = results_dt_indexed['8. VRE share of demand'] * results_dt_indexed['5. Timestep inflow']
+    vre_flow_d = vre_flow_dt.groupby(level=['group', 'period']).sum()
+    vre_share_d = vre_flow_d / inflow_d.where(inflow_d != 0, pd.NA)
+
+    # For curtailed VRE share: similar recovery
+    curtailed_vre_share_dt = results_dt_indexed['4. Curtailed VRE'] / results_dt_indexed['5. Timestep inflow']
+    curtailed_vre_share_d = curtailed_vre_share_dt.groupby(level=['group', 'period']).mean()
+    curtailed_vre_of_potential_vre_d = results_dt_indexed['6. Curtailed VRE of potential VRE'].groupby(level=['group', 'period']).sum()
+
+    # Slack shares: sum absolute values and recalculate
+    upward_slack_d = results_dt_indexed['1. Loss of load'].groupby(['group', 'period']).sum()
+    upward_slack_share_d = upward_slack_d / inflow_d
+
+    downward_slack_d = results_dt_indexed['3. Excess load'].groupby(['group', 'period']).sum()
+    downward_slack_share_d = downward_slack_d / inflow_d
+
+    # Combine period-level results
+    results_d_indexed = pd.DataFrame({
+        '1. Loss of load share': upward_slack_share_d.fillna(0),
+        '2. VRE share of demand': vre_share_d.fillna(0),
+        '3. Excess load share': downward_slack_share_d.fillna(0),
+        '4. Curtailed VRE of demand': curtailed_vre_share_d.fillna(0),
+        '5. Annualized inflow': annualized_inflow_d,
+        '6. Curtailed VRE of potential VRE': curtailed_vre_of_potential_vre_d.fillna(0)
+    })
+    results_d_indexed.columns.name = "parameter"
+
+    results.append((results_d_indexed, 'nodeGroup_gd_p'))
+
+    return results
+
+
+def nodeGroup_VRE_share(par, s, v, r, debug):
+    """VRE share for node groups by period and time"""
+
+    results = []
+
+    # Get timesteps and groups
+    timesteps = list(s.dt_realize_dispatch)
+
+    # Filter groups that have nodes with inflow
+    groups_with_inflow = [
+        g for g in s.nodeGroupIndicators
+        if _get_group_nodes_with_inflow(s, g)
+    ]
+
+    if not groups_with_inflow or not timesteps:
+        index = pd.MultiIndex.from_tuples([], names=['period', 'time'])
+        results_dt = pd.DataFrame(
+            index=index,
+            columns=pd.Index(groups_with_inflow, name='group'),
+        )
+        return [(results_dt, 'nodeGroup_VRE_share_dt_g')]
+
+    # Create index
+    index = pd.MultiIndex.from_tuples(timesteps, names=['period', 'time'])
+    results_dt = pd.DataFrame(
+        index=index,
+        columns=pd.Index(groups_with_inflow, name='group'),
+        dtype=float,
+    )
+
+    # Get VRE processes
+    vre_processes = s.process_VRE.unique()
+
+    # Calculate for each group
+    for g in groups_with_inflow:
+        group_nodes = _get_group_nodes_with_inflow(s, g)
+        node_cols = [col for col in par.node_inflow.columns.get_level_values(0) if col in group_nodes]
+
+        # Total inflow to group nodes (vectorized)
+        total_inflow = par.node_inflow[node_cols].sum(axis=1)
+
+        # VRE flow: sum flows from VRE processes to group nodes (vectorized)
+        vre_cols = [(p, src, snk) for (p, src, snk) in r.flow_dt.columns
+                    if p in vre_processes and (p, snk) in s.process_sink and snk in group_nodes]
+
+        if vre_cols:
+            # r.flow_dt is MW — multiply by step_duration to get MWh/step so
+            # the share against total_inflow (MWh/step) is a proper ratio.
+            vre_flow = r.flow_dt[vre_cols].mul(par.step_duration, axis=0).sum(axis=1)
+        else:
+            vre_flow = pd.Series(0.0, index=r.flow_dt.index)
+
+        # Calculate share (avoid division by zero)
+        results_dt[g] = (vre_flow / (-total_inflow)).fillna(0.0)
+
+    results.append((results_dt, 'nodeGroup_VRE_share_dt_g'))
+
+    # Return period results
+    results_d = results_dt.groupby(level='period').mean()
+    results_d.columns.name = 'group'
+    results.append((results_d, 'nodeGroup_VRE_share_d_g'))
+
+    return results
+
+
+def nodeGroup_total_inflow(par, s, v, r, debug):
+    """Total inflow (par.node_inflow) summed over nodes in each group."""
+
+    results = []
+
+    # Use node-based group membership (same as nodeGroup_VRE_share)
+    groups = [
+        g for g in s.nodeGroupIndicators
+        if _get_group_nodes_with_inflow(s, g)
+    ]
+
+    if not groups:
+        return results
+
+    timesteps = list(s.dt_realize_dispatch)
+    if not timesteps:
+        return results
+
+    # Calculate timestep-level results
+    index = pd.MultiIndex.from_tuples(timesteps, names=['period', 'time'])
+    result_multi_dt = pd.DataFrame(index=index, columns=groups, dtype=float)
+
+    for g in groups:
+        group_nodes = _get_group_nodes_with_inflow(s, g)
+        node_cols = [col for col in par.node_inflow.columns.get_level_values(0)
+                     if col in group_nodes]
+        if node_cols:
+            result_multi_dt[g] = par.node_inflow[node_cols].sum(axis=1)
+        else:
+            result_multi_dt[g] = 0.0
+
+    result_multi_dt.columns.name = 'group'
+    results.append((result_multi_dt, 'nodeGroup_flows_dt_g'))
+
+    # Aggregate to period level.  Weight each (d, t) by par.timestep_weight
+    # (=1.0 with no/uniform timeset_weights → byte-identical) before the
+    # period sum.  result_multi_dt is group inflow (already MWh/step), so no
+    # step_duration.
+    result_multi_d = annualize_dt_to_d(result_multi_dt, par.timestep_weight, par.complete_period_share_of_year)
+    result_multi_d.columns.name = 'group'
+    results.append((result_multi_d, 'nodeGroup_flows_d_g'))
+
+    return results
+
+
+def nodeGroup_flows(par, s, v, r, debug):
+    """Group output flows for periods and time.
+
+    result_multi_dt combines sources that arrive in different units: slacks
+    and inflow are already MWh/step, but the v_flow-derived columns
+    (unit/connection flows, internal losses) are MW.  We multiply the
+    latter by step_duration at assignment so every column is MWh/step at
+    the timestep level.  The period-level output (nodeGroup_flows_d_gpe)
+    is then divided by complete_period_share_of_year so it reports
+    annualized MWh, matching node_d_ep and nodeGroup_flows_d_g.
+    """
+
+    results = []
+
+    if s.nodeGroupDispatch.empty or s.dt_realize_dispatch.empty:
+        return results
+
+    step_dur = par.step_duration
+
+    def _to_energy(df: pd.DataFrame) -> pd.DataFrame:
+        """Multiply a (period, time)-indexed MW frame by step_duration → MWh/step.
+
+        Guards against empty placeholder frames whose index lacks 'period'/'time'
+        level names (pandas' align-on-index would raise).
+        """
+        if df.empty:
+            return df
+        return df.mul(step_dur, axis=0)
+
+    # Calculate timestep-level results first
+    result_multi_dt = pd.DataFrame(index=s.dt_realize_dispatch, columns=pd.MultiIndex.from_tuples([], names=['group', 'type', 'item']))
+
+    # Assign simple mappings for all groups at once (before group loop)
+    # Slack upward
+    r.group_node_up_slack__dt.columns = pd.MultiIndex.from_arrays([
+        r.group_node_up_slack__dt.columns,
+        ['slack'] * len(r.group_node_up_slack__dt.columns),
+        ['upward'] * len(r.group_node_up_slack__dt.columns)
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.group_node_up_slack__dt.columns] = r.group_node_up_slack__dt
+
+    # Unit aggregates (aggregateUnits to group)
+    r.nodeGroupDispatch__group_aggregate_Unit_to_group__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__group_aggregate_Unit_to_group__dt.columns.get_level_values('group'),
+        ['from_unitGroup'] * len(r.nodeGroupDispatch__group_aggregate_Unit_to_group__dt.columns),
+        r.nodeGroupDispatch__group_aggregate_Unit_to_group__dt.columns.get_level_values(1)
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__group_aggregate_Unit_to_group__dt.columns] = _to_energy(r.nodeGroupDispatch__group_aggregate_Unit_to_group__dt)
+
+    # Units not in aggregate (unit to group) - sum across nodes
+    r.nodeGroupDispatch__unit_to_node_not_in_aggregate__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__unit_to_node_not_in_aggregate__dt.columns.get_level_values('group'),
+        ['from_unit'] * len(r.nodeGroupDispatch__unit_to_node_not_in_aggregate__dt.columns),
+        r.nodeGroupDispatch__unit_to_node_not_in_aggregate__dt.columns.get_level_values('process')
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__unit_to_node_not_in_aggregate__dt.columns] = _to_energy(r.nodeGroupDispatch__unit_to_node_not_in_aggregate__dt)
+
+    # Connection aggregates (from connections to group) - sum across nodes
+    r.nodeGroupDispatch__from_connection_aggregate__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__from_connection_aggregate__dt.columns.get_level_values('group'),
+        ['from_connectionGroup'] * len(r.nodeGroupDispatch__from_connection_aggregate__dt.columns),
+        r.nodeGroupDispatch__from_connection_aggregate__dt.columns.get_level_values(1)
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__from_connection_aggregate__dt.columns] = _to_energy(r.nodeGroupDispatch__from_connection_aggregate__dt)
+
+    # Connections not in aggregate (from connections)
+    r.nodeGroupDispatch__from_connection_not_in_aggregate__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__from_connection_not_in_aggregate__dt.columns.get_level_values('group'),
+        ['from_connection'] * len(r.nodeGroupDispatch__from_connection_not_in_aggregate__dt.columns),
+        r.nodeGroupDispatch__from_connection_not_in_aggregate__dt.columns.get_level_values('process')
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__from_connection_not_in_aggregate__dt.columns] = _to_energy(r.nodeGroupDispatch__from_connection_not_in_aggregate__dt)
+
+    # Connections not in aggregate (to connections)
+    r.nodeGroupDispatch__to_connection_not_in_aggregate__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__to_connection_not_in_aggregate__dt.columns.get_level_values('group'),
+        ['to_connection'] * len(r.nodeGroupDispatch__to_connection_not_in_aggregate__dt.columns),
+        r.nodeGroupDispatch__to_connection_not_in_aggregate__dt.columns.get_level_values('process')
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__to_connection_not_in_aggregate__dt.columns] = -_to_energy(r.nodeGroupDispatch__to_connection_not_in_aggregate__dt)
+
+    # Connection aggregates (to connections) - sum across nodes
+    r.nodeGroupDispatch__to_connection_aggregate__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__to_connection_aggregate__dt.columns.get_level_values('group'),
+        ['to_connectionGroup'] * len(r.nodeGroupDispatch__to_connection_aggregate__dt.columns),
+        r.nodeGroupDispatch__to_connection_aggregate__dt.columns.get_level_values(1)
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__to_connection_aggregate__dt.columns] = -_to_energy(r.nodeGroupDispatch__to_connection_aggregate__dt)
+
+    # Group to aggregate units (negative)
+    r.nodeGroupDispatch__group_aggregate_Group_to_unit__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__group_aggregate_Group_to_unit__dt.columns.get_level_values('group'),
+        ['to_unitGroup'] * len(r.nodeGroupDispatch__group_aggregate_Group_to_unit__dt.columns),
+        r.nodeGroupDispatch__group_aggregate_Group_to_unit__dt.columns.get_level_values(1)
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__group_aggregate_Group_to_unit__dt.columns] = -_to_energy(r.nodeGroupDispatch__group_aggregate_Group_to_unit__dt)
+
+    # Node to unit not in aggregate (negative)
+    r.nodeGroupDispatch__node_to_unit_not_in_aggregate__dt.columns = pd.MultiIndex.from_arrays([
+        r.nodeGroupDispatch__node_to_unit_not_in_aggregate__dt.columns.get_level_values('group'),
+        ['to_unit'] * len(r.nodeGroupDispatch__node_to_unit_not_in_aggregate__dt.columns),
+        r.nodeGroupDispatch__node_to_unit_not_in_aggregate__dt.columns.get_level_values('process')
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.nodeGroupDispatch__node_to_unit_not_in_aggregate__dt.columns] = -_to_energy(r.nodeGroupDispatch__node_to_unit_not_in_aggregate__dt)
+
+    # Inflow
+    r.group_node_inflow_dt.columns = pd.MultiIndex.from_arrays([
+        r.group_node_inflow_dt.columns,
+        ['inflow'] * len(r.group_node_inflow_dt.columns),
+        r.group_node_inflow_dt.columns
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.group_node_inflow_dt.columns] = r.group_node_inflow_dt
+
+    # Internal losses - connections (sum across processes, negate)
+    if not r.nodeGroupDispatch_Internal_connection_losses__dt.empty:
+        r.nodeGroupDispatch_Internal_connection_losses__dt = r.nodeGroupDispatch_Internal_connection_losses__dt.T.groupby('group').sum().T
+        r.nodeGroupDispatch_Internal_connection_losses__dt.columns = pd.MultiIndex.from_arrays([
+            r.nodeGroupDispatch_Internal_connection_losses__dt.columns,
+            ['internal_losses'] * len(r.nodeGroupDispatch_Internal_connection_losses__dt.columns),
+            ['connections'] * len(r.nodeGroupDispatch_Internal_connection_losses__dt.columns)
+        ], names=['group', 'type', 'item'])
+        result_multi_dt[r.nodeGroupDispatch_Internal_connection_losses__dt.columns] = _to_energy(r.nodeGroupDispatch_Internal_connection_losses__dt)
+
+    # Internal losses - units (sum across processes, negate)
+    if not r.nodeGroupDispatch_Internal_unit_losses__dt.empty:
+        r.nodeGroupDispatch_Internal_unit_losses__dt = r.nodeGroupDispatch_Internal_unit_losses__dt.T.groupby('group').sum().T
+        r.nodeGroupDispatch_Internal_unit_losses__dt.columns = pd.MultiIndex.from_arrays([
+            r.nodeGroupDispatch_Internal_unit_losses__dt.columns,
+            ['internal_losses'] * len(r.nodeGroupDispatch_Internal_unit_losses__dt.columns),
+            ['units'] * len(r.nodeGroupDispatch_Internal_unit_losses__dt.columns)
+        ], names=['group', 'type', 'item'])
+        result_multi_dt[r.nodeGroupDispatch_Internal_unit_losses__dt.columns] = _to_energy(r.nodeGroupDispatch_Internal_unit_losses__dt)
+
+    # Internal losses - storages (negate)
+    r.group_node_state_losses__dt.columns = pd.MultiIndex.from_arrays([
+        r.group_node_state_losses__dt.columns,
+        ['internal_losses'] * len(r.group_node_state_losses__dt.columns),
+        ['storages'] * len(r.group_node_state_losses__dt.columns)
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.group_node_state_losses__dt.columns] = _to_energy(r.group_node_state_losses__dt)
+
+    # Slack downward
+    r.group_node_down_slack__dt.columns = pd.MultiIndex.from_arrays([
+        r.group_node_down_slack__dt.columns,
+        ['slack'] * len(r.group_node_down_slack__dt.columns),
+        ['downward'] * len(r.group_node_down_slack__dt.columns)
+    ], names=['group', 'type', 'item'])
+    result_multi_dt[r.group_node_down_slack__dt.columns] = r.group_node_down_slack__dt
+
+    # Tidy: drop all-zero (group, type, item) columns.  The inflow,
+    # internal_losses storages and slack families are pre-allocated one
+    # column per group (filled with 0.0 even when a group has no inflow /
+    # no self-discharge node / no slack), unlike the join-built unit /
+    # connection families which only appear when non-empty.  Without this
+    # an ``elec`` group that is a single loss-free node still emits an
+    # ``internal_losses | storages`` column of zeros, which reads as a
+    # spurious participant in the plot legend.  ``result_multi_d`` is
+    # derived from ``result_multi_dt`` below, so both stay consistent.
+    if result_multi_dt.shape[1] > 0:
+        result_multi_dt = result_multi_dt.loc[:, (result_multi_dt != 0).any(axis=0)]
+
+    result_multi_dt.columns.names = ['group', 'type', 'item']
+    result_multi_dt = result_multi_dt.sort_index(axis=1, level='group', sort_remaining=False)
+
+    # Return timestep results
+    results.append((result_multi_dt, 'nodeGroup_flows_dt_gpe'))
+
+    # Aggregate to period level and annualize to match node_d_ep convention.
+    # result_multi_dt is already energy (MWh/step); weight each (d, t) by
+    # par.timestep_weight (=1.0 with no/uniform timeset_weights →
+    # byte-identical) before the period sum.
+    result_multi_d = annualize_dt_to_d(result_multi_dt, par.timestep_weight, par.complete_period_share_of_year)
+
+    # Return period results
+    results.append((result_multi_d, 'nodeGroup_flows_d_gpe'))
+
+    return results

flextool/process_outputs/out_node.py

@@ -0,0 +1,190 @@
+import pandas as pd
+
+from flextool.process_outputs._annualize import annualize_dt_to_d
+
+# Storage node is surfaced in the node balance/price outputs only if it is
+# wired to more than this many distinct processes.  A battery (one inverter,
+# or separate charge + discharge units ⇒ ≤2 processes) stays hidden to avoid
+# cluttering the outputs; a multi-use hub (e.g. a hydrogen node feeding an
+# electrolyser, a turbine and several conversion routes ⇒ many processes) is
+# surfaced automatically.
+MULTI_USE_STORAGE_PROCESS_THRESHOLD = 2
+
+
+def _multi_use_storage_nodes(s):
+    """Storage nodes wired to more than the threshold of distinct processes.
+
+    Counts distinct process *names* across the node's source- and sink-side
+    arcs (``s.process_source`` / ``s.process_sink``), so a bidirectional unit
+    appearing on both sides counts once.  Arc-level only — never touches the
+    ``(d, t)`` timeline.  Returns a ``node``-named Index that is a subset of
+    ``s.node_state``; the complement (boring storage) is what gets hidden.
+    """
+    if len(s.node_state) == 0:
+        return s.node_state
+    src = s.process_source.to_frame(index=False).rename(columns={"source": "node"})
+    snk = s.process_sink.to_frame(index=False).rename(columns={"sink": "node"})
+    arcs = pd.concat([src, snk], ignore_index=True)
+    arcs = arcs[arcs["node"].isin(s.node_state)]
+    if arcs.empty:
+        return pd.Index([], name="node", dtype=s.node_state.dtype)
+    counts = arcs.groupby("node")["process"].nunique()
+    return pd.Index(
+        counts.index[counts > MULTI_USE_STORAGE_PROCESS_THRESHOLD], name="node",
+    )
+
+
+def node_summary(par, s, v, r, debug):
+    """Node balance summaries for periods and timesteps"""
+    results = []
+
+    categories = ['From units', 'From connections', 'Loss of load', 'To units', 'To connections', 'Self discharge', 'Excess load', 'Inflow']
+
+    balanced_nodes = s.node_balance.union(s.node_balance_period)
+    if debug:
+        nodes = s.node
+    else:
+        # Hide boring storage nodes (batteries); keep multi-use storage hubs.
+        hidden_storage = s.node_state.difference(_multi_use_storage_nodes(s))
+        nodes = balanced_nodes.difference(hidden_storage)
+    nodes_sink = s.node.copy().intersection(nodes)
+    nodes_sink.name = 'sink'
+    nodes_source = s.node.copy().intersection(nodes)
+    nodes_source.name = 'source'
+
+    # 1. Timestep-level node summary
+    node_dt = pd.DataFrame(index=s.dt_realize_dispatch, columns=pd.MultiIndex.from_product([nodes, categories], names=['node', 'category']), dtype=float)
+
+    # From units
+    from_units = r.flow_dt[s.process_unit.join(r.flow_dt.columns).join(nodes_sink, how='inner')].T.groupby('sink').sum().T
+    from_units_cols = node_dt.columns[
+                        node_dt.columns.get_level_values('node').isin(from_units.columns)
+                        & node_dt.columns.get_level_values('category').isin(['From units'])]
+    node_dt[from_units_cols] = from_units[from_units_cols.get_level_values('node')]
+
+    # From connections
+    from_connections = r.flow_dt[s.process_connection.join(r.flow_dt.columns).join(nodes_sink, how='inner')].T.groupby('sink').sum().T
+    from_connections_cols = node_dt.columns[
+                        node_dt.columns.get_level_values('node').isin(from_connections.columns)
+                        & node_dt.columns.get_level_values('category').isin(['From connections'])]
+    node_dt[from_connections_cols] = from_connections[from_connections_cols.get_level_values('node')]
+
+    # Upward slack
+    upward_slack_data = v.q_state_up.loc[:, v.q_state_up.columns.get_level_values('node').isin(balanced_nodes.intersection(nodes))].clip(lower=0)
+    # node_capacity_for_scaling is complete over nodeBalance ∪
+    # nodeBalancePeriod (⊇ q_state nodes), so direct column indexing is safe.
+    upward_slack_data = upward_slack_data.mul(par.node_capacity_for_scaling[upward_slack_data.columns], axis=1)
+    upward_slack_cols = node_dt.columns[
+                        node_dt.columns.get_level_values('node').isin(upward_slack_data.columns.get_level_values('node'))
+                        & node_dt.columns.get_level_values('category').isin(['Loss of load'])]
+    node_dt[upward_slack_cols] = upward_slack_data[upward_slack_cols.get_level_values('node')]
+
+    # To units (negative)
+    to_units = -r.flow_dt[s.process_unit.join(r.flow_dt.columns).join(nodes_source, how='inner')].T.groupby('source').sum().T
+    to_units_cols = node_dt.columns[
+                        node_dt.columns.get_level_values('node').isin(to_units.columns)
+                        & node_dt.columns.get_level_values('category').isin(['To units'])]
+    node_dt[to_units_cols] = to_units[to_units_cols.get_level_values('node')]
+
+    # To connections (negative)
+    to_connections = -r.flow_dt[s.process_connection.join(r.flow_dt.columns).join(nodes_source, how='inner')].T.groupby('source').sum().T
+    to_connections_cols = node_dt.columns[
+                        node_dt.columns.get_level_values('node').isin(to_connections.columns)
+                        & node_dt.columns.get_level_values('category').isin(['To connections'])]
+    node_dt[to_connections_cols] = to_connections[to_connections_cols.get_level_values('node')]
+
+    # Self discharge (negative)
+    self_discharge = -r.self_discharge_loss_dt[r.self_discharge_loss_dt.columns.intersection(s.node_self_discharge.intersection(nodes))]
+    self_discharge_cols = node_dt.columns[
+                        node_dt.columns.get_level_values('node').isin(self_discharge.columns)
+                        & node_dt.columns.get_level_values('category').isin(['Self discharge'])]
+    node_dt[self_discharge_cols] = self_discharge[self_discharge_cols.get_level_values('node')]
+
+    # Downward slack (negative)
+    downward_slack_data = (-v.q_state_down.loc[:, v.q_state_down.columns.get_level_values('node').isin(balanced_nodes.intersection(nodes))]).clip(upper=0)
+    downward_slack_data = downward_slack_data.mul(par.node_capacity_for_scaling[downward_slack_data.columns], axis=1)
+    downward_slack_cols = node_dt.columns[
+                        node_dt.columns.get_level_values('node').isin(downward_slack_data.columns.get_level_values('node'))
+                        & node_dt.columns.get_level_values('category').isin(['Excess load'])]
+    node_dt[downward_slack_cols] = downward_slack_data[downward_slack_cols.get_level_values('node')]
+
+    # Inflow
+    inflow_cols = node_dt.columns[
+                    node_dt.columns.get_level_values('node').isin(par.node_inflow.columns.intersection(nodes))
+                    & node_dt.columns.get_level_values('category').isin(['Inflow'])]
+    node_dt[inflow_cols] = par.node_inflow[inflow_cols.get_level_values('node')]
+
+    # Fill any remaining NaN values with 0
+    node_dt = node_dt.fillna(0.0)
+
+    results.append((node_dt, 'node_dt_ep'))
+
+    # 2. Period-level node summary.  Most categories (flows, slacks, self
+    # discharge) are MW — multiply by step_duration to get MWh per step.
+    # Inflow is already MWh/step (par.node_inflow is energy per step, see
+    # mod comment at flextool.mod:2319), so compute it separately.
+    energy_categories = [c for c in categories if c != 'Inflow']
+    energy_cols = node_dt.columns[node_dt.columns.get_level_values('category').isin(energy_categories)]
+    inflow_cols = node_dt.columns[node_dt.columns.get_level_values('category') == 'Inflow']
+
+    # Weight each (d, t) by par.timestep_weight (=1.0 with no/uniform
+    # timeset_weights → byte-identical) before the period sum, so reported
+    # annual energy matches the cost-weighted objective.
+    node_d_energy = annualize_dt_to_d(
+        node_dt[energy_cols], par.timestep_weight,
+        par.complete_period_share_of_year, par.step_duration, div_level=1)
+    node_d_inflow = annualize_dt_to_d(
+        node_dt[inflow_cols], par.timestep_weight,
+        par.complete_period_share_of_year, div_level=1)
+    node_d = pd.concat([node_d_energy, node_d_inflow], axis=1).reindex(columns=node_dt.columns)
+
+    results.append((node_d, 'node_d_ep'))
+
+    return results
+
+
+def node_additional_results(par, s, v, r, debug):
+    """Additional node results: prices, state, and slacks"""
+    results = []
+
+    # 1. Nodal prices — the per-(d,t) nodal-balance dual.  Per-step balance
+    # nodes carry ``nodeBalance_eq``; coarse variable-resolution nodes
+    # (``new_stepduration`` → ``nodeStateBlock``) carry ``nodeBalanceBlock_eq``
+    # broadcast to per-(d,t) — both are merged into ``v.dual_node_balance``
+    # by ``write_v_dual_node_balance``.  Defensive intersection with the
+    # available columns (order-preserving): every requested node normally
+    # has a dual, but if a node genuinely lacks one (e.g. a future balance
+    # mode without a dual writer) this omits it rather than raising
+    # ``KeyError: None of [...] are in the columns``.
+    # Mirror the node-balance summary: hide boring storage nodes (batteries),
+    # keep multi-use storage hubs.  For a battery the balance dual is largely
+    # redundant with the connected electricity node's price (and most prone to
+    # degeneracy at the storage margin); for a multi-use hub (e.g. a hydrogen
+    # node) it is the genuine, otherwise-unavailable marginal value of that
+    # commodity — the case worth reporting.
+    hidden_storage = s.node_state.difference(_multi_use_storage_nodes(s))
+    price_nodes = s.node_balance.difference(hidden_storage).intersection(
+        v.dual_node_balance.columns)
+    results.append((v.dual_node_balance[price_nodes], 'node_prices_dt_e'))
+
+    # 2. Node state
+    node_state = v.state.mul(par.entity_unitsize[s.node_state], level="node")
+    results.append((node_state, 'node_state_dt_e'))
+
+    # 3. Node upward slack (MW at timestep; multiply by step_duration for MWh period)
+    upward_slack = v.q_state_up.mul(par.node_capacity_for_scaling[s.node_balance.union(s.node_balance_period)], level=0).clip(lower=0)
+    results.append((upward_slack, 'node_slack_up_dt_e'))
+    upward_slack_d = annualize_dt_to_d(
+        upward_slack, par.timestep_weight, par.complete_period_share_of_year,
+        par.step_duration, div_level=1)
+    results.append((upward_slack_d, 'node_slack_up_d_e'))
+
+    # 4. Node downward slack (MW at timestep; multiply by step_duration for MWh period)
+    downward_slack = v.q_state_down.mul(par.node_capacity_for_scaling[s.node_balance.union(s.node_balance_period)], level=0).clip(lower=0)
+    results.append((downward_slack, 'node_slack_down_dt_e'))
+    downward_slack_d = annualize_dt_to_d(
+        downward_slack, par.timestep_weight, par.complete_period_share_of_year,
+        par.step_duration, div_level=1)
+    results.append((downward_slack_d, 'node_slack_down_d_e'))
+
+    return results