# Tutorials¶

We demonstrate the use of Conjure for some small problems.

## Number puzzle¶

Authors: András Salamon, Özgür Akgün

We first show how to solve a classic word addition puzzle, due to Dudeney [Dud24]. This is a small toy example, but already illustrates some interesting features of Conjure.

```   SEND
+  MORE
-------
= MONEY
```

Here each letter represents a numeric digit in an addition, and we are asked to find an assignment of digits to letters so that the number represented by the digits SEND when added to the number represented by MORE yields the number represented by MONEY.

### Initial model¶

We are looking for a mapping (a function) from letters to digits. We can represent the different letters as an enumerated type, with each letter appearing only once.

```language Essence 1.3
letting letters be new type enum {S,E,N,D,M,O,R,Y}
find f : function letters --> int(0..9)
such that
1000 * f(S) + 100 * f(E) + 10 * f(N) + f(D) +
1000 * f(M) + 100 * f(O) + 10 * f(R) + f(E) =
10000 * f(M) + 1000 * f(O) + 100 * f(N) + 10 * f(E) + f(Y)
```

Each Essence specification can optionally contain a declaration of which dialect of Essence it is written in. The current version of Essence is 1.3. We leave out this declaration in the remaining examples.

This model is stored in `sm1.essence`; let’s use Conjure to find the solution:

```conjure solve -ac sm1.essence
```

Unless we specify what to call the solution, it is saved as `sm1.solution`.

```letting f be function(S --> 0, E --> 0, N --> 0, D --> 0, M --> 0, O --> 0, R --> 0, Y --> 0)
```

This is clearly not what we wanted. We haven’t specified all the constraints in the problem!

### Identifying a missing constraint¶

In these kinds of puzzles, usually we need each letter to map to a different digit: we need an injective function. Let’s replace the line

```find f : function letters --> int(0..9)
```

by

```find f : function (injective) letters --> int(0..9)
```

and save the result in file `sm2.essence`. Now let’s run Conjure again on the new model:

```conjure solve -ac sm2.essence
```

This time the solution `sm2.solution` looks more like what we wanted:

```letting f be function(S --> 2, E --> 8, N --> 1, D --> 7, M --> 0, O --> 3, R --> 6, Y --> 5)
```

### Final model¶

There is still something strange with `sm2.essence`. We usually do not allow a number to begin with a zero digit, but the solution maps M to 0. Let’s add the missing constraints to file `sm3.essence`:

```letting letters be new type enum {S,E,N,D,M,O,R,Y}
find f : function (injective) letters --> int(0..9)
such that
1000 * f(S) + 100 * f(E) + 10 * f(N) + f(D) +
1000 * f(M) + 100 * f(O) + 10 * f(R) + f(E) =
10000 * f(M) + 1000 * f(O) + 100 * f(N) + 10 * f(E) + f(Y)

such that f(S) > 0, f(M) > 0
```

Let’s try again:

```conjure solve -ac sm3.essence
```

This now leads to the solution we expected:

```letting f be function(S --> 9, E --> 5, N --> 6, D --> 7, M --> 1, O --> 0, R --> 8, Y --> 2)
```

Finally, let’s check that there are no more solutions:

```conjure solve -ac sm3.essence --number-of-solutions=all
```

This confirms that there is indeed only one solution. As an exercise, verify that the first two models have multiple solutions, and that the solution given by the third model is among these. (The first has 1155 solutions, the second 25.)

## Nurse rostering¶

Authors: András Salamon, Nguyen Dang, Saad Attieh

We now discuss a version of Nurse Rostering <https://en.wikipedia.org/wiki/Nurse_scheduling_problem>, a constrained scheduling problem. Variants of this problem are also known by other names, such as workforce planning and staff scheduling. Unlike versions of this problem studied by operations research practitioners and researchers (such as competition instances [CDDC+19]), we here focus on just a few of the simplest constraints.

Some nurses are available to work in a hospital. Each day is divided into a sequence of shifts, for instance an early-morning shift, a day shift, and a night shift. Each nurse should be assigned to work some shifts during the course of a period of consecutive days. A nurse can be assigned to at most one shift per day. Moreover, for each nurse we need to avoid some forbidden shift patterns within two consecutive days. For example, a nurse cannot work a night shift on one day, and an early-morning shift the next day. We also must make sure to meet the minimum number of nurses required for each shift. These demand values may vary between different days.

### Initial specification¶

To begin with, let’s ignore the forbidden patterns, and focus instead on the elements needed to model the problem. We need nurses, shifts for each day, the minimum demand, and a roster.

```given nNurses, nDays : int(1..)
given shifts new type enum
letting days be domain int(1..nDays)
letting nurses be domain int(1..nNurses)
letting nShifts be |`shifts`|
given forbiddenPatterns : set of tuple (shifts, shifts)
given minimumDemand : function (total) (days, shifts) --> int(0..nNurses)
where
forAll d : days .
(sum s : shifts . minimumDemand((d,s))) <= nNurses

find roster: function (days, shifts) --> nurses
\$ constraint 1 (Single assignment per day)
\$ a nurse can be assigned to at most one shift per day
such that
forAll nurse : nurses .
forAll day : days .
(sum ((d,_),n) in roster . toInt(n=nurse /\ d=day)) <= 1
```

This specification contains the basic elements. We made the choice to use an enumerated type for shifts, positive integers to number the nurses and the days, a set of forbidden patterns (each being a pair of shifts), and a total function mapping each shift slot to a number of nurses to represent the minimum demands. Because we only allow a nurse to work one shift each day, the forbidden patterns can only apply to one day and the next day, with the first shift in a forbidden pattern referring to the first day and the second shift referring to the subsequent day. We also added a `where` condition to ensure that instances are not trivially impossible, by requiring the minimum demand to never exceed the number of nurses.

We also need a test instance. Generating test instances is an interesting subject (for instance, see [AkgunDM+19]) but here we have just made one up.

```letting nNurses be 5
letting nDays be 7
letting shifts be new type enum {Early, Late, Night}
letting forbiddenPatterns be {
(Late,Early), (Night,Early), (Night,Late)
}
letting minimumDemand be function (
(1,Early) --> 2, (1,Late) --> 2, (1,Night) --> 0,
(2,Early) --> 1, (2,Late) --> 1, (2,Night) --> 2,
(3,Early) --> 1, (3,Late) --> 1, (3,Night) --> 1,
(4,Early) --> 0, (4,Late) --> 0, (4,Night) --> 1,
(5,Early) --> 1, (5,Late) --> 1, (5,Night) --> 2,
(6,Early) --> 2, (6,Late) --> 1, (6,Night) --> 1,
(7,Early) --> 0, (7,Late) --> 1, (7,Night) --> 1
)
```

We have 5 nurses, 7 days in the period, three shifts each day, three forbidden pairs of shifts, and some minimum demands for the various shifts.

### Changing an overly restrictive assumption¶

However, on further reflection this first specification is not correct. Since roster is a function `(days, shifts) --> nurses` only one nurse can be assigned to the same shift of the same day. This means that if the minimum demand asks for 2 or more nurses for a particular day and shift, then we can’t satisfy this demand. We need to remove the overly restrictive assumption enforced by our choice of representation for `roster`.

Let’s change the representation of `roster`, leaving the specification exactly the same up to and including the `where` condition. Instead of mapping each day/shift pair to a single nurse, we could map each day/shift pair to a set of nurses, map each nurse to a set of day/shift pairs, or map each combination of day and nurse to a shift (but with not all combinations needing to be assigned). Each of these choices leads to a slightly different way to model the problem; here we have picked the last. It is left as an exercise to try the others!

```find roster: function (days, nurses) --> shifts
\$ constraint 1 (Single assignment per day)
\$ a nurse can be assigned to at most one shift per day
\$ NOTE: automatically satisfied because of how "roster" is defined

\$ constraint 2 (Under staffing)
\$ the number of nurses for each shift suffice for the minimum demand
such that
forAll day : days .
forAll shift : shifts .
(sum ((d,_),s) in roster . toInt(d=day /\ s=shift))
>= minimumDemand((day,shift))

\$ constraint 3 (Shift type successions)
\$ the shift type assignments of one nurse on two consecutive days
\$ must not violate any forbidden succession
such that
forAll d : int(1..(nDays-1)) .
forAll n : nurses .
!((roster(d,n), roster(d+1,n)) in forbiddenPatterns)
```

Note that in this specification, the first constraint is automatically satisfied because of the way we have defined `roster` as a function from a day/nurse pair to a shift. So changing the representation of `roster` has not only removed the overly restrictive assumption that only one nurse can be assigned to a day/shift pair, but also dealt with the first real constraint.

We have added a second constraint to enforce the minimum demand for each shift, by requiring that the number of nurses mapped to each day/shift pair is at least as large as the minimum demand for that day/shift pair.

Finally, we have added a third constraint to ensure that forbidden shift patterns do not occur.

### Final model¶

Unfortunately, the second specification is not accepted by Conjure. The `roster` function is expecting a single pair as its argument, but we have given two arguments (a day and a nurse). We replace the last constraint by a version that corrects this syntax error:

```\$ constraint 3 (Shift type successions)
\$ the shift type assignments of one nurse on two consecutive days
\$ must not violate any forbidden succession
such that
forAll d : int(1..(nDays-1)) .
forAll n : nurses .
!((roster((d,n)), roster((d+1,n))) in forbiddenPatterns)
```

This is a specification that is acceptable to Conjure and which captures the key constraints we wanted to include.

Assuming that the third specification is in file `model3.essence` and the test instance in file `test.param`, we can run Conjure to solve the instance.

```conjure solve -ac model3.essence test.param
```

Without any specification, the default solver is Minion [CDDC+19], a constraint programming solver. After quite some time, this creates the following solution:

```letting roster be function(
(1, 2) --> Early, (1, 3) --> Early, (1, 4) --> Late,  (1, 5) --> Late,
(2, 2) --> Early, (2, 3) --> Late,  (2, 4) --> Night, (2, 5) --> Night,
(3, 2) --> Early, (3, 3) --> Late,  (3, 4) --> Night, (4, 5) --> Night,
(5, 2) --> Early, (5, 3) --> Late,  (5, 4) --> Night, (5, 5) --> Night,
(6, 1) --> Early, (6, 2) --> Early, (6, 3) --> Late,  (6, 4) --> Night,
(7, 4) --> Night, (7, 5) --> Late)
```

A much faster way to obtain a solution is to ask Minion to use the `domoverwdeg` variable ordering, which is often effective on constrained scheduling problems:

```conjure solve -ac --solver-options='-varorder domoverwdeg' model3.essence test.param
```

Choosing the right parameters to control solver behaviour is important but not generally well understood, and we leave discussion of this problem for another time.

## Labelled connected graphs¶

Author: András Salamon (with thanks to Roy Dyckhoff for proofreading)

We now illustrate the use of Conjure for a more realistic modelling task, to enumerate all labelled connected graphs. The number of labelled connected graphs over a fixed set of n distinct labels grows quickly; this is OEIS sequence A001187.

We first need to decide how to represent graphs. A standard representation is to list the edges. One natural representation for each edge is as a set of two distinct vertices. Vertices of the graph are labelled with integers between 1 and n, and each vertex is regarded as part of the graph, whether there is some edge involving that vertex or not.

```letting n be 4
letting G be {{1,2},{2,3},{3,4}}
```

In this specification, we declare two aliases. The number of vertices n is first defined as 4. Then G is defined as a set of edges.

This specification is saved in a file `path-4.param` that we refer to later. We should also have a different graph that is not connected:

```letting n be 4
letting G be {{1,2},{4,3}}
```

which is saved in file `disconnected-4.param`.

We now need to express what it means for a graph to be connected.

### Model 1: distance matrix¶

In our first attempt, we use a matrix of distances. Each entry `reach[u,v]` represents the length of a shortest path from u to v, or n if there is no path from u to v. To enforce this property, we use several constraints, one for each possible length; there are four ranges of values we need to cover. A distance of 0 happens when u and v are the same vertex. A distance of 1 happens when there is an edge from u to v. When the distance is greater than 1 but less than n, then there must be some vertex that is a neighbour of u from which v is reachable in one less step. Finally, the distance of n is used when no neighbour of u can reach v (and in this case, the neighbours all have distance of n to v as well).

```given n : int(1..)
letting vertices be domain int(1..n)
given G : set of set (size 2) of vertices
find reach : matrix indexed by [vertices, vertices] of int(0..n)
such that
forAll u,v : vertices .
((reach[u,v] = 0) -> (u=v))
/\ ((reach[u,v] = 1) -> ({u,v} in G))
/\ (((reach[u,v] > 1) \/ (reach[u,v] < n)) ->
(exists w : vertices . ({u,w} in G) /\ (reach[w,v] = reach[u,v] - 1)))
/\ ((reach[u,v] = n) -> (forAll w : vertices . !({u,w} in G) \/ (reach[w,v] = n)))
find connected : bool
such that
connected = (forAll u,v : vertices . reach[u,v] < n)
```

This is stored in file `gc1.essence`. The values of n and G will be specified later as parameters, such as via the `path-4.param` or `disconnected-4.param` files.

In the model, first the matrix `reach` is specified by imposing the four conditions that we mentioned. Finally a Boolean variable is used to conveniently indicate whether the `reach` matrix represents a connected graph or not; in a connected graph every vertex is reachable from every other vertex.

Let’s now try this model with the two graphs defined so far.

```conjure solve -ac gc1.essence path-4.param
conjure solve -ac gc1.essence disconnected-4.param
```

In the solutions found by Conjure, the matrix `reach` indicates the distances between each pair of vertices. In the solution for the connected graph `gc1-path-4.solution` all entries are at most 3.

```letting connected be true
letting reach be
[[0, 1, 2, 3; int(1..4)], [1, 0, 1, 2; int(1..4)],
[2, 1, 0, 1; int(1..4)], [3, 2, 1, 0; int(1..4)]; int(1..4)]
\$ Visualisation for reach
\$ 0 1 2 3
\$ 1 0 1 2
\$ 2 1 0 1
\$ 3 2 1 0
```

In contrast, in the solution for the disconnected graph `gc1-disconnected-4.solution` there are some entries that are 4:

```letting connected be false
letting reach be
[[0, 1, 4, 4; int(1..4)], [1, 0, 4, 4; int(1..4)],
[4, 4, 0, 1; int(1..4)], [4, 4, 1, 0; int(1..4)]; int(1..4)]
\$ Visualisation for reach
\$ 0 1 4 4
\$ 1 0 4 4
\$ 4 4 0 1
\$ 4 4 1 0
```

Graphs with four vertices are good for quick testing but are too small to notice much difference between models. Small differences are important for tasks such as enumerating many objects, when even a small difference is multiplied by the number of objects. For testing we can create other parameter files containing graphs with more vertices. Notice that we do not have to change the model, only the parameter files containing the input data.

Testing with larger graphs of say 1000 vertices, it becomes clear that this first model works but does not scale well. It computes the lengths of the shortest paths between pairs of vertices, from which we can deduce whether the graph is connected. This is quite round-about! We can now try to improve the model by asking the system to do less work. After all, we don’t actually need all the pairwise distances.

### Model 2: reachability matrix¶

In the following model, stored as file `gc2.essence`, the reachability matrix uses Boolean values for the distances rather than integers, with `true` representing reachable and `false` unreachable. Each entry `reach[u,v]` represents whether it is possible to reach v by some path that starts at u. This is modelled as the disjunction of three conditions: u is reachable from itself, any neighbour of u is reachable from it, and if v is not a neighbour of u then there should be a neighbour w of u so that v is reachable from w.

```given n : int(1..)
letting vertices be domain int(1..n)
given G : set of set (size 2) of vertices
find reach : matrix indexed by [vertices, vertices] of bool
such that
forAll u,v : vertices . reach[u,v] =
((u = v) \/ ({u,v} in G) \/
(exists w : vertices . ({u,w} in G) /\ reach[w,v]))
find connected : bool
such that
connected = (forAll u,v : vertices . reach[u,v])
```

In the solutions found by Conjure, the reachability matrix contains regions of true entries indicating the connected components.

In the connected graph all entries are true:

```letting connected be true
letting reach be
[[true, true, true, true; int(1..4)], [true, true, true, true; int(1..4)],
[true, true, true, true; int(1..4)], [true, true, true, true; int(1..4)];
int(1..4)]
\$ Visualisation for reach
\$ T T T T
\$ T T T T
\$ T T T T
\$ T T T T
```

In contrast, in the disconnected graph there are some false entries:

```letting connected be false
letting reach be
[[true, true, false, false; int(1..4)], [true, true, false, false; int(1..4)],
[false, false, true, true; int(1..4)], [false, false, true, true; int(1..4)];
int(1..4)]
\$ Visualisation for reach
\$ T T _ _
\$ T T _ _
\$ _ _ T T
\$ _ _ T T
```

This model takes about half as long as the previous one, but is still rather slow for large graphs.

### Model 3: structured reachability matrices¶

In the previous two models the solver may spend a long time early in the search process looking for ways to reach vertices that are far away, even though it would be more efficient to focus the early stages of search on vertices close by. It is possible to improve performance by guiding the search to consider nearby vertices before vertices that are far from each other. The following model `gc3.essence` uses additional decision variables to more precisely control how the desired reachability matrix should be computed. There are multiple reachability matrices. Each corresponds to a specific maximum distance. The first n by n matrix `reach` expresses reachability in one step, and is simply the adjacency matrix of the graph. The entry `reach[k,u,v]` expresses whether v is reachable from u via a path of length at most 2**k. If a vertex v is reachable from some vertex u, then it can be reached in at most n-1 steps. (Note: in this model a vertex cannot reach itself in zero steps, so a graph with a single vertex is not regarded as connected.)

```given n : int(1..)
letting vertices be domain int(1..n)
given G : set of set (size 2) of vertices
letting m be sum([1 | i : int(0..64), 2**i <= n])
find reach : matrix indexed by [int(0..m), vertices, vertices] of bool
such that
forAll u,v : vertices . reach[0,u,v] = ({u,v} in G),
forAll i : int(0..(m-1)) . forAll u,v : vertices . reach[i+1,u,v] =
(reach[i,u,v] \/ (exists w : vertices . (reach[i,u,w] /\ reach[i,w,v]))),
find connected : bool
such that
connected = (forAll u,v : vertices . reach[m,u,v])
```

The variable m is used to compute the number of matrices that are required; this is the smallest integer that is not less than the base-2 logarithm of n. (This is computed by discrete integration as Conjure currently does not support a logarithm operator; this may change in a future release.) The value of `connected` is then based on whether whether `reach[m]` contains any false entries.

This model is the fastest yet, but it generates intermediate distance matrices, each containing n**2 variables. We omit the solutions here, but they show how the number of true values increases, until reaching a fixed point.

### Model 4: connected component¶

Each of the three models so far deals with all possible pairs of vertices. The number of possible pairs of vertices is quadratic in the number of vertices. However, many graphs are sparse, with a number of edges that is bounded by a linear function of the number of vertices. For sparse graphs, and especially those with many vertices, it is therefore important to only consider the edges that are present rather than all possible pairs of vertices. The next model `gc4.essence` uses this insight, and is indeed faster than any of the three previous ones.

The model builds on the fact that a graph is disconnected if, and only if, its vertices can be partitioned into two sets, with no edges between vertices in the two different sets. Here C is used to indicate a subset of the vertices. There are three constraints. The first is that C must contain some vertex. The second is that C must be a connected component; each vertex in C is connected to some other vertex in C (unless C only contains a single vertex). The third is that the value of `connected` is determined by whether it is possible to find some vertex that is not in C. The following is an attempt to capture these constraints in an Essence specification.

```given n : int(1..)
letting vertices be domain int(1..n)
given G : set of set (size 2) of vertices
find C : set of vertices
find connected : bool
such that
exists u : vertices . u in C,
forAll e in G . (min(e) in C) = (max(e) in C),
connected = !(exists u : vertices . !(u in C))
```

This is the solution for `disconnected-4.param`:

```letting C be {1, 2}
letting connected be false
```

Model `gc4.essence` yields a solution quickly. Unfortunately it can also give incorrect results: letting C be the set of all vertices and letting `connected` be true is always a solution, whether the graph is connected or not. This can be confirmed by asking Conjure to generate all solutions:

```conjure solve -ac --number-of-solutions=all gc4.essence
```

This gives two solutions, the one above and the following one:

```letting C be {1, 2, 3, 4}
letting connected be true
```

It is actually possible to ensure that this “solution” is never the first one generated, and then to ask Conjure to only look for the first solution; if the graph is not connected then the first solution will correctly indicate its status. However, this relies on precise knowledge of the ordering heuristics being employed at each stage of the toolchain.

The problem with this fourth specification is that it only captures the property that C is a union of connected components. We would need to add additional constraints to enforce the property that C should contain only one connected component. This can be done, but is not especially efficent.

### Model 5: minimal connected component¶

Let’s look for a robust approach that won’t unexpectedly fail if parts of the toolchain change which optimisations they perform or the order in which evaluations occur.

One option could be to look for solutions of a more restrictive model which includes an additional constraint that requires some vertex to not be in C. This model would have a solution precisely if the graph is not connected. Failure to find solutions to this model would then indicate connectivity. It is possible to call Conjure from a script that uses the failure to find solutions to conclude connectivity, but the Conjure toolchain currently does not support testing for the presence of solutions directly.

In place of the missing “if-has-solution” directive, we could instead quantify over all possible subsets of vertices. Such an approach quickly becomes infeasible as n grows (and is much worse than the models considered so far), because it attempts to check 2**n subsets.

As another option, we can make use of the optimisation features of Essence to find a solution with a C of minimal cardinality. This ensures that C can only contain one connected component. Choosing a minimal C ensures that when there is more than one solution, then the one that is generated always indicates the failure of connectivity. Since we don’t care about the minimal C, as long as it is smaller than the set of all vertices if possible, we also replace the general requirement for non-emptiness by a constraint that always forces the set C to contain the vertex labelled 1.

```given n : int(1..)
letting vertices be domain int(1..n)
given G : set of set (size 2) of vertices
find C : set of vertices
find connected : bool
such that
1 in C,
forAll e in G . (min(e) in C) = (max(e) in C)
minimising |C|
```

This model `gc5.essence` is still straightforward, even with the additional complication to rule out incorrect solutions. Out of the correct models so far, this tends to generate the smallest input files for the back-end constraint or SAT solver, and also tends to be the fastest.

### Generating all connected graphs¶

We now have a fast model for graph connectivity. Let’s modify it as `gce1.essence`, hardcoding n to be 4 and asking the solver to find G as well as C.

```letting n be 4
letting vertices be domain int(1..n)
find G : set of set (size 2) of vertices
find C : set of vertices
such that
1 in C,
forAll e in G . (min(e) in C) = (max(e) in C)
minimising |C|
```

We now ask for all solutions:

```conjure solve -ac --number-of-solutions=all gce1.essence
```

However, this finds only one solution!

The solver finds one solution that minimises `|C|`; this minimisation is performed globally over all possible solutions. This is what we intended when G was given, but is not what we want if our goal is to generate all connected graphs. We want to minimise C for each choice of G, producing one solution for each G. Currently there is no way to tell Conjure that minimisation should be restricted to the decision variable C.

Checking whether there is a nontrivial connected component seems to be the most efficient model for graph connectivity, but it doesn’t work in the setting of generating all connected graphs. We therefore need to choose one of the other models to start with, say the iterated adjacency matrix representation.

We now use this model of connectivity to enumerate the labelled connected graphs over the vertices `{1,2,3,4}`. Previously we checked connectivity of a given graph G. We now instead ask the solver to find G, specifying that it be connected. We do this by asking for the same adjacency matrix `reach` as before, but in addition asking for the graph G. We also hardcode n, so no parameter file is needed, and add the condition that previously determined the value of the `connected` decision variable as a constraint.

```letting n be 4
letting vertices be domain int(1..n)
find G : set of set (size 2) of vertices
letting m be sum([1 | i : int(0..64), 2**i <= n])
find reach : matrix indexed by [int(0..m), vertices, vertices] of bool
such that
forAll u,v : vertices . reach[0,u,v] = ({u,v} in G),
forAll i : int(0..(m-1)) . forAll u,v : vertices . reach[i+1,u,v] =
(reach[i,u,v] \/ (exists w : vertices . (reach[i,u,w] /\ reach[i,w,v]))),
forAll u,v : vertices . reach[m,u,v]
```

If this model is in the file `gce2.essence`, then we now need to explicitly ask Conjure to generate all the possible graphs:

```conjure solve -ac --number-of-solutions=all gce2.essence
```

In this case Conjure generates 38 solutions, one solution per file.

Instead of listing the edges of a graph, and then deriving the adjacency matrix as necessary, it is also possible to use the adjacency matrix representation. As an exercise, modify the models of connectivity to use the adjacency matrix representation instead of the set of edges representation.