.

September 19, 2006

ruby-units

In scientific (and non-scientific) programming one frequently needs to be able to manipulate units such as ‘10 mm’, ‘6 gal’, or ‘3 weeks’. The traditional way to handle units in programming is to simply save the scalar part of the unit (i.e., the 10 from ‘10 mm’), and then make sure you programmatically convert the unit whenever necessary. Needless to say, this is error prone and it constrains the user to only being able to enter known unit types.

Ruby has a few libraries (notably, Facets) available that handle unit conversions in one form or another. However, most of these systems don’t quite meet my somewhat demanding and arbitrary requirements, so I set out to write a new one.

Installation

You can get ‘ruby-units’ using

gem install ruby-units

Usage

To use this gem, you need to do the standard

  1. require ‘rubygems’
  2. require ‘ruby-units’

Creating a Unit object

Because I use a lot of units in my work, and I’m lazy, there are several different ways to create a new ‘Unit’ object.

  1. unit = Unit.new(”1 mm”)
  2. unit = Unit(”1 mm”)
  3. unit = U(”1 mm”)
  4. unit = “1 mm”.to_unit
  5. unit = “1 mm”.unit
  6. unit = “1 mm”.u
  7. unit = “mm”.unit (yields ‘1 mm’)

Of these, I use #5 the most since it is reasonably terse without becoming obscure.
You can also create Unit objects from Numerics, Arrays, and Time objects. Numerics just become unitless Unit objects, Arrays are interpreted as [scalar, numerator, denominator], and Time objects are converted into a number of seconds.

Unit objects can be serialized through YAML using ‘unit.to_yaml’, which facilitates them being stored in database columns using Rails’ :serialize functionality.

Unit strings generally consist of text in the following format:

  1. R = "8.31451 kJ/mol*degK".unit
  2. a = "9.8 m/s^2".unit

Since Units are constructed from strings, it is easy to have a user specify them in input fields. Because the format is fairly standard, there should not be too many problems with misinterpreted units.

A couple of points:

  1. only one ‘/’ per unit. No ‘m/s/s’
  2. everything after the ‘/’ is in the denominator
  3. you can use negative exponents (’9.8 m*s^-2′)
  4. use either a space or a ‘*’ to separate units (’9.8 ms^-2′ == ‘9.8 1/ms^2′)
  5. ruby-units understands all SI prefixes, and a few others as well

Unit Compatibility

Sometimes it is helpful to know if two units are ‘compatible’. Compatible units can be converted into each other, so ‘feet’ and ‘meters’ are compatbile, but ‘feet’ and ‘liters’ are not.

  1. unit1= ‘1 feet’.unit
  2. unit2 = ‘1 meter’.unit
  3. unit3 = ‘1 liter’.unit
  4.  
  5. unit1 =~ unit2  #=>true
  6. unit1 =~ unit3  #=>false
  7.  
  8. unit1.compatible? unit2  #=> true
  9. unit1.compatible_with? unit3  #=>false

Unit Conversion

Units can be converted to each other so long as they are ‘compatible’. Ruby-units will throw an exception if units need to be compatible, but aren’t, so be sure to trap those exceptions when malformed input is possible.

Explicit Conversion

Explicit unit conversion occurs when the user asks for it. There are a couple of ways to force conversion to a particular unit.

  1. unit = "1 mm".unit
  2. unit >> "ft"
  3. unit.to("inches")
  4. unit2.to(unit1)     # converts unit2 to same units as unit1

Implicit Conversion

There are times when unit conversions are implied or assumed for simplicity. For example, when adding two units, the gem will convert the second unit to the same base units as the first prior to doing the math.

  1. unit1 = "1 meter".unit
  2. unit2 = "50 cm".unit
  3. result = unit1 + unit2 #=> 1.5 m

Unit Math

Unit objects come in really handy when doing complex math calculations:

  1. pr = "1 atm".unit
  2. n = "1 mol".unit
  3. R = "8.3144 J/mol*degK".unit
  4. T = "0 tempC".unit
  5. v = (n*R*T)/pr   # ideal gas law
  6. p v.to_s("l")  #=> 22.4 l

You can add, multiply, subtract, and divide units as you can with any Numeric class. You can also exponentiate or root them, although I restrict roots to integer values, since ‘m^0.5′ doesn’t really make any sense.

As an added bonus, all Trig functions (sin, cos, tan, sinh, …) can accept units that are compatible with radians. The values will be converted to radians before returning the result. So you can do this..

  1. Math.sin("90 deg".unit) #=> 1.0

Temperatures

Note that we specified the temperature in this equation as a ‘tempC’. Specifying a temperature will convert that unit into the equivalent number of degrees kelvin. So in this case, “0 tempC”.unit => 273.15 degK.

This is necessary to make the calculations work out right. Most times unit conversions are done by just adjusting the size of the units, but temperatures require you to also specify the zero point on the scale.

You can convert ‘degree’ units (like ‘degC’, ‘degF’, ‘degR’, or ‘degK’) to a temperature this way…

temp = ‘0 degC’.unit.to(’tempK’)

This really only makes sense when the value represents the degrees between absolute zero and the point of interest. Only the user knows when that is the case, so use it carefully.

Time and Date Math

Ruby-units understands a wide range of time units, and can convert back and forth between them with ease. Nothing new there.

However, ruby-units can add and subtract time units from Date, DateTime, and Time objects. Throw in a few rails-esque helpers and you can write code like this…

  1. one_hour_from_now = "1 h".from_now
  2. in_five_minutes = Time.in("5 min")
  3. an_hour_ago = "1 h".ago
  4. next_week = Time.now + "1 week".unit
  5. waiting_for = "min".until(one_hour_from_now)
  6. days_to_christmas = "days".until("12/25/06")
  7. age = "years".since("4/24/69")

Formatting Output

You can format the output of a Unit object by using the “.to_s” function and string format specifiers…

  1. length = "1 mm".unit
  2. length.to_s("%0.2f")  #=> "1.00 mm"
  3. height = "6 ft 4 in".unit.to_s(:ft)  #=> 6′4"
  4. weight = "8.25 lbs".unit.to_s(:lbs) #=> 8 lbs, 4 oz
  5. time = "1.5 h".unit.to_s("%H:%M") #=> 1:30

Miscellaneous Stuff

You can create ranges of units, so long as they have scalar integers.

  1. ( U("1 mm") .. U("5 mm") ).map  #=>[ 1 mm, 2 mm, 3 mm, 4 mm, 5mm]

If a unit is ‘unitless?’ then it can be converted back to other types of Numerics.

Note that ‘Unit’ objects are pretty slow compared to more common ones like Integers and Floats, so if performance is a big issue, you might want to consider using these sparingly.

Defining new units

You can define custom units by adding a code block like this..

  1. class Unit < Numeric
  2.   @@USER_DEFINITIONS =
  3.     {‘<inchworm>’ =>  [%w{inworm inchworm}, 0.0254, :length, %w{<meter>} ],
  4.      ’<cell>’ => [%w{cells cell}, 1, :counting, %w{<each>}],
  5.      ’<habenero>’   => [%{degH}, 100, :temperature, %w{<celcius>}]}
  6.   Unit.setup
  7. end

The format for the array is [%w{primary_name synonyms}, conversion_factor, unit_type, %w{}]

Useful References

Wikipedia: Units of Measurement

* Filed by Kevin Olbrich at 3:23 pm under Ruby, gems, ruby-units
* 4 Comments

June 12, 2006

Rails Testing Strategies: Valid and Invalid Data

Consider this test…

  1. def test_create
  2.   @item = Item.new
  3.   assert_valid @item
  4. end

Can you tell what the expected result of this test is?

It turns out that you can’t tell from reading this test if it will pass or fail without knowing if ‘Item.new’ returns a valid or invalid object. If ‘Item’ has a ‘validates_presence_of’ statement in there, this new item will be invalid and the test will fail. In addition, this test is ‘fragile’, subtle changes to the model definition can make the result of this test change. This isn’t such a big deal if all you are doing is testing to see if an object is valid or not, but if you are writing a more involved test that depends on this assumption then you might be in trouble.

Currently the only way to ensure that your test data is valid is to add an assertion to each test making the appropriate test. This isn’t very DRY.

One trick that I use to avoid repeating myself a lot in tests is to define a mock object like this..(putting this in a mock object keeps these methods out of production mode).

  1. # mocks/test/item.rb
  2. require ‘models/item’
  3.  
  4. class Item
  5.   #this assumes that an empty object is invalid
  6.   #modify this as needed
  7.   def self.new_invalid
  8.     Item.new
  9.   end
  10.  
  11.   def self.new_valid
  12.     item = self.new_invalid
  13.     item.name = "new valid item"
  14.     # add any additional statements
  15.     # required to make the item valid
  16.   end
  17. end

Then in my tests I add…

  1. def test_valid
  2.   assert_valid Item.new_valid
  3. end
  4.  
  5. def test_invalid
  6.   assert !Item.new_invalid.valid?, "Item not invalid"
  7. end
  8.  
  9. def test_save_invalid
  10.   @invalid_item = Item.new_invalid
  11.   assert !@invalid_item.save, "Saved invalid item"
  12. end

This way I am guaranteed to get a valid or invalid item when I need one. in addition, if the definition of valid or invalid changes sufficiently the ‘test_valid’ and ‘test_invalid’ tests will fail, warning me that my assumptions in the rest of the tests are incorrect.

One problem with this approach is if your tests care about HOW the object is invalid. In that case, you might need additional methods like ‘new_with_invalid_name’.

* Filed by Kevin Olbrich at 1:36 pm under Ruby on Rails, testing
* 3 Comments

Rails Testing Strategies: Positive and Negative Controls

Testing your rails application can be a great way to make your application robust. Proper testing aids in debugging, and can alert you when some minor change you made breaks something horribly. Rails has some nice testing features ‘baked-in’, but the best advice I have seen so far regarding which actual tests to run is … ‘it depends’.

Needless to say, that isn’t very practical advice.

Over the course of developing my own rails application, I have developed a list of ‘tests’ that I like to run on my models and controllers. This article will discuss some of the strategic design of tests, but won’t cover how to implement them (well, not much anyway).

Positive Controls

Tests should be designed with both ‘positive’ and ‘negative’ controls in mind. A positive control is a test or assertion that succeeds when you expect it to, and likewise a negative control fails when you expect it to. For example, if you create and save an object using predefined good data, an appropriate positive control could be…

  1. def test_create
  2.   num_items = Item.count
  3.   @item = Item.new
  4.   assert @item.save, "Item not saved"
  5.   assert_valid @item  # a positive control
  6.   assert_equal num_items + 1, Item.count  #another positive control
  7. end

In this case, we just check to make sure that the object is valid and that the number of them in the database has increased by one. These types of tests don’t really tell you much. The only time these types of tests fail is when something is seriously wrong with your database server, your ruby install, or your rails install. The only other time this type of test will fail is if you change the definition of the ‘Item’ model so that creating one using the ‘new’ method results in an invalid object (more on that later). The problem with positive controls is that when they pass, all they tell you is that nothing in the test caused an assertion to fail. This could mean that everything is hunky-dory, or it could mean that your assertions are not working as expected.

Passing the test doesn’t mean much if the test itself can’t detect a failure. Our test would pass just fine, even if the object model should really have a ‘validates_presence_of :name’ specified. It’s also easy to see that if we write a test like this…

  1. def test_name
  2.   @object = Object.new(:name=>’test name’)
  3.   @object.save
  4.   assert_valid @object
  5.   assert_equal @object.name, ‘test name’
  6. end

This test will still pass, even if the validation is not specified. Still, it’s nice to know that things work as expected.

Negative Controls

Negative controls are really much more handy. A Negative control is a test that is designed to detect when things fail.
If we write another test for our ‘item’

  1. class Item < ActiveRecord::Base
  2.   validates_presence_of :name
  3. end
  4.  
  5. def test_valid
  6.   @item = Item.new
  7.   @item.name = "test item"
  8.   assert_valid @item
  9. end
  10.  
  11. def test_invalid
  12.   @item = Item.new
  13.   assert !@item.valid?, "Object is not invalid"
  14. end

If ‘test_invalid’ passes, then you can be confident that your ‘validates_presence_of’ is working. If it had been commented out during a bug fix and never replaced, this test would fail, while ‘test_valid’ would still happily report a success.

The same approach should be used when testing model methods. At least one test for each type of expected output, and one for each possible failure mode. Then make sure that the negative controls are in place so that they will pass when the model is fed corrupt data.

The bottom line… tests should be written to pass when you pass valid data, but they should also be written to pass when you pass missing, corrupt, or extra data. The failure modes are the most useful during development since they will point out places where bugs and security holes may creep into your application.

* Filed by Kevin Olbrich at 1:36 pm under Ruby on Rails, testing
* 5 Comments

« Previous Page — Next Page »