{-| The basic module for working with Pitch Class Sets of all kinds, including Tone Rows. The broadest datatypes ('GenSet' and 'GenRow') can model any equal temperament system; the standard datatypes ('StdSet' and 'StdRow') model /12 Tone Equal Temperament/ (12-TET). -} module Data.PcSets ( -- * Classes PcSet (modulus,elements,pMap) , Selective (complement) , Inclusive (reconcile) -- * Types -- ** Selective (Sets) , GenSet , StdSet -- ** Inclusive (Rows) , GenRow , StdRow -- * Constructors -- ** Selective (Sets) , genset , stdset -- ** Inclusive (Rows) , genrow , stdrow -- * General Operations (All Sets) -- ** Transformations , transpose , invert , invertXY , zero -- ** Permutations , retrograde , rotate -- * Selective Set Operations -- ** Systematically Equivalent Forms , sort , normal , reduced , prime -- ** Scalar Quantities , cardinality , binaryValue -- ** Vector Quantities , avec , cvec , ivec -- * Inclusive Set (Tone Row) Operations , rowP , rowR , rowI , rowRI ) where\end{code} \subsection{The Module Import List} \begin{code}

import qualified Data.List (nub,sort,sortBy,elemIndices)\end{code} \section{Classes} \subsection{PcSet} \begin{code}

{-| The broadest class of Pitch Class Set. All members of this class have a 'modulus' which restricts their 'elements' in some way. They also have 'pMap', a method for lifting integer list functions to act on set elements. The 'modulus' corresponds to the underlying system of equivalent pitch classes, for example, 12-TET = modulus 12. -} class PcSet a where -- | Determines the range of possible 'elements' of the set, -- from 0 to (m-1). If m = 0, the set can only be empty. modulus :: a -> Int -- | Returns the elements of the set as a list. elements :: a -> [Int] -- | Maps an integer list function across the members of the set, -- and returns the results in a new set of the same type. pMap :: ([Int] -> [Int]) -> a -> a\end{code} \subsection{Selective PcSets (Pitch Class Sets)} \begin{code}

{-| Selective Pitch Class Sets can have 'elements' in a range of values permitted by their 'modulus'. They can have as few as 0 (the empty set) or as many as all. The set 'complement' operation only makes sense for 'Selective' sets. -} class PcSet a => Selective a where -- | Returns a new PcSet which is the complement of the original: -- it contains all the 'elements' which the original does not. complement :: a -> a\end{code} \subsection{Inclusive PcSets (Tone Rows)} \begin{code}

{-| Inclusive Pitch Class Sets, or Tone Rows, have all the possible 'elements' permitted by their 'modulus'. The most important characteristic of a Tone Row is not its 'elements', but the /ordering/ of its 'elements'. -} class PcSet a => Inclusive a where -- | Transposes the 'elements' of a Tone Row so that the first -- element is /n/. reconcile :: Int -> a -> a reconcile n ps = transpose r ps where firstElement = head . elements $ ps r = n - firstElement\end{code} \section{Types} \subsection{GenSet: General Pitch Class Sets} \begin{code}

{-| General Pitch Class Set. This represents a Pitch Class Set that can have a 'modulus' of any positive integer value, representing the number of equivalent pitch classes in a given system; for example, 19-TET would be a modulus 19 set. The members of a the set can be as few as zero and as many as all possible values. -} data GenSet = GenSet Int [Int] deriving (Eq,Ord,Show)\end{code} text \begin{code}

instance PcSet GenSet where modulus (GenSet m _ ) = m elements (GenSet _ es) = es pMap f (GenSet m es) = genset m . f $ es\end{code} text \begin{code}

instance Selective GenSet where complement (GenSet 0 _ ) = GenSet 0 [] complement (GenSet m es) = GenSet m cs where cs = filter (`notElem` es) [0..(m-1)]\end{code} \subsection{StdSet: Standard Pitch Class Sets} \begin{code}

{-| Standard Pitch Class Set. This represents the traditional definition of a pitch class set, based on 12-TET, with the pitch classes numbered C = 0, C#/Db = 1, D = 2, and so on up to B = 11. This set can have anywhere from zero to 12 members (the empty set vs. the chromatic scale). -} data StdSet = StdSet [Int] deriving (Eq,Ord,Show)\end{code} text \begin{code}

instance PcSet StdSet where modulus (StdSet _ ) = 12 elements (StdSet es) = es pMap f (StdSet es) = stdset . f $ es\end{code} text \begin{code}

instance Selective StdSet where complement (StdSet es) = StdSet cs where cs = filter (`notElem` es) [0..11]\end{code} \subsection{GenRow: General Tone Rows} \begin{code}

{-| General Tone Row. A /Tone Row/ is a collection of all possible Pitch Class Set 'elements' within a given 'modulus'. Since it contains all elements, the significant information in this type of set is the ordering of the 'elements'. This set always has a length equal to its 'modulus'. -} data GenRow = GenRow [Int] deriving (Eq,Ord,Show)\end{code} text \begin{code}

instance PcSet GenRow where modulus (GenRow es) = length es elements (GenRow es) = es pMap f (GenRow es) = genrow (length es) . f $ es\end{code} text \begin{code}

instance Inclusive GenRow\end{code} \subsection{StdRow: Standard Tone Rows} \begin{code}

{-| Standard Tone Row. This is the traditional Tone Row, a collection of all the elements @[0..11]@, based on 12-TET. As with 'GenRow', the most significant information in this type of set is the ordering of the elements. Since this is always a complete set, this set always has a length of 12. -} data StdRow = StdRow [Int] deriving (Eq,Ord,Show)\end{code} text \begin{code}

instance PcSet StdRow where modulus (StdRow _ ) = 12 elements (StdRow es) = es pMap f (StdRow es) = stdrow . f $ es\end{code} text \begin{code}

instance Inclusive StdRow\end{code} \section{Constructors} \subsection{genset} \begin{code}

{-| Constructor for General Pitch Class Sets. This constructor accepts any @Int@ value for 'modulus', and any @[Int]@ values for an input list. Zero 'modulus' always returns an empty set; a negative 'modulus' is always taken as positive (since the number represent the /absolute/ size of the equivalence class). -} genset :: Int -> [Int] -> GenSet genset 0 _ = GenSet 0 [] genset m_in es = GenSet m (f es) where m = abs m_in f = Data.List.nub . map (`mod` m)\end{code} \subsection{stdset} \begin{code}

{-| Constructor for Standard Pitch Class Sets. This constructor accepts any @[Int]@ values for elements. The 'modulus' is always 12 (12-TET). -} stdset :: [Int] -> StdSet stdset es = StdSet ps where ps = elements $ genset 12 es\end{code} \subsection{genrow} \begin{code}

{-| Constructor for General Tone Rows. This constructor accepts any @Int@ value for 'modulus', and any @[Int]@ values for an input list. Zero 'modulus' always returns an empty set; a negative 'modulus' is always taken as positive (see 'GenSet'). If the input list of 'elements' is incomplete, the remaining 'elements' are filled in at the end, in order. -} genrow :: Int -> [Int] -> GenRow genrow m es = GenRow (os ++ cs) where ps = genset m es os = elements ps cs = elements $ complement ps\end{code} \subsection{stdrow} \begin{code}

{-| Constructor for Standard Tone Rows. This constructor accepts any @[Int]@ values for an input list. The 'modulus' is always 12 (12-TET). If the input list of 'elements' is incomplete, the remaining 'elements' are filled in at the end, in order. -} stdrow :: [Int] -> StdRow stdrow es = StdRow ts where ts = elements $ genrow 12 es\end{code} \section{General Operations (All Sets)} \subsection{Transformations} \subsubsection{transpose} \begin{code}

-- | Returns a new 'PcSet' which is the original transposed by /n/. transpose :: PcSet a => Int -> a -> a transpose = pMap . map . (+)\end{code} \subsubsection{invert} \begin{code}

{-| Returns a new 'PcSet' which is the /standard inverse/ of the original, that is, about an axis containing pitch class 0. -} invert :: PcSet a => a -> a invert ps = pMap (map (m -)) ps where m = modulus ps\end{code} \subsubsection{invertXY} \begin{code}

{-| Inversion around an axis specified by pitch classes /x/ and /y/. This inverts the set in such a way that /x/ becomes /y/ and /y/ becomes /x/. -} invertXY :: PcSet a => Int -> Int -> a -> a invertXY x y = transpose (x + y) . invert\end{code} \subsubsection{zero} \begin{code}

{-| Returns a new 'PcSet' in which the elements have been transposed so that the first element is zero. -} zero :: PcSet a => a -> a zero ps = transpose (-n) ps where n = head . elements $ ps\end{code} \subsection{Permutations} \subsubsection{retrograde} \begin{code}

-- | Returns a new 'PcSet' with the elements of the original reversed. retrograde :: PcSet a => a -> a retrograde = pMap reverse\end{code} \subsubsection{rotate} \begin{code}

-- | Returns a new 'PcSet' with the elements shifted /n/ places to the left. rotate :: PcSet a => Int -> a -> a rotate n ps = pMap nShift ps where nShift = take sameLength . drop offset . cycle sameLength = (length . elements) ps offset = n `mod` sameLength\end{code} \section{Selective Set Operations} \subsection{Systematically Equivalent Forms} \subsubsection{sort} \begin{code}

{-| Returns a 'Selective' 'PcSet' in which the elements of the original have been sorted in ascending order. (Note this is restricted to Sets, as sorting a Tone Row produces only an ascending chromatic scale.) -} sort :: (PcSet a, Selective a) => a -> a sort = pMap Data.List.sort\end{code} \subsubsection{normal} \begin{code}

{-| Returns a 'Selective' 'PcSet' in which the elements of the original have been put into /normal form/. This can be defined as an ascending order in which the elements fit into the smallest overall interval. In the event of a tie, the arrangement with the closest leftward packing is chosen. -} normal :: (PcSet a, Selective a) => a -> a normal = nform . bestPack . pcsArrangements\end{code} \subsubsection{reduced} \begin{code}

{-| Returns a 'Selective' 'PcSet' in which the elements of the original have been put into /reduced form/. This can be thought of as the 'normal' form, transposed so that the first element starts on 'zero'. -} reduced :: (PcSet a, Selective a) => a -> a reduced = rform . bestPack . pcsArrangements\end{code} \subsubsection{prime} \begin{code}

{-| Returns a 'Selective' 'PcSet' in which the elements of the original have been put into /prime form/. A prime form is able to generate all the members of its set family through the some combination of the operations 'transpose', 'invert', and simple permutation. -} prime :: (PcSet a, Selective a) => a -> a prime ps = if i_val < o_val then inversion else original where original = reduced ps inversion = reduced $ invert ps o_val = binaryValue original i_val = binaryValue inversion\end{code} \subsection{Scalar Quantities} \subsubsection{cardinality} \begin{code}

-- | Returns the number of elements in a 'Selective' 'PcSet'. cardinality :: (PcSet a, Selective a) => a -> Int cardinality = length . elements\end{code} \subsubsection{binaryValue} \begin{code}

{-| Binary Value. For a given 'Selective' 'PcSet', this returns a /unique/ number relating to the elements of the set -- a measure of the "leftward packing" of the sorted set (overall closeness of each element to zero). -} binaryValue :: (PcSet a, Selective a) => a -> Integer binaryValue = sum . map (2 ^) . elements\end{code} \subsection{Vector Quantities} \subsubsection{avec} \begin{code}

{-| Ascending Vector. If the elements of a 'Selective' 'PcSet' are taken to be in strictly ascending order, the ascending vector is the interval difference between each element. -} avec :: (PcSet a, Selective a) => a -> [Int] avec ps = map (`mod` m) $ zipWith (-) rs os where m = modulus ps os = elements ps rs = elements . rotate 1 $ ps\end{code} \subsubsection{cvec} \begin{code}

{-| Common Tone Vector: finds the number of common tones for each possible value of /n/ in the operation 'transpose' /n/ . 'invert'. Returns a list where element 0 is the number of common tones with /n/=0, element 1 is with /n/=1, and so on. -} cvec :: (PcSet a, Selective a) => a -> [Int] cvec ps = count . concatMap f $ es where m = modulus ps es = elements ps count cs = map (\n -> length (Data.List.elemIndices n cs)) [0..(m-1)] f x = map (\y -> (x + y) `mod` m) es\end{code} \subsubsection{ivec} \begin{code}

{-| Interval Vector. Each element of the interval vector represents the number of intervals in the set for that particular interval class. Element 0 measures the number of 1-interval leaps; element 1 measures the number of 2-interval leaps, and so on, up to half of the modulus /m/. -} ivec :: (PcSet a, Selective a) => a -> [Int] ivec ps = if m == 0 then [] else pivotguard . spacefold . count . intervals . elements $ ps where m = modulus ps -- pivotguard: compensates for even lists, where the largest possible -- interval is equal to its inverse (and thereby counted twice, here). pivotguard es = if odd m then es else init es ++ [last es `div` 2] -- spacefold: wraps interval list to interval classes spacefold = take (m `div` 2) . flipSum flipSum es = zipWith (+) es (reverse es) -- count: counts each occurrence of each possible diff count ivs = map (g ivs) [1..(m-1)] g ivs n = length (Data.List.elemIndices n ivs) -- intervals: returns recursive list of diffs intervals [] = [] intervals (e:es) = diffs e es ++ intervals es -- diffs: interval difference between pitches diffs = map . f f a b = (b - a) `mod` m\end{code} \section{Inclusive Set (Tone Row) Operations} \subsection{Permutation-Transformations} \subsubsection{rowP} \begin{code}

{-| Returns a new Tone Row in which the elements are /Prograde/ (in their original order) and transposed so that the first element is /n/. -} rowP :: (PcSet a, Inclusive a) => Int -> a -> a rowP = reconcile\end{code} \subsubsection{rowR} \begin{code}

{-| Returns a new Tone Row in which the elements are /Retrograde/ (reversed compared to their original order) and transposed so that the first element is /n/. -} rowR :: (PcSet a, Inclusive a) => Int -> a -> a rowR = (. retrograde) . reconcile\end{code} \subsubsection{rowI} \begin{code}

{-| Returns a new Tone Row in which the elements have been /Inverted/ (see 'invert') and transposed so that the first element is /n/. -} rowI :: (PcSet a, Inclusive a) => Int -> a -> a rowI = (. invert) . reconcile\end{code} \subsubsection{rowRI} \begin{code}

{-| Returns a new Tone Row in which the elements are both /Retrograde/ and /Inverted/, and transposed so that the first element is /n/. -} rowRI :: (PcSet a, Inclusive a) => Int -> a -> a rowRI = (. (invert . retrograde)) . reconcile\end{code} \section{Not Exported} \subsection{Related to Normal, Reduced, and Prime} \begin{code}

data (PcSet a, Selective a) => Candidate a = Candidate { idx :: Integer, nform :: a, rform :: a }\end{code} \begin{code}

interview :: (PcSet a, Selective a) => a -> Candidate a interview ps = Candidate { idx = binaryValue zs, nform = ps, rform = zs } where zs = zero ps\end{code} \begin{code}

sortFunction :: (PcSet a, Selective a) => Candidate a -> Candidate a -> Ordering sortFunction a b = compare (idx a) (idx b)\end{code} \begin{code}

bestPack :: (PcSet a, Selective a) => [a] -> Candidate a bestPack arrs = head (Data.List.sortBy sortFunction candidates) where candidates = [interview ps | ps <- arrs]\end{code} \begin{code}

pcsArrangements :: (PcSet a, Selective a) => a -> [a] pcsArrangements ps = if n == 0 then [ps] -- only one possible arrangement for nothing. else take n $ iterate f (sort ps) where n = cardinality ps f = rotate 1\end{code} % last line Data.PcSets