unitConvert

Convert units to other units of measurement

Syntax

convertedExpr = unitConvert(expr,units)

convertedExpr = unitConvert(expr,unitSystem)

convertedExpr = unitConvert(expr,unitSystem,unitMode)

convertedExpr = unitConvert(___,Temperature=tempMode)

Description

convertedExpr = unitConvert(expr,units) converts symbolic units in the input expression to the specified symbolic units. If the conversion is not possible, unitConvert returns the input expression without converting it.

convertedExpr = unitConvert(expr,unitSystem) converts symbolic units in the input expression to the base units of the specified unit system.

You can specify unitSystem as one of these predefined unit systems: "SI", "CGS", "US", "GU", "ESU", or "EMU". Alternatively, you can specify a custom unit system defined by using the newUnitSystem function.

convertedExpr = unitConvert(expr,unitSystem,unitMode) specifies whether to use the base units or derived units of the specified unit system by specifying unitMode as "base" or "derived". If you convert to the "SI" unit system, you can also specify unitMode as "constants" to convert the units in the input expression to the seven SI-defining constants.

convertedExpr = unitConvert(___,Temperature=tempMode) specifies whether temperatures in the input expression represent absolute temperatures or temperature differences. Specify tempMode as "absolute" or "difference" after any of the input argument combinations in the previous syntaxes. By default, temperatures are assumed to represent differences during conversion.

Examples

Convert Between Units

Convert 5 centimeters to inches. Because the calculation is symbolic, unitConvert returns a symbolic fractional result.

u = symunit;
length = unitConvert(5*u.cm,u.in)

length = 
$$\frac{250}{127}\hspace{0.17em}\mathrm{in}\mathrm{"inch\; -\; a\; physical\; unit\; of\; length."}$$

Convert length to its numeric value in double precision by separating the value from the units using separateUnits and converting the value using double. Alternatively, keep the units by using vpa.

lengthDouble = double(separateUnits(length))

lengthDouble = 
1.9685

lengthVpa = vpa(length)

lengthVpa = $$1.968503937007874015748031496063\hspace{0.17em}\mathrm{in}\mathrm{"inch\; -\; a\; physical\; unit\; of\; length."}$$

Calculate the force required to accelerate 2 kg by 5 m/s². The result is not automatically converted to newtons.

m = 2*u.kg;
a = 5*u.m/u.s^2;
F = m*a

F = 
$$10\hspace{0.17em}\frac{\mathrm{kg}\mathrm{"kilogram\; -\; a\; physical\; unit\; of\; mass."}\hspace{0.17em}\mathrm{m}\mathrm{"meter\; -\; a\; physical\; unit\; of\; length."}}{{\mathrm{s}\mathrm{"second\; -\; a\; physical\; unit\; of\; time."}}^2}$$

Convert F to newtons by using unitConvert.

F = unitConvert(F,u.N)

F = $$10\hspace{0.17em}\mathrm{N}\mathrm{"newton\; -\; a\; physical\; unit\; of\; force."}$$

For more information, see Unit Conversions and Unit Systems.

Specify Compound Unit for Conversion

Convert 5 kilometers per hour to meters per second by specifying meters per second as a compound unit.

u = symunit;
v = unitConvert(5*u.km/u.hr,u.m/u.s)

v = 
$$\frac{25}{18}\hspace{0.17em}\frac{\mathrm{m}\mathrm{"meter\; -\; a\; physical\; unit\; of\; length."}}{\mathrm{s}\mathrm{"second\; -\; a\; physical\; unit\; of\; time."}}$$

Specify Multiple Units for Conversion

Specify multiple units for conversion by specifying the second argument as a vector of units. This syntax allows you to specify the target units for each dimension of the input expression.

Convert 5 kilometers per hour to centimeters per minute.

u = symunit;
v = 5*u.km/u.hr;
units = [u.cm u.min];
vConverted = unitConvert(v,units)

vConverted = 
$$\frac{25000}{3}\hspace{0.17em}\frac{\mathrm{cm}\mathrm{"centimeter\; -\; a\; physical\; unit\; of\; length."}}{\min \mathrm{"minute\; -\; a\; physical\; unit\; of\; time."}}$$

Perform Element-Wise Conversion

Create a symbolic vector for several measurements with multiple units.

syms x y
u = symunit;
v = 5*u.km/u.hr + x*u.cm/u.min;
measurements = [v; y*u.lb; 5*u.ft]

measurements = 
$$\left(\begin{array}{c}5\hspace{0.17em}\frac{\mathrm{km}\mathrm{"kilometer\; -\; a\; physical\; unit\; of\; length."}}{\mathrm{h}\mathrm{"hour\; -\; a\; physical\; unit\; of\; time."}}+x\hspace{0.17em}\frac{\mathrm{cm}\mathrm{"centimeter\; -\; a\; physical\; unit\; of\; length."}}{\min \mathrm{"minute\; -\; a\; physical\; unit\; of\; time."}}\\ y\hspace{0.17em}\mathrm{lbm}\mathrm{"pound\; mass\; -\; a\; physical\; unit\; of\; mass."}\\ 5\hspace{0.17em}\mathrm{ft}\mathrm{"foot\; -\; a\; physical\; unit\; of\; length."}\end{array}\right)$$

To convert the units in each element of this vector, you can use the arrayfun function and specify the target units as a vector, with each element corresponding to each measurement. For example, convert the mixed units of kilometers per hour and centimeters per minute in the first element to meters per second, convert the unit of pounds in the second element to grams, and convert the unit of feet in the third element to inches.

targetUnits = [u.m/u.s; u.g; u.in];
convertedMeas = arrayfun(@(vals,units) ...
    unitConvert(vals,units),measurements,targetUnits)

convertedMeas = 
$$\left(\begin{array}{c}\frac{25}{18}\hspace{0.17em}\frac{\mathrm{m}\mathrm{"meter\; -\; a\; physical\; unit\; of\; length."}}{\mathrm{s}\mathrm{"second\; -\; a\; physical\; unit\; of\; time."}}+\frac{x}{6000}\hspace{0.17em}\frac{\mathrm{m}\mathrm{"meter\; -\; a\; physical\; unit\; of\; length."}}{\mathrm{s}\mathrm{"second\; -\; a\; physical\; unit\; of\; time."}}\\ \frac{45359237\hspace{0.17em}y}{100000}\hspace{0.17em}\mathrm{g}\mathrm{"gram\; -\; a\; physical\; unit\; of\; mass."}\\ 60\hspace{0.17em}\mathrm{in}\mathrm{"inch\; -\; a\; physical\; unit\; of\; length."}\end{array}\right)$$

Convert Units to Conventional Unit System

Instead of converting to specific units, you can convert the units in an input expression to the base units or derived units of another conventional unit system, such as SI, CGS, US, GU, ESU, or EMU. You can also convert the input units to the seven defining constants of the SI unit system.

Convert 5 meters to the base units of the US unit system. unitConvert returns the result in feet.

u = symunit;
length = 5*u.m

length = $$5\hspace{0.17em}\mathrm{m}\mathrm{"meter\; -\; a\; physical\; unit\; of\; length."}$$

lengthInUS = unitConvert(length,"US")

lengthInUS = 
$$\frac{6250}{381}\hspace{0.17em}\mathrm{ft}\mathrm{"foot\; -\; a\; physical\; unit\; of\; length."}$$

If you specify the new unit system as "SI", you can convert the input to the seven SI-defining constants. For example, convert 5 meters to the SI-defining constants. Here, the length is expressed in terms of the speed of light in vacuum and the caesium hyperfine frequency.

lengthInSIConst = unitConvert(length,"SI","constants")

lengthInSIConst = 
$$\frac{3283082775}{21413747}\hspace{0.17em}\frac{{\mathrm{c}}_{\mathrm{0}}\mathrm{"speed\; of\; light\; in\; vacuum\; -\; a\; physical\; unit\; of\; velocity."}}{{\mathrm{\Delta \nu }}_{\mathrm{Cs}}\mathrm{"caesium\; hyperfine\; transition\; frequency\; -\; a\; physical\; unit\; of\; frequency."}}$$

Next, convert 10 newtons to derived units in CGS by specifying the unit mode as "derived". The result is in dynes. Repeat the conversion without the unit mode "derived" to get a result in the base units.

F = 10*u.N;
FInCGSDerived = unitConvert(F,"CGS","derived")

FInCGSDerived = $$1000000\hspace{0.17em}\mathrm{dyn}\mathrm{"dyne\; -\; a\; physical\; unit\; of\; force."}$$

FInCGSBase = unitConvert(F,"CGS")

FInCGSBase = 
$$1000000\hspace{0.17em}\frac{\mathrm{cm}\mathrm{"centimeter\; -\; a\; physical\; unit\; of\; length."}\hspace{0.17em}\mathrm{g}\mathrm{"gram\; -\; a\; physical\; unit\; of\; mass."}}{{\mathrm{s}\mathrm{"second\; -\; a\; physical\; unit\; of\; time."}}^2}$$

Convert Units to Custom Unit System

Define a custom unit system for atomic units (au) to use for unit conversions. First, define the base units based on this table.

Dimension	Unit	Implementation
Mass	Electron rest mass $m_e$	u.m_e
Electric charge	Electron charge $e$	u.e
Length	Bohr radius $a_0$	u.a_0
Time	Reduced Planck constant $\hslash$ divided by Hartree energy $E_h$	Define using newUnit

u = symunit;
newUnit("t_au",u.h_bar/u.E_h);
baseCustom = [u.m_e u.e u.a_0 u.t_au]

baseCustom = $$\left(\begin{array}{cccc}{\mathrm{m}}_{\mathrm{e}}\mathrm{"electron\; mass\; -\; a\; physical\; unit\; of\; mass."}& \mathrm{e}\mathrm{"elementary\; charge\; -\; a\; physical\; unit\; of\; electric\; charge."}& {\mathrm{a}}_{\mathrm{0}}\mathrm{"Bohr\; radius\; -\; a\; physical\; unit\; of\; length."}& {\mathrm{t}}_{\mathrm{au}}\mathrm{"t\_au\; -\; a\; physical\; unit\; of\; time."}\end{array}\right)$$

Next, define the derived units based on this table.

Dimension	Unit	Implementation
Angular momentum	Reduced Planck constant $\hslash$	u.h_bar
Energy	Hartree energy $E_h$	u.E_h
Electric dipole moment	Electron charge $e$ multiplied by Bohr radius $a_0$	Define using newUnit
Magnetic dipole moment	Bohr magneton	Define using newUnit
Electric potential	Hartree energy $E_h$ divided by electron charge $e$	Define using newUnit

newUnit("p_au",u.e*u.a_0);
newUnit("m_au",u.e*u.h_bar/(2*u.me));
newUnit("V_au",u.E_h/u.e);
derivedCustom = [u.h_bar u.E_h u.p_au u.m_au u.V_au]

derivedCustom = $$\left(\begin{array}{ccccc}\mathrm{\hslash }\mathrm{"reduced\; Planck\; constant\; -\; a\; physical\; unit\; of\; angular\; momentum."}& {\mathrm{E}}_{\mathrm{h}}\mathrm{"Hartree\; energy\; -\; a\; physical\; unit\; of\; energy."}& {\mathrm{p}}_{\mathrm{au}}\mathrm{"p\_au\; -\; a\; physical\; unit."}& {\mathrm{m}}_{\mathrm{au}}\mathrm{"m\_au\; -\; a\; physical\; unit\; of\; magnetic\; moment."}& {\mathrm{V}}_{\mathrm{au}}\mathrm{"V\_au\; -\; a\; physical\; unit\; of\; electric\; potential\; or\; electromotive\; force."}\end{array}\right)$$

Finally, define the custom unit system for the atomic units.

newUnitSystem("atomicUnits",baseCustom,derivedCustom)

ans = 
"atomicUnits"

Now, convert the properties of a proton to the base units of the atomic units.

proton = [1.672621925e-27*u.kg;       % mass
          1.602176634e-19*u.C;        % charge
          5.4e-24*u.e*u.cm;           % electric dipole moment
          1.410606795e-26*u.m^2*u.A;  % magnetic dipole moment
          0.5*u.h_bar                 % spin angular momentum
         ];
proton = unitConvert(proton,"atomicUnits","base")

proton = 
$$\left(\begin{array}{c}1836.1526748780789486223496324943\hspace{0.17em}{\mathrm{m}}_{\mathrm{e}}\mathrm{"electron\; mass\; -\; a\; physical\; unit\; of\; mass."}\\ 0.99999999999999993368785457223212\hspace{0.17em}\mathrm{e}\mathrm{"elementary\; charge\; -\; a\; physical\; unit\; of\; electric\; charge."}\\ 0.0000000000000010204521072979158739839711133946\hspace{0.17em}{\mathrm{a}}_{\mathrm{0}}\mathrm{"Bohr\; radius\; -\; a\; physical\; unit\; of\; length."}\hspace{0.17em}\mathrm{e}\mathrm{"elementary\; charge\; -\; a\; physical\; unit\; of\; electric\; charge."}\\ \frac{0.0023892317923137943916446667268902}{\pi }\hspace{0.17em}\frac{{{\mathrm{a}}_{\mathrm{0}}\mathrm{"Bohr\; radius\; -\; a\; physical\; unit\; of\; length."}}^2\hspace{0.17em}\mathrm{e}\mathrm{"elementary\; charge\; -\; a\; physical\; unit\; of\; electric\; charge."}}{{\mathrm{t}}_{\mathrm{au}}\mathrm{"t\_au\; -\; a\; physical\; unit\; of\; time."}}\\ \frac{4.9348022005629884193493647544533}{{\pi }^2}\hspace{0.17em}\frac{{{\mathrm{a}}_{\mathrm{0}}\mathrm{"Bohr\; radius\; -\; a\; physical\; unit\; of\; length."}}^2\hspace{0.17em}{\mathrm{m}}_{\mathrm{e}}\mathrm{"electron\; mass\; -\; a\; physical\; unit\; of\; mass."}}{{\mathrm{t}}_{\mathrm{au}}\mathrm{"t\_au\; -\; a\; physical\; unit\; of\; time."}}\end{array}\right)$$

You can also convert the properties of the proton to the derived units of the atomic units.

proton = unitConvert(proton,"atomicUnits","derived")

proton = 
$$\left(\begin{array}{c}1836.1526748780789486223496324943\hspace{0.17em}{\mathrm{m}}_{\mathrm{e}}\mathrm{"electron\; mass\; -\; a\; physical\; unit\; of\; mass."}\\ 0.99999999999999993368785457223212\hspace{0.17em}\mathrm{e}\mathrm{"elementary\; charge\; -\; a\; physical\; unit\; of\; electric\; charge."}\\ 0.0000000000000010204521072979158739839711133946\hspace{0.17em}{\mathrm{p}}_{\mathrm{au}}\mathrm{"p\_au\; -\; a\; physical\; unit."}\\ 0.00048415958638447923027051145918036\hspace{0.17em}\pi \hspace{0.17em}{\mathrm{m}}_{\mathrm{au}}\mathrm{"m\_au\; -\; a\; physical\; unit\; of\; magnetic\; moment."}\\ 0.5\hspace{0.17em}\mathrm{\hslash }\mathrm{"reduced\; Planck\; constant\; -\; a\; physical\; unit\; of\; angular\; momentum."}\end{array}\right)$$

After completing the calculations, remove the unit system and the added units.

removeUnitSystem("atomicUnits")
removeUnit([u.t_au u.p_au u.m_au u.V_au])

Convert Absolute Temperatures and Temperature Differences

By default, temperatures are assumed to represent temperature differences. For example, 5*u.Celsius represents a temperature difference of 5 degrees Celsius. This assumption allows arithmetic operations on temperature values and conversion between temperature scales.

To represent absolute temperatures, use kelvin so that you do not have to distinguish an absolute temperature from a temperature difference.

Convert 23 degrees Celsius to K, treating the temperature first as a temperature difference and then as an absolute temperature.

u = symunit;
T = 23*u.Celsius;
diffK = unitConvert(T,u.K)

diffK = $$23\hspace{0.17em}\mathrm{K}\mathrm{"kelvin\; -\; a\; physical\; unit\; of\; temperature."}$$

absK = unitConvert(T,u.K,Temperature="absolute")

absK = 
$$\frac{5923}{20}\hspace{0.17em}\mathrm{K}\mathrm{"kelvin\; -\; a\; physical\; unit\; of\; temperature."}$$

Input Arguments

expr — Input expression

symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector | symbolic matrix | symbolic multidimensional array

Input expression, specified as a symbolic number, variable, expression, function, vector, matrix, or multidimensional array. If the conversion is not possible, unitConvert returns the input expression without converting it.

units — Units to convert input to

symbolic unit | vector of symbolic units

Units to convert the input to, specified as a symbolic unit or vector of symbolic units.

A symbolic unit can be a single symbolic unit, like u.kg, or a compound unit, like u.m/u.s^2.

unitSystem — Unit system to convert input to

"SI" | "CGS" | "US" | "GU" | "ESU" | "EMU" | symbolic unit system

Unit system to convert the input to, specified as one of these values:

• "SI" – International System of Units

• "CGS" – Centimeter-gram-second system of units

• "US" – United States customary units

• "GU" – Gaussian units

• "ESU" – Electrostatic units

• "EMU" – Electromagnetic units

• symbolic units system – Custom unit system defined by using the newUnitSystem function.

unitMode — Conversion mode for new unit system

"base" (default) | "derived" | "constants"

Conversion mode for the new unit system, specified as one of these values:

• "base" – Convert to the base units of the new unit system.

• "derived" – Convert to the derived units of the new unit system.

• "constants" – If the new unit system is "SI", then convert the units in the input expression to the seven SI-defining constants.

tempMode — Conversion mode for temperature

"difference" (default) | "absolute"

Conversion mode for temperature, specified as one of these values:

• "difference" – Convert input temperatures as temperature differences.

• "absolute" – Convert input temperatures as absolute temperatures.

Output Arguments

convertedExpr — Output expression in converted units

symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector | symbolic matrix | symbolic multidimensional array

Output expression in converted units, returned as a symbolic number, variable, expression, function, vector, matrix, or multidimensional array.

Tips

• When you use symbolic units, the value of 0 multiplied by a symbolic unit, such as 0*u.Celsius, is returned as a dimensionless 0. To preserve the unit when multiplying a symbolic unit by 0, use a cell array to represent the zero measurement.

  For example, you can define 0 degrees Celsius as a cell array and convert it to degrees Fahrenheit by using the unitConvert function.

  u = symunit;
  tC = {0,u.Celsius};
  tF = unitConvert(tC,u.Fahrenheit,Temperature="absolute")

  tF =
  32*[Fahrenheit]

Version History

Introduced in R2018b