joules 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7a84b8c006d8d0a2350bf289f2ed38840d872fb3
-  data.tar.gz: 26f4381a896f244a451e3582a1f190a423143fb2
+  metadata.gz: 73cc9f5843a96d24a698edd34d88f242df38678a
+  data.tar.gz: 76ca90cf9af87effc2f4adbaab64e5e1145c6925
 SHA512:
-  metadata.gz: e95c4f6be852c8356a034f295a5e913187df2acc6437f887d2510eccfb539f69fcf228f5234f8f9990c7095f7a41aaaed1febdf403346fbaba92239c044f02d9
-  data.tar.gz: f6de041a305570a7e25f5544c6f61ea13afdf05cea7bf018eb8c984d80b395479159a583571cc382f4cb5e32686f2bbd55b8bc8e63b6c5d5dc0c22396530c515
+  metadata.gz: 6ac9efd15828c56da8c5268a7cb67de5f71325fee00e971c512cbd9f5963ed245b9f1a0e0285cd6883f24b3b4e12afa0e5ffbcc718d47bf3b1fe446fe360ba53
+  data.tar.gz: 0ac87b0cb54ccdb32d99cd1a53144f43539e6a2c3fcd5c814e634bd0d3f0a2306016e8a65e60377b2e549b8a0e555133c699188b6e3b553117211b066c0207a5

data/README.md

@@ -15,7 +15,7 @@ gem build joules.gemspec
 
 ### Library Installation
 ```Bash
-gem install joules-0.3.1.gem
+gem install joules-0.3.2.gem
 ```
 
 ### Library Import
@@ -26,15 +26,15 @@ require 'joules'
 ### Usage
 #### Simple Method Call
 ```Ruby
-gravitational_potential_energy(0.5, 6)
+Joules.gravitational_potential_energy(0.5, 6)
 ```
 This would return 29.43.
 #### Method Composition
 ```Ruby
-power(work_done(40, 2.34), 4)
+Joules.power(Joules.work_done(40, 2.34), 4)
 ```
 This would return 23.4.
-> Note: For documentation on methods and constants, please visit [http://www.rubydoc.info/gems/joules/](http://www.rubydoc.info/gems/joules/).
+> Note: For documentation on usage of methods and constants, please visit [http://www.rubydoc.info/gems/joules/](http://www.rubydoc.info/gems/joules/).
 
 ### Change Log
 #### Version 0.0.1
@@ -61,7 +61,11 @@ This would return 23.4.
 * Added more geometric and conversion formulas commonly used in Physics
 
 #### Version 0.3.1
-* Added Physics formulas in gravitational fields and electric fields 
+* Added Physics formulas in gravitational fields and electric fields
+
+#### Version 0.3.2
+* Added Physics formulas in magnetic fields
+* Added Physics formulas in stress and strain
 
 ### Contribution
 Please feel free to submit any ideas, questions, or problems by reporting an issue. 

data/lib/joules/constants.rb

@@ -3,7 +3,7 @@
 #
 # @description: Module for providing constants
 # @author: Elisha Lai
-# @version: 0.3.1 01/06/2015
+# @version: 0.3.2 03/06/2015
 #==============================================================================
 
 # Constants module (constants.rb)
@@ -11,15 +11,15 @@
 module Joules
   
   # Speed of light in free space.
-  # @note This quantity is in meters per second.
+  # @note This quantity is in metres per second.
   SPEED_OF_LIGHT = 3.00e8
 
   # Permeability of free space.
-  # @note This quantity is in henries per meter.
-  FREE_SPACE_PERMEABILITY = 4 * Math::PI * 1e-7
+  # @note This quantity is in henries per metre.
+  FREE_SPACE_PERMEABILITY = (4 * Math::PI * 1e-7)
 
   # Permittivity of free space.
-  # @note This quantity is in farads per meter.
+  # @note This quantity is in farads per metre.
   FREE_SPACE_PERMITTIVITY = 8.85e-12
 
   # Elementary charge.
@@ -59,11 +59,11 @@ module Joules
   BOLTZMANN_CONSTANT = 1.38e-23
 
   # Stefan constant.
-  # @note This quantity is in watts per meter squared kelvin to the fourth power.
+  # @note This quantity is in watts per metre squared kelvin to the fourth power.
   STEFAN_CONSTANT = 5.67e-8
 
   # Wien constant.
-  # @note This quantity is in meter kelvins.
+  # @note This quantity is in metre kelvins.
   WIEN_CONSTANT = 2.9e-3
 
   # Gravitational constant.
@@ -71,7 +71,7 @@ module Joules
   GRAVITATIONAL_CONSTANT = 6.67e-11
 
   # Acceleration of free fall.
-  # @note This quantity is in meters per second squared.
+  # @note This quantity is in metres per second squared.
   FREE_FALL_ACCELERATION = 9.81
 
 end

data/lib/joules/conversion.rb

@@ -3,7 +3,7 @@
 #
 # @description: Module for providing conversion formulas
 # @author: Elisha Lai
-# @version: 0.3.1 01/06/2015
+# @version: 0.3.2 03/06/2015
 #==============================================================================
 
 # Conversion module (conversion.rb)
@@ -55,25 +55,25 @@ module Joules
     return temperature - 273.15
   end
 
-  # Calculates the equivalent velocity in meters per second given kilometers per hour.
+  # Calculates the equivalent velocity in metres per second given kilometres per hour.
   # @param velocity [Int, Float]
-  #   velocity is in kilometers per hour
+  #   velocity is in kilometres per hour
   # @return [Float]
-  #   return value is in meters per second
+  #   return value is in metres per second
   # @example
-  #   Joules.to_meters_per_second(200) #=> 55.55555555555556 
-  def to_meters_per_second(velocity)
+  #   Joules.to_metres_per_second(200) #=> 55.55555555555556 
+  def to_metres_per_second(velocity)
     return (velocity * 1000) / 3600.0
   end
 
-  # Calculates the equivalent velocity in kilometers per hour given meters per second.
+  # Calculates the equivalent velocity in kilometres per hour given metres per second.
   # @param velocity [Int, Float]
-  #   velocity is in meters per second
+  #   velocity is in metres per second
   # @return [Float]
-  #   return value is in kilometers per hour
+  #   return value is in kilometres per hour
   # @example
-  #   Joules.to_kilometers_per_hour(50) #=> 180.0
-  def to_kilometers_per_hour(velocity)
+  #   Joules.to_kilometres_per_hour(50) #=> 180.0
+  def to_kilometres_per_hour(velocity)
     return (velocity * 3600) / 1000.0
   end
 

data/lib/joules/density.rb

@@ -3,7 +3,7 @@
 #
 # @description: Module for providing density formulas
 # @author: Elisha Lai
-# @version: 0.3.1 01/06/2015
+# @version: 0.3.2 03/06/2015
 #==============================================================================
 
 # Density module (density.rb)
@@ -15,13 +15,18 @@ module Joules
   # @param mass [Int, Float]
   #   mass >= 0; mass is in kilograms
   # @param volume [Int, Float]
-  #   volume > 0; volume is in meters cubed
+  #   volume > 0; volume is in metres cubed
   # @return [Float]
-  #   return value >= 0; return value is in kilograms per meter cubed
+  #   return value >= 0; return value is in kilograms per metre cubed
+  # @raise [ZeroDivisionError] if volume = 0 
   # @example
-  #   Joules.density(8.96, 0.002) #=> 4480.0   
+  #   Joules.density(8.96, 0.002) #=> 4480.0
   def density(mass, volume)
-    return mass / volume.to_f
+    if volume.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return mass / volume.to_f
+    end
   end
 
 end

data/lib/joules/electric_fields.rb

@@ -3,7 +3,7 @@
 #
 # @description: Module for providing electric fields formulas
 # @author: Elisha Lai
-# @version: 0.3.1 01/06/2015
+# @version: 0.3.2 03/06/2015
 #==============================================================================
 
 # Electric fields module (electric_fields.rb)
@@ -15,55 +15,89 @@ module Joules
   # @param voltage [Int, Float]
   #   voltage is in volts
   # @param distance [Int, Float]
-  #   distance > 0; distance is in meters
+  #   distance > 0; distance is in metres
   # @return [Float]
   #   return value is in newtons per coulomb/volts per metre
+  # @raise [ZeroDivisionError] if distance = 0
   # @example
   #   Joules.electric_field_strength_v1(9, 0.1) #=> 90.0
   # @note There are two other method for calculating electric field strength.
   def electric_field_strength_v1(voltage, distance)
-  	return voltage / distance.to_f
+    if distance.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return voltage / distance.to_f
+    end
   end
 
   # Calculates the electric field strength for an uniform field given force and charge.
   # @param force [Int, Float]
   #   force is in newtons
   # @param charge [Int, Float]
-  #   charge is in coulombs
+  #   charge != 0; charge is in coulombs
   # @return [Float]
   #   return value is in newtons per coulomb/volts per metre
+  # @raise [ZeroDivisionError] if charge = 0
   # @example
   #   Joules.electric_field_strength_v2(50, 1.3e-6) #=> 38461538.461538464
   # @note There are two other method for calculating electric field strength.
   def electric_field_strength_v2(force, charge)
-    return force / charge.to_f
+    if charge.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return force / charge.to_f
+    end
   end
 
   # Calculates the electric field strength for a radial field given charge and distance.
   # @param charge [Int, Float]
   #   charge is in coulombs
   # @param distance [Int, Float]
-  #   distance > 0; distance is in meters
+  #   distance > 0; distance is in metres
   # @return [Float]
   #   return value is in newtons per coulomb/volts per metre
+  # @raise [ZeroDivisionError] if distance = 0
   # @example
   #   Joules.electric_field_strength_v3(3.2e-19, 0.2) #=> 7.193443755565889e-08
   # @note There are two other method for calculating electric field strength.
   def electric_field_strength_v3(charge, distance)
-    return charge / (4 * Math::PI * FREE_SPACE_PERMITTIVITY * (distance ** 2))
+    if distance.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return charge / (4 * Math::PI * FREE_SPACE_PERMITTIVITY * (distance ** 2))
+    end
   end
 
   # Calculates the electric potential given charge and distance.
   # @param charge [Int, Float]
   #   charge is in coulombs
   # @param distance [Int, Float]
-  #   distance > 0; distance is in meters
+  #   distance > 0; distance is in metres
   # @return [Float]
   #   return value is in volts
+  # @raise [ZeroDivisionError] if distance = 0
   # @example
   #   Joules.electric_potential(3.2e-19, 0.2) #=> 1.4386887511131779e-08
   def electric_potential(charge, distance)
-    return charge / (4 * Math::PI * FREE_SPACE_PERMITTIVITY * distance)
+    if distance.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return charge / (4 * Math::PI * FREE_SPACE_PERMITTIVITY * distance)
+    end
+  end
+
+  # Calculates the kinetic energy of an electron given voltage.
+  # @param voltage [Int, Float]
+  #   voltage is in volts
+  # @param charge [Int, Float]
+  #   charge is in coulombs
+  # @return [Float]
+  #   return value is in electronvolts
+  # @example
+  #   Joules.kinetic_energy_v2(20, 2) #=> 2.5e+20
+  # @note There is one other method for calculating kinetic energy.
+  def kinetic_energy_v2(voltage, charge)
+    return voltage * (charge / ELEMENTARY_CHARGE)
   end
 
 end

data/lib/joules/electricity.rb

@@ -3,7 +3,7 @@
 #
 # @description: Module for providing electricity formulas
 # @author: Elisha Lai
-# @version: 0.3.1 01/06/2015
+# @version: 0.3.2 03/06/2015
 #==============================================================================
 
 # Electricity module (electricity.rb)
@@ -18,10 +18,15 @@ module Joules
   #   time > 0; time is in seconds
   # @return [Float]
   #   return value is in amperes
+  # @raise [ZeroDivisionError] if time = 0
   # @example
   #   Joules.current(325, 5) #=> 65.0
   def current(charge, time)
-    return charge / time.to_f
+    if time.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return charge / time.to_f
+    end
   end
 
   # Calculates the resistance given voltage and current.
@@ -31,27 +36,37 @@ module Joules
   #   current != 0; current is in amperes
   # @return [Float]
   #   return value is in ohms
+  # @raise [ZeroDivisionError] if current = 0
   # @example
   #   Joules.resistance_v1(1.8, 0.6) #=> 3.0
   # @note There is one other method for calculating resistance.
   def resistance_v1(voltage, current)
-    return voltage / current.to_f	
+    if current.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return voltage / current.to_f
+    end
   end
 
   # Calculates the resistance given resistivity, wire length, and cross sectional area.
   # @param resistivity [Int, Float]
   #   resistivity >= 0; resistivity is in ohm metres
   # @param wire_length [Int, Float]
-  #   wire_length >= 0; wire_length is in meters
+  #   wire_length >= 0; wire_length is in metres
   # @param cross_sectional_area [Int, Float]
-  #   cross_sectional_area > 0; cross_sectional_area is in meters squared
+  #   cross_sectional_area > 0; cross_sectional_area is in metres squared
   # @return [Float]
   #   return value >= 0; return value is in ohms
+  # @raise [ZeroDivisionError] if cross_sectional_area = 0
   # @example
   #   Joules.resistance_v2(1e13, 250, 0.4) #=> 6.25e+15
   # @note There is one other method for calculating resistance.
   def resistance_v2(resistivity, wire_length, cross_sectional_area)
-    return (resistivity * wire_length) / cross_sectional_area.to_f
+    if cross_sectional_area.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return (resistivity * wire_length) / cross_sectional_area.to_f
+    end
   end
 
   # Calculates the total resistance of resistors in series.
@@ -95,10 +110,15 @@ module Joules
   #   voltage != 0; voltage is in volts
   # @return [Float]
   #   return value is in farads
+  # @raise [ZeroDivisionError] if voltage = 0
   # @example
   #   Joules.capacitance(2e-3, 100) #=> 2.0e-05
   def capacitance(charge, voltage)
-    return charge / voltage.to_f
+    if voltage.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return charge / voltage.to_f
+    end
   end
 
   # Calculates the capacitor potential energy given charge and voltage.
@@ -133,14 +153,19 @@ module Joules
   # @param charge [Int, Float]
   #   charge is in coulombs
   # @param capacitance [Int, Float]
-  #   capacitance is in farads
+  #   capacitance != 0; capacitance is in farads
   # @return [Float]
   #   return value is in joules
+  # @raise [ZeroDivisionError] if capacitance = 0
   # @example
   #   Joules.capacitor_potential_energy_v3(25, 50) #=> 6.25
   # @note There are two other methods for calculating capacitor potential energy.
   def capacitor_potential_energy_v3(charge, capacitance)
-    return (0.5 * (charge ** 2)) / capacitance
+    if capacitance.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return (0.5 * (charge ** 2)) / capacitance
+    end
   end
 
   # Calculates the total capacitance of capacitors in series.
@@ -172,7 +197,7 @@ module Joules
   def capacitance_in_parallel(capacitances)
     total_capacitance = 0
     capacitances.each do |capacitance|
-  	  total_capacitance += capacitance
+      total_capacitance += capacitance
     end
     return total_capacitance.to_f
   end
@@ -184,11 +209,16 @@ module Joules
   #   charge != 0; charge is in coulombs
   # @return [Float]
   #   return value is in volts
+  # @raise [ZeroDivisionError] if charge = 0
   # @example
   #   Joules.voltage_v1(1.8, 0.6) #=> 3.0
   # @note There is one other method for calculating voltage.
   def voltage_v1(energy, charge)
-    return energy / charge.to_f
+    if charge.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return energy / charge.to_f
+    end
   end
 
   # Calculates the voltage given current and resistance.
@@ -240,11 +270,16 @@ module Joules
   #   resistance != 0; resistance is in ohms
   # @return [Float]
   #   return value is in watts
+  # @raise [ZeroDivisionError] if resistance = 0
   # @example
   #   Joules.power_v5(1.8, 3) #=> 1.08
   # @note There are four other methods for calculating power.
   def power_v5(voltage, resistance)
-    return (voltage ** 2.0) / resistance
+    if resistance.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return (voltage ** 2.0) / resistance
+    end
   end
 
   # Calculates the energy given voltage, current, and time.

data/lib/joules/energy_work_power.rb

@@ -3,7 +3,7 @@
 #
 # @description: Module for providing energy, work, and power formulas
 # @author: Elisha Lai
-# @version: 0.3.1 01/06/2015
+# @version: 0.3.2 03/06/2015
 #==============================================================================
 
 # Energy, work, and power module (energy_work_power.rb)
@@ -15,7 +15,7 @@ module Joules
   # @param mass [Int, Float]
   #   mass >= 0; mass is in kilograms
   # @param height [Int, Float]
-  #   height >= 0; height is in meters
+  #   height >= 0; height is in metres
   # @return [Float]
   #   return value >= 0; return value is in joules
   # @example
@@ -26,9 +26,9 @@ module Joules
 
   # Calculates the elastic potential energy given spring constant and extension.
   # @param spring_constant [Int, Float]
-  #   spring_constant >= 0; spring_constant is in newtons per meter
+  #   spring_constant >= 0; spring_constant is in newtons per metre
   # @param extension [Int, Float]
-  #   extension >= 0; extension is in meters
+  #   extension >= 0; extension is in metres
   # @return [Float]
   #   return value >= 0; return value is in joules
   # @example
@@ -41,12 +41,13 @@ module Joules
   # @param mass [Int, Float]
   #   mass >= 0; mass is in kilograms
   # @param velocity [Int, Float]
-  #   velocity is in meters per second
+  #   velocity is in metres per second
   # @return [Float]
   #   return value >= 0; return value is in joules
   # @example
-  #   Joules.kinetic_energy(500, 22) #=> 121000.0 
-  def kinetic_energy(mass, velocity)
+  #   Joules.kinetic_energy_v1(500, 22) #=> 121000.0
+  # @note There is one other method for calculating kinetic energy.
+  def kinetic_energy_v1(mass, velocity)
     return 0.5 * mass * (velocity ** 2)
   end
 
@@ -54,13 +55,15 @@ module Joules
   # @param force [Int, Float]
   #   force is in newtons
   # @param displacement [Int, Float]
-  #   displacement is in meters
+  #   displacement is in metres
+  # @param angle [Int, Float]
+  #   angle is in degrees
   # @return [Float]
   #   return value is in joules
   # @example
   #   Joules.work_done(40, 2.34) #=> 93.6
-  def work_done(force, displacement)
-    return force * displacement.to_f
+  def work_done(force, displacement, angle = 0)
+    return force * displacement.to_f * Math.cos(to_radians(angle))
   end
 
   # Calculates the power given work done and time.
@@ -70,11 +73,16 @@ module Joules
   #   time > 0; time is in seconds
   # @return [Float]
   #   return value is in watts
+  # @raise [ZeroDivisionError] if time = 0
   # @example
   #   Joules.power_v1(28, 7) #=> 4.0
   # @note There are four other methods for calculating power.
   def power_v1(work_done, time)
-    return work_done / time.to_f
+    if time.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return work_done / time.to_f
+    end
   end
 
   # Calculates the power given force and velocity.
@@ -98,10 +106,15 @@ module Joules
   #   energy_input > 0; energy_input is in joules
   # @return [Float]
   #   return value >= 0
+  # @raise [ZeroDivisionError] if energy_input = 0
   # @example
   #   Joules.energy_efficiency(16, 20) #=> 80.0 
   def energy_efficiency(useful_energy_output, energy_input)
-    return (useful_energy_output / energy_input.to_f) * 100
+    if energy_input.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return (useful_energy_output / energy_input.to_f) * 100
+    end
   end
 
   # Calculates the power efficiency given useful power output and power input.
@@ -111,10 +124,15 @@ module Joules
   #   power_input > 0; power_input is in watts
   # @return [Float]
   #   return value >= 0
+  # @raise [ZeroDivisionError] if power_input = 0
   # @example
   #   Joules.power_efficiency(26, 40) #=> 65.0
   def power_efficiency(useful_power_output, power_input)
-    return (useful_power_output / power_input.to_f) * 100
+    if power_input.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return (useful_power_output / power_input.to_f) * 100
+    end
   end
 
 end

data/lib/joules/forces.rb

@@ -3,7 +3,7 @@
 #
 # @description: Module for providing forces formulas
 # @author: Elisha Lai
-# @version: 0.3.1 01/06/2015
+# @version: 0.3.2 03/06/2015
 #==============================================================================
 
 # Forces module (forces.rb)
@@ -15,7 +15,7 @@ module Joules
   # @param mass [Int, Float]
   #   mass >= 0; mass is in kilograms
   # @param acceleration [Int, Float]
-  #   acceleration is in meters per second squared
+  #   acceleration is in metres per second squared
   # @return [Float]
   #   return value is in newtons
   # @example
@@ -27,9 +27,9 @@ module Joules
 
   # Calculates the force given spring constant and extension.
   # @param spring_constant [Int, Float]
-  #   spring_constant >= 0; spring_constant is in newtons per meter
+  #   spring_constant >= 0; spring_constant is in newtons per metre
   # @param extension [Int, Float]
-  #   extension >= 0; extension is in meters
+  #   extension >= 0; extension is in metres
   # @return [Float]
   #   return value >= 0; return value is in newtons
   # @example
@@ -41,27 +41,32 @@ module Joules
 
   # Calculates the force given initial velocity, final velocity, mass, and time.
   # @param initial_velocity [Int, Float]
-  #   initial_velocity is in meters per second
+  #   initial_velocity is in metres per second
   # @param final_velocity [Int, Float]
-  #   final_velocity is in meters per second
+  #   final_velocity is in metres per second
   # @param mass [Int, Float]
   #   mass >= 0; mass is in kilograms
   # @param time [Int, Float]
   #   time > 0; time is in seconds
   # @return [Float]
   #   return value is in newtons
+  # @raise [ZeroDivisionError] if time = 0
   # @example
   #   Joules.force_v3(20, 35, 50, 2.4) #=> 312.5
   # @note There are two other methods for calculating force.
   def force_v3(initial_velocity, final_velocity, mass, time)
-    return ((final_velocity - initial_velocity) * mass) / time.to_f
+    if time.zero?
+      raise ZeroDivisionError.new('divided by 0')
+    else
+      return ((final_velocity - initial_velocity) * mass) / time.to_f
+    end
   end
 
   # Calculates the moment given force and distance.
   # @param force [Int, Float]
   #   force is in newtons
   # @param distance [Int, Float]
-  #   distance >= 0; distance is in meters
+  #   distance >= 0; distance is in metres
   # @return [Float]
   #   return value is in newton metres
   # @example