Harpa – English Documentation
Harpa – A program to study the harmonic
possibilities of the pedal harp
Hudson Lacerda (2000-2009)
harpa is a program to aid the study of the harmonic
possibilities of the harp (pedal combinations), using pitch-class set
theory principles. Original version (harpa.exe) is for
MS-DOS. There is also an adaptation for GNU+Linux
(harpa).
The program (in both source and executable forms) is available at:
http://hudsonlacerda.webs.com/harpa.tar.bz2
Description
harpa is intended to help analysing the harmonic
possibilities of the harp which are provided by the different pedals
combinations. Pitch-class set theory principles complements the approach.
The program is interactive. It waits for user input and then
process the request, until the command fim is found, when
the program ends. For help, the user can issue the command
ajuda or ? (alternative form). The user
interface is in Portuguese, therefore the commands will be described
in this document for users who can read English.
Features
The main features of harpa are:
- Identification of all the 2187 pedal combinations.
- Interpolation between two given pedal combinations.
- Search of pedal combinations according to selection criteria, such as:
- include a given pitch-class set;
- the number of pedals positioned as flat, natural and sharp lies inside a given range;
- have certain pedals in the specified positions;
- do not include the given pitch classes;
- have a certain number of common pedals positions relative to a given combination.
- Can read commands from a file.
- Can store command results in a file.
Examples
Pedal positions (flat, natural or sharp) are represented by the
note names (such as C#, G or Bb). Each one of the 2187 possible
combination of the pedals is identified by a number (starting from
zero for all pedals in flat position, and ending with 2186 for all
pedals in sharp position).
The command NUM returns the identifier of any pedal
combination:
harpa> num Db Cb Bb Eb Fb Gb Ab 0 harpa> num D C B E F G A 1093 harpa> num D# C# B# E# F# G# A# 2186
The command COMB does the reverse:
harpa> comb 0 [Db,Cb,Bb,Eb,Fb,Gb,Ab] harpa> comb 1093 [D, C, B, E, F, G, A ] harpa> comb 2186 [D#,C#,B#,E#,F#,G#,A#]
The command ESQUEMA generates diagrams representing
pedal positions (^ for flat, – for natural, . for sharp):
harpa> esquema 1167 (--.|-^.^) harpa> comb 1167 [D, C, B#,E, Fb,G#,Ab]
To represent enharmonic pitches, the program accepts pitch classes
numbers. In this form, C and/or B# are represented by the number 0; C#
and/or Db by 1; D by 2; D# and/or Eb by 3 and so on. Pitch numbers
equal of greater than 12 are reduced into the module 12, resulting in
numbers inside the range 0 to 11.
The command CALT converts pitches into pitch-class
sets:
harpa> calt F# [6] harpa> calt C E G [0,4,7]
How many ways are there to set up a whole-tone scale on C in the
harp?
harpa>> enarm c d e f# g# a# bb *CONJUNTO: [0,2,4,6,8,10] [D, C, Bb,E, Fb,Gb,Ab] **** 999 [D, C, Bb,E, F#,Gb,Ab] **** 1017 [D, C, Bb,E, F#,G#,Ab] **** 1023 [D, C, Bb,E, F#,G#,A#] **** 1025 [D, C, B#,E, F#,G#,A#] **** 1187 *NUMERO DE COMBINACOES ENARMONICAS: 5
Which pedal combinations generate transpositions of the whole-tone
scale?
harpa> pesq conjunto transp [0,2,4,6,8,10]
94 580 999 1017 1023 1025 1187 2038 2092
*NUMERO DE COMBINACOES ENCONTRADAS: 9
More examples below, along with the description of the commands.
Commands
harpa is not case-sensitive, thus the command
AJUDA is equivalent as the command ajuda.
The list of available commands is:
AJUDA ? FIM CLS ! &PAUSA COMB ESQUEMA CONJ NUM ENARM NOTAS CALT CLCONJ PESQ DIF COMP ELOS INTERP SEMENTE IGNORACOMENT FIXO ENTRADA SAIDA TESTE
AJUDA or ?
The command AJUDA (or ?) accesses the
documentation of the program. Without any argument, the command shows
the list of help topics. To consult a topic, execute:
ajuda <topic_name>
Examples:
ajuda ajuda ajuda calt
FIM
Close the program.
CLS
Clear the screen.
!
Execute an external command from the operative system. Example:
! date
&PAUSA
Suspend program execution until some user input. Useful for scripts.
COMB
Return the pedal combination which corresponds to the given
identifier (range 0 to 2186). It accepts one or more numbers as
arguments. Examples:
comb 0 comb 1093 2186
ESQUEMA
Show a diagram of the given pedal combination. Argument is one or
more numbers from 0 to 2186. Example:
esquema 0 1093 2186 esquema 777
CONJ
Return a pitch-class set for the given pedal combination. Argument
is one or more numbers from 0 to 2186. Example:
conj 1093 conj 1932
NUM
Return the identification number of a given pedal
combination. Input can be a list of the seven note names (separated by
spaces, commas, braces or brackets) or a formatted diagram. Examples:
num { c d e f g a b }
num (---|----)
num [D, C, Bb,E, F#,G#,Ab]
num (--^|-..^)
ENARM
Find pedal combinations which are enharmonic of the given
combination (the given combination is included in the
results). Arguments are a list of the seven note names or a
diagram. Examples:
enarm G A Bb Cb F Eb Db enarm (^..|.^.-)
NOTAS
Find pedal combinations which include the given pedal
positions. Argument is a list of note names. Examples:
notas C E G Bb D
CALT
Convert input pitch set into a pitch-class set. Argument is a list
of pitches, as note names or as numbers (C=0, C#=1, D=2, Eb=3, and so
on). Numbers equal or greater than 12 are reduced into modulo
12. Examples:
calt C calt Db calt C# calt c d e calt 0 2 4 calt C D# 7 11 14 F#
CLCONJ
Return the complete pc-set class (transpositions and inversions) of
the given pitch set. Example:
clconj 1 2 3
PESQ
PESQ is the most complex and powerful command of the
program. It searches all 2187 possible pedal combinations of the harp
for combinations which obey the given restrictions. There are several
user options the set the restrictions.
incl
Include the given pitch set (pitches are given as numbers) and/or
pedal positions (note names).
Examples:
pesq incl C D B E F pesq incl [0,1,4,8,10] pesq incl [0,2,4,6] [Cb, G#]
incl classe
Include any transposition/inversion of the given pitch set (pitches
are given as numbers) and/or pedal positions (note names, never
transposed/inverted).
incl transp
Include any transposition of the given pitch set (pitches are given
as numbers) and/or pedal positions (note names, never transposed).
excl
The resulting pedal combinations do not contain any of the given
elements.
Examples:
pesq excl [Cb] [0,2,4,5,8] pesq excl G A [0 1 2 5 10]
excl classe
The resulting pedal combinations do not contain any
transpostion/inversion of the given pitch set (numbers), and do not
contain any of the pedal positions (note names).
excl transp
The resulting pedal combinations do not contain any transpostion of
the given pitch set (numbers), and do not contain any of the pedal
positions (note names).
conjunto
Exact pitch set (numbers), and have the defined pedal positions (if
note names are present).
Example:
pesq conjunto [0,2,4,6,8,10] [Ab]
conjunto classe
Exact transpositions or inversions of the pitch set (numbers), and
have the given pedal positions (if note names are present).
conjunto transp
Exact transpositions of the pitch set (numbers), and have the given
pedal positions (if note names are present).
Example:
calt C D Eb F G Ab B *minor scale (harmonic form) pesq conjunto transp [0,2,3,5,7,8,11] *all minor harm. scales
cardinal
The pitch-class set of the pedal combination has exactly the
requested number of elements (from 4 to 7).
cruza
If argument is S (yes), look for combinations
including both Cb and B#, and/or both E# and Fb (“crossings”). If
argument is N (no), exclude combinations with any of the
pairs [Cb,B#] or [E#,Fb].
Example:
pesq cruza s incl F# Gb
min
Have the minimum number of accidentals. Argument is a three-digits
number: first digit is the minimum number of flats, middle digit is
the minimum number of naturals, and the third digit is the minimum
number of sharps.
Examples:
pesq min 006 * min. 6 sharpened notes pesq min 034 * min. 3 natural notes and 4 sharpened notes pesq min 601 * min. 6 flats and 1 sharp
max
Have the maximum number of accidentals. Argument is a three-digits
number: first digit is the maximum number of flats, middle digit is
the maximum number of naturals, and the third digit is the maximum
number of sharps.
Examples:
pesq max 610 * max. 6 flats and 1 natural pesq min 511 max 511 * exactly 5 flats, 1 natural and 1 sharp
muda
Change from a given reference pedal combination. The first argument
sets the range of pedal changes, and the second argument is the
reference position (list of note names or diagram).
If the first argument is a number, it is the exact number o f pedal
moves from the reference.
To control the number of changes at each harp side, use
/ to separate left and right.
Additionally, a range of minimum and maximum changes can be
defined, using ~ as separator.
Examples:
pesq muda 1 (---|----) * change any single pedal pesq muda 1/1 (---|----) * change one pedal each harp side pesq muda 2/~3 (...|....) * change at least 2 left pedals, 3 total * change one or two pedals each side, have crossings and Eb: pesq muda 1/1~2/2 [c,d,e,f,g,a,b] cruza S incl Eb
DIF
Show the differences between all combinations (given as numbers
from 0 to 2186). The result is composed of: number differences of
pedals of left-side, a bar, differences right-side, and total number
of differences. Example:
comb 1093 1824 dif 1093 1824
COMP
Compare the listed pedal combinations (given as numbers from 0 to
2186). The result is a table which entries have the number of
differences left-side and right-side between every pair of pedal
combinations.
comp 1 2 3 4 5 1000
ELOS
Compare the listed pedal combinations and show possible easy
changes (that is: at most one pedal change each harp side) between
every pair.
elos 1094 1095 1096 1097 1099 1101 1102 1103 1105 1111
INTERP
Interpolate pedal combinations between the two given ones, changing
at most one pedal each harp side at each intermediate combination. The
resulting sequence is dependend of random choice; an optional third
argument is the the “seed” for the pseudo-random generator (see
SEMENTE). Examples:
comb 252 2186 interp 252 2186 interp 252 2186 interp 252 2186 interp 252 2186 1000 interp 252 2186 1000 interp 252 2186 1000
SEMENTE
Reinit the pseudo-random generator with the given seed. If the
given number is 0, set the seed based on the current time.
IGNORACOMENT
Do not print to the output file the coments started by
* (asterisk). Comments started with ;
(semicolon) are copied to the output file without the leading
character ;.
FIXO
With the argument SIM, remember the last command name
for the subsequent input lines. With the argument NAO,
cancel the command remembering. Example:
fixo sim comb 1092 1093 1094 esquema 1092 1093 1094 0 fixo nao
ENTRADA
Read input from a file. Filename must be given between double quotes. Example:
entrada "tutorial"
SAIDA
Write output to a file. Filename must be given between double
quotes. To close the file and reset the standard output to the
console, execute SAIDA PADRAO. Example:
saida "/tmp/output" saida padrao
TESTE
There is a command — in testing stage — to run the sound
synthesizer Csound, playing the given pedal combination(s). Future
versions of harpa may have this facility with a proper
name; then, the command name TESTE will be removed or
replaced with another testing functionality.
teste 0 teste 0 1093 2186 teste 557 1167 teste 1682 1968
Contact
Hudson Lacerda
hfmlacerda @ yahoo . com . br
HudLac 
Deixe um comentário