The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Quantum-Superpositions-Lazy-1.08
River stage zero No dependents
1 ++
/ Quantum::Superpositions::Lazy::Superposition

NAME

Quantum::Superpositions::Lazy::Superposition - a weighted superposition implementation

DESCRIPTION

This class implements a weighted superposition consisting of a set of Quantum::Superpositions::Lazy::State states. Each state contains a weight and a value, and the probability of each state occuring randomly is weight / superposition_weight_sum. A superposition can be collapsed, so that it will pick and return one state's value at random. After that, further collapsing will keep returning that value until the state is reset.

Simple operations only touching superposition creation and collapsing are optimized - they do not produce the entire list of values that superposition may contain. For example, creating a superposition which is a mathematical operation (see Quantum::Superpositions::Lazy::Computation) would normally create a lot of possible outcomes - one of 100 values plus one of 10 values is one of 1000 values. Normally, picking a random value from such superposition would require 1000 addition operations and one random / select an element operation. In this implementation however, this only requires one addition and two random numbers being generated.

This only works this way for the easiest use case. Every time you want to do a logical operation, get some statistics out of the superposition or even export to string (the ket notation) a full set of states is generated. Be aware of the performance implications - producing a million values superposition is not hard yet very costly.

METHODS

new

        # auto weights (all elements have the same probability)
        my $superposition = Quantum::Superpositions::Lazy::Superposition
                ->new(states => [1, 2, 3]);

        # custom weights (weight, value)
        my $superposition = Quantum::Superpositions::Lazy::Superposition
                ->new(states => [[5, 1], [5, 2], [7, 3]]);

A constructor. The only named argument accepted is the states argument. It can contain either an array reference of Quantum::Superpositions::Lazy::State objects (no coercion is applied), an array reference of array references, each having exactly two elements (coerced into Quantum::Superpositions::Lazy::State objects, the first element becomes the weight and the second element becomes the value) or an array referenc of just about anything else (coerced into state objects with automatic weight).

In most cases it should be easier to use superpos helper function from Quantum::Superpositions::Lazy rather than the constructor explicitly.

collapse

        my $random_value = $superposition->collapse;

Collapses a superposition into a single random scalar value. Any further calls to collapse will keep returning the same value until reset is called.

is_collapsed

Returns a boolean to tell whether the superposition is currently collapsed.

reset

Resets the collapsed state of the superposition and any nested superpositions. The next collapse call will return a newly randomized value.

Returns $self

states

        my $complete_states = $superposition->states;

Compiles a complete set of possible states for the superposition and returns it. It will be an array reference consisting of Quantum::Superpositions::Lazy::State objects or their descendants.

The result of the operation is cached. The operation itself can be costly in some circumstances (especially when using it on Quantum::Superpositions::Lazy::Computation of two superpositions).

stats

        my $mean = $superposition->stats->mean;

Constructs and returns an instance of Quantum::Superpositions::Lazy::Statistics, and caches it for later use.

weight_sum

Returns the sum of all states' weights. A possibility for each state occuring during collapsing can be calculated with a simple division: $state->weight / $superposition->weight_sum.

to_ket_notation

        # will return: 0.5|1> + 0.5|2>
        my $ket = superpos(1, 2)->to_ket_notation;

Compiles and returns a string containing the superposition in form of ket notation.

stringify

An alias to collapse method. Also invoked with overloaded "".

transform

        # will double every element, same as * 2
        my $transformed1 = $superposition->transform(sub { shift() * 2 });
        my $transformed2 = $superposition->transform(sub { $_ * 2 });

        # more arguments can be specified, which will be passed to the subroutine
        my $transformed = $superposition->transform(sub { $_[0] * $_[1] }, $another_superposition);

Enables creating a new superposition from an existing one using complex logic passed as a subroutine reference in the first argument. Can optionally accept more arguments (superpositions) that can take part in the calculation.

The first argument is also passed as a localized $_. Works just like the regular computations but with a custom function. This can be thought of as a way to use a function against some superpositions, for example "max" in List::Util:

        $pos->transform(\&max, $another_pos, $yet_another_pos);

Will produce a superposition with a maximum of each three values of the given superpositions.

compare

        # will perform a custom comparison
        my $boolean = $superposition->compare(sub { shift() =~ /regexp/ });
        my $matches = fetch_matches { $superposition->compare(sub { /regexp/ }) };

Like </transform>, but performs a logical comparison instead of a state mutation. Just like transform, it can accept more superpositions as its arguments.

OVERLOADING

The package uses overloading to have its objects used in perl expressions seamlessly. Most operators do the same stuff as they'd do with normal scalars, but perform them on the superposition states or return a new Quantum::Superpositions::Lazy::Computation object. The only operator that does something different is the "" stringification, which collapses the superposition and returns the state.

Operators can be divided into two types:

Since the behavior of overloaded operators is hard to control, the module introduces blocks that change how the internal operations will behave when they are performed in these blocks. These are documented in "FUNCTIONS" in Quantum::Superpositions::Lazy.

The list of overloaded operators considered logical

        ! == != > >= < <= eq ne gt ge lt le

The list of overloaded operators considered computational

        neg + - * ** << >> / % += -= *= **= <<= >>= /= %= . x .=
        x= atan2 cos sin exp log sqrt int abs