IDLUNIT
The IDLUNIT function allows you to perform basic dimensional analysis, conversions, and mathematical operations, all while factoring units. IDLUNIT is designed to be flexible, allowing you to evaluate simple mathematical expressions, or convert units. Results can be used in other IDL functions and programs.
Examples
Example 1
Approximately how many miles across is our galaxy, assuming its diameter is roughly 100,000 lightyears?
milkyway = IDLUNIT('100000 ly > miles')
PRINT, milkyway
IDL prints:
5.87861E+017 miles
Example 2
How far does a spaceship travel in 10 hours at warp 3 whilst trying to outrun an enemy fighter? Assume our Chief Engineer can keep the engines in one piece for that long, and warp for our spaceship is defined as:
v = w^{3}c
where v is velocity in m/s, w is the warp factor, and c is the speed of light in m/s.
velocity = IDLUNIT('3^3 * c')
time = IDLUNIT('10 hours')
distance = time * velocity
PRINT, distance
IDL prints:
291.398 terameter
PRINT, distance.to('kilometers')
IDL prints:
2.91398E+011 kilometers
So, our spaceship travels 2.91x10^{11} kilometers in 10 hours at warp 3.
For more examples using IDLUNIT, see Additional Examples near the end of this topic.
Syntax
Result = IDLUNIT(Expression [, SIMPLIFY=value] [, /DECOMPOSE])
Properties
<ANY UNIT>, QUANTITY, UNIT, TERMS
Methods
AddUnit
ListUnits
RemoveUnit
To
Return Value
IDLUNIT returns an object that can be used asis or assigned to a variable and used in further operations.
IDLUNIT determines the units of the Return Value based on:
 Explicit Conversion: if the input expression includes the conversion operators ' > ' or ' to ', IDLUNIT will automatically convert the Result to the target unit that you specify.
 Order of Units: The units that come first in the input string, Unit Expression, are retained as the default base output unit. In other words, if you ask IDLUNIT to evaluate '3 feet + 7 meters' the Result will be in feet unless you indicate otherwise.
 IDLUNIT objects are immutable  once created they can never be modified, only replaced with new values.
Arguments
Expression
A string containing an expression that you want IDLUNIT to evaluate. The expression can consist of any combination of numbers, units, and mathematical operators. Numbers may be entered in scientific notation using 'e' to denote the exponent. The input expression may also include an optional conversion operator followed by a unitless expression. The input expression is parsed, evaluated to a single quantity and a set of units, and then optionally converted or simplified.
IDLUNIT recognizes the following operators:
 addition: '+'
 subtraction, negation: ''
 division: '/'
 multiplication: '*'
 grouping: '(' and ')'
 conversion: '>' or 'to'
Additionally, white space between numbers and units implies multiplication.
Note: You can also use the TO method to convert an IDLUNIT object into different units.
Keywords
SIMPLIFY
Set this keyword to specify the method IDL should use to simplify the input expression:
Value

Description

Example

0

Do not simplify units

1 ft s / s > 1 ft s / s
1 m ft > 1 m ft
1 volt / amp > 1 volt / amp
1 furlong > 1 furlong

1

Cancel out dimensionally equivalent units only

1 ft s / s > 1 ft
1 m ft > 0.3048 m^2
1 volt / amp > 1 volt / amp
1 furlong > 1 furlong

2 (default)

Cancel terms then choose new unit, if shorter

1 ft s / s > 1 ft
1 m ft > 0.3048 m^2
1 volt / amp > 1 ohm
1 furlong > 1 furlong

3

Always choose new unit

1 ft s / s > 304.8 millimeter
1 m ft > 304800 millimeter^2
1 volt / amp > 1 ohm
1 furlong > 201.168 meter

DECOMPOSE
Setting this keyword prompts IDL to break down the result into one of the eight base SI units: meters, grams, seconds, amperes, Kelvins, moles, candela, and bits.
For example, 1 joule = 1000 meter^2 gram / second^2
Properties
<Any Unit> (static)
When called statically, you can use the property syntax to access any unit, as in the following examples:
four_weeks = 2 * IDLUNIT.fortnight
PRINT, four_weeks.TO('weeks')
PRINT, IDLUNIT('1 gram') * IDLUNIT.c^2
IDL displays:
8.98755E+013 joule
QUANTITY (Get Only)
Returns the numeric quantity of the resultant value from IDLUNIT, e.g., 3 for '3 gallons / min'
UNIT (Get Only)
Returns a string representing the units of the resulting value from IDLUNIT, e.g., 'gallons / min'
TERMS
A list of IDLUNITTERM structures that fully describe each of the unit terms.
Methods
AddUnit
The AddUnit static method adds a new unit to the list that IDLUNIT can recognize.
Syntax
IDLUNIT.AddUnit, name, value [, /BINARY] [, OFFSET=value]
[, PLURAL=string] [, /PREFER] [, /PREFIXABLE] [, SYMBOL=string]
Arguments
name
The full singular name of the new unit.
value
The value of the new unit. This can be any valid IDLUNIT expression string.
Keywords
BINARY
This keyword flags IDL that this unit uses kilo orders of magnitude of 1024 rather than 1000.
OFFSET
The new unit's offset from 'absolute zero'. For example, the offset for Degrees Celsius is 273.15.
PLURAL
The plural name for the unit, if any, so IDL can recognize it in expressions.
PREFER
Adds this unit to the 'preferred' unit list, from which IDL may select units to simplify expressions.
PREFIXABLE
This keyword flags IDL that it is appropriate to prepend this unit with SI prefixes ('milli', 'kilo', etc.) when necessary.
SYMBOL
The symbol or abbreviated name, if any, so IDL can recognize it in expressions.
Examples
PRINT, IDLUNIT('1 shake > nanoseconds')
Since "shake" is not a recognized unit, IDL returns:
% IDLUnit error: Unit "shake" not recognized.
% Execution halted at: $MAIN$
IDLUNIT.AddUnit, 'shake', '10 nanoseconds', PLURAL='shakes', SYMBOL='sh'
PRINT, IDLUNIT('2 shake > picoseconds')
IDL displays:
20000 picoseconds
PRINT, IDLUNIT('2 shakes > picoseconds')
IDL displays:
20000 picoseconds
PRINT, IDLUNIT('2 sh > picoseconds')
We can see that it works:
20000 picoseconds
PRINT, (2 * IDLUNIT.shake).TO('picoseconds')
IDL displays:
20000 picoseconds
ListUnits
The ListUnits static method returns a listing of the names of all units presently "known" by IDL.
Syntax
Result = IDLUnit.ListUnits()
RemoveUnit
This method removes a unit from the list that IDLUNIT can recognize.
Syntax
IDLUNIT.RemoveUnit, name
Arguments
name
The name of the unit you want to remove.
To
The To method converts an IDLUNIT value to new units as specified. This is functionally equivalent to using the conversion operator ('>') inside an IDLUNIT expression.
For example, these two commands:
speed = IDLUNIT('100 feet / second')
PRINT, speed.To('miles / hour')
Are equivalent to the following:
PRINT, IDLUNIT('100 feet / second > miles / hour')
Fundamental Units
The fundamental units that form the basis of processing within IDLUNIT are:
 meter (m)
 gram (g)
 second (s)
 ampere (A)
 Kelvin (K)
 mole (mol)
 candela (cd)
 bit (b)
Note: Processing within IDLUNIT requires that units be broken down into their most basic form. While kilogram is the SI standard unit for mass, it is a prefixed unit, therefore IDLUNIT uses the gram instead.
Available Unit Prefixes
IDLUNIT recognizes the following unit prefixes and prefix symbols:
Prefix

Order of Magnitude (kilo)

Base10

Symbol
(case sensitive)

yotta

8

10^{24}

Y

zetta

7

10^{21}

Z

exa

6

10^{18}

E

peta

5

10^{15}

P

tera

4

10^{12}

T

giga

3

10^{9}

G

mega

2

10^{6}

M

kilo

1

10^{3}

k

hecto

2/3

10^{2}

h

deca

1/3

10^{1}

da

deci

1/3

10^{1}

d

centi

2/3

10^{2}

c

milli

1

10^{3}

m

micro

2

10^{6}

u

nano

3

10^{9}

n

pico

4

10^{12}

p

femto

5

10^{15}

f

atto

6

10^{18}

a

zepto

7

10^{21}

z

yocto

8

10^{24}

y

Note: Symbols are case sensitive; prefixes are case insensitive.
Almost all units use 1000 as their kilo orders of magnitude. Some units, however, can be flagged as 'binary' and use 1024 instead. For example:
 1 kilogram = 1000 grams
 1 megagram = 1000^{2} grams = 1,000,000 grams
 1 gigagram = 1000^{3} grams = 1,000,000,000 grams
 1 kilobyte = 1024 bytes
 1 megabyte = 1024^{2} bytes = 1,048,576 bytes
 1 gigabyte = 1024^{3} bytes = 1,073,741,824 bytes
PreDefined Units
IDL contains the following predefined units. Use the name, the plural, or the symbol to reference the unit in your call to IDLUNIT. A dot in the Prefixes column indicates that you can prepend this unit with SI prefixes ('milli', 'kilo', etc.).
Note: Symbols for the units are case sensitive; names and plurals are case insensitive. Underscores are required in the names and plurals as indicated.
Length
Name

Plural

Symbol

Prefixes

meter

meters

m

•

micron

microns



inch

inches

in

•

point

points

pt


pica

picas



foot

feet

ft


yard

yards

yd


mile

miles

mi


link

links



rod

rods



chain

chains



furlong

furlongs



league

leagues



fathom

fathoms



cable

cables



nautical_mile

nautical_miles

nmi 




Area
Name

Plural

Symbol

Prefixes

acre

acres

ac


hectare

hectares

ha


Volume
Name

Plural

Symbol

Prefixes

liter

liters

l

•

fluid_ounce

fluid_ounces

floz


minim

minims



fluid_dram

fluid_drams



teaspoon

teaspoons

tsp


tablespoon

tablespoons

tbsp


jigger

jiggers



gill

gills



cup

cups



pint

pints



quart

quarts



gallon

gallons

gal


barrel

barrels



oil_barrel

oil_barrels



hogshead

hogsheads



dash

dashes



pinch

pinches



smidgen

smidgens



Mass
Name

Plural

Symbol

Prefixes

gram

grams

g

•

pound

pounds

lbs


grain

grains



dram

drams



ounce

ounces

oz


hundredweight

hundredweights



ton

tons



Time
Name

Plural

Symbol

Prefixes

hertz


Hz

•

second

seconds

s

•

minute

minutes

min


hour

hours



day

days



week

weeks



fortnight

fortnights



year

years



Velocity
Name

Plural

Symbol

Prefixes

mph




kph




fps




Acceleration
Name

Plural

Symbol

Prefixes

gravity

gravities


•

galileo

galileos

Gal


Force
Name

Plural

Symbol

Prefixes

newton

newtons

N

•

pound_force

pounds_force

lbf


dyne


dyn


Pressure
Name

Plural

Symbol

Prefixes

pascal

pascals

Pa

•

psi


psi


bar




atmosphere

atmospheres

atm


torr




Data
Name

Plural

Symbol

Prefixes

bit

bits

b

•

byte

bytes

B

•

Electrical
Name

Plural

Symbol

Prefixes

ampere (aka amp)

amperes

A

•

amp (aka ampere)

amps


•

volt

volts

V

•

ohm

ohms


•

coulomb

coulombs

C

•

farad

farads

F

•

watt

watts

W

•

Energy
Name

Plural

Symbol

Prefixes

joule

joules

J


erg

ergs



calorie

calories

cal


british_thermal_unit


BTU


Temperature
Name

Plural

Symbol

Prefixes

kelvin


K

•

celsius


deg_C


fahrenheit


deg_F


Misc
Name

Plural

Symbol

Prefixes

candela

candelas

cd

•

mole

moles

mol

•

jansky

janskies

Jy


Constants
For additional information on these constants, please see !CONST in the Constant System Variables help topic.
Name

Plural

Symbol

Prefixes

astronomical_unit

astronomical_units

au


speed_of_light


c


elementary_charge


e


electric_permittivity


eps0


faraday

faradays



gravitation_constant


G


planck_constant


h


lightyear

lightyears

ly


earth_mass


M_earth


sun_mass


M_sun


electron_mass


me


neutron_mass


mn


proton_mass


mp


magnetic_permeability


mu0


Loschmidt_number


n0


avogadro


Na


parsec

parsecs

pc


gas_constant




earth_radius


R_earth


electron_radius


re


rydberg




standard_temperature


T0


atomic_mass




molar_volume




sigma




Operators
Calls to IDLUNIT allow the use of a subset of IDL's mathematical operators: addition, subtraction, multiplication, division, exponents, unit conversion, parentheses, and negation. However, the following functionality is not available inside a call to IDLUNIT:
 more complex mathematical operations (increment, decrement, MOD, etc.)
 relational and logical operators
 variables
 matrices
 flow control
Even though the IDLUNIT functionality is limited, its result is an object that you can use within IDL just as you would any other data. You can store the result of an IDLUNIT call in a variable, print it, or use it in math operations. See the Examples for more ways to use the results of IDLUNIT.
Order of Operations
The order of operations within an IDLUNIT call is slightly different from IDL's standard order of operations due to the introduction of implied multiplication and unit conversion. IDLUNIT's order of operations is:
Order 
Operator 
Symbol 
Example 
1 
Parenthesis 
() 
(2 m + 3 m) * 4 m 
2 
Exponent 
^ 
2 m ^ 3 
3 
Implied Multiplication 
space between numbers and units 
7 meters 
4 
Negation 
 
7 
5 
Multiplication and Division 
*, / 
2 m * 3 or 3 m / 3 
6 
Addition and Subtraction 
+,  
4 m + 5 m or 5 m  4 m 
7 
Unit Conversion 
' > ',
' to '

'7 meters to inches' or '7 meters > inches' 
Unit Conversion
IDLUNIT allows you to explicitly convert a result into a specified "target" unit, thus overriding the default presentation of units in the Result. You can explicitly convert units in one of two ways, either inside a call to IDLUNIT using conversion operators, or by using the IDLUNIT::To method:
Conversion Operators: " > " or " to " within an IDLUNIT call. As an example,
'4 feet * 3 meters > inches^2'
and
'4 feet * 3 meters to inches^2'
both tell IDLUNIT to multiply 4 feet by 3 meters and display the result in terms of square inches rather than feet (the default in this case because "feet" is the first unit in the expression).
Note: You can specify the exponent on the target unit (e.g., 'meters^3' for cubic meters) or explicitly state more complex units such as 'meters/second' or 'kg/m^3'. If you do not explicitly state these more complex target units, IDLUNIT will attempt to present the "best" output units based on a combination of the input string and unit factoring.
See also: IDLUNIT::To
Additional Examples
General Examples
PRINT, IDLUNIT('1 mile')
PRINT, IDLUNIT('1 mile > feet')
PRINT, IDLUNIT('2 miles^2 > acres')
PRINT, IDLUNIT('(2 miles)^2 > acres')
PRINT, IDLUNIT('(2 miles)^2 * 12 cm + 1000 gallons')
PRINT, IDLUNIT('3^2 amp seconds')
PRINT, IDLUNIT('1.234e12 b to GB')
PRINT, IDLUNIT('3.14e7 g to nanograms')
PRINT, IDLUNIT('100 m / 9.63s > mph')
PRINT, IDLUNIT('(2 m + 3 m) * 5 m')
PRINT, IDLUNIT('(53 / 1 minute) * 1 year')
PRINT, IDLUNIT('4 acres * 3 kilometers > feet')
PRINT, IDLUNIT('4 acres * 3 kilometers > feet^3')
testVal = IDLUNIT('3 gallons')
PRINT, testVal.UNIT
PRINT, testVal.quantity
Example 3
How fast did the Curiosity rover approach Mars?
init_speed = IDLUNIT('13000mph')
final_speed = IDLUNIT('0 mph')
time = IDLUNIT('7 minutes')
accel = (init_speed  final_speed) / time
PRINT, accel
PRINT, accel.TO('gravities')
Example 4
A land baroness owns 10 square miles of Montana rangeland and purchases an additional 15. How many square miles does she have?
PRINT, IDLUNIT('10 miles^2 + 15 miles^2')
PRINT, IDLUNIT('(10 miles ^ 2) + (15 miles ^ 2)')
acres = IDLUNIT('(10 miles ^ 2) + (15 miles ^ 2) to acres')
PRINT, acres
Our land baroness buys more parcels, how many acres does she own now?
acres2 = IDLUNIT('(20 miles ^ 2) + (25 miles ^ 2) to acres')
total = acres + acres2
PRINT, total
Version History
8.3

Introduced

8.4.1

Added nautical_mile

See Also
Constant System Variables: !CONST