d-krupke
commented
2 months ago You are making a good point and this is something I have actually been thinking about, too, the last two weeks. This has already been reflected by the fact that I removed "Cheat Sheet" from the title.
The primer actually started as a cheat sheet of maybe 4 pages for my students to help them with their exercises. It then grew to become a "primer", and now it is has grown even more. New sections were usually added whenever I needed to show my students how to do a certain thing and then I just added it to the primer, too, so I can easily reuse it. However, there have been too many additions without caring about the overall structure and this needs to change to make it accessible again.
I love your idea with Part 1 and Part 2, and the other points seem to be good, too. I try to make an action plan, soon. Unfortunately, my vacation days are over and I have to somehow squeeze it in between my other responsibilities, but I am eager to finally fix the structure of the primer.
leonlan
Prelude
Here's my understanding of the CP-SAT Primer book.
The CPSAT-Primer book is an introduction to Google OR-Tools' CP-SAT solver. The book covers the whole of CP-SAT's modeling interface (chapter 2-5) and basics related to solving such as parameters and logging (chapter 6-7). There are many examples that showcase how to use CP-SAT to solve combinatorial optimization problems (primarily knapsack and TSP). The details of how CP-SAT works are briefly discussed in chapter 10, and as you humbly acknowledge, the linked resources do a great job at explaining the inner workings of CP-SAT. Since CP-SAT is a solver portfolio of many sophisticated techniques, it only makes sense that this is not explained in detail in CP-SAT Primer. Furthermore, the book is also a collection of meta-skills related to solving optimization problems: coding patterns (chapter 8), developing an optimization API (chapter 9), benchmarking (chapter 12), etc. I am a big fan of this book, because I personally have been going through all these steps myself and I would have benefited a lot from a book like this early in my PhD.
Discussion point
My main discussion point is: what is the CP-SAT Primer book exactly, and what is its intended audience? It can be a bit confusing for readers what to expect from this book because, from what I perceived, it is an introduction of CP-SAT and related topics that you have encountered in your work as well. Because that is not explicitly mentioned anywhere and the sections are interwoven, I got quite confused about this, and I also recognize that this is an "organic growth" process that the book is going through.
Suggestions
I have the following two suggestions to improve clarity regarding "what to expect."
Restructure the sections
I think it would be helpful to make a more clear distinction between the sections related to CP-SAT and other topics. Based on the title and introduction, I would expect mostly topics on CP-SAT.
Part 1: Introduction to CP-SAT
Part 2: Software skills for optimization (or something else
Part 2 is much more advanced and not really relevant immediately for those who just want to get an introduction to CP-SAT. The topics are, however, extremely relevant, but it having this structure allows readers to much easier cherry-pick what they want to read.
Restructure "Introduction"
The current intro is structured like this:
I think this kind of structure is clearer:
Opinion not to be taken harsh: you provide a lot of helpful recommendations but they sometimes distract from the main text to "get to the point." The introduction has a similar build-up and I'll point it out in other chapters once I get to creating the issues related to those chapters.
(PS: In the coming days, I will make separate issues for other, overarching discussion points. For collections of improvements related to a single chapter I will also make individual issues.)