calcpace 1.10.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d89d16ea156af81fa6cd59976eebf680d435b38b41a65fcd46ee79ec2ea5fe6
-  data.tar.gz: b79d25c3f1da091543d1f1a930350bdd846ff15369f7e8476303e99aeccbcc79
+  metadata.gz: 42ce231ceded47814ccd2f3a0e8ecb79d0e8572253533980a76e11a70afeb6f1
+  data.tar.gz: a2680a1f0607ef49d5178431b415cce7e0945a722ad3dbec8bb58b2c2a698131
 SHA512:
-  metadata.gz: 1582ebc32a95e1e7702881c0efc16da68768a6616382bb1fb8102e83c9be665ac3f8eb3524f1581f0ec82db1d05e1db2eedf2217b822f959a2dc62711e6b8aa5
-  data.tar.gz: 9b95fd1feacc28b87a6477788a76bf141651cfa0ee254d4923ccc44cb9f6af63feb666046835c01d3ff5ddd65fb1632ef5d7825b540933ea3295f1ae406f55d3
+  metadata.gz: 836dd745def09ebc585241308d56298b986693c075b4676e12b1d95e57d4847f05b979d41cf203491dedd4e1228561163782c7c14886e4c75a9fe7f577c70820
+  data.tar.gz: 672cb17a7a142cc6f693c8b3c6d3597223e3391f8d9cd3c6c552259a1eb1a377805bdaa26c95adb8e8e56d3b2acde94da66a8c125d0044c02fee3a11fd13174c

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,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.12.0] - 2026-08-01
+
+### Added
+- Fitness predictor — race times from a VO2max value, the inverse of
+  `estimate_vo2max`
+  - `predict_time_from_vo2max(vo2max, race, distance_unit: nil)`: predicted
+    finish time in seconds. `race` accepts a standard race name ('5k',
+    'marathon', '5mile', ...) or a numeric distance in kilometres (miles via
+    `distance_unit: :mi`), same semantics as `training_paces_from_race`
+  - `predict_time_from_vo2max_clock(...)`: same prediction as `HH:MM:SS`
+  - `race_times_from_vo2max(vo2max, races: nil, unit: :km)`: one call returns a
+    table of `time`, `time_clock`, `pace`, and `pace_clock` per race (default
+    races: 5k, 10k, half marathon, marathon; `unit: :mi` for paces per mile)
+  - VO2max inputs outside 10–100 ml/kg/min raise `ArgumentError`, where the
+    Daniels & Gilbert model stops being physiologically meaningful
+
+Predictions come from bisecting the Daniels & Gilbert curve on the time axis
+(it has no closed-form inverse), so
+`estimate_vo2max(d, predict_time_from_vo2max(v, d))` returns `v` back. Times
+match Daniels' published VDOT table within a few seconds for the shorter races
+and about a minute for the marathon.
+
+No existing behaviour changed: the Riegel (`predict_time`) and Cameron
+predictors are untouched.
+
+## [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
@@ -215,7 +294,9 @@ 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.10.0...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.12.0...HEAD
+[1.12.0]: https://github.com/0jonjo/calcpace/compare/v1.11.0...v1.12.0
+[1.11.0]: https://github.com/0jonjo/calcpace/compare/v1.10.0...v1.11.0
 [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

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.10.0&x2=0)](https://badge.fury.io/rb/calcpace)
+# Calcpace [![Gem Version](https://badge.fury.io/rb/calcpace.svg)](https://badge.fury.io/rb/calcpace)
 
 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.10.0'
+gem 'calcpace', '~> 1.12.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"
 ```
@@ -285,10 +287,18 @@ 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_from_race(10.0, '00:40:00')  # from a recent race result
+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 |
@@ -302,6 +312,51 @@ calc.hr_zones(hr_max: 190, hr_rest: 55)
 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.
+
+---
+
+### Fitness Predictor (race times from VO2max)
+
+The inverse of `estimate_vo2max`: what a given fitness is worth over a race.
+
+```ruby
+calc.predict_time_from_vo2max(50, '5k')             # => 1196.02 (seconds)
+calc.predict_time_from_vo2max_clock(50, 'marathon') # => "03:10:39"
+
+calc.predict_time_from_vo2max(50, 10.0)                          # numeric distance in km
+calc.predict_time_from_vo2max_clock(50, 6.2, distance_unit: :mi) # => "00:41:13"
+
+calc.race_times_from_vo2max(50)['10k']
+# => { time: 2479.6, time_clock: "00:41:19", pace: 247.96, pace_clock: "00:04:07" }
+
+calc.race_times_from_vo2max(50, races: %w[5k 10mile], unit: :mi)['5k']
+# => { time: 1196.02, time_clock: "00:19:56", pace: 384.96, pace_clock: "00:06:24" }
+```
+
+`race_times_from_vo2max` returns the whole table in one call — default races are
+`5k`, `10k`, `half_marathon`, and `marathon`, and `unit:` sets the pace unit. In
+`predict_time_from_vo2max`, `distance_unit:` sets the unit of a numeric distance;
+combining it with a race name raises `ArgumentError`, as elsewhere in the gem.
+
+The Daniels & Gilbert curve has no closed-form inverse, so the time is found by
+bisection — which makes the round trip exact:
+
+```ruby
+calc.estimate_vo2max(5.0, calc.predict_time_from_vo2max(50, '5k')) # => 50.0
+```
+
+Predictions match Daniels' published VDOT table within a few seconds for the shorter
+races and about a minute for the marathon. VO2max values outside 10–100 ml/kg/min
+raise `ArgumentError` — beyond that range the model stops describing running.
+
 ---
 
 ### Other Utilities
@@ -320,6 +375,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/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
@@ -102,8 +106,8 @@ module Converter
   #   convert_to_clocktime(3600)    #=> '01:00:00' (1 hour)
   #   convert_to_clocktime(100000)  #=> '1 03:46:40' (1 day, 3 hours, 46 minutes, 40 seconds)
   def convert_to_clocktime(seconds)
-    days = seconds / 86_400
-    format = days.to_i.positive? ? "#{days} %H:%M:%S" : '%H:%M:%S'
+    days = (seconds / 86_400).to_i
+    format = days.positive? ? "#{days} %H:%M:%S" : '%H:%M:%S'
     Time.at(seconds).utc.strftime(format)
   end
 
@@ -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/fitness_predictor.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+# Module for predicting race performances from a VO2max value
+#
+# This is the inverse of Vo2maxEstimator#estimate_vo2max: instead of asking
+# "what fitness does this race result imply?", it asks "what race result does
+# this fitness imply?".
+#
+# The Daniels & Gilbert (1979) model cannot be inverted in closed form — the
+# %VO2max term mixes two exponentials of time with a quadratic in velocity —
+# so the finish time is found by bisection on the time axis. VO2max decreases
+# monotonically with time for a fixed distance, which makes the search exact
+# to within the tolerance and guarantees the round trip:
+#
+#   estimate_vo2max(distance, predict_time_from_vo2max(vo2max, distance)) == vo2max
+#
+# Predicted times reproduce Daniels' published VDOT table within a few seconds
+# for the shorter races and about a minute for the marathon.
+module FitnessPredictor
+  # Range of VO2max values the model is meaningful for. Below it the effort is
+  # slower than a walk, above it faster than any human has run — in both cases
+  # the resulting "prediction" would be arithmetic, not physiology.
+  SUPPORTED_VO2MAX_RANGE = (10.0..100.0)
+
+  # Bisection bounds, as seconds per kilometre: from 1:00/km (well beyond world
+  # record pace) to 20:00/km (slower than walking). They bracket every VO2max
+  # in SUPPORTED_VO2MAX_RANGE at any distance.
+  FASTEST_PACE_SECONDS_PER_KM = 60.0
+  SLOWEST_PACE_SECONDS_PER_KM = 1200.0
+
+  # Search stops when the bracket is tighter than this many seconds or when the
+  # VO2max at the midpoint is this close to the target
+  TIME_TOLERANCE_SECONDS = 0.001
+  VO2MAX_TOLERANCE = 1e-6
+
+  # Races reported by #race_times_from_vo2max when none are given
+  DEFAULT_RACES = %w[5k 10k half_marathon marathon].freeze
+
+  # Predicts the finish time a given VO2max is worth over a given race
+  #
+  # @param vo2max [Numeric] VO2max in ml/kg/min (must be within SUPPORTED_VO2MAX_RANGE)
+  # @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 distance_unit [Symbol, nil] unit of a numeric race distance — :km
+  #   (default) or :mi. Rejected when race is a race name: standard races
+  #   already carry their own distance
+  # @return [Float] predicted finish time in seconds
+  # @raise [Calcpace::NonPositiveInputError] if vo2max or distance are not positive
+  # @raise [ArgumentError] if vo2max is outside the supported range, if a race
+  #   name is not recognized, or if distance_unit is combined with a race name
+  # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
+  #
+  # @note estimate_vo2max can report values below 10 for very slow efforts
+  #   (walking pace); those estimates are outside this predictor's supported
+  #   range on purpose — a race plan built on them would be meaningless
+  #
+  # @example
+  #   calc.predict_time_from_vo2max(50, '5k')       #=> 1196.02 (≈19:56)
+  #   calc.predict_time_from_vo2max(50, 'marathon') #=> 11439.74 (≈3:10:39)
+  #   calc.predict_time_from_vo2max(50, 6.2, distance_unit: :mi)
+  def predict_time_from_vo2max(vo2max, race, distance_unit: nil)
+    target = validated_vo2max(vo2max)
+    distance_km = predicted_race_distance_km(race, distance_unit)
+    check_positive(distance_km, 'Distance')
+
+    solve_time_for_vo2max(target, distance_km)
+  end
+
+  # Predicts the finish time and returns it as a clock time string
+  #
+  # @param (see #predict_time_from_vo2max)
+  # @return [String] predicted finish time in HH:MM:SS format
+  #
+  # @example
+  #   calc.predict_time_from_vo2max_clock(50, 'marathon') #=> '03:10:39'
+  def predict_time_from_vo2max_clock(vo2max, race, distance_unit: nil)
+    convert_to_clocktime(predict_time_from_vo2max(vo2max, race, distance_unit: distance_unit))
+  end
+
+  # Builds a full race-time table for one VO2max — one call per dashboard
+  #
+  # @param vo2max [Numeric] VO2max in ml/kg/min
+  # @param races [Array<String, Symbol>, nil] race names to report
+  #   (default: 5k, 10k, half marathon, marathon)
+  # @param unit [Symbol] unit of the returned paces — :km (default) or :mi
+  # @return [Hash{String => Hash}] race name => { time: seconds,
+  #   time_clock: 'HH:MM:SS', pace: seconds per unit, pace_clock: 'HH:MM:SS' }
+  # @raise [ArgumentError] if a race name is not recognized or vo2max is out of range
+  # @raise [Calcpace::NonPositiveInputError] if vo2max is not positive
+  # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
+  #
+  # @example
+  #   calc.race_times_from_vo2max(50)['10k']
+  #   #=> { time: 2479.6, time_clock: '00:41:19', pace: 247.96, pace_clock: '00:04:07' }
+  #   calc.race_times_from_vo2max(50, races: %w[5k 10mile], unit: :mi)
+  def race_times_from_vo2max(vo2max, races: nil, unit: :km)
+    meters = pace_unit_meters(unit)
+    validated_vo2max(vo2max)
+
+    Array(races || DEFAULT_RACES).to_h do |race|
+      [normalize_race_key(race), race_time_entry(vo2max, race, meters)]
+    end
+  end
+
+  private
+
+  def race_time_entry(vo2max, race, meters)
+    seconds = predict_time_from_vo2max(vo2max, race)
+    pace = (seconds / (race_distance(race) * Converter::Distance::KM_TO_METERS / meters)).round(2)
+
+    {
+      time: seconds,
+      time_clock: convert_to_clocktime(seconds),
+      pace: pace,
+      pace_clock: convert_to_clocktime(pace)
+    }
+  end
+
+  # Same distance semantics as TrainingZones#training_paces_from_race: numeric
+  # strings ('10') stay distances, only race names fall through to the lookup
+  def predicted_race_distance_km(race, distance_unit)
+    numeric = race.is_a?(Numeric) ? race : Float(race, exception: false)
+    return normalize_distance_km(numeric, distance_unit || :km) if numeric
+
+    reject_distance_unit_with_race_name!(distance_unit, race)
+    race_distance(race)
+  end
+
+  def validated_vo2max(vo2max)
+    value = vo2max.to_f
+    check_positive(value, 'VO2max')
+    return value if SUPPORTED_VO2MAX_RANGE.cover?(value)
+
+    raise ArgumentError,
+          "VO2max #{value} is outside the supported range " \
+          "(#{SUPPORTED_VO2MAX_RANGE.min}–#{SUPPORTED_VO2MAX_RANGE.max} ml/kg/min)"
+  end
+
+  # Bisects the time axis for the finish time whose VO2max equals the target
+  def solve_time_for_vo2max(target, distance_km)
+    low = distance_km * FASTEST_PACE_SECONDS_PER_KM
+    high = distance_km * SLOWEST_PACE_SECONDS_PER_KM
+    ensure_vo2max_reachable!(target, distance_km, low, high)
+
+    while high - low > TIME_TOLERANCE_SECONDS
+      mid = (low + high) / 2.0
+      value = raw_vo2max(distance_km, mid)
+      return mid.round(2) if (value - target).abs < VO2MAX_TOLERANCE
+
+      # VO2max falls as time grows: a midpoint fitter than the target means
+      # the answer is a slower time (raise low), otherwise a faster one
+      if value > target
+        low = mid
+      else
+        high = mid
+      end
+    end
+
+    ((low + high) / 2.0).round(2)
+  end
+
+  # Defensive bracket check: the search bounds cover the whole supported range
+  # at every distance, so this only fires if those constants are ever widened
+  def ensure_vo2max_reachable!(target, distance_km, low, high)
+    reachable = raw_vo2max(distance_km, high)..raw_vo2max(distance_km, low)
+    return if reachable.cover?(target)
+
+    raise ArgumentError,
+          "VO2max #{target} is not reachable over #{distance_km} km within the search bounds " \
+          "(#{reachable.begin.round(1)}–#{reachable.end.round(1)} ml/kg/min)"
+  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

@@ -19,11 +19,15 @@ module TrainingZones
     repetition: { low: 1.05, high: 1.10 }
   }.freeze
 
-  # A pace band for one training zone (paces per kilometre).
+  # 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)
 
-  # Heart-rate zone boundaries as fractions of Heart Rate Reserve (Karvonen)
+  # 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)
@@ -32,18 +36,22 @@ module TrainingZones
   # 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 km
+  #   :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"
-  def training_paces(vo2max)
+  #   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])
-      fast = pace_seconds_at_pct(vo2max.to_f, band[:high])
+      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,
@@ -59,16 +67,39 @@ module TrainingZones
   # Convenience wrapper: estimates VO2max via Daniels & Gilbert
   # (see Vo2maxEstimator#estimate_vo2max) and derives the bands from it.
   #
-  # @param distance_km [Numeric] race distance in kilometres (must be > 0)
+  # @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"
-  def training_paces_from_race(distance_km, time)
-    training_paces(estimate_vo2max(distance_km, time))
+  #   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
@@ -89,15 +120,39 @@ module TrainingZones
     check_heart_rates(max, rest)
 
     reserve = max - rest
-    points  = HR_ZONE_BOUNDARIES.map { |pct| (rest + (pct * reserve)).round }
+    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
 
-  private
-
   def check_heart_rates(hr_max, hr_rest)
     check_positive(hr_max, 'Maximum heart rate')
     check_positive(hr_rest, 'Resting heart rate')
@@ -116,8 +171,14 @@ module TrainingZones
     (-b + Math.sqrt((b**2) - (4 * a * c))) / (2 * a)
   end
 
-  def pace_seconds_at_pct(vo2max, pct)
+  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)
-    (60_000.0 / velocity).round
+    (meters * 60.0 / velocity).round
   end
 end

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.10.0'
+  VERSION = '1.12.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))
@@ -140,6 +154,17 @@ module Vo2maxEstimator
     -4.60 + (0.182258 * velocity) + (0.000104 * (velocity**2))
   end
 
+  # Unrounded Daniels & Gilbert VO2max for a distance/time pair. Lives next to
+  # the formula it composes so the two cannot drift apart: FitnessPredictor
+  # bisects against this to guarantee an exact round trip with the public
+  # estimator, which only differs by rounding to one decimal.
+  def raw_vo2max(distance_km, seconds)
+    time_min = seconds / 60.0
+    velocity = distance_km * Converter::Distance::KM_TO_METERS / time_min
+
+    vo2_at_velocity(velocity) / percent_vo2max(time_min)
+  end
+
   def percent_vo2max(time_min)
     0.8 +
       (0.1894393 * Math.exp(-0.012778 * time_min)) +

data/lib/calcpace.rb

@@ -8,6 +8,7 @@ require_relative 'calcpace/checker'
 require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
 require_relative 'calcpace/errors'
+require_relative 'calcpace/fitness_predictor'
 require_relative 'calcpace/pace_calculator'
 require_relative 'calcpace/pace_converter'
 require_relative 'calcpace/race_predictor'
@@ -45,6 +46,7 @@ class Calcpace
   include Checker
   include Converter
   include ConverterChain
+  include FitnessPredictor
   include PaceCalculator
   include PaceConverter
   include RacePredictor

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.12.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -44,6 +44,7 @@ files:
 - lib/calcpace/data/wma_2023_road.yml
 - lib/calcpace/environmental_adjuster.rb
 - lib/calcpace/errors.rb
+- lib/calcpace/fitness_predictor.rb
 - lib/calcpace/pace_calculator.rb
 - lib/calcpace/pace_converter.rb
 - lib/calcpace/race_predictor.rb
@@ -73,7 +74,7 @@ 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: 'Running calculations: pace, race predictions, GPS track analysis, VO2max,
   and training zones.'