README

Qalculate! library and CLI

Qalculate! is a multi-purpose cross-platform desktop calculator. It is simple
to use but provides power and versatility normally reserved for complicated
math packages, as well as useful tools for everyday needs (such as currency
conversion and percent calculation). Features include a large library of
customizable functions, unit calculations and conversion, symbolic calculations
(including integrals and equations), arbitrary precision, uncertainty
propagation, interval arithmetic, plotting, and a user-friendly interface (GTK+,
Qt, and CLI).

1. Requirements

* GMP and MPFR
* libxml2
* libcurl, icu, gettext (recommended)
* iconv, readline (recommended for CLI)
* Gnuplot 1.7 (optional)
* doxygen (for compilation of git version)

For Linux distributions which provide separate development packages, these must
be installed for all the required libraries (e.g. libmpfr-dev) before
compilation.

2. Installation

In a terminal window in the top source code directory run

* ./autogen.sh (not required if using a release source tarball, only if using
  the git version)
* ./configure
* make
* make install (as root)
* ldconfig (if necessary, as root)

If libqalculate is installed in /usr/local (default) you may need to add
/usr/local/lib to the library path of the system (add /usr/local/lib to a file
under /etc/ld.so.conf.d/ and run ldconfig).

3. API Documentation

The API documentation is included in the package and is installed in
$docdir/libqalculate/html (usually /usr/share/doc/libqalculate/html).
It is generated when running autogen.sh.

It is also available online at reference/index.html.

4. Using the CLI program "qalc"

To calculate a single expression from the command line (non-interactive mode)
enter "qalc EXPRESSION" (e.g. qalc 5+2)

"qalc --help" shows information about command line options in non-interactive
mode.

If you run "qalc" without any mathematical expression the program will start in
interactive mode, where you can enter multiple expressions with history and
completion, manipulate the result and change settings.

Type "help" in interactive mode for more information.

A man page is also available (shown using the command "man qalc", or online at https://qalculate.github.io/manual/qalc.html).

5. Other Applications

The main user interfaces for libqalculate are
qalculate-gtk (https://github.com/Qalculate/qalculate-gtk) and
qalculate-qt (https://github.com/Qalculate/qalculate-qt).

Other software using libqalculate include
* KDE Plasma Workspace (https://www.kde.org/workspaces/plasmadesktop/)
* Cantor (http://kde.org/applications/education/cantor/)
* Step (http://kde.org/applications/education/step/)
* Qalculate widget for KDE Plasma (https://store.kde.org/p/1155946/)

6. Features

* Calculation and parsing:
   * Basic operations and operators:
     + - * / mod ^ E () && || ! < > >= <= != ~ & | << >> xor
   * Fault-tolerant parsing of strings:
     log 5 / 2 .5 (3) + (2( 3 +5 = ln(5) / (2.5 * 3) + 2 * (3 + 5)
   * Expressions may contain any combination of numbers, functions, units,
     variables, vectors and matrices, and dates
   * Supports complex and infinite numbers
   * Propagation of uncertainty
   * Interval arithmetic (for determination of the number of significant digits
     or direct calculation with intervals of numbers)
   * Supports all common number bases, as well as negative and non-integer
     radices, sexagesimal numbers, time format, and roman numerals
   * Ability to disable functions, variables, units or unknown variables for
     less confusion: e.g. when you do not want (a+b)^2 to mean (are+barn)^2 but
     ("a"+"b")^2
   * Controllable implicit multiplication
   * Matrices and vectors, and related operations (determinants etc.)
   * Verbose error messages
   * Arbitrary precision
   * RPN mode
* Result display:
   * Supports all common number bases, as well as negative and non-integer
     radices, sexagesimal numbers, time format, and roman numerals
   * Many customization options: precision, max/min decimals, complex form,
     multiplication sign, etc.
   * Exact or approximate: sqrt(32) returns 4 * sqrt(2) or 5.66
   * Simple and mixed fractions: 4 / 6 * 2 = 1.333... = 4/3 = 1 + 1/3
* Symbolic calculation:
   * E.g. (x + y)^2 = x^2 + 2xy + y^2; 4 "apples" + 3 "oranges"
   * Factorization and simplification
   * Differentiation and integration
   * Can solve most equations and inequalities
   * Customizable assumptions give different results
     (e.g. ln(2x) = ln(2) + ln(x) if x is assumed positive)
* Functions:
   * Hundreds of flexible functions: trigonometry, exponents and logarithms,
     combinatorics, geometry, calculus, statistics, finance, time and date,
     etc.
   * Can easily be created, edited and saved to a standard XML file
* Units:
   * Supports all SI units and prefixes (including binary), as well as imperial
     and other unit systems
   * Automatic conversion: ft + yd + m = 2.2192 m
   * Explicit conversion: 5 m/s to mi/h = 11.18 miles/hour
   * Smart conversion: automatically converts 5 kg*m/s^2 to 5 N
   * Currency conversion with retrieval of daily exchange rates
   * Different name forms: abbreviation, singular, plural (m, meter, meters)
   * Can easily be created, edited and saved to a standard XML file
* Variables and constants:
   * Basic constants: pi, e, etc.
   * Lots of physical constants (with or without units) and properties of
     chemical element
   * CSV file import and export
   * Can easily be created, edited and saved to a standard XML file
   * Flexible - may contain simple numbers, units, or whole expressions
   * Data sets with objects and associated properties in database-like
     structure
* Plotting:
   * Uses Gnuplot
   * Can plot functions or data (matrices and vectors)
   * Ability to save plot to PNG image, postscript, etc.
   * Several customization options
* and more...