gravitheque 0.3.0 → 0.4.0

data/lib/calculators/hops.rb

@@ -4,64 +4,87 @@ require "conversions/volume"
 
 module Calculate
 
-  # Calculate hop utilization.
+  # Calculates hop utilization.
+  # Supported extract units are `:brix`, `:plato` and `:specific_gravity`. Default: `:plato`
   #
   # @example
-  #    Calculate.hop_utilization 12, 20
-  #    Calculate.hop_utilization 16.3, 45, :brix
-  #    Calculate.hop_utilization 1.089, 60, :specific_gravity
+  #     Calculate.hop_utilization({ at: 20, extract: 12 })
+  #     Calculate.hop_utilization({ at: 20, extract: 12 }, :brix)
+  #     Calculate.hop_utilization({ at: 20, extract: 12 }, :specific_gravity)
   #
-  # @param [Float] extract degrees Plato of wort being pitched
-  # @param [Float] at boil time remaining when hop addition is made
-  # @param [Symbol] unit used to change default settings for `extract`
+  # @param [Hash] data the extract level and time added
+  # @param [Symbol] unit the unit used to measure extract
   # @return [Float] hop utilization
-  def self.hop_utilization extract, at, unit = :plato
-    unless unit == :specific_gravity
-      extract = case unit
-      when :brix then Convert.brix_to_specific_gravity extract
-      when :plato then Convert.plato_to_specific_gravity extract
-      else raise ArgumentError, "#{unit} is not recognized as a unit of extract"
+  def self.hop_utilization data, units = :plato
+    unless units == :specific_gravity
+      data[:extract] = case units
+      when :brix then Convert.brix_to_specific_gravity data[:extract]
+      when :plato then Convert.plato_to_specific_gravity data[:extract]
+      else raise ArgumentError, "#{units} is an unknown unit of extract. Use :brix, :plato or :specific_gravity"
       end
     end
 
-    ((hop_extract_adjustment extract, :specific_gravity) *
-    ((hop_boil_time_adjustment at) / 4.15)).round 2
+    ((hop_extract_adjustment data[:extract], :specific_gravity) *
+    ((hop_boil_time_adjustment data[:at]) / 4.15)).round 2
   end
 
-  # Calculate IBUs for hop addition.
+  # Calculates IBUs for hop addition.
+  # Supported extract units are `:brix`, `:plato` and `:specific_gravity`. Default: `:plato`
+  # Supported mass units are `:grams` and `:ounces`. Default: `:grams`
+  # Supported volume units are `:gallons` and `:liters`. Default: `:liters`
   #
   # @example
-  #    Calculate.ibus({ :extract => 15, :at => 60, :alpha => 6.5, :mass => 56, :volume => 20 })
-  #    Calculate.ibus({ :extract => 18.5, :at => 60, :alpha => 6.5, :mass => 56, :volume => 20 }, { :extract => :brix })
-  #    Calculate.ibus({ :extract => 1.055, :at => 60, :alpha => 6.5, :mass => 2, :volume => 5 }, { :extract => :specific_gravity, :mass => :ounces, :volume => :gallons })
+  #     Calculate.ibus({
+  #       alpha: 12.4,
+  #       at: 90,
+  #       extract: 15,
+  #       mass: 56,
+  #       volume: 20
+  #     })
   #
-  # @param [Hash] data data required to calculate IBUs; `:extract`, `:alpha`, `:at`, `:mass`, `:volume`
-  # @param [Hash] options used to change default settings for `extract`, `volume` and `mass`
+  #     Calculate.ibus({
+  #       alpha: 6.5,
+  #       at: 60,
+  #       extract: 18.5,
+  #       mass: 30,
+  #       volume: 40
+  #     }, { extract: :brix })
+  #
+  #     Calculate.ibus({
+  #       alpha: 8,
+  #       at: 30,
+  #       extract: 1.055,
+  #       mass: 3,
+  #       volume: 5
+  #     }, { extract: :specific_gravity, mass: :ounces, volume: :gallons })
+  #
+  # @param [Hash] data data required to calculate IBUs; `extract`, `alpha`, `at`, `mass`, `volume`
+  # @param [Hash] units used to change default units for `extract`, `volume` and `mass`
   # @return [Fixnum] IBUs from hop addition
-  def self.ibus data, options = {}
-    options.merge!(:extract => :plato)  unless options[:extract]
-    options.merge!(:mass    => :grams)  unless options[:mass]
-    options.merge!(:volume  => :liters) unless options[:volume]
+  def self.ibus data, units = {}
+    units.merge!(extract: :plato) unless units[:extract]
+    units.merge!(mass: :grams)    unless units[:mass]
+    units.merge!(volume: :liters) unless units[:volume]
 
-    unless options[:extract] == :specific_gravity
-      data[:extract] = case options[:extract]
+    unless units[:extract] == :specific_gravity
+      data[:extract] = case units[:extract]
       when :brix then Convert.brix_to_specific_gravity data[:extract]
       when :plato then Convert.plato_to_specific_gravity data[:extract]
-      else raise ArgumentError, "#{options[:extract]} is not recognized as a unit of extract"
+      else raise ArgumentError, "#{units[:extract]} is an unknown unit of extract. Use :brix, :plato or :specific_gravity"
       end
     end
 
-    unless options[:mass] == :grams
-      data[:mass] = case options[:mass]
+    unless units[:mass] == :grams
+      data[:mass] = case units[:mass]
       when :ounces then Convert.ounces_to_grams data[:mass]
-      else raise ArgumentError, "#{options[:mass]} is not recognized as a unit of mass"
+      else raise ArgumentError, "#{units[:mass]} is an unknown unit of mass. Use :grams or :ounces"
       end
     end
 
-    unless options[:volume] == :liters
-      data[:volume] = case options[:volume]
+    unless units[:volume] == :liters
+      data[:volume] = case units[:volume]
       when :gallons then Convert.gallons_to_liters data[:volume]
-      else raise ArgumentError, "#{options[:volume]} is not recognized as a unit of volume"
+      else raise ArgumentError, "#{units[:volume]} is an unknown unit of volume. Use :gallons or :liters"
       end
     end
 
@@ -70,66 +93,113 @@ module Calculate
      data[:mass] * 1000 / (data[:volume] * 4.15)).round
   end
 
-  # Calculate hop mass required to achieve specific IBUs.
+  # Calculates hop mass required to achieve specific IBUs.
+  # Supported extract units are `:brix`, `:plato` and `:specific_gravity`. Default: `:plato`
+  # Supported volume units are `:gallons` and `:liters`. Default: `:liters`
   #
   # @example
-  #    Calculate.hop_mass_required({ :ibu => 50, :extract => 12, :at => 30, :alpha => 10, :volume => 20 })
-  #    Calculate.hop_mass_required({ :ibu => 15, :extract => 14.5, :at => 15, :alpha => 3.2, :volume => 20 }, { :extract => :brix })
-  #    Calculate.hop_mass_required({ :ibu => 100, :extract => 1.05, :at => 90, :alpha => 12.4, :volume => 10 }, { :extract => :specific_gravity, :volume => :gallons })
-  #
-  # @param [Hash] data data required to calculate hop mass required; `:extract`, `:alpha`, `:at`, `:volume`, `:ibus`
-  # @param [Hash] options used to change default settings for `extract` and `volume`
-  # @return [Fixnum] hop mass required to achieve specific IBUs
-  def self.hop_mass_required data, options = {}
-    options.merge!(:extract => :plato)  unless options[:extract]
-    options.merge!(:volume  => :liters) unless options[:volume]
-
-    unless options[:extract] == :specific_gravity
-      data[:extract] = case options[:extract]
+  #     Calculate.hop_mass_required({
+  #       alpha: 13.5,
+  #       at: 60,
+  #       extract: 16,
+  #       ibus: 25,
+  #       volume: 20
+  #     })
+  #
+  #     Calculate.hop_mass_required({
+  #       alpha: 3.2,
+  #       at: 15,
+  #       extract: 14.5,
+  #       ibus: 15,
+  #       volume: 20
+  #     }, { extract: :brix })
+  #
+  #     Calculate.hop_mass_required({
+  #       alpha: 12.4,
+  #       at: 90,
+  #       extract: 1.05,
+  #       ibus: 100,
+  #       volume: 10
+  #     }, { extract: :specific_gravity, volume: :gallons })
+  #
+  # @param [Hash] data data required to calculate hop mass required; `extract`, `ibus`, `alpha`, `at`, `volume`
+  # @param [Hash] units used to change default units for `extract` and `volume`
+  # @return [Float] hop mass required to achieve specific IBUs
+  def self.hop_mass_required data, units = {}
+    units.merge!(extract: :plato) unless units[:extract]
+    units.merge!(mass: :grams) unless units[:mass]
+    units.merge!(volume: :liters) unless units[:volume]
+
+    unless units[:extract] == :specific_gravity
+      data[:extract] = case units[:extract]
       when :brix then Convert.brix_to_specific_gravity data[:extract]
       when :plato then Convert.plato_to_specific_gravity data[:extract]
-      else raise ArgumentError, "#{options[:extract]} is not recognized as a unit of extract"
+      else raise ArgumentError, "#{units[:extract]} is an unknown unit of extract. Use :brix, :plato or :specific_gravity"
       end
     end
 
-    unless options[:volume] == :liters
-      data[:volume] = case options[:volume]
+    unless units[:volume] == :liters
+      data[:volume] = case units[:volume]
       when :gallons then Convert.gallons_to_liters data[:volume]
-      else raise ArgumentError, "#{options[:volume]} is not recognized as a unit of volume"
+      else raise ArgumentError, "#{units[:volume]} is an unknown unit of volume. Use :gallons or :liters"
       end
     end
 
-    ((data[:volume] * data[:ibus]) /
-     (hop_utilization(data[:extract], data[:at], :specific_gravity) *
-     data[:alpha] * 10)).round
+    mass = ((data[:volume] * data[:ibus]) /
+            (hop_utilization({extract: data[:extract], at: data[:at]}, :specific_gravity) *
+            data[:alpha] * 10))
+
+    units[:mass] == :grams ? mass.round : Convert.grams_to_ounces(mass).round(1)
   end
 
   # Calculate milliliters of HopShot required to achieve specific IBUs.
+  # Supported extract units are `:brix`, `:plato` and `:specific_gravity`. Default: `:plato`
+  # Supported volume units are `:gallons` and `:liters`. Default: `:liters`
   #
   # @example
-  #    Calculate.hopshot_required({ :ibus => 40, :extract => 18, :at => 60, :volume => 20 })
-  #    Calculate.hopshot_required({ :ibus => 40, :extract => 14.5, :at => 60, :volume => 20 }, { :extract => :brix })
-  #    Calculate.hopshot_required({ :ibus => 40, :extract => 1.085, :at => 60, :volume => 10.5 }, { :extract => :specific_gravity, :volume => :gallons })
-  #
-  # @param [Hash] data data required to calculate HopShot required; `:extract`, `:at`, `:volume`, `:ibus`
-  # @param [Hash] options used to change default settings for `extract` and `volume`
-  # @return [Fixnum] HopShot required to achieve specific IBUs
-  def self.hopshot_required data, options = {}
-    options.merge!(:extract => :plato)  unless options[:extract]
-    options.merge!(:volume  => :liters) unless options[:volume]
-
-    unless options[:extract] == :specific_gravity
-      data[:extract] = case options[:extract]
+  #     Calculate.hopshot_required({
+  #       alpha: 13.5,
+  #       at: 60,
+  #       extract: 16,
+  #       ibus: 25,
+  #       volume: 20
+  #     })
+  #
+  #     Calculate.hopshot_required({
+  #       alpha: 3.2,
+  #       at: 15,
+  #       extract: 14.5,
+  #       ibus: 15,
+  #       volume: 20
+  #     }, { extract: :brix })
+  #
+  #     Calculate.hopshot_required({
+  #       alpha: 12.4,
+  #       at: 90,
+  #       extract: 1.05,
+  #       ibus: 100,
+  #       volume: 10
+  #     }, { extract: :specific_gravity, volume: :gallons })
+  #
+  # @param [Hash] data data required to calculate hop mass required; `extract`, `ibus`, `at`, `volume`
+  # @param [Hash] units used to change default units for `extract` and `volume`
+  # @return [Float] milliliters of HopShot required to achieve specific IBUs
+  def self.hopshot_required data, units = {}
+    units.merge!(extract: :plato) unless units[:extract]
+    units.merge!(volume: :liters) unless units[:volume]
+
+    unless units[:extract] == :specific_gravity
+      data[:extract] = case units[:extract]
       when :brix then Convert.brix_to_specific_gravity data[:extract]
       when :plato then Convert.plato_to_specific_gravity data[:extract]
-      else raise ArgumentError, "#{options[:extract]} is not recognized as a unit of extract"
+      else raise ArgumentError, "#{units[:extract]} is an unknown unit of extract. Use :brix, :plato or :specific_gravity"
       end
     end
 
-    unless options[:volume] == :liters
-      data[:volume] = case options[:volume]
+    unless units[:volume] == :liters
+      data[:volume] = case units[:volume]
       when :gallons then Convert.gallons_to_liters data[:volume]
-      else raise ArgumentError, "#{options[:volume]} is not recognized as a unit of volume"
+      else raise ArgumentError, "#{units[:volume]} is an unknown unit of volume. Use :liters or :gallons"
       end
     end
 
@@ -172,12 +242,12 @@ module Calculate
   #
   # @param [Float] extract extract level when hop addition is made
   # @return [Float] extract adjustment
-  def self.hop_extract_adjustment extract, unit = :plato
-    unless unit == :specific_gravity
-      extract = case unit
+  def self.hop_extract_adjustment extract, units = :plato
+    unless units == :specific_gravity
+      extract = case units
       when :brix then Convert.brix_to_specific_gravity extract
       when :plato then Convert.plato_to_specific_gravity extract
-      else raise ArgumentError, "#{unit} is not recognized as a unit of extract"
+      else raise ArgumentError, "#{units} is an unknown unit of extract. Use :brix, :plato or :specific_gravity"
       end
     end
 

data/lib/calculators/mash.rb

@@ -1,40 +1,69 @@
 module Calculate
 
-  # Calculate temperature of strike water for dough in.
+  # Calculates temperature of strike water for dough in.
+  # Supported units are `:metric` and `:us`. Default: `:metric`
   #
   # @example
-  #     Calculate.strike_temperature 1.5, 20, 68
-  #     Calculate.strike_temperature 1.5, 70, 154, :us
+  #     Calculate.strike_temperature({
+  #       ratio: 1.5,
+  #       initial: 20,
+  #       target: 75
+  #     })
   #
-  # @param [Float] ratio water to grain ratio; e.g. 1.5 liters per kilogram
-  # @param [Fixnum] initial temperature of grains
-  # @param [Fixnum] target mash temperature
-  # @param [Symbol] units change units of measure to U.S. customary
+  #     Calculate.strike_temperature({
+  #       ratio: 1.25,
+  #       initial: 65,
+  #       target: 154
+  #     }, :us)
+  #
+  #     Calculate.strike_temperature({
+  #       ratio: 1.5,
+  #       initial: 60,
+  #       target: 150,
+  #       loss: 1.015
+  #     }, :us)
+  #
+  # @param [Hash] data data required to calculate hop mass required; `ratio`, `initial`, `target`
+  # @param [Symbol] units the unit used to measure temperature
   # @return [Fixnum] strike water temperature
-  def self.strike_temperature ratio, initial, target, units = :metric
+  def self.strike_temperature data, units = :metric
     constant = case units
     when :metric then 0.41
     when :us then 0.2
-    else raise ArgumentError, "Units must be one of :metric or :us"
+    else raise ArgumentError, "#{units} is an unknown unit of measures. Use :metric or :us"
     end
 
-    ((constant / ratio) * (target - initial) + target).round
+    data.merge!(loss: 1) unless data[:loss]
+
+    (((constant / data[:ratio]) *
+      (data[:target] - data[:initial]) +
+       data[:target]) * data[:loss]).round
   end
 
-  # Calculate volume of boiling infusion water needed to increase mash temperature.
+  # Calculates volume of boiling infusion water needed to increase mash temperature.
+  # Supported units are `:metric` and `:us`. Default: `:metric`
   #
   # @example
-  #     Calculate.infusion_volume 1.5, 20, 68, 3.6, 4.3
-  #     Calculate.infusion_volume 1.5, 70, 154, 8, 9.6, :us
+  #     Calculate.infusion_volume({
+  #       ratio: 1,
+  #       initial: 40,
+  #       target: 60,
+  #       mass: 3.6,
+  #       volume: 3.6
+  #     })
+  #
+  #     Calculate.infusion_volume({
+  #       ratio: 1,
+  #       initial: 104,
+  #       target: 140,
+  #       mass: 8,
+  #       volume: 8
+  #     }, :us)
   #
-  # @param [Float] ratio water to grain ratio; e.g. 1.5 liters per kilogram
-  # @param [Fixnum] initial temperature of mash
-  # @param [Fixnum] target mash temperature
-  # @param [Float] mass weight of grain in the mash
-  # @param [Float] volume amount of water already in the mash
-  # @param [Symbol] units change units of measure to U.S. customary
+  # @param [Hash] data data required to calculate infusion volume; `ratio`, `initial`, `target`, `mass`, `volume`
+  # @param [Symbol] units the unit used for measurements
   # @return [Fixnum] infusion water volume
-  def self.infusion_volume ratio, initial, target, mass, volume, units = :metric
+  def self.infusion_volume data, units = :metric
     case units
     when :metric
       boiling = 100
@@ -42,10 +71,12 @@ module Calculate
     when :us
       boiling = 212
       constant = 0.2
-    else raise ArgumentError, "Units must be one of :metric or :us"
+    else raise ArgumentError, "#{units} is an unknown unit of measures. Use :metric or :us"
     end
 
-    ((target - initial) * ((constant * mass) + volume) / (boiling - target)).round 1
+    ((data[:target] - data[:initial]) *
+     ((constant * data[:mass]) + data[:volume]) /
+     (boiling - data[:target])).round 1
   end
 
-end
+end

data/lib/calculators/yeast.rb

@@ -3,42 +3,66 @@ require "conversions/volume"
 
 module Calculate
 
-  # Calculate the number of yeast cells needed to properly ferment a batch.
+  # Calculates the number of yeast cells needed to properly ferment a batch.
+  # Supported extract units are `:brix`, `:plato` and `:specific_gravity`. Default: `:plato`
+  # Supported beers types are `:ale`, `:hybrid` and `:lager`. Default: `:ale`
+  # Supported volume units are `:gallons` and `:liters`. Default: `:liters`
   #
   # @example
-  #    Calculate.yeast_cells_needed 12, 20
-  #    Calculate.yeast_cells_needed 12, 20, { :type => :lager }
-  #    Calculate.yeast_cells_needed 12, 50, { :volume => :gallons }
-  #    Calculate.yeast_cells_needed 1.048, 20, { :extract => :specific_gravity }
-  #    Calculate.yeast_cells_needed 1.065, 10.5, { :extract => :specific_gravity, :type => :hybrid, :volume => :gallons }
+  #     Calculate.yeast_cells_required({
+  #       extract: 16.5,
+  #       volume: 19
+  #     })
   #
-  # @param [Float] extract degrees Plato of wort being pitched
+  #     Calculate.yeast_cells_required({
+  #       extract: 15.75,
+  #       volume: 5.25
+  #     }, { volume: :gallons })
+  #
+  #     Calculate.yeast_cells_required({
+  #       extract: 1.055,
+  #       volume: 55
+  #     }, { extract: :specific_gravity })
+  #
+  #     Calculate.yeast_cells_required({
+  #       extract: 18,
+  #       volume: 20,
+  #       type: :hybrid
+  #     })
+  #
+  #     Calculate.yeast_cells_required({
+  #       extract: 21.5,
+  #       volume: 10.5,
+  #       type: :lager
+  #     }, { volume: :gallons, extract: :brix })
+  #
+  # @param [Hash] data data required to calculate yeast cells required; `extract`, `volume`, `type`
   # @param [Float] volume liters of wort being pitched
   # @param [Hash] options used to change default settings for `extract`, `volume` and `type`
   # @return [Fixnum] yeast cells needed to ferment the batch
-  def self.yeast_cells_required extract, volume, options = {}
-    options.merge!(:volume  => :liters) unless options[:volume]
-    options.merge!(:extract => :plato)  unless options[:extract]
-    options.merge!(:type    => :ale)    unless options[:type]
+  def self.yeast_cells_required data, units = {}
+    data.merge!(:type => :ale) unless data[:type]
+    units.merge!(:extract => :plato) unless units[:extract]
+    units.merge!(:volume => :liters) unless units[:volume]
 
-    cells_per_milliliter = case options[:type]
+    cells_per_milliliter = case data[:type]
     when :ale     then 750_000
     when :hybrid  then 1_125_000
     when :lager   then 1_500_000
-    else raise ArgumentError, "#{options[:type]} is not recognized as a beer type"
+    else raise ArgumentError, "#{data[:type]} is an unknown type of beer. Use :ale, :hybrid or :lager"
     end
 
-    volume = case options[:volume]
-    when :liters  then volume
-    when :gallons then Convert.gallons_to_liters volume
-    else raise ArgumentError, "#{options[:volume]} is not recognized as measure of volume"
+    volume = case units[:volume]
+    when :liters  then data[:volume]
+    when :gallons then Convert.gallons_to_liters data[:volume]
+    else raise ArgumentError, "#{units[:volume]} is an unknown unit of volume. Use :gallons or :liters"
     end
 
-    extract = case options[:extract]
-    when :plato             then extract
-    when :brix              then Convert.specific_gravity_to_plato(Convert.brix_to_specific_gravity extract)
-    when :specific_gravity  then Convert.specific_gravity_to_plato extract
-    else raise ArgumentError, "#{options[:extract]} is not recognized as measure of extract"
+    extract = case units[:extract]
+    when :plato             then data[:extract]
+    when :brix              then Convert.specific_gravity_to_plato(Convert.brix_to_specific_gravity data[:extract])
+    when :specific_gravity  then Convert.specific_gravity_to_plato data[:extract]
+    else raise ArgumentError, "#{units[:extract]} is an unknown unit of extract. Use :brix, :plato or :specific_gravity"
     end
 
     (cells_per_milliliter * (volume * 1000) * extract).round