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')
Additional Information on IDLUNIT
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