=========================================================================
numericalunits: Units and dimensional analysis compatible with everything
=========================================================================
`Package homepage at PyPI <http://pypi.python.org/pypi/numericalunits>`_ --
`Source code at github <http://github.com/sbyrnes321/numericalunits>`_ --
Written by `Steve Byrnes <http://sjbyrnes.com>`_
This package implements units and dimensional analysis in an unconventional
way that has the following unique advantages:
* **Compatible with everything:** Compatible with virtually any numerical
calculation routine, including numpy and scipy, and even including routines
not written in Python! That means, for example, if you have a decades-old
closed-source C routine for numerical integration, you can pass it a
quantity with units of velocity and an integration range with units of
time, and the final answer will magically have units of distance. This
extreme compatibility is possible because if the variable ``x`` represents
a quantity with dimensions (like "3.3 kg"), ``x`` is actually stored
internally as an ordinary floating-point number. The dimension is
encoded in the value as a multiplicative factor. When two numbers are
multiplied, their dimensions are automatically multiplied, and so on.
* **Modular and non-intrusive:** When you input data, you say what units
they are in. When you display results, you say what units you want to
display them in. These steps are very little trouble, and in fact help you
create nice, self-documenting code. Other than that, you have to do nothing
at all to pass dimensionful quantities into and out of any already-written
programs or routines.
* **Powerful tool for debugging:** Not *all* calculation mistakes cause
violations of dimensional analysis, but *most* do--for example, if you
accidentally multiply two lengths instead of adding them, the result will
have the wrong dimension. If you use this package, it will alert you to
these sorts of mistakes.
* **Zero storage overhead**
* **Zero calculation overhead**
These great features come with the disadvantage that the interface is less
*slick* than other unit packages. If you have a quantity with units, you
cannot directly see what the units are. You are supposed to already know
what the units are, and then the package will tell you whether you made a
mistake. Even worse, you only get alerted to the mistake after running a
calculation all the way through twice.
Therefore the package is *not* suggested for students exploring how units work.
It *is* suggested for engineering and science professionals who want to make
their code more self-documenting and self-debugging.
Installation
============
You can install from PyPI: ::
pip install numericalunits
Alternatively---since it's a single module that requires no setup or
compilation---you can download ``numericalunits.py`` from `PyPI
<http://pypi.python.org/pypi/numericalunits>`_ or `github
<http://github.com/sbyrnes321/numericalunits>`_ and use it directly.
Usage and examples
==================
To assign a unit to a quantity, **multiply** by the unit, e.g.
``my_length = 100 * mm``. (In normal text you would write "100 mm", but
unfortunately Python does not have "implied multiplication".)
To express a dimensionful quantity in a certain unit, **divide** by that unit,
e.g. when you see ``my_length / cm``, you pronounce it "my_length expressed
in cm".
Unit errors, like trying to add a length to a mass, will not *immediately*
announce themselves as unit errors. Instead, you need to run the whole
calculation twice (in a new Python session each time). If you get the
same final answers both times, then congratulations, all your calculations
are almost guaranteed to pass dimensional analysis! If you get different
answers every time you run, then you made a unit error! It is up to you to
figure out where and what the error is.
**Example 1:** What is 5 mL expressed in cubic nanometers?::
from numericalunits import mL, nm
x = 5 * mL # "Read: x is equal to 5 milliliters"
print(x / nm**3) # "Read: x expressed in cubic nanometers is..." --> 5e21
**Example 2:** An electron is in a 1e5 V/cm electric field. What is its
acceleration? (Express the answer in m/s².) ::
from numericalunits import V, cm, e, me, m, s
Efield = 1e5 * (V / cm)
force = e * Efield # (e is the elementary charge)
accel = force / me # (me is the electron mass)
print(accel / (m / s**2)) # Answer --> 1.7588e18
**Example 3:** You measured a voltage as a function of the position of dial:
10 volts when the dial is at 1cm, 11 volts when the dial is at 2cm, etc.
etc. Interpolate from this data to get the expected voltage when the dial is
at 41mm, and express the answer in mV. ::
from numericalunits import cm, V, mm, mV
from numpy import array
from scipy.interpolate import interp1d
voltage_data = array([[1 * cm, 10 * V],
[2 * cm, 11 * V],
[3 * cm, 13 * V],
[4 * cm, 16 * V],
[5 * cm, 18 * V]])
f = interp1d(voltage_data[:,0], voltage_data[:,1])
print(f(41 * mm) / mV) # Answer --> 16200
**Example 4:** A unit mistake ... what is 1 cm expressed in atmospheres? ::
from numericalunits import cm, atm
print((1 * cm) / atm) # --> a randomly-varying number
# The answer randomly varies every time you run this (in a new Python
# session), indicating that you are violating dimensional analysis.
How it works
============
A complete set of independent base units (meters, kilograms, seconds,
coulombs, kelvins) are defined as randomly-chosen positive floating-point
numbers. All other units and constants are defined in terms of those. In a
dimensionally-correct calculation, the units all cancel out, so the final
answer is deterministic, not random. In a dimensionally-incorrect
calculations, there will be random factors causing a randomly-varying final
answer.
Included units and constants
============================
Includes a variety of common units, both SI and non-SI, everything from
frequency to magnetic flux. Also includes common physical constants like
Planck's constant and the speed of light. Browse the source code to see a
complete list. It is very easy to add in any extra units and constants that
were left out.
Notes
=====
Notes on implementation and use
-------------------------------
* **What does it mean to "run the calculation again in a new Python
session?"** You know that you've started a new Python session if all
the variable definitions have been forgotten. Three examples: In Spyder, each "Console"
tab is its own session. In Jupyter, make a new Python session by selecting
"Restart kernel". From the command line, each time you type
``python blah.py``, you are opening a new Python session.
* For little, self-contained calculations (a few lines that are all within a
single module), it is possible to check the units without opening a new Python
session: Run the function ``numericalunits.reset_units()`` at the beginning of
the calculation before any variables are defined; then check for
dimensional errors by re-running the whole calculation (including the
``reset_units()`` part). Note that if you are using ``from``-style imports,
like ``from numericalunits import cm``, you need to put them *after*
``reset_units()`` in the code.
* While debugging a program, it may be annoying to have intermediate values
in the calculation that randomly vary every time you run the program. In
this case, you can use ``reset_units('SI')`` instead of the normal
``reset_units()``. This puts all dimensionful variables in standard (MKS)
SI units: All times are in seconds, all lengths are in meters, all forces
are in newtons, etc. Alternatively, ``reset_units(123)`` uses ``123`` as
the seed for the random-number generator. Obviously, in these modes, you
will *not* get any indication of dimensional-analysis errors. As above,
if you are going to use any version of ``reset_units()``, make sure you do
it before any dimensionful variable is defined in any module.
* There are very rare, strange cases where the final answer does not seem to
randomly vary even though there was a dimensional-analysis violation: For
example, the expression ``(1 + 1e-50 * cm / atm)`` fails dimensional
analysis, so if you calculate it the answer is randomly-varying. But, it is
only randomly varying around the 50th decimal point, so the variation is
hidden from view. You would not notice it as an error.
* Since units are normal Python ``float``-type numbers, they follow the normal
casting rules. For example, ``2 * cm`` is a python ``float``, not an ``int``.
This is usually what you would want and expect.
* You can give a dimension to complex numbers in the same way as real
numbers--for example ``(2.1e3 + 3.9e4j) * ohm``.
* Requires Python 3. (For Python 2 compatibility, install numericalunits
version 1.23 or earlier.)
* If you find bugs, please tell me by `email <http://sjbyrnes.com>`_ or
`github issue board <https://github.com/sbyrnes321/numericalunits/issues>`_.
* If you get overflows or underflows, you can edit the unit initializations.
For example, the package sets the meter to a random numerical value between 0.1
and 10. Therefore, if you're doing molecular simulation, most lengths you
use will be tiny numbers. You should probably set the meter instead to be
between, say, a random numerical value between 1e8 and 1e10.
* Some numerical routines use a default *absolute* tolerance, rather than
relative tolerance, to decide convergence. This can cause the calculation
result to randomly vary even though there is no dimensional analysis error.
When this happens, you should set the absolute tolerance to a value with the
appropriate units. Alternatively, you can scale the data before running the
algorithm and scale it back afterwards. Maybe this sounds like a hassle, but
it's actually a benefit: If your final result is very sensitive to some
numerical tolerance setting, then you really want to be aware of that.
Notes on unit definitions
-------------------------
* For electromagnetism, all units are intended for use in SI formulas. If
you plug them into cgs-gaussian electromagnetism formulas, or cgs-esu
electromagnetism formulas, etc., you will get nonsense results.
* The package does not keep track of "radians" as an independent unit
assigned a random number. The reason is that the "radians" factor does not
always neatly cancel out of formulas.
* The package does not keep track of "moles" as an independent unit assigned
a random number; instead ``mol`` is just a pure number (~6e23), like you
would say "dozen"=12. That means: (1) gram/mol is exactly the same as amu,
and Boltzmann constant is exactly the same as the ideal gas constant, and so
on. (2) You should rarely need to use Avogadro's number ``NA`` -- it is just a
synonym of ``mol`` (``NA = mol ~ 6e23``). Here are a few examples using moles: ::
from numericalunits import um, uM, kcal, mol, fmol, J
# There are eight copies of a protein inside a yeast nucleus of volume
# 3 cubic microns. What is the concentration of the protein, in micromolar (uM)?
print((8 / (3 * um**3)) / uM) # Answer --> 0.0044
# 5 kcal / mol is how many joules?
print((5 * kcal / mol) / J) # Answer --> 3.47e-20
# How many molecules are in 2.3 femtomoles?
print(2.3 * fmol) # Answer --> 1.39e9
* The package cannot convert temperatures between Fahrenheit, Celsius, and
kelvin. The reason is that these scales have different zeros, so the units
cannot be treated as multiplicative factors. It is, however, possible to
convert temperature *intervals*, via the units ``degCinterval`` (which is a
synonym of kelvin, ``K``) and ``degFinterval``.
Raw data
{
"_id": null,
"home_page": "http://pypi.python.org/pypi/numericalunits",
"name": "numericalunits",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "units,quantities,physical constants,dimensional analysis",
"author": "Steven J. Byrnes",
"author_email": "steven.byrnes@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/62/82/73c8b55014cae2462d04a957f468a95f7a262196325343709fc6c7315191/numericalunits-1.25.tar.gz",
"platform": "",
"description": "=========================================================================\nnumericalunits: Units and dimensional analysis compatible with everything\n=========================================================================\n\n`Package homepage at PyPI <http://pypi.python.org/pypi/numericalunits>`_ -- \n`Source code at github <http://github.com/sbyrnes321/numericalunits>`_ -- \nWritten by `Steve Byrnes <http://sjbyrnes.com>`_\n\nThis package implements units and dimensional analysis in an unconventional \nway that has the following unique advantages:\n\n* **Compatible with everything:** Compatible with virtually any numerical \n calculation routine, including numpy and scipy, and even including routines \n not written in Python! That means, for example, if you have a decades-old \n closed-source C routine for numerical integration, you can pass it a \n quantity with units of velocity and an integration range with units of \n time, and the final answer will magically have units of distance. This \n extreme compatibility is possible because if the variable ``x`` represents \n a quantity with dimensions (like \"3.3 kg\"), ``x`` is actually stored \n internally as an ordinary floating-point number. The dimension is \n encoded in the value as a multiplicative factor. When two numbers are \n multiplied, their dimensions are automatically multiplied, and so on. \n\n\n* **Modular and non-intrusive:** When you input data, you say what units \n they are in. When you display results, you say what units you want to \n display them in. These steps are very little trouble, and in fact help you \n create nice, self-documenting code. Other than that, you have to do nothing \n at all to pass dimensionful quantities into and out of any already-written \n programs or routines.\n\n* **Powerful tool for debugging:** Not *all* calculation mistakes cause \n violations of dimensional analysis, but *most* do--for example, if you \n accidentally multiply two lengths instead of adding them, the result will \n have the wrong dimension. If you use this package, it will alert you to \n these sorts of mistakes.\n\n* **Zero storage overhead**\n\n* **Zero calculation overhead**\n\nThese great features come with the disadvantage that the interface is less \n*slick* than other unit packages. If you have a quantity with units, you \ncannot directly see what the units are. You are supposed to already know \nwhat the units are, and then the package will tell you whether you made a \nmistake. Even worse, you only get alerted to the mistake after running a \ncalculation all the way through twice.\n\nTherefore the package is *not* suggested for students exploring how units work.\nIt *is* suggested for engineering and science professionals who want to make\ntheir code more self-documenting and self-debugging.\n\nInstallation\n============\n\nYou can install from PyPI: ::\n\n pip install numericalunits\n\nAlternatively---since it's a single module that requires no setup or \ncompilation---you can download ``numericalunits.py`` from `PyPI \n<http://pypi.python.org/pypi/numericalunits>`_ or `github \n<http://github.com/sbyrnes321/numericalunits>`_ and use it directly.\n\nUsage and examples\n==================\n\nTo assign a unit to a quantity, **multiply** by the unit, e.g.\n``my_length = 100 * mm``. (In normal text you would write \"100 mm\", but\nunfortunately Python does not have \"implied multiplication\".)\n\nTo express a dimensionful quantity in a certain unit, **divide** by that unit,\ne.g. when you see ``my_length / cm``, you pronounce it \"my_length expressed\nin cm\".\n\nUnit errors, like trying to add a length to a mass, will not *immediately*\nannounce themselves as unit errors. Instead, you need to run the whole\ncalculation twice (in a new Python session each time). If you get the\nsame final answers both times, then congratulations, all your calculations\nare almost guaranteed to pass dimensional analysis! If you get different\nanswers every time you run, then you made a unit error! It is up to you to\nfigure out where and what the error is.\n\n**Example 1:** What is 5 mL expressed in cubic nanometers?::\n\n from numericalunits import mL, nm\n x = 5 * mL # \"Read: x is equal to 5 milliliters\"\n print(x / nm**3) # \"Read: x expressed in cubic nanometers is...\" --> 5e21\n\n**Example 2:** An electron is in a 1e5 V/cm electric field. What is its\nacceleration? (Express the answer in m/s\u00c2\u00b2.) ::\n\n from numericalunits import V, cm, e, me, m, s\n Efield = 1e5 * (V / cm)\n force = e * Efield # (e is the elementary charge)\n accel = force / me # (me is the electron mass)\n print(accel / (m / s**2)) # Answer --> 1.7588e18\n\n**Example 3:** You measured a voltage as a function of the position of dial: \n10 volts when the dial is at 1cm, 11 volts when the dial is at 2cm, etc. \netc. Interpolate from this data to get the expected voltage when the dial is \nat 41mm, and express the answer in mV. ::\n\n from numericalunits import cm, V, mm, mV\n from numpy import array\n from scipy.interpolate import interp1d\n voltage_data = array([[1 * cm, 10 * V],\n [2 * cm, 11 * V],\n [3 * cm, 13 * V],\n [4 * cm, 16 * V],\n [5 * cm, 18 * V]])\n f = interp1d(voltage_data[:,0], voltage_data[:,1])\n print(f(41 * mm) / mV) # Answer --> 16200\n\n\n**Example 4:** A unit mistake ... what is 1 cm expressed in atmospheres? ::\n\n from numericalunits import cm, atm\n print((1 * cm) / atm) # --> a randomly-varying number\n # The answer randomly varies every time you run this (in a new Python\n # session), indicating that you are violating dimensional analysis.\n\nHow it works\n============\n\nA complete set of independent base units (meters, kilograms, seconds, \ncoulombs, kelvins) are defined as randomly-chosen positive floating-point \nnumbers. All other units and constants are defined in terms of those. In a \ndimensionally-correct calculation, the units all cancel out, so the final \nanswer is deterministic, not random. In a dimensionally-incorrect \ncalculations, there will be random factors causing a randomly-varying final \nanswer.\n\nIncluded units and constants\n============================\n\nIncludes a variety of common units, both SI and non-SI, everything from \nfrequency to magnetic flux. Also includes common physical constants like \nPlanck's constant and the speed of light. Browse the source code to see a \ncomplete list. It is very easy to add in any extra units and constants that\nwere left out.\n\nNotes\n=====\n\nNotes on implementation and use\n-------------------------------\n\n* **What does it mean to \"run the calculation again in a new Python\n session?\"** You know that you've started a new Python session if all\n the variable definitions have been forgotten. Three examples: In Spyder, each \"Console\"\n tab is its own session. In Jupyter, make a new Python session by selecting\n \"Restart kernel\". From the command line, each time you type\n ``python blah.py``, you are opening a new Python session. \n\n* For little, self-contained calculations (a few lines that are all within a\n single module), it is possible to check the units without opening a new Python\n session: Run the function ``numericalunits.reset_units()`` at the beginning of\n the calculation before any variables are defined; then check for\n dimensional errors by re-running the whole calculation (including the\n ``reset_units()`` part). Note that if you are using ``from``-style imports,\n like ``from numericalunits import cm``, you need to put them *after*\n ``reset_units()`` in the code.\n\n* While debugging a program, it may be annoying to have intermediate values \n in the calculation that randomly vary every time you run the program. In \n this case, you can use ``reset_units('SI')`` instead of the normal \n ``reset_units()``. This puts all dimensionful variables in standard (MKS)\n SI units: All times are in seconds, all lengths are in meters, all forces\n are in newtons, etc. Alternatively, ``reset_units(123)`` uses ``123`` as\n the seed for the random-number generator. Obviously, in these modes, you\n will *not* get any indication of dimensional-analysis errors. As above,\n if you are going to use any version of ``reset_units()``, make sure you do\n it before any dimensionful variable is defined in any module.\n\n* There are very rare, strange cases where the final answer does not seem to \n randomly vary even though there was a dimensional-analysis violation: For \n example, the expression ``(1 + 1e-50 * cm / atm)`` fails dimensional \n analysis, so if you calculate it the answer is randomly-varying. But, it is \n only randomly varying around the 50th decimal point, so the variation is\n hidden from view. You would not notice it as an error.\n\n* Since units are normal Python ``float``-type numbers, they follow the normal\n casting rules. For example, ``2 * cm`` is a python ``float``, not an ``int``.\n This is usually what you would want and expect.\n\n* You can give a dimension to complex numbers in the same way as real \n numbers--for example ``(2.1e3 + 3.9e4j) * ohm``.\n\n* Requires Python 3. (For Python 2 compatibility, install numericalunits\n version 1.23 or earlier.)\n\n* If you find bugs, please tell me by `email <http://sjbyrnes.com>`_ or \n `github issue board <https://github.com/sbyrnes321/numericalunits/issues>`_.\n\n* If you get overflows or underflows, you can edit the unit initializations.\n For example, the package sets the meter to a random numerical value between 0.1\n and 10. Therefore, if you're doing molecular simulation, most lengths you\n use will be tiny numbers. You should probably set the meter instead to be\n between, say, a random numerical value between 1e8 and 1e10.\n\n* Some numerical routines use a default *absolute* tolerance, rather than\n relative tolerance, to decide convergence. This can cause the calculation\n result to randomly vary even though there is no dimensional analysis error.\n When this happens, you should set the absolute tolerance to a value with the\n appropriate units. Alternatively, you can scale the data before running the\n algorithm and scale it back afterwards. Maybe this sounds like a hassle, but\n it's actually a benefit: If your final result is very sensitive to some\n numerical tolerance setting, then you really want to be aware of that.\n\nNotes on unit definitions\n-------------------------\n\n* For electromagnetism, all units are intended for use in SI formulas. If \n you plug them into cgs-gaussian electromagnetism formulas, or cgs-esu \n electromagnetism formulas, etc., you will get nonsense results.\n\n* The package does not keep track of \"radians\" as an independent unit \n assigned a random number. The reason is that the \"radians\" factor does not \n always neatly cancel out of formulas.\n\n* The package does not keep track of \"moles\" as an independent unit assigned \n a random number; instead ``mol`` is just a pure number (~6e23), like you\n would say \"dozen\"=12. That means: (1) gram/mol is exactly the same as amu,\n and Boltzmann constant is exactly the same as the ideal gas constant, and so\n on. (2) You should rarely need to use Avogadro's number ``NA`` -- it is just a\n synonym of ``mol`` (``NA = mol ~ 6e23``). Here are a few examples using moles: ::\n\n from numericalunits import um, uM, kcal, mol, fmol, J\n\n # There are eight copies of a protein inside a yeast nucleus of volume\n # 3 cubic microns. What is the concentration of the protein, in micromolar (uM)?\n print((8 / (3 * um**3)) / uM) # Answer --> 0.0044\n\n # 5 kcal / mol is how many joules?\n print((5 * kcal / mol) / J) # Answer --> 3.47e-20\n\n # How many molecules are in 2.3 femtomoles?\n print(2.3 * fmol) # Answer --> 1.39e9\n\n* The package cannot convert temperatures between Fahrenheit, Celsius, and \n kelvin. The reason is that these scales have different zeros, so the units \n cannot be treated as multiplicative factors. It is, however, possible to \n convert temperature *intervals*, via the units ``degCinterval`` (which is a \n synonym of kelvin, ``K``) and ``degFinterval``.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package that lets you define quantities with units, which can then be used in almost any numerical calculation in any programming language. Checks that calculations pass dimensional analysis, performs unit conversions, and defines physical constants.",
"version": "1.25",
"split_keywords": [
"units",
"quantities",
"physical constants",
"dimensional analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7bf36052a42af74a41b17f78f98fcf47d797a2ac5a1d96368f7aa11febd94dad",
"md5": "033cb3f6cdf9b23e7aaf9f938a2bdcee",
"sha256": "5919ce8ad0009dbd73041698bb53c12cb9c1f7374e56131e1bbb6504791ae6e7"
},
"downloads": -1,
"filename": "numericalunits-1.25-py3-none-any.whl",
"has_sig": false,
"md5_digest": "033cb3f6cdf9b23e7aaf9f938a2bdcee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13723,
"upload_time": "2020-11-08T02:00:36",
"upload_time_iso_8601": "2020-11-08T02:00:36.534165Z",
"url": "https://files.pythonhosted.org/packages/7b/f3/6052a42af74a41b17f78f98fcf47d797a2ac5a1d96368f7aa11febd94dad/numericalunits-1.25-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "628273c8b55014cae2462d04a957f468a95f7a262196325343709fc6c7315191",
"md5": "6b0f9b34260df691540a19c049328848",
"sha256": "c32a482adae818a1a8d6c799bf9fb153326461d490c0de9deab9c694a6537eec"
},
"downloads": -1,
"filename": "numericalunits-1.25.tar.gz",
"has_sig": false,
"md5_digest": "6b0f9b34260df691540a19c049328848",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16027,
"upload_time": "2020-11-08T02:00:37",
"upload_time_iso_8601": "2020-11-08T02:00:37.840875Z",
"url": "https://files.pythonhosted.org/packages/62/82/73c8b55014cae2462d04a957f468a95f7a262196325343709fc6c7315191/numericalunits-1.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-11-08 02:00:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "numericalunits"
}
JSON