Safe list indexing

Pitches

The Pnum is a 0-indexed diatonic pitch-class number, C through C an octave higher. (In Kircher's 1-indexed system he uses both 1 and 8 for C so we must be able to tell the difference.)

Convert any integer to a Pnum

Accidentals

Octaves

We set octave numbers in the Helmholtz system (middle C = C4); we only need the enum OctNil if the note is a rest.

TODO check

Voices

The ark always produces four-voice polyphony.

Vocal Ranges

Set of VoiceRange data for each VoiceName

Access data from VoiceRanges by VoiceName

Duration values

We use the mensural names; first the base values, then dotted variants, then a series marked as rest values.

How should the accidental be displayed? (Needed for MEI)

A Pitch stores the essential information for notating a single note.

Make a pitch with only pnum and octave, no duration or accidental

Kircher only seems to allow for duple (not making distinction between C and cut C), cut C 3 (triple major) and C3 (triple minor).

TODO Should we distinguish between C and cut C duple?

Select meter by string

Text meter (of input text, distinguished from musical meter of setting)

Select text meter by string

Get maximum number of syllables for a TextMeter

The choice of style determines which of Kircher's three syntagmata we select. Simple style calls up Syntagma 1 for simple, note-against-note (first-species) homorhythmic counterpoint. Florid style calls up Syntagma 2 for syllabic, imitative, and even in some permutations fugal counterpoint.

TODO There is also a third syntagma, for adding rhetorical figures to simple counterpoint for more nuanced text-setting. We have not yet implemented this, and do not know if it can be fully automated.

Select style by string (used in processing XML input)

Tone

Kircher's table of tones is a hybrid of toni ecclesiastici or "church keys" which were matched to the eight traditional psalm tones in Gregorian chant, and the twelve modes of Zarlino.

Select tone by string (e.g., Tone1 or Tone12 in XML input)

Tone system, durus (natural) or mollis (one flat in the key signature)

The series of System values for the tones

Combination Pnum and Accid used to set a Pitch

A list of scales, including some notes with accidentals, from Kircher

List of tones appropriate for a single pinax

List of tones appropriate for each pinax within each syntagma (style): association list mapping style to sets of pinakes, and then pinakes to tones

Lookup a value by equality in an association list, or raise an error if not found

Get a list of legal tones for a given Style and PinaxLabel

Penultimate Syllable Length

Every unit of text to be set to music must be marked with either a long or short penultimate syllable.

Pinax maps to TextMeter

Extract a Pinax from the ark by style and pinax label

Get pinax from textual meter; this depends on the Style because the syntagmata differ in the order of meters, so IambicumEuripidaeum meter in Syntagma 1 is Pinax4, but in Syntagma 2 it is Pinax2.

Is this tone acceptable to use for this pinax in this syntagma, for this line number ("stropha")?

In prose, determine TextMeter based on penultimate syllable length

All the ark settings in one structure: We use this to pass configuration settings through many functions down to the core level of pulling data from the ark.

The top part of Kircher's "rods" contain tables table of numbers with four rows, where the numbers represent pitch offsets from a modal base note, and the rows are the notes for the four voice parts SATB. Each table represents the notes to set a single phrase of text with a given number of syllables.

We implement the notes for one voice as a Vperm, a list of Int values.

A vector of four Vperms makes a VpermChoir.

A Vector of VpermChoirs is a VpermTable, which represents the top part of Kircher's "rods". We need to know the vector length because it varies in different pinakes.

The bottom part of the "rods" contain tables of rhythmic values written with musical notes. In the simple note-against-note style, there is one list of values to match each table of voices.

We implement this using our Dur data type for the rhythmic values. An Rperm is a list of Dur values.

In Syntagma I, there is only one set of rhythmic permutation that we apply to all four voices of the VpermChoir. But in Syntagma II, there are groups of four Rperms that match up with the four voices. So we make a "choir" as a vector of Rperms, though in Syntagma I this will always just have a single member.

An RpermMeter includes a vector of RpermChoirs all in one meter (see the MusicMeter data type above) and the length of that vector.

Kircher has a variable number of Rperms in the different meters, in each column, so we need to know how many there are.

In Syntagma II everything is duple meter so there is just the one meter.

The RpermTable is a vector containing all the rhythmic permutations for one of Kircher's "rods".

The ark is a box containing rods (pinakes), each of which includes columns with voice and rhythm permutations. The rods are grouped according to style into syntagmata, where syntagma 1 is simple homorhythmic counterpoint.

We implement the Column as a structure with one VpermTable and one RpermTable.

A vector of Column instances is a Pinax.

A vector of Pinax instances is a Syntagma.

A vector of Syntagma instances plus the other elements of the physical device (tone table, vocal ranges, information matching tones to pinakes) makes up the full Arca.

Just get a vector value by index, safely (combining fromJust and !?)

Getting a Column requires indexing through nested vectors. But because there are two parts of pinax 3 in syntagma 1, we can't just use the pinax label as an enum; we have to look up the number with arca2pinax.

Getting a VpermChoir means taking the first of the Column 2-tuple; we select which one using a random number (from Fortuna module), though the Inquisition forbids chance operations

Getting an RpermChoir means taking data from Column, using the meter and a random index (for Kircher, user's choice)

The user of Kircher's arca needs only to know the number of syllables in a phrase and whether the penultimate syllable is long or short. Then they must freely (?) choose which table in the column.

We go straight to a voice and a rhythm permutation, given all the needed variables and an index. Instead of choosing freely we tempt fate and use a random number.

Use toneB attribute if needed, otherwise tone (We only use toneB for florid pinax 4, every third and fourth line!)

Select the rhythm values for a single phrase from the ark's rhythm permutations (Rperms).

In Pinax 9, there is no TripleMinor category of rperms, so we screen that out first.

TODO: Using an error, but we could just substitute TripleMajor with a note in the log (if we had a log).

The rule for selecting the column index varies depending on the pinax. Pinax 1 and 2 are determined by whether the penultimate syllables is long or short, respectively, and then the column is based on the number of syllables in the phrase.

For the other pinaces we are supposed to choose successive columns for each "stropha" (verse line), so here we select based on the position within a quatrain.

(TODO Kircher doesn't provide clear guidance about how to deal with poetry that cannot or should not be grouped in quatrains, and neither do we.)

There are different rules for each syntagma, hence the need for Style input.

Select the pitch numbers for a single voice from one of the ark's pitch permutations (Vperms).

Voice permutation data: 1-indexed pitch numbers, sets of four voices each, usually ten sets per column

Rhythm permutation data: Dur values, three sets for different meters, each containing either one set per voice permutation set (syntagma I) or a four-voice set to match (syntagma II)

Column data: Pairs of input data for voice and rhythm permutations

Pinax data: List of data for columns

To build the ark from the data in the Arca/ directory, we must take a singly nested list and make it into a vector of vectors. This allows for the data to be input and maintained more simply, as a nested list of integers and strings, but then converted to vectors for better performance. The innermost layer stays in list format.

TODO: Optimize?

Make a new VpermTable that knows its own length: Application of fromList2D to Vperm

Make a new RpermMeter that knows its own length.

Build an RpermTable with RpermMeters that know their length.

Build a Column directly from input data: two nested lists, one for all the voice permutations in the column and the other for all the rhythm permutations. Because we are manually entering Kircher's data for the ark we do not check for validity here, and there are several variations across the syntagmata and pinakes in how the data is structured.

Build a Pinax from pairs of VpermTable and RpermTable data

Build a Syntagma from constructed Pinax items (not from raw input)

Pull out a single Column given indices

Pull out a single Vperm, which is a list of Int

Pull out a single Rperm, which is a list of Dur