Constraint
Bases: BaseBlock
An optimization constraint that can be added to a Model.
Implementation Note
Pyoframe simplifies constraints by moving all the constraint's mathematical terms to the left-hand side. This way, the right-hand side is always zero, and constraints only need to manage one expression.
Use <=
, >=
, or ==
operators to create constraints
Constraints should be created using the <=
, >=
, or ==
operators, not by directly calling the Constraint
constructor.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
lhs
|
Expression
|
The constraint's left-hand side expression. |
required |
sense
|
ConstraintSense
|
The sense of the constraint. |
required |
Methods:
Name | Description |
---|---|
estimated_size |
Returns the estimated size of the constraint. |
filter |
Syntactic sugar on |
relax |
Allows the constraint to be violated at a |
to_str |
Converts the constraint to a human-readable string, or several arranged in a table. |
Attributes:
Name | Type | Description |
---|---|---|
attr |
Container
|
Allows reading and writing constraint attributes similarly to Model.attr. |
dual |
DataFrame | float
|
Returns the constraint's dual values. |
lhs |
Expression
|
|
sense |
|
Source code in pyoframe/_core.py
attr: Container
Allows reading and writing constraint attributes similarly to Model.attr.
dual: pl.DataFrame | float
Returns the constraint's dual values.
Examples:
Notice that for every unit increase in the right-hand side, the objective only improves by 0.5.
For every unit increase in the right-hand side of constraint_x
, the objective improves by 0.5.
For every unit increase in the right-hand side of constraint_y
, the objective worsens by 0.5.
lhs: Expression = lhs
sense = sense
estimated_size(*args, **kwargs)
Returns the estimated size of the constraint.
Includes the size of the underlying expression (Constraint.lhs
).
See Expression.estimated_size
for details on signature and behavior.
Examples:
An dimensionless constraint has contains a 32 bit constraint id and, for each term, a 64 bit coefficient with a 32 bit variable id. For a two-term expression that is: (32 + 2 * (64 + 32)) = 224 bits = 28 bytes.
Source code in pyoframe/_core.py
filter(*args, **kwargs) -> pl.DataFrame
relax(cost: Operable, max: Operable | None = None) -> Constraint
Allows the constraint to be violated at a cost
and, optionally, up to a maximum.
Warning
.relax()
must be called before the constraint is assigned to the Model (see examples below).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cost
|
Operable
|
The cost of violating the constraint. Costs should be positive because Pyoframe will automatically make them negative for maximization problems. |
required |
max
|
Operable | None
|
The maximum value of the relaxation variable. |
None
|
Returns:
Type | Description |
---|---|
Constraint
|
The same constraint |
Examples:
>>> m = pf.Model()
>>> m.hours_sleep = pf.Variable(lb=0)
>>> m.hours_day = pf.Variable(lb=0)
>>> m.hours_in_day = m.hours_sleep + m.hours_day == 24
>>> m.maximize = m.hours_day
>>> m.must_sleep = (m.hours_sleep >= 8).relax(cost=2, max=3)
>>> m.optimize()
>>> m.hours_day.solution
16.0
>>> m.maximize += 2 * m.hours_day
>>> m.optimize()
>>> m.hours_day.solution
19.0
relax
can only be called after the sense of the model has been defined.
>>> m = pf.Model()
>>> m.hours_sleep = pf.Variable(lb=0)
>>> m.hours_day = pf.Variable(lb=0)
>>> m.hours_in_day = m.hours_sleep + m.hours_day == 24
>>> m.must_sleep = (m.hours_sleep >= 8).relax(cost=2, max=3)
Traceback (most recent call last):
...
ValueError: Cannot relax a constraint before the objective sense has been set. Try setting the objective first or using Model(sense=...).
One way to solve this is by setting the sense directly on the model. See how this works fine:
>>> m = pf.Model(sense="max")
>>> m.hours_sleep = pf.Variable(lb=0)
>>> m.hours_day = pf.Variable(lb=0)
>>> m.hours_in_day = m.hours_sleep + m.hours_day == 24
>>> m.must_sleep = (m.hours_sleep >= 8).relax(cost=2, max=3)
And now an example with dimensions:
>>> homework_due_tomorrow = pl.DataFrame(
... {
... "project": ["A", "B", "C"],
... "cost_per_hour_underdelivered": [10, 20, 30],
... "hours_to_finish": [9, 9, 9],
... "max_underdelivered": [1, 9, 9],
... }
... )
>>> m.hours_spent = pf.Variable(homework_due_tomorrow["project"], lb=0)
>>> m.must_finish_project = (
... m.hours_spent
... >= homework_due_tomorrow[["project", "hours_to_finish"]]
... ).relax(
... homework_due_tomorrow[["project", "cost_per_hour_underdelivered"]],
... max=homework_due_tomorrow[["project", "max_underdelivered"]],
... )
>>> m.only_one_day = m.hours_spent.sum("project") <= 24
>>> # Relaxing a constraint after it has already been assigned will give an error
>>> m.only_one_day.relax(1)
Traceback (most recent call last):
...
ValueError: .relax() must be called before the Constraint is added to the model
>>> m.attr.Silent = True
>>> m.optimize()
>>> m.maximize.value
-50.0
>>> m.hours_spent.solution
shape: (3, 2)
┌─────────┬──────────┐
│ project ┆ solution │
│ --- ┆ --- │
│ str ┆ f64 │
╞═════════╪══════════╡
│ A ┆ 8.0 │
│ B ┆ 7.0 │
│ C ┆ 9.0 │
└─────────┴──────────┘
Source code in pyoframe/_core.py
1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 |
|
to_str(return_df: bool = False) -> str | pl.DataFrame
Converts the constraint to a human-readable string, or several arranged in a table.
Long expressions are truncated according to Config.print_max_terms
and Config.print_polars_config
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
return_df
|
bool
|
If |
False
|
Examples:
>>> import polars as pl
>>> m = pf.Model()
>>> x = pf.Set(x=range(1000))
>>> y = pf.Set(y=range(1000))
>>> m.V = pf.Variable(x, y)
>>> expr = 2 * m.V * m.V
>>> print((expr <= 3).to_str())
┌────────┬────────┬────────────────────────────────┐
│ x ┆ y ┆ constraint │
│ (1000) ┆ (1000) ┆ │
╞════════╪════════╪════════════════════════════════╡
│ 0 ┆ 0 ┆ 2 V[0,0] * V[0,0] <= 3 │
│ 0 ┆ 1 ┆ 2 V[0,1] * V[0,1] <= 3 │
│ 0 ┆ 2 ┆ 2 V[0,2] * V[0,2] <= 3 │
│ 0 ┆ 3 ┆ 2 V[0,3] * V[0,3] <= 3 │
│ 0 ┆ 4 ┆ 2 V[0,4] * V[0,4] <= 3 │
│ … ┆ … ┆ … │
│ 999 ┆ 995 ┆ 2 V[999,995] * V[999,995] <= 3 │
│ 999 ┆ 996 ┆ 2 V[999,996] * V[999,996] <= 3 │
│ 999 ┆ 997 ┆ 2 V[999,997] * V[999,997] <= 3 │
│ 999 ┆ 998 ┆ 2 V[999,998] * V[999,998] <= 3 │
│ 999 ┆ 999 ┆ 2 V[999,999] * V[999,999] <= 3 │
└────────┴────────┴────────────────────────────────┘
>>> expr = expr.sum("x")
>>> print((expr >= 3).to_str())
┌────────┬─────────────────────────────────────────────────────────────────────────────────────────┐
│ y ┆ constraint │
│ (1000) ┆ │
╞════════╪═════════════════════════════════════════════════════════════════════════════════════════╡
│ 0 ┆ 2 V[0,0] * V[0,0] +2 V[1,0] * V[1,0] +2 V[2,0] * V[2,0] +2 V[3,0] * V[3,0] +2 V[4,0] * │
│ ┆ V[4,0] … >= 3 │
│ 1 ┆ 2 V[0,1] * V[0,1] +2 V[1,1] * V[1,1] +2 V[2,1] * V[2,1] +2 V[3,1] * V[3,1] +2 V[4,1] * │
│ ┆ V[4,1] … >= 3 │
│ 2 ┆ 2 V[0,2] * V[0,2] +2 V[1,2] * V[1,2] +2 V[2,2] * V[2,2] +2 V[3,2] * V[3,2] +2 V[4,2] * │
│ ┆ V[4,2] … >= 3 │
│ 3 ┆ 2 V[0,3] * V[0,3] +2 V[1,3] * V[1,3] +2 V[2,3] * V[2,3] +2 V[3,3] * V[3,3] +2 V[4,3] * │
│ ┆ V[4,3] … >= 3 │
│ 4 ┆ 2 V[0,4] * V[0,4] +2 V[1,4] * V[1,4] +2 V[2,4] * V[2,4] +2 V[3,4] * V[3,4] +2 V[4,4] * │
│ ┆ V[4,4] … >= 3 │
│ … ┆ … │
│ 995 ┆ 2 V[0,995] * V[0,995] +2 V[1,995] * V[1,995] +2 V[2,995] * V[2,995] +2 V[3,995] * │
│ ┆ V[3,995] +2 V[4,99… │
│ 996 ┆ 2 V[0,996] * V[0,996] +2 V[1,996] * V[1,996] +2 V[2,996] * V[2,996] +2 V[3,996] * │
│ ┆ V[3,996] +2 V[4,99… │
│ 997 ┆ 2 V[0,997] * V[0,997] +2 V[1,997] * V[1,997] +2 V[2,997] * V[2,997] +2 V[3,997] * │
│ ┆ V[3,997] +2 V[4,99… │
│ 998 ┆ 2 V[0,998] * V[0,998] +2 V[1,998] * V[1,998] +2 V[2,998] * V[2,998] +2 V[3,998] * │
│ ┆ V[3,998] +2 V[4,99… │
│ 999 ┆ 2 V[0,999] * V[0,999] +2 V[1,999] * V[1,999] +2 V[2,999] * V[2,999] +2 V[3,999] * │
│ ┆ V[3,999] +2 V[4,99… │
└────────┴─────────────────────────────────────────────────────────────────────────────────────────┘
>>> expr = expr.sum("y")
>>> print((expr == 3).to_str())
2 V[0,0] * V[0,0] +2 V[0,1] * V[0,1] +2 V[0,2] * V[0,2] +2 V[0,3] * V[0,3] +2 V[0,4] * V[0,4] … = 3
Source code in pyoframe/_core.py
2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 |
|
Comments