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')
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