Routines (alphabetical) > Routines: I > IDLUNIT

# 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:

- 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 = 10002 grams = 1,000,000 grams
- 1 gigagram = 10003 grams = 1,000,000,000 grams
- 1 kilobyte = 1024 bytes
- 1 megabyte = 10242 bytes = 1,048,576 bytes
- 1 gigabyte = 10243 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