Skip to content

Commit

Permalink
Trying to add sub tocs for better navigation
Browse files Browse the repository at this point in the history
  • Loading branch information
@d-krupke
d-krupke committed May 3, 2024
1 parent ff6811d commit 5193b39
Show file tree
Hide file tree
Showing 3 changed files with 84 additions and 1 deletion.
39 changes: 39 additions & 0 deletions 04_modelling.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,21 @@ Resources on mathematical modelling (not CP-SAT specific):
> the future. I observed cases where certain methods were not available in one
> or the other style, so you may need to switch between them for some versions.
- [Variables](#04-modelling-variables)
- [Domain Variables](#04-modelling-domain-variables)
- [Objectives](#04-modelling-objectives)
- [Linear Constraints](#04-modelling-linear-constraints)
- [Logical Constraints (Propositional Logic)](#04-modelling-logic-constraints)
- [Conditional Constraints (Channeling, Reification)](#04-modelling-conditional-constraints)
- [AllDifferent](#04-modelling-alldifferent)
- [Absolute Values and Max/Min](#04-modelling-absmaxmin)
- [Multiplication, Division, and Modulo](#04-modelling-multdivmod)
- [Circuit/Tour-Constraints](#04-modelling-circuit)
- [Interval/Packing/Scheduling Constraints](#04-modelling-intervals)
- [Piecewise Linear Constraints](#04-modelling-pwl)

<a name="04-modelling-variables"></a>

### Variables

There are two important types of variables in CP-SAT: Booleans and Integers
Expand Down Expand Up @@ -124,6 +139,8 @@ infeasibility. In such scenarios, having named variables can significantly
enhance the clarity of the internal representation, making your debugging
process much more manageable.

<a name="04-modelling-domain-variables"></a>

#### Domain Variables

When dealing with integer variables that you know will only need to take certain
Expand Down Expand Up @@ -174,6 +191,8 @@ only take on the values specified in `domain`. This method is particularly
useful when you are working with variables that only have a meaningful range of
possible values within your problem's context.

<a name="04-modelling-objectives"></a>

### Objectives

Not every problem actually has an objective, sometimes you only need to find a
Expand Down Expand Up @@ -232,6 +251,8 @@ model.Minimize(abs_x)

The available constraints are discussed next.

<a name="04-modelling-linear-constraints"></a>

### Linear Constraints

These are the classical constraints also used in linear optimization. Remember
Expand Down Expand Up @@ -264,6 +285,8 @@ use the explicit `!=` constraints.
> of floating point arithmetic. In CP-SAT, you have to make sure that values can
> match exactly.
<a name="04-modelling-logic-constraints"></a>

### Logical Constraints (Propositional Logic)

You can actually model logical constraints also as linear constraints, but it
Expand All @@ -283,6 +306,8 @@ model.AddImplication(b1, b2) # b1 -> b2
In this context you could also mention `AddAtLeastOne`, `AddAtMostOne`, and
`AddExactlyOne`, but these can also be modelled as linear constraints.

<a name="04-modelling-conditional-constraints"></a>

### Conditional Constraints (Channeling, Reification)

Linear constraints (Add), BoolOr, and BoolAnd support being activated by a
Expand All @@ -299,6 +324,8 @@ model.Add(x + z == 2 * y).OnlyEnforceIf(b1)
model.Add(x + z == 10).OnlyEnforceIf([b2, b3.Not()]) # only enforce if b2 AND NOT b3
```

<a name="04-modelling-alldifferent"></a>

### AllDifferent

A constraint that is often seen in Constraint Programming, but I myself was
Expand Down Expand Up @@ -348,6 +375,8 @@ Maybe CP-SAT will allow you to use `AllDifferent` without any performance
penalty in the future, but for now, you have to be aware of this. See also
[the optimization parameter documentation](https://github.com/google/or-tools/blob/1d696f9108a0ebfd99feb73b9211e2f5a6b0812b/ortools/sat/sat_parameters.proto#L542).

<a name="04-modelling-absmaxmin"></a>

### Absolute Values and Max/Min

Two often occurring and important operators are absolute values as well as
Expand Down Expand Up @@ -403,6 +432,8 @@ issues from improperly applied optimizations frequently requires more time than
applying these techniques initially to a model that uses the less efficient
constraints.

<a name="04-modelling-multdivmod"></a>

### Multiplication, Division, and Modulo

A big nono in linear optimization (the most successful optimization area) are
Expand Down Expand Up @@ -438,6 +469,8 @@ exact function you had in mind.
> variables is supported, but I got an error when trying it out. I have not
> investigated this further, as I would expect it to be painfully slow anyway.
<a name="04-modelling-circuit"></a>

### Circuit/Tour-Constraints

The
Expand Down Expand Up @@ -598,6 +631,8 @@ eucl. distance) from the TSPLIB with a time limit of 90 seconds.
| lin318 | 318 | 92.43 | 41915 | 52025 | 19% |
| pr439 | 439 | 94.22 | 105610 | 163452 | 35% |

<a name="04-modelling-array"></a>

### Array operations

You can even go completely bonkers and work with arrays in your model. The
Expand All @@ -617,6 +652,8 @@ model.AddElement(index=i, variables=[x, y, z], target=ai)
model.AddInverse([x, y, z], [z, y, x])
```

<a name="04-modelling-intervals"></a>

### Interval Variables and No-Overlap Constraints

A special case of variables are the interval variables, that allow to model
Expand Down Expand Up @@ -940,6 +977,8 @@ solver.parameters.use_pairwise_reasoning_in_no_overlap_2d = True
With the latest version of CP-SAT, I did not notice a significant difference in
performance when using these parameters.

<a name="04-modelling-pwl"></a>

### Non-Linear Constraints/Piecewise Linear Functions

In practice, you often have cost functions that are not linear. For example,
Expand Down
39 changes: 39 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -615,6 +615,21 @@ Resources on mathematical modelling (not CP-SAT specific):
> the future. I observed cases where certain methods were not available in one
> or the other style, so you may need to switch between them for some versions.
- [Variables](#04-modelling-variables)
- [Domain Variables](#04-modelling-domain-variables)
- [Objectives](#04-modelling-objectives)
- [Linear Constraints](#04-modelling-linear-constraints)
- [Logical Constraints (Propositional Logic)](#04-modelling-logic-constraints)
- [Conditional Constraints (Channeling, Reification)](#04-modelling-conditional-constraints)
- [AllDifferent](#04-modelling-alldifferent)
- [Absolute Values and Max/Min](#04-modelling-absmaxmin)
- [Multiplication, Division, and Modulo](#04-modelling-multdivmod)
- [Circuit/Tour-Constraints](#04-modelling-circuit)
- [Interval/Packing/Scheduling Constraints](#04-modelling-intervals)
- [Piecewise Linear Constraints](#04-modelling-pwl)

<a name="04-modelling-variables"></a>

### Variables

There are two important types of variables in CP-SAT: Booleans and Integers
Expand Down Expand Up @@ -683,6 +698,8 @@ infeasibility. In such scenarios, having named variables can significantly
enhance the clarity of the internal representation, making your debugging
process much more manageable.

<a name="04-modelling-domain-variables"></a>

#### Domain Variables

When dealing with integer variables that you know will only need to take certain
Expand Down Expand Up @@ -733,6 +750,8 @@ only take on the values specified in `domain`. This method is particularly
useful when you are working with variables that only have a meaningful range of
possible values within your problem's context.

<a name="04-modelling-objectives"></a>

### Objectives

Not every problem actually has an objective, sometimes you only need to find a
Expand Down Expand Up @@ -791,6 +810,8 @@ model.Minimize(abs_x)

The available constraints are discussed next.

<a name="04-modelling-linear-constraints"></a>

### Linear Constraints

These are the classical constraints also used in linear optimization. Remember
Expand Down Expand Up @@ -823,6 +844,8 @@ use the explicit `!=` constraints.
> of floating point arithmetic. In CP-SAT, you have to make sure that values can
> match exactly.
<a name="04-modelling-logic-constraints"></a>

### Logical Constraints (Propositional Logic)

You can actually model logical constraints also as linear constraints, but it
Expand All @@ -842,6 +865,8 @@ model.AddImplication(b1, b2) # b1 -> b2
In this context you could also mention `AddAtLeastOne`, `AddAtMostOne`, and
`AddExactlyOne`, but these can also be modelled as linear constraints.

<a name="04-modelling-conditional-constraints"></a>

### Conditional Constraints (Channeling, Reification)

Linear constraints (Add), BoolOr, and BoolAnd support being activated by a
Expand All @@ -858,6 +883,8 @@ model.Add(x + z == 2 * y).OnlyEnforceIf(b1)
model.Add(x + z == 10).OnlyEnforceIf([b2, b3.Not()]) # only enforce if b2 AND NOT b3
```

<a name="04-modelling-alldifferent"></a>

### AllDifferent

A constraint that is often seen in Constraint Programming, but I myself was
Expand Down Expand Up @@ -907,6 +934,8 @@ Maybe CP-SAT will allow you to use `AllDifferent` without any performance
penalty in the future, but for now, you have to be aware of this. See also
[the optimization parameter documentation](https://github.com/google/or-tools/blob/1d696f9108a0ebfd99feb73b9211e2f5a6b0812b/ortools/sat/sat_parameters.proto#L542).

<a name="04-modelling-absmaxmin"></a>

### Absolute Values and Max/Min

Two often occurring and important operators are absolute values as well as
Expand Down Expand Up @@ -962,6 +991,8 @@ issues from improperly applied optimizations frequently requires more time than
applying these techniques initially to a model that uses the less efficient
constraints.

<a name="04-modelling-multdivmod"></a>

### Multiplication, Division, and Modulo

A big nono in linear optimization (the most successful optimization area) are
Expand Down Expand Up @@ -997,6 +1028,8 @@ exact function you had in mind.
> variables is supported, but I got an error when trying it out. I have not
> investigated this further, as I would expect it to be painfully slow anyway.
<a name="04-modelling-circuit"></a>

### Circuit/Tour-Constraints

The
Expand Down Expand Up @@ -1157,6 +1190,8 @@ eucl. distance) from the TSPLIB with a time limit of 90 seconds.
| lin318 | 318 | 92.43 | 41915 | 52025 | 19% |
| pr439 | 439 | 94.22 | 105610 | 163452 | 35% |

<a name="04-modelling-array"></a>

### Array operations

You can even go completely bonkers and work with arrays in your model. The
Expand All @@ -1176,6 +1211,8 @@ model.AddElement(index=i, variables=[x, y, z], target=ai)
model.AddInverse([x, y, z], [z, y, x])
```

<a name="04-modelling-intervals"></a>

### Interval Variables and No-Overlap Constraints

A special case of variables are the interval variables, that allow to model
Expand Down Expand Up @@ -1499,6 +1536,8 @@ solver.parameters.use_pairwise_reasoning_in_no_overlap_2d = True
With the latest version of CP-SAT, I did not notice a significant difference in
performance when using these parameters.

<a name="04-modelling-pwl"></a>

### Non-Linear Constraints/Piecewise Linear Functions

In practice, you often have cost functions that are not linear. For example,
Expand Down
7 changes: 6 additions & 1 deletion build.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,14 @@ def convert_for_mdbook(content):
content = content.replace(":warning:", "⚠️")
# replace all anchor links `(#01-installation)` by `(./01_installation.md)`.
# you have to replace the `#` with `./` and `-` with `_`, and attach `.md` at the end.
def replace_relative(match):
md_path = match.group(1).replace("-", "_") + ".md"
if Path(md_path).exists():
return f"(./{md_path})"
return f"(#{match.group(1)})"
content = re.sub(
r"\(#(.*?)\)",
lambda match: "(./" + match.group(1).replace("-", "_") + ".md)",
replace_relative,
content,
)
# replace in all links that lead to a .png file the `github.com` with `raw.githubusercontent.com`.
Expand Down

0 comments on commit 5193b39

Please sign in to comment.