musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/datasets/score/to-mxml/process-time.rb

@@ -1,9 +1,47 @@
 require 'prime'
 
+# Time and duration processing for MusicXML export.
+#
+# This module provides helper methods for converting musical durations
+# to MusicXML note types, dots, and tuplet ratios. Handles the complex
+# mathematics of decomposing arbitrary rational durations into standard
+# notation elements.
+#
+# ## Duration Representation
+#
+# Durations are Rational numbers where 1 = one beat (typically quarter note).
+# - 1r = quarter note
+# - 1/2r = eighth note
+# - 3/2r = dotted quarter
+# - 1/3r = eighth note triplet
+#
+# ## Decomposition Process
+#
+# 1. **Decompose**: Break duration into sum of simple durations (powers of 2)
+# 2. **Integrate**: Combine consecutive halves into dotted notes
+# 3. **Type & Dots**: Determine note type and dot count
+# 4. **Tuplet Ratio**: Calculate tuplet modification if needed
+#
+# @api private
 module Musa::Datasets::Score::ToMXML
   private
 
+  # Decomposes duration into dotted note representation.
+  #
+  # Internal class representing the breakdown of an element's duration
+  # within a measure. Handles ties across bar lines and duration decomposition.
+  #
+  # @api private
   class ElementDurationDecomposition
+    # Creates duration decomposition for element.
+    #
+    # @param element [Hash] event with :start, :finish, :dataset keys
+    # @param bar [Integer] bar number (1-based)
+    # @param bar_size [Rational] bar duration (default: 1r)
+    #
+    # @note This method is experimental and currently unused. See TODO comment.
+    #
+    # @api private
     def initialize(element, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
       @continue_from_previous_bar = element[:start] < bar
       @continue_to_next_bar = element[:finish] >= bar + bar_size
@@ -17,7 +55,25 @@ module Musa::Datasets::Score::ToMXML
       @duration_decomposition = integrate_as_dotteable_durations(decompose_as_sum_of_simple_durations(@duration))
     end
 
-    attr_reader :continue_from_previous_bar, :continue_to_next_bar, :start, :duration, :duration_decomposition
+    # Whether note continues from previous bar (tied).
+    # @return [Boolean]
+    attr_reader :continue_from_previous_bar
+
+    # Whether note continues to next bar (tied).
+    # @return [Boolean]
+    attr_reader :continue_to_next_bar
+
+    # Start time within bar.
+    # @return [Rational]
+    attr_reader :start
+
+    # Total duration.
+    # @return [Rational]
+    attr_reader :duration
+
+    # Duration broken into dotteable components.
+    # @return [Array<Rational>]
+    attr_reader :duration_decomposition
 
     def to_s
       "ElementDurationDecomposition(#{@duration}) = [#{@duration_decomposition}]"
@@ -28,6 +84,21 @@ module Musa::Datasets::Score::ToMXML
 
   private_constant :ElementDurationDecomposition
 
+  # Optimizes time and tuplet representation (experimental).
+  #
+  # Attempts to find optimal tuplet grouping for elements in a bar.
+  # Currently unused due to incomplete implementation.
+  #
+  # @param elements [Array] PDV events
+  # @param bar [Integer] bar number
+  # @param bar_size [Rational] bar duration
+  #
+  # @return [nil] incomplete implementation
+  #
+  # @note This method is experimental and currently unused. See TODO comment.
+  #
+  # @api private
+  # @todo Complete or remove this experimental method
   def time_and_tuplet_optimize(elements, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
     decompositions = elements.collect { |pdv| ElementDurationDecomposition.new(pdv, bar, bar_size) }
 
@@ -46,6 +117,32 @@ module Musa::Datasets::Score::ToMXML
     nil
   end
 
+  # Decomposes duration into sum of simple durations.
+  #
+  # Breaks a rational duration into sum of fractions with power-of-2 denominators.
+  # This is the first step in converting arbitrary durations to standard notation.
+  #
+  # Uses greedy algorithm: repeatedly subtracts largest possible simple duration.
+  #
+  # @param duration [Rational] duration to decompose
+  #
+  # @return [Array<Rational>] simple durations that sum to input
+  #
+  # @raise [ArgumentError] if duration cannot be decomposed
+  #
+  # @example Quarter note
+  #   decompose_as_sum_of_simple_durations(1r)
+  #   # => [1r]
+  #
+  # @example Dotted quarter
+  #   decompose_as_sum_of_simple_durations(3/2r)
+  #   # => [1r, 1/2r]
+  #
+  # @example Complex duration
+  #   decompose_as_sum_of_simple_durations(5/8r)
+  #   # => [1/2r, 1/8r]
+  #
+  # @api private
   def decompose_as_sum_of_simple_durations(duration)
     return [] if duration.zero?
 
@@ -69,6 +166,17 @@ module Musa::Datasets::Score::ToMXML
     summands
   end
 
+  # Generates all combinations of array elements.
+  #
+  # @param numbers [Array] elements to combine
+  #
+  # @return [Array<Array>] all unique combinations (excluding empty)
+  #
+  # @example
+  #   all_combinations([2, 3])
+  #   # => [[2], [3], [2, 3]]
+  #
+  # @api private
   def all_combinations(numbers)
     all_combinations = []
     i = 1
@@ -80,6 +188,28 @@ module Musa::Datasets::Score::ToMXML
     all_combinations.uniq
   end
 
+  # Integrates consecutive halves into dotted durations.
+  #
+  # Combines simple durations where each is half the previous into
+  # single dotted duration. Example: [1r, 1/2r] → [3/2r] (dotted quarter).
+  #
+  # @param simple_durations [Array<Rational>] simple durations from decomposition
+  #
+  # @return [Array<Rational>] integrated dotted durations
+  #
+  # @example Dotted quarter
+  #   integrate_as_dotteable_durations([1r, 1/2r])
+  #   # => [3/2r]
+  #
+  # @example Double-dotted half
+  #   integrate_as_dotteable_durations([1/2r, 1/4r, 1/8r])
+  #   # => [7/8r]
+  #
+  # @example Non-dotteable
+  #   integrate_as_dotteable_durations([1r, 1/4r])
+  #   # => [1r, 1/4r]  (no integration possible)
+  #
+  # @api private
   def integrate_as_dotteable_durations(simple_durations)
     integrated_durations = []
     last = nil
@@ -94,6 +224,32 @@ module Musa::Datasets::Score::ToMXML
     integrated_durations
   end
 
+  # Calculates note type, dots, and tuplet ratio.
+  #
+  # Converts a dotteable duration into MusicXML note representation:
+  # - **type**: Base note type (quarter, eighth, etc.)
+  # - **dots**: Number of dots (0-3 typically)
+  # - **tuplet_ratio**: Tuplet modification (3:2 for triplets, etc.)
+  #
+  # @param noteable_duration [Rational] duration to convert
+  #
+  # @return [Array(String, Integer, Rational)] [type, dots, tuplet_ratio]
+  #
+  # @raise [ArgumentError] if duration cannot be represented with dots
+  #
+  # @example Quarter note
+  #   type_and_dots_and_tuplet_ratio(1r)
+  #   # => ["quarter", 0, 1r]
+  #
+  # @example Dotted quarter
+  #   type_and_dots_and_tuplet_ratio(3/2r)
+  #   # => ["quarter", 1, 1r]
+  #
+  # @example Eighth triplet
+  #   type_and_dots_and_tuplet_ratio(1/3r)
+  #   # => ["eighth", 0, 3/2r]
+  #
+  # @api private
   def type_and_dots_and_tuplet_ratio(noteable_duration)
     r = decompose_as_sum_of_simple_durations(noteable_duration)
     n = r.shift
@@ -117,6 +273,18 @@ module Musa::Datasets::Score::ToMXML
     return type, dots, tuplet_ratio
   end
 
+  # Finds nearest power of 2 greater than or equal to number.
+  #
+  # @param number [Numeric] number to round up
+  #
+  # @return [Integer] nearest upper power of 2
+  #
+  # @example
+  #   nearest_upper_power_of_2(5)  # => 8
+  #   nearest_upper_power_of_2(8)  # => 8
+  #   nearest_upper_power_of_2(9)  # => 16
+  #
+  # @api private
   def nearest_upper_power_of_2(number)
     return 0 if number.zero?
 
@@ -127,6 +295,18 @@ module Musa::Datasets::Score::ToMXML
     2 ** (exp_floor + plus)
   end
 
+  # Finds nearest power of 2 less than or equal to number.
+  #
+  # @param number [Numeric] number to round down
+  #
+  # @return [Integer] nearest lower power of 2
+  #
+  # @example
+  #   nearest_lower_power_of_2(5)  # => 4
+  #   nearest_lower_power_of_2(8)  # => 8
+  #   nearest_lower_power_of_2(15) # => 8
+  #
+  # @api private
   def nearest_lower_power_of_2(number)
     return 0 if number.zero?
 
@@ -135,6 +315,25 @@ module Musa::Datasets::Score::ToMXML
     2 ** exp_floor
   end
 
+  # Converts duration to MusicXML note type name.
+  #
+  # Maps inverse powers of 2 to standard note type names.
+  # Duration must be power of 2 between 1/1024 and maxima (8 whole notes).
+  #
+  # @param base_type_duration [Numeric] duration as power of 2
+  #
+  # @return [String] MusicXML note type name
+  #
+  # @raise [ArgumentError] if duration is not power of 2 or out of range
+  #
+  # @example Standard durations
+  #   type_of(1r)    # => "quarter"
+  #   type_of(1/2r)  # => "eighth"
+  #   type_of(1/4r)  # => "16th"
+  #   type_of(2r)    # => "half"
+  #   type_of(4r)    # => "whole"
+  #
+  # @api private
   def type_of(base_type_duration)
     duration_log2i = Math.log2(base_type_duration)
 

data/lib/musa-dsl/datasets/score/to-mxml/to-mxml.rb

@@ -6,11 +6,137 @@ require_relative 'process-time'
 require_relative 'process-pdv'
 require_relative 'process-ps'
 
-module Musa::Datasets 
+module Musa::Datasets
   class Score
+    # MusicXML export for scores.
+    #
+    # ToMXML provides conversion of {Score} objects to MusicXML format,
+    # suitable for import into notation software like MuseScore, Finale,
+    # or Sibelius.
+    #
+    # ## Conversion Process
+    #
+    # 1. Creates MusicXML structure with metadata (title, creators, etc.)
+    # 2. Defines parts (instruments) with clefs and time signatures
+    # 3. Divides score into measures (bars)
+    # 4. Processes events in each measure:
+    #
+    #    - {PDV} events → notes and rests
+    #    - {PS} events → dynamics markings (crescendo, diminuendo)
+    #
+    # 5. Fills gaps with rests
+    #
+    # ## Event Types Supported
+    #
+    # - **{PDV}** (Pitch/Duration/Velocity): Converted to notes or rests
+    # - **{PS}** (Pitch Series): Converted to dynamics markings
+    #
+    # ## Multi-part Scores
+    #
+    # Scores can contain multiple instruments, differentiated by the
+    # :instrument attribute. Each part is rendered separately.
+    #
+    # ## Time Representation
+    #
+    # - Score times are 1-based (first beat is at position 1)
+    # - Each measure represents one bar
+    # - Duration is specified in beats (1.0 = quarter note if beat_type is 4)
+    #
+    # @example Basic single-part score
+    #   score = Musa::Datasets::Score.new
+    #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #   score.at(2r, add: { pitch: 64, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #
+    #   mxml = score.to_mxml(
+    #     4, 24,  # 4 beats per bar, 24 ticks per beat
+    #     bpm: 120,
+    #     title: 'My Song',
+    #     creators: { composer: 'John Doe' },
+    #     parts: { piano: { name: 'Piano', clefs: { g: 2 } } }
+    #   )
+    #
+    #   File.write('score.musicxml', mxml.to_xml.string)
+    #
+    # @example Multi-part score
+    #   score = Musa::Datasets::Score.new
+    #   score.at(1r, add: { instrument: :violin, pitch: 67, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #   score.at(1r, add: { instrument: :cello, pitch: 48, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #
+    #   mxml = score.to_mxml(
+    #     4, 24,
+    #     parts: {
+    #       violin: { name: 'Violin', clefs: { g: 2 } },
+    #       cello: { name: 'Cello', clefs: { f: 4 } }
+    #     }
+    #   )
+    #
+    # @example With dynamics
+    #   score = Musa::Datasets::Score.new
+    #   score.at(1r, add: { pitch: 60, duration: 2.0 }.extend(Musa::Datasets::PDV))
+    #   score.at(1r, add: { type: :crescendo, duration: 2.0 }.extend(Musa::Datasets::PS))
+    #
+    # @see Musa::MusicXML::Builder MusicXML builder
+    # @see PDV MIDI-style events
+    # @see PS Pitch series for dynamics
     module ToMXML
       using Musa::Extension::InspectNice
 
+      # Converts score to MusicXML.
+      #
+      # Creates complete MusicXML document with metadata, parts, measures,
+      # notes, rests, and dynamics markings.
+      #
+      # @param beats_per_bar [Integer] time signature numerator (e.g., 4 for 4/4)
+      # @param ticks_per_beat [Integer] resolution per beat (typically 24)
+      #
+      # @param bpm [Integer] tempo in beats per minute (default: 90)
+      # @param title [String] work title (default: 'Untitled')
+      # @param creators [Hash{Symbol => String}] creator roles and names
+      #   (default: { composer: 'Unknown' })
+      # @param encoding_date [DateTime, nil] encoding date for metadata
+      # @param parts [Hash{Symbol => Hash}] part definitions
+      #   Each part: { name: String, abbreviation: String, clefs: Hash }
+      #   Clefs: { clef_sign: line_number } (e.g., { g: 2, f: 4 } for piano)
+      # @param logger [Musa::Logger::Logger, nil] logger for debugging
+      # @param do_log [Boolean, nil] enable logging output
+      #
+      # @return [Musa::MusicXML::Builder::ScorePartwise] MusicXML document
+      #
+      # @example Simple piano score
+      #   score = Musa::Datasets::Score.new
+      #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #
+      #   mxml = score.to_mxml(
+      #     4, 24,
+      #     bpm: 120,
+      #     title: 'Invention',
+      #     creators: { composer: 'J.S. Bach' },
+      #     parts: { piano: { name: 'Piano', clefs: { g: 2, f: 4 } } }
+      #   )
+      #
+      # @example String quartet
+      #   score = Musa::Datasets::Score.new
+      #   score.at(1r, add: { instrument: :vln1, pitch: 67, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #   score.at(1r, add: { instrument: :vln2, pitch: 64, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #   score.at(1r, add: { instrument: :vla, pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #   score.at(1r, add: { instrument: :vc, pitch: 48, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #
+      #   mxml = score.to_mxml(
+      #     4, 24,
+      #     parts: {
+      #       vln1: { name: 'Violin I', abbreviation: 'Vln. I', clefs: { g: 2 } },
+      #       vln2: { name: 'Violin II', abbreviation: 'Vln. II', clefs: { g: 2 } },
+      #       vla: { name: 'Viola', abbreviation: 'Vla.', clefs: { c: 3 } },
+      #       vc: { name: 'Cello', abbreviation: 'Vc.', clefs: { f: 4 } }
+      #     }
+      #   )
+      #
+      # @example Export to file
+      #   score = Musa::Datasets::Score.new
+      #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #
+      #   mxml = score.to_mxml(4, 24, parts: { piano: { name: 'Piano' } })
+      #   File.write('output.musicxml', mxml.to_xml.string)
       def to_mxml(beats_per_bar, ticks_per_beat,
                   bpm: nil,
                   title: nil,
@@ -77,6 +203,24 @@ module Musa::Datasets
 
       private
 
+      # Fills a MusicXML part with measures and events.
+      #
+      # Processes each bar (measure) in the score, converting events to
+      # MusicXML notes, rests, and dynamics. Handles:
+      #
+      # - Initial silences (gaps before first event)
+      # - Event processing (PDV → notes, PS → dynamics)
+      # - Ending silences (filling remainder of measure)
+      #
+      # @param part [Musa::MusicXML::Builder::Part] MusicXML part to fill
+      # @param divisions_per_bar [Integer] total divisions in one bar
+      # @param instrument [Symbol, nil] instrument filter (nil for single-part scores)
+      # @param logger [Musa::Logger::Logger] logger for debugging
+      # @param do_log [Boolean] enable logging
+      #
+      # @return [void]
+      #
+      # @api private
       def fill_part(part, divisions_per_bar, instrument, logger, do_log)
         measure = nil
         dynamics_context = nil