Metadata-Version: 1.1
Name: imks
Version: 1.2.2b0
Summary: An ipython extension to make computations with units
Home-page: https://github.com/astrozot/imks
Author: Marco Lombardi
Author-email: marco.lombardi@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Description: iMKS -- An advanced physical quantity calculator
        ================================================
        
        iMKS is an IPython extension to allows the use of physical quantities
        (Value's) in mathematical expressions.  A physical quantity is simply a number
        (typically, a float number) followed by a unit specification.  Within iMKS,
        one can use physical quantities in normal expressions: the result will be a
        physical quantity with the correct unit.
        
        Main Features
        -------------
        
        * Allow the use of physical quantities in mathematical expressions and
          performs consistency checks (so that, for example, an error is generated if
          one tries to add a length with a time).
        
        * Unit systems make it easy to perform conversions of physical quantities in
          different units.  A unit system provides a list of units that should be
          used, alone or in combination, to represent physical values.  Large unit
          systems are effectively useful to define preferences in unit
          representations.
        
        * Completely modular: one can define base units, prefixes, derived units, and
          unit systems using magic commands.  Definitions can be stored in an external
          file for reuse.
        
        * Currencies are considered as physical units.  Automatically retrieves a
          large list of currencies and exchange rates from openexchangerates.org and
          stores them in a file for offline use.
        
        * A list of physical constants can be retrieved from the NIST server
          http://physics.nist.gov/constants and are available as variable in
          interactive mode.
        
        * Add autocompletion for units and constants.
        
        * Allow the use of documentation strings for all quantities (base units,
          prefixes, units, unit systems, and values) using the ... # "doc string"
          notation.
        
        * Optionally allow the use of the standard exponent (caret, ^) in mathematical
          expressions in addition to the Python notation (**).  Also, optionally allow
          the use of unicode characters in identifiers, units, and prefixes.
        
        * Physical quantities are displayed in a proper way (using the LaTeX notation)
          in the notebook.
        
        * Allow the use of "lazy" quantities (variables, units, prefixes) whose value is
          evaluated each time the quantity is required.
        
        * Add an easy way to write documentation strings for any quantity, including
          variables.
        
        * Several mathematical engines can be used: the standard Python math module,
          mpmath, fpmath (mpmath with fixed point arithmetic), numpy, and umath (based
          on the uncertanties package), soerp (higher order error analysis), and mcerp
          (Monte Carlo error analysis).  The engines are used to perform calculations
          involving mathematical functions.
        
        * Engines with error analysis (umath, soerp, and mcerp) will keep track of the
          error propagation within all define variables or physical constants.
        
        * Advanced input transformations and output formats for special quantities such
          as angles in sexagesimal format, times, dates...
          
        Use of iMKS
        -----------
        
        iMKS extends the standard Python syntax in several ways:
        
        * Physical quantities can be entered using the format 9.8[m s^-2] or
          9.8[m/s^2], i.e. with a number followed by a unit specification in brackets.
          In simple cases, quantities can also be entered without the brackets:
          9.8 m/s^2 or 9.8 m s^-2.  This shorter notation however can generate
          ambiguities when the quantity is exponentiated (2m^2 is 2[m^2], while 2[m]^2
          is 4[m^2]) or when a unit has the same name of a variable (12 km/h is a
          speed, 12[km/h] or 12[km] over the Planck constant?).  Moreover, in the
          shorter notation parentheses in units, such as 3[m/(s K)], are not accepted.
        
        * A unit specification follows a standard notation: it is a space-separated
          list of prefixed units followed by an optional exponent.  A prefixed unit is
          a unit with a prefix, such as [km] = prefix k + simple unit m.  The exponent
          in the unit must be a simple number or a fraction: it cannot involve any
          other term (for example, [km^a] is not a valid unit, while [km^2/3] is).  In
          a unit specification one can use an arbitrary number of parentheses; within
          a parenthesis, a single division can be used, as in 9.8[m/s^2]. Additionally,
          a unit specification can contain (at most) one divide (/) sign: in this case
          all units following the sign will have their exponents reversed.
        
        * Physical quantities can be used in expressions with the standard operators.
          
        * The result of an expression can be converted into a different unit by using
          the @ operator::
        
          > 12 m + 3 cm @ km --> 0.01203[km]
        
          Multiple units can be used after the @ operator: in that case, they are
          combined as necessary to obtain the requested quantity::
        
          > 20[m/s] @ [km|hour] --> 72.0[km hour^-1]
        
          When the quantity can be represented using multiple combinations, the
          shorter one is used (i.e., the one that involves the smallest number of
          elements in the list at the right of the @ operator)::
        
          > 20[m/s] @ [km|hour|mph] --> 44.738725841088[mph]
        
        * In some cases, it might be useful to use a variable as a unit.  To do this,
          one can use single quotes around a variable name in the unit specification::
        
          > 5[s 'c'] @ [km] --> 1498962.29[km]
          > 3['g'] --> 29.41995[m s^-2]
        
        * The same operation can be performed in the argument of the at (@) operator::
        
          > 300000[km] @ [s 'c'] --> 1.00069228559446[s 'c']
          > 1e30[kg] @ ['c'|'G'] --> 742.564845009288['c'^2 m 'G'^-1]
          > 1K @ ['k'|eV] --> 8.61733238496096e-5[eV 'k'^-1]
        
        * The output unit, set by the @ operator, can also contain double quoted
          variables.  In this case the value is completely transformed using the
          appropriate combination of the variables, thus removing any appearance of
          the variable in the final result.  This technique generally changes the
          unit of the quantity (and not only the displayed unit)::
        
          > 300000[km] @ [s|"c"] --> 1.00069228559446[s]
          > 1e30[kg] @ ["c"|"G"] --> 742.564845009288[m]
          
        * iMKS understands special units, such as the temperature related ones, that
          are defined together with a zero point, i.e. in terms of an affine
          transformation.  Quantities involving these units alone are called absolute::
        
          > 300[K] @ [Celsius] --> 26.85[Celsius]
          > 122°F @ °C --> 50.0[°C]
        
          Absolute quantities can be made relative (and vice-versa) by using the tilde
          (~) operator.  For example, 300[K] is understood as an absolute temperature,
          but ~300[K] as a relative one (i.e. a temperature difference)::
        
          > ~300[K] @ [Celsius] --> ~300.0[Celsius]
        
          Another example of absolute quantities are calendar dates or datetimes::
        
          > %load_imks_ext calendars
          > Egyptian("today") + 2[day] --> 1 First of Akhet (Thoth) 2764
        
        * The @ operator can be used to force the display of a result using a specific
          prefix or a set of prefixes.  For this, one can just specify the desired
          prefix(es) after the @ inside the brackets::
        
          > 1200[s] @ [k] --> 1.2[ks]
        
          If multiple prefixes are used, the most convenient one is selected::
          
          > 1200[s] @ [k|M] --> 1.2[ks]
        
          A dot (.) can be used to specify that no prefix is also accepted; a star (*)
          to select all known prefixes::
        
          > 8[m] @ [.|k|M] --> 8.0[m]
          > 0.12[cm] @ [m|*] --> 1.2[mm]
        
          Note that if a prefix has the same name as a valid unit, one needs to use a
          star after the prefix name, to indicate that the name must be understood as a
          prefix rather than a unit::
        
          > 12[cm] @ [m] --> 0.12[m]
          > 12[cm] @ [m*] --> 120.0[mm]
        
          The star can also be used within a single unit to indicate that an arbitrary
          prefix is allowed::
        
          > 1200[m] @ [*m] --> 12.0[km]
        
        * Unit systems work just like list of units that can be used after the @
          operator::
        
          > 72[km/hour] @ [SI] --> 20.0[m s^-1]
        
          A star prepended or appended to a unit system indicates that a prefix among
          all known ones can be used to make the expression simpler; the same effect is
          obtained if the star is specified within the brackets with the unit system::
        
          > 5600[K] @ [*SI] --> 5.6[kK]
          > 5600[K] @ [SI|*] --> 5.6[kK]
        
        * Unit systems containing multiple units are especially convenient to reduce
          expressions to the simplest form::
        
          > %newsystem easy=[m|s|kg|K|A|lx|mol|EUR|N|J|W|Pa|C|V|ohm|F|H|T|lx]
          > 6.63e-34[kg m^2 s^-1] @ [easy] --> 6.63e-34[s J]
        
        * Unit systems can also contain variable units: this is especially useful to
          define natural unit systems::
        
          > %newsystem planck=["c"|"hbar"|"G"|"ke"|"k"] # "Planck's natural system"
          > 1[m] @ [planck] --> 6.18735589978243e+34
        
          The reverse conversion can be performed by indicating the output unit at the
          beginning of the unit specification, and by adding the unit system::
        
          > 6.2e34 @ [m|planck] --> 1.00204353853607[m]
          > 1 @ [kg|planck] --> 2.17650925244531e-8[kg]
        
          Note that this notation is an exception to the general rule that pure numbers
          are not influenced by unit specifications.  Note also that the order is
          relevant here: first the final unit, than all the natural system::
        
          > 1 @ [planck|kg] --> 1
          > 1 @ [kg/m|"c"|"G"] --> 1.34668373640485e+27[kg m^-1]
          > 1 @ [kg|m|"c"|"G"] --> 1
        
        * When a natural unit system is used enclosed within single or double quotes,
          all the quotes of the unit system are replaced by the one used: hence,
          ['planck'] is identical to ['c'|'hbar'|'G'|'ke'|'k'].  This is useful to
          explicitly show all the converting factors in the result::
        
          > 1 @ [kg|'planck'] --> 2.17650925244531e-8['G'^1/2 'c'^-1/2 'hbar'^-1/2 kg]
          > 2.17650925244531e-8['G'^1/2 'c'^-1/2 'hbar'^-1/2 kg] --> 0.999999999999999
          
        * The @ operator can also be used in variable definitions to set the default
          display unit to be used for a variable::
        
          > v = 20[m/s] @ [km|hour]
          > v --> 72.0[km hour^-1]
        
        * When an engine with error analysis is used (umath, soerp, or mcerp), the
          special syntax value +/- error can be used to input quantities with errors::
        
          > %imks -c umath
          > %reset
          > v = (3+/-0.1)[m/s]
          > v^2 @ [mph] --> (45.0+/-3.0)[mph^2]
        
          Uncertainties are silently ignored with engines not supporting them.  The
          same quantity, (3+/-0.1)[m/s] can also be entered without parentheses,
          3+/-0.1m/s, using the ± sign instead of the +/-, or using a shorter notation
          3.0(1)[m/s] (see uncertainties for a list of formats accepted). 
        
        * Correlation among variables is automatically taken into account::
        
          > w = (3+/-0.1)[m/s]
          > v + w --> (6.00+/-0.14)[m s^-1]
          > v + v --> (6.00+/-0.20)[m s^-1]
        
        * Input transformer make it easy to enter special quantities such as
          sexagesimal angles or times::
        
          > 18d 24' 32" --> 0.321295722745
          > 12h 34m 56s --> 45296.0[s]
        
          The reverse is also possible using output formats::
        
          > 1[rad] @ [dms] --> 57d 17' 44.806s"
          > 10[ks] @ [hms] --> 2h 46m 40s
          
        * Documentation strings can be entered even for variables::
        
          > v = 50[km/hour] # "Standard maximum speed within towns"
        
        
        Configuration file
        ------------------
        
        When launched, iMKS load definitions from the configuration file Startup.imks.
        This file is searched in the current directory, and if not found in the
        ~/.imks directory.  The file should contain the standard definitions that one
        is likely to need for any computation.  Typically the file uses the following
        magic commands:
        
        %newbaseunit <name>
          Define a new base unit.  Base units are the building blocks for all
          subsequent units definitions.  A base unit does not have a value: for
          example, one cannot express a meter in any other unit if no unit of length
          is known.
        
        %newbasecurrency <name>
          Define a new base currency, used for all currency conversions.  A base
          currency is also a base unit.
        
        %newprefix <name>=<expression>
          Define a new prefix.  The <expression> value evaluate to a simple number.
        
        %newunit <name>=<expression>
          Define a new unit.  <expression> should evaluate to a Value'd number.  To
          define a new absolute unit, expression should evaluate to a 2-tuple with
          identical units (indicating the zero-point, and the scale).
        
        %newsystem <name>=[u1], [u2], ...
          Define a new unit system.  A unit system is simply a list of units.
        
        %defaultsystem <name>
          Set the unit system to use in case no @ is used.
        
        %newtransformer <name>="regex":<transformer>
          Define a new input transformer: the regular expression regex is applied to
          each input line, and if a match is found the <transformer> function is
          called together with all named matching groups which must return the
          transformed input.
        
        %newformat <name>=<transformer>
          Define a new output format.  When <name> is entered (alone) in a unit
          specification, <transformer> is called with the result of the expression: it
          must return a string that will be displayed on the screen.
          
        
        Other magic commands
        --------------------
        
        %imks [<options>]
          Show this help page or set configuration options for iMKS.
        
        %delprefix, %delunit, %delsystem, %deltransformer, or %delformat <name>
          Delete a previously define prefix, unit, unit system, transformer, or format.
        
        %lazy <name>=<expression>
          Define the variable <name> as <expression> lazily: that is, <expression> is
          evaluated only when <name> is used or displayed.  This is implemented by
          making <name> a function with no arguments, and by automatically adding a
          function call name() when name is used in the input.
        
        %dellazy <name>
          Delete a previously defined %lazy variable.
        
        %lazyvalue <name>=<expression>
          Define the variable <name> as <expression> lazily: that is, <expression> is
          evaluated only when <name> is used or displayed.  This only works for simple
          values, and not for more general objects such as %lazy.
        
        %lazyprefix <name>=<expression>
          Define a lazy prefix (whose <expression> is evaluate only when the prefix is
          used).
        
        %lazyunit <name>=<expression>
          Define a lazy unit (whose <expression> is evaluated only when the unit is
          used).
        
        %compatible <stuff>
          Find out the known variables or units that are compatible to <stuff>.
          <stuff> can be either a unit (in brackets) or an expression.
        
        %load_imks <filename>
          Load an external <filename> with definitions in iMKS format.
        
        %load_imks_ext <filename>
          Load an imks extension.
        
        %uinfo <name>
          Display an help page for a prefix, unit, or unit system.  This is the
          equivalent of %pinfo (which works for objects in the user namespace).  A
          short notation for %uinfo <name> is <name>! (i.e., the name of an imks
          object followed by the exclamation mark).  When used with the -a flag,
          as in %uinfo -a <text>, shows all quantities with <text> in their docstring.
          The same effect is achieved using <text>!!
        
        %pickle <filename>
          Save all current variables into a filename, in the Python pickle format.
        
        %unpickle <filename>
          Load all previously %pickle'd variables from a filename.
        
        %reset
          Perform a full reset of the iMKS interpreter.
        
        
        Extensions
        ----------
        
        iMKS comes with a number of extensions that define new commands, new
        variables, or new units.  Extensions are loaded with the command
        %load_imks_ext.  The currently defined extensions are
        
        * calendars: defines several new functions, one for each calendar (for example
          Gregorian, Julian, Roman, Egyptian...).  Each calendar accepts a date in
          several formats: as an integer (number of days from 1 January 1 C.E.), one of
          the strings "today", "tomorrow", "yesterday", or "now", as a year followed by
          a holiday name such as Gregorian(2017, "Easter"), or as a full year (with a
          number of arguments depending on the calendar).  Optionally, one can also
          add a time, counted from midnight, noon, sunset, or sunrise depending on the
          specification of the calendar.  When calendars are loaded, one can input a
          date using dot-separated integers.  For example, 1973.5.7 is interpreted as
          May 7th, 1973.  The default calendar used to interpret dates is the Gregorian
          one, but it can be changed using %imks -d <calendar>.  A date can be also
          followed by a time, in the format hh:mm[:ss.d].
        
        * constants: loads a large list of constants from the NIST database.  Constants
          are then inserted into the variable const, a dictionary.
        
        * currencies: loads a large list of currencies from the online database
          openexachangerages.org.  Currencies are then used as usual units.  Note that
          in order this to work, you first need to set a variable called
          openexchangerates_id as a string holding your id.
        
        * geolocation: defines two functions to set the current geographic location and
          to retrieve it.
        
        * jpl: loads the JPL database and creates two dictionaries, planets and moons,
          where it stores the physical and orbital data.  Additionally, it defines a
          function called minorplanet, which allows one to search a minor body database.
        
        * wiki: experimental interface to Wikipedia.
        
          
        Internals
        ---------
        
        Internally, iMKS works by converting an input string into Python expressions.
        The following rules are used:
        
        * Physical quantities are converted into Value's::
        
          > 72[km hour^-1] --> Value(72,"km hour^-1")
        
        * The @ operator is converted into the | operator, and what follows is put in
          a unit System::
        
          > 72[km hour^-1] @ [m], [s] --> Value(72,"km hour^-1") | System("m", "s")
        
        * Quoted comments, used to enter documentation strings, are transformed into
          the & operator followed by a Doc object::
        
          > a=2 # "Simple string" --> a=2 & Doc("Simple string")
        
        * Normal Python operator precedence applies to @=| and to #=&: that is, @ has
          a quite low precedence, which makes it possible to write expressions like::
        
          > v = 15[m/s] + 10[m]/2[s] @ [km/hour]
        
          with the unit specification after @ applying to the result of the other
          operations.  Note also that since ``&`` binds stronger than ``|``, in theory a
          # documentation string after the @ operator would apply to the unit
          specification, and not the the expression: however, this is handled
          internally by System (that is, the documentation string that System gets
          from the #=& operator is actually transferred to the result of the unit
          conversion).
        
        * The ! operator, if used at the end of a string, is converted into a %uinfo
          magic (this is similar to the ? operator, that is converted by ipython into
          a %pinfo magic)::
        
          > hour! --> %uinfo hour
        
          If used alone, instead, it is equivalent to %imks -h.  Note that the same !
          symbol can still be used to perform shell operations if used at the beginning
          of a line::
        
          > !ls
        
          Two exclamation marks are converted into the %uinfo -a magic::
        
          > mile!! --> mile, mph, nmi, mi
        
        * Unicode characters appearing outside strings are converted into strings of 
          the form _uTf_xx_xx_xx..., where each xx is the hexadecimal representation
          of a byte of the character in UTF8 encoding.
        
        * Value, System, and Doc are defined in units.py, and for these objects the
          standard operators are redefined to include tracking of physical units.
        
        * If necessary, one can directly use the Value, System, and Doc objects to
          make more complicated expressions.
        
        * The know prefixes, units, and unit systems are stored in the dictionaries
          prefixes, units, and systems, freely accessible from the user space.
        
Keywords: units physics calculator
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Framework :: IPython
Classifier: Topic :: Scientific/Engineering :: Physics
