flextool 4.0.0__py3-none-any.whl

flextool/schemas/comparison_settings_template.json

@@ -0,0 +1,197 @@
+{
+    "entity_classes": [
+        [
+            "settings",
+            [],
+            null,
+            280959580696595,
+            true
+        ]
+    ],
+    "entities": [
+        [
+            "settings",
+            "default",
+            null
+        ]
+    ],
+    "parameter_definitions": [
+        [
+            "settings",
+            "active-output-configs",
+            null,
+            null,
+            null
+        ],
+        [
+            "settings",
+            "output-config-path",
+            null,
+            null,
+            null
+        ],
+        [
+            "settings",
+            "plot_duration",
+            null,
+            null,
+            null
+        ],
+        [
+            "settings",
+            "plot_first_timestep",
+            null,
+            null,
+            null
+        ],
+        [
+            "settings",
+            "show-plots",
+            false,
+            null,
+            null
+        ],
+        [
+            "settings",
+            "write-dispatch-to-excel",
+            true,
+            null,
+            null
+        ],
+        [
+            "settings",
+            "write-to-excel",
+            true,
+            null,
+            null
+        ],
+        [
+            "settings",
+            "write-to-ods",
+            false,
+            null,
+            null
+        ]
+    ],
+    "parameter_types": [
+        [
+            "settings",
+            "active-output-configs",
+            "array",
+            1
+        ],
+        [
+            "settings",
+            "output-config-path",
+            "str",
+            0
+        ],
+        [
+            "settings",
+            "plot_duration",
+            "float",
+            0
+        ],
+        [
+            "settings",
+            "plot_first_timestep",
+            "float",
+            0
+        ],
+        [
+            "settings",
+            "show-plots",
+            "bool",
+            0
+        ],
+        [
+            "settings",
+            "write-dispatch-to-excel",
+            "bool",
+            0
+        ],
+        [
+            "settings",
+            "write-to-excel",
+            "bool",
+            0
+        ],
+        [
+            "settings",
+            "write-to-ods",
+            "bool",
+            0
+        ]
+    ],
+    "parameter_values": [
+        [
+            "settings",
+            "default",
+            "active-output-configs",
+            {
+                "value_type": "str",
+                "data": [
+                    "default",
+                    "chunks"
+                ],
+                "type": "array"
+            },
+            "default"
+        ],
+        [
+            "settings",
+            "default",
+            "output-config-path",
+            "templates/comparison_plots.yaml",
+            "default"
+        ],
+        [
+            "settings",
+            "default",
+            "plot_duration",
+            168,
+            "default"
+        ],
+        [
+            "settings",
+            "default",
+            "plot_first_timestep",
+            0.0,
+            "default"
+        ],
+        [
+            "settings",
+            "default",
+            "write-dispatch-to-excel",
+            true,
+            "default"
+        ],
+        [
+            "settings",
+            "default",
+            "write-to-excel",
+            true,
+            "default"
+        ]
+    ],
+    "alternatives": [
+        [
+            "default",
+            ""
+        ]
+    ],
+    "scenarios": [
+        [
+            "default",
+            false,
+            ""
+        ]
+    ],
+    "scenario_alternatives": [
+        [
+            "default",
+            "default",
+            null
+        ]
+    ]
+}

flextool/schemas/default_plot_settings.yaml

@@ -0,0 +1,260 @@
+# Plot settings for this project.
+#
+# This file is this project's own starting point for how its results are
+# plotted: which colors entities and result categories get, the stacking
+# order, and the sign (positive vs negative side) coloring.  You can edit
+# it freely — it is yours to keep.  Deleting it falls back to a built-in
+# starting point.
+#
+# How it is read:
+#
+#   categories:   result / parameter names produced by the pipeline.
+#                 Looked up by EXACT label match (casing is controlled by
+#                 the pipeline, so it is stable).
+#
+#   entities:     entity names that come from your data (units,
+#                 connections, nodes, and groups).  Looked up
+#                 CASE-INSENSITIVELY, so "Solar", "solar" and "SOLAR" all
+#                 resolve to the same entry.
+#
+#   scenarios:    colors for comparison scenarios.
+#
+# Entry VALUES may be either a ``#RRGGBB`` hex string or an ``[r, g, b]``
+# list.  RGB components are accepted as floats in ``0..1`` or ints in
+# ``0..255``.  An entity entry may instead be a mapping with an optional
+# negative-side color, e.g.::
+#
+#     chp: { color: "#E64A19", neg_color: "#9c3010" }
+#
+# in which case ``neg_color`` colors the entity's negative-side part of a
+# mixed (both-signs) stacked column and ``color`` is used for the positive
+# side.  A bare color uses the same color for both sides.
+#
+# Entry ORDER defines the stacking order: items listed here are placed in
+# file order (positives top→bottom; negatives reversed), and any item not
+# listed falls back to the default ordering and the tab10/tab20 matplotlib
+# palette — so this file is purely additive and there is no penalty for an
+# item that is not listed here.
+
+scenarios:
+  # Colors for comparison scenarios, keyed by scenario name, e.g.
+  #   S04_battery: "#1f77b4"
+  # (Left empty here — fill in per project.)
+
+categories:
+  # Cost components produced by flextool/process_outputs/out_costs.py.
+  # Semantic grouping:
+  #   - Investment / capex   → saturated blues
+  #   - Fixed O&M            → teals / light blues
+  #   - Fuel / commodities   → warm browns / oranges / greens (sales)
+  #   - Emissions (CO2)      → dark gray / near-black
+  #   - Variable O&M         → purples
+  #   - Startup              → amber / yellow
+  #   - Slack / penalties    → reds / magentas (visually alarming)
+  costs:
+    # Investment / capex (saturated blues)
+    unit investment & retirement:          '#1f4ea8'   # strong blue
+    connection investment & retirement:    '#3b6fc4'   # medium blue
+    storage investment & retirement:       '#6691d8'   # lighter blue
+    # Fixed O&M (teal family — "keep the lights on, recurring")
+    fixed cost pre-existing:               '#0f8a7a'   # teal
+    fixed cost invested:                   '#3bb0a0'   # brighter teal
+    fixed cost reduction of divestments:   '#8ed2c9'   # pale teal
+    # Commodity / fuel (warm browns / oranges for input, green for sales)
+    commodity_cost:                        '#a0522d'   # sienna (fuel "energy input")
+    commodity_sales:                       '#2ca02c'   # green (revenue / negative cost)
+    # Emissions (gray/near-black — instantly reads as "emissions")
+    co2:                                   '#4d4d4d'   # dark gray
+    # Variable O&M (purple)
+    other operational:                     '#8856a7'   # purple
+    # Startup (amber/yellow — "ignition")
+    starts:                                '#e6a41a'   # amber
+    # Slack / penalties (red / magenta family — alarming)
+    upward slack penalty:                  '#d62728'   # strong red
+    downward slack penalty:                '#ff7f7f'   # light red
+    inertia slack penalty:                 '#b5179e'   # magenta
+    non-synchronous slack penalty:         '#e147b7'   # pink-magenta
+    upward reserve slack penalty:          '#c1272d'   # dark red
+    downward reserve slack penalty:        '#ff9896'   # salmon
+    capacity margin penalty:               '#7b0828'   # deep wine red
+  # Node balance components produced by
+  # flextool/process_outputs/out_node.py::node_summary().  The plot shows
+  # stacked contributions to a node's energy balance: supply-side labels
+  # sit above the zero line (From units, From connections, Inflow, Loss
+  # of load), draw-side labels below it (To units, To connections, Self
+  # discharge, Excess load).  Colors are chosen so:
+  #   - supply / generation / imports → greens and teals
+  #   - load / exports / storage charge → blues
+  #   - storage self-discharge losses → neutral gray
+  #   - slacks (infeasibility) → reds, matching the cost-slack hues so
+  #     users learn a single "slack = red" vocabulary across plots
+  node_flows:
+    # Supply side (positive contributions to the node)
+    From units:         '#2ca02c'   # green — generation delivered to node
+    From connections:   '#17a2b8'   # teal — imports from neighbouring nodes
+    Inflow:             '#7dd87a'   # light green — exogenous inflow (wind, hydro)
+    # Draw side (negative contributions to the node)
+    To units:           '#1f77b4'   # strong blue — consumption / storage charge
+    To connections:     '#5b8fbf'   # steel blue — exports to neighbouring nodes
+    Self discharge:     '#808080'   # gray — storage self-discharge loss
+    # Slacks (infeasibility; red family matches costs-category slacks)
+    Loss of load:       '#d62728'   # strong red — upward slack (unmet demand)
+    Excess load:        '#ff7f7f'   # light red — downward slack (spill / dump)
+
+  # NodeGroup flow components emitted by
+  # flextool/process_outputs/out_group.py::nodeGroup_flows().  The column
+  # index there has two levels, ``type`` and ``item``; legend labels arrive
+  # as either ``"<type> | <item>"`` (bar plans, via _format_legend_labels)
+  # or Python tuple repr ``"('<type>', '<item>')"`` (time-series stacks).
+  #
+  # Coloring is split by ``type``:
+  #
+  #   * The per-participant flow types — ``from_unitGroup`` / ``to_unitGroup``
+  #     / ``from_unit`` / ``to_unit`` / ``from_connectionGroup`` /
+  #     ``to_connectionGroup`` / ``from_connection`` / ``to_connection`` —
+  #     are colored by their ``item`` (the participating entity), looked up
+  #     in the ``entities`` section below: ``*unit*`` items in ``entities.unit``,
+  #     ``*connection*`` items in ``entities.connection`` and the ``*Group``
+  #     aggregates in ``entities.group``.  The ``to_*`` (draw) side uses the
+  #     entity's ``neg_color`` when one is set, else its ``color``.  So a unit
+  #     keeps the same color here as in its node-flow / dispatch plots, and an
+  #     item with no ``entities`` entry falls back to the tab10/tab20 palette.
+  #     These types are therefore NOT listed here.
+  #
+  #   * The group-property aggregates below — ``inflow``, ``internal_losses``
+  #     and ``slack`` — aren't entities, so they keep explicit category
+  #     colors, looked up as ``<type>_<item>`` then ``<type>``.  Reds match
+  #     costs / node_flows slacks; grays read as "dissipated inside the
+  #     group".  ``internal_losses`` and ``slack`` have a CLOSED set of item
+  #     subtypes (connections/units/storages; upward/downward — see
+  #     out_group.py::nodeGroup_flows), so every series hits a ``<type>_<item>``
+  #     key and no bare ``<type>`` fallback is needed.  ``inflow`` keeps a
+  #     bare key because its item is the node name (open set), resolved via
+  #     the ``<type>`` step.
+  nodegroup_flows:
+    inflow:                      '#7dd87a'   # light green — exogenous node inflow
+    # Internal losses (neutral grays — "energy dissipated inside the group")
+    internal_losses_connections: '#9e9e9e'   # lighter gray — connection losses
+    internal_losses_units:       '#6b6b6b'   # darker gray — unit losses
+    internal_losses_storages:    '#5c5c5c'   # darkest gray — storage self-discharge
+    # Slacks (red family; aligned with costs.upward/downward slack penalty
+    # and node_flows.Loss of load / Excess load)
+    slack_upward:                '#d62728'   # strong red — upward slack (unmet demand)
+    slack_downward:              '#ff7f7f'   # light red — downward slack (spill)
+
+  # Dispatch special tokens.  These are the fixed-name columns that the
+  # dispatch stacked-area plots add alongside the per-entity flows: loss of
+  # load / discharge / import on the POSITIVE side (top of the stack) and
+  # charge / export / internal losses on the NEGATIVE side (bottom).  Their
+  # color is configurable, and their KEY ORDER here is honored by the engine:
+  # this list is read TOP-TO-BOTTOM as the visual stack order.  A positive
+  # special always stacks above the zero axis and a negative special always
+  # below it (they never cross), but WITHIN each sign group the order of these
+  # keys sets the top-to-bottom stacking (and matches the picker's
+  # "Colors, order..." dialog, where they are reorderable within each group).
+  # Looked up by EXACT label match.  The values below are the historical
+  # dispatch defaults (DEFAULT_SPECIAL_COLORS) in the historical stack order,
+  # so a project with no per-entity dispatch colors renders exactly as before.
+  # (The dashed ``Curtailed`` line and the solid ``Demand`` line are drawn
+  # with fixed red / black and are not configured here.)
+  dispatch:
+    # Positive side, visual top-to-bottom (top of the stacked area / legend)
+    LossOfLoad:      crimson     # upward slack — unmet demand
+    Discharge:       aqua        # storage discharge into the group
+    Import:          indigo      # imports into the group
+    # Negative side, visual top-to-bottom (nearest the zero axis downward)
+    internal_losses: darkgray    # losses dissipated inside the group
+    Export:          purple      # exports out of the group
+    Charge:          lime        # storage charge drawn from the group
+
+entities:
+  # Colors for entities, keyed by entity name (case-insensitive).  The
+  # subsections below correspond to entity classes.  Entry order within a
+  # subsection defines stacking order; an optional ``neg_color`` colors an
+  # entity's negative-side part of a mixed (both-signs) stacked column.
+  #
+  # ``group`` entities are split by their membership into two subsections:
+  #   * ``nodeGroup``  — a group whose membership is ``group__node`` (a
+  #     collection of nodes, e.g. the balance/dispatch group being plotted).
+  #   * ``flowGroup``  — a group whose membership is ``group__unit__node`` /
+  #     ``group__connection`` (it aggregates FLOWS, e.g. "Battery", "Coal").
+  #     These are the per-participant items colored in nodeGroup-dispatch
+  #     plots, so they ship with recommended technology/fuel colors below.
+  # The ``unit`` / ``connection`` / ``node`` / ``nodeGroup`` subsections
+  # start empty — per-project entity colors are filled in by you (or
+  # auto-populated from the entities present in your results); leaving them
+  # empty means no change from the palette fallback.  (Projects seeded
+  # before the split keep a legacy ``group`` subsection, which the dispatch
+  # resolver still reads; a "Refresh from DB" re-buckets into
+  # nodeGroup/flowGroup.)
+  nodeGroup:
+    # Per-project nodeGroup colors, keyed by group name (case-insensitive).
+    # (Left empty here — fill in per project.)
+  flowGroup:
+    # Recommended colors for user-named flowGroup entities.  A flowGroup is a
+    # ``group`` entity whose membership is ``group__unit__node`` or
+    # ``group__connection__node`` (i.e. it aggregates flows, not nodes) and
+    # that carries ``output_flowGroup_indicators = yes``.  The labels below
+    # are a *convention*: if different projects happen to name a flow group
+    # "solar" or "Wind", they get the same color across dashboards.
+    #
+    # Lookup is case-insensitive (see color_template.resolve_label_color), so
+    # "Solar", "solar", and "SOLAR" all resolve to the same entry.  Labels
+    # that aren't listed fall back to the tab10/tab20 palette, so this list
+    # is purely additive — there's no penalty for a project using a name
+    # that isn't here.
+    #
+    # Palette rationale: semantic colors users already associate with the
+    # technology / fuel (yellow for solar, sky blue for wind, black for
+    # coal, …), paired across related pairs (coal/lignite both dark, two
+    # blues for hydro vs pumped hydro) so stacked plots read naturally.
+    # Renewables — bright, warm-to-cool gradient
+    solar:          '#F4B400'   # gold / sun
+    pv:             '#F4B400'   # gold / sun (alias for solar PV)
+    wind:           '#4FC3F7'   # sky blue
+    hydro:          '#1565C0'   # deep blue (flowing water)
+    biomass:        '#33691E'   # forest green
+    geothermal:     '#8D6E63'   # burnt-orange brown (earth heat)
+    ocean:          '#006064'   # teal (deep sea — tidal / wave)
+    # Conventional — dark, muted (carbon-heavy "reads as dirty")
+    coal:           '#212121'   # near-black
+    lignite:        '#4E342E'   # dark brown (lower-grade coal)
+    gas:            '#FB8C00'   # orange-red (flame)
+    oil:            '#6A1B9A'   # dark purple (heavy fuel)
+    nuclear:        '#7B1FA2'   # purple (convention in energy atlases)
+    # Storage — greens / teals (shifts energy in time, not a generator)
+    battery:        '#43A047'   # bright green (electrochemistry)
+    pumped_hydro:   '#00838F'   # teal (water-based storage)
+    h2_storage:     '#BA68C8'   # light purple (hydrogen)
+    # Other flows
+    chp:            '#E64A19'   # orange-red (combined heat & power)
+    import:         '#90CAF9'   # light blue (external supply)
+    export:         '#EF9A9A'   # light red (outbound)
+    demand_response: '#FFB300'  # amber (flexible load)
+  unit:
+    # Per-project unit colors, keyed by unit name (case-insensitive).
+    # Entry order defines stacking order; an optional ``neg_color`` colors
+    # the unit's negative-side part of a mixed column.  These colors apply
+    # to the unit's stacked/line flow and online time-series plots (e.g.
+    # "Flows: unit to node", "Flows: node to unit", "Unit online").
+    # (Left empty here — fill in per project.)  Accepted formats, e.g.:
+    #   <unit_name>: "#1f77b4"                                   # bare color (both sides)
+    #   <unit_name>: { color: "#1f77b4", neg_color: "#0d3a6b" }  # distinct negative side
+  connection:
+    # Per-project connection colors, keyed by connection name
+    # (case-insensitive).  Entry order defines stacking order; an optional
+    # ``neg_color`` colors the negative side.  These colors apply to the
+    # connection's stacked/line flow time-series plots (e.g. "Flows
+    # connection", "Connection leftward", "Connection rightward").
+    # (Left empty here — fill in per project.)  Accepted formats, e.g.:
+    #   <connection_name>: "#888888"                                 # bare color (both sides)
+    #   <connection_name>: { color: "#5b8fbf", neg_color: "#3c5e8a" } # distinct negative side
+  node:
+    # Per-project node colors, keyed by node name (case-insensitive).
+    # Entry order defines stacking order; an optional ``neg_color`` colors
+    # the negative side.  These colors apply to the node's state time-series
+    # plot ("Node state").  The node *balance* plot ("Node") stays
+    # category-coloured (see categories.node_flows above), by design.
+    # (Left empty here — fill in per project.)  Accepted formats, e.g.:
+    #   <node_name>: "#4FC3F7"                                # bare color (both sides)
+    #   <node_name>: { color: "#43A047", neg_color: "#2e7d32" } # distinct negative side