In this overview, we will discuss the most essential parts of sator, but it is assumed that the reader is well versed in atonal theory.

Constructing Tone Rows and Pitch/Pitch Class Sets

The core module in sator contains the three essential classes for instantiating and manipulating tone rows, pitch sets, and pitch class sets.

To construct rows and sets, import the ToneRow, PCSet, and PSet classes from the core module as follows:

from sator.core import ToneRow, PCSet, PSet

To instantiate an empty pitch set, or pitch class set, use:

a = PSet()
b = PCSet()
  • ToneRow objects are excluded from the above example because by definition, they cannot be empty.

The classes’ constructors take an optional number of positional arguments as pitches or pc’s. These arguments can be integers, lists, tuples, sets of integers, or another ToneRow, PCSet, or PSet object. Any of the following are both valid and equivalent:

a = PSet([0, 2, 4, 6, 8])
a = PSet(0, 2, 4, 6, 8)
a = PSet(0, [2, 4], 6, 8)
b = PSet(a)

The constructors also take several optional keyword arguments. For further details, refer to Constructor Options

For more information about how pitch/pitch class data is stored and retrieved and how to instantiate objects from objects of other classes refer to Data Inspection Casting objects from PSet, PCSet, or ToneRow to another works as expected, but it is not recommened to cast in both directions arbitrarily as data may be lost. Refer to “data inspection” above for more details.

While PSet objects contain pitch data, it is neccessary and desirable to have upper and lower limits. Rahn numbers are assumed, and pitches may be within 10 octaves of C4 (e.g. Rahn number 0). A PSet with pitches outside of this range will have the octave of the offending pitches reduced or raised 10 octaves appropriately.

Operating on Tone Row and Pitch/Pitch Class objects

Each of these objects can be iterated over, has a length, and with the exception of tone rows, can have additional pitches or pitch classes added or removed from them. Each class also supports an insert and copy method. The following example introduces an overview of the supported operators:

a = PCSet([0, 3, 9], ordered=True)
a = a + 11
a = a - 3
print a
Out: [0, 9, 11]
for pc in a:
    print pc
Out: 0
Out: 9
Out: 11
print len(a)
Out: 3
a.insert(0, 10)
print a
Out: [10, 0, 9, 11]
b = a.copy()
print b
Out: [10, 0, 9, 11]

Refer to Operators for more specifics on these operators.


At the heart of atonal music are the twelve tone operators, or TTO’s. Each of sator’s classes have methods for these, which are detailed at TTO’s

Below is a simple example of using each to modify a PCSet in place:

a = PCSet(0, 1, 3)
print a
Out: [0, 9, 11]
print a
Out: [3, 5, 6]
Out: [1, 3, 6]
a.t_m(6, 7)
print a
Out: [0, 1, 3]

Attributes, Generators, and Properties

Sator core class objects have various boolean attributes such as ordered and multiset. They also have several property and generator methods. For more information on each topic, refer to the relevant links below:



Properties and Static Methods

Tone Rows

ToneRow objects share many of the same methods as PCSet and PSet methods, but sometimes these methods have different or limited meaning. ToneRow objects also have many unique methods such as: P, R, I, RI, M, MI, RM, RMI, and swap.

Refer to Tone Rows for more information

Similarity Relations

Similarity relations are imported from sator.sim and are used to make various kinds of comparisons between pitch or pitch class sets. For example:

from sator.core import PCSet
from sator.sim import m, c, z
a = PCSet(0, 1, 2, 4, 7, 9)
b = PCSet(0, 1, 3, 5, 6, 8)
print c(a, b)
Out: True
print z(a, b)
Out: True
print m(a, b)
Out: False

Refer to Similarity Relations for more information.

Project Versions

Table Of Contents

Previous topic


Next topic

Constructor Options

This Page