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
Sourcenode named"inlet"—solve()writesT/p/m/fluidonto its outgoing connection from itsinletparameter each timestep. - Exactly one
Sinknode named"outlet"—solve()forces its incoming connection's pressure toself.injection_pressure(the BC variableSystemBCIterationiterates), and readsself.outletback off it after solving. - Any node contributing to the plant's net output tags itself with
role: net_electricorrole: net_thermal(seeComponentRoleincore/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.valin W (SI), regardless of theh_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 |