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 = w3c

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.91x1011 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:

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:

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:

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:

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:

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