Welcome to the L3 Harris Geospatial documentation center. Here you will find reference guides and help documents.
﻿

### 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])

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

• 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

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

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

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