Suggestion on algorithm descriptions

[chelseas]

I think the move from pseudo-code to actual code in the textbook is nice for implementation purposes, but something was lost as well. I think it might be nice to comment the code with explanations with what's going on OR give a straightforward descrip of an algo in the text.

Consider the section on Fibonacci search in the textbook. It doesn't give a straightforward description of how the search works, e.g. you could add something like "In Fibonacci search, we pick successive evaluation points according to the Fibonacci sequence. The first two points are at Fn/Fn-1 and 1 - Fn/Fn-1 along the bracketing interval. At each successive iteration we evaluate one additional point ...we decrement n as the search progresses." Alternatively, comments to the same effect could be added inline to algo 3.2.

What's there currently under section 3.3 gives nice intuition but the closest thing to an algo description is "For n queries, the interval lengths are related to the Fibonacci sequence." Which is a rather vague starting point for the students to come up with an explicit algorithm description from. Algorithm 3.2 is nice, but the caption doesn't explain in enough detail what's going on in each line. Example 3.1 helps, but students still have to generalize from the example to an explicit pseudo-code / algo descrip.

[tawheeler]

Hi Chelsea - thanks for the comment.

So there is always an inherent trade-off between verbosity and compactness. Julia is great in how compact it is. Without it, we would have no hope of presenting an implementation for covariance matrix adaptation on one page. Writing books like this requires a lot of balance between additional things like consistency - keeping how we present everything the same.

Generally, Algorithms for Optimization is a reference text that gives you a basic overview of an approach. We do not have the space to cover all algorithms in the detail they often rightly deserve. We hope to provide enough context for readers to understand things, but know that a deeper understanding can be obtained by following the references we provide, or other sources.

That being said, we probably can improve comments in the code. Unfortunately, we cannot do that everywhere, especially places where we are already constrained. This leads to inconsistencies, but it may be worth it. Furthermore, we are not allowed to change pagination for the book as it is. Adding comments will usually change pagination. As such, changes to this end would have to be made in a larger book overhaul.

It doesn't give a straightforward description of how the search works

I'd like to poke at this a bit. There are two pages dedicated to a description of how Fibonacci search works. Figure 3.6 basically contains everything one needs to know:

Grab two points, spaced according to the Fibonacci sequence and how many points we intend to sample, use those to grab the next point, update, etc.
I agree that going from that figure to the code requires some doing, but what the overall idea is should be fairly well covered.
A picture is worth a thousand words, and writing algorithmic psuedocode out in all cases would cause the book to explode in size (and generally bore the reader).

@mykelk I hope I captured that right, but maybe you have something to add?

[chelseas]

I know you have space constraints and your own stylistic preferences but to me, it just seems a bit odd you would spend all this time in attempt to provide clarity for the reader but forget the most basic thing: a straightforward, declarative description of the algorithm. It's sort of like someone describing why an argument makes sense without actually telling you what the argument is. That picture you point out is definitely helpful but still doesn't provide what I, as a reader, am looking for in a textbook. You may think it would be boring to add a few sentences or a bit of math to give a straightforward algorithm description but I have to disagree. I think it would add essential clarity. In the end, it's your book, but I thought I would just let you know how it reads to me.

…

On Tue, Apr 12, 2022, 2:36 PM Tim Wheeler ***@***.***> wrote: Hi Chelsea - thanks for the comment. So there is always an inherent trade-off between verbosity and compactness. Julia is great in how compact it is. Without it, we would have no hope of presenting an implementation for covariance matrix adaptation on one page. Writing books like this requires a lot of balance between additional things like consistency - keeping how we present everything the same. Generally, *Algorithms for Optimization* is a reference text that gives you a basic overview of an approach. We do not have the space to cover all algorithms in the detail they often rightly deserve. We hope to provide enough context for readers to understand things, but know that a deeper understanding can be obtained by following the references we provide, or other sources. That being said, we probably can improve comments in the code. Unfortunately, we cannot do that everywhere, especially places where we are already constrained. This leads to inconsistencies, but it may be worth it. Furthermore, we are not allowed to change pagination for the book as it is. Adding comments will usually change pagination. As such, changes to this end would have to be made in a larger book overhaul. It doesn't give a straightforward description of how the search works I'd like to poke at this a bit. There are two pages dedicated to a description of how Fibonacci search works. Figure 3.6 basically contains everything one needs to know: [image: image] <https://user-images.githubusercontent.com/3334079/163057802-29381a2c-dd8c-45bf-bafb-ad267f5bfb44.png> Grab two points, spaced according to the Fibonacci sequence and how many points we intend to sample, use those to grab the next point, update, etc. I agree that going from that figure to the code requires some doing, but what the overall idea is should be fairly well covered. A picture is worth a thousand words, and writing algorithmic psuedocode out in all cases would cause the book to explode in size (and generally bore the reader). @mykelk <https://github.com/mykelk> I hope I captured that right, but maybe you have something to add? — Reply to this email directly, view it on GitHub <#58 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADRQXSWFQYT7G57EMJA2FIDVEXUGBANCNFSM5TIPZI6A> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[mykelk]

Thank you for taking your time to share your views because we're always trying to optimize our books. ;-) Tim and I have been discussing a number of different ways to further optimize this one. I agree with Tim's statement about how there is a bit of a tradeoff in how to approach algorithm books. What we aimed for here is an unambiguous declarative description of the algorithms in the form of Julia code. The ability to actually execute the code eliminates any ambiguity. Having written pseudocode and other kinds of algorithmic descriptions in various contexts, I am well aware of the difficulty of communicating complex processes in natural language. So, we try to give the intuition of the algorithms in natural language, and then follow it up with concrete implementations. Although we cannot make significant changes between printings, we have more leeway in adding and modifying content in later editions, so feedback is certainly valued.