3.5. pctheory.pcset
This module contains classes and functions for working with pcsets, or sets of pitch-classes. A pcset is represented as a set of PitchClass12 or PitchClass24 elements.
Functions marked with * can be used with chromatic or microtonal pcsets.
class SetClass12
Represents a pitch-class set-class with elements drawn from the twelve-note equally-tempered chromatic scale. Notes are represented with PitchClass12 objects. There are 224 set-classes in the chromatic system, including the null set-class.
SetClass12 constructor
SetClass12.__init__(pcset: set)
Constructs a SetClass12. You can provide a pcset to initialize the SetClass12.
SetClass12 properties
SetClass12.pcset{PitchClass12}
The prime-form pcset of the current SetClass12. If you assign a pcset to this property, the SetClass12 will automatically calculate its prime form and update the SetClass12.pcset properly.
SetClass12.weight_rightbool
Whether or not the prime form should be calculated by packing from the right.
SetClass12 read-only properties
SetClass12.derived_corebool
Whether or not the current SetClass12 is one of Elliott Carter's “derived core” harmonies, as specified by John Link.
SetClass12.dsymint
The degree of symmetry of the SetClass12. This is the number of Tn and TnI transformations which will transform a member of the set-class into itself. Many set-classes have a degree of symmetry of 1, which means that there are 24 pcsets in the set-class. The whole-tone scale has a degree of symmetry of 12 because there are only two whole-tone scales. The chromatic scale has a degree of symmetry of 24 because it is invariant under all of the Tn and TnI transformations.
SetClass12.ic_vector[int]
The ic vector of the current SetClass12 as a list of ints.
SetClass12.ic_vector_strstr
The ic vector of the current SetClass12 as a str.
SetClass12.ic_vector_long[int]
The long form of the ic vector of the current SetClass12 as a list of ints. The long form has an extra leading digit with the cardinality of the set-class.
SetClass12.ic_vector_long_strstr
The long form of the ic vector of the current SetClass12 as a str.
SetClass12.is_z_relationbool
Whether or not the current SetClass12 is Z-related to another class.
SetClass12.name_carterstr
Returns the Carter number for the current SetClass12.
SetClass12.name_fortestr
Returns the Forte name for the current SetClass12.
SetClass12.name_morrisstr
Returns the Morris name for the current SetClass12.
SetClass12.name_primestr
Returns the prime form name for the current SetClass12.
SetClass12.num_forteint
Returns the Forte number (the part after the hyphen) for the current SetClass12.
SetClass12 methods
SetClass12.calculate_prime_form(pcset: set, weight_from_right: bool = True)[PitchClass12]
Calculates the prime form of a provided pcset. Pcsets are Python set objects containing PitchClass12 elements. The weight_from_right parameter determines if the prime form will be packed from the right (Rahn) or packed to the left (Forte). This produces different prime forms in only a few set-classes.
SetClass12.contains_abstract_subset(sc: SetClass12)bool
Determines if a set-class sc is an abstract subset of the current SetClass12 object. Returns True or False.
SetClass12.get_abstract_complement()SetClass12
Returns the abstract complement of the current SetClass12 object.
SetClass12.get_invariance_vector()[int]
Returns the invariance vector of the current SetClass12 object.
SetClass12.get_partition2_subset_classes(){(SetClass12, SetClass12)}
Returns a set of SetClass12 tuple objects containing all two-partitions of the current set-class. Particularly applicable to the music of Milton Babbitt.
SetClass12.get_set_classes(cardinalities: list=None)[SetClass12]
Returns a list of SetClass12s. You can provide a list of cardinalities if you want to limit which set‐classes you get; otherwise you will get all 224 set‐classes.
@staticmethodSetClass12.get_abstract_subset_classes(){SetClass12}
Returns a set of SetClass12 objects representing all set-classes abstractly contained within the current set-class.
SetClass12.get_z_relation()SetClass12
Returns a SetClass12 object representing the Z-relation of the current set-class. If there is no Z-relation, returns an empty SetClass12 object.
SetClass12.is_all_combinatorial_hexachord()bool
Determines if the set‐class is an all‐combinatorial hexachord (ACH).
@staticmethod SetClass12.is_valid_name(name: str)bool
Determines if a provided set-class name is valid. Valid name types include [xxx]
(prime form),
x-x
(Forte), and (x-x)[xxx]
(Morris).
SetClass12.load_from_name(name: str)
Loads a set-class into the current SetClass12 object. The name can be in prime-form, Forte, or Morris format.
SetClass12 overloaded special functions
Overloaded special functions include __eq__(), __hash__(), __len__(), __lt__(), __ne__(), __repr__(), and __str__(). Basically, this means that you can use the ==, < and != operators on SetClass12 objects. The < operator is implemented to allow sorting using built-in Python functionality. The len() function is supported, as well as hash() (which allows you to use SetClass12 objects in sets and dictionary keys), and the str() implementation allows SetClass12 objects to be printed.
class SetClass24
Represents a pitch-class set-class with elements drawn from the 24-note equally-tempered microtonal scale. Notes are represented with PitchClass24 objects. There are 352,698 set-classes in the microtonal system, including the null set-class.
SetClass24 constructor
SetClass24.__init__(pcset: set)
Constructs a SetClass24. You may choose to provide a pcset to initialize the SetClass24.
SetClass24 properties
SetClass24.pcset{PitchClass24}
The prime-form pcset of the current SetClass24. If you assign a pcset to this property, the SetClass24 will automatically calculate its prime form and update the SetClass24.pcset properly.
SetClass24.weight_rightbool
Whether or not the prime form should be calculated by packing from the right.
SetClass24 read-only properties
SetClass24.dsymint
The degree of symmetry of the SetClass24. This is the number of Tn and TnI transformations which will transform a member of the set-class into itself. Many set-classes have a degree of symmetry of 1, which means that there are 48 pcsets in the set-class.
SetClass24.ic_vector[int]
The ic vector of the current SetClass24 as a list of ints.
SetClass24.ic_vector_strstr
The ic vector of the current SetClass24 as a str.
SetClass24.ic_vector_long[int]
The long form of the ic vector of the current SetClass24 as a list of ints. The long form has an extra leading digit with the cardinality of the set-class.
SetClass24.ic_vector_long_strstr
The long form of the ic vector of the current SetClass24 as a str.
SetClass24.name_primestr
Returns the prime form name for the current SetClass24.
SetClass24 methods
SetClass24.calculate_prime_form(pcset: set, weight_from_right: bool = True){PitchClass24}
Calculates the prime form of a provided pcset. Pcsets are Python set objects containing PitchClass24 elements. The weight_from_right parameter determines if the prime form will be packed from the right (Rahn) or packed to the left (Forte). This produces different prime forms in only a few set-classes.
SetClass24.contains_abstract_subset(sc: SetClass24)bool
Determines if a set-class sc is an abstract subset of the current SetClass24 object. Returns True or False.
SetClass24.get_abstract_complement(){PitchClass24}
Returns the abstract complement of the current SetClass24 object.
SetClass24.get_abstract_subset_classes(){SetClass24}
Returns a set of SetClass24 objects representing all set-classes abstractly contained within the current set-class.
SetClass24.is_valid_name(name: str)bool
Determines if a provided set-class name is valid. Valid name types include [xxx]
(prime form).
SetClass24.load_from_name(name: str)
Loads a set-class into the current SetClass24 object. The name can be in prime-form format.
SetClass24 overloaded special functions
Overloaded special functions include __eq__(), __hash__(), __len__(), __lt__(), __ne__(), __repr__(), and __str__(). Basically, this means that you can use the ==, < and != operators on SetClass24 objects. The < operator is implemented to allow sorting using built-in Python functionality. The len() function is supported, as well as hash() (which allows you to use SetClass24 objects in sets and dictionary keys), and the str() implementation allows SetClass24 objects to be printed.
*find_utos(pcset1: set, pcset2: set){UTO}
Finds all UTOs that transform pcset1 so that it contains pcset2. This function can be used to find individual pcs, subsets, or the entire transformed pcset.
get_all_combinatorial_hexachord(name: str){PitchClass12}
Gets an all‐combinatorial hexachord (ACH) by name (A through F).
*get_complement(pcset: set){PitchClass12}or{PitchClass24}
Gets the complement of a provided pcset. This is not the abstract complement of a set-class.
*get_complement_map_utos(pcset: set){UTO}
Gets all UTOs that map pcset into its complement.
*get_corpus(pcset: set){frozenset(PitchClass12)}or{frozenset(PitchClass24)}
Gets all UTO transformations of a provided pcset, as a set.
*get_self_map_utos(pcset: set){UTO}
Gets all UTOs that map pcset into itself.
*invert(pcset: set){PitchClass12}or{PitchClass24}
Inverts a pcset by using the M11 or M23 operations, depending on whether the pcset contains PitchClass12 or PitchClass24 elements.
is_all_combinatorial_hexachord(pcset: set)bool
Determines if a pcset is an all‐combinatorial hexachord (ACH).
make_pcset12(*args){PitchClass12}
Creates a chromatic pcset from one or more int values.
make_pcset24(*args){PitchClass24}
Creates a microtonal pcset from one or more int values.
*make_subset_graph(set_class, smallest_cardinality=1, show_graph=False, size=(800,1100)){networkx.DiGraph}
Makes a subset graph, using a provided SetClass12 or SetClass24. If you choose to show the graph, it will be generated as a PyVis visualization.
*multiply(pcset: set, n: int){PitchClass12}or{PitchClass24}
Multiplies a pcset using the operator Mn.
*partitions2(pcset: set)[({PitchClass12}, {PitchClass12})]or[({PitchClass24}, {PitchClass24})]
Gets a list of all two-partitions of a provided pcset. Each two-partition is a tuple of pcsets.
*permutations(pcset: set)[[PitchClass12]]or[[PitchClass24]]
Gets a list of all permutations of a provided pcset. The permutations are pcsegs. Note that the number of permutations of a set is n! where n is the cardinality of the set. You probably do not want to run this function on a twelve-note set.
set_class_filter12(name: str, sets: list)[{PitchClass12}]
Filters a list of chromatic pcsets. Returns a list that only contains pcsets in the set-class name.
*subsets(pcset: set)[{PitchClass12}]or[{PitchClass24}]
Generates all subsets of a provided pcset, and returns them in sorted order.
*transpose(pcset: set, n: int){PitchClass12}or{PitchClass24}
Transposes a pcset using the operator Tn.
*visualize(pcset: set)
Creates a string visualization of a pcset. The string has length 12 or 24, and contains "X" or a space for each of the 12 or 24 pitch-classes, depending on whether or not that pitch-class is present. This function is useful for inspecting pcsets visually for common tones.