fix: correct fractional_beat calculation to always use finest level

The fractional_beat should always represent the position within the finest
hierarchical level unit (between pulses), regardless of the reference_level
parameter. The reference_level only affects hierarchical_position truncation.

Fixed examples:
- meter.get_musical_time(0.125) now returns C0:0.2+0.000 (was C0:0.2+0.500)
- meter.get_musical_time(0.0625) now returns C0:0.1+0.000 (was C0:0.1+0.250)
- meter.get_musical_time(0.03125) now returns C0:0.0+0.500 (was C0:0.0+0.125)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jon-myers

idtap/classes/meter.py

@@ -621,99 +621,40 @@ def get_musical_time(self, real_time: float, reference_level: Optional[int] = No
                 remaining_time = remaining_time % subdivision_duration
 
         # Step 4: Fractional beat calculation
-        if ref_level == len(self.hierarchy) - 1:
-            # Default behavior: pulse-based calculation, but check for sparse pulse data
-            expected_pulses = self._pulses_per_cycle * self.repetitions
-            if len(self.all_pulses) < expected_pulses * 0.5:  # Less than 50% of expected pulses
-                # Fall back to proportional timing calculation for sparse pulse data
-                # For fractional_beat, we need the containing unit (parent) duration and start time
-                if ref_level == 0:
-                    # Ref level 0: fractional position within the cycle
-                    current_level_start_time = self.start_time + cycle_number * self.cycle_dur
-                    level_duration = self.cycle_dur
-                else:
-                    # Ref level > 0: fractional position within the parent unit
-                    parent_positions = positions[:ref_level]  # Parent positions
-                    current_level_start_time = self._calculate_proportional_level_start_time(parent_positions, cycle_number, ref_level - 1)
-                    level_duration = self._calculate_proportional_level_duration(parent_positions, cycle_number, ref_level - 1)
-                
-                if level_duration <= 0:
-                    fractional_beat = 0.0
-                else:
-                    time_from_level_start = real_time - current_level_start_time
-                    fractional_beat = time_from_level_start / level_duration
-            else:
-                # Use pulse-based calculation for complete pulse data
-                current_pulse_index = self._hierarchical_position_to_pulse_index(positions, cycle_number)
-                
-                # Add bounds checking for pulse access
-                if current_pulse_index < 0 or current_pulse_index >= len(self.all_pulses):
-                    # Fall back to proportional calculation if pulse index out of bounds
-                    # For fractional_beat, we need the containing unit (parent) duration and start time
-                    if ref_level == 0:
-                        # Ref level 0: fractional position within the cycle
-                        current_level_start_time = self.start_time + cycle_number * self.cycle_dur
-                        level_duration = self.cycle_dur
-                    else:
-                        # Ref level > 0: fractional position within the parent unit
-                        parent_positions = positions[:ref_level]  # Parent positions
-                        current_level_start_time = self._calculate_proportional_level_start_time(parent_positions, cycle_number, ref_level - 1)
-                        level_duration = self._calculate_proportional_level_duration(parent_positions, cycle_number, ref_level - 1)
-                    
-                    if level_duration <= 0:
-                        fractional_beat = 0.0
-                    else:
-                        time_from_level_start = real_time - current_level_start_time
-                        fractional_beat = time_from_level_start / level_duration
-                else:
-                    # Safe pulse-based calculation - use parent unit logic for reference levels
-                    if ref_level == 0:
-                        # Ref level 0: fractional position within the cycle
-                        current_level_start_time = self.start_time + cycle_number * self.cycle_dur
-                        level_duration = self.cycle_dur
-                    else:
-                        # For ref_level > 0: fractional position within the parent unit
-                        parent_positions = positions[:ref_level]  # Truncate to parent level
-                        current_level_start_time = self._calculate_proportional_level_start_time(parent_positions, cycle_number, ref_level - 1)
-                        level_duration = self._calculate_proportional_level_duration(parent_positions, cycle_number, ref_level - 1)
-                    
-                    if level_duration <= 0:
-                        fractional_beat = 0.0
-                    else:
-                        time_from_level_start = real_time - current_level_start_time
-                        fractional_beat = time_from_level_start / level_duration
-            
-            # Clamp to [0, 1] range
-            fractional_beat = max(0.0, min(1.0, fractional_beat))
-            
+        # ALWAYS calculate fractional_beat as position within finest level unit (between pulses)
+        # This is independent of reference_level, which only affects hierarchical_position truncation
+        current_pulse_index = self._hierarchical_position_to_pulse_index(positions, cycle_number)
+        
+        # Bounds checking
+        if current_pulse_index < 0 or current_pulse_index >= len(self.all_pulses):
+            fractional_beat = 0.0
         else:
-            # Reference level behavior
-            truncated_positions = positions[:ref_level + 1]
+            current_pulse_time = self.all_pulses[current_pulse_index].real_time
 
-            # For fractional_beat calculation, we need the containing unit (parent) duration and start time
-            if ref_level == 0:
-                # Ref level 0: fractional position within the cycle
-                current_level_start_time = self.start_time + cycle_number * self.cycle_dur
-                level_duration = self.cycle_dur
+            # Handle next pulse
+            if current_pulse_index + 1 < len(self.all_pulses):
+                next_pulse_time = self.all_pulses[current_pulse_index + 1].real_time
             else:
-                # Ref level > 0: fractional position within the parent unit
-                parent_positions = truncated_positions[:-1]  # Remove the last position for parent unit
-                current_level_start_time = self._calculate_proportional_level_start_time(parent_positions, cycle_number, ref_level - 1)
-                level_duration = self._calculate_proportional_level_duration(parent_positions, cycle_number, ref_level - 1)
+                # Last pulse - use next cycle start
+                next_cycle_start = self.start_time + (cycle_number + 1) * self.cycle_dur
+                next_pulse_time = next_cycle_start
 
-            if level_duration <= 0:
+            pulse_duration = next_pulse_time - current_pulse_time
+            if pulse_duration <= 0:
                 fractional_beat = 0.0
             else:
-                time_from_level_start = real_time - current_level_start_time
-                fractional_beat = time_from_level_start / level_duration
-            
-            # Clamp to [0, 1] range
-            fractional_beat = max(0.0, min(1.0, fractional_beat))
-            
-            # Update positions to only include levels up to reference for final result
-            positions = truncated_positions
+                time_from_current_pulse = real_time - current_pulse_time
+                fractional_beat = time_from_current_pulse / pulse_duration
+        
+        # Clamp to [0, 1] range
+        fractional_beat = max(0.0, min(1.0, fractional_beat))
+        
+        # Step 5: Handle reference level truncation (if specified)
+        if ref_level is not None and ref_level < len(self.hierarchy) - 1:
+            # Truncate positions to reference level for final result
+            positions = positions[:ref_level + 1]
 
-        # Step 5: Result construction
+        # Step 6: Result construction
         return MusicalTime(
             cycle_number=cycle_number,
             hierarchical_position=positions,

idtap/tests/musical_time_test.py

@@ -93,13 +93,13 @@ def test_reference_level_beat(self):
         """Test Case 2 from spec: Reference level at beat level."""
         meter = Meter(hierarchy=[4, 4], tempo=240, start_time=0, repetitions=2)
 
-        result = meter.get_musical_time(1.375, reference_level=0)  # Within bounds: 1.375 = 37.5% through cycle
+        result = meter.get_musical_time(1.375, reference_level=0)  # 1.375s = 2nd cycle, beat 1, subdivision 2 (exactly on pulse)
 
         assert result is not False
         assert result.cycle_number == 1  # Second cycle
-        assert result.hierarchical_position == [1]  # Only beat level (beat 2)
-        assert abs(result.fractional_beat - 0.375) < 0.01  # 37.5% through cycle (ref_level=0 = within cycle)
-        assert "C1:1+" in str(result)
+        assert result.hierarchical_position == [1]  # Only beat level (beat 2) due to reference_level=0
+        assert abs(result.fractional_beat - 0.0) < 0.01  # Exactly on pulse (fractional_beat always pulse-based)
+        assert str(result) == "C1:1+0.000"
 
     def test_reference_level_subdivision(self):
         """Test Case 3 from spec: Reference level at subdivision level."""
@@ -113,6 +113,26 @@ def test_reference_level_subdivision(self):
         assert abs(result.fractional_beat - 0.5) < 0.01  # 50% through beat (ref_level=1 = within beat)
         assert str(result) == "C0:1.2+0.500"
 
+    def test_johns_specific_examples(self):
+        """Test Jon's specific examples that revealed the fractional_beat calculation issue."""
+        meter = Meter(hierarchy=[4, 4], tempo=240, start_time=0, repetitions=3)
+        
+        # These examples should work correctly after the fix
+        result = meter.get_musical_time(0.5)
+        assert str(result) == "C0:2.0+0.000", f"Expected C0:2.0+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.25)
+        assert str(result) == "C0:1.0+0.000", f"Expected C0:1.0+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.125)
+        assert str(result) == "C0:0.2+0.000", f"Expected C0:0.2+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.0625)
+        assert str(result) == "C0:0.1+0.000", f"Expected C0:0.1+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.03125)
+        assert str(result) == "C0:0.0+0.500", f"Expected C0:0.0+0.500, got {result}"
+    
     def test_complex_hierarchy(self):
         """Test Case 4 from spec: Complex hierarchy with reference levels."""
         meter = Meter(hierarchy=[3, 2, 4], tempo=480, start_time=0, repetitions=1)  # Slower tempo