Add support for modeling with units in JuMP

[blegat]

Project

JuMP

Summary

The goal of the project is to add support for create JuMP variables that have a specific unit as well as creating constraints with units.

submitter

Benoît Legat

project lead

@mlubin

Community benefit

JuMP is often used for modeling problems involving physical quantities with units. The Julia Unitful package allows using units with most of the Julia ecosystem. However, when encoding the JuMP model, these need to be stripped out as JuMP does not support it. The user then need to handle unit conversion manually which is error prone and decreases the readability of the code.
Adding units to JuMP is a long-standing issue dating back to 2018 and is also part of the JuMP roadmap.
By allowing users to define and manipulate variables with physical units directly in JuMP, the risk of unit-related errors—such as mismatched constraints or incorrect scaling—will be significantly reduced. This enhancement will make JuMP more intuitive for users in engineering, energy systems, and other applied fields where unit consistency is critical.

Amount requested

10000

Execution plan

There is an existing proof-of-concept implementation : https://github.com/trulsf/UnitJuMP.jl
The goal of this SDG is to integrate this support natively to JuMP as part of a package extension so that units work out of the box.
While the proof-of-concept is a good start and set up the ideal user interface, it is challenging to make this approach work for quadratic and nonlinear expressions. Indeed, the UnitJuMP approach is to define new types of variables and expressions and implement all needed operator overloading for all interactions of these variables and expressions with the ones defined in JuMP or JuMP extensions.
When I added complex support for JuMP as part of a previous round of SDG, I tested a different approach: use complex numbers in the coefficients of the JuMP existing expressions, without the need to define new Julia objects.
As this approach was quite successful, the goal of this SDG is to apply this approach for units. More precisely, variables with units will be represented as classical JuMP expressions with units in the coefficients.

The project will consist in the following 5 steps:

Step 1 Variables

This step would allow the user to create variables with units and interact between different variables to create algebraic expressions. It would involve:

1. Extending the JuMP @variable macro by adding the ability to create JuMP variables
2. Ensuring that the API for setting bounds, starting values, etc... work for these variables
3. Ensuring that these variables interact correctly with other expressions and that unit promotion is applied appropriately

Budget allocation: $2000
Timeline: 1-2 month

Step 2 Objective and Constraints

This step would allow the user to set an objective function and add constraints with units. It would involve

1. Strip out the unit from the objective and constraints when adding them to the inner solver as the solver does not support units.
2. Recover the unit when the user queries the objective value or prints the model.

Budget allocation: $2000
Timeline: 1-2 month

Step 3 Nonlinear

Stripping out units in nonlinear expressions is slightly more challenging as they need to be removed for each subexpression of the expression graph. The choice of scaling when stripping out the unit is crucial for the numerical accuracy of the automatic differentiation so this step would involve careful consideration and transparent behavior so that expert user can diagnose issues related to it.

Budget allocation: $2000
Timeline: 1-2 month

Step 4 Documentation

Once the implementation is complete and tested, this step would involve completing the documentation to detail how these units can be used and what are the important aspects to be aware of such as numerical issues when the scaling used is not appropriate.

Budget allocation: $2000
Timeline: 1-2 month

Step 5 Examples

This step would involve converting relevant examples in control and power systems to use units in addition to adding new tutorials and examples showcasing how this new support allow JuMP to better interact with other Julia packages supporting units in the fields of biology, chemistry or physics.

Budget allocation: $2000
Timeline: 1-2 month