feat: add shuffle feature to array with power of two size

[manel1874]

This PR introduces support for array shuffling for arrays with size as a power of two.

Apart from this it also:

• isort changed some ordering of the imports in some files.

Tests

One test added to tests/nada-tests. It tests arrays of Rational, SecretRational, PublicInteger and SecretInteger To run them use:

nada test shuffle

[jcabrero]

Great work. I had never seen an implementation of Benes Networks and yours seems very clear. Two small nits:

• We could have array.shuffle() as a primitive in array.py. Though it may not match Numpy, I think it prevents users from not finding the available routine.
• I also think this deserves an example in itself, as it is the basis for many card-games or things users may want to implement.

[manel1874]

Missing closing: ```

[manel1874]

We could have array.shuffle() as a primitive in array.py. Though it may not match Numpy, I think it prevents users from not finding the available routine.

Ok, I will add this. Thanks.

[manel1874]

I also think this deserves an example in itself, as it is the basis for many card-games or things users may want to implement.

What do you mean by an example? I have an example in the function docs but I assume you are referring to more than that. Are you proposing to add an example to the examples folder?

[oceans404]

hey @manel1874! I think @jcabrero is asking you to create an example program using shuffling in our nada-by-example repo. Then I can add it to the docs!

here's how: https://github.com/NillionNetwork/nada-by-example?tab=readme-ov-file#add-a-new-example

[jcabrero]

Yes, you can copy the example in the docstring both into the examples folder and in nada-by-example. In that way, users have a direct way of knowing the shuffle primitive is there.

[jimouris]

@manel1874 instead of checking that shuffled_method_a - shuffled_method_a == 0, can we loop over all the elements of the original array and the shuffle version and assert that not everything is equal? (i.e., at least two have been swapped). The equality to zero doesn't guarantee us anything -- the elements may not have been swapped at all, or even we may have completely different elements, both these would pass.

[manel1874]

Agree! Thanks. So, ideally we would test three properties:

1. Randomness: we can use your idea here. We test it by showing that at least one element is in a different position. This gives us a bit more confidence than the current method but this test might fail, although with a very low probability: the same configuration can happen with the same probability as any other.
2. The elements are preserved: agree!

[manel1874]

Follow-up PR for reference #72