An extension to handle quantities with units

Screenshot of a question with a quantities part, answered

The short story: We’ve written an extension to Numbas which adds a data type for handling quantities with associated units, and a custom part type which asks the student to enter a value with units.

The long story: Some of my colleagues in chemistry have recently started using Numbas, and one of the first things they wanted to do was ask students to specify units along with their answers. In the sciences, using the correct units is very important, while in pure maths we rarely trouble with such things.

Numbas has no built-in understanding of units, so we needed to add it in: working with units hadn’t been a priority for me until now, since most use of Numbas in Newcastle outside the main maths degree has been for stage 1 service courses or for statistics.

It’s a testament to the extensibility of Numbas that within an afternoon I got a proof of concept working. I found an existing JavaScript library, js-quantities, which handles parsing and manipulating quantities. I quickly wrapped that up in a Numbas extension, adding a ‘quantity’ JME data type. That allowed me to randomly generate quantities in question variables and display them to the student. From there, it didn’t take long to make a custom part type which asks the student to type a number along with units. I then spent some time over the next couple of weeks playing with it and thinking about how it would be used.

Here’s how it looks:

Screenshot of a variable definition involving a random length

Quantity variables are created and manipulated using a natural syntax

Settings for a quantity part

The “quantity with units” part type has several options, including the style of hint to show, and how to handle units that are different from those used in the expected answer.

Screenshot of a question with a quantities part, answered

The student enters their answer in a standard text box. The part will reject a quantity in incompatible units, and can optionally convert or reject units compatible with, but not exactly the same as, the expected answer.

Screenshot of an input box with hint "Give your answer in mol/dmĀ³"

You can tell the student which units to use, automatically detected from the correct answer.

The extension integrates completely with Numbas: you can use quantities like any other JME variable, so arithmetic, sorting, and substitution into question text or LaTeX expressions work as you’d expect. The extension handles compound units as a matter of course, and converting to different units is as easy as quantity as "kg/m^3". You can even substitute quantities into SVG diagrams, as demonstrated in the image above.

The code and documentation for the extension are on GitHub now, and it’s available to use on the Numbas editor at I’ve prepared a demo exam containing a few questions which demonstrate how to work with quantities, and show off a few of the possibilities.

To use the extension, tick the “Quantities” item in the question editor’s Extensions and Scripts tab, and add a “Quantity with units” part by clicking the “More part types” button when you add a new part, then searching for “quantity”.

Here are a few notes about using the extension, based on my experiments so far:

  • The numerical part is still a JavaScript number object, so beware of all the usual floating-point inaccuracies. The js-quantities code doesn’t do a great job of avoiding divisions when a more circuitous calculation would have been more accurate, so rounding errors can crop up even when you’re doing something as innocuous as converting km to mm. Numbas does a good job of hiding rounding errors, and the “quantity with units” part type allows some wiggle room, but be ready to use precround liberally when required. Arbitrary precision arithmetic has just climbed a long way up my to-do list.
  • Don’t generate scalars and add on units at the last minute. You really can generate an amount with units, and do arithmetic on it throughout the variable generation process. It’s nice to do something like the volume calculation above and see the right units pop out at the end!
  • The ‘as’ operator makes it easy to convert between units. You could generate a quantity in some base units, then randomly pick the units to show them to the student, or decide between mm, cm and m based on the order of magnitude.
  • It’s very easy to come up with a random length, say, that is the wrong order of magnitude for the units you’ve chosen. For example, one question produced a measurement of “0.0000001km”. I might add a “sensible_si_unit” function to pick the right units for a given quantity – that needs some thought!

I’m excited to see what can be done with this extension: it’s really very straightforward to use, and opens up a new world of topics for Numbas questions.