### 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"