built in operators: weighted-pick-elt

weighted-pick-elt:
    description:
        weighted-pick-elt input-sp
        randomly pick a ket from the input superposition
        the probability of being picked is determined by the coefficients of the ket
        the returned ket has the same coefficient as in the input superposition
        for un-weighted probabilities, use pick-elt

    examples:

        -- if applied to an empty ket, return the empty ket:
        weighted-pick-elt |>
            |>

        -- applied to a clean superposition:
        -- it has the same effect as pick-elt:
        weighted-pick-elt split |uvwxyz>
            |w>

        -- applied to a random superposition:
        weighted-pick-elt random[1, 0.7] (|1> .. |10>)
            1.494102|7>


        -- a simple quantum mechanics experiment:
        -- let's first define a superposition, that we can measure one ket at a time:
        the |superposition> => |a> + 0.2|b> + 0.5|c> + 8.1|d> + 0.01|e>

        -- now define the run experiment operator:
        run-experiment |*> #=>
            unlearn[the] |result>
            for( the|k> in |1> .. |__self>):
                measure |system> !=> clean weighted-pick-elt the |superposition>
                the |result> +=> measure |system>
                the |similarity> => simm(the |result>, the |superposition>)
                print (the |k> :_ round[1] extract-value push-float 100 the |similarity>)
            end:
            the |similarity>

        -- now invoke it for 500 trials:
        sa: run-experiment |500>

            1: 82.6
            2: 82.6
            3: 82.6
            4: 82.6
            5: 82.6
            6: 82.6
            7: 82.6
            8: 82.6
            9: 82.6
            10: 87.7
            ...
            494: 95.4
            495: 95.4
            496: 95.6
            497: 95.6
            498: 95.6
            499: 95.5
            500: 95.5
            0.955095|simm>

    see also:
        pick-elt, random