calcpace 1.15.0 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eefef398417bfe2d045b2afd7ee78991b443c7c9bc1eabd536e81d03789908c
-  data.tar.gz: 7b676576e7e3af9b9d4ce75430af80835a35535b2c8b971ed5ef764ddd608853
+  metadata.gz: 5fd21092789d45d81f1cc1def219122a63cd74ead051cc59ee30b178198702f1
+  data.tar.gz: e67ee4c7a71c194ce57928993ee2e898947465d2647e8ffa5b85277386e652b2
 SHA512:
-  metadata.gz: 2b7481ff8c0c4b91f724af723eacfd9357905fa2207adc0871dd745d7fc4a4beac52349f0051703a91288c724dd2b6c00298beb585d08949b156833e9fc70af7
-  data.tar.gz: 7d58f1c452924bbc9c7a895a5ed5102e1ae298b002984d9708aea23b4f54f7339fa2b4dd6708b678cf5f1dd45d5cfd8cc8dd5c3e869df6b07856f08eaf6c720c
+  metadata.gz: ee62a321a8a53d93f36698579ab5bb3a5e87c3ad744191219477492a63daafc100b07fe01421bba40835b8bfef84554698db605ca9279e7619473301b0e366cb
+  data.tar.gz: ed4c5799eeb409dbb595e594417cc9efbcb9a6316bdb93dc6f9288c3deae7291aef63ff78415ca172f8ea86789d894fa7c057ecd4887902a9e5e3b0b962e2add

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-09-05
+
+### Added
+- `stride_length(pace, cadence, unit: :km)` — metres per step from a pace (clock
+  string or seconds per unit) and a cadence in steps per minute counting **both
+  feet**; Strava's API reports cadence as one-leg RPM, so callers reading it from
+  there must double it first.
+- `cadence_for_stride(pace, stride, unit: :km)` — the inverse: the both-feet
+  cadence in steps per minute that a given stride length implies at a given pace.
+
 ## [1.15.0] - 2026-08-30
 
 ### Added
@@ -505,7 +515,8 @@ predictors are untouched.
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.15.0...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.16.0...HEAD
+[1.16.0]: https://github.com/0jonjo/calcpace/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/0jonjo/calcpace/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/0jonjo/calcpace/compare/v1.13.0...v1.14.0
 [1.13.0]: https://github.com/0jonjo/calcpace/compare/v1.12.1...v1.13.0

data/README.md

@@ -417,6 +417,32 @@ pace bands, and age-grading tolerances agree to the metre.
 
 ---
 
+### Stride & Cadence
+
+Pace, cadence and stride length are one identity, so any two of them give the third:
+
+```ruby
+calc.stride_length('05:00', 170)             # => 1.18
+calc.stride_length('04:00', 180)             # => 1.39
+calc.stride_length('08:02', 170, unit: :mi)  # => 1.18
+
+calc.cadence_for_stride('05:00', 1.18)       # => 169.5
+calc.cadence_for_stride('05:30', 1.15)       # => 158.1
+```
+
+`stride_length` returns metres per step (2 decimals); `cadence_for_stride` is its
+inverse and returns steps per minute (1 decimal). Pace takes the same forms as
+everywhere else — a clock string (`'05:00'`, `'00:05:00'`) or seconds per unit
+(`300`) — and `unit:` says which unit that pace is per: `:km` (default) or `:mi`.
+`8:02/mi` is `5:00/km` rounded down to the second (exactly 8:02.8), so the two strides
+agree to the centimetre at this cadence.
+
+Cadence is steps per minute counting **both feet** — the number a watch shows during a
+run, typically 160–185 spm. Strava's API reports cadence as one-leg RPM, so a value
+read from there must be doubled before it is passed in.
+
+---
+
 ### Fitness Predictor (race times from VO2max)
 
 The inverse of `estimate_vo2max`: what a given fitness is worth over a race.

data/lib/calcpace/stride_calculator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Module relating pace, cadence and stride length
+#
+# The three quantities are one identity, not three measurements:
+#   speed (m/min) = unit_metres / pace_seconds * 60
+#   stride (m)    = speed / cadence
+# so any two of them give the third. Cadence here is steps per minute counting
+# BOTH feet (spm) — the number a watch shows during a run. Strava's API reports
+# cadence as one-leg RPM, so a caller reading it from there must double it
+# before passing it in.
+module StrideCalculator
+  # Calculates stride length from pace and cadence
+  #
+  # @param pace [Numeric, String] pace in seconds per unit or time string (MM:SS or HH:MM:SS)
+  # @param cadence [Numeric] cadence in steps per minute, both feet (must be > 0)
+  # @param unit [Symbol, String] unit the pace is expressed in — :km (default) or :mi
+  # @return [Float] stride length in metres per step, rounded to 2 decimals
+  # @raise [Calcpace::InvalidTimeFormatError] if pace is a string that is not a valid clock
+  # @raise [Calcpace::NonPositiveInputError] if pace or cadence is not positive
+  # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
+  #
+  # @example
+  #   # 300 s/km → 200 m/min; 200/170
+  #   calc.stride_length('05:00', 170)             #=> 1.18
+  #   # numeric seconds per km
+  #   calc.stride_length(300, 170)                 #=> 1.18
+  #   # 8:02/mi is 5:00/km rounded down to the second
+  #   calc.stride_length('08:02', 170, unit: :mi)  #=> 1.18
+  def stride_length(pace, cadence, unit: :km)
+    speed = speed_meters_per_minute(pace, unit)
+    check_positive(cadence, 'Cadence')
+
+    (speed / cadence).round(2)
+  end
+
+  # Calculates the cadence a given stride length implies at a given pace
+  #
+  # The inverse of #stride_length: it answers what turnover a runner needs to
+  # hold a pace with the stride they actually have.
+  #
+  # @param pace [Numeric, String] pace in seconds per unit or time string (MM:SS or HH:MM:SS)
+  # @param stride [Numeric] stride length in metres per step (must be > 0)
+  # @param unit [Symbol, String] unit the pace is expressed in — :km (default) or :mi
+  # @return [Float] cadence in steps per minute, both feet, rounded to 1 decimal
+  # @raise [Calcpace::InvalidTimeFormatError] if pace is a string that is not a valid clock
+  # @raise [Calcpace::NonPositiveInputError] if pace or stride is not positive
+  # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
+  #
+  # @example
+  #   # 200 m/min / 1.18 m
+  #   calc.cadence_for_stride('05:00', 1.18)  #=> 169.5
+  #   calc.cadence_for_stride('05:30', 1.15)  #=> 158.1
+  def cadence_for_stride(pace, stride, unit: :km)
+    speed = speed_meters_per_minute(pace, unit)
+    check_positive(stride, 'Stride')
+
+    (speed / stride).round(1)
+  end
+
+  private
+
+  # Turns a pace (clock string or seconds per unit) into a running speed
+  #
+  # A String pace is checked as a clock before it is parsed, the way
+  # Calculator#validate_time, Vo2maxEstimator and AgeGrading check theirs — so
+  # '05:xx' is a format error, not a silently truncated pace. The unit is
+  # resolved first, so a bad unit wins over a bad pace, as it does in
+  # FitnessPredictor#race_times_from_vo2max.
+  #
+  # @param pace [Numeric, String] pace in seconds per unit or time string
+  # @param unit [Symbol, String] :km or :mi
+  # @return [Float] speed in metres per minute
+  def speed_meters_per_minute(pace, unit)
+    meters = pace_unit_meters(unit)
+    pace_seconds = pace_seconds_from(pace)
+    check_positive(pace_seconds, 'Pace')
+
+    meters / pace_seconds * 60.0
+  end
+
+  # @param pace [Numeric, String] pace in seconds per unit or time string
+  # @return [Numeric] the pace in seconds
+  # @raise [Calcpace::InvalidTimeFormatError] if a string pace is not a valid clock
+  def pace_seconds_from(pace)
+    return pace unless pace.is_a?(String)
+
+    check_time(pace)
+    convert_to_seconds(pace)
+  end
+end

data/lib/calcpace/version.rb

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

data/lib/calcpace.rb

@@ -13,6 +13,7 @@ require_relative 'calcpace/pace_calculator'
 require_relative 'calcpace/pace_converter'
 require_relative 'calcpace/race_predictor'
 require_relative 'calcpace/race_splits'
+require_relative 'calcpace/stride_calculator'
 require_relative 'calcpace/track_calculator'
 require_relative 'calcpace/training_zones'
 require_relative 'calcpace/vo2max_estimator'
@@ -51,6 +52,7 @@ class Calcpace
   include PaceConverter
   include RacePredictor
   include RaceSplits
+  include StrideCalculator
   include TrackCalculator
   include TrainingZones
   include Vo2maxEstimator

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.15.0
+  version: 1.16.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -49,6 +49,7 @@ files:
 - lib/calcpace/pace_converter.rb
 - lib/calcpace/race_predictor.rb
 - lib/calcpace/race_splits.rb
+- lib/calcpace/stride_calculator.rb
 - lib/calcpace/track_calculator.rb
 - lib/calcpace/training_zones.rb
 - lib/calcpace/version.rb