1. About
--------

This is a Ruby class for performing various pitch-class set operations. The author is Beau Sievers, and can be found at http://beausievers.com/


2. License
----------

This software is licensed under a modified version of the MIT License which limits use of my name in advertising and also requires attribution. See the included LICENSE file for details.


3. How to use it
----------------

Make new PCSets:
> my_pcset = PCSet.new([0,2,4,6,8,10])
=> [0, 2, 4, 6, 8, 10]
> my_pcset2 = PCSet.new([1,5,9])
=> [1, 5, 9]

Intersection of two PCSets:
> my_pcset & my_pcset2
=> [10]

Union of two PCSets:
> my_pcset | my_pcset2
=> [0, 2, 4, 6, 8, 10, 1, 5, 9]

Inversion:
> my_pcset2.invert
=> [11, 7, 3, 2]

Complement:
> my_pcset.complement
=> [1, 3, 5, 7, 9, 11]

Inversion around an arbitrary axis:
> my_pcset2.invert(3)
=> [2, 10, 6, 5]

Transposition:
> my_pcset.transpose(-1)
=> [11, 1, 3, 5, 7, 9]

Multiplication:
> my_pcset2.multiply(5)
=> [5, 1, 9, 2]

Transposing to zero:
> my_pcset2.zero
=> [0, 4, 8, 9]

Get all transpositions:
> my_pcset2.transpositions
=> [[0, 4, 8, 9], [1, 5, 9, 10], [2, 6, 10, 11], [3, 7, 11, 0], [4, 8, 0, 1], [5, 9, 1, 2], [6, 10, 2, 3], [7, 11, 3, 4], [8, 0, 4, 5], [9, 1, 5, 6], [10, 2, 6, 7], [11, 3, 7, 8]]

Get all transpositions and inversions:
> my_pcset2.transpositions_and_inversions
=> [[0, 4, 8, 9], [1, 5, 9, 10], [2, 6, 10, 11], [3, 7, 11, 0], [4, 8, 0, 1], [5, 9, 1, 2], [6, 10, 2, 3], [7, 11, 3, 4], [8, 0, 4, 5], [9, 1, 5, 6], [10, 2, 6, 7], [11, 3, 7, 8], [0, 8, 4, 3], [1, 9, 5, 4], [2, 10, 6, 5], [3, 11, 7, 6], [4, 0, 8, 7], [5, 1, 9, 8], [6, 2, 10, 9], [7, 3, 11, 10], [8, 4, 0, 11], [9, 5, 1, 0], [10, 6, 2, 1], [11, 7, 3, 2]]

Place a set in normal form:
> my_pcset2.normal_form
=> [9, 10, 1, 5]

Check if a set is in normal form:
> my_pcset2.is_normal_form?
=> false
> my_pcset2.normal_form.is_normal_form?
=> true

Get every member of the set class to which this set belongs:
> my_pcset2.set_class
=> [[0, 1, 4, 8], [0, 3, 4, 8], [1, 2, 5, 9], [1, 4, 5, 9], [2, 3, 6, 10], [2, 5, 6, 10], [3, 4, 7, 11], [3, 6, 7, 11], [4, 5, 8, 0], [4, 7, 8, 0], [5, 6, 9, 1], [5, 8, 9, 1], [6, 7, 10, 2], [6, 9, 10, 2], [7, 8, 11, 3], [7, 10, 11, 3], [8, 9, 0, 4], [8, 11, 0, 4], [9, 0, 1, 5], [9, 10, 1, 5], [10, 1, 2, 6], [10, 11, 2, 6], [11, 0, 3, 7], [11, 2, 3, 7]]

Prime form:
> my_pcset2.prime
=> [0, 1, 4, 8]

Check if a set is prime:
> my_pcset2.is_prime?
=> false
> my_pcset2.prime.is_prime?
=> true

Get the interval vector of a set:
> my_pcset2.interval_vector
=> [1, 0, 1, 3, 1, 0]

Get the full interval vector of a set:
> my_pcset2.full_interval_vector
=> [1, 0, 0, 2, 1, 0, 0, 1, 1, 0, 0]

Get Morris's invariance vector:
> my_pcset.invariance_vector
=> [6, 6, 6, 6, 6, 6, 6, 6]

Huron's aggregate dyadic consonance measure:
> my_pcset2.huron
=> [1.564, 0.343482463712422]

Balzano's vector of relations:
> my_pcset.vector_of_relations
=> [[0, 2, 4, 6, 8, 10], [0, 2, 4, 6, 8, 10], [0, 2, 4, 6, 8, 10], [0, 2, 4, 6, 8, 10], [0, 2, 4, 6, 8, 10], [0, 2, 4, 6, 8, 10]]

Check if the set satisfies Balzano's uniqueness:
> my_pcset.is_unique?
=> false
> my_pcset2.is_unique?
=> true

Check if the set satisfies Balzano's scalestep-semitone coherence:
> my_pcset.is_coherent?
=> true
> my_pcset2.is_coherent?
=> false

Check if the set satisfies Balzano's criterea for strict coherence:
> my_pcset.is_strictly_coherent?
=> true
> my_pcset2.is_strictly_coherent?
=> false

Gimmie some note names:
> my_pcset.notes
=> "C, D, E, F#, G#, A#"

Gimmie all kinds of information all at once, in human-readable form:
> my_pcset.info
modulo: 12
raw input: [0, 2, 4, 6, 8, 10]
pitch set: [0, 2, 4, 6, 8, 10]
notes: C, D, E, F#, G#, A#
normal: [0, 2, 4, 6, 8, 10]
prime: [0, 2, 4, 6, 8, 10]
interval vector: [0, 6, 0, 6, 0, 3]
invariance vector: [6, 6, 6, 6, 6, 6, 6, 6]
huron ADC: -2.535  pearsons: -0.135297599244473
balzano coherence: strictly coherent


Note on destructive methods:

In general, methods are non-destructive. Following Ruby convention, destructive methods which modify an object in place end with an exclaimation point. The following methods are destructive:

invert!
transpose!
multiply!
zero!
normalForm!
prime!


4. Copyright and license for this documentation
-----------------------------------------------

This documentation is Copyright © 2009 Beau Sievers, and licensed under the Creative Commons Attribution 3.0 United States License. Go to http://creativecommons.org/licenses/by/3.0/us/ for the complete text of and information about this license. Permissions beyond the scope of this license may be available by contacting the author.