The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Quantum::Superpositions::Lazy - Weighted QM-like superpositions with lazy evaluation


        use Quantum::Superpositions::Lazy;

        # superpos() accepts a list or an array reference
        my $position_1 = superpos(1 .. 10);
        my $position_2 = superpos(1 .. 10);

        # most standard perl operators are supported
        my $multiplication_plate = $position_1 * $position_2;

        # get something randomly
        my $random_outcome = $multiplication_plate->collapse;


This module allows for creation of superpositions that contain a set of possible states. A superposition is an object that tries to behave as if it was in all of these states at once when used in regular numeric / string operations. Any operation that involves a superposition will yield a new superposition-like calculation object.

Superpositions can be collapsed, which happens when they are stringified or manually upon calling the collapse method. During collapsing, a random element from all the possible outcomes is chosen and saved as a current persistent state of a superposition. For calculations created from superpositions, all the source superpositions are collapsed as well.

Many parts of the module are lazy by nature - they are only calculated as late as possible, which is also how quantum physics work. Those lazily generated states are also persistent - once generated, they will be cached for later (re)use. The most prominent example of that would be the behavior of computations made on superpositions. Instead of generating all the outcomes right away, references to source superpositions and the type of operation are stored. They are only called once the computation is observed (collapsed).

This is mostly where the quantum physics part of the module ends. The rest of the capabilities go beyond that and allow for calculations on uncollapsed superpositions. It's important to note that these calculations are extremely slow by their nature. Adding one of 1000 numbers to one of another 1000 numbers just to get one state randomly is very fast because of the optimizations made. Doing any kind of serious calculations on this volume of data (basically a million objects) is only valid for educational purposes, toy programs and other kinds of not very serious work.


Superpositions and calculations

  • quantum-like superpositions with weighted states, containing any data

  • persistent state after collapsing, manual state clearing

  • superposition objects can be used with most native Perl operators

  • calculation results are objects that reference the source objects

  • collapsing a calculation result also collapses the source superpositions

Complete set of superposition states

  • ability to get a complete set of superposition states, together with their calculated weights (the cartesian product)

  • exporting the states to ket notation

  • extracting statistical data from the superpositions, like the most probable outcome or weighted mean

  • obtaining the sources of each and every state, which is the exact set calculation parameters used to obtain it


Refer to Quantum::Superpositions::Lazy::Manual for a quick tutorial.


superpos is exported by default. :all tag can be used to import everything.



Exported by default. Feeds its arguments to the Quantum::Superpositions::Lazy::Superposition constructor. If the only argument is an array reference, it is passed as-is into the constructor, resulting with a state for every array ref element. Otherwise creates a reference out of the arguments and passes them instead.

        # Creates 0.5|1> + 0.5|2>
        superpos(1, 2);

        # Same thing, but with explicit weights
        superpos([1, 1], [1, 2]);

        # Caution: this does not create 1|2>, but 0.5|1> + 0.5|2>
        superpos([1, 2]);

        # Any data is OK
        superpos(qw(dont eat the fish));



Takes a list of argument that each must be an instance of Quantum::Superpositions::Lazy::Role::Collapsible. Returns the list of results of calling a "collapse" in Quantum::Superpositions::Lazy::Superposition method on each of them.




        any_state BLOCK
        every_state BLOCK
        one_state BLOCK

Changes the behavior of superposition logical operations inside the block to return true if any / every / one element matches the criteria. The default behavior is any. Returns the value returned by the BLOCK.

        my $pos = superpos(1, 2, 3);

        $pos == 1; # true
        any_state { $pos == 1 }; # true
        every_state { $pos == 1 }; # false
        one_state { $pos == 1 }; # true

See Quantum::Superpositions::Lazy::Manual::Comparisons for more details.


        fetch_matches BLOCK

Changes the behavior of superposition logical operations inside the block to return a new superposition of left-hand superposition states that match the criteria instead of returning a boolean. This can be used to get more data about the superposition rather than just an information if it matches the criteria at all. Returns the value returned by the BLOCK.

        my $pos = superpos(1, 2, 3);

        $pos == 2; # true
        fetch_matches { $pos == 2 }; # a superposition: 1|2>

See Quantum::Superpositions::Lazy::Manual::Comparisons for more details.


        with_sources BLOCK

Changes the behavior of superposition mathematical operations inside the block to also contain the sources of the calculations made. This can be helpful to determine how the value was calculated. This is disabled by default due to the amount of extra memory needed by the states that are created this way. Returns the value returned by the BLOCK.

        my $calc = superpos(2, 3) * superpos(1, 2);

        # these states will now be instances of Quantum::Superpositions::Lazy::ComputedState
        my $states = with_sources { $calc->states };

        # and contain source and operation fields which will hold:
        # source - an array reference of array references in form [$val1, $val2, ... $valn]
        # operation - instance of Quantum::Superpositions::Lazy::Operation::Computational


This module uses Random::Any to generate random numbers. It is recommended that you also install Data::Entropy if you're going to use the random features of the module.


The module is mostly finished feature-wise, as puting any more features into it would make it bloated. However, I'm open to suggestions - if you have one, open an issue on Github or send me an email and we can talk it through.


  • possibly change the data type of state weights to rational numbers

    The precision of floating point values may not be enough for weight calculations in this module, even more so because often integer weights are re-calculated as float probabilities. Furthermore, a couple of pain spots in the module exist that compare floating point values with == (not in critical places tho).

    Math::BigRat could be harder to handle, so this could be done by an option or even simply allow the user to specify either float or Math::BigRat and calculate accordingly.


Bartosz Jarzyna, <>


Copyright (C) 2020 - 2022 by Bartosz Jarzyna

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.