driving_physics 0.0.0.2

data/lib/driving_physics/tire.rb

@@ -0,0 +1,288 @@
+# NOTE: This entire file will likely be replaced or removed.
+#       It was created early on, before taking a true physics / formulaic
+#       approach.  Just treat it as a toy / PoC for now.  It does not
+#       currently behave as desired.
+#
+
+require 'driving_physics'
+
+# treat instances of this class as immutable
+# Tire::Condition has mutable attributes
+#
+module DrivingPhysics
+  class Tire
+    class Error < RuntimeError; end
+
+    attr_accessor :roll_cof,
+                  :tread_mm,
+                  :cords_mm,
+                  :radius_mm,
+                  :g_factor,
+                  :max_heat_cycles,
+                  :temp_profile,
+                  :condition
+
+    def initialize
+      @roll_cof = ROLL_COF
+      @tread_mm = 10
+      @cords_mm = 1
+      @radius_mm = 350
+      @g_factor = 1.0
+      @max_heat_cycles = 50
+      @temp_profile = TemperatureProfile.new
+
+      yield self if block_given?
+      @condition = Condition.new(tread_mm: @tread_mm, cords_mm: @cords_mm)
+    end
+
+    def to_s
+      [[format("Grip: %.2f / %.1f G", max_g, @g_factor),
+        format("Radius: %d mm", @radius_mm),
+        format("cRR: %.3f", @roll_cof),
+       ].join(' | '),
+       @condition,
+      ].join("\n")
+    end
+
+    def tread_left?
+      @condition.tread_mm > 0.0
+    end
+
+    # cords give half the traction as tread
+    def tread_factor
+      tread_left? ? 1.0 : 0.5 * @condition.cords_mm / @cords_mm
+    end
+
+    # up to max_heat_cycles, the grip decays down to 80%
+    # beyond max_heat_cycles, the grip decay plateaus at 80%
+    def heat_cycle_factor
+      heat_cycles = [@condition.heat_cycles, @max_heat_cycles].min.to_f
+      heat_pct = heat_cycles / @max_heat_cycles
+      1.0 - 0.2 * heat_pct
+    end
+
+    def temp_factor
+      @temp_profile.grip_factor(@condition.temp_c)
+    end
+
+    def max_g
+      @g_factor * temp_factor * heat_cycle_factor * tread_factor
+    end
+
+    # treat instances of this class as immutable
+    class TemperatureProfile
+      class Error < DrivingPhysics::Tire::Error; end
+
+      TEMPS = [-100, 0, 25, 50, 75, 80, 85, 95, 100, 105, 110, 120, 130, 150]
+      GRIPS = [0.1, 0.5, 0.75, 0.8, 0.9, 0.95, 1.0,
+               0.95, 0.9, 0.75, 0.5, 0.25, 0.1, 0.05]
+      MIN_GRIP = 0.01
+
+      attr_reader :critical_temp
+
+      def initialize(deg_ary = TEMPS, grip_ary = GRIPS)
+        if !deg_ary.is_a?(Array) or !grip_ary.is_a?(Array)
+          raise(ArgumentError, "two arrays are required")
+        end
+        if deg_ary.count != grip_ary.count
+          raise(ArgumentError, "arrays don't match")
+        end
+        @deg_c = deg_ary
+        @grip_pct = grip_ary
+        @critical_temp = nil
+        determine_critical_temp!
+      end
+
+      def grip_factor(temp_c)
+        pct = MIN_GRIP
+        @deg_c.each_with_index { |deg, i|
+          pct = @grip_pct[i] if temp_c >= deg
+          break if temp_c < deg
+        }
+        pct
+      end
+
+      def to_s
+        lines = []
+        @deg_c.each_with_index { |deg, i|
+          lines << [deg, @grip_pct[i]].join("\t")
+        }
+        lines.join("\n")
+      end
+
+      private
+      def determine_critical_temp!
+        return @critical_temp if @critical_temp
+        reached_100 = false
+        # go up to 100% grip, then back down to less than 80%
+        @deg_c.each_with_index { |deg, i|
+          next if !reached_100 and @grip_pct[i] < 1.0
+          reached_100 = true if @grip_pct[i] == 1.0
+          if reached_100 and @grip_pct[i] <= 0.8
+            @critical_temp = deg
+            break
+          end
+        }
+        raise(Error, "bad profile, can't find 100% grip") unless reached_100
+        raise(Error, "bad profile, no critical temp") unless @critical_temp
+      end
+    end
+
+    # treat attributes of this class as *mutable*
+    class Condition
+      class Error < DrivingPhysics::Tire::Error; end
+      class Destroyed < Error; end
+
+      attr_accessor :tread_mm,
+                    :cords_mm,
+                    :temp_c,
+                    :heat_cycles,
+                    :debug_temp,
+                    :debug_wear
+
+      def initialize(temp_c: AIR_TEMP, tread_mm:, cords_mm:)
+        @tread_mm = tread_mm.to_f
+        @cords_mm = cords_mm.to_f
+        @temp_c = temp_c.to_f
+        @heat_cycles = 0
+        @hottest_temp = @temp_c
+        @debug_temp = false
+        @debug_wear = false
+      end
+
+      def to_s
+        [format("Temp: %.1f C", @temp_c),
+         format("Tread: %.2f (%.1f) mm", @tread_mm, @cords_mm),
+         format("Cycles: %d", @heat_cycles),
+        ].join(' | ')
+      end
+
+      def temp_tick(ambient_temp:, g:, slide_speed:,
+                    mass:, tire_mass:, critical_temp:)
+        # env:
+        # * mass (kg) (e.g. 1000 kg)
+        # * tire_mass (kg) (e.g. 10 kg)
+        # * critical temp (c) (e.g. 100c)
+        # * g (e.g. 1.0 g)
+        # * slide_speed (m/s) (typically 0.1, up to 1 or 10 or 50)
+        # * ambient_temp (c) (e.g. 30c)
+
+        # g gives a target temp between 25 and 100
+        # at 0g, tire tends to ambient temp
+        # at 1g, tire tends to 100 c
+        # that 100c upper target also gets adjusted due to ambient temps
+
+        target_hot = critical_temp + 5
+        ambient_diff = AIR_TEMP - ambient_temp
+        target_hot -= (ambient_diff / 2)
+        puts "target_hot=#{target_hot}" if @debug_temp
+
+        if slide_speed <= 0.1
+          target_g_temp = ambient_temp + (target_hot - ambient_temp) * g
+        else
+          target_g_temp = target_hot
+        end
+        puts "target_g_temp=#{target_g_temp}" if @debug_temp
+
+        slide_factor = slide_speed * 5
+        target_slide_temp = target_g_temp + slide_factor
+
+        puts "target_slide_temp=#{target_slide_temp}" if @debug_temp
+
+        # temp_tick is presumed to be +1.0 or -1.0 (100th of a degree)
+        # more mass biases towards heat
+        # more tire mass biases for smaller tick
+
+        tick = @temp_c < target_slide_temp ? 1.0 : -1.0
+        tick += slide_speed / 10
+        puts "base tick: #{tick}" if @debug_temp
+
+        mass_factor = (mass - 1000).to_f / 1000
+        if mass_factor < 0
+          # lighter car cools quicker; heats slower
+          tick += mass_factor
+        else
+          # heavier car cools slower, heats quicker
+          tick += mass_factor / 10
+        end
+        puts "mass tick: #{tick}" if @debug_temp
+
+        tire_mass_factor = (tire_mass - 10).to_f / 10
+        if tire_mass_factor < 0
+          # lighter tire has bigger tick
+          tick -= tire_mass_factor
+        else
+          # heavier tire has smaller tick
+          tire_mass_factor = (tire_mass - 10).to_f / 100
+          tick -= tire_mass_factor
+        end
+        puts "tire mass tick: #{tick}" if @debug_temp
+        puts if @debug_temp
+
+        tick
+      end
+
+      def wear_tick(g:, slide_speed:, mass:, critical_temp:)
+        # cold tires wear less
+        tick = [0, @temp_c.to_f / critical_temp].max
+        puts "wear tick: #{tick}" if @debug_wear
+
+        # lower gs reduce wear in the absence of sliding
+        tick *= g if slide_speed <= 0.1
+        puts "g wear tick: #{tick}" if @debug_wear
+
+        # slide wear
+        tick += slide_speed
+        puts "slide wear tick: #{tick}" if @debug_wear
+        puts if @debug_wear
+        tick
+      end
+
+
+      def tick!(ambient_temp:, g:, slide_speed:,
+                mass:, tire_mass:, critical_temp:)
+
+        # heat cycle:
+        # when the tire goes above the critical temp and then
+        # cools significantly below the critical temp
+        # track @hottest_temp
+
+        @temp_c += temp_tick(ambient_temp: ambient_temp,
+                             g: g,
+                             slide_speed: slide_speed,
+                             mass: mass,
+                             tire_mass: tire_mass,
+                             critical_temp: critical_temp) / 100
+        @hottest_temp = @temp_c if @temp_c > @hottest_temp
+        if @hottest_temp > critical_temp and @temp_c < critical_temp * 0.8
+          @heat_cycles += 1
+          @hottest_temp = @temp_c
+        end
+
+        # a tire should last for 30 minutes at 1g sustained
+        # with minimal sliding
+        # 100 ticks / sec
+        # 6000 ticks / min
+        # 180_000 ticks / 30 min
+        # 10mm = 180_000 ticks
+        # wear_tick is nominally 1 / 18_000 mm
+
+        wt = wear_tick(g: g,
+                       slide_speed: slide_speed,
+                       mass: mass,
+                       critical_temp: critical_temp)
+
+        if @tread_mm > 0
+          @tread_mm -= wt / 18000
+          @tread_mm = 0 if @tread_mm < 0
+        else
+          # cords wear 2x faster
+          @cords_mm -= wt * 2 / 18000
+          if @cords_mm <= 0
+            raise(Destroyed, "no more cords")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/driving_physics/vector_force.rb

@@ -0,0 +1,136 @@
+require 'matrix' # stdlib, provides Vector class
+require 'driving_physics'
+
+module DrivingPhysics
+  # compatibility for Vector#zero? in Ruby 2.4.x
+  unless Vector.method_defined?(:zero?)
+    module VectorZeroBackport
+      refine Vector do
+        def zero?
+          all?(&:zero?)
+        end
+      end
+    end
+    using VectorZeroBackport
+  end
+
+  # e.g. given 5, yields a uniformly random number from -5 to +5
+  def self.random_centered_zero(magnitude)
+    m = [magnitude.abs, 1].max
+    Random.rand(m * 2 + 1) - m
+  end
+
+  def self.random_unit_vector(dimensions = 2, resolution: 9)
+    begin
+      v = Vector.elements(Array.new(dimensions) {
+                            random_centered_zero(resolution)
+                          })
+    end while v.zero?
+    v.normalize
+  end
+
+  def self.rot_90(vec, clockwise: true)
+    raise(Vector::ZeroVectorError) if vec.zero?
+    raise(ArgumentError, "vec should be size 2") unless vec.size == 2
+    clockwise ? Vector[vec[1], -1 * vec[0]] : Vector[-1 * vec[1], vec[0]]
+  end
+
+  # +,0 E
+  # 0,+ N
+  # .9,.1 ENE
+  # .1,.9 NNE
+  #
+  def self.compass_dir(unit_vector)
+    horz = case
+           when unit_vector[0] < -0.001 then 'W'
+           when unit_vector[0] > 0.001 then 'E'
+           else ''
+           end
+
+    vert = case
+           when unit_vector[1] < -0.001 then 'S'
+           when unit_vector[1] > 0.001 then 'N'
+           else ''
+           end
+
+    dir = [vert, horz].join
+    if dir.length == 2
+      # detect and include bias
+      if (unit_vector[0].abs - unit_vector[1].abs).abs > 0.2
+        bias = unit_vector[0].abs > unit_vector[1].abs ? horz : vert
+        dir = [bias, dir].join
+      end
+    end
+    dir
+  end
+
+  module VectorForce
+    #
+    # Resistance Forces
+    #
+    # 1. air resistance aka drag aka turbulent drag
+    #    depends on v^2
+    # 2. "rotatational" resistance, e.g. bearings / axles / lubricating fluids
+    #    aka viscous drag; linear with v
+    # 3. rolling resistance, e.g. tire and surface deformation
+    #    constant with v, depends on normal force and tire/surface properties
+    # 4. braking resistance, supplied by operator, constant with v
+    #    depends purely on operator choice and physical limits
+    #    as such, it is not modeled here
+    #
+
+    # velocity is a vector; return value is a force vector
+    def self.air_resistance(velocity,
+                            frontal_area: FRONTAL_AREA,
+                            drag_cof: DRAG_COF,
+                            air_density: AIR_DENSITY)
+      -1 * 0.5 * frontal_area * drag_cof * air_density *
+       velocity * velocity.magnitude
+    end
+
+    def self.rotational_resistance(velocity, rot_cof: ROT_COF)
+      -1 * velocity * rot_cof
+    end
+
+    # dir is drive_force vector or velocity vector; will be normalized
+    # normal_force is a magnitude, not a vector
+    #
+    def self.rolling_resistance(nf_mag, dir:, roll_cof: ROLL_COF)
+      return dir if dir.zero? # don't try to normalize a zero vector
+      nf_mag = nf_mag.magnitude if nf_mag.is_a? Vector
+      -1 * dir.normalize * roll_cof * nf_mag
+    end
+
+    #
+    # convenience methods
+    #
+
+    def self.velocity_resistance(velocity,
+                                 frontal_area: FRONTAL_AREA,
+                                 drag_cof: DRAG_COF,
+                                 air_density: AIR_DENSITY,
+                                 rot_cof: ROT_COF)
+      air_resistance(velocity,
+                     frontal_area: frontal_area,
+                     drag_cof: drag_cof,
+                     air_density: air_density) +
+        rotational_resistance(velocity, rot_cof: rot_cof)
+    end
+
+    def self.all_resistance(velocity,
+                            frontal_area: FRONTAL_AREA,
+                            drag_cof: DRAG_COF,
+                            air_density: AIR_DENSITY,
+                            rot_cof: ROT_COF,
+                            dir:,
+                            nf_mag:,
+                            roll_cof: ROLL_COF)
+      velocity_resistance(velocity,
+                          frontal_area: frontal_area,
+                          drag_cof: drag_cof,
+                          air_density: air_density,
+                          rot_cof: rot_cof) +
+        rolling_resistance(nf_mag, dir: dir, roll_cof: roll_cof)
+    end
+  end
+end

data/lib/driving_physics/wheel.rb

@@ -0,0 +1,191 @@
+require 'driving_physics/environment'
+require 'driving_physics/vector_force'
+
+module DrivingPhysics
+  # Rotational complements to acc/vel/pos
+  # alpha - angular acceleration
+  # omega - angular velocity (radians / s)
+  # theta - radians
+
+  class Wheel
+    # Note, this is not the density of solid rubber.  This density
+    # yields a sensible mass for a wheel / tire combo at common radius
+    # and width, assuming a uniform density
+    # e.g. 25kg at 350mm R x 200mm W
+    #
+    DENSITY = 0.325  # kg / L
+
+    # * the traction force opposes the axle torque / drive force
+    #   thus, driving the car forward
+    # * if the drive force exceeds the traction force, slippage occurs
+    # * slippage reduces the available traction force further
+    # * if the drive force is not reduced, the slippage increases
+    #   until resistance forces equal the drive force
+    def self.traction(normal_force, cof)
+      normal_force * cof
+    end
+
+    def self.force(axle_torque, radius_m)
+      axle_torque / radius_m.to_f
+    end
+
+    # in m^3
+    def self.volume(radius_m, width_m)
+      Math::PI * radius_m ** 2 * width_m.to_f
+    end
+
+    # in L
+    def self.volume_l(radius_m, width_m)
+      volume(radius_m, width_m) * 1000
+    end
+
+    def self.density(mass, volume_l)
+      mass.to_f / volume_l
+    end
+
+    def self.mass(radius_m, width_m, density)
+      density * volume_l(radius_m, width_m)
+    end
+
+    # I = 1/2 (m)(r^2) for a disk
+    def self.rotational_inertia(radius_m, mass)
+      mass * radius_m**2 / 2.0
+    end
+    class << self
+      alias_method(:moment_of_inertia, :rotational_inertia)
+    end
+
+    # angular acceleration
+    def self.alpha(torque, inertia)
+      torque / inertia
+    end
+
+    def self.tangential(rotational, radius_m)
+      rotational * radius_m
+    end
+    class << self
+      alias_method(:tangential_a, :tangential)
+      alias_method(:tangential_v, :tangential)
+      alias_method(:tangential_p, :tangential)
+    end
+
+    # vectors only
+    def self.torque_vector(force, radius)
+      if !force.is_a?(Vector) or force.size != 2
+        raise(ArgumentError, "force must be a 2D vector")
+      end
+      if !radius.is_a?(Vector) or radius.size != 2
+        raise(ArgumentError, "radius must be a 2D vector")
+      end
+      force = Vector[force[0], force[1], 0]
+      radius = Vector[radius[0], radius[1], 0]
+      force.cross(radius)
+    end
+
+    # vectors only
+    def self.force_vector(torque, radius)
+      if !torque.is_a?(Vector) or torque.size != 3
+        raise(ArgumentError, "torque must be a 3D vector")
+      end
+      if !radius.is_a?(Vector) or radius.size != 2
+        raise(ArgumentError, "radius must be a 2D vector")
+      end
+      radius = Vector[radius[0], radius[1], 0]
+      radius.cross(torque) / radius.dot(radius)
+    end
+
+    attr_reader :env, :radius, :radius_m, :width, :width_m, :density, :temp,
+                :mu_s, :mu_k, :omega_friction
+
+    def initialize(env,
+                   radius: 350, width: 200, density: DENSITY,
+                   temp: nil, mass: nil,
+                   mu_s: 1.1, mu_k: 0.7,
+                   omega_friction: 0.002)
+      @env = env
+      @radius = radius.to_f # mm
+      @radius_m = @radius / 1000
+      @width  = width.to_f  # mm
+      @width_m = @width / 1000
+      @mu_s = mu_s.to_f # static friction
+      @mu_k = mu_k.to_f # kinetic friction
+      @omega_friction = omega_friction # scales with speed
+      @density = mass.nil? ? density : self.class.density(mass, volume_l)
+      @temp = temp.to_f || @env.air_temp
+    end
+
+    def to_s
+      [[format("%d mm (R) x %d mm (W)", @radius, @width),
+        format("Mass: %.1f kg %.3f kg/L", self.mass, @density),
+        format("cF: %.1f / %.1f", @mu_s, @mu_k),
+       ].join(" | "),
+       [format("Temp: %.1f C", @temp),
+       ].join(" | "),
+      ].join("\n")
+    end
+
+    def wear!(amount_mm)
+      @radius -= amount_mm
+      @radius_m = @radius / 1000
+    end
+
+    def heat!(amount_deg_c)
+      @temp += amount_deg_c
+    end
+
+    def mass
+      self.class.mass(@radius_m, @width_m, @density)
+    end
+
+    # in m^3
+    def volume
+      self.class.volume(@radius_m, @width_m)
+    end
+
+    # in L
+    def volume_l
+      self.class.volume_l(@radius_m, @width_m)
+    end
+
+    def rotational_inertia
+      self.class.rotational_inertia(@radius_m, self.mass)
+    end
+    alias_method(:moment_of_inertia, :rotational_inertia)
+
+    def traction(nf, static: true)
+      self.class.traction(nf, static ? @mu_s : @mu_k)
+    end
+
+    def force(axle_torque)
+      self.class.force(axle_torque, @radius_m)
+    end
+
+    # how much torque to accelerate rotational inertia at alpha
+    def inertial_torque(alpha)
+      alpha * self.rotational_inertia
+    end
+
+    # this doesn't take inertial losses or internal frictional losses
+    # into account.  input torque required to saturate traction will be
+    # higher than what this method returns
+    def tractable_torque(nf, static: true)
+      traction(nf, static: static) * @radius_m
+    end
+
+    # inertial loss in terms of axle torque when used as a drive wheel
+    def inertial_loss(axle_torque, total_driven_mass)
+      drive_force = self.force(axle_torque)
+      force_loss = 0
+      # The force loss depends on the acceleration, but the acceleration
+      # depends on the force loss.  Converge the value via 5 round trips.
+      # This is a rough way to compute an integral and should be accurate
+      # to 8+ digits.
+      5.times {
+        acc = DrivingPhysics.acc(drive_force - force_loss, total_driven_mass)
+        alpha = acc / @radius_m
+        force_loss = self.inertial_torque(alpha) / @radius_m
+      }
+      force_loss * @radius_m
+    end
+  end
+end

data/lib/driving_physics.rb

@@ -0,0 +1,71 @@
+module DrivingPhysics
+  #
+  # Units: metric
+  #
+  # distance: meter
+  # velocity: meter / sec
+  # acceleration: meter / sec^2
+  # volume: Liter
+  # temperature: Celsius
+  #
+
+  #
+  # environmental defaults
+  #
+  HZ = 1000
+  TICK = Rational(1) / HZ
+  G = 9.8               # m/s^2
+  AIR_TEMP = 25         # deg c
+  AIR_DENSITY = 1.29    # kg / m^3
+  PETROL_DENSITY = 0.71 # kg / L   TODO: move to car.rb
+
+  #
+  # defaults for resistance forces
+  #
+  FRONTAL_AREA = 2.2  # m^2, based roughly on 2000s-era Chevrolet Corvette
+  DRAG_COF = 0.3      # based roughly on 2000s-era Chevrolet Corvette
+  DRAG = 0.4257       # air_resistance at 1 m/s given above numbers
+  ROT_COF = 12.771    # if rotating resistance matches air resistance at 30 m/s
+  ROLL_COF = 0.01     # roughly: street tires on concrete
+
+  #
+  # constants
+  #
+  SECS_PER_MIN = 60
+  MINS_PER_HOUR = 60
+  SECS_PER_HOUR = SECS_PER_MIN * MINS_PER_HOUR
+
+  def self.elapsed_display(elapsed_ms)
+    elapsed_s, ms = elapsed_ms.divmod 1000
+
+    h = elapsed_s / SECS_PER_HOUR
+    elapsed_s -= h * SECS_PER_HOUR
+    m, s = elapsed_s.divmod SECS_PER_MIN
+
+    [[h, m, s].map { |i| i.to_s.rjust(2, '0') }.join(':'),
+     ms.to_s.rjust(3, '0')].join('.')
+  end
+
+  def self.kph(meters_per_sec)
+    meters_per_sec.to_f * SECS_PER_HOUR / 1000
+  end
+
+  # acceleration; F=ma
+  # force can be a scalar or a Vector
+  def self.acc(force, mass)
+    force / mass.to_f
+  end
+
+  # init and rate can be scalar or Vector but must match
+  # this provides the general form for determining velocity and position
+  def self.accum(init, rate, dt: TICK)
+    init + rate * dt
+  end
+
+  class << self
+    alias_method(:vel, :accum)
+    alias_method(:pos, :accum)
+    alias_method(:omega, :accum)
+    alias_method(:theta, :accum)
+  end
+end