documentation changes March 2025

[ahawkes]

Description

Changes to documentation - the model description changed to address some issues and improve clarity

Fixes # (issue)

Type of change

• [ x] Documentation (improve or add documentation)

Key checklist

• [x ] All tests pass: $ cargo test
• [x ] The documentation builds and looks OK: $ cargo doc

Further checks

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.03%. Comparing base (043e63e) to head (12efa24).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #466   +/-   ##
=======================================
  Coverage   95.03%   95.03%           
=======================================
  Files          36       36           
  Lines        4893     4893           
  Branches     4893     4893           
=======================================
  Hits         4650     4650           
  Misses        123      123           
  Partials      120      120           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tsmbland]

Looks good! Clearly still lots of unknowns, but this has a lot to get us started

[tsmbland]

I think an example would be helpful here

[ahawkes]

Do you mean an example in a simple model that we can try out? Or an example in written text here? The latter would be something like: e.g. there are two technologies that can produce heat, a gas boiler and a biomass-fuelled boiler. In the base year the gas boiler serves all demand. There is no other technology consuming biomass, so there is no price for biomass in the base year dispatch solution. Therefore, for the next milestone year, when trying to calculate objectives we do not have a price for biomass, and cannot proceed. So, we need to consider the range of processes that can produce biomass, and figure out the marginal cost of the best one (and this is the cost of biomass for the desired objective calculation).

This is complicated by the fact that there might be multiple processes needed to produce a specific commodity (ie.. the full commodity supply chain might be missing).

[alexdewar]

Hi @ahawkes,

I've taken the liberty of reviewing this because I thought I should give it a read before the next engagement. Besides @tsmbland's suggestions I've spotted a few typos etc. You should just be able to commit most of them directly. Otherwise all good!

Thanks for keeping this updated. It'll be a handy resource for the next stages of development.

[tsmbland]

@ahawkes Could you please provide an equation for marginal cost?

[ahawkes]

Marginal cost is operational costs only (i.e. no contribution from capex and fixed opex). So it's cost of inputs, cost (if any) of outputs, and variable operating cost.

[alexdewar]

Just to double-check: the costs of inputs/outputs are commodity costs (as in, the things in commodity_costs.csv) rather than commodity prices... right?

[tsmbland]

Just to double-check: the costs of inputs/outputs are commodity costs (as in, the things in commodity_costs.csv) rather than commodity prices... right?

I assume we'd have to include both? i.e. for each input commodity (commodity_x), the contribution to the marginal cost (of commodity_y) is:

input_flow_of_commodity_x * (price_of_commodity_x + cost_of_commodity_x) / output_flow_of_commodity_y

Where cost can be positive (tax) or negative (subsidy), but price is always positive

@ahawkes Is that correct?

[alexdewar]

It would also be useful to have a formula for decision values. It's not clear how utilisation, availability and commodity price should be combined here.

[alexdewar]

Just spoke to @tsmbland and he said decision values should be the same as objective values for the single-objective case? If so, we don't have to worry about it until we add support for additional decision rules.

[ahawkes]

Actually I think this description is wrong, because if the commodity is present in the solution then we already have a price for it. Instead I think we should use an assumption of max utilisation for now, and create an issue for this (because it would be better to use the utilisation corresponding to the availability profile of the potential downstream demand - but this is a very complicated thing to do!)

[ahawkes]

Also it may be possible to get prices for commodities not present in the solution by adding the processes to the problem with capacity constrained to zero. Then Highs might generate related prices - we would need to try this.

[alexdewar]

Also it may be possible to get prices for commodities not present in the solution by adding the processes to the problem with capacity constrained to zero. Then Highs might generate related prices - we would need to try this.

We can certainly give this a go!

Does the below make sense (for now)? I can open an issue about getting a better value for utilisation here.

Suggested change

	We also calculate the prices of commodities that are not present in the dispatch
	solution, but could exist in the solution for the next milestone year. These are calculated
	directly from input data. This is done by calculating the marginal price of the process producing
	the commodity in question with the best decision value, where decision values are calculated
	using the utilisation of the next most expensive (marginal cost) asset in the dispatch stack,
	adjusted for availability differences, and commodity prices from the price discovery at step 2(A).
	We also calculate the prices of commodities that are not present in the dispatch
	solution, but could exist in the solution for the next milestone year. These are calculated
	directly from input data. This is done by calculating the marginal price of the process producing
	the commodity in question with the best decision value, assuming maximum utilisation.