Improved documentation
This commit is contained in:
Hernan Grecco
parent
c5fdea94c2
commit
417f248767
|
|
@ -1,5 +1,5 @@
|
|||
<h3>About Pint</h3>
|
||||
Units
|
||||
Units in Python.
|
||||
You are currently looking at the documentation of version {{ version }}.
|
||||
<h3>Other Formats</h3>
|
||||
<p>
|
||||
|
|
|
|||
|
|
@ -2,3 +2,21 @@
|
|||
<img src="{{ pathto('_images/logo-full.jpg', 1) }}" alt="Logo" style="width:80%;height:80%"/>
|
||||
</a></p>
|
||||
|
||||
<h3>About Pint</h3>
|
||||
Units in Python.
|
||||
You are currently looking at the documentation of version {{ version }}.
|
||||
<h3>Other Formats</h3>
|
||||
<p>
|
||||
You can download the documentation in other formats as well:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a href="https://media.readthedocs.org/pdf/pint/latest/pint.pdf">as PDF</a>
|
||||
<li><a href="https://media.readthedocs.org/htmlzip/pint/latest/pint.zip">as ePub</a>
|
||||
<li><a href="https://media.readthedocs.org/epub/pint/latest/pint.epub">as zipped HTML</a>
|
||||
</ul>
|
||||
<h3>Useful Links</h3>
|
||||
<ul>
|
||||
<li><a href="https://pypi.python.org/pypi/Pint/">Pint @ PyPI</a></li>
|
||||
<li><a href="https://github.com/hgrecco/lantz">Code in GitHub</a></li>
|
||||
<li><a href="https://github.com/hgrecco/pint/issues">Issue Tracker</a></li>
|
||||
</ul>
|
||||
|
|
|
|||
|
|
@ -1,19 +1,20 @@
|
|||
|
||||
<h3>Related Topics</h3>
|
||||
<ul>
|
||||
<li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul>
|
||||
{%- for parent in parents %}
|
||||
<li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul>
|
||||
{%- endfor %}
|
||||
{%- if prev %}
|
||||
<li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter')
|
||||
}}">{{ prev.title }}</a></li>
|
||||
{%- endif %}
|
||||
{%- if next %}
|
||||
<li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter')
|
||||
}}">{{ next.title }}</a></li>
|
||||
{%- endif %}
|
||||
{%- for parent in parents %}
|
||||
</ul></li>
|
||||
{%- endfor %}
|
||||
</ul></li>
|
||||
<li><a href="{{ pathto(master_doc) }}">Documentation overview</a></li>
|
||||
{%- for parent in parents %}
|
||||
<li><a href="{{ parent.link|e }}">{{ parent.title }}</a><li>
|
||||
</ul>
|
||||
{%- endfor %}
|
||||
{%- if prev %}
|
||||
<p>
|
||||
<b>Previous</b><br/>
|
||||
<a href="{{ prev.link|e }}" title="{{ _('previous chapter') }}">{{ prev.title }}</a>
|
||||
</p>
|
||||
{%- endif %}
|
||||
{%- if next %}
|
||||
<p>
|
||||
<b>Next</b><br/>
|
||||
<a href="{{ next.link|e }}" title="{{ _('next chapter') }}">{{ next.title }}</a>
|
||||
</p>
|
||||
{%- endif %}
|
||||
|
|
|
|||
|
|
@ -54,6 +54,7 @@ User Guide
|
|||
numpy
|
||||
nonmult
|
||||
pitheorem
|
||||
measurement
|
||||
defining
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ All usual Pint methods can be used with this quantity. For example:
|
|||
...
|
||||
DimensionalityError: Cannot convert from 'meter' ([length]) to 'joule' ([length] ** 2 * [mass] / [time] ** 2)
|
||||
|
||||
But pint
|
||||
NumPy functions are supported by Pint. For example if we define:
|
||||
|
||||
.. doctest::
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ But pint
|
|||
>>> print(legs2)
|
||||
[ 400. 300.] centimeter
|
||||
|
||||
and we can calculate the hypotenuse of the right triangles with legs1 and legs2.
|
||||
we can calculate the hypotenuse of the right triangles with legs1 and legs2.
|
||||
|
||||
.. doctest::
|
||||
|
||||
|
|
@ -98,4 +98,40 @@ results in an error:
|
|||
...
|
||||
DimensionalityError: Cannot convert from 'centimeter' ([length]) to 'dimensionless' (dimensionless)
|
||||
|
||||
|
||||
Support
|
||||
--------
|
||||
|
||||
The following ufuncs_ can be applied to a Quantity object:
|
||||
|
||||
- **Math operations**: add, subtract, multiply, divide, logaddexp, logaddexp2, true_divide, floor_divide, negative, remainder mod, fmod, absolute, rint, sign, conj, exp, exp2, log, log2, log10, expm1, log1p, sqrt, square, reciprocal
|
||||
- **Trigonometric functions**: sin, cos, tan, arcsin, arccos, arctan, arctan2, hypot, sinh, cosh, tanh, arcsinh, arccosh, arctanh, deg2rad, rad2deg
|
||||
- **Comparison functions**: greater, greater_equal, less, less_equal, not_equal, equal
|
||||
- **Floating functions**: isreal,iscomplex, isfinite, isinf, isnan, signbit, copysign, nextafter, modf, ldexp, frexp, fmod, floor, ceil, trunc
|
||||
|
||||
And the following `ndarrays methods`_ and functions:
|
||||
|
||||
- sum, fill, reshape, transpose, flatten, ravel, squeeze, take, put, repeat, sort, argsort, diagonal, compress, nonzero, searchsorted, max, argmax, min, argmin, ptp, clip, round, trace, cumsum, mean, var, std, prod, cumprod, conj, conjugate, flatten
|
||||
|
||||
`Quantity` is not a subclass of `ndarray`. This might change in the future, but for this reason functions that call `numpy.asanyarray` are currently not supported. These functions are:
|
||||
|
||||
- unwrap, trapz, diff, ediff1d, fix, gradient, cross, ones_like
|
||||
|
||||
|
||||
Comments
|
||||
--------
|
||||
|
||||
What follows is a short discussion about how NumPy support is implemented in Pint's `Quantity` Object.
|
||||
|
||||
For the supported functions, Pint expects certain units and attempts to convert the input (or inputs). For example, the argument of the exponential function (`numpy.exp`) must be dimensionless. Units will be simplified (converting the magnitude appropriately) and `numpy.exp` will be applied to the resulting magnitude. If the input is not dimensionless, a `DimensionalityError` exception will be raised.
|
||||
|
||||
In some functions that take 2 or more arguments (e.g. `arctan2`), the second argument is converted to the units of the first. Again, a `DimensionalityError` exception will be raised if this is not possible.
|
||||
|
||||
This behaviour introduces some performance penalties and increased memory usage. Quantities that must be converted to other units require additional memory and cpu cycles. On top of this, all `ufuncs` are implemented in the `Quantity` class by overriding `__array_wrap__`, a NumPy hook that is executed after the calculation and before returning the value. To our knowledge, there is no way to signal back to NumPy that our code will take care of the calculation. For this reason the calculation is actually done twice: first in the original ndarray and then in then in the one that has been converted to the right units. Therefore, for numerically intensive code, you might want to convert the objects first and then use directly the magnitude.
|
||||
|
||||
|
||||
|
||||
|
||||
.. _`NumPy ndarray`: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
|
||||
.. _ufuncs: http://docs.scipy.org/doc/numpy/reference/ufuncs.html
|
||||
.. _`ndarrays methods`: http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html#array-methods
|
||||
|
|
|
|||
|
|
@ -195,12 +195,15 @@ If you use Pint in multiple modules within you Python package, you normally want
|
|||
The best way to do this is by instantiating the registry in a single place. For example,`you can add the following code to your package `__init__.py`::
|
||||
|
||||
from pint import UnitRegistry
|
||||
Q_ = UnitRegistry().Quantity
|
||||
ureg = UnitRegistry()
|
||||
Q_ = ureg.Quantity
|
||||
|
||||
|
||||
Then in `yourmodule.py` the code would be::
|
||||
|
||||
from . import Q_
|
||||
from . import ureg, Q_
|
||||
|
||||
length = 10 * ureg.meter
|
||||
my_speed = Quantity(20, 'm/s')
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue