Open ludwigpacifici opened 6 years ago
Thanks a lot @ludwigpacifici! I've just edited your post so that someone will not working on these examples before we have a chance to discuss them :+1:
In general we are thinking about adding whole "Science" chapter to the cookbook (hence issue renaming).
This might be a good moment to stop and think about fundamental aspects of future cookbook work:
num
crate seams to be current community consensus for basic mathematics (both number of downloads, names on the maintainer list and being targeted for libzBlitz working towards its advantage) the rest of the scientific (and not only these) crates are not so easily chosen.I'd love to hear your thoughts cc @aturon
You're welcome @budziq ! You highlight well thought and broader remarks. My opinion below:
Should we include an example that would be a oneliner from std? - IDK.
A oneliner recipe does not bring lots of value in the cookbook. I feel, it is for very beginner reader who wish to know how to call a function (which is covered in the first chapters of RBE).
However, they can be surprising! For example, I was not expecting to find "basic mathematics functions" in Rust std floats (I am coming form a C++ background). Maybe, I am still too beginner in Rust. But it's not enough to put it in a recipe ; Cookbook is about solving some small problems, not discovering libraries/API.
If it can be highlighted in a useful problem, then it could be a candidate for a recipe. For example, still with "basic mathematics": compute distance latitude/longitude points.
I'd probably just go with std unless the crate provides some significant advantage (usability/conciseness/error handling/speed/etc.)
This could be another reason to highlight oneliner function. This leads me to the question: how to design recipes? I don't know if it was already discussed. A simple approach:
A dummy example:
cos
, sin
, abs
, etc. (from std)num
crate and explain if it provides quicker/more precise computations. It starts getting late here :-) I'll think of other comments tomorrow.
Additional small comments:
Do we write some common algorithms from scratch Rossetta code style or try to use specialized crates as much as possible? ...
I agree with you. Some problem can look simple (like computing an average) but the devil is in the details (average of 0 values, average of big values, precision, etc.). I expect to find robust algorithm in a dedicated crate.
How do we choose crates for inclusion [...] number of downloads, names on the maintainer list and being targeted for libzBlitz working towards its advantage
👍
The ecosystem is not super mature. What if there are no clear crate winners based on the previously mentioned metrics? Do we pool the community? Should we use?
Once mature, the book should not require lots of editing. If there is no clear consensus on the crate to use, better postpone it.
Thanks for the feedback @ludwigpacifici !
Here are some thoughts:
Cookbook is about solving some small problems, not discovering libraries/API.
I'd say that cookbook is both aimed at solving problems (not necessarily small) as well as providing a set of building blocks for software developers and helping the young ecosystem bootstrap itself. So improving discoverability is certainly one of the project goals!
This could be another reason to highlight oneliner function. This leads me to the question: how to design recipes? I don't know if it was already discussed. A simple approach:
- TL;DR - Good for recipe discoverability
- Issue - Few lines that will set the context of the Rust snippet
- Solution - Code
- Going Further - Give more information about usability/conciseness/error handling/speed/etc.
:+1: Very cool the "compute distance latitude/longitude points" idea look like a good example to showoff the basic maths capabilities of std
although I'd probably link to a more authoritative (or at least subject matter related) web resource. FWIW I'd implement at least this example along with some complex and bigint examples.
Some problem can look simple (like computing an average) but the devil is in the details (average of 0 values, average of big values, precision, etc.). I expect to find robust algorithm in a dedicated crate.
There is always a thin line to decide such things, with subjects that are easy to get wrong I'd certainly try to promote a known robust solution.
Once mature, the book should not require lots of editing.
This might not be the case. I expect that cookbook might require some upkeep to reflect the changes in the language (e.g. the recent addition of for_each
) or the crate ecosystem (crate being abandoned/unmaintained, another one or superseding it - see failure as possible replacement for error-chain , etc.).
If there is no clear consensus on the crate to use, better postpone it.
I'm inclined to agree. On the other hand we might like to have a structured and accessible wishlist for community to edit / contribute to / upvote. Some of the ideas might be ready for implementation and some marked as blocked.
cc @aturon
Thanks @budziq. I general I think you have a sensible approach.
see failure as possible replacement for error-chain
I saw that yesterday on reddit while I was trying to find a good example for #215 :-) It's to soon for now, but for example failure crate can be highlighted in the "going further" section for error-chain recipes.
Sum up some ideas:
On the other hand we might like to have a structured and accessible wishlist for community to edit / contribute to / upvote
Is it an additional wish for #246 being experimented by @jaroslaw-weber ?
This could be another reason to highlight oneliner function. This leads me to the question: how to design recipes? I don't know if it was already discussed. A simple approach:
- TL;DR - Good for recipe discoverability
- Issue - Few lines that will set the context of the Rust snippet
- Solution - Code
- Going Further - Give more information about usability/conciseness/error handling/speed/etc.
Should this discussion continue with #302?
FWIW I'd implement at least this example along with some complex and bigint examples.
Do you think these 3 recipes are safe enough to start the Science section? Later, once we have more news (crate consensus, more mature ecosystem, more feedback, etc.) more recipes will follow.
So I think we are ready to create a science section!
num
crate as a beginning. nalgrebra
was written for physics engines and ndarray
is more general. Let's put ndarray
in Science and I'm hoping someday we will make a Game Programming section. (https://www.reddit.com/r/rust/comments/63wts9/why_are_there_so_many_linear_algebra_crates_which/)
:+1:
Very cool idea @ludwigpacifici ! Would you like to propose some example topics?
@budziq sure! #452 is ready. I will try to provide few more examples.
Resurrecting this thread...
What do you think of Linear Programming examples with https://github.com/jcavat/rust-lp-modeler and/or https://github.com/ztlpn/minilp? Both provide some examples that could be nicely put in the cookbook.
Section 16 Science
Mathematics
Here are a bunch of ideas related to mathematics. Some can be implemented with Rust primitives, other can show how to use the
num
crate. Maybe some other crates can be used, but I am not too familiar with the math crates. Please, if you have additional ideas let me know, I can keep this first post up-to-date.Basic mathematics functions
f32
,f64
) or/and withnum
. Highlight the differences between the two?Simple statistics
Manipulation
1/3 = 0
1/3 = 0.3
, and so forth.Complex numbers
via
num
crate, show some usage of complex numbers.Geometry examples:
Big Numbers
num
crate hasBigInt
concept.Basic algebra
I am not aware of a good crate for this section, so I am not sure this a good candidate for the cookbook. However, here are some ideas.
If you are happy with this, next we can discuss how many recipes/issues can be created, I think several ideas can be fitted in one recipe.