Skip to content

Refactoring to allow multiple asset selection algorithms - #1577

Merged
tsmbland merged 12 commits into
mainfrom
multi_investment_algorithms_prep
Nov 13, 2026
Merged

tsmbland merged 12 commits into
mainfrom
multi_investment_algorithms_prep

Conversation

@tsmbland

@tsmbland tsmbland commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

Description

We want to support multiple different asset selection algorithms. The idea is that we will have different agent "types" which select assets in different ways (this is different to objectives which are used within each algorithm as a way of assessing asset options).

This is just a refactor of the current algorithm to make it possible to easily slot in new algorithms, introducing the concept of an agent type. I've called the current type "competitive", as I believe the algorithm was designed to try to simulate a competitive market. This is in contrast to the "portfolio" type introduced in #1574, in which agents are meant to be a single decision maker in change of a portfolio of assets.

The design decision is to make select_assets the front-end for each algorithm, with any implementation details up to the algorithm (these should be private, although currently some need to be public for the benchmark, unfortunately). This includes making the algorithm in charge of its own debug files. To allow this I had to modify the output module to accept custom_writers.

Fixes # (issue)

Type of change

  • Bug fix (non-breaking change to fix an issue)
  • New feature (non-breaking change to add functionality)
  • Refactoring (non-breaking, non-functional change to improve maintainability)
  • Optimization (non-breaking change to speed up the code)
  • Breaking change (whatever its nature)
  • Documentation (improve or add documentation)

Key checklist

  • All tests pass: $ cargo test
  • The documentation builds and looks OK: $ cargo doc
  • Update release notes for the latest release if this PR adds a new feature or fixes a bug
    present in the previous release

Further checks

  • Code is commented, particularly in hard-to-understand areas
  • Tests added that prove fix is effective or that feature works

@tsmbland tsmbland changed the title Multi investment algorithms prep Refactoring to allow multiple investment algorithms Nov 4, 2026
@tsmbland tsmbland changed the title Refactoring to allow multiple investment algorithms Refactoring to allow multiple asset selection algorithms Nov 4, 2026
@tsmbland
tsmbland force-pushed the multi_investment_algorithms_prep branch from 7e8fd94 to 40e4737 Compare November 9, 2026 15:16
@tsmbland
tsmbland marked this pull request as ready for review November 9, 2026 15:45
@tsmbland
tsmbland requested a balanced review from Copilot November 9, 2026 15:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are identified for the agent-selection refactor.

No open issues 🎉

What changed in this PR

Refactors asset selection to support multiple agent algorithms, isolating the existing behaviour as competitive and preparing for the portfolio algorithm described in #1574.

Changes:

  • Adds an optional agent_type input, defaulting to competitive, and routes market selection accordingly.
  • Moves competitive selection, appraisal and debug output into a dedicated module.
  • Adds reusable custom debug writers and updates tests, fixtures and benchmark imports.
File Description
tests/​data/​simple/​debug_asset_selection_competitive.csv Adds expected competitive-selection debug output.
src/​simulation/​market.rs Routes asset selection by agent type.
src/​simulation/​investment/​competitive/​optimisation.rs Updates imports for the relocated optimisation code.
src/​simulation/​investment/​competitive/​metrics.rs Relocates appraisal metrics and narrows visibility.
src/​simulation/​investment/​competitive/​debug.rs Owns competitive debug CSV output and its tests.
src/​simulation/​investment/​competitive/​costs.rs Houses competitive appraisal cost calculations.
src/​simulation/​investment/​competitive/​constraints.rs Updates imports for relocated appraisal constraints.
src/​simulation/​investment/​competitive/​coefficients.rs Adjusts coefficient interfaces and helper visibility.
src/​simulation/​investment/​competitive.rs Encapsulates competitive selection and related tests.
src/​simulation/​investment.rs Retains shared utilities and exposes the competitive module.
src/​output.rs Adds lazily created custom debug writers and tests.
src/​input/​agent/​search_space.rs Updates test agents with the default agent type.
src/​input/​agent.rs Parses optional agent types and tests defaults and validation.
src/​fixture.rs Updates agent fixtures and removes the shared appraisal fixture.
src/​agent.rs Defines AgentType and adds it to agents.
schemas/​input/​agents.yaml Documents the optional agent_type field.
benches/​assets.rs Updates imports to the competitive module.

Review effort: Balanced

@tsmbland

tsmbland commented Nov 9, 2026

Copy link
Copy Markdown
Collaborator Author

@alexdewar Again, you missed all the conversations I had with Adam about this (mostly on Teams and not captured in issues). Happy to discuss further if you need more explanation.

@tsmbland
tsmbland requested a review from alexdewar November 9, 2026 15:52
@tsmbland
tsmbland added this pull request to stack #1584 November 10, 2026 11:27
@tsmbland
tsmbland force-pushed the multi_investment_algorithms_prep branch from 3db7b64 to c241bd6 Compare November 10, 2026 11:53
@codecov

codecov Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.88991% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.26%. Comparing base (b98ea56) to head (eded7a3).

Files with missing lines Patch % Lines
src/simulation/investment/competitive.rs 91.34% 24 Missing and 1 partial ⚠️
src/simulation/investment/competitive/output.rs 91.22% 1 Missing and 4 partials ⚠️
src/output.rs 98.50% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1577      +/-   ##
==========================================
+ Coverage   89.12%   89.26%   +0.14%     
==========================================
  Files          61       63       +2     
  Lines        9160     9244      +84     
  Branches     9160     9244      +84     
==========================================
+ Hits         8164     8252      +88     
+ Misses        677      675       -2     
+ Partials      319      317       -2     

☔ View full report in Codecov by Harness.
📢 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
tsmbland removed this pull request from stack #1584 November 10, 2026 15:58
@tsmbland
tsmbland added this pull request to stack #1588 November 10, 2026 16:00
@tsmbland
tsmbland removed this pull request from stack #1588 November 11, 2026 16:29
@tsmbland
tsmbland added this pull request to stack #1594 November 11, 2026 16:29
@tsmbland
tsmbland force-pushed the multi_investment_algorithms_prep branch from c241bd6 to 0c4d505 Compare November 12, 2026 16:13
Base automatically changed from circularity_milp to main November 13, 2026 13:48
tsmbland and others added 7 commits November 13, 2026 14:00
Pure move: appraisal.rs becomes competitive/metrics.rs and the appraisal
submodules move alongside it, in preparation for supporting multiple asset
selection algorithms.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…module

select_best_assets, its helpers and the candidate/tranche logic move from
investment.rs and market.rs into investment/competitive.rs. No behaviour
change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Option building and process exclusion move inside the algorithm, so
select_assets_for_single_market only computes demand portions and limits.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Allows modules such as asset selection algorithms to own their debug files,
which are created lazily on first write.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove appraisal-specific code from the output module. The competitive
algorithm now writes debug_asset_selection_competitive.csv and
debug_asset_selection_competitive_time_slices.csv via DataWriter::write_debug_rows.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The optional agent_type column selects the asset selection algorithm for each
agent. Currently the only option is `competitive` (the default), so existing
models are unaffected.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@tsmbland
tsmbland force-pushed the multi_investment_algorithms_prep branch from 0c4d505 to f6a556f Compare November 13, 2026 14:02
@alexdewar

Copy link
Copy Markdown
Member

This makes sense to me as a first pass. As discussed, we can always fiddle with the interface for investment algos later. Off the top of your head, is there any more functionality in competitive that you think is generic to other algorithms? Or is everything in the different select_assets implementations likely to be different?

Not directly related to this PR, but select_assets takes a crazy number of arguments. I'm not sure I have a good enough sense of how they all relate to one another to suggest anything concrete, but I do wonder if some of them could be bundled together in structs to reduce the cognitive load on anyone reading the code. Probably not a job for now anyway, though.

In terms of the output stuff, I've got a couple of ideas:

  1. We could expose DataWriter's (optional) inner DebugDataWriter via a debug_writer() method, then do away with the debug_enabled() helper. The way it's written now is ok, but feels a bit like the antipattern where you call is_none() on an Option followed by unwrap(). select_assets and other functions could just take an Option<&mut DebugDataWriter> then (which would also simplify writing tests).
  2. I like the idea of having custom writers stored in a HashMap by the filename (though I'd also check that the filenames start with debug_ and end with .csv). Rather than allowing callers to use them via the write_custom_rows() method though, I'd just have a get_custom_writer() method returning a &mut csv::Writer, so that the caller can do what it wants with it (it also disambiguates errors caused by creating vs writing to the file, although in practice we might not care that much about the distinction).

Comment thread src/input/agent.rs Outdated
/// The region(s) in which the agent operates.
regions: String,
/// The algorithm that the agent uses to select assets (defaults to `competitive`).
agent_type: Option<AgentType>,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think you need to make this an Option type as you've designated a default for the enum.

Comment thread src/output.rs Outdated
let writer = match self.custom_writers.entry(file_name) {
Entry::Occupied(entry) => entry.into_mut(),
Entry::Vacant(entry) => {
entry.insert(csv::Writer::from_path(self.output_path.join(file_name))?)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about we double-check the file doesn't already exist, as it would if someone passes the same
name as one of the existing output files:

Suggested change
entry.insert(csv::Writer::from_path(self.output_path.join(file_name))?)
// Create a new `csv::Writer`, ensuring file doesn't already exist
let file = OpenOptions::new()
.write(true)
.create_new(true)
.open(self.output_path.join(file_name)?;
entry.insert(csv::Writer::from_writer(file)

I'd also assert that the name starts with debug_ and ends with .csv.

Comment on lines +103 to +112
/// Get options from existing and potential assets for the given parameters
pub fn get_asset_options<'a>(
all_existing_assets: &'a [AssetRef],
demand: &'a DemandMap,
agent: &'a Agent,
commodity: &'a Commodity,
region_id: &'a RegionID,
year: u32,
capacity_tranche_fraction: Dimensionless,
) -> impl Iterator<Item = AssetRef> + 'a {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this functionality specific to the competitive agent type? It seems pretty generic

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's mostly generic, yes. The specific thing here is the tranching - setting candidate capacities according to capacity_tranche_fraction. The other algorithm doesn't need to do this.

There is probably a better way of sharing the generic parts, but I'll hold off for now and properly re-assess the interface once this current batch of PRs is done

Comment on lines +134 to +149
/// Get candidate assets which produce a particular commodity for a given agent
///
/// Each candidate represents one investment tranche with a defined capacity.
/// - For processes with a defined `tranche_size`, the capacity is set to `tranche_size`.
/// - For processes without a defined `tranche_size`, the capacity is calculated based on the total
/// demand for the commodity and the asset's maximum annual production per unit capacity
/// (see `calculate_candidate_asset_capacity_scale`), then multiplied by
/// `capacity_tranche_fraction` to infer the tranche size.
fn get_candidate_assets<'a>(
demand: &'a DemandMap,
agent: &'a Agent,
region_id: &'a RegionID,
commodity: &'a Commodity,
year: u32,
capacity_tranche_fraction: Dimensionless,
) -> impl Iterator<Item = AssetRef> + 'a {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto

Comment on lines +74 to +75
let run_description = &run_description;
result.activity.iter().map(move |(time_slice, activity)| {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You only need to take a ref because you're moving it into the closure. This also works:

Suggested change
let run_description = &run_description;
result.activity.iter().map(move |(time_slice, activity)| {
result.activity.iter().map(|(time_slice, activity)| {

Comment thread src/output.rs Outdated
}

/// Prepend the current debug context (if any) to a run description
pub fn debug_run_description(&self, run_description: &str) -> String {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that we'll often be returning run_description as is, you could also return a Cow<'a, str>
so that you only allocate a new string if needed. Not esp important

@@ -0,0 +1,668 @@
//! The competitive asset selection algorithm.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume the functions in this file haven't been changed much beyond being rehomed?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, but they will (#1563)

@@ -0,0 +1,197 @@
//! Debug output for the competitive asset selection algorithm.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like output.rs might be a better name for this file

@alexdewar

Copy link
Copy Markdown
Member

Looks like tests are failing after the conversion of excluded_processes to IndexSet<ProcessID>

@tsmbland
tsmbland enabled stacked auto-merge November 13, 2026 16:08
@tsmbland
tsmbland merged commit bd37615 into main Nov 13, 2026
@tsmbland
tsmbland deleted the multi_investment_algorithms_prep branch November 13, 2026 16:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants