calcpace 1.9.10 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e8d5ca7f00eaacd53af3a268a695a80523a497eedf9caebbd8c5459ea261808
-  data.tar.gz: 974e29530df057bcc3317c66d78343af96c30d246c076c51115a0bcfe93c0736
+  metadata.gz: 8bc8b750605e9b531f01c27f0839668a04f9acf1d0c45316cd8860761afffbae
+  data.tar.gz: ceb6a60b435735552b2fd7eb0e78ec131c73a9faa3ef22a84ce59dda20d6d375
 SHA512:
-  metadata.gz: 30f1a094b09bb131ad43923f6cabda560c4bb64b811c6b621d6b87e92f9f53101f9ff94f5a5c62926c003b743b53b3a2967e387c06effef1fd463de2481a0f8d
-  data.tar.gz: 38eb834c5acb4d18dc9729159733dc0ff72ec56d5e7391867c1182f1c2abe62dd690348afdee0686a5aa25f7570c3fe1e176d1cdd99671ad03e9c44eaa57cf7e
+  metadata.gz: 5b76dea0d30d9a98b6fa46364a1750f1d6051b342ae723205cf3e1b4560e3fc5ef568703df87c70cb74826434eedc78bcaa2d2cc57354b259521a371ecf9fd51
+  data.tar.gz: def67fc24bbab2e8d7275f2db2d9a2b8f724e9690b1a3bf40d2d329de919db1c6bf35dd37e2878b775ff943026a372b0eda3a5f27302ca980645ccf7e3c3f6f7

data/.rubocop.yml

@@ -50,6 +50,12 @@ Metrics/AbcSize:
   Exclude:
     - 'test/**/*'
 
+# Keyword arguments are self-documenting, so the ceiling is a little higher than
+# the default 5 — but it stays a ceiling: kwargs still count, so a method growing
+# to eight or ten of them is flagged.
+Metrics/ParameterLists:
+  Max: 6
+
 Metrics/BlockLength:
   Exclude:
     - 'test/**/*'

data/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-07-25
+
+### Added
+- Training zones improvements
+  - `training_paces` and `training_paces_from_race` accept `unit: :mi` for
+    pace bands per mile (default remains `:km`)
+  - `hr_zones_from_max(hr_max:)`: five heart-rate zones from maximum heart
+    rate only (%HRmax method) — fallback when resting heart rate is unknown
+  - `training_paces_from_race` accepts standard race names ('10k', 'marathon',
+    '5mile', ...) in addition to numeric kilometres, matching `predict_time`
+    and `race_pace`
+  - `distance_unit: :mi` keyword on `estimate_vo2max`, `estimate_detailed_vo2max`,
+    `age_grade`, `age_grade_percent`, and `training_paces_from_race` — numeric
+    distance inputs can now be given in miles (default remains kilometres)
+
+### Changed
+- `training_paces_from_race` resolves non-numeric distances as race names. Strings
+  that v1.10.0 silently parsed with `to_f` change meaning: `'5mile'` was 5.0 km and
+  is now the 5-mile standard distance (8.04672 km). Numeric strings (`'10'`,
+  `'21.0975'`) keep working as before, in kilometres.
+- `training_paces_from_race` with an unparseable distance (`nil`, `'banana'`) now
+  raises `ArgumentError` ("Unknown race: ...") instead of
+  `Calcpace::NonPositiveInputError`.
+- Unknown `unit:` / `distance_unit:` values raise `Calcpace::UnsupportedUnitError`
+  (inherits from `Calcpace::Error`) instead of `ArgumentError`. Unit keywords are
+  now case-insensitive (`'MI'` works) and `nil` raises the same error instead of a
+  `NoMethodError`.
+- `unit: :mi` pace bands are computed natively per mile instead of being converted
+  from the km bands, so they can differ by ±1 s from `pace_km_to_mi(km_band)` —
+  the native value is the one without double rounding.
+- Every mile-based factor now derives from the exact international mile
+  (1 mi = 1609.344 m), which was previously truncated to 1.60934 in some places
+  and exact in others. Affected values move by ~2.5e-6 relative:
+  `convert(1, :mi_to_km)` 1.60934 → 1.609344, `convert(1, :km_to_mi)` 0.621371 →
+  0.6213711922…, `convert(1, :mi_to_meters)` 1609.34 → 1609.344, the `mi_h`/`m_s`
+  speed pairs, and `list_races` entries `'1mile'` (1.609344) and `'10mile'`
+  (16.09344). Age-grading tolerance and pace bands now agree on mile length.
+- Passing `distance_unit:` together with a race name (`training_paces_from_race('10k',
+  t, distance_unit: :mi)`, `age_grade('10k', …, distance_unit: :mi)`) raises
+  `ArgumentError` instead of silently ignoring the keyword — a standard race already
+  carries its own distance.
+- Race-name lookup is normalized in one place: `' 10K '` and `:MARATHON` now resolve
+  everywhere (previously `PaceCalculator` did not strip whitespace), and `AgeGrading`
+  uses the same "Unknown race: …" message wording as the rest of the gem.
+
+### Fixed
+- Age grading accepts mile distances as runners write them (`3.1`, `6.2`, `13.1`,
+  `26.2` with `distance_unit: :mi`); the previous 0.001 km match window only
+  accepted 6-decimal conversions.
+- Unsupported age-grading distances report the input in the unit it was given
+  instead of always labelling it "km".
+- `estimate_detailed_vo2max` rejects a non-positive distance even when
+  `elevation_gain_m` is positive (the elevation adjustment used to mask it).
+
+## [1.10.0] - 2026-07-11
+
+### Added
+- Training Zones module (`TrainingZones`)
+  - `training_paces(vo2max)`: personalized Easy/Marathon/Threshold/Interval/Repetition
+    pace bands per km, inverting the Daniels & Gilbert velocity equation
+  - `training_paces_from_race(distance_km, time)`: pace bands straight from a race result
+  - `hr_zones(hr_max:, hr_rest:)`: five Karvonen (Heart Rate Reserve) heart-rate zones
+  - Structured results (`PaceBand`, `HrZone`) with seconds and clock formats
+
 ## [1.9.10] - 2026-07-09
 
 ### Changed
@@ -205,7 +269,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.9.6...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.10.0...HEAD
+[1.10.0]: https://github.com/0jonjo/calcpace/compare/v1.9.10...v1.10.0
 [1.9.6]: https://github.com/0jonjo/calcpace/compare/v1.9.5...v1.9.6
 [1.9.5]: https://github.com/0jonjo/calcpace/compare/v1.9.4...v1.9.5
 [1.6.0]: https://github.com/0jonjo/calcpace/releases/tag/v1.6.0

data/README.md

@@ -1,11 +1,11 @@
-# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.9.8&x2=0)](https://badge.fury.io/rb/calcpace)
+# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.10.0&x2=0)](https://badge.fury.io/rb/calcpace)
 
-A Ruby gem for running and cycling calculations: pace, time, distance, unit conversions, race predictions, GPS track analysis, and VO2max estimation.
+A Ruby gem for runners: pace, time, and distance calculations, unit conversions, race predictions, GPS track analysis, age grading, VO2max estimation, and training zones.
 
 ## Installation
 
 ```ruby
-gem 'calcpace', '~> 1.9.8'
+gem 'calcpace', '~> 1.10.0'
 ```
 
 ## Usage
@@ -76,8 +76,8 @@ calc.predict_time_cameron_adjusted('10k', '00:40:00', 'marathon', temperature: 8
 30+ units supported. String or symbol format:
 
 ```ruby
-calc.convert(10, :km_to_mi)         # => 6.21371
-calc.convert(10, 'mi to km')        # => 16.0934
+calc.convert(10, :km_to_mi)         # => 6.213711922...
+calc.convert(10, 'mi to km')        # => 16.09344
 calc.convert(1, :m_s_to_km_h)       # => 3.6
 
 # Chain conversions
@@ -169,6 +169,7 @@ age factors and open standards.
 
 ```ruby
 result = calc.age_grade(10.0, '00:45:00', age: 55, sex: :male)
+# numeric distances also accepted in miles: calc.age_grade(6.21371, '00:45:00', age: 55, sex: :male, distance_unit: :mi)
 # => {
 #      age_grade_percent: 64.6,
 #      category: "Local Class",
@@ -208,6 +209,7 @@ Estimate aerobic fitness from a race result using the **Daniels & Gilbert formul
 calc.estimate_vo2max(10.0, '00:40:00')   # => 51.9 ml/kg/min
 calc.estimate_vo2max(42.195, '03:30:00') # => 44.8
 calc.estimate_vo2max(5.0, 2400)          # also accepts total seconds
+calc.estimate_vo2max(6.21371, '00:40:00', distance_unit: :mi)  # => 51.9 (miles input)
 
 calc.vo2max_label(51.9)  # => "Very Good"
 ```
@@ -276,6 +278,51 @@ easy.value        # => 29.3   (underestimates real aerobic capacity)
 
 ---
 
+### Training Zones
+
+Personalized training paces (Daniels' Running Formula) and Karvonen heart-rate zones:
+
+```ruby
+zones = calc.training_paces(50.0)
+zones[:threshold].fast_clock   # => "00:04:15" per km
+zones[:easy].slow_clock        # => "00:05:52" per km
+
+calc.training_paces(50.0, unit: :mi)[:threshold].fast_clock  # => "00:06:51" per mile
+
+calc.training_paces_from_race(10.0, '00:40:00')                # from a recent race result
+calc.training_paces_from_race('5mile', '00:35:00', unit: :mi)  # race names work too
+calc.training_paces_from_race(6.2, '00:40:00', distance_unit: :mi, unit: :mi)  # race distance in miles
+
+calc.hr_zones(hr_max: 190, hr_rest: 55)
+# => [#<struct zone=1, min_bpm=123, max_bpm=136>, ... zone=5, max_bpm=190]
+
+calc.hr_zones_from_max(hr_max: 190)
+# => [#<struct zone=1, min_bpm=95, max_bpm=114>, ... zone=5, max_bpm=190]
+# %HRmax fallback — prefer hr_zones (Karvonen) when resting HR is known
+```
+
+| Zone | %VO2max | Purpose |
+|------|---------|---------|
+| Easy | 59–74% | Base building, recovery |
+| Marathon | 75–84% | Marathon race pace |
+| Threshold | 83–88% | Lactate threshold, tempo runs |
+| Interval | 95–100% | VO2max development |
+| Repetition | 105–110% | Speed and running economy |
+
+Pace accuracy vs published VDOT tables: within a few seconds per km
+(threshold matches exactly; easy band is a range heuristic).
+
+`unit:` sets the unit of the returned pace bands; `distance_unit:` sets the unit of a
+numeric race distance you pass in. Combining `distance_unit:` with a race name raises
+`ArgumentError` — `'10k'` already carries its own distance. Mile bands are computed
+natively (not converted from the km bands), so they can differ by ±1 s from
+`pace_km_to_mi(km_band)`.
+
+All mile factors derive from the exact international mile (1609.344 m), so distances,
+pace bands, and age-grading tolerances agree to the metre.
+
+---
+
 ### Other Utilities
 
 ```ruby
@@ -292,6 +339,11 @@ All errors inherit from `Calcpace::Error`:
 
 - `Calcpace::NonPositiveInputError` — numeric input is zero or negative
 - `Calcpace::InvalidTimeFormatError` — time string not in `HH:MM:SS` or `MM:SS` format
+- `Calcpace::UnsupportedUnitError` — unknown conversion (`convert`) or unknown
+  `unit:` / `distance_unit:` keyword
+
+Argument validation that is not about units or numbers raises a plain `ArgumentError`:
+unknown race names, unsupported age-grading distances, and invalid `age` / `sex` values.
 
 ---
 

data/calcpace.gemspec

@@ -8,11 +8,12 @@ Gem::Specification.new do |spec|
   spec.authors       = ['João Gilberto Saraiva']
   spec.email         = ['joaogilberto@tuta.io']
 
-  spec.summary       = 'Pace, distance, GPS track analysis, and VO2max calculations for runners and cyclists.'
-  spec.description   = 'Ruby gem for running and cycling calculations: pace, time, distance, ' \
-                       'unit conversions (30+ units), race predictions (Riegel & Cameron), ' \
+  spec.summary       = 'Running calculations: pace, race predictions, GPS track analysis, VO2max, and training zones.'
+  spec.description   = 'Ruby gem for runners: pace, time, and distance calculations, ' \
+                       'unit conversions (30+ units), race time predictions (Riegel & Cameron), ' \
                        'GPS track analysis (Haversine, elevation gain, per-km splits), ' \
-                       'and VO2max estimation (Daniels & Gilbert).'
+                       'age grading (WMA 2023), VO2max estimation (Daniels & Gilbert), and ' \
+                       'personalized training zones (Daniels paces & Karvonen heart-rate zones).'
   spec.homepage      = 'https://github.com/0jonjo/calcpace'
   spec.metadata['source_code_uri'] = spec.homepage
   spec.license = 'MIT'

data/lib/calcpace/age_grading.rb

@@ -49,14 +49,22 @@ module AgeGrading
 
   # Returns a full age-grading report for a race performance
   #
-  # @param distance_km [Numeric, String, Symbol] race distance in kilometres
-  #   (5.0, 10.0, 21.0975, 42.195) or race key (:5k, :10k, :half_marathon, :marathon)
+  # @param distance [Numeric, String, Symbol] race distance in kilometres
+  #   (5.0, 10.0, 21.0975, 42.195) or race key (:5k, :10k, :half_marathon, :marathon);
+  #   numeric input can also be given in miles via distance_unit: :mi
   # @param time [String, Numeric] performance time as HH:MM:SS / MM:SS, or total seconds
   # @param age [Integer] athlete age (must be >= 18)
   # @param sex [String, Symbol] male or female
+  # @param distance_unit [Symbol] unit of a numeric distance input — :km (default) or :mi.
+  #   Rejected when distance is a race key: standard races already carry their own
+  #   distance, so the combination is always a caller mistake
   # @return [Hash] age-grading result details
-  def age_grade(distance_km, time, age:, sex:)
-    distance_m = normalize_distance(distance_km)
+  # @raise [ArgumentError] if the distance, race key, age or sex is not supported,
+  #   or if distance_unit is combined with a race key
+  # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is malformed
+  def age_grade(distance, time, age:, sex:, distance_unit: nil)
+    distance_m = normalize_distance(distance, distance_unit)
     seconds = parse_time_seconds(time)
     age_value = normalize_age(age)
     sex_value = normalize_sex(sex)
@@ -83,13 +91,15 @@ module AgeGrading
 
   # Returns only the age-grade percentage
   #
-  # @param distance_km [Numeric] race distance in kilometres
+  # @param distance [Numeric, String, Symbol] race distance in kilometres or race key
   # @param time [String, Numeric] performance time
   # @param age [Integer] athlete age
   # @param sex [String, Symbol] male or female
+  # @param distance_unit [Symbol] unit of a numeric distance input — :km (default) or :mi
+  #   (rejected alongside race keys, see #age_grade)
   # @return [Float] age-grade percentage
-  def age_grade_percent(distance_km, time, age:, sex:)
-    age_grade(distance_km, time, age: age, sex: sex)[:age_grade_percent]
+  def age_grade_percent(distance, time, age:, sex:, distance_unit: nil)
+    age_grade(distance, time, age: age, sex: sex, distance_unit: distance_unit)[:age_grade_percent]
   end
 
   # Returns a descriptive label for an age-grade percentage
@@ -110,23 +120,35 @@ module AgeGrading
 
   private
 
-  def normalize_distance(distance_km)
-    if distance_km.is_a?(String) || distance_km.is_a?(Symbol)
-      key = distance_km.to_s.strip.downcase
-      return RACE_TO_METERS.fetch(key) if RACE_TO_METERS.key?(key)
-
-      raise ArgumentError,
-            "Unsupported race '#{distance_km}'. Supported: #{RACE_TO_METERS.keys.join(', ')}"
+  def normalize_distance(distance_input, distance_unit = nil)
+    if distance_input.is_a?(String) || distance_input.is_a?(Symbol)
+      reject_distance_unit_with_race_name!(distance_unit, distance_input)
+      return race_key_to_meters(distance_input)
     end
 
-    distance = distance_km.to_f
+    distance = normalize_distance_km(distance_input, distance_unit || :km)
     check_positive(distance, 'Distance')
 
-    match = SUPPORTED_DISTANCES_KM.find { |value| (distance - value).abs <= 0.001 }
+    match = SUPPORTED_DISTANCES_KM.find { |value| standard_distance?(distance, value) }
     return DISTANCE_TO_METERS.fetch(match) if match
 
     raise ArgumentError,
-          "Unsupported distance #{distance_km}km. Supported: #{SUPPORTED_DISTANCES_KM.join(', ')}"
+          "Unsupported distance #{distance_input}#{(distance_unit || :km).to_s.downcase}. " \
+          "Supported: #{SUPPORTED_DISTANCES_KM.join(', ')} km"
+  end
+
+  def race_key_to_meters(race_input)
+    # normalize_race_key is PaceCalculator's — one lookup convention gem-wide
+    RACE_TO_METERS.fetch(normalize_race_key(race_input)) do
+      raise ArgumentError,
+            "Unknown race: #{race_input}. Available races: #{RACE_TO_METERS.keys.join(', ')}"
+    end
+  end
+
+  # Runners write rounded distances (3.1 mi, 13.1 mi, 26.2 mi), so the match
+  # window is relative — 0.5% of the standard distance, never below 1 metre
+  def standard_distance?(distance, standard)
+    (distance - standard).abs <= [0.001, standard * 0.005].max
   end
 
   def parse_time_seconds(time)

data/lib/calcpace/converter.rb

@@ -7,14 +7,18 @@
 # speed units (m/s, km/h, mi/h, knots, etc.).
 module Converter
   module Distance
-    KM_TO_MI = 0.621371
-    MI_TO_KM = 1.60934
+    # One international mile is exactly 1609.344 m. Every mile-based factor
+    # derives from this single value so that no two call sites — a pace band, a
+    # distance conversion, an age-grading tolerance — can disagree about how
+    # long a mile is.
+    MI_TO_KM = 1.609344
+    KM_TO_MI = 1 / MI_TO_KM
     NAUTICAL_MI_TO_KM = 1.852
     KM_TO_NAUTICAL_MI = 0.539957
     METERS_TO_KM = 0.001
     KM_TO_METERS = 1000
-    METERS_TO_MI = 0.000621371
-    MI_TO_METERS = 1609.34
+    MI_TO_METERS = MI_TO_KM * 1000
+    METERS_TO_MI = 1 / MI_TO_METERS
     METERS_TO_FEET = 3.28084
     FEET_TO_METERS = 0.3048
     METERS_TO_YARDS = 1.09361
@@ -28,30 +32,30 @@ module Converter
     KM_TO_INCHES = 39_370.1
     INCHES_TO_KM = 0.0000254
     MI_TO_YARDS = 1760
-    YARDS_TO_MI = 0.000568182
+    YARDS_TO_MI = 1.0 / MI_TO_YARDS
     MI_TO_FEET = 5280
-    FEET_TO_MI = 0.000189394
+    FEET_TO_MI = 1.0 / MI_TO_FEET
     MI_TO_INCHES = 63_360
-    INCHES_TO_MI = 0.0000157828
+    INCHES_TO_MI = 1.0 / MI_TO_INCHES
   end
 
   module Speed
     M_S_TO_KM_H = 3.6
     KM_H_TO_M_S = 0.277778
-    M_S_TO_MI_H = 2.23694
-    MI_H_TO_M_S = 0.44704
+    M_S_TO_MI_H = 3.6 / Distance::MI_TO_KM
+    MI_H_TO_M_S = Distance::MI_TO_METERS / 3600
     M_S_TO_NAUTICAL_MI_H = 1.94384
     NAUTICAL_MI_H_TO_M_S = 0.514444
     M_S_TO_FEET_S = 3.28084
     FEET_S_TO_M_S = 0.3048
     M_S_TO_KNOTS = 1.94384
     KNOTS_TO_M_S = 0.514444
-    KM_H_TO_MI_H = 0.621371
-    MI_H_TO_KM_H = 1.60934
+    KM_H_TO_MI_H = Distance::KM_TO_MI
+    MI_H_TO_KM_H = Distance::MI_TO_KM
     KM_H_TO_NAUTICAL_MI_H = 0.539957
     NAUTICAL_MI_H_TO_KM_H = 1.852
-    MI_H_TO_NAUTICAL_MI_H = 0.868976
-    NAUTICAL_MI_H_TO_MI_H = 1.15078
+    MI_H_TO_NAUTICAL_MI_H = Distance::MI_TO_KM / Distance::NAUTICAL_MI_TO_KM
+    NAUTICAL_MI_H_TO_MI_H = Distance::NAUTICAL_MI_TO_KM / Distance::MI_TO_KM
   end
 
   # Converts a value from one unit to another
@@ -139,8 +143,35 @@ module Converter
     format_list(Distance.constants)
   end
 
+  # Multipliers from a supported distance-input unit to kilometres
+  # (used by methods that accept a distance_unit: keyword)
+  DISTANCE_UNIT_TO_KM = { km: 1.0, mi: Distance::MI_TO_KM }.freeze
+
   private
 
+  # Guards the "race name + distance_unit" combination. A standard race already
+  # carries its own distance, so the keyword can only be a caller mistake —
+  # better to say so than to ignore it silently.
+  #
+  # @raise [ArgumentError] if a distance_unit was given alongside a race name
+  def reject_distance_unit_with_race_name!(distance_unit, race)
+    return if distance_unit.nil?
+
+    raise ArgumentError,
+          "distance_unit: #{distance_unit.inspect} cannot be combined with the race name " \
+          "#{race.inspect} — a standard race already carries its own distance"
+  end
+
+  # Normalizes a numeric distance input to kilometres
+  #
+  # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
+  def normalize_distance_km(value, distance_unit)
+    factor = DISTANCE_UNIT_TO_KM.fetch(distance_unit.to_s.downcase.to_sym) do
+      raise Calcpace::UnsupportedUnitError.new(distance_unit, supported: DISTANCE_UNIT_TO_KM.keys)
+    end
+    value.to_f * factor
+  end
+
   def format_unit(unit)
     unit.downcase.gsub(' ', '_').to_sym
   end

data/lib/calcpace/errors.rb

@@ -20,11 +20,27 @@ class Calcpace
     end
   end
 
-  # Raised when an unsupported unit conversion is requested
+  # Raised when an unsupported unit or unit conversion is requested
+  #
+  # @example conversion pair
+  #   raise UnsupportedUnitError, :km_to_furlong
+  # @example single unit, with the supported ones listed
+  #   raise UnsupportedUnitError.new(:furlong, supported: %i[km mi])
   class UnsupportedUnitError < Error
-    def initialize(unit = nil)
-      msg = unit ? "Unsupported unit conversion: #{unit}" : 'Unsupported unit conversion'
-      super(msg)
+    def initialize(unit = nil, supported: nil)
+      super(build_message(unit, supported))
+    end
+
+    private
+
+    def build_message(unit, supported)
+      return conversion_message(unit) unless supported
+
+      "Unsupported unit: #{unit.inspect}. Supported units: #{supported.map(&:inspect).join(', ')}"
+    end
+
+    def conversion_message(unit)
+      unit ? "Unsupported unit conversion: #{unit}" : 'Unsupported unit conversion'
     end
   end
 end

data/lib/calcpace/pace_calculator.rb

@@ -12,9 +12,9 @@ module PaceCalculator
     'half_marathon' => 21.0975,
     'marathon' => 42.195,
     '100k' => 100.0,
-    '1mile' => 1.60934,
-    '5mile' => 8.04672,
-    '10mile' => 16.0934
+    '1mile' => Converter::Distance::MI_TO_KM,
+    '5mile' => 5 * Converter::Distance::MI_TO_KM,
+    '10mile' => 10 * Converter::Distance::MI_TO_KM
   }.freeze
 
   # Calculates the finish time for a race given a pace per kilometer
@@ -93,10 +93,18 @@ module PaceCalculator
   # @return [Float] distance in kilometers
   # @raise [ArgumentError] if race is not recognized
   def race_distance(race)
-    key = race.to_s.downcase
-    RACE_DISTANCES.fetch(key) do
+    RACE_DISTANCES.fetch(normalize_race_key(race)) do
       raise ArgumentError,
             "Unknown race: #{race}. Available races: #{RACE_DISTANCES.keys.join(', ')}"
     end
   end
+
+  # Single normalization for every race-name lookup in the gem (here and in
+  # AgeGrading), so ' 10K ' and :marathon always resolve like '10k' and 'marathon'
+  #
+  # @param race [String, Symbol] race name in any case, with or without padding
+  # @return [String] normalized lookup key
+  def normalize_race_key(race)
+    race.to_s.strip.downcase
+  end
 end

data/lib/calcpace/training_zones.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Module for deriving personalized training zones from VO2max
+#
+# Training paces invert the Daniels & Gilbert (1979) velocity equation:
+#   VO2 = -4.60 + 0.182258 * v + 0.000104 * v²   (v in m/min)
+# Solving the quadratic for v at a target %VO2max gives the running
+# velocity for each training intensity (Daniels' Running Formula).
+#
+# Heart rate zones use the Karvonen method (Heart Rate Reserve):
+#   target = hr_rest + pct * (hr_max - hr_rest)
+module TrainingZones
+  # Training intensities as fraction of VO2max (Daniels' Running Formula)
+  TRAINING_INTENSITIES = {
+    easy: { low: 0.59, high: 0.74 },
+    marathon: { low: 0.75, high: 0.84 },
+    threshold: { low: 0.83, high: 0.88 },
+    interval: { low: 0.95, high: 1.00 },
+    repetition: { low: 1.05, high: 1.10 }
+  }.freeze
+
+  # A pace band for one training zone (paces per kilometre or mile).
+  # slow = lower-intensity end of the band, fast = higher-intensity end.
+  PaceBand = Struct.new(:slow_seconds, :fast_seconds, :slow_clock, :fast_clock)
+
+  # Metres per pace unit — pace bands can be expressed per km or per mile
+  PACE_UNIT_METERS = { km: 1000.0, mi: Converter::Distance::MI_TO_METERS }.freeze
+
+  # Heart-rate zone boundaries as fractions of the range being split:
+  # Heart Rate Reserve in #hr_zones (Karvonen) and HRmax in #hr_zones_from_max
+  HR_ZONE_BOUNDARIES = [0.50, 0.60, 0.70, 0.80, 0.90, 1.00].freeze
+
+  # One heart-rate training zone (1 = recovery … 5 = maximal)
+  HrZone = Struct.new(:zone, :min_bpm, :max_bpm)
+
+  # Derives training pace bands from a VO2max value
+  #
+  # @param vo2max [Numeric] VO2max in ml/kg/min (must be > 0)
+  # @param unit [Symbol] pace unit — :km (default) or :mi
+  # @return [Hash{Symbol => PaceBand}] keys: :easy, :marathon, :threshold,
+  #   :interval, :repetition — paces per chosen unit
+  # @raise [Calcpace::NonPositiveInputError] if vo2max is not positive
+  # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
+  #
+  # @example
+  #   calc.training_paces(50.0)[:threshold].fast_clock             #=> "00:04:15"
+  #   calc.training_paces(50.0, unit: :mi)[:threshold].fast_clock  #=> "00:06:51"
+  def training_paces(vo2max, unit: :km)
+    check_positive(vo2max.to_f, 'VO2max')
+    meters = pace_unit_meters(unit)
+
+    TRAINING_INTENSITIES.transform_values do |band|
+      slow = pace_seconds_at_pct(vo2max.to_f, band[:low], meters)
+      fast = pace_seconds_at_pct(vo2max.to_f, band[:high], meters)
+
+      PaceBand.new(
+        slow_seconds: slow,
+        fast_seconds: fast,
+        slow_clock: convert_to_clocktime(slow),
+        fast_clock: convert_to_clocktime(fast)
+      )
+    end
+  end
+
+  # Derives training pace bands from a recent race result
+  #
+  # Convenience wrapper: estimates VO2max via Daniels & Gilbert
+  # (see Vo2maxEstimator#estimate_vo2max) and derives the bands from it.
+  #
+  # @param race [Numeric, String, Symbol] race distance in kilometres (or in
+  #   miles via distance_unit: :mi), either numeric or as a numeric string
+  #   ('10', '21.0975'), or a standard race name ('5k', '10k', 'half_marathon',
+  #   'marathon', '1mile', '5mile', '10mile', '100k' — see
+  #   PaceCalculator::RACE_DISTANCES)
+  # @param time [String, Integer] finish time as "HH:MM:SS" / "MM:SS" or total seconds
+  # @param unit [Symbol] pace unit of the output bands — :km (default) or :mi
+  # @param distance_unit [Symbol] unit of a numeric race distance input — :km (default) or :mi.
+  #   Rejected when race is a race name: standard races already carry their own
+  #   distance, so the combination is always a caller mistake
+  # @return [Hash{Symbol => PaceBand}] same shape as #training_paces
+  # @raise [ArgumentError] if a race name is not recognized, or if distance_unit
+  #   is combined with a race name
+  # @raise [Calcpace::UnsupportedUnitError] if unit or distance_unit is not :km or :mi
+  # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is malformed
+  #
+  # @example
+  #   calc.training_paces_from_race(10.0, '00:40:00')[:easy].slow_clock #=> "00:05:42"
+  #   calc.training_paces_from_race('5mile', '00:35:00', unit: :mi)
+  #   calc.training_paces_from_race(6.2, '00:40:00', distance_unit: :mi, unit: :mi)
+  def training_paces_from_race(race, time, unit: :km, distance_unit: nil)
+    # Numeric strings ('10') keep working as distances; only non-numeric input
+    # (race names) falls through to the RACE_DISTANCES lookup
+    numeric = race.is_a?(Numeric) ? race : Float(race, exception: false)
+    distance_km = if numeric
+                    normalize_distance_km(numeric, distance_unit || :km)
+                  else
+                    reject_distance_unit_with_race_name!(distance_unit, race)
+                    race_distance(race)
+                  end
+
+    training_paces(estimate_vo2max(distance_km, time), unit: unit)
+  end
+
+  # Computes the five Karvonen heart-rate training zones
+  #
+  # target_bpm = hr_rest + pct * (hr_max - hr_rest)
+  #
+  # @param hr_max [Numeric] maximum heart rate in bpm (must be > 0)
+  # @param hr_rest [Numeric] resting heart rate in bpm (must be > 0 and < hr_max)
+  # @return [Array<HrZone>] five contiguous zones from Z1 (50–60% HRR) to Z5 (90–100% HRR)
+  # @raise [Calcpace::NonPositiveInputError] if any rate is not positive
+  # @raise [Calcpace::Error] if hr_rest >= hr_max
+  #
+  # @example
+  #   calc.hr_zones(hr_max: 190, hr_rest: 55).last.max_bpm #=> 190
+  def hr_zones(hr_max:, hr_rest:)
+    max  = hr_max.to_f
+    rest = hr_rest.to_f
+    check_heart_rates(max, rest)
+
+    reserve = max - rest
+    build_hr_zones(HR_ZONE_BOUNDARIES.map { |pct| (rest + (pct * reserve)).round })
+  end
+
+  # Computes five heart-rate zones from maximum heart rate only (%HRmax method)
+  #
+  # Fallback for athletes who don't know their resting heart rate — the
+  # classic percent-of-max model used as default by most sports watches:
+  #   target_bpm = pct * hr_max
+  #
+  # Prefer #hr_zones (Karvonen) when resting heart rate is available.
+  #
+  # @param hr_max [Numeric] maximum heart rate in bpm (must be > 0)
+  # @return [Array<HrZone>] five contiguous zones from Z1 (50–60% HRmax) to Z5 (90–100% HRmax)
+  # @raise [Calcpace::NonPositiveInputError] if hr_max is not positive
+  #
+  # @example
+  #   calc.hr_zones_from_max(hr_max: 190).first.min_bpm #=> 95
+  def hr_zones_from_max(hr_max:)
+    max = hr_max.to_f
+    check_positive(max, 'Maximum heart rate')
+
+    build_hr_zones(HR_ZONE_BOUNDARIES.map { |pct| (pct * max).round })
+  end
+
+  private
+
+  # Turns six ascending bpm boundary points into five contiguous HrZone structs
+  def build_hr_zones(points)
+    points.each_cons(2).with_index(1).map do |(min_bpm, max_bpm), zone|
+      HrZone.new(zone: zone, min_bpm: min_bpm, max_bpm: max_bpm)
+    end
+  end
+
+  def check_heart_rates(hr_max, hr_rest)
+    check_positive(hr_max, 'Maximum heart rate')
+    check_positive(hr_rest, 'Resting heart rate')
+    return if hr_rest < hr_max
+
+    raise Calcpace::Error,
+          "Resting heart rate (#{hr_rest}) must be lower than maximum heart rate (#{hr_max})"
+  end
+
+  # Inverts Daniels & Gilbert: velocity (m/min) that demands a given VO2
+  def velocity_at_vo2(vo2)
+    a = 0.000104
+    b = 0.182258
+    c = -(4.60 + vo2)
+
+    (-b + Math.sqrt((b**2) - (4 * a * c))) / (2 * a)
+  end
+
+  def pace_unit_meters(unit)
+    PACE_UNIT_METERS.fetch(unit.to_s.downcase.to_sym) do
+      raise Calcpace::UnsupportedUnitError.new(unit, supported: PACE_UNIT_METERS.keys)
+    end
+  end
+
+  def pace_seconds_at_pct(vo2max, pct, meters)
+    velocity = velocity_at_vo2(vo2max * pct)
+    (meters * 60.0 / velocity).round
+  end
+end

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.9.10'
+  VERSION = '1.11.0'
 end

data/lib/calcpace/vo2max_estimator.rb

@@ -32,17 +32,21 @@ module Vo2maxEstimator
 
   # Estimates VO2max from a race performance using Daniels & Gilbert formula
   #
-  # @param distance_km [Numeric] race distance in kilometres (must be > 0)
+  # @param distance [Numeric] race distance (must be > 0), in kilometres by
+  #   default or in the unit given by distance_unit
   # @param time [String, Integer] finish time as "HH:MM:SS" / "MM:SS", or total seconds (must be > 0)
+  # @param distance_unit [Symbol] unit of the distance input — :km (default) or :mi
   # @return [Float] estimated VO2max in ml/kg/min, rounded to one decimal place
   # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
   # @raise [Calcpace::InvalidTimeFormatError] if time string is not in HH:MM:SS or MM:SS format
+  # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
   #
   # @example 10 km in 40:00 → ~51.9 ml/kg/min
   #   calc = Calcpace.new
-  #   calc.estimate_vo2max(10.0, '00:40:00') #=> 51.9
-  def estimate_vo2max(distance_km, time)
-    distance_m = distance_km.to_f * 1000
+  #   calc.estimate_vo2max(10.0, '00:40:00')                    #=> 51.9
+  #   calc.estimate_vo2max(6.21371, '00:40:00', distance_unit: :mi) #=> 51.9
+  def estimate_vo2max(distance, time, distance_unit: :km)
+    distance_m = normalize_distance_km(distance, distance_unit) * 1000
     time_min   = parse_time_minutes(time)
 
     check_positive(distance_m, 'Distance')
@@ -57,13 +61,23 @@ module Vo2maxEstimator
 
   # Estimates a detailed and contextualized VO2max
   #
-  # @param distance_km [Numeric] race distance in kilometres
+  # @param distance [Numeric] race distance, in kilometres by default or in
+  #   the unit given by distance_unit
   # @param time [String, Integer] finish time
   # @param elevation_gain_m [Numeric] total elevation gain in metres
   # @param hr_avg [Numeric] average heart rate during the effort
   # @param hr_max [Numeric] athlete's maximum heart rate
+  # @param distance_unit [Symbol] unit of the distance input — :km (default) or :mi
   # @return [Vo2maxResult] structured result with value and metadata
-  def estimate_detailed_vo2max(distance_km, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil)
+  #   (adjusted_distance_km is always in kilometres)
+  # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
+  # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
+  def estimate_detailed_vo2max(distance, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil, distance_unit: :km)
+    distance_km = normalize_distance_km(distance, distance_unit)
+    # Validated before the elevation adjustment, which would otherwise turn a
+    # negative distance into a positive equivalent-flat one
+    check_positive(distance_km, 'Distance')
+
     adj_dist_km = adjusted_distance_for_vo2(distance_km, elevation_gain_m)
     vo2max_val  = estimate_vo2max(adj_dist_km, time)
     confidence  = calculate_time_confidence(parse_time_minutes(time))

data/lib/calcpace.rb

@@ -13,6 +13,7 @@ require_relative 'calcpace/pace_converter'
 require_relative 'calcpace/race_predictor'
 require_relative 'calcpace/race_splits'
 require_relative 'calcpace/track_calculator'
+require_relative 'calcpace/training_zones'
 require_relative 'calcpace/vo2max_estimator'
 
 # Calcpace - A Ruby gem for pace, distance, and time calculations
@@ -49,6 +50,7 @@ class Calcpace
   include RacePredictor
   include RaceSplits
   include TrackCalculator
+  include TrainingZones
   include Vo2maxEstimator
 
   # Creates a new Calcpace instance

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.9.10
+  version: 1.11.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -9,9 +9,11 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Ruby gem for running and cycling calculations: pace, time, distance,
-  unit conversions (30+ units), race predictions (Riegel & Cameron), GPS track analysis
-  (Haversine, elevation gain, per-km splits), and VO2max estimation (Daniels & Gilbert).'
+description: 'Ruby gem for runners: pace, time, and distance calculations, unit conversions
+  (30+ units), race time predictions (Riegel & Cameron), GPS track analysis (Haversine,
+  elevation gain, per-km splits), age grading (WMA 2023), VO2max estimation (Daniels
+  & Gilbert), and personalized training zones (Daniels paces & Karvonen heart-rate
+  zones).'
 email:
 - joaogilberto@tuta.io
 executables: []
@@ -47,6 +49,7 @@ files:
 - lib/calcpace/race_predictor.rb
 - lib/calcpace/race_splits.rb
 - lib/calcpace/track_calculator.rb
+- lib/calcpace/training_zones.rb
 - lib/calcpace/version.rb
 - lib/calcpace/vo2max_estimator.rb
 homepage: https://github.com/0jonjo/calcpace
@@ -70,8 +73,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Pace, distance, GPS track analysis, and VO2max calculations for runners and
-  cyclists.
+summary: 'Running calculations: pace, race predictions, GPS track analysis, VO2max,
+  and training zones.'
 test_files: []