Skip to content

Surface plant

surface components/surface/ · config type: surface, variant graph

The surface plant turns the produced fluid into electricity or heat and returns it, cooled, to the injection well. Its layout is not hard-coded: the config's power_plant block lists TESPy nodes (turbines, separators, heat exchangers, pumps) and the edges between them, and TANGO solves that network every timestep. A single-flash, double-flash, ORC or direct-heat plant is therefore a config change, not new code. See templates/hydro_sf_electric.yml (single flash) and templates/AGS_direct_heat.yml (direct heat) for complete graphs. An Aspen Plus connection is planned as a further variant.

How the model works

Generic, YAML-graph-driven surface / power-plant component for tango.

GraphSurface builds its TESPy network entirely from a power_plant.nodes/power_plant.edges block in the YAML, rather than hardcoding a fixed topology in Python. One class covers single-flash, AGS direct-heat, and any future topology; adding a new plant design is a YAML change, not a new Python class.

Required naming convention (the one piece that can't be pure YAML — this is wiring to the rest of the simulation, not plant layout, so it has to be an explicit, documented contract rather than inferred from graph shape):

  • Exactly one Source node named "inlet" — solve() writes T/p/m/fluid onto its outgoing connection from its inlet parameter each timestep.
  • Exactly one Sink node named "outlet" — solve() forces its incoming connection's pressure to self.injection_pressure (the BC variable SystemBCIteration iterates), and reads self.outlet back off it after solving.
  • Any node contributing to the plant's net output tags itself with role: net_electric or role: net_thermal (see ComponentRole in core/policies.py). Untagged nodes (valves, separators, condensers, mixers) are solved as part of the network but not summed into either total.

Sign convention for role aggregation (no per-component-type branch needed): TESPy's P.val/Q.val are positive when power/heat flows into the fluid and negative when it flows out. Summing -P.val over every net_electric node therefore adds turbines (negative P → positive contribution) and subtracts compressors/pumps (positive P → negative contribution) uniformly; summing -Q.val over net_thermal nodes gives positive delivered heat for a heat exchanger rejecting heat to a district-heating loop.

type: PumpOrValve (in addition to the real TESPy component types) is a per-node opt-in for a circulation point whose physically correct resolution (a passive Valve, or a real Compressor) depends on design-point conditions rather than being knowable up front -- see init()/_NetworkBundle/_check_pump_or_valve_validity. It builds and holds TWO full networks, tries the Valve-resolved one first each solve(), and falls back to the Compressor-resolved one if that's physically invalid for the current timestep -- see docs/archive/bugs-fixed-in-tango.md's "AGS closed loop has no pump anywhere" entry for the physical motivation.

Example YAML (AGS direct-heat — the topology that motivated this class):

surface:
  type: 'graph'
  power_plant:
    nodes:
      inlet: {type: Source}
      district_heating_hx: {type: SimpleHeatExchanger, role: net_thermal, T_out: 323.15, pressure_ratio: 0.99}
      circulation_control: {type: PumpOrValve, role: net_electric, efficiency: 1.0}
      outlet: {type: Sink}
    edges:
      1: {source: inlet, target: district_heating_hx}
      2: {source: district_heating_hx, target: circulation_control}
      3: {source: circulation_control, target: outlet}

Unit conventions (TESPy network created with p_unit="bar", T_unit="C"):

  • YAML pressures in Pa -> bar via x 1e-5; p_out_megapascals -> bar via x 10
  • Temperatures: K -> degC for TESPy input, TESPy degC -> K for output
  • Power: TESPy node .P.val/.Q.val in W (SI), regardless of the h_unit="kJ/kg" display setting

Plant graph nodes

Every power_plant.nodes.<name> entry has a type from this list and an optional role that decides which plant total its power counts toward.

Node type TESPy class
Compressor tespy.components.Compressor
CycleCloser tespy.components.CycleCloser
DropletSeparator tespy.components.DropletSeparator
HeatExchanger tespy.components.HeatExchanger
Merge tespy.components.Merge
SimpleHeatExchanger tespy.components.SimpleHeatExchanger
Sink tespy.components.Sink
Source tespy.components.Source
Turbine tespy.components.Turbine
Valve tespy.components.Valve
PumpOrValve resolved to a valve or a compressor at solve time

Node role (optional): net_electric, net_thermal.

Config keys

surface · graph → GraphSurface

Key Type Default Meaning
component_idx int required undocumented
save_interval int \| None 1 undocumented
prev int required undocumented
next int required undocumented
pipe_diameter float required undocumented
pipe_roughness float required undocumented
approach_temperature float required undocumented
power_plant dict[str, Any] computed undocumented
record_node_detail bool True undocumented

Filled in automatically, not set in this block: common from the common: block, target_extraction_pressure from sim_config.target_extraction_pressure, well_spacing from layout.well_spacing.

Outputs per timestep

Columns in <name>.smry.csv, where <name> is the component's key in the config.

surface · graph → GraphSurface

Column Meaning
<name>_h_inlet undocumented
<name>_h_outlet undocumented
<name>_T_inlet undocumented
<name>_T_outlet undocumented
<name>_P_inlet undocumented
<name>_P_outlet undocumented
<name>_mass_rate undocumented
<name>_dP_pipe undocumented
<name>_P_tespy_inlet undocumented
<name>_rho undocumented
<name>_mu undocumented
<name>_net_power_W undocumented
<name>_net_thermal_W undocumented