From 4433688d8d7ed0563efc7fee0c5dc54334c30def Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Thu, 3 Sep 2026 10:49:17 +0100 Subject: [PATCH 1/2] Update documentation for total_capacity_limit --- docs/model/investment.md | 50 +++++++++++++++---- .../input/process_investment_constraints.yaml | 6 ++- 2 files changed, 43 insertions(+), 13 deletions(-) diff --git a/docs/model/investment.md b/docs/model/investment.md index f784aab08..e54490911 100644 --- a/docs/model/investment.md +++ b/docs/model/investment.md @@ -66,7 +66,7 @@ Each commodity market may be served by multiple agents, each responsible for a d (or *portion*) of the total demand. An agent's portion determines: - The fraction of the total demand that the agent is responsible for meeting. -- The scaling applied to any `addition_limit` investment constraints +- The scaling applied to any `addition_limit` and `total_capacity_limit` investment constraints (see [Investment Constraints](#investment-constraints)). Agent portions for each commodity and milestone year are defined in the agent input files. @@ -145,21 +145,49 @@ tranches. ### Investment constraints -Processes may have an `addition_limit` (see -[`process_investment_constraints.csv`][process-investment-constraints-csv]) specifying the -maximum new capacity that can be built per year. The installable capacity limit for a given MSY is: +Processes may be subject to investment constraints defined in +[`process_investment_constraints.csv`][process-investment-constraints-csv]: an `addition_limit` +constraining new-build capacity, and a `total_capacity_limit` constraining total installed +capacity. + +In multi-agent simulations, both limits are scaled by \\( \mathrm{AgentPortion} \\), the fraction +of the commodity market for which an agent is responsible, to give a limit for each agent. One +agent falling short of its own limits does **not** allow others to exceed theirs. Therefore, the +overall limits can only ever be reached if *all* agents max out their own individual limits. + +#### Addition limits + +The `addition_limit` specifies the maximum new capacity that can be built *per year*, and applies +only to **candidate** (new-build) assets. The installable capacity limit for a given process +(\\( p \\)), agent (\\( g \\)), region (\\( r \\)), commodity (\\( c \\)) and milestone year is: \\[ - \mathrm{MaxInstallableCapacity} = \mathrm{AdditionLimit} \times \Delta_{\mathrm{MSY}} - \times \mathrm{AgentPortion} + \mathrm{MaxInstallableCapacity}\_{p,r,y,g} = \mathrm{AdditionLimit}\_{p,r,y} + \cdot \Delta\_{\mathrm{MSY}} \cdot \mathrm{AgentPortion}\_{c,r,y,g} \\] -where \\( \Delta_{\mathrm{MSY}} \\) is the number of years since the previous MSY and -\\( \mathrm{AgentPortion} \\) is the fraction of the commodity market for which this agent is -responsible. +where \\( \Delta_{\mathrm{MSY}} \\) is the number of years since the previous milestone year. + +Each selection of a candidate asset tranche counts towards the \\(\mathrm{MaxInstallableCapacity} \\) +of that process. A candidate asset tranche is excluded from consideration if its capacity would +exceed the remaining limit. + +#### Total capacity limits + +The `total_capacity_limit` specifies a hard upper limit on the **total capacity** of a process that +may exist at any given time. This includes both existing assets which are considered for retention, +and candidate assets which are considered for commissioning. The total capacity limit for a given +process, agent, region and milestone year is: + +\\[ + \mathrm{MaxTotalCapacity}\_{p,r,y,g} = \mathrm{TotalCapacityLimit}\_{p,r,y} + \cdot \mathrm{AgentPortion}\_{c,r,y,g} +\\] -If the remaining installable capacity is exhausted, the candidate is excluded from further -consideration. +Each selection of a candidate asset tranche, or retention of an existing asset tranche, counts +towards the \\(\mathrm{MaxTotalCapacity} \\) of their respective process. Any tranche (whether for +a candidate asset or an existing asset) is excluded from consideration if it would exceed the +remaining limit. ## Mini Dispatch Optimisation diff --git a/schemas/input/process_investment_constraints.yaml b/schemas/input/process_investment_constraints.yaml index c2c9775f7..208dca6ee 100644 --- a/schemas/input/process_investment_constraints.yaml +++ b/schemas/input/process_investment_constraints.yaml @@ -40,5 +40,7 @@ fields: notes: This is currently unused. - name: total_capacity_limit type: number - description: The hard upper limit on the amount agents can invest in the process - notes: This is currently unused. + description: A hard upper limit on the total amount of installed capacity that can exist at any given time + notes: | + The total capacity limit is allocated evenly between all agents using their proportion of the + process's primary commodity demand. From 3726dba6e1a7c5a85d81fdfbd5fecc9b2e0f44ee Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Thu, 3 Sep 2026 11:29:10 +0100 Subject: [PATCH 2/2] Copilot suggestions --- docs/model/investment.md | 5 +++-- schemas/input/process_investment_constraints.yaml | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/model/investment.md b/docs/model/investment.md index e54490911..88d0e7318 100644 --- a/docs/model/investment.md +++ b/docs/model/investment.md @@ -159,7 +159,8 @@ overall limits can only ever be reached if *all* agents max out their own indivi The `addition_limit` specifies the maximum new capacity that can be built *per year*, and applies only to **candidate** (new-build) assets. The installable capacity limit for a given process -(\\( p \\)), agent (\\( g \\)), region (\\( r \\)), commodity (\\( c \\)) and milestone year is: +(\\( p \\)), agent (\\( g \\)), region (\\( r \\)), commodity (\\( c \\)) and milestone year +(\\( y \\)) is: \\[ \mathrm{MaxInstallableCapacity}\_{p,r,y,g} = \mathrm{AdditionLimit}\_{p,r,y} @@ -177,7 +178,7 @@ exceed the remaining limit. The `total_capacity_limit` specifies a hard upper limit on the **total capacity** of a process that may exist at any given time. This includes both existing assets which are considered for retention, and candidate assets which are considered for commissioning. The total capacity limit for a given -process, agent, region and milestone year is: +process, agent, region, commodity and milestone year is: \\[ \mathrm{MaxTotalCapacity}\_{p,r,y,g} = \mathrm{TotalCapacityLimit}\_{p,r,y} diff --git a/schemas/input/process_investment_constraints.yaml b/schemas/input/process_investment_constraints.yaml index 208dca6ee..1f185334e 100644 --- a/schemas/input/process_investment_constraints.yaml +++ b/schemas/input/process_investment_constraints.yaml @@ -24,7 +24,7 @@ fields: type: number description: Yearly constraint on the amount agents can invest in the process notes: | - The addition limit is allocated evenly between all agents using their proportion of the + The addition limit is allocated between all agents in proportion to their share of the process's primary commodity demand. - name: capacity_growth_limit type: number @@ -42,5 +42,5 @@ fields: type: number description: A hard upper limit on the total amount of installed capacity that can exist at any given time notes: | - The total capacity limit is allocated evenly between all agents using their proportion of the + The total capacity limit is allocated between all agents in proportion to their share of the process's primary commodity demand.