device_control 0.0.0.3 → 0.3.0.1

data/lib/pid_controller.rb

@@ -1,267 +0,0 @@
-# There is a pattern for how both Controllers (e.g. thermostat) and Devices
-#   (e.g. heater) operate.
-# They each have an _input_ varying over time which determines the _output_.
-# A thermostat (Controller) listens for  temperature and tells the heater how
-# high to turn it up (or just on / off).  A heater (Device) listens to its
-# control knob and yields heat as an output.
-#
-# We capture this pattern with a single method: _update_.  It accepts the
-# latest input and provides an _output_ based on the input. When the input
-# is read in, perhaps some internal state is changed on
-# the processor which will affect the _output_.
-#
-# Any class which mixes in Updateable can define its own _input=_ method,
-# which may update any ivars.  Any such class must define an _output_ method.
-#
-module Updateable
-  def update(val)
-    self.input = val
-    self.output
-  end
-end
-
-# A Device is like a heater.  It has a control knob, maybe on/off or perhaps
-# a variable control.  Its output (maybe on/off) depends on the control knob.
-class Device
-  include Updateable
-
-  attr_reader :knob
-
-  def initialize
-    @knob = 0.0
-  end
-
-  def input=(val)
-    @knob = val.to_f
-  end
-  alias_method :knob=, :input=
-
-  def output
-    @knob # do nothing by default
-  end
-
-  def to_s
-    format("Knob: %.3f\tOutput: %.3f", @knob, self.output)
-  end
-end
-
-# Alright, fine, let's make a Heater
-# Input is the control knob (turned far enough to on, else off)
-# Output is watts
-class Heater < Device
-  # convert electricity into thermal output
-  EFFICIENCY = 0.999
-
-  attr_reader :watts
-
-  def initialize(watts, threshold: 0)
-    super()
-    @watts = watts
-    @threshold = threshold
-  end
-
-  # output is all or none
-  def output
-    @knob > @threshold ? (@watts * self.class::EFFICIENCY) : 0
-  end
-
-  def to_s
-    format("Power: %d W\tKnob: %.1f\tThermal: %.1f W",
-           @watts, @knob, self.output)
-  end
-end
-
-class Cooler < Heater
-  # not nearly as efficient as a heater at turning electrons into therms
-  EFFICIENCY = 0.35
-end
-
-# A Controller is like a thermostat.  It has a setpoint, and it reads a
-# measurement from the environment, and it adjusts its output to try to make
-# the measurement match the setpoint.
-class Controller
-  include Updateable
-
-  attr_reader :measure
-  attr_accessor :setpoint
-
-  def initialize(setpoint)
-    @setpoint, @measure = setpoint, 0.0
-  end
-
-  def input=(val)
-    @measure = val.to_f
-  end
-  alias_method :measure=, :input=
-
-  # just output the error
-  def output
-    @setpoint - @measure
-  end
-
-  def to_s
-    format("Setpoint: %.3f\tMeasure: %.3f", @setpoint, @measure)
-  end
-end
-
-class Thermostat < Controller
-  # true or false; can drive a Heater or a Cooler
-  # true means input below setpoint; false otherwise
-  def output
-    @setpoint - @measure > 0
-  end
-end
-
-class Flexstat < Thermostat
-  def self.cold_val(hot_val)
-    case hot_val
-    when true, false
-      !hot_val
-    when 0,1
-      hot_val == 0 ? 1 : 0
-    when Numeric
-      0
-    when :on, :off
-      hot_val == :on ? :off : :on
-    else
-      raise "#{hot_val.inspect} not recognized"
-    end
-  end
-
-  def initalize(hot_val: false, cold_val: nil)
-    @hot_val = hot_val
-    @cold_val = cold_val.nil? ? self.class.cold_val(hot_val) : cold_val
-  end
-
-  def output
-    super ? @cold_val : @hot_val
-  end
-end
-
-# now consider e.g.
-# h = Heater.new(1000)
-# ht = Thermostat.new(20)
-# c = Cooler.new(1000)
-# ct = Thermostat.new(25)
-# temp = 26.4
-# heat_knob = ht.update(temp) ? 1 : 0
-# heating_watts = h.update(heat_knob)
-# cool_knob = ct.update(temp) ? 0 : 1
-# cooling_watts = c.update(cool_knob)
-# etc
-
-# A StatefulController tracks its error over time: current, last, accumulated
-#
-class StatefulController < Controller
-  HZ = 1000
-  TICK = Rational(1) / HZ
-
-  attr_accessor :dt
-  attr_reader :error, :last_error, :sum_error
-
-  def initialize(setpoint, dt: TICK)
-    super(setpoint)
-    @dt = dt
-    @error, @last_error, @sum_error = 0.0, 0.0, 0.0
-  end
-
-  # update @error, @last_error, and @sum_error
-  def input=(val)
-    @measure = val
-    @last_error = @error
-    @error = @setpoint - @measure
-    if @error * @last_error <= 0  # zero crossing; reset the accumulated error
-      @sum_error = @error * @dt
-    else
-      @sum_error += @error * @dt
-    end
-  end
-
-  def to_s
-    [super,
-     format("Error: %+.3f\tLast: %+.3f\tSum: %+.3f",
-            @error, @last_error, @sum_error),
-    ].join("\n")
-  end
-end
-
-# A PIDController is a StatefulController that calculates
-# * Proportion (current error)
-# * Integral   (accumulated error)
-# * Derivative (error slope, last_error)
-# The sum of these terms is the output
-#
-class PIDController < StatefulController
-  # Ziegler-Nichols method for tuning PID gain knobs
-  # https://en.wikipedia.org/wiki/Ziegler%E2%80%93Nichols_method
-  ZN = {
-    #           Kp     Ti    Td     Ki     Kd
-    #     Var:  Ku     Tu    Tu    Ku/Tu  Ku*Tu
-    'P'    => [1/2r],
-    'PI'   => [9/20r, 4/5r,   nil, 27/50r],
-    'PD'   => [ 4/5r,  nil,  1/8r,  nil, 1/10r],
-    'PID'  => [ 3/5r, 1/2r,  1/8r, 6/5r, 3/40r],
-    'PIR'  => [7/10r, 2/5r, 3/20r, 7/4r, 21/200r],
-    # less overshoot than standard PID
-    'some' => [ 1/3r, 1/2r,  1/3r, 2/3r, 1/11r],
-    'none' => [ 1/5r, 1/2r,  1/3r, 2/5r, 2/30r],
-  }
-
-  # _ku_ = ultimate gain, _tu_ = oscillation period
-  # output includes ti and td, which are not necessary
-  # typically kp, ki, and kd are used
-  def self.tune(type, ku, tu)
-    record = ZN[type.downcase] || ZN[type.upcase] || ZN.fetch(type)
-    kp, ti, td, ki, kd = *record
-    kp *= ku if kp
-    ti *= tu if ti
-    td *= tu if td
-    ki *= (ku / tu) if ki
-    kd *= (ku * tu) if kd
-    { kp: kp, ti: ti, td: td, ki: ki, kd: kd }
-  end
-
-  attr_accessor :kp, :ki, :kd, :p_range, :i_range, :d_range, :o_range
-
-  def initialize(setpoint, dt: TICK)
-    super
-
-    # gain / multipliers for PID; tunables
-    @kp, @ki, @kd = 1.0, 1.0, 1.0
-
-    # optional clamps for PID terms and output
-    @p_range = (-Float::INFINITY..Float::INFINITY)
-    @i_range = (-Float::INFINITY..Float::INFINITY)
-    @d_range = (-Float::INFINITY..Float::INFINITY)
-    @o_range = (-Float::INFINITY..Float::INFINITY)
-
-    yield self if block_given?
-  end
-
-  def output
-    (self.proportion +
-     self.integral +
-     self.derivative).clamp(@o_range.begin, @o_range.end)
-  end
-
-  def proportion
-    (@kp * @error).clamp(@p_range.begin, @p_range.end)
-  end
-
-  def integral
-    (@ki * @sum_error).clamp(@i_range.begin, @i_range.end)
-  end
-
-  def derivative
-    (@kd * (@error - @last_error) / @dt).clamp(@d_range.begin, @d_range.end)
-  end
-
-  def to_s
-    super +
-      [format(" Gain:\t%.3f\t%.3f\t%.3f",
-              @kp, @ki, @kd),
-       format("  PID:\t%+.3f\t%+.3f\t%+.3f\t= %.5f",
-              self.proportion, self.integral, self.derivative, self.output),
-      ].join("\n")
-  end
-end

data/test/pid_controller.rb

@@ -1,283 +0,0 @@
-require 'pid_controller'
-require 'minitest/autorun'
-
-# create a basic class that includes Updateable as a Mixin
-# the class should define #initialize, #input= and #output at minimum
-class Doubler
-  include Updateable
-
-  attr_accessor :input
-
-  def initialize
-    @input = 0.0
-  end
-
-  def output
-    @input * 2
-  end
-end
-
-describe Updateable do
-  describe "a mixin that provides the _update_ pattern" do
-    before do
-      @o = Doubler.new
-    end
-
-    it "has an _update_ method that accepts an _input_ and returns _output_" do
-      expect(@o.input).must_equal 0.0
-      expect(@o.output).must_equal 0.0
-
-      output = @o.update(45)
-      expect(@o.input).must_equal 45
-      expect(@o.output).must_equal output
-    end
-
-    it "requires an _output_ method" do
-      k = Class.new(Object) do
-        include Updateable
-      end
-      o = k.new
-      expect { o.update(45) }.must_raise NoMethodError
-    end
-  end
-end
-
-describe Device do
-  before do
-    @device = Device.new
-  end
-
-  it "has an _output_" do
-    expect(@device.output).must_be_kind_of Float
-  end
-
-  it "has a string representation" do
-    expect(@device.to_s).must_be_kind_of String
-  end
-
-  it "has an _update_ method from Updateable" do
-    expect(@device.update(2.34)).must_be_kind_of Float
-  end
-end
-
-describe Heater do
-  before do
-    @h = Heater.new(1000)
-  end
-
-  it "has an _output_ when _knob_ is greater than zero" do
-    expect(@h.knob).must_equal 0
-    expect(@h.output).must_equal 0
-    @h.knob = 1
-    expect(@h.output).must_be :>, 0
-  end
-
-  it "has a string representation" do
-    expect(@h.to_s).must_be_kind_of String
-  end
-
-  it "has _update_ from Updateable" do
-    expect(@h.knob).must_equal 0
-    expect(@h.output).must_equal 0
-    output = @h.update(1)
-    expect(output).must_be :>, 0
-    expect(@h.knob).must_equal 1
-    expect(@h.output).must_equal output
-  end
-end
-
-describe Controller do
-  before do
-    @sp = 500
-    @c = Controller.new(@sp)
-  end
-
-  it "has an _output_, the difference between setpoint and measure" do
-    expect(@c.output).must_be_kind_of Float
-    expect(@c.output).must_equal @sp
-  end
-
-  it "has a string representation" do
-    expect(@c.to_s).must_be_kind_of String
-  end
-
-  it "has an _update_ method from Updateable" do
-    expect(@c.update(499)).must_equal 1.0
-  end
-end
-
-describe Thermostat do
-  before do
-    @t = Thermostat.new 25
-  end
-
-  it "outputs true when it's too cold; when measure < setpoint" do
-    expect(@t.update 20).must_equal true
-    expect(@t.update 30).must_equal false
-  end
-
-  it "outputs false when it's too hot; when measure > setpoint" do
-    expect(@t.update 30).must_equal false
-    expect(@t.update 20).must_equal true
-  end
-end
-
-describe StatefulController do
-  it "tracks error, last_error, sum_error" do
-    sc = StatefulController.new(100)
-    expect(sc.error).must_equal 0.0
-    expect(sc.last_error).must_equal 0.0
-    expect(sc.sum_error).must_equal 0.0
-
-    output = sc.update 50
-    expect(sc.output).must_equal output
-    expect(sc.measure).must_equal 50
-    expect(sc.error).must_be_within_epsilon 50.0
-    expect(sc.last_error).must_equal 0.0
-    expect(sc.sum_error).must_be_within_epsilon(50.0 * sc.dt)
-
-    output = sc.update 75
-    expect(sc.output).must_equal output
-    expect(sc.measure).must_equal 75
-    expect(sc.error).must_be_within_epsilon 25.0
-    expect(sc.last_error).must_be_within_epsilon 50.0
-    expect(sc.sum_error).must_be_within_epsilon(75.0 * sc.dt)
-  end
-
-  it "resets sum_error after crossing setpoint" do
-    sc = StatefulController.new(100)
-    sc.update 50
-    sc.update 75
-    expect(sc.sum_error).must_be_within_epsilon(75.0 * sc.dt)
-    sc.update 125
-    expect(sc.error).must_equal(-25.0)
-    expect(sc.sum_error).must_equal(sc.error * sc.dt)
-  end
-end
-
-describe PIDController do
-  it "informs Ziegler-Nichols tuning" do
-    # P only, not PID
-    hsh = PIDController.tune('P', 5, 0.01)
-    expect(hsh[:kp]).must_be :>, 0
-    expect(hsh[:ki]).must_be_nil
-    expect(hsh[:kd]).must_be_nil
-    expect(hsh[:ti]).must_be_nil
-    expect(hsh[:td]).must_be_nil
-
-    hsh = PIDController.tune('PI', 5, 0.01)
-    expect(hsh[:kp]).must_be :>, 0
-    expect(hsh[:ki]).must_be :>, 0
-    expect(hsh[:kd]).must_be_nil
-    expect(hsh[:ti]).must_be :>, 0
-    expect(hsh[:td]).must_be_nil
-
-    hsh = PIDController.tune('PID', 5, 0.01)
-    expect(hsh[:kp]).must_be :>, 0
-    expect(hsh[:ki]).must_be :>, 0
-    expect(hsh[:kd]).must_be :>, 0
-    expect(hsh[:ti]).must_be :>, 0
-    expect(hsh[:td]).must_be :>, 0
-  end
-
-  it "has an optional _dt_ argument to initialize" do
-    pid = PIDController.new(1000, dt: 0.1)
-    expect(pid).must_be_kind_of PIDController
-    expect(pid.setpoint).must_equal 1000
-    expect(pid.dt).must_equal 0.1
-  end
-
-  it "has PID gain settings" do
-    pid = PIDController.new(1000)
-    expect(pid.kp).must_be :>, 0
-    pid.kp = 1000
-    expect(pid.kp).must_equal 1000
-    pid.ki = 1000
-    expect(pid.ki).must_equal 1000
-    pid.kd = 1000
-    expect(pid.kd).must_equal 1000
-  end
-
-  it "clamps the _proportion_ term" do
-    pid = PIDController.new(1000)
-    pid.p_range = (0..1)
-    pid.update(500)
-    expect(pid.proportion).must_equal 1.0
-    pid.update(1500)
-    expect(pid.proportion).must_equal 0.0
-  end
-
-  it "clamps the _integral_ term" do
-    pid = PIDController.new(1000)
-    pid.i_range = (-1.0 .. 1.0)
-    pid.setpoint = 10_000
-    pid.update(500)
-    expect(pid.integral).must_equal 1.0
-    pid.update(10_001)
-    pid.update(20_000)
-    expect(pid.integral).must_equal(-1.0)
-  end
-
-  it "clamps the _derivative_ term" do
-    pid = PIDController.new(1000)
-    pid.d_range = (-1.0 .. 0.0)
-    pid.update(0)
-    pid.update(10)
-    expect(pid.derivative).must_equal(-1.0)
-    pid.update(990)
-    expect(pid.derivative).must_equal(-1.0)
-    pid.update(1000)
-    pid.update(990)
-    expect(pid.derivative).must_equal(0.0)
-  end
-
-  it "clamps the _output_" do
-    pid = PIDController.new(1000)
-    pid.o_range = (0.0 .. 1.0)
-    pid.update(0)
-    expect(pid.output).must_equal(1.0)
-    pid.update(2000)
-    expect(pid.output).must_equal(0.0)
-  end
-
-  it "calculates _proportion_ based on current error" do
-    pid = PIDController.new(1000)
-    pid.kp = 1.0
-    pid.update(0)
-    expect(pid.proportion).must_equal 1000.0
-    pid.update(1)
-    expect(pid.proportion).must_equal 999.0
-    pid.update(1001)
-    expect(pid.proportion).must_equal(-1.0)
-  end
-
-  it "calculates _integral_ based on accumulated error" do
-    pid = PIDController.new(1000)
-    pid.ki = 1.0
-    pid.update(0)
-    # sum error should be 1000; dt is 0.001
-    expect(pid.integral).must_equal(1.0)
-    pid.update(999)
-    expect(pid.integral).must_be_within_epsilon(1.001)
-    pid.update(1100) # zero crossing
-    expect(pid.integral).must_be_within_epsilon(-0.1)
-  end
-
-  it "calculates _derivative_ based on error slope" do
-    pid = PIDController.new(1000)
-    pid.kp = 1.0
-    pid.update(0)
-    # error should be 1000; last_error 0
-    expect(pid.derivative).must_equal(1_000_000)
-    pid.update(500)
-    expect(pid.derivative).must_equal(-500_000)
-    pid.update(999)
-    expect(pid.derivative).must_equal(-499_000)
-    pid.update(1001)
-    expect(pid.derivative).must_equal(-2000)
-    pid.update(1100)
-    expect(pid.derivative).must_equal(-99_000)
-    pid.update(900)
-    expect(pid.derivative).must_equal(200_000)
-  end
-end