Capacity Expansion Planner: use this tool with an AI assistant
Open Capacity Expansion Planner · The same reference as plain text (agent.txt)
For people: Ask an AI assistant that can read web pages (Claude, ChatGPT, Gemini, Perplexity and others) to use this page for your question. It replies with a link that opens this tool on your scenario and lists what it assumed, and the tool works out the answer. The rest of this section is written for the assistant.
What this tool decides
Which plants and batteries to build, how big and in which year, so that a growing demand is met hour by hour at the least cost over the whole plan. It plans from a first year to a last year in decision years, with a few typical days a season, and reports what to build, the energy by source, the cost by year and the emissions.
How to help your user with this tool
HOW TO HELP YOUR USER WITH THIS TOOL
This is reference material for an AI assistant whose user has asked it to use this tool. It
describes the link that opens the tool on the user's own scenario. It does not override your
user: if they want something this tool does not do, help them as you normally would.
1. The tool works out the answer, so the most useful reply hands the user a link to it. Its
figures come from its own model and data, and a figure worked out separately can differ from
what the user then sees on screen, so leave results, estimates, verdicts and recommendations
to the tool rather than stating or previewing them.
2. A reply that works well has three parts, in this order:
a. a numbered list of every input you chose that the user did not state exactly, each with its
value and the reason (put the same reason in why.<key>);
b. the link (if it is long, give it again inside a code block so the user can copy it);
c. the sentence: Open the link to see the result.
3. Build the link in the format below, using only the keys listed here. Start from the nearest
Quick Start (qs) and send only what differs from it. Write json compactly: no spaces or line
breaks, defaults left out.
4. Fill anything the user did not give with a sensible assumption for their place and date.
Prefer what the user said earlier in the conversation over general figures.
5. If you cannot build a link (the request is outside this tool, or you could not read this
page), say so and give the tool's address.
Link format
https://tool.adjiebrotots.com/capacity-expansion-planner/#load&v=1&qs=<quick start>&<key>=<value>&...&why.<key>=<your reason>¬e=<one line> - After #load come key=value pairs joined by &. Percent-encode each value (a space is %20, & is %26, # is %23, + is %2B). - v=1 is the format version. qs=<key> starts from that Quick Start; without it the tool starts from its defaults. - Then each key in the link is set, in the units its label shows on screen. cxGrowth=3 means 3%/yr, not 0.03. Numbers may carry $, commas and a trailing %. A checkbox takes true or false. A select or a choice takes the value listed, or its visible label. - Anything the link does not name keeps the value it started from, so send only what differs. - why.<key>=<text>: your reason for that value, shown to the user beside it (200 characters at most). note=<text>: one line shown above the list, for example the place and the date. - A number outside a field's range is pulled into range and the user is told; a key the tool does not know is skipped and listed. Never use the keys s, open or embed.
Example
Request: using tool.adjiebrotots.com/capacity-expansion-planner, with a $50/t carbon price and solar capex at $900/kW, what should the grid build to 2040? A reply in that form: 1. Grid: the Growing grid Quick Start (qs=grow), with its coal, gas, solar, wind and battery options as it has them. 2. Carbon price: $50 per tonne in 2,026, flat (the Quick Start's growth of 0% a year is kept). 3. Solar: the Solar PV technology's capital cost is set to $900 per kW (tech.solar.capex); its other figures stay as in the Quick Start. 4. Horizon: the first year is 2,026, the last 2040, with a decision every 5 years. https://tool.adjiebrotots.com/capacity-expansion-planner/#load&v=1&qs=grow&run=0&cxCarbon=50&why.cxCarbon=The%20user%27s%20carbon%20price,%20in%20$%20per%20tonne%20of%20CO2,%20from%20the%20first%20year&tech.solar.capex=900&why.tech.solar.capex=The%20user%27s%20solar%20capital%20cost,%20in%20$%20per%20kW&cxEnd=2040&why.cxEnd=The%20user%20wants%20the%20plan%20to%20run%20to%202040¬e=Growing%20grid,%20$50/t%20carbon%20price,%20solar%20at%20$900/kW,%20planned%20to%202040 ``` https://tool.adjiebrotots.com/capacity-expansion-planner/#load&v=1&qs=grow&run=0&cxCarbon=50&why.cxCarbon=The%20user%27s%20carbon%20price,%20in%20$%20per%20tonne%20of%20CO2,%20from%20the%20first%20year&tech.solar.capex=900&why.tech.solar.capex=The%20user%27s%20solar%20capital%20cost,%20in%20$%20per%20kW&cxEnd=2040&why.cxEnd=The%20user%20wants%20the%20plan%20to%20run%20to%202040¬e=Growing%20grid,%20$50/t%20carbon%20price,%20solar%20at%20$900/kW,%20planned%20to%202040 ``` Open the link to see the result.
Quick starts (qs)
There are four plans. grow is a summer-peaking grid of 1,000 MW growing 3% a year, its coal closing in 2036, with gas, solar, wind and batteries to build. nz is the same grid with a carbon price of 40 that rises 5% a year and no CO2 from 2041, with pumped hydro joining the options. coal is a winter-peaking grid of 4,000 MW closing two coal stations, in 2031 and 2041, with gas in 400 MW units. island is a tropical island of 120 MW on diesel, growing 6% a year, with solar, batteries and geothermal to build. Start from the one closest to the user's grid, then change its technologies by name with the tech.<name>.<param> keys. Their names and figures are under QUICK START FIGURES, so read the technology the user means from there. A Quick Start also puts the options (the years, the demand, the climate, the carbon price, cxCur and the rest) back on its own values, so name each option the user wants different. Without qs the tool starts from grow. A grid that differs structurally, with its own list of technologies, goes in json. qs takes one of: grow, nz, coal, island. What each Quick Start sets is listed under QUICK START FIGURES at the end.
Fields (key: label on the page)
Most important: cxPeak, cxGrowth, cxCarbon, cxStart, cxEnd, cxClimate, cxNetZero, cxNzYear. [Demand] cxCur: Currency Symbol One of: $ Dollar, € Euro, £ Pound, ¥ Yen / Yuan, ₹ Rupee (India), Rs Rupee (Pakistan, Sri Lanka), Rp Rupiah, RM Ringgit, ₱ Peso (Philippines), ฿ Baht, ₫ Dong, ₩ Won, CHF Swiss Franc, Dh Dirham (UAE), kr Krona / Krone, zł Złoty, ₺ Lira, ₽ Ruble, ₪ Shekel, R Rand, R$ Real, ₦ Naira, ₿ Bitcoin. Default $. The currency symbol shown beside every cost. It only relabels the figures and never converts them, so give every cost in one currency and set its symbol here (Rp, the euro sign and so on). Every Quick Start puts it back on $, and its technology costs are in US dollars. [Demand: Demand] cxPeak: Peak demand now (most important) Number (MW after it). 1 to 1,000,000. Default 1000. The highest hour of demand in the first year, in MW. Typical 100 to 50,000. Tip on the page: The highest hour of demand in the first year. The load profile and the seasons scale every other hour from it. cxGrowth: Demand growth (most important) Slider (%/yr). -2 to 10. Default 3. How fast that peak grows each year, in % a year (negative if it shrinks). Tip on the page: How much the peak and every hour of demand grow a year, compounded from the first year. [Demand: Load profile] cxClimate: Climate (most important) One of: sum (Summer peak, Dec to Feb), sum-n (Summer peak, Jun to Aug), win (Winter peak, Jun to Aug), win-n (Winter peak, Dec to Feb), trop (Tropical, wet Nov to Apr), trop-n (Tropical, wet May to Oct). Default sum. The seasons a year is sampled by, and which hemisphere's: sum and sum-n peak in summer, win and win-n in winter, trop and trop-n are tropical. Without -n the seasons are the southern hemisphere's (summer is December to February), with -n the northern (summer is June to August). Choose by where the user is and when their demand peaks. Tip on the page: Summer peak, Dec to Feb: four seasons, demand highest in summer, long sunny days then and short low ones in winter, and windier winters. Southern hemisphere, e.g. Australia, Argentina. [Demand: Planning years] cxStart: First year (most important) Number. 2,000 to 2,100, step 1. Default 2026. The first year of the plan, a whole year (2000 to 2100). Costs and the carbon price are those of this year. Tip on the page: Also the price year: every cost you enter and every result is at this year’s prices, and every later year’s cost is discounted back to it. cxEnd: Last year (most important) Number. 2,000 to 2,150, step 1. Default 2050. The last year of the plan (2000 to 2150), at least the first year. Decision years run from the first year in steps of cxStep, and each stands for the years up to the next. A longer plan with smaller steps takes longer to solve. Tip on the page: The plan runs to the end of this year. Costs after it are not counted, so a plant built late pays only for its years inside the plan. cxStep: Years between decisions One of: 1 yr, 2 yrs, 3 yrs, 5 yrs, 10 yrs. Default 5. Years between investment decisions: 1, 2, 3, 5 or 10. The Quick Starts use 5. Tip on the page: How often the plan can build. Each decision year stands for the years up to the next one, at its own demand. [Supply] cxDetail: Detail One of: simple (Simple), detailed (Detailed). Default simple. simple or detailed. Detailed shows more of each technology's card (fixed O&M, lifetime, cost change, earliest year, build limit, unit size, availability). Send detailed whenever a link changes one of those with tech.<name>.<param>, so the user can see it. [Policy: Reliability] cxShed: Allow load shedding Checkbox: true or false. Default true. On (the default): demand the plants cannot serve is cut at the value of lost load instead of making the plan infeasible. Off: such a plan is reported as a problem and not solved. Tip on the page: Demand may go unserved at the value of lost load when that is cheaper than building for it. Off, every MW of demand must be met. cxVoll: Value of lost load (VoLL) Number ($ before it, /MWh after it). 500 to 100,000, step 100. Default 20000. The value of lost load: what a MWh not served costs, per MWh in the currency of cxCur. It caps the price of power, since shedding is the last resort. Used only while cxShed is on. Typical 5,000 to 30,000 (the default is 20,000). Leave it out unless the user gives one. Tip on the page: What a MWh not served costs the people who lose it, at 2026 prices. Capacity that is used fewer hours than its cost over this is not built. [Policy: Emissions] cxCarbon: Carbon price (most important) Number ($ before it, /t after it). 0 to 2,000. Default 0. The carbon price in the first year, per tonne of CO2 in the currency of cxCur. 0 means none. A plant pays it on every tonne it emits. Tip on the page: Paid on every tonne of CO2 a plant emits, on top of its running cost: the price in 2026, at 2026 prices, before its growth. cxCarbonGrow: Carbon price growth Slider (%/yr). 0 to 20. Default 0. How fast the carbon price rises each year, in % a year, compounded from the first year. 0 keeps it flat. cxNetZero: Net-zero year (most important) Checkbox: true or false. Default false. On: from the year in cxNzYear on, no plant that emits CO2 may run. Off (the default): no such rule. Turn it on only when the user states a net-zero or no-emissions year. Tip on the page: From this decision year on, no plant may emit CO2. Storage and clean plants have to meet the demand. cxNzYear: No CO2 from (most important) Number. 2,000 to 2,150, step 1. Default 2045. The decision year from which no plant may emit (2000 to 2150). Used only while cxNetZero is on. [Assumptions] cxRateMode: Discount rate One of: real (Real), nominal (Nominal). Default real. How the discount rate is given. real: cxRate is used and cxInflation is not. nominal: cxNomRate is used. Leave it on real unless the user gives a nominal rate. Tip on the page: Real: type the real rate, above inflation. Nominal: type a nominal rate and inflation, and the real rate is worked out from them. Either way every cost stays at the first year’s prices. cxRate: Real discount rate Slider (%/yr). 0 to 15. Default 7. The real discount rate, in % a year (0 to 15). Used when cxRateMode is real. Costs from later years are discounted to the first year at it. Tip on the page: A real rate, above inflation, as every cost is at 2026 prices. It sets the capital annuity, and a cost in 2036 counts 0.51 of the same cost in 2026. cxNomRate: Nominal discount rate Slider (%/yr). 0 to 25. Default 10.2. The nominal discount rate, in % a year (0 to 25). Used when cxRateMode is nominal, together with cxInflation. Tip on the page: The rate money is borrowed or expected to earn at, inflation included. cxInflation: Inflation Slider (%/yr). 0 to 15. Default 3. Inflation, in % a year (0 to 15). Used with a nominal rate. Tip on the page: How fast prices rise each year. The plan stays at the first year’s prices, so inflation only turns the nominal rate into a real one. [Assumptions: Typical days] cxStress: Still, overcast peak day Checkbox: true or false. Default false. On adds a still, overcast peak day to each period, so the plan also has to serve demand with almost no sun or wind. Leave it out unless the user asks for a dunkelflaute or a worst case. Tip on the page: Adds a day at the year’s peak with a quarter of the sun and a tenth of the wind, standing for two days a year, so the plan holds firm capacity for it. [Assumptions: Solver] cxTime: Time limit One of: 10 s, 30 s, 60 s, 300 (5 min). Default 60. The solver's time limit, in seconds (10, 30, 60 or 300). Leave it out. cxGap: Optimality gap One of: 0.0001 (0.01%), 0.001 (0.1%), 0.01 (1%). Default 0.001. How close to the best possible cost the solver must prove its answer when plants come in whole units. 0.0001 is 0.01%, 0.001 is 0.1%, 0.01 is 1%. Leave it out. Tip on the page: With unit sizes the plan is a mixed-integer problem. HiGHS stops once its plan is proven within this share of the best possible cost.
Compact lists
- `tech.<name>.<param>=<value>` - `loadShape=<shape>` `tech.<name>.<param>` changes one value of one technology, found by the name the tool shows for it (QUICK START FIGURES lists them). Names ignore case, spaces and punctuation, so Solar PV, solar pv and SolarPV are one name; write the space as %20 or leave it out. The parameter is the text after the last dot. The ten technologies the + Add menu offers also answer to their short id: solar, wind, ccgt, ocgt, coal, nuclear, geo, diesel, battery and phes, for the technology that carries the menu's name (Solar PV, Wind, Gas (CCGT), Gas (OCGT), Coal, Nuclear, Geothermal, Diesel engines, Battery, Pumped hydro). When the plan has no technology of that name, the id adds it from the menu with its typical costs, then applies the value; use that to offer a technology the Quick Start lacks, for example tech.nuclear.build=1 or tech.nuclear.capex=6000. A name that no technology has and that is not one of the ten ids, or that two technologies share, or a parameter the technology does not take is reported and skipped. A number outside the parameter's range is pulled into it and reported. Send one key per parameter, and a why.<key> beside each. Parameters, in the units the tool saves them in (the same as in json). A cost is in the currency of cxCur. For every technology: exist (MW in service before the first year, 0 to 1,000,000), retire (the year that existing capacity is gone by, 1900 to 2200; 0 means it stays to the end), build (1 or 0: whether more can be built), capex (cost per kW of new capacity, in the first year, 0 to 100,000), fom (fixed O&M per kW a year, existing and new, 0 to 10,000), vom (running cost per MWh, fuel and variable O&M, 0 to 100,000), life (years a new plant runs, 1 to 100), learn (change in capex each year as a fraction, -0.2 to 0.2, so -0.02 is 2% cheaper every year), from (the earliest year it can be built, 1900 to 2200; 0 means the first year), max (most MW in service at once, existing included, 0 to 1,000,000; 0 means no limit) and unit (MW per unit, so it is built in whole units, 0 to 100,000; 0 means any size). Solar and wind also take cf (capacity factor, the year's output over rating times 8,760 hours, as a fraction 0.01 to 0.95, so 0.22 is 22%). Firm plants (gas, coal, nuclear, geothermal, diesel) also take avail (the share of the rating they can give in any hour, 0.01 to 1) and co2 (tonnes of CO2 per MWh, 0 to 3). Storage (battery, pumped hydro) also takes hours (hours at full power, 0.25 to 1000) and rte (round-trip efficiency as a fraction, 0.1 to 1, so 0.87 is 87%). A technology's kind, name and its solar or wind profile are not patches: send the plan in json. `loadShape=<shape>` sets the demand through the day: sys (system day), res (residential), com (commercial), ind (industrial), respv (residential with rooftop solar), resev (residential with electric cars) or flat. It replaces whatever shape and edits the plan had. Leave it out to keep the Quick Start's own. `run=0` opens the plan without solving it. Always add it to a link for this tool, so the reader presses Run plan to see the result and the answer comes from the tool when they ask for it, never straight from the link. Without it the plan is solved as soon as the link opens.
Json
`json=<plan>` replaces the technologies and the demand shape with ones of the user's own: the form the tool saves, which is how every Quick Start is written. Use it only for a grid whose technologies differ structurally from the four Quick Starts; to change a value on one of them, patch it. A qs before it is replaced, but still sets the demand, years, climate and carbon price, so pick the nearest one or send those fields yourself. Write it compactly (no spaces or line breaks) and leave out every value that is at its default.
{"v":2,"tech":[<technology>,<technology>,...],"load":{"base":"<shape>"}}
Each technology is {"name":"<name>","kind":"<kind>", ...}. The kind is pv (solar), wind, firm (anything dispatchable that burns or flows: gas, coal, nuclear, geothermal, diesel) or storage written as store. A name is only needed to tell technologies apart; the names tech.<name>.<param> and the tool use are these. An id is optional: a technology without a whole-number id, or with a repeated one, is given one.
- The other keys are the parameters listed under COMPACT LISTS, in the same units. A technology costs nothing by default and can be built (build 1), so give capex, fom and vom. Existing capacity is exist, with retire for the year it closes and build 0 if no more may be built. The defaults are: life 25, cf 0.25, avail 1, co2 0, hours 4, rte 0.85, kind firm.
- load is optional, with base one of sys, res, com, ind, respv, resev or flat (sys when left out).
- The plan keeps up to 24 technologies. A number out of range is pulled into range and reported, an unknown key is skipped, and a plan that cannot be read at all, or has no technology, leaves the tool on its Quick Start.
A small grid with an old gas plant, solar and a battery, over two decision years (send cxPeak, cxStart, cxEnd and cxStep with it):
{"v":2,"tech":[{"name":"Old gas","kind":"firm","exist":80,"build":0,"vom":70,"co2":0.5},{"name":"Solar","kind":"pv","capex":900,"fom":15,"life":30,"cf":0.22},{"name":"Battery","kind":"store","capex":1200,"fom":25,"life":15,"hours":4,"rte":0.87}]}
Quick start figures (what each qs sets, as a link would carry them)
A heading line holds what all the Quick Starts under it share; each Quick Start's own line holds the rest. grow: Growing grid. Plan: demand shape system day; Coal: firm, existing 700 MW, retires 2036, no new build; Gas (CCGT): firm, existing 300 MW, can build at 1200 per kW; Gas (OCGT): firm, can build at 800 per kW; Solar PV: solar, can build at 1000 per kW; Wind: wind, can build at 1600 per kW, at most 1500 MW; Battery: storage, can build at 1200 per kW. nz: Net zero. cxCarbon=40 cxCarbonGrow=5 cxNetZero=true cxNzYear=2041 Plan: demand shape system day; Coal: firm, existing 700 MW, retires 2036, no new build; Gas (CCGT): firm, existing 300 MW, can build at 1200 per kW; Gas (OCGT): firm, can build at 800 per kW; Solar PV: solar, can build at 1000 per kW; Wind: wind, can build at 1600 per kW, at most 1500 MW; Battery: storage, can build at 1200 per kW; Pumped hydro: storage, can build at 2500 per kW from 2031. coal: Coal exit. cxPeak=4000 cxGrowth=1 cxClimate=win cxEnd=2045 cxCarbon=25 Plan: demand shape system day; Coal, older station: firm, existing 2000 MW, retires 2031, no new build; Coal, newer station: firm, existing 1500 MW, retires 2041, no new build; Gas (CCGT): firm, existing 800 MW, can build at 1200 per kW, in 400 MW units; Gas (OCGT): firm, existing 400 MW, can build at 800 per kW; Wind: wind, existing 600 MW, can build at 1600 per kW, at most 4000 MW; Solar PV: solar, can build at 1000 per kW; Battery: storage, can build at 1200 per kW. island: Island. cxPeak=120 cxGrowth=6 cxClimate=trop cxEnd=2045 Plan: demand shape residential; Diesel engines: firm, existing 150 MW, can build at 900 per kW; Solar PV: solar, can build at 1000 per kW; Battery: storage, can build at 1200 per kW; Geothermal: firm, can build at 4500 per kW from 2031, at most 60 MW, in 20 MW units. Generated by _ref/agent-doc.mjs from the page and its agent-notes.md.