ortools.math_opt.python.expressions

Utilities for working with linear and quadratic expressions.

View Source

 1# Copyright 2010-2024 Google LLC
 2# Licensed under the Apache License, Version 2.0 (the "License");
 3# you may not use this file except in compliance with the License.
 4# You may obtain a copy of the License at
 5#
 6#     http://www.apache.org/licenses/LICENSE-2.0
 7#
 8# Unless required by applicable law or agreed to in writing, software
 9# distributed under the License is distributed on an "AS IS" BASIS,
10# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11# See the License for the specific language governing permissions and
12# limitations under the License.
13
14"""Utilities for working with linear and quadratic expressions."""
15
16import typing
17from typing import Iterable, Mapping, Union
18
19from ortools.math_opt.python import model
20
21
22@typing.overload
23def fast_sum(summands: Iterable[model.LinearTypes]) -> model.LinearSum: ...
24
25
26@typing.overload
27def fast_sum(
28    summands: Iterable[model.QuadraticTypes],
29) -> Union[model.LinearSum, model.QuadraticSum]: ...
30
31
32# TODO(b/312200030): There is a pytype bug so that for the code:
33#   m = mathopt.Model()
34#   x = m.Variable()
35#   s = expressions.fast_sum([x*x, 4.0])
36# pytype picks the wrong overload and thinks s has type model.LinearSum, rather
37# than Union[model.LinearSum, model.QuadraticSum]. Once the bug is fixed,
38# confirm that the overloads actually work.
39def fast_sum(summands):
40    """Sums the elements of summand into a linear or quadratic expression.
41
42    Similar to Python's sum function, but faster for input that not just integers
43    and floats.
44
45    Unlike sum(), the function returns a linear expression when all inputs are
46    floats and/or integers. Importantly, the code:
47      model.add_linear_constraint(fast_sum(maybe_empty_list) <= 1.0)
48    is safe to call, while:
49      model.add_linear_constraint(sum(maybe_empty_list) <= 1.0)
50    fails at runtime when the list is empty.
51
52    Args:
53      summands: The elements to add up.
54
55    Returns:
56      A linear or quadratic expression with the sum of the elements of summand.
57    """
58    summands_tuple = tuple(summands)
59    for s in summands_tuple:
60        if isinstance(s, model.QuadraticBase):
61            return model.QuadraticSum(summands_tuple)
62    return model.LinearSum(summands_tuple)
63
64
65def evaluate_expression(
66    expression: model.QuadraticTypes,
67    variable_values: Mapping[model.Variable, float],
68) -> float:
69    """Evaluates a linear or quadratic expression for given variable values.
70
71    E.g. if expression  = 3 * x + 4 and variable_values = {x: 2.0}, then
72    evaluate_expression(expression, variable_values) equals 10.0.
73
74    Args:
75      expression: The expression to evaluate.
76      variable_values: Must contain a value for every variable in expression.
77
78    Returns:
79      The value of the expression when replacing variables by their value.
80    """
81    if isinstance(expression, model.QuadraticBase):
82        return model.as_flat_quadratic_expression(expression).evaluate(variable_values)
83    return model.as_flat_linear_expression(expression).evaluate(variable_values)

def fast_sum(summands): View Source

40def fast_sum(summands):
41    """Sums the elements of summand into a linear or quadratic expression.
42
43    Similar to Python's sum function, but faster for input that not just integers
44    and floats.
45
46    Unlike sum(), the function returns a linear expression when all inputs are
47    floats and/or integers. Importantly, the code:
48      model.add_linear_constraint(fast_sum(maybe_empty_list) <= 1.0)
49    is safe to call, while:
50      model.add_linear_constraint(sum(maybe_empty_list) <= 1.0)
51    fails at runtime when the list is empty.
52
53    Args:
54      summands: The elements to add up.
55
56    Returns:
57      A linear or quadratic expression with the sum of the elements of summand.
58    """
59    summands_tuple = tuple(summands)
60    for s in summands_tuple:
61        if isinstance(s, model.QuadraticBase):
62            return model.QuadraticSum(summands_tuple)
63    return model.LinearSum(summands_tuple)

Sums the elements of summand into a linear or quadratic expression.

Similar to Python's sum function, but faster for input that not just integers and floats.

Unlike sum(), the function returns a linear expression when all inputs are floats and/or integers. Importantly, the code: model.add_linear_constraint(fast_sum(maybe_empty_list) <= 1.0) is safe to call, while: model.add_linear_constraint(sum(maybe_empty_list) <= 1.0) fails at runtime when the list is empty.

Arguments:

summands: The elements to add up.

Returns:

A linear or quadratic expression with the sum of the elements of summand.

def evaluate_expression( expression: Union[int, float, ForwardRef('LinearBase'), ForwardRef('QuadraticBase')], variable_values: Mapping[ortools.math_opt.python.model.Variable, float]) -> float: View Source

66def evaluate_expression(
67    expression: model.QuadraticTypes,
68    variable_values: Mapping[model.Variable, float],
69) -> float:
70    """Evaluates a linear or quadratic expression for given variable values.
71
72    E.g. if expression  = 3 * x + 4 and variable_values = {x: 2.0}, then
73    evaluate_expression(expression, variable_values) equals 10.0.
74
75    Args:
76      expression: The expression to evaluate.
77      variable_values: Must contain a value for every variable in expression.
78
79    Returns:
80      The value of the expression when replacing variables by their value.
81    """
82    if isinstance(expression, model.QuadraticBase):
83        return model.as_flat_quadratic_expression(expression).evaluate(variable_values)
84    return model.as_flat_linear_expression(expression).evaluate(variable_values)

Evaluates a linear or quadratic expression for given variable values.

E.g. if expression = 3 * x + 4 and variable_values = {x: 2.0}, then evaluate_expression(expression, variable_values) equals 10.0.

Arguments:

expression: The expression to evaluate.
variable_values: Must contain a value for every variable in expression.

Returns:

The value of the expression when replacing variables by their value.