search

rust-lang-nursery / rust-cookbook

https://rust-lang-nursery.github.io/rust-cookbook
Creative Commons Zero v1.0 Universal
2.25k stars 284 forks source link

Cookbook ideas for "Science" section #362

Open ludwigpacifici opened 6 years ago

ludwigpacifici commented 6 years ago

Section 16 Science

EDIT - Some ideas here are not accepted yet, please comment here and wait for separate "example" implementation issues before submitting a PR :+1:

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

  1. cosinus, sinus with Rust primitives (f32, f64) or/and with num. Highlight the differences between the two?
  2. Compute distance latitude/longitude points. Good example to show trigonometric functions.
  3. Implement some activation functions to highlight exp, log, tan(h), max, abs. Activation functions are used in neural networks and in computer chip circuits.

Simple statistics

  1. For a given data series, compute the average, the median, the standard deviation and the mode

Manipulation

  1. truncate/round decimal number to a lower precision. Take into account a precision, i.e.
    • precision 1: 1/3 = 0
    • precision 2: 1/3 = 0.3, and so forth.

Complex numbers

via num crate, show some usage of complex numbers.

Geometry examples:

  1. 3 points are collinear (they are aligned). 2 lines are perpendicular. 2 lines are parallel.

Big Numbers

  1. Compute factorial or Fibonacci which yield a big number (bigger than u128). num crate has BigInt 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.

budziq commented 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:

I'd love to hear your thoughts cc @aturon

ludwigpacifici commented 6 years ago

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:

  1. TL;DR - Good for recipe discoverability
  2. Issue - Few lines that will set the context of the Rust snippet
  3. Solution - Code
  4. Going Further - Give more information about usability/conciseness/error handling/speed/etc.

A dummy example:

  1. Show how basic usage of mathematics functions, such as cos, sin, abs, etc. (from std)
  2. Compute distance latitude/longitude points
  3. Mostly Rust code here and comments if necessary
  4. Discuss num crate and explain if it provides quicker/more precise computations.

It starts getting late here :-) I'll think of other comments tomorrow.

ludwigpacifici commented 6 years ago

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.

budziq commented 6 years ago

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:

  1. TL;DR - Good for recipe discoverability
  2. Issue - Few lines that will set the context of the Rust snippet
  3. Solution - Code
  4. 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

ludwigpacifici commented 6 years ago

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:

  1. TL;DR - Good for recipe discoverability
  2. Issue - Few lines that will set the context of the Rust snippet
  3. Solution - Code
  4. 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.

AndyGauge commented 6 years ago

So I think we are ready to create a science section!

budziq commented 6 years ago

:+1:

ludwigpacifici commented 6 years ago

Reddit redirecting to blog post can be an inspiration for the science section?

budziq commented 6 years ago

Very cool idea @ludwigpacifici ! Would you like to propose some example topics?

ludwigpacifici commented 5 years ago

@budziq sure! #452 is ready. I will try to provide few more examples.

carrascomj commented 3 years ago

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.