CTAN Comprehensive TeX Archive Network

Directory macros/luatex/latex/lua-physical



Author: Thomas Jenni

Version: 1.0.5

Date: 2021-05-08

License: MIT

This is a pure Lua library which provides functions and object for doing computation with physical quantities.

In general, a physical quantity consists of a numerical value called magnitude and a unit. There are restrictions to the allowed mathematical operations with physical quantities. For example the quantity time cannot be added to the quantity mass. Furthermore, new quantities can be obtained by multiplication or division from other base quantities. The density is such an example. It can be calculated by dividing the mass of a body by its volume.


The library can be loaded with the command require("physical"). Like probably no other Lua library, lua-physical pollutes the global namespace with objects that represent physical units. This is in order to simplify the entry of physical quantities. By convention, each unit starts with an underscore in order to distinguish them from other variables. A basic example is the following:

> require("physical")
> a = 1.4 * _m
> b = 2 * _m
> A = (a*b):to(_m^2)
> print(A)
2.8 * _m^2

In the above example, two length a and b are defined and then multiplied. The result is an area. The unit of this area is _m*_m and has to be explicitly converted to _m^2 be the :to() command. The next example is slightly more complicated.

> require("physical")
> m1 = 22 * _kg
> m2 = 5.972e24 * _kg
> r = 6371 * _km
> F_G = (_Gc * m1 * m2 / r^2):to(_N)
> print(F_G)
2.16032(10)e2 * _N

The goal of the above example is to calculate the gravitational force on a body with mass 22 kg sitting on the surface of the earth. As one can see, the result is given with an uncertainty in parentheses. This is because the gravitational constant is not exactly known. Lua-physical can deal with uncertainties. One can give an uncertainty explicitly by instantiating physical.Number().

Temperature units

Temperatur units as _degC or _degF are treated as temperature differences. An absolute conversion can be done and has to be called explicitly. The :to()-function has therefore a second argument, which is by default false. That means temperatures are by default treated as temperature differences. If it is true, absolute conversion is used.

> physical = require("physical")
> T_1 = 15 * _degC
> print(T_1)
15 * _degC
> print(T_1:to(_K))
15.0 * _K
> print(T_1:to(_K,true))
288.15 * _K


> physical = require("physical")
> a = physical.Number(2,0.1) * _m
> A = (a^2):to(_m^2)
> V = (a^3):to(_m^3)
> print(a)
2.00(10) * _m
> print(A)
4.0(4) * _m^2
> print(V)
8.0(12) * _m^3

The uncertainty gets propagated by the Gaussian rule for completely uncorrelated uncertainties, i.e. they are added in quadrature. In the above example it is assumed, that the three sides of the cube were measured independently from each other and that the uncertainties of these measurements are not correlated. If one prefers another way of printing uncertainties, there are a few formatting options.

> physical = require("physical")
> local l = physical.Number(20.453,0.002) * _m

> physical.Number.format = physical.Number.SCIENTIFIC

> physical.Number.seperateUncertainty = true
> print(l)
(2.0453 +/- 0.0002)e1 * _m

> physical.Number.seperateUncertainty = false
> print(l)
2.0453(2)e1 * _m

> physical.Number.format = physical.Number.DECIMAL

> physical.Number.seperateUncertainty = true
> print(l)
(20.453 +/- 0.002) * _m

> physical.Number.seperateUncertainty = false
20.453(2) * _m

One can define, whether the uncertainty should be printed in the plus-minus notation or in the parentheses notation.


Since Latex now supports lua, this library is able to generate latex output. It uses the siunitx package notation, see ctan.org.

> physical = require("physical")
> E = 210 * _MeV
> print(E:tosiunitx())

Physical Data

Besides some physical constans, lua-physical has an isotope database. The data was taken from the Atomic Mass Evaluation - AME2016 by the Chinese Atomic Mass Data Center. The data was parsed and converted into a Lua table. One can access the data via the command physical.Data.Isotope(name,key).

> physical = require("physical")

> E_b = physical.Data.Isotope("235U","BindingEnergyPerNucleon")
> print(E_b)
7.590914(5)e3 * _keV

>  T_12 = physical.Data.Isotope("210Po","HalfLife")
>  print(T_12:to(_d))
1.38376(2)e2 * _d

List of Units and Prefixes

Base Units

The SI defines seven base units. For dimensionless quantities the unit _1 can be used.

Symbol Name Dimension
_1 Number Dimensionless
_m Meter Length
_kg Kilogram Mass
_s Second Time
_A Ampere Electric Current
_K Kelvin Temperature
_mol Mole Amount of Substance
_cd Candela Luminous Intensity

Source: (NIST)http://physics.nist.gov/cuu/Units/units.html


Most of the SI Units can have prefixes, i.e. _km, _hL, _ms, _uJ.

Symbol Name Factor Symbol Name Factor
Y Yotta 10^24 y Yocto 10^-24
Z Zetta 10^21 z Zepto 10^-21
E Exa 10^18 a Atto 10^-18
P Peta 10^15 f Femto 10^-15
T Tera 10^12 p Pico 10^-12
G Giga 10^9 n Nano 10^-9
M Mega 10^6 u Micro 10^-6
k Kilo 10^3 m Milli 10^-3
h Hecto 10^2 c Centi 10^-2
da Deca 10^1 d Deci 10^-1

Source: (NIST)http://physics.nist.gov/cuu/Units/prefixes.html

Derived SI Units

Symbol Name Definition Dimension
_rad Radian _1 Plane Angle (Dimensionless)
_sr Steradian _rad^2 Solid Angle (Dimensionless)
_Hz Hertz 1/_s Frequency
_N Newton _kg*_m/_s^2 Force
_Pa Pascal _N/_m^2 Pressure
_J Joule _N*_m Energy
_W Watt _J/_s Power
_C Coulomb _A*_s Electric Charge
_V Volt _J/_C Electric Potential
_F Farad _C/_V Electric Capacitance
_Ohm Ohm _V/_A Electric Resistance
_S Siemens _A/_V Electric Conductance
_Wb Weber _V*_s Magnetic Flux
_T Tesla _Wb/_m^2 Magnetic Flux Density
_H Henry _Wb/_A Inductance
_lm Lumen _cd*_sr Luminous Flux
_lx Lux _lm/_m^2 Illuminance
_Bq Becquerel 1/_s Radioactivity
_Gy Gray _J/_kg Absorbed Dose
_Sv Sievert _J/_kg Equivalent Dose
_kat katal _mol/_s Catalytic Activity
_degC Degree Celsius x/_K - 273.15 Temperature

Source: (NIST)http://physics.nist.gov/cuu/Units/units.html

Mathematical Constants

Symbol Name Definition
_Pi pi 3.1415926535897932384626433832795028841971693993751
_E eulernumber 2.7182818284590452353602874713526624977572470936999

Physical Constants

Symbol Name Definition
_c Speed of Light 299792458 * _m/_s
_Gc Gravitational Constant 6.67408(31)e-11 * _m^3/(_kg*_s^2)
_h_P Planck Constant 6.626070040(81)e-34 * _J*_s
_h_Pbar Reduced Planck Constant _hP/(2*Pi)
_e Elementary Charge 1.6021766208(98)e-19 * _C
_u_0 Vacuum Permeability 4e-7*Pi * _N*_A^2
_e_0 Vacuum Permitivity 1/(_u0*_c^2)
_u Atomic Mass Unit 1.66053904(2)e-27 * _kg
_m_e Electron Rest Mass 9.10938356(11)e-31 * _kg
_m_p Proton Mass 1.672621898(21)e-27 * _kg
_m_n Neutron Mass 1.674927471(21)e-27 * _kg
_u_B Bohr Magneton _e*_hPbar/(2*_m_e)
_u_N Nuclear Magneton _e*_hPbar/(2*_m_p)
_alpha Finestructure Constant _u0*_e^2*_c/(2*_hP)
_Ry Rydberg Constant _alpha^2*_m_e*_c/(2*_hP)
_N_A Avogadro Constant 6.022140857(74)e23 /_mol
_R Molar Gas Constant 8.3144598(48) * _J/(_K*_mol)
_sigma Stefan-Boltzmann Constant Pi^2*_k_B^4/(60*_h_Pbar^3*_c^2)
_g_0 Standard Acceleration of Gravity 9.80665 * _m/_s^2

Source: (NIST)http://physics.nist.gov/cuu/Constants/

Nominal Astronomical Units

Symbol Name Definition
_R_sun Nominal Solar Radius 6.957e8 * _m
_S_sun Nominal Solar Irradiance 1361 * _W/_m^2
_L_sun Nominal Solar Luminosity 3.828e26 * _W
_T_sun Nominal Solar Effective Temperature 5772 * _K
_GM_sun Nominal Solar Mass Parameter 1.3271244e20 * _m^3 * _s^-2
_Re_E Nominal Terrestrial Equatorial Radius 6.3781e6 * _m
_Rp_E Nominal Terrestrial Polar Radius 6.3568e6 * _m
_GM_J Nominal Terrestrial Mass Parameter 3.986 004e14 * _m^3 * _s^-2
_Re_J Nominal Jovian Equatorial Radius 7.1492e7 * _m
_Rp_J Nominal Jovian Polar Radius 6.6854e7 * _m
_GM_J Nominal Jovian Mass Parameter 1.2668653e17 * _m^3 * _s^-2

Source: (IAU 2015 Resolution B3)https://www.iau.org/static/resolutions/IAU2015English.pdf

Non-SI Units accepted for use with the SI

Symbol Name Definition Dimension
_percent Percent 0.01 * _1 Dimensionless
_permille Permille 0.001 * _1 Dimensionless
_dB Decibel _1 Dimensionless
_deg Degree (Pi/180) * _rad Plane Angle (Dimensionless)
_arcmin Arc Minute _deg/60 Plane Angle (Dimensionless)
_arcsec Arc Second _arcmin/60 Plane Angle (Dimensionless)
_au Astronomical Unit 149597870700 * _m Length
_ly Lightyear _c*_a Length
_pc Parsec (648000/Pi)*_au Length
_angstrom Angstrom 1e-10 * _m Length
_fermi Fermi 1e-15 * _m Length
_are Are 1e2 * _m^2 Area
_hectare Hectare 1e4 * _m^2 Area
_barn Barn 1e-28 * _m^2 Area
_L Liter 0.001 * _m^3 Volume
_t Tonne 1000 * _kg Mass
_svedberg Svedberg 1e-13 * _s Time
_min Minute 60 * _s Time
_h Hour 60 * _min Time
_d Day 24 * _h Time
_wk Week 7 * _d Time
_a Julian Year 365.25 * _d Time
_bar Bar 100000 * _Pa Pressure
_atm Standard Atmosphere 101325 * _Pa Pressure
_at Technical Atmosphere _g0 * _kg/_m^2 Pressure
_mmHg Millimeter of Mercury 133.322387415*_Pa Pressure
_cal Thermochemical Calorie 4.184 * _J Energy
_cal_IT International Calorie 4.1868 * _J Energy
_g_TNT Gram of TNT 1e3 * _cal Energy
_t_TNT Ton of TNT 1e9 * _cal Energy
_eV Electron-Volt _e * _V Energy
_Wh Watt-Hour _W*_h Energy
_VA Volt-Ampere _V*_A Power
_PS Metric Horsepower 75*_g0*_kg*_m/_s Power
_Ah Ampere-Hour _A*_h Electric Charge
_PI Poiseuille _Pa*_s Dynamic Viscosity

Source: (NIST)http://physics.nist.gov/cuu/Units/outside.html

Other Metric Units

Symbol Name Definition Dimension
_tsp Metric Teaspoon 0.005 * _L Volume
_Tbsp Metric Tablespoon 3 * _tsp Volume
_gon Gradian Pi/200*_rad Plane Angle (Dimensionless)
_tr Turn 2*Pi*_rad Plane Angle (Dimensionless)
_sp Spat 4*Pi*_sr Solid Angle (Dimensionless)
_kp Kilopond _g0*_kg Force
_Ci Curie 3.7e10 * _Bq Radioactivity
_rd Rad 0.01 * _Gy Absorbed Dose
_rem Rem 0.01 * _Sv Equivalent Dose
_Ro Roentgen 2.58e-4 * _C/_kg Ionic Dose

Source: (NIST)http://physics.nist.gov/cuu/Units/outside.html

Imperial Units

Symbol Name Definition Dimension
_in Inch 0.0254 * _m Length
_th Thou 0.001 * _in Length
_pc Pica _in/6 Length
_pt Point _in/72 Length
_hh Hand 4 * _in Length
_ft Foot 12 * _in Length
_yd Yard 3 * _ft Length
_rd Rod 5.5 * _yd Length
_ch Chain 4 * _rd Length
_fur Furlong 10 * _ch Length
_mi Mile 8 * _fur Length
_lea League 3 * _mi Length
_nmi Nautical Mile 1852 * _m Length
_nlea Nautical League 3 * _nmi Length
_cb Cable _nmi/10 Length
_ftm Fathom 6 * _ft Length
_ac Acre 43560 * _ft^2 Area
_gal Gallon 4.54609 * _L Volume
_qt Quart _gal/4 Volume
_pint Pint _qt/2 Volume
_cup Cup _pint/2 Volume
_gi Gill _pint/4 Volume
_fl_oz Fluid Ounce _gi/5 Volume
_fl_dr Fluid Dram _fl_oz/8 Volume
_gr Grain 64.79891 * _mg Mass
_lb Pound 7000 * _gr Mass
_oz Ounce _lb/16 Mass
_dr Dram _oz/256 Mass
_st Stone 14 * _lb Mass
_qtr Quarter 2*_st Mass
_cwt Hundredweight 4*_qtr Mass
_ton Long Ton 20*_cwt Mass
_lb_t Troy Pound 5760*_gr Mass
_oz_t Troy Ounce _lb_t/12 Mass
_pwt Pennyweight 24 * _gr Mass
_fir Firkin 56*_lb Mass
_sen Sennight 7*_d Time
_ftn Fortnight 14*_d Time
_degF Degree Fahrenheit (x/_K + 459.67)*(5/9) Temperature
_degR Degree Rankine (x/_K)*(5/9) Temperature
_kn Knot _nmi/_h Velocity
_lbf Pound Force _lb*_g0 Force
_pdl Poundal _lb*_ft/_s^2 Force
_slug Slug _lbf*_s^2/_ft Mass
_psi Pound per Square Inch _lbf/_in^2 Pressure
_BTU_it British Thermal Unit 1055.05585262 * _J Energy
_BTU_th British Thermal Unit (1897.83047608/1.8) * _J Energy
_hp Horsepower 33000*_ft*_lbf/_min Power

Source: (Wikipedia)https://en.wikipedia.org/wiki/Imperialunits

US Customary and Survey Units

Symbol Name Definition Dimension
_in_US US Survey Inch _m/39.37 Length
_hh_US US Survey Hand 4 * _in_US Length
_ft_US US Survey Foot 3 * _hh_US Length
_li_US US Survey Link 0.66 * _ft_US Length
_yd_US US Survey Yard 3 * _ft_US Length
_rod_US US Survey Rod 5.5 * _yd_US Length
_ch_US US Survey Chain 4 * _rd_US Length
_fur_US US Survey Furlong 10 * _ch_US Length
_mi_US US Survey Mile 8 * _fur_US Length
_lea_US US Survey League 3 * _mi_US Length
_ftm_US US Survey Fathom 72 * _in_US Length
_cbl_US US Survey Cable 120 * _ftm_US Length
_ac_US US Survey Acre _ch * _fur_US Area
_gal_US US Gallon 231 * _in^3 Volume
_qt_US US Quart _gal_US/4 Volume
_pint_US US Pint _qt_US/2 Volume
_cup_US US Cup _pint_US/2 Volume
_gi_US US Gill _pint_US/4 Volume
_fl_oz_US US Fluid Ounce _gi_US/4 Volume
_Tbsp_US US Tablespoon _fl_oz_US/2 Volume
_tsp_US US Teaspoon _Tbsp_US/3 Volume
_fl_dr_US US Fluid Dram _fl_oz_US/8 Volume
_qtr_US US Quarter 25 * _lb Mass
_cwt_US US Hundredweight 4 * _qtr_US Mass
_ton_US Short Ton 20*_cwt_US Mass

Source: (Wikipedia)https://en.wikipedia.org/wiki/UnitedStatescustomaryunits

Download the contents of this package in one zip archive (835.3k).

lua-physical – Functions and objects for the computation of physical quantities

This is a pure Lua library, which provides functions and objects for the computation of physical quantities. The package provides units of the SI and the imperial system. In order to display the numbers with measurement uncertainties, the package is able to perform Gaussian error propagation.

Home pagehttps://github.com/tjenni/lua-physical
Bug trackerhttps://github.com/tjenni/lua-physical/issues
Version1.0.5 2021-05-08
LicensesMIT License
Copyright2020–2021 Thomas Jenni
MaintainerThomas Jenni
Contained inTeX Live as lua-physical
MiKTeX as lua-physical
Guest Book Sitemap Contact Contact Author