object types: superposition

superposition:
    description:
        ket1 + ket2 + ... + ketn
        a superposition is the sum of one or more kets
        superpositions are equal regardless of the order of the kets
        though it is useful in practice to treat superpositions as ordered
        especially if you need to sort the superposition, using either ket-sort, coeff-sort, or sort-by[], etc
        superpositions are intended to be very general in what they can represent
        if a single ket corresponds to say a single synapse, then a superposition corresponds to several synapses active at the same time
        if the coefficients of all the kets in a superposition are either 0 or 1 then the superposition corresponds to a set
        if the coefficients of all the kets in a superposition are positive integers, then the superposition corresponds to a multi-set
        if the coefficients of all the kets in a superposition are floats in range [0,1] then the superposition corresponds to a fuzzy-set
        if the coefficients of all the kets are floats, then the superposition corresponds to a (real valued) vector in some abstract space
        if the superposition has just the right properties, then it is equivalent to a NuPIC Sparse Distributed Representation, ie, a SDR
        however, the most common interpretation of a superposition is just a list
        NB: complex valued coefficients of kets are not supported, and not currently planned to be
        |> is the identity element for superposition addition: sp + |> == |> + sp == sp
        a shuffled superposition is equal to the original superposition: shuffle sp == sp
        superpositions can be: added, subtracted, unioned and intersected
        we also have operators for fuzzy is-membership, and is-subset
        and we have a similarity measure, that compares the similarity of two superpositions
        simm(sp1, sp2), with values in [0,1]. 1 for equality, 0 for completely disjoint, and values in between otherwise

    examples:
        -- the simplest superposition is a single ket:
        |blue>
        |Fred Smith>

        -- the next simplest superposition is a list:
        -- eg, a list of fruit:
        |apple> + |banana> + |orange> + |pear> + |avocado> + |cherry> + |plum>

        -- however, a list is also a mathematical set:
        {apple, banana, orange, pear, avocado, cherry, plum}

        -- then a list with positive integer coefficients, eg a shopping list:
        5|apple> + 7|orange> + |bread> + |coffee> + |chocolate> + 2|milk>

        -- which is a mathematical multi-set:
        -- https://en.wikipedia.org/wiki/Multiset
        {(apple,5), (orange,7), (bread,1), (coffee,1), (chocolate,1), (milk,2)}

        -- another example of positive integer coefficients (ie, a multi-set) is the prime factorization of a number:
        -- usefully, we have a built in operator that maps positive integers to their factors:
        sa: prime-factors |120>
            3|2> + |3> + |5>

        sa: prime-factors |1234567890>
            |2> + 2|3> + |5> + |3607> + |3803>

        -- and we can represent fuzzy states, such as hungry, tired and lonely:
        -- https://en.wikipedia.org/wiki/Fuzzy_set
        -- eg, very hungry, a little tired and somewhat lonely could be represented as:
        0.94|hungry> + 0.2|tired> + 0.5|lonely>

        -- finally, we can represent vectors as superpositions too:
        -- eg, the vector [0.1, 7.2, 5, 0.09, 3.4] could be represented as:
        0.1|x: 1> + 7.2|x: 2> + 5|x: 3> + 0.09|x: 4> + 3.4|x: 5>
        -- where we have chosen |x: k> as the basis elements, but they can be any strings
        -- where operators applied to any vector result in a new vector
        -- if the operator is a numeric operator, then that is scalar multiplication
        -- if the operator is a simple operator, then sometimes that is sparse matrix multiplication
        -- otherwise, operators are a more general type of "multiplication"

    see also:
        ket, sequence, union, intersection, is-mbr, is-subset, simm