Derivatives & topology

In simple terms

A project turns hydrogen into one or more products (derivatives) — ammonia, e-methanol, e-SAF, e-natural-gas, green iron/steel, or compressed hydrogen for export. Each product automatically pulls in the extra equipment it needs (ammonia needs an air-separation unit + Haber-Bosch; methanol needs a CO₂ source, etc.). The topology is the value-chain graph that wires these together, and the Derivatives room shows it.

Why it exists

A developer picks what to make, not which components to wire — the plant’s shape should follow from the product. Auto-deriving the components keeps the model correct (you can’t forget the ASU on an ammonia plant) and keeps the UI a guided editor, not a blank-canvas node graph.

Where it lives

• Room: frontend/src/rooms/derivatives/DerivativesRoom.tsx (the topology graph).
• Engine: backend/core/engine/topology.py (build + validate from config); derivative physics in core/components/derivatives/.

The taxonomy

NH3 | eMeOH | eSAF | eNG | green_iron | green_steel | H2_export. A project holds a list of derivatives; a single molecule is a list of length 1 — single-vs-multi is a view over the same data, not a different mode.

Intrinsic components (auto-derived from kind)

Assembled by topology.py, never user-wired:

Product	Adds
NH₃	ASU (N₂) + Haber-Bosch
eMeOH	CO₂ source + methanol synthesis
eSAF	per-project pathway — FT (CO₂+purification+RWGS+FT+upgrading) or MtJ (CO₂+methanol-synth+methanol-to-jet)
eNG	CO₂ source + methanation
green_iron	H₂-DRI (+ ore); green_steel = green_iron + EAF (a superset)
H2_export	H₂ injection compressor (1:1; no CO₂/N₂/ore)
shared upstream (all)	renewables → BESS → electrolyser → desalination

The CO₂ source mode (shared by eMeOH/eSAF/eNG) is selectable: capture | dac | feedstock.

H₂ allocation & cost allocation

• Prefeasibility splits the H₂ by the capacities (since 2026-11-09): each product’s share is its unit’s need at full output over all the units’ needs — a result, never typed. Derivatives draw H₂ in parallel; short of hydrogen every unit runs at the same fraction of its maximum, and hydrogen beyond what the units take is not made — it idles the electrolyser, so that electricity is curtailed (add an H2_export product, with a capacity, to use it). Feasibility is demand-driven instead. The rule: How prefeasibility works.
• Cost allocation (multi): shared upstream by the realized H₂ share; the CO₂ chain by CO₂-demand share; derivative-specific costs assigned directly → a per-product LCO.

How it works, step by step

1. You add/remove derivatives and set their capacities in the cockpit’s value-chain editor (and choose the eSAF pathway where relevant); the capacities decide the split of the hydrogen.
2. topology.py assembles the graph — shared upstream + each product’s intrinsic components — and validates it.
3. The engine solves it; the Derivatives room draws the resulting chain, and the cockpit’s FlowDiagram lights the binding stage.

Failure & edge cases

• Unknown derivative field on create → 422 naming the key (not a 500).
• More hydrogen than the units take → the surplus is not made and its electricity curtailed, surfaced in the Production panel (hydrogen not made) and the energy balance (raise a capacity / add H₂-export).
• A product without a capacity → the solve is refused (422) with one sentence naming the product to fix.
• Mixed NH₃ + others is supported — NH₃ co-solves inside the multi engine (its ASU electricity folded into the downstream spec); an NH₃-only project keeps the single-chain engine for LCOA/LCOH.

How to modify this safely

• New product = a component in core/components/derivatives/ + a topology.py branch that declares its intrinsic components. Don’t wire components in the UI.
• Keep the auto-derivation rule: the plant shape follows from kind.

Related topics

• Prefeasibility cockpit
• Feature index
• System architecture