Cookbook ideas for "Science" section

[ludwigpacifici]

trafficstars

Section 16 Science

• [ ] Trigonometry
• [ ] Distance between points
• [ ] Statistics
• [ ] Complex Numbers
• [ ] Big Integer
• [ ] Matricies Series

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

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

Manipulation

5. 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:

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

Big Numbers

7. 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.

• Add two vectors
• Norm of two vectors
• A vector time a matrix
• Add, multiply two matrix
• invert a Matrix
• A scalar time a vector time a matrix
• Serialize/Deserialize a big matrix

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]

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:

• How basic do we want to get with the examples
  • Should we include an example that would be a oneliner from std? - IDK.
• What is our preferencje in terms of std vs crates
  • If there is a duplication of readily available functions between std and crate like in some cases with num or chrono. - I'd probably just go with std unless the crate provides some significant advantage (usability/conciseness/error handling/speed/etc.)
  • Do we write some common algorithms from scratch Rossetta code style or try to use specialized crates as much as possible? - This one has me in a pickle, I'd probably try to use dedicated crates if available and popular. Some seemingly simple scientific domains are surprisingly easy to get wrong like statistics.
• How do we choose crates for inclusion -
  • While the 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.
  • 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?:
    • ndarray
    • nalgebra
    • matrix
    • streaming-stats
    • statistical
    • ...

I'd love to hear your thoughts cc @aturon

[ludwigpacifici]

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]

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]

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]

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]

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

• I am on board with highlighting the num crate as a beginning.
• Calculating geometry with Trigonometric functions would be welcomed.
• I remember using sine/cos to draw a circle was a pretty good mathematics example we could show
• +1 for Distance between 2 lat/long.
• Let's table activation functions for now
• +1 for Statistics
• precision is too simple an example for the Cookbook
• +1 Complex Numbers
• +1 BigInt
• 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/)
  • various vector math recipes
  • various matrix recipes
  • serailze matrix

[budziq]

:+1:

[ludwigpacifici]

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

[budziq]

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

[ludwigpacifici]

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

[carrascomj]

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.