sharkdp / insect

High precision scientific calculator with support for physical units

Note: Please consider using the follow-up project instead: Numbat.

you can read more about why Insect has been rewritten from scratch here.

---

A high-precision scientific calculator with full support for physical units.

Try the web version here: https://insect.sh

Contents

• Documentation
• Reference
• Pros and cons
• FAQ
• Terminal version
• Development
• Maintainers

Documentation

• Evaluate mathematical expressions:

  1920/16*9
  2^32
  sqrt(1.4^2 + 1.5^2) * cos(pi/3)^2
  

  • Operators: addition (+), subtraction (-), multiplication (*, ·, ×), division (/, ÷, per), exponentiation (^, **). Full list: see Reference below.

  • Mathematical functions: abs, acos, acosh, acot/arccotangent, acoth/archypcotangent, acsc/arccosecant, acsch/archypcosecant, arcsecant, asech/archypsecant, asin, asinh, atan2, atan, atanh, ceil, cos, cosh, cot/cotangent, coth/hypcotangent, csc/cosecant, csch/hypcosecant, exp, floor, fromCelsius, fromFahrenheit, gamma, ln, log10, log, maximum, mean, minimum, round, secant, sech/hypsecant, sin, sinh, sqrt, tan, tanh, toCelsius, toFahrenheit.

  • High-precision numeric type with 30 significant digits that can handle very large (or small) exponents like 10^(10^10).

  • Exponential notation: 6.022e23.

  • Hexadecimal, octal and binary number input:

    0xFFFF
    0b1011
    0o32
    0x2.F
    0o5p3
    

• Physical units: parsing and handling, including metric prefixes:

  2 min + 30 s
  40 kg * 9.8 m/s^2 * 150 cm
  sin(30°)
  

  • Supported units: see Reference section below.

  • Implicit conversions: 15 km/h * 30 min evaluates to 7.5 km.

  • Useful error messages:

    > 2 watts + 4 newton meter
    
    Conversion error:
      Cannot convert unit N·m (base units: kg·m²·s⁻²)
                  to unit W (base units: kg·m²·s⁻³)
    

• Explicit unit conversions: the -> conversion operator (aliases: →, ➞, to):

  60 mph -> m/s
  500 km/day -> km/h
  1 mrad -> degree
  52 weeks -> days
  5 in + 2 ft -> cm
  atan(30 cm / 2 m) -> degree
  6 Mbit/s * 1.5 h -> GB
  

• Variable assignments:

  Example: mass of the earth

  r = 6000km
  vol = 4/3 * pi * r^3
  density = 5 g/cm^3
  vol * density -> kg
  

  Example: oscillation period of a pendulum

  len = 20 cm
  2pi*sqrt(len/g0) -> ms
  

  • Predefined constants (type list to see them all): speed of light (c), Planck's constant (h_bar), electron mass (electronMass), elementary charge (elementaryCharge), magnetic constant (µ0), electric constant (eps0), Bohr magneton (µ_B), Avogadro's constant (N_A), Boltzmann constant (k_B), gravitational acceleration (g0), ideal gas constant (R), ...

  • Last result: you can use ans (answer) or _ to refer to the result of the last calculation.

• User-defined functions:

  Example: kinetic energy

  kineticEnergy(mass, speed) = 0.5 * mass * speed^2 -> kJ
  
  kineticEnergy(800 kg, 120 km/h)
  

  Example: barometric formula

  P0 = 1 atm
  T0 = fromCelsius(15)
  tempGradient = 0.65 K / 100 m
  
  pressure(height) = P0 * (1 - tempGradient * height / T0)^5.255 -> hPa
  
  pressure(1500 m)
  

• Sums and products:

  Syntax:

  sum(<expression>, <index-variable>, <from>, <to>)
  product(<expression>, <index-variable>, <from>, <to>)
  

  Examples:

  # sum of the first ten squares
  sum(k^2, k, 1, 10)
  
  # the factorial of n as the product 1 × 2 × ... × n
  myFactorial(n) = product(k, k, 1, n)
  

• Unicode support:

  λ = 2 × 300 µm
  ν = c/λ → GHz
  

• And more: tab completion, command history (arrow keys, Ctrl+R), pretty printing, syntax highlighting, ...

Reference

• Operators (ordered by precedence: high to low)

  Operator	Syntax
  factorial	!
  square, cube, ...	², ³, ⁻¹, ...
  exponentiation	^, **
  multiplication (implicit)	whitespace
  modulo	%
  division	per
  division	/, ÷
  multiplication (explicit)	*, ·, ×
  subtraction	-
  addition	+
  unit conversion	->, →, ➞, to
  assignment	=

  Note that implicit multiplication has a higher precedence than division, i.e. 50 cm / 2 m will be parsed as 50 cm / (2 m).

• Commands

  Command	Syntax
  help text	help, ?
  list of variables	list, ls, ll
  reset environment	reset
  clear screen	clear, cls
  copy result to clipboard	copy, cp
  quit (CLI)	quit, exit

• Supported units (remember that you can use tab completion).

  All SI-accepted units support metric prefixes and binary prefixes (MiB, GiB, ...).

  Unit	Syntax
  Ampere	amperes, ampere, A
  Ångström	angstroms, angstrom, Å
  Astronomical unit	AU, au, astronomicalunits, astronomicalunit
  Atmosphere	atm
  Bar	bars, bar
  Barn	barns, barn
  Becquerel	becquerels, becquerel, Bq
  Bel	bels, bel
  Bit	bits, bit
  Bits per second	bps
  British thermal unit	BTU
  Byte	Bytes, bytes, Byte, byte, B, Octets, octets, Octet, octet
  Calorie	calories, calorie, cal
  Candela	candelas, candela, cd
  Coulomb	coulombs, coulomb, C
  Cup	cups, cup
  DPI	dpi
  Day	days, day, d
  Degree	degrees, degree, deg, °
  Dot	dots, dot
  Electronvolt	electronvolts, electronvolt, eV
  Euro	euros, euro, EUR, €
  Farad	farads, farad, F
  Fluid ounce	fluidounces, fluidounce, floz
  Foot	feet, foot, ft
  Fortnight	fortnights, fortnight
  Frame	frames, frame
  Frames per second	fps
  Furlong	furlongs, furlong
  Gallon	gallons, gallon, gal
  Gauss	gauss
  Gram	grams, gram, grammes, gramme, g
  Gray	grays, gray, Gy
  Hectare	hectares, hectare, ha
  Henry	henrys, henries, henry, H
  Hertz	hertz, Hz
  Hogshead	hogsheads, hogshead
  Hour	hours, hour, hr, h
  Inch	inches, inch, in
  Joule	joules, joule, J
  Katal	katals, katal, kat
  Knot	knots, knot, kn, kt
  Kelvin	kelvins, kelvin, K
  Light-year	lightyears, lightyear, ly
  Liter	liters, liter, litres, litre, L, l
  Lumen	lumens, lumen, lm
  Lux	lux, lx
  Meter	meters, meter, metres, metre, m
  Mile	miles, mile
  Miles per hour	mph
  Millimeter of mercury	mmHg
  Minute	minutes, minute, min
  Molal	molals, molal
  Molar	molars, molar
  Mole	moles, mole, mol
  Month	months, month
  Nautical mile	M, NM, nmi
  Newton	newtons, newton, N
  Ohm	ohms, ohm, Ω
  Ounce	ounces, ounce, oz
  PPI	ppi
  Parsec	parsecs, parsec, pc
  Parts-per-million	ppm
  Parts-per-billion	ppb
  Parts-per-trillion	ppt
  Parts-per-quadrillion	ppq
  Pascal	pascals, pascal, Pa
  Percent	percent, pct
  Person	persons, person, people
  Piece	pieces, piece
  Pint	pints, pint
  Pixel	pixels, pixel, px
  Pound-force	pound_force, lbf
  Pound	pounds, pound, lb
  Psi	psi
  RPM	RPM, rpm
  Radian	radians, radian, rad
  Rod	rods, rod
  Second	seconds, second, sec, s
  Siemens	siemens, S
  Sievert	sieverts, sievert, Sv
  Tablespoon	tablespoons, tablespoon, tbsp
  Teaspoon	teaspoons, teaspoon, tsp
  Tesla	teslas, tesla, T
  Thou	thou, mils, mil
  Tonne	tonnes, tonne, tons, ton, t
  US Dollar	dollars, dollar, USD, $
  Volt	volts, volt, V
  Watt-hour	Wh
  Watt	watts, watt, W
  Weber	webers, weber, Wb
  Week	weeks, week
  Yard	yards, yard, yd
  Gregorian year	years, year
  Julian year	julianYears, julianYear

Pros and cons

Reasons to use Insect

• Insect is open-source.
• There is a web version that requires no installation.
• With both browser and terminal versions available, Insect is truly cross-platform.
• Insect has first-class support for physical units, including metric and binary prefixes. While evaluating your calculation, Insect ensures that you did not accidentally make any mistakes in combining the physical quantities.
• Insect supports an interactive style with its readline-like interface. There is a saved history that can be browsed by pressing the up and down arrow keys. The history is also searchable via Ctrl-R.
• Insect's syntax is rather strict. The parser does not try to be "smart" on syntactically incorrect input, so there shouldn't be any surprises - and you can trust the result of your calculation. The parsed user input is always pretty-printed for a quick double-check.
• Insect is written in PureScript and therefore benefits from all the safety guarantees that a strictly typed functional programming language gives you.
• The source code of purescript-quantities (the underlying library for physical units) as well as the code of Insect itself is extensively tested.

Reasons to choose an alternative

• Insect is a scientific calculator. It's not a computer algebra system that solves differential equations or computes integrals. Try WolframAlpha instead.
• There is no graphical user interface with buttons for each action (x², 1/x, DEG/RAD, etc.). Qalculate! is a fantastic tool that supports both text as well as graphical input.
• Insect supports a huge range of physical units: all SI units, all non-SI units that are accepted by SI as well as most units of the imperial and US customary systems (and many more). However, if you need something even more comprehensive, try GNU units.
• Insect is not a general-purpose programming language. You could try Frink.
• Insect does not have a special mode for hexadecimal, octal, or binary numbers (yet), though it does support inputting them.

FAQ

• Why are Celsius and Fahrenheit not supported?

  In contrast to the SI unit of temperature, the Kelvin, and to all other units, Celsius and Fahrenheit both require an additive offset when converting into and from other temperature units. This additive offset leads to all kinds of ambiguities when performing calculations in these units. Adding two temperatures in Celsius, for example, is only meaningful if one of them is seen as an offset value (rather than as an absolute temperature). Insect is primarily a scientific calculator (as opposed to a unit conversion tool) and therefore focuses on getting physical calculations right.

  Even though °C and °F are not supported as built-in units, there are helper functions to convert to and from Celsius (and Fahrenheit):

  • fromCelsius takes a scalar value that represents a temperature in Celsius and returns a corresponding temperature in Kelvin:

    > fromCelsius(0)
    
       = 273.15 K
    
    > k_B * fromCelsius(23) to meV
    
       = 25.5202 meV
    

  • toCelsius takes a temperature in Kelvin and returns a scalar value that represents the corresponding temperature in Celsius:

    > toCelsius(70 K)
    
       = -203.15
    
    > toCelsius(25 meV / k_B)
    
       = 16.963
    

• Why is 1/2 x parsed as 1/(2x)?

  Implicit multiplication (without an explicit multiplication sign) has a higher precedence than division (see operator precedence rules). This is by design, in order to parse inputs like 50 cm / 2 m as (50 cm) / (2 m). If you meant ½ · x, write 1/2 * x.

• What is the internal numerical precision?

  By default, Insect shows 6 significant digits in the result of the calculation. However, the internal numerical precision is much higher (30 digits).

• How does the conversion operator work?

  The conversion operator -> attempts to convert the physical quantity on its left hand side to the unit of the expression on its right hand side. This means that you can write an arbitrary expression on the right hand side (but only the unit part will be extracted). For example:

  # simple unit conversion:
  > 120 km/h -> mph
  
    = 74.5645 mi/h
  
  # expression on the right hand side:
  > 120 m^3 -> km * m^2
  
    = 0.12 m²·km
  
  # convert x1 to the same unit as x2:
  > x1 = 50 km / h
  > x2 = 3 m/s -> x1
  
    x2 = 10.8 km/h
  

• What is the relation between the units RPM, rad/s, deg/s and Hz?

  The unit RPM (revolutions per minute) is defined via 1 RPM = 1 / minute where the 1 on the right hand side symbolizes "1 revolution".

  As the base unit is the same (1 / second), RPM can be converted to rad / s, deg / s or Hz. Note, however, that 1 RPM does not equal 2π rad / min or 360° / min or 1 Hz, as some might expect. If you're interested in computing the traversed angle of something that rotates with a given number of revolutions per minute, you need to multiply by 2π rad or 360° because:

  1 RPM · (360°/revolution) = (1 revolution / minute) · (360° / revolution) = 360° / minute
  

Terminal version

In addition to the web interface, there is also a command-line version (supporting Node.js 10 and later) which can by installed via npm:

npm install -g insect

Note that you should almost always never run this as root or with sudo. If the command fails due to permission issues, set up a prefix directory and call npm install as a user instead.

For Arch Linux, there is an AUR package:

yaourt -S insect

For macOS, there is a Homebrew formula:

brew install insect

For Android, install Termux from F-Droid. Install Node.js in Termux and then install insect from npm:

pkg install nodejs-lts
npm install -g insect

Development

Insect is written in PureScript (see the Getting Started guide). First, install all dependencies:

npm install

To start the web version:

npm start

To build a bundled JavaScript file that you can run from the terminal (note that this builds the web version too):

npm run build

To run the index.cjs file which the previous command creates:

node index.cjs
# Or simply on Un*x
./index.cjs

Note that it's not possible to just move this file anywhere and then run it there, since it depends on packages in node_modules.

Insect comes with a comprehensive set of unit tests. To run them:

npm test

Note that Node.js 12 or above is required to work on/build Insect (despite Insect itself requiring only Node.js 10 or later to run). If you don't have or want to install Node.js 12 or later, you can use the following Dockerfile to build or run Insect on Node.js 18:

FROM node:18

WORKDIR /usr/src/insect

COPY . .

RUN npm install && \
    npm run build

CMD ["node", "index.cjs"]

After creating the image (docker build -t sharkdp/insect .), you can create the container and copy out the build artifacts:

docker create sharkdp/insect:latest
# copy SHA (e.g. 71f0797703e8)
docker cp 71f0797703e8:/usr/src/insect/index.cjs .
docker cp -r 71f0797703e8:/usr/src/insect/node_modules .

To directly run Insect inside Docker (paying a heavy startup time penalty), you can use:

docker run -it --rm -v ~/.local/share/insect-history:/root/.local/share/insect-history sharkdp/insect:latest

Maintainers

• sharkdp
• mhmdanas

insect's Issues

parse floats correctly

• Support for fractional parts
• Support for negative numbers
• Support for exponential notation

CLI version

How to treat NaN and Infinity?

> (1/0)m
Infinitym

> sqrt(-2)m
NaNm

🙁

Options to deal with this:

• Add DivideByZeroError to EvalError.

Handle name clash between units and variables

How should this be treated?

> km = 3.0
???

Possible solutions:

• Try to parse the identifier as a (derived) unit. If it succeeds -> disallow this identifier
• Ignore it -> identifier takes precence -> km=3.0 -> 2km = 6.

Re-introduce "to" in addition to "->"

The 'clear' command does not clear the screen

Steps to Reproduce :

• Go to Web version of calculator
• Perform some operation then enter the 'clear' command
• Observe that : The 'clear' command does not clear the screen

Expected Result
The 'clear' command should clear the screen

Actual Result
The 'clear' command does not clear the screen

Add let-style bindings

Example commands listing style on help command is confusing

Hi, visited the site for the first time and used the ? command, and because the columns are so close together it seemed like > 2min + 30s somehow results in > 6Mbit/s * 1.5h -> Gb which of course makes no sense. You could increase the distance between the columns to help readability.

'Detect' scalar values and always discard of the units

The results for all of these should be pure numbers:

5m/2in
5m/5cm
360° -> rad

Save history

I think it would be quite useful if the history (possibly including variables) can be saved and later loaded again, something akin to sessions or worksheets.

Cannot convert quantity of unit 'b' to a scalar

> b = 5
5
> a = 5
5
> a+b
Cannot convert quantity of unit 'b' to a scalar

Add pretty printer?

Sth along the lines of

> 3m/4m

    (3m)/(4m) = 0.75

Add all SI units

• Ampere (and derived electrical units: V, C, H, F, Ω, S, Wb, T)
• Kelvin
• Mole
• Candela (and Lumen, Lux)

Other derived units

• Pascal
• Becquerel
• Gray
• Sievert

Support conversions to combined units

4J -> Nm
4J -> N*m

Improve simplification of physical quantities

An input like

5Mbit/s * 2h

should be simplified to 36 Gbit, i.e. units of the same dimension should always be unified (here: second and hour). Similarly

5cm * 5m

should be simplified to either 0.25m² or 2500cm²

This is related to sharkdp/purescript-quantities#16

Does not work on android

[Bug] No unit is returned when we divide for example 1hour / 3s.

Nevermind, I was wrong. (you can delete this Issue)

Add more mathematical functions

• log10, log2, ln
• abs
• sinh, cosh, tanh, asinh, acosh, atanh

Add AST

Treat conversions as expressions?

We could treat 3in -> cm as an expression by parsing -> as an operator with very low precedence.

Advantages:

• This would allow us to use conversions in assigments: x = 2in -> cm.
• It would simplify the AST since Conversion is not needed anymore

Neutral:

• It would allow us to write (3cm -> in)^2. Do we need this?

Disadvantages:

• What is 3km -> 500m? qalculate parses this as 3km to m.
• What is 3km -> 2in+2cm. This would be a valid expression.

add parens

Binary operations on hex int32s

Hi! Awesome project! Will you be willing to accept a PR adding hex ints with binary operations? (add, or, xor shr, etc.)

do not allow SI-prefixes for imperial units

Support "²" and "³" instead of "^2" and "^3"

support exponentiation

Note

2m^2 should be parsed as 2*(m^2)
(2m)^2 should be parsed as (2m)^2

CLI easy exit

So far, interrupt (CTRL-C) seems to be the only way to exit on the cli tool?

Maybe add a more discoverable method with a common keyword like quit or exit?

Add unit tests

Add unicode operators and variable names

As suggested here: https://news.ycombinator.com/reply?id=13915043

• Add ⁴ as ^4, ⁵ as ^5 etc.
• Add × for multiplication
• Add ÷ for division
• Add π and ℏ for pi and hbar

make history persistent between page reloads

Parse 3km^2 as 3(km)^2, not as (3km)^2

-> quantities should not be parsed as a single entity -> see #7

support Python-style exponentiation

^ -> **

Radians per second to Hertz conversion incorrect

> 6rad/s -> hertz

    6Hz

Expected result: 0.9549Hz

Treat unary '-' as operator

.. in order to parse -(3+4) correctly

Add pre-defined constants (pi, e, speed_of_light, ...)

Neater command-line usage

Currently, the CLI version is only really usable as a REPL-style interactive prompt. However, it would be really nice if it also handled the non-interactive use-case nicer.

To give an example, the only way to compute something like 6h -> min currently without interactivity is currently:

$ echo "6h -> min" | insect
> 6h -> min

  360min

> �

If you want just the answer, you need even more trickery:

$ echo "6h -> min" | insect | grep -vE '^>' | paste -sd' ' | tr -d ' '
360min

And even then, it also includes color codes, and so can't directly be handled as a number (notice the \e[36mat the beginning, and the \e[0m at the end):

$ echo "6h -> min" | insect | grep -vE '^>' | paste -sd' ' | tr -d ' ' | hexdump -C
00000000  1b 5b 33 36 6d 33 36 30  6d 69 6e 1b 5b 30 6d 0a  |.[36m360min.[0m.|

If insect could instead detect that it was being used in non-interactive mode, and then only output the answer (a command-line flag would also be ok), that would make this kind of use much easier. One step further would be to also add a -e flag to allow evaluating an expression without pipes:

$ insect -e '6h -> min'
360min

support powers for units

• m²
• m^2
• m^(-2)

Show integer values without fractional part

Automatically create list of identifiers for tab completion

Use a better default precision (~6 sign. digits)

Complex/imaginary numbers

@sharkdp Are you planning to add support for complex/imaginary numbers. I am up for sending a PR to add that capability 😸

mb is treated as "millibytes"

Due to the uniform handling of SI prefixes, mb is unfortunately a millibyte, which is a pretty useless unit of measure:

$ insect '1 mb -> bytes'
0.001b

This was pretty confusing to me, until I realized I needed to use Mb to get the desired unit (of mebibytes = 1000000 bytes, which is close enough).

Fixing this requires some special-casing of data storage-related units.

Precedence of units in parsing

This is possibly best illustrated by an example:

> 3m/4m
0.75m²
> 3m/(4m)
0.75

I was expecting to get 0.75 in both cases. Nice work on this by the way, it's a really nifty project!

Allow for whitespace everywhere

Show welcome message only for first visit

support combined units

Some examples:

3km/h
2Nm/h    <- do we want to support this?
2N*m/h
kg*m^2/s^2
3km³s^(-1)/(kg^5*THz^4)

add commands: help, clear, reset, ls, ...

• help
• clear
• reset
• ls

Ctrl+R support (+ more readline features)

Could be fixed by using jquery.terminal
See also: #12

allow for whitespace

Implicit multiplication of numbers with identifiers that start with "e"

> ex = 2
2
> 1ex
Parse error: Expected a digit at position 3

support simple mathematical functions