opycleid.knetanalysis

Overview

This module defines a class for performing Klumpenhouwer network (K-Net) and poly-Klumpenhouwer network (PK-Net) analysis.

Informally, a K-Net is a directed graph, the vertices of which are labelled with musical objects, and the arrows of which are labelled with transformations between them. Arrows are understood to be composable: the label of a resulting composite arrow should be equal to the label of the composition of the two original arrows.

A K-Net allows one to study the interconnections between different musical elements, for example in the study of the different intervals in the constitutive elements of chords in post-tonal music.

Recent research (see below) has proposed new categorical formalizations of the K-Net notion, in which a K-Net can be conceived as the data $(R,S,F,\phi)$ of

a lax functor $R \colon \Delta \to \mathbf{Rel}$ , called the diagram action,
a functor $S \colon \mathbf{C} \to \mathbf{Rel}$ where $\mathbf{C}$ is a finite category called the context action, and
a category action morphism $(F, \phi)$ between them, i.e. a functor $F \colon \Delta \to \mathbf{C}$ , and a lax natural transformation $\phi \colon R \to SF$ (left-total on all components).

Complete and local homographies allow to transform PK-Nets into one another. More precisely,

Complete homographies correspond to category action morphisms $(N, \nu)$ between functors $S \colon \mathbf{C} \to \mathbf{Rel}$ and $S' \colon \mathbf{C'} \to \mathbf{Rel}$ and yield the new PK-Net $(R,S',F'=NF,\phi'=\nu \circ \phi)$ .
Local homographies correspond to the data $N, \tilde{\nu}$ of a functor $N \colon \mathbf{C} \to \mathbf{C'}$ and a natural transformations $\tilde{\nu}$ between functors $F \colon \Delta \to \mathbf{C}$ and $NF \colon \Delta \to \mathbf{C'}$ , which yields the new PK-Net $(R,S',F'=NF,\phi'=S\tilde{\nu} \circ \phi)$ .

References

Reference literature on Klumpenhouwer networks:

David Lewin: Klumpenhouwer Networks and Some Isographies That Involve Them, Music Theory Spectrum, Vol. 12, pp. 83–120, (1990).
David Lewin: A Tutorial on Klumpenhouwer Networks, Using the Chorale in Schoenberg’s Opus 11, No. 2, Journal of Music Theory, Vol. 38, pp. 79–101, (1994).
Henri Klumpenhouwer: The Inner and Outer Automorphisms of Pitch-Class Inversion and Transposition: Some Implications for Analysis with Klumpenhouwer Networks, Intégral, Vol. 12, pp. 81–93, (1998).

Categorical approaches to Klumpenhouwer networks:

Guerino Mazzola, Moreno Andreatta: From a Categorical Point of View: K-Nets as Limit Denotators, Perspectives of New Music, 44(2), pp. 88–113, (2006).
Alexandre Popoff, Moreno Andreatta, Andrée Ehresmann: A Categorical Generalization of Klumpenhouwer Networks, Proceedings of MCM 2015, Vol. 9110 of Lecture Notes in Computer Science, pp. 303–314, Springer .
Alexandre Popoff, Carlos Agon, Moreno Andreatta, Andrée Ehresmann: From K-nets to PK-nets: a Categorical Approach, Perspectives of New Music, 54(2), pp. 5–63, (2016).
Alexandre Popoff, Moreno Andreatta, Andrée Ehresmann: Relational poly-Klumpenhouwer networks for transformational and voice-leading analysis, Journal of Mathematics and Music, 12:1 (2018), pp. 35-55, DOI: 10.1080/17459737.2017.1406011.

KNet

opycleid.knetanalysis.PKNet(context_action)

Instantiates a new poly-Klumpenhouwer network (PK-Net) as defined above. The argument context_action is an instance of opycleid.categoryaction.CategoryAction and defines the context action of the PK-Net.

Methods

set_edges

set_edges(list_edges)

Defines the generating edges of the PK-Net.

Defines the list of vertices for this K-Net. The argument list_edges is a list of instances of opycleid.categoryaction.CatMorphism, each one representing a generating morphism for the 'diagram' category action. Objects need not be specified, as they will be automatically extracted from the list of morphisms.

set_mappings

set_mappings(edges_map,elements_map)

Defines the category action functor through the mapping of the edges and of the elements of the diagram action. The method will raise exceptions if the edge or elements mapping are not valid. The arguments are as follows.

edges_map : a dictionary, the keys of which are the names of the edges (i.e. the generating morphisms of the diagram action), the values of which are the names of morphisms in the context action.
elements_map : a dictionary, the keys of which are the names of the elements in the objects of the diagram action, the values of which are lists of elements names in the objects of the context action. The method will automatically build the components of the natural transformation of the category action functor. Each component must be left total, an exception will be raised otherwise.

get_edge_mapping

get_edge_mapping()

Returns the mapping of all edges in the diagram action as a dictionary, the keys of which are morphism names in the diagram action, the values of which are the names of the image morphisms in the context action by the category functor of the category action functor which defines this PK-Net.

get_elements_mapping

get_elements_mapping()

Returns the mapping of all elements in the diagram action as a dictionary, the keys of which are element names in the objects of the diagram action, the values of which are the names of the image elements in the context action by the natural transformation of the category action functor which defines this PK-Net.

from_progression

from_progression(elements)

From a list elements of $n$ element names in the context action, yields all PK-Nets with a diagram action built on the ordinal $n$ category, i.e. all PK-Nets with $n$ objects and $n-1$ edges, each edge $f_i$ corresponding to a transformation in the context action between elements[i] and elements[i+1]. Raises an exception if no transformation exists between consecutive elements.

global_transform

global_transform(cat_action_functor)

Apply complete homography, i.e. a category action functor cat_action_functor (an instance of opycleid.categoryaction.CategoryActionFunctor and returns the corresponding new PK-Net. This new PK-Net has

the same diagram action,
a context action which corresponds to the target category action of cat_action_functor, and
a category action functor which is the product of the initial category action functor by cat_action_functor.

local_transform

local_transform(cat_functor,local_dict)

Apply a local homography, defined by the instance cat_functor of opycleid.categoryaction.CategoryFunctor (which should be an automorphism) and local_dict, and returns the corresponding new PK-Net. The argument local_dict defines the natural transformations $\tilde{\nu}$ between functors $F \colon \Delta \to \mathbf{C}$ and $NF \colon \Delta \to \mathbf{C'}$ (N being defined by cat_functor). Its keys are objects names in the diagram category action, its values are morphism names in the context category action.

Returns a new PK-Net

with the same diagram action and context action, and
whose category action functor is the product of the initial category action functor by the image by S of the natural transformation defined by local_dict.

Raises an exception if local_dict does not define a valid natural transformation, or if cat_functor is not an automorphism.

str

Overloads Python str to return a string description of the PK_Net. Returns a description of the PK-Net which lists for each edge its name, its source and target, and the corresponding maps between elements, expressed as their image in the context action.