Opycleid: The Python library for transformational music analysis

Welcome to Opycleid

Opycleid is a Python library for transformational music analysis (TMT), a field of musicology which studies transformations between musical objects (notes, chords, durations, etc.) from a mathematical point of view. This field was initiated by David Lewin in the 1980s, relying mainly on mathematical group theory, and later developed and extended using elements of category theory.

The use of this library assumes that one is familiar with the basic notions in transformational music theory. Here are a few links for those who would be interested in discovering this subject.

The Wikipedia page on the subject.
A series of blog posts introducing transformational music theory.
The book of David Lewin, where he first defined its group-theoretical approach of generalized musical intervals: Lewin, D.: Generalized Musical Intervals and Transformations, Yale University Press: New Haven, CT, 1987.

Guiding principles

User-friendly: Opycleid provides ready-to-use classes for the common groups and monoids encountered in TMT, such as the $T\text{/}I$ group or the $\text{PRL}$ group usually found in neo-Riemannian theory. These classes provides methods for determining, multiplying, and applying musical transformations. For, one can start analyzing chords in just a few lines of Python, as shown below.

from opycleid.musicmonoids import TI_Group_Triads

my_group = TI_Group_Triads()
print (my_group.get_operation("C_M","B_m")) ## ['I6']
print (my_group.apply_operation("I5","E_m")) ## ['Fs_M']

Generalizability: TMT has mainly been applied to the analysis of relations between notes and chords, but it can in fact be applied to any musical object, such as durations, time-spans, rhythms, etc. Opycleid takes a very general approach to TMT by considering category actions in $\mathbf{Rel}$ , i.e. faithful functors from a small category to the 2-category $\mathbf{Rel}$ of finite sets and relations between them. The elements of these sets are specified as strings and can represent any musical object. Opycleid also provides basic support for the definition of sub-categories of $\mathbf{Rel(Q)}$ , the 2-category of finite sets and quantale-valued relations between them, where $Q$ is a given quantale.
Customizability: though the usual musical groups and monoids are already implemented in Opycleid, custom monoids can be generated by specifying objects and morphisms. Their definition is made easy by the use of standard Python primitives (dictionaries and lists).
What it is not: to allow the user to define his own category actions, Opycleid implements some routines which can be found in computer algebra systems such as GAP and SageMath. However, Opycleid is focused on musical applications, and is therefore not meant to be as complete as these softwares. In particular, Opycleid does not fully implement category theory (categories, functors, natural transformations, etc.), but focuses on faithful functors to $\mathbf{Rel}$ , which can be more easily implemented.

User installation

The easiest way to install Opycleid is using pip:

$ pip install opycleid

Opycleid can also be installed directly from source:

$ python setup.py install

Support

Bug reports and features requests (only) can be posted in GitHub issues.

Why this name, Opycleid ?

The ophicleide is a keyed brass instrument from the 19th century. From the greek ophis (ὄφις) "serpent" (hence the perfect name for a Python library) + kleis (κλείς) "keys", it means a serpent with keys, the serpent being an older instrument it evolved from.

Screenshot

The ophicleide was later superseded by the tuba, which was considered more reliable in terms of tone production.