# Scala Examples

## Evaluating Expressions

The CALCULATE command (which can be abbreviated like all commands) evaluates a pitch expression and shows the result. One can use this result subsequently as input to other commands. For example:

`calc 3/2^12-2/1^7`

which means take 3/2 to the power 12 and divide by 2/1 to the power 7. In other words 12 pure fifths minus 7 pure octaves. It displays the following:

``` 531441/524288 = 2^-19.3^12 = 1.01364326477
size is 23.46001038465 cents,  5.884553 savarts/eptamerides
Pythagorean comma```

Parentheses can be added if necessary. Ratios and values in cents can be used together in an expression. There is also a longer output format which gives the value in units of a (modifiable) list of intervals. See CALCULATE for the list of operations.

## Displaying Scales

The SHOW SCALE command (which can be abbreviated to SHOW or even SH) displays the working scale in the following form:

```Ptolemy's Intense Diatonic, also Zarlino's scale
0:          1/1            0.000000 unison, perfect prime
1:          9/8            203.9100 major whole tone
2:          5/4            386.3139 major third
3:          4/3            498.0452 perfect fourth
4:          3/2            701.9553 perfect fifth
5:          5/3            884.3591 major sixth
6:         15/8            1088.269 classic major seventh
7:          2/1            1200.000 octave```

The first column is the scale degree number. The first note is always number 0 with value 1/1 or 0 cents. The second column contains the frequency ratio with respect to degree 0. This need not be a ratio. If it is not, then the value is given in cents. The third column gives the frequency ratio in cents in the preceding example. However the contents of this column can be chosen from a wide range of options such as note names, prime factorisations, linear factors, harmonic complexity measures, interval sizes, logarithmic sizes in any unit, and so on. See also SET ATTRIBUTE.

## Displaying Scale Properties

The SHOW DATA command displays a list of values and properties. For example, given the following scale:

```1/4-comma mean-tone scale. Pietro Aaron's temperament (1523).
0:          1/1            0.000000 unison, perfect prime
1:         76.049 cents    76.04904
2:        193.157 cents    193.1569
3:        310.265 cents    310.2648
4:          5/4            386.3139 major third
5:        503.422 cents    503.4218
6:        579.471 cents    579.4708
7:        696.578 cents    696.5787
8:         25/16           772.6278 classic augmented fifth
9:        889.735 cents    889.7357
10:       1006.843 cents    1006.843
11:       1082.892 cents    1082.892
12:          2/1            1200.000 octave```

the SHOW DATA command displays:

```Number of notes                     : 12
-- Interval properties --
Smallest interval                   : 76.04900 cents, class 1
Average step (divided formal octave): 100.0000 cents
Largest one step interval           : 117.10786 cents
Average / Smallest step             : 1.314942
Largest / Average step              : 1.171079
Largest / Smallest step             : 1.539900
Median interval of one step         : 117.10786 cents, amount: 7
Most common interval of one step    : 117.10786 cents, amount: 7
Least squares average step          : 99.04196 cents, oct.:  1188.50352 cents
Scale is strictly proper
Scale has Myhill's property
chromas: 41.05886 cents and 34.99014 cents
generators: 5 of 503.42157 cents and 7 of 696.57843 cents
ET pair of linear temperament       : 12&19
Scale is maximally even for L / S <= 2
Scale is distributional even
Scale is a mode of a 789-tone equal temperament with octave  2/1
degrees: 50 127 204 254 331 381 458 508 585 662 712 789
generators: 331 and 458
Number of contiguous 1-step segments: 0
Interval pattern alph. order: ABBABABABBAB
Interval pattern size order : SLLSLSLSLLSL
Scale is a Constant Structure, by a margin of 34.99015 cents
Ratio Whole / Half tone: 1.649393
Rothenberg stability                : 1.000000 = 1
Lumma stability                     : 0.623627
Rothenberg efficiency               : 0.722222   redundancy: 0.277778
Efficiency x scale size             : 8.666667
Number of different interval sizes  : 22 = 2.00000 / class
Number of one step interval sizes   : 2
Highest interval variety            : 2
Mean interval variety               : 2.00000 = 2
Lowest interval variety             : 2
Smallest interval difference        : 34.99015 cents
Most common intervals               : 503.42157 cents & inv., amount: 11
Scale is a chain of 6 triads 0.0 117.108 696.578 cents
Most common triad is 0.0 503.422 696.578 cents, amount: 10
Number of recognisable fifths       : 11, average 696.5784 cents
Scale contains two identical disjunct hexachords
Best fifths form a closed circle
Formal octave complements present   : 7 = 58.3333%
Limited inverse transpositions      :
11
Inversional symmetry on intervals   :
5-6 11-12
-- Rational properties --
Prime limit                         : 5 (not all pitches rational)```

There are many more commands for obtaining structural and other properties of scales such as COMPARE, LATTICE, SHOW/FREQUENCY, SHOW INTERVALS, SHOW BEATS, SHOW ET_DIFF, SHOW TEMPERINGS, SHOW TRANSPOSE, etc. There's also a built-in procedure for accurately calculating lengths for fretted string instruments: SHOW STRINGLEN.

## Notation Systems

If the pitches in a scale are close or equal to those of an equal temperament, a notation system for this equal temperament can be selected with the command SET NOTATION (follow this link to see which systems are provided). Take 26-tone equal temperament for example. It's shown as

```  0:          1/1           C          unison, perfect prime
1:         46.154 cents   C#    Dbbb
2:         92.308 cents   Cx    Dbb
3:        138.462 cents   Cx#   Db
4:        184.615 cents   D
5:        230.769 cents   D#    Ebbb
6:        276.923 cents   Dx    Ebb
7:        323.077 cents   Dx#   Eb
8:        369.231 cents   E
9:        415.385 cents   E#    Fbb
10:        461.538 cents   Ex    Fb
11:        507.692 cents   F
12:        553.846 cents   F#    Gbbb
13:        600.000 cents   Fx    Gbb
14:        646.154 cents   Fx#   Gb
15:        692.308 cents   G
16:        738.462 cents   G#    Abbb
17:        784.615 cents   Gx    Abb
18:        830.769 cents   Gx#   Ab
19:        876.923 cents   A
20:        923.077 cents   A#    Bbbb
21:        969.231 cents   Ax    Bbb
22:       1015.385 cents   Ax#   Bb
23:       1061.538 cents   B
24:       1107.692 cents   B#    Cbb
25:       1153.846 cents   Bx    Cb
26:          2/1           C          octave
```

## Displaying Equal Temperament Properties

The command EQUALTEMP/DATA provides a set of properties of a given equal temperament, not necessarily an octave division. This for example is the output for 31-tone equal temperament:

```    1200.0000 cents divided by 31, step = 38.7097 cents
Nearest to 5/4    : 10, 387.0968 cents, diff.  0.020229 steps,  0.7831 cents
Nearest to 3/2    : 18, 696.7742 cents, diff. -0.133837 steps, -5.1808 cents
Nearest to 7/4    : 25, 967.7419 cents, diff. -0.028002 steps, -1.0840 cents
Nearest to 11/8   : 14, 541.9355 cents, diff. -0.242380 steps, -9.3825 cents
Misfit numbers M1-M5  : 26.84076 27.45395 28.62894 116.65947 239.54205
Relative errors R1-R5 :  53.5350  30.8133  24.2759  42.4449  56.8654 % of average
Highest errors H1-H5  :  26.7675  30.8133  30.8133  57.5808  94.2502 % of half step size
Pepper ambiguities 1-5:  0.15452  0.18213  0.18213  0.40431  0.89126
TOP errors T1-T5      :   3.2687   3.2687   3.2687   3.2687   3.2687 cents
TOP-RMS errors 1-5    :   2.3113   1.8972   1.6543   1.9133   2.1322 cents
Combined error factor : 1.4792 (3 - 7)
Combined error factor : 11.5745 (3 - 11)
Weighted triad dissonance : 3.4217 cents, 0.088394 steps
Major triad min/maj third beat ratio :  11.40708
Highest harmonic represented consistently     : 12
highest error 9/5 : 26, diff. -0.287904 steps, -11.1447 cents, level 1
Highest harmonic represented uniquely         : 9
highest error 9/5 : 26, diff. -0.287904 steps, -11.1447 cents, level 1
Highest harm. represented uniquely inv. equiv.: 8
highest error 5/3 : 23, diff.  0.154066 steps,  5.9639 cents, level 3
Consistency levels : 3: 3 5: 3 7: 3 9: 1 11: 1
Diameters          : 3: 15 5: 4 7: 2 9: 2 11: 2
Consistency 12 region : 30.85557 .. 31.07329 tones/octave or
1197.1696 cents .. 1205.6168 cents
Embedded divisions: none
Number of possible generators: 30
Coprime sums: all
Pyth. maj. third  : 10, 387.0968 cents, diff.  0.020229 steps,  0.7831 cents
Pyth. dim. fourth : 11, 425.8065 cents, diff.  1.020229 steps,  39.4927 cents
Basic fifth       : 18, 696.7742 cents, diff. -0.133837 steps, -5.1808 cents,
-0.24090 syntonic commas, -0.22084 Pythagorean commas ( 2/9 )
Number of recognisable fifths : 1
Number of recognisable thirds : 2
Best Pyth. comma  :-1,    Basic Pyth. comma  :-1
Best diesis       : 1,    Basic diesis       : 1
Syntonic comma    : 0,    2nd-best syntonic comma : 1
Diaschisma        : 1,    Schisma            :-1
Diatonic semitone : 3,    Chromatic semitone : 2
Minor tone        : 5,    Minor chroma       : 2
Pythagorean limma : 3,    Apotome            : 2,    Pyth. whole tone : 5
R = W / H         : 1.666667 = 5/3
Hyperoche         : 1,    Eschatum           : 0
Kleisma           : 1,    Würschmidt comma   : 0
Septimal kleisma  : 0,    Septimal comma     : 1
Septimal diesis   : 1,    Harrison comma     : 0
Undecimal comma   : 1,    Tridecimal comma   : 1
Some enharmonic equivalences:
Bx = Dbb
Cx = Ebbb  Cx# = Ebb
Shortest one-step   3-limit interval     : 1162261467/1073741824 Pythagorean-19 comma
Shortest one-step   5-limit interval     : 128/125 minor diesis, diesis
Shortest one-step   7-limit interval     : 50/49 Erlich's decatonic comma, tritonic diesis
Shortest one-step  11-limit interval     : 50/49 Erlich's decatonic comma, tritonic diesis
Shortest one-step  13-limit interval     : 78/77
Shortest vanishing  5-limit interval     : 81/80 syntonic comma, Didymus comma
Shortest vanishing  7-limit interval     : 126/125 small septimal comma, Starling comma
Shortest vanishing 11-limit interval     : 99/98 small undecimal comma
Shortest vanishing 13-limit interval     : 66/65
Shortest reversed   3-limit interval     : 531441/524288 Pythagorean comma, ditonic comma
Shortest reversed   5-limit interval     : 78732/78125 medium semicomma, Sensi comma
Shortest reversed   7-limit interval     : 118098/117649 stearnsma
Shortest reversed  11-limit interval     : 43923/43750
Shortest reversed  13-limit interval     : 847/845 Cuthbert comma
Largest superparticular  1-step interval : 27/26 tridecimal comma
Largest superparticular  0-step interval : 54/53
Largest superparticular -1-step interval : 222/221
Standard 13-limit val                    : <31 49 72 87 107 115|
TOP error: 3.268725 cents, TOP-RMS error: 2.335681 cents
3-limit TOP octave                       : 1201.636592 cents, error: 1.636592 cents
5-limit TOP octave                       : 1201.467532 cents, error: 1.805191 cents
7-limit TOP octave                       : 1201.467532 cents, error: 1.805191 cents
11-limit TOP octave                      : 1201.467532 cents, error: 1.805191 cents
13-limit TOP octave                      : 1200.136551 cents, error: 3.132547 cents
3-limit TOP-RMS octave                   : 1201.634357 cents, error: 1.636590 cents
5-limit TOP-RMS octave                   : 1200.975747 cents, error: 1.627544 cents
7-limit TOP-RMS octave                   : 1200.828262 cents, error: 1.432402 cents
11-limit TOP-RMS octave                  : 1201.205316 cents, error: 1.486858 cents
13-limit TOP-RMS octave                  : 1200.502314 cents, error: 2.072213 cents
3-limit MSR octave                       : 1203.277654 cents, error: 3.277654 cents
5-limit MSR octave                       : 1203.277654 cents, error: 3.277654 cents
7-limit MSR octave                       : 1201.344124 cents, error: 4.400348 cents
11-limit MSR octave                      : 1209.003745 cents, error: 9.003745 cents
13-limit MSR octave                      : 1185.592928 cents, error: 14.407072 cents
Minimal steps generators to primes 3-13  : 13  13  8  7  2
Number of generator steps                : 1  4  10  11  14
Best 13-limit pentadic subgroup          : 2 5 11/9 7 7/5, error: 1.8670 cents
Best 13-limit pentadic integer subgroup  : 2 5 7 15 3, error: 5.1808 cents
Number of cycles of basic fifths         : 1 of 31 tones
Number of basic fifths in basic third    : 4 or -27
Number of basic fifths in best seventh   : 10 or -21
Number of basic fifths in best sixth     : 3 or -28
Number of basic thirds in best seventh   : 18 or -13
Number of cycles of basic thirds         : 1 of 31 tones
Number of basic thirds in basic fifth    : 8 or -23
Number of cycles of best sevenths        : 1 of 31 tones
Number of best sevenths in basic fifth   : 28 or -3
Number of best sevenths in basic third   : 19 or -12
Nearest diff. tone is class 30: -2, diff. -0.022872 steps, -0.8854 cents
Nearest summ. tone is class 2:  32, diff.  0.011178 steps,  0.4327 cents
Number of different Myhill subsets: 157
Number of different triads: 145, with inversional equivalence: 80
Possible Pythagorean chromatic distribution 7X 5Y:
0  2   5   8   10  13  15  18  20  23  26  28  31 : strictly proper
C  C#   D  Eb   E   F  F#   G  G#   A  Bb   B   C
0  2   3   5   7   8   10  12  13  15  16  18  20  21  23  25  26  28  30  31
C  C#  Db  D   D#  Eb  E   E#  F   F#  Gb   G  G#  Ab   A  A#  Bb   B  B#   C
Possible classical chromatic distribution :
0  3   5   8   10  13  15  18  21  23  26  28  31 : strictly proper
C  C#   D  Eb   E   F  F#   G  G#   A  Bb   B   C
Possible diatonic distributions of form 5L 2s :
0  5   10  13  18  23  28  31 : strictly proper
C   d   e - f   G   a   b - C
Possible distributions of form 4L 3Z :
0  7   14  15  22  23  30  31 : not proper
C   d   e   f   g   a   b   C
Possible distributions of form 6X Y :
0  5   10  15  20  25  30  31 : strictly proper
C   d   e   f   g   a   b   C
Possible distributions of form 3L 2M 2s :
0  7   10  12  19  22  29  31 : not proper
C   d   e   f   g   a   b   C
```

It shows how good the basic intervals major third, perfect fifth and harmonic seventh are approximated in an equal temperament.
Misfit numbers are an invention of Fokker and are sums of squared errors in cents. M1 only counts 3/2, M2 is the sum of squared errors of 3/2 and 5/4, M3 of 3/2, 5/4 and 7/4, M4 adds 11/8 and M5 adds 13/8.
Relative errors are a percentage of the average deviation in terms of step size. The average error is a quarter step, because the error varies between zero and half a step. R1 only counts 3/2, R2 is the sum of relative errors of 3/2 and 5/4 divided by two, R3 of 3/2, 5/4 and 7/4 divided by three, etc. like with the misfit numbers.
Combined error factor, from Joel Mandelbaum, is the sum of the squared errors of the first basic three divided by the size of half a step. This makes it a kind of normalised version of the misfit number M3. The second combined error factor is given if the highest consistently represented harmonic is 9 or higher. It then includes the errors of the higher odd consistent harmonics reduced by the octave like 9/8, 11/8, etc.
The number of possible Pythagorean generators is the value of Euler's totient function for the given division. It is the amount of numbers from 1 to the division with a greatest common divisor of 1 with the division. If the greatest common divisor of a scale degree with the number of notes is larger than 1 then it cannot be a Pythagorean generator for the complete scale.
Two Pythagorean thirds are shown. The first is the value of 4 times the best fifth minus two octaves and the second is five octaves minus eight best fifths.
A list of basic intervals and commas is given with their sizes in number of scale steps. For example the syntonic comma is four times the nearest degree to 3/2 minus two times the number of steps in the octave minus the nearest degree to 5/4.

## Command Scripts

Defining one's own methods for constructing scales can be done with files containing Scala commands. The following example makes a Fokker double-tie circular mirroring. If the filename is dt.cmd, it can be invoked by entering @dt at the prompt.

```echo Create a double-tie circular mirroring
echo enter the 3 triad factors
input/factor
2
?
?
?
%3 := -%1
%4 := -%2
%5 := %2-%1
%6 := -%5
%7 := 2/1
normalize 2/1
show scale```

In this example, the user enters three factors which define some triad chord and then the rest of the notes of the resulting 7-note scale are calculated automatically. The question marks cause waiting for user input. The percent sign refers to the scale degree with the given number. In these scripts, pitch variables can be used and the command syntax is the same as with interactive use.

## Keyboard Mappings

Mapping of scale degrees to keyboard keys is achieved by using keyboard mapping files. Often they won't be needed, such as with scales with 12 tones per octave. Keyboard mappings can be created with any text editor, and look like the following. Lines beginning with an exclamation mark are comments.

```! Example keyboard mapping for a 10-tone scale. Two tones are duplicated.
! Other ones may be more convenient depending on the scale.
!
! Size of map. The pattern repeats every so many keys:
12
! First MIDI note number to retune:
0
! Last MIDI note number to retune:
127
! Middle note where the first entry of the mapping is mapped to:
60
! Reference note for which frequency is given:
60
! Frequency to tune the above note to (floating point e.g. 440.0):
261.6256
! Scale degree to consider as formal octave (determines difference in pitch
10
! Mapping.
! The numbers represent scale degrees mapped to keys. The first entry is for
! the given middle note, the next for subsequent higher keys.
0
1
2
3
3
4
5
6
7
8
8
9```

Once a keyboard mapping is loaded into Scala, the correspondences of keys with notes and notes with keys can be viewed with the SHOW MAPPING command:

```Range         : 0.C  .. 127.G
Middle        : 60.C
Reference     : 261.6256 Hertz at note 60.C
Octave degree : 10
Mapping :
60.C : 0           0:  60.C
61.C#: 1           1:  61.C#
62.D : 2           2:  62.D
63.Eb: 3           3:  63.Eb 64.E
64.E : 3           4:  65.F
65.F : 4           5:  66.F#
66.F#: 5           6:  67.G
67.G : 6           7:  68.G#
68.G#: 7           8:  69.A  70.Bb
69.A : 8           9:  71.B
70.Bb: 8          10:  72.C
71.B : 9          11:  73.C#
72.C : 10         12:  74.D```

A set of keyboard mappings for scales of various sizes is supplied with Scala. They can be used as examples or be adapted to your own needs.

## Approximating Scales

How a given scale is approximated by equal temperaments is indicated by the command FIT/MODE. If we take Ptolemy's Intense Diatonic scale from above, then FIT/MODE will give:

```  7:  1 1 1 1 1 1 1  SP B ME I SD: 33.3285 c. M: 59.6973 c.  Lebeng
10:  2 1 1 2 1 2 1   P M ME S SD: 25.8629 c. M: 44.3587 c.  Sethares Neutral, Beatles-7, Dichotic-7
12:  2 2 1 2 2 2 1   P M ME S SD: 9.2003 c. M:-15.6413 c.  G.Lydian, M.Ionian, M.Hypolydian, Major, Bilaval That, Mela Shankarabharanam, Ghana Heptatonic, Peruvian Major, 4th plagal Byzantine, Ararai: Ethiopia, Makam Cargah, Ajam Ashiran,
19:  3 3 2 3 3 3 2  SP M ME S SD: 9.0995 c. M: 14.5845 c.  Nineteen-tone Major
22:  4 3 2 4 3 4 2   P   T3   SD: 8.1766 c. M:-14.2718 c.  Twenty-two tone "Just" Major
29:  5 4 3 5 4 5 3  SP   T3   SD: 9.2386 c. M: 15.3932 c.  Twenty-nine tone "Just" Major
31:  5 5 3 5 5 5 3  SP M DE S SD: 5.5622 c. M: 10.3616 c.  Thirty-one tone Major, Intense Diatonic Lydian, M.Ionian
34:  6 5 3 6 5 6 3   P   T3   SD: 4.3829 c. M:-7.8547 c.  Thirty-four tone "Just" Major
41:  7 6 4 7 6 7 4  SP   T3   SD: 3.8489 c. M: 6.3099 c.  Forty-one tone "Just" Major
46:  8 7 4 8 7 8 4   P   T3   SD: 4.1494 c. M:-7.3835 c.  Forty-six tone "Just" Major
53:  9 8 5 9 8 9 5  SP   T3   SD: 0.9247 c. M: 1.4763 c.  Fifty-three tone "Just" Major
118: 20 18 11 20 18 20 11  SP   T3   SD: 0.2902 c. M: 0.5202 c.
```
The first column is the number of equal tempered steps per octave. Then the following numbers are the number of steps that approximate each successive interval in the scale, so a higher number represents a larger interval. Some properties are shown with the following codes: P = proper, SP = strictly proper, N = not proper, M = Myhill's property, B = block repeats, G = generated, ME = maximal even, DE = distributional even, D3 = 3-distributional even, T3 = trivalent, I = self-inverse, S = symmetrical. The number after SD: is the standard deviation of the scale from the approximation in units of cents. If the given equal temperament mode is in the list of modes, then its name is also given.

## Creating Music

Computer sound cards and instruments which have no built-in tuning table(s) can also be used to play MIDI files generated by Scala with retuning via pitch bend commands. There are two methods to create these MIDI files. One is with an input file with text in Scala sequence format and the other by conversion of an existing MIDI file. MIDI files can also be converted to the sequence format so the tuning can be changed at any point in time. Keyboard mappings can also be applied. The command to be used is EXAMPLE.

Because pitch bend commands affect all notes on a MIDI channel, different channels have to be used and chosen dynamically based on the programs (voices) and pitch bend values. This poses some restriction on the amount of simultaneous notes with different voice and tuning. The algorithm that does the channel allocation minimises the amount of pitch bend messages.

The sequence file format is quite powerful. One can use different tunings without having to change the input file. The file may specify a default tuning. Notes can be specified by scale degree number, frequency ratio, or note name/octave number pairs. MIDI program change, tempo change and controller messages can be inserted. Tracks can be specified. Time can be specified either in absolute values or relative to the end of the previous note statement. There are statements for changing the scale, key, or base frequency at any time. MIDI channels can also be excluded from being used. This is a short example:

```! Easley Blackwood: harmonization of a mode in 15-tET,
! example 29 of "Modes and chord progressions in equal tunings", p. 195
! Perspectives of New Music vol. 29/2, 1991.
!
0     exclude   10
0     tempo     800_000
0     program   5
0     velocity  64
0     frequency 261.6255653
0     equal  15
0     notation  E15
!
0	track 1
0	note C.1	480
0	note E\.1	480
480	note B\		480
480	note D.1	480
960	note Bb/	480
960	note D\.1	480
1440	note A\		480
1440	note C.1	480
1920	note G		480
1920	note B\		480
2400	note F#\	480
2400	note A		480
2880	note F		480
2880	note A\		480
3360	note E\		480
3360	note G		480
3840	note Eb		480
3840	note G\		480
4320	note D\		480
4320	note F		480
4800	note C		960
4800	note E\		960
!
0	track 2
0	note C		480
0	note G		960
480	note G.-1	480
960	note Bb.-1	480
960	note F		960
1440	note F.-1	480
1920	note G.-1	480
1920	note D		960
2400	note D.-1	480
2880	note F.-1	480
2880	note C		960
3360	note C.-1	480
3840	note Eb.-1	480
3840	note Bb.-1	960
4320	note Bb.-2	480
4800	note C.-1	960
4800	note G.-1	960```

2003-2015