Add tutorial READMEs and fix tutorial return codes

Add README.md files for moeo/tutorial/Lesson{1-4}, smp/tutorial/Lesson{1-4},
and mo/tutorial/Lesson9 — these tutorials had no documentation.

Fix return 1 → return 0 in 28 tutorial main() functions across mo/ and
smp/ that unconditionally returned failure status.
This commit is contained in:
Eremey Valetov 2026-02-28 19:24:05 -05:00
commit c1a44fd2a6
37 changed files with 371 additions and 30 deletions

View file

@ -0,0 +1,48 @@
# Variable Neighborhood Search (VNS)
VNS on the N-Queens problem, using multiple neighborhood structures to
escape local optima.
The N-Queens problem places N queens on an N x N chessboard so that no two
queens attack each other. The representation is a permutation (one queen
per column) and the fitness counts conflicts (minimized).
## Running
From the `build/mo/tutorial/Lesson9` directory:
```shell
./VNS -V=12
```
This runs VNS on a 12-queens instance with a 3-second time limit.
## How it works
VNS alternates between perturbation (shaking) and local search using
different neighborhood structures. Here, two neighborhoods are used:
```c++
shiftNeighborhood shiftNH((vecSize-1) * (vecSize-1));
swapNeighborhood swapNH(vecSize * (vecSize-1) / 2);
```
Each has its own hill-climber and mutation operator:
```c++
moSimpleHC<shiftNeighbor> ls1(shiftNH, fullEval, shiftEval);
moSimpleHC<swapNeighbor> ls2(swapNH, fullEval, swapEval);
moRndVectorVNSelection<Queen> selectNH(ls1, shiftMut, true);
selectNH.add(ls2, swapMut);
```
`moRndVectorVNSelection` randomly picks which neighborhood/local search
to apply at each iteration. Forward (`moForwardVectorVNSelection`) and
backward (`moBackwardVectorVNSelection`) selection strategies are also
available. The search runs until the `moTimeContinuator` time limit:
```c++
moTimeContinuator<shiftNeighbor> cont(3); // 3 seconds
moVNS<shiftNeighbor> vns(selectNH, acceptCrit, fullEval, cont);
```

View file

@ -284,5 +284,5 @@ int main(int argc, char **argv)
catch (exception& e) {
cout << "Exception: " << e.what() << '\n';
}
return 1;
return 0;
}