Allow passing custom options to HiGHS via `model.toml` by alexdewar · Pull Request #1276 · EnergySystemsModellingLab/MUSE2

alexdewar · 2026-05-07T15:05:35Z

Description

The HiGHS solver provides many options to change its behaviour, but there is currently no mechanism for changing them within MUSE2. While we don't want ordinary users to be mucking around with things like tolerances, it's useful for development to be able to tweak them to see what happens.

Add a new optional [highs] section to the model.toml file, which lets users pass through options directly to the solver. I thought it was worth letting users change things separately for dispatch and appraisal, as these are different optimisation problems, so there are actually three subsections to [highs]: [highs.global_options], [highs.dispatch_options] and [highs.appraisal_options]. Global options are applied to both optimisation types (for if e.g. you want to enable logging for HiGHS for both). As we can't be sure that the options changed won't do something odd, it's gated behind the please_give_me_broken_results setting, like we do for other potentially dangerous things.

An alternative way of implementing this would be to let users create a HiGHS config file then telling HiGHS to load this, but it seemed cleaner to just use the existing file we have for configuring models and not having to worry about another input format etc.

I've also added a short page to the docs to explain how to use this feature.

Closes #420.

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

It doesn't make sense to create a `DispatchRun` struct and not do anything with it.

…rent/non-optimal

Closes #420.

codecov · 2026-05-07T15:06:55Z

Codecov Report

❌ Patch coverage is 50.68493% with 36 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.50%. Comparing base (ddf4a95) to head (a29c7f6).

Files with missing lines	Patch %	Lines
src/simulation/optimisation.rs	25.64%	25 Missing and 4 partials ⚠️
src/model/parameters.rs	79.16%	2 Missing and 3 partials ⚠️
...rc/simulation/investment/appraisal/optimisation.rs	75.00%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1276      +/-   ##
==========================================
- Coverage   89.78%   89.50%   -0.29%     
==========================================
  Files          57       57              
  Lines        8204     8267      +63     
  Branches     8204     8267      +63     
==========================================
+ Hits         7366     7399      +33     
- Misses        542      567      +25     
- Partials      296      301       +5

☔ 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.

Copilot

Pull request overview

This PR adds a development-focused mechanism for passing user-specified HiGHS solver options through model.toml, gated behind please_give_me_broken_results, and wires those options into both dispatch and investment appraisal optimisations.

Changes:

Introduces a new optional [highs] configuration section with global_options, dispatch_options, and appraisal_options, plus validation/gating.
Applies configured HiGHS options when constructing the HiGHS model for dispatch and appraisal runs.
Adds developer documentation and schema updates for the new configuration.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`src/simulation/optimisation.rs`	Adds TOML→HiGHS option application helper; updates solver error handling; applies dispatch options before solving.
`src/simulation/investment/appraisal/optimisation.rs`	Applies appraisal options before solving and adjusts API to access `Model` for parameters/time slices.
`src/simulation/investment/appraisal.rs`	Updates appraisal calls to pass `Model` into optimisation helper.
`src/model/parameters.rs`	Adds `HighsOptions` to `ModelParameters`, validates gating, and merges `global_options` into dispatch/appraisal options.
`schemas/input/model.yaml`	Documents the new `[highs]` config structure in the model schema.
`docs/SUMMARY.md`	Links the new developer guide page.
`docs/developer_guide/custom_highs_options.md`	Documents how to configure custom HiGHS options via `model.toml`.
`clippy.toml`	Allows “HiGHS” as a valid doc identifier for Clippy.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+fn check_highs_options(dangerous_options_enabled: bool, highs: &HighsOptions) -> Result<()> {
+    ensure!(
+        dangerous_options_enabled || highs.is_empty(),
+        "Cannot set custom HiGHS options without enabling {ALLOW_DANGEROUS_OPTION_NAME}"
+    );


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…options Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

+    /// Another error occurred
+    Other(anyhow::Error),
+}
+


 /// NOTE: If you add or change a field in this struct, you must also update the schema in
 /// `schemas/input/model.yaml`.
-#[derive(Debug, Deserialize, PartialEq)]
+#[derive(Deserialize)]


+
+    Ok(())
+}
+


tsmbland · 2026-05-12T12:18:02Z

    pub fn from_path<P: AsRef<Path>>(model_dir: P) -> Result<ModelParameters> {
        let file_path = model_dir.as_ref().join(MODEL_PARAMETERS_FILE_NAME);
-        let model_params: ModelParameters = read_toml(&file_path)?;
+        let mut model_params: ModelParameters = read_toml(&file_path)?;

        set_dangerous_model_options_flag(model_params.allow_dangerous_options);

        model_params
            .validate()
            .with_context(|| input_err_msg(file_path))?;

+        // Copy global options to other tables
+        model_params.highs.apply_global_options();
+
        Ok(model_params)


Probably fine as it is, but I agree this isn't ideal. Have you considered other approaches? Wouldn't move it to validate() like it's suggesting, but possibly the deserialization suggestion if easy, or merging the global and local options on retrieval?

+As part of development, you may wish to directly set custom options for the HiGHS solver. Note that
+while some of these options will not affect results of simulations (e.g. to enable console logging
+for HiGHS), as we cannot guarantee this for all options, in order to use this feature, you have to
+set `please_give_me_broken_results = true` in your [`model.toml` file][model.toml].
+
+You can change any of the options exposed by the HiGHS solver; for more information, see [the HiGHS
+documentation][highs-opts].
+
+You can set options to be applied to all optimisations, just dispatch or just appraisal.
+
+Here is an example:
+
+```toml
+please_give_me_broken_results = true
+milestone_years = [2020, 2030, 2040]
+
+# These options are applied to all optimisations
+[highs.global_options]
+# These two options are required to be enabled to log to console
+log_to_console = true


tsmbland

Some comments perhaps worth addressing, but otherwise this looks good and potentially very useful!

tsmbland · 2026-05-12T12:03:37Z

 ## New features

-<!-- TODO -->
+- Users can now optionally pass [custom options][highs-options] to the HiGHS solver [#1276]


I think it would be more helpful here to link to the new documentation page

tsmbland · 2026-05-12T12:18:02Z

    pub fn from_path<P: AsRef<Path>>(model_dir: P) -> Result<ModelParameters> {
        let file_path = model_dir.as_ref().join(MODEL_PARAMETERS_FILE_NAME);
-        let model_params: ModelParameters = read_toml(&file_path)?;
+        let mut model_params: ModelParameters = read_toml(&file_path)?;

        set_dangerous_model_options_flag(model_params.allow_dangerous_options);

        model_params
            .validate()
            .with_context(|| input_err_msg(file_path))?;

+        // Copy global options to other tables
+        model_params.highs.apply_global_options();
+
        Ok(model_params)


Probably fine as it is, but I agree this isn't ideal. Have you considered other approaches? Wouldn't move it to validate() like it's suggesting, but possibly the deserialization suggestion if easy, or merging the global and local options on retrieval?

tsmbland · 2026-05-12T12:27:45Z

 /// For a detailed description, please see the [dispatch optimisation formulation][1].
 ///
 /// [1]: https://energysystemsmodellinglab.github.io/MUSE2/model/dispatch_optimisation.html
+#[must_use = "Must call run() method on DispatchRun struct"]


Didn't know about this before, good to know that it's a thing!

tsmbland · 2026-05-12T12:37:22Z

+            let option = $option.as_str();
+            let value = $value;
+
+            debug!("Setting HiGHS option \"{option}\" to \"{value}\"");


I can see the value in logging this, but shall we make this trace instead? I use debug level to see model progress and choices like investment decisions, and it would be annoying to clog up my console/log files with potentially thousands of these messages

alexdewar added 5 commits May 7, 2026 13:42

ModelParameters: Remove some unnecessarily derived traits

c0ac6b2

Add must_use attribute to DispatchRun

ca2d250

It doesn't make sense to create a `DispatchRun` struct and not do anything with it.

Allow ModelError to contain arbitrary errors other than just incohe…

dcc9e50

…rent/non-optimal

Allow users to set custom HiGHS options for dispatch and appraisal

6b740d0

Closes #420.

Document highs property for model.toml in schema and with extra doc

e4fbde2

Copilot AI review requested due to automatic review settings May 7, 2026 15:05

Copilot started reviewing on behalf of alexdewar May 7, 2026 15:06 View session

Update release notes

3df49f3

Copilot AI reviewed May 7, 2026

View reviewed changes

Implement Error::source() for ModelError

b891381

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 7, 2026 15:14

Copilot started reviewing on behalf of alexdewar May 7, 2026 15:15 View session

Fix: Enable please_give_me_broken_results for example use of HiGHS …

a29c7f6

…options Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

alexdewar requested review from AdrianDAlessandro, Aurashk, mjademitchell and tsmbland May 7, 2026 15:19

Copilot AI reviewed May 7, 2026

View reviewed changes

tsmbland approved these changes May 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow passing custom options to HiGHS via `model.toml`#1276

Allow passing custom options to HiGHS via `model.toml`#1276
alexdewar wants to merge 8 commits into
mainfrom
highs-settings-in-model.toml

alexdewar commented May 7, 2026 •

edited

Loading

Uh oh!

codecov Bot commented May 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

tsmbland May 12, 2026

Uh oh!

tsmbland left a comment

Uh oh!

tsmbland May 12, 2026

Uh oh!

tsmbland May 12, 2026

Uh oh!

tsmbland May 12, 2026

Uh oh!

tsmbland May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

alexdewar commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Key checklist

Further checks

Uh oh!

codecov Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

tsmbland May 12, 2026

Choose a reason for hiding this comment

Uh oh!

tsmbland left a comment

Choose a reason for hiding this comment

Uh oh!

tsmbland May 12, 2026

Choose a reason for hiding this comment

Uh oh!

tsmbland May 12, 2026

Choose a reason for hiding this comment

Uh oh!

tsmbland May 12, 2026

Choose a reason for hiding this comment

Uh oh!

tsmbland May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexdewar commented May 7, 2026 •

edited

Loading

codecov Bot commented May 7, 2026 •

edited

Loading