Mercurial > hg > amuse

--- a/base/classes.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/base/classes.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -23,11 +23,13 @@

 (defclass moment (moment-designator)
   ((time :accessor %moment-time :initarg :time))
-  (:documentation "A moment represented on a number line"))
+  (:documentation "A moment-designator that has moments in time
+  represented on a number line"))

 (defclass period (period-designator)
   ((interval :accessor %period-interval :initarg :interval))
-  (:documentation "A number-line-based period"))
+  (:documentation "A period-designator that places time intervals
+  on a number-line"))

 (defclass floating-period (period) ()
   (:documentation "A simple numeric period"))
@@ -66,9 +68,10 @@
 (defclass chromatic-pitched-event (pitched-event chromatic-pitch) ()
   (:documentation "Event with chromatic pitch information"))
 (defclass percussive-event (event) ()
-  (:documentation "Unpitched percussion Event. Is there a reason why
-this is unpitched necessarily, or why I'm not counting piano, etc in
-this? Perhaps what I mean is that it should be renamed?"))
+  (:documentation "Unpitched percussion Event. There's an issue
+with this name - is there a reason why this is unpitched
+necessarily, or why I'm not counting piano, etc in this? Perhaps
+what I mean is that it should be renamed unpitched-event?"))

 ;;; Range-based `constituents'
 ;; Whilst these are all constituents in the CHARM sense, their
--- a/base/constructors.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/base/constructors.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -3,17 +3,23 @@
 ;; Time classes

 (defun make-moment (time)
+  "Returns a new moment, taking a number as input for the time
+point."
   (make-instance 'moment :time time))

 ;; N.B. period should never be constructed directly - it's either
 ;; floating or anchored or some other subclass.

 (defun make-floating-period (interval)
+  "Returns a new floating-period, taking a number for the
+duration."
   (make-instance 'floating-period :interval interval))


 ;; Should this take a moment and/or a period too?
 (defun make-anchored-period (onset interval)
+  "Returns a new floating-period, taking numbers for onset and
+duration."
   (make-instance 'anchored-period
 		 :time onset
 		 :interval interval))
@@ -21,9 +27,14 @@
 ;; Pitch classes (no, not that sort of pitch class)

 (defun make-chromatic-pitch (pitch-number)
+"Returns a new chromatic pitch, taking a number for the
+pitch."
   (make-instance 'chromatic-pitch :number pitch-number))

 (defun make-diatonic-pitch (name accidental octave)
+  "Returns a new diatonic pitch, taking as input a character for the name,
+a positive or negative number for the accidental (+ve for sharps,
+-ve for flats) and another for octave. (Is this description right?)"
   (flet ((asa-string (name accidental octave)
            (with-output-to-string (s)
              (write-char name s)
--- a/base/generics.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/base/generics.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -137,9 +137,11 @@
   time signatures"))
 (defgeneric beat-units (time-signature)
   (:documentation "In a standard, fraction-like time-signature or
-  a symbolic equivalent, this is the numerator (n.b.,
-  tactus-duration is the method of choice for compound time
-  sensitive queries."))
+  a symbolic equivalent, this is the denominator (n.b.  the
+  difference between this and @code{tactus-duration} is only
+  visible for compound time, where this returns the lower portion
+  of the time signature, but @code{tactus-duration} returns the
+  higher-level unit)."))
 (defgeneric time-signature-denominator (time-signature)
   (:method (ts) (beat-units ts))
   (:documentation "Not obviously meaningful for non fraction-like
--- a/implementations/geerdes/classes.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/implementations/geerdes/classes.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -36,7 +36,14 @@
    (db-cat-id :initarg :cat-id
 	      :accessor %db-cat-id)
    (db-file-id :initarg :file-id
-	       :accessor %db-file-id)))
+	       :accessor %db-file-id))
+  (:documentation "MIDI composition with extra slots for Geerdes
+  database entries and ids. Because this implementation is for a
+  particular need, caching of information is also handled within
+  the object, so Geerdes compositions are faster for bar lookups,
+  monody-finding and so on. They also make use of interval trees
+  for time calculations, which make them faster for window-based
+  queries (but slower to import as a result)."))

 (defclass geerdes-monody (monody geerdes-composition)
   ;; FIXME: necessary slots? Do we even use them?
@@ -49,8 +56,10 @@

 (defclass geerdes-pitched-event (midi-pitched-event geerdes-object)
   ((id :initarg :id
-       :accessor %geerdes-pitched-event-id)))
+       :accessor %geerdes-pitched-event-id))
+  (:documentation "Only adds a database id to midi-pitched-event"))

 (defclass geerdes-percussive-event (midi-percussive-event geerdes-object)
   ((id :initarg :id
-       :accessor %geerdes-percussive-event-id)))
+       :accessor %geerdes-percussive-event-id))
+  (:documentation "Only adds a database id to midi-percussive-event"))
--- a/implementations/geerdes/methods.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/implementations/geerdes/methods.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -11,9 +11,11 @@
   (make-instance 'geerdes-identifier-file-id :file-id file-id))

 (defgeneric cat-id (object)
-  (:documentation "Return a catalogue id for object"))
+  (:documentation "Return a database catalogue id for object (for
+  Geerdes data, this is the company's own ID"))
 (defgeneric file-id (object)
-  (:documentation "Return a file id (unique db id) for object"))
+  (:documentation "Return a database file id for object (for
+  Geerdes data, this is a unique integer identifier)"))
 (defgeneric (setf cat-id) (value object))
 (defgeneric (setf file-id) (value object))
--- a/implementations/midi/classes.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/implementations/midi/classes.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -1,6 +1,7 @@
 (cl:in-package #:amuse-midi)

-(defclass midi-object (amuse:amuse-object) ())
+(defclass midi-object (amuse:amuse-object) ()
+  (:documentation "MIDI base class"))

 (defclass midi-composition (amuse:composition midi-object)
   ((time-signatures :initarg :time-signatures
@@ -14,7 +15,10 @@
 		    :accessor %midi-key-signatures)
    (misc-controllers :initarg :controllers
 		      :initform 'nil
-		      :accessor %midi-misc-controllers)))
+		      :accessor %midi-misc-controllers))
+  (:documentation "Class for midi compositions, with time
+  signatures, tempi, key signatures and other controllers as
+  lists in slots"))

 (defclass midi-message (midi-object) ;?
   ((channel :accessor %midi-message-channel :initarg :channel)
@@ -24,7 +28,8 @@
   ((velocity :initarg :velocity
 	     :accessor %midi-pitched-event-velocity)
    (patch :initarg :patch
-	  :accessor %midi-pitched-event-patch)))
+	  :accessor %midi-pitched-event-patch))
+  (:documentation "Adds MIDI information to chromatic-pitched-event"))

 (defclass midi-percussive-event (percussive-event midi-message)
   ((velocity :initarg :velocity
@@ -32,5 +37,6 @@
    (patch :initarg :patch
 	  :accessor %midi-percussive-event-patch)
    (sound :initarg :sound
-	  :accessor %midi-percussive-event-sound)))
+	  :accessor %midi-percussive-event-sound))
+  (:documentation "Adds MIDI information to percussive-event"))
--- a/implementations/midi/methods.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/implementations/midi/methods.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -1,24 +1,32 @@
 (cl:in-package #:amuse-midi)

-(defgeneric midi-channel (midi-message))
+(defgeneric midi-channel (midi-message)
+  (:documentation "MIDI channel. Also used for midi output"))
 (defmethod midi-channel ((midi-message midi-message))
   (%midi-message-channel midi-message))

-(defgeneric midi-track (midi-message))
+(defgeneric midi-track (midi-message)
+  (:documentation "MIDI track. Also used for midi output"))
 (defmethod midi-track ((midi-message midi-message))
   (%midi-message-track midi-message))

-(defgeneric midi-velocity (event))
+(defgeneric midi-velocity (event)
+  (:documentation "MIDI velocity. Also used for midi output"))
 (defmethod midi-velocity ((event midi-pitched-event))
   (%midi-pitched-event-velocity event))
 (defmethod midi-velocity ((event midi-percussive-event))
   (%midi-percussive-event-velocity event))

-(defgeneric midi-patch (event))
+(defgeneric midi-patch (event)
+  (:documentation "MIDI patch (instrumental sound). Also used for
+  midi output"))
 (defmethod midi-patch ((event midi-pitched-event))
   (%midi-pitched-event-patch event))

-(defgeneric midi-drum-sound (event))
+(defgeneric midi-drum-sound (event)
+  (:documentation "MIDI pitch for unpitched events (usually, drum
+  sound for drum kits on channel 10, but also for semi-pitched
+  SFX, etc). Also used for midi output"))
 (defmethod midi-drum-sound ((event midi-percussive-event))
   (%midi-percussive-event-sound event))
--- a/implementations/midi/midifile-import.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/implementations/midi/midifile-import.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -3,9 +3,12 @@
 (defclass midifile-identifier (identifier midi-object)
   ((pathname :initarg :path
 	     :reader midifile-identifier-pathname
-	     :initform 'nil)))
+	     :initform 'nil))
+  (:documentation "Identifier for MIDI files, containing pathname
+  information"))

 (defun midifile-id (pathname)
+  "Creates an identifier for MIDI files, based on a pathname"
   (make-instance 'midifile-identifier :path pathname))

 (defmethod get-composition ((identifier midifile-identifier))
--- a/implementations/midi/package.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/implementations/midi/package.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -1,6 +1,7 @@
 (cl:defpackage #:amuse-midi
   (:use #:common-lisp #:amuse #:amuse-utils #:amuse-tools)
   (:export #:midi-composition
+	   #:midifile-id
 	   #:midi-pitched-event
            #:midi-percussive-event
            #:make-midi-pitched-event
--- a/tools/midi-output.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/tools/midi-output.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -7,10 +7,17 @@
 (in-package #:amuse-tools)

 (defgeneric play (music)
-  (:method (m) (play-midifile (make-midi m))))
+  (:method (m) (play-midifile (make-midi m)))
+  (:documentation "Plays using timidity, unless mac os is
+  present, in which case open (=QuickTime) is used. CoreAudio
+  code exists, but is awkward to maintain."))
 (defmethod play ((music composition))
   (play-midifile (make-midi music)))

+(defun write-midi (music pathname)
+  "Exports music as midi file."
+  (midi:write-midi-file (make-midi music) pathname))
+
 (defun play-midifile (midifile)
   ;; coremidi is easy as an alternative, but we'll probably want midi
   ;; file export anyway, so it makes some sense to focus our efforts
--- a/utils/n-grams.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/utils/n-grams.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -1,6 +1,16 @@
 (in-package "AMUSE-UTILS")

 (defun get-n-grams (state-sequence start-n &optional (finish-n nil) (test-for-duplicates nil))
+  "Takes a state sequence and an order, or the bounding indices
+for a range of orders, and returns an array of n-gram-frequency
+hash tables. The order of n-gram is used as the index for the
+n-grams in the returned array. N-grams are represented as equal
+hash tables with lists of states as the keys and counts as
+values. If test-for-duplicates is provided, it is assumed that a)
+consecutive instances of a state to not count as an interesting
+transition for noting and b) that (funcall test-for-duplicates
+state1 state2) returns true if the states are the same by a
+relevant measure. FIXME: Why are these optionals, not keys?"
   (let ((memory (make-array (or finish-n start-n) :initial-element :BLANK))
 	(pointer 0) (step 1) (prev-state)
 	(n-grams (make-array (or finish-n start-n)
@@ -34,9 +44,17 @@
       (incf step))))

 (defun get-n-gram (state-sequence n)
+  "Uses get-n-grams to return a single order n n-gram from
+state-sequence"
   (aref (get-n-grams state-sequence n) (1- n)))

 (defun n-gram-stats (n-gram &key (alphabet-size nil))
+  "Summarises the vital statistics of an n-gram, returning values
+for the total number of entries, the number of different n-grams
+occurring and a list of the hash table contents as a list of
+lists. If alphabet-size is provided, an additional value is
+returned for the proportion of n-grams occurring as compared with
+the number possible with alphabet-size symbols."
   (let ((count 0)
 	(frequencies)
 	(n))
--- a/utils/utils.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/utils/utils.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -11,7 +11,12 @@
   (:method (e) (not (pitchedp e))))

 ;; Rhythm methods
-(defgeneric crotchets-in-a-bar (time-signature))
+(defgeneric crotchets-in-a-bar (time-signature)
+  (:documentation "Convenient function for finding the number of
+  crotchet beats in a bar based on the provided
+  time-signature. It should be borne in mind that this needn't be
+  an integer - a time signature of 3/8, for example, should yield
+  an answer of 3/2"))
 (defmethod crotchets-in-a-bar ((time-signature basic-time-signature))
   (let ((num (time-signature-numerator time-signature))
 	(den (time-signature-denominator time-signature)))
@@ -39,8 +44,17 @@
 ;; Not as simple as it seems - have to take into account numbering
 ;; practices and leading silences in representations where bar number
 ;; isn't part of the explicit structure.
-(defgeneric bar-number (moment composition))
-(defgeneric bar-onset (bar-number composition))
+(defgeneric bar-number (moment composition)
+  (:documentation "Returns the bar number of moment in
+  composition. N.B. Although this will be a designated value in
+  some, particularly score-based, implementations, it will be a
+  derived value in others, particularly midi, where it may be
+  necessary to take into account numbering practices and leading
+  silences."))
+(defgeneric bar-onset (bar-number composition)
+  (:documentation "Returns a moment for the beginning of the bar
+  with the given bar-number. Cautions about bar numbering as
+  given in the bar-number documentation apply here also."))

 (defgeneric bass-note (anchored-period composition))