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³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

;How far is that in kilometers?

PRINT, distance.to('kilometers')

IDL prints:

2.91398E+011 kilometers

So, our spaceship travels 2.91x10¹¹ 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 as-is 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')  ; IDL displays 4 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$

; Add "shake" to the list of units.

IDLUNIT.AddUnit, 'shake', '10 nanoseconds', PLURAL='shakes', SYMBOL='sh'

; Now that we have added the unit, we can use it in IDLUNIT:

PRINT, IDLUNIT('2 shake -> picoseconds')

IDL displays:

20000 picoseconds

; Check to make sure the plural works:

PRINT, IDLUNIT('2 shakes -> picoseconds')

IDL displays:

20000 picoseconds

; Try it by using the symbol:

PRINT, IDLUNIT('2 sh -> picoseconds')

We can see that it works:

20000 picoseconds

 

; Use the TO method to convert:

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-)	Base-10	Symbol (case sensitive)
yotta	8	1024	Y
zetta	7	1021	Z
exa	6	1018	E
peta	5	1015	P
tera	4	1012	T
giga	3	109	G
mega	2	106	M
kilo	1	103	k
hecto	2/3	102	h
deca	1/3	101	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² grams = 1,000,000 grams
• 1 gigagram = 1000³ grams = 1,000,000,000 grams
• 1 kilobyte = 1024 bytes
• 1 megabyte = 1024² bytes = 1,048,576 bytes
• 1 gigabyte = 1024³ bytes = 1,073,741,824 bytes

Pre-Defined Units

IDL contains the following pre-defined 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

; Convert one mile to feet

PRINT, IDLUNIT('1 mile') ;1 mile

PRINT, IDLUNIT('1 mile -> feet') ;5280 feet

; Convert 2 square miles to acres

PRINT, IDLUNIT('2 miles^2 -> acres') ;1280 acres

; Convert 2 miles, squared, to acres. Note the difference

; between this and the previous example.

PRINT, IDLUNIT('(2 miles)^2 -> acres') ;2560 acres

; Perform basic arithmetic in the input expression

PRINT, IDLUNIT('(2 miles)^2 * 12 cm + 1000 gallons') ;1.2432 gigaliter

PRINT, IDLUNIT('3^2 amp seconds') ;9 coulomb

; Convert bits to gigabytes

PRINT, IDLUNIT('1.234e12 b to GB') ;143.657 GB

; Convert grams to nanograms

PRINT, IDLUNIT('3.14e-7 g to nanograms') ;314 nanograms

; How fast did the men's 100 m gold medalist run?

PRINT, IDLUNIT('100 m / 9.63s -> mph') ;23.2288 mph

; General example showing order of operations

PRINT, IDLUNIT('(2 m + 3 m) * 5 m') ;25 m^2

; About how many times does my heart beat in a year?

PRINT, IDLUNIT('(53 / 1 minute) * 1 year') ;2.78759E+007

; How many cubic feet of air are in the 3 km of space 

; above a 4 acre plot of land? Try it a couple of ways

; first without specifying the exponent on feet

PRINT, IDLUNIT('4 acres * 3 kilometers -> feet')

PRINT, IDLUNIT('4 acres * 3 kilometers -> feet^3')

; Demonstrate the QUANTITY and UNIT properties

testVal = IDLUNIT('3 gallons')

PRINT, testVal.UNIT ;gallons

PRINT, testVal.quantity ;3.0000000

Example 3

How fast did the Curiosity rover approach Mars?

init_speed = IDLUNIT('13000mph')

final_speed = IDLUNIT('0 mph')

                ; How long it took to come to a stop (the "Seven Minutes of Terror")

time  = IDLUNIT('7 minutes')

                   ; Arithmetic on IDLUNIT objects works, too

accel = (init_speed - final_speed) / time

 ; How fast was the Curiosity rover's descent?

PRINT, accel 

           ; How does that compare to standing on Earth?

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?

; Try 2 different ways to demonstrate order of operations

PRINT, IDLUNIT('10 miles^2 + 15 miles^2') ;25 miles^2

PRINT, IDLUNIT('(10 miles ^ 2) + (15 miles ^ 2)') ;25 miles^2

; How many acres is that?

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

; How many acres does she now have? Do some math on these

; IDLUNIT objects

total = acres + acres2

PRINT, total

Version History

---

8.3	Introduced
8.4.1	Added nautical_mile

See Also

---

Constant System Variables: !CONST