B b|@sdZddlmZmZmZdZdZddlmZm Z ddl m Z ddl Z ddl Z dd lTdd lmZmZmZGd d d eZe re`d dZddZedkrddlZddlZeejedS)a* Module simtk.unit.quantity Physical quantities with units, intended to produce similar functionality to Boost.Units package in C++ (but with a runtime cost). Uses similar API as Scientific.Physics.PhysicalQuantities but different internals to satisfy our local requirements. In particular, there is no underlying set of 'canonical' base units, whereas in Scientific.Physics.PhysicalQuantities all units are secretly in terms of SI units. Also, it is easier to add new fundamental dimensions to simtk.dimensions. You might want to make new dimensions for, say, "currency" or "information". Some features of this implementation: * Quantities are a combination of a value and a unit. The value part can be any python type, including numbers, lists, numpy arrays, and anything else. The unit part must be a simtk.unit.Unit. * Operations like adding incompatible units raises an error. * Multiplying or dividing units/quantities creates new units. * Users can create new Units and Dimensions, but most of the useful ones are predefined. * Conversion factors between units are applied transitively, so all possible conversions are available. * I want dimensioned Quantities that are compatible with numpy arrays, but do not necessarily require the python numpy package. In other words, Quantities can be based on either numpy arrays or on built in python types. * Units are NOT necessarily stored in terms of SI units internally. This is very important for me, because one important application area for us is at the molecular scale. Using SI units internally can lead to exponent overflow in commonly used molecular force calculations. Internally, all unit systems are equally fundamental in SimTK. Two possible enhancements that have not been implemented are 1) Include uncertainties with propagation of errors 2) Incorporate offsets for celsius <-> kelvin conversion This is part of the OpenMM molecular simulation toolkit originating from Simbios, the NIH National Center for Physics-Based Simulation of Biological Structures at Stanford, funded under the NIH Roadmap for Medical Research, grant U54 GM072970. See https://simtk.org. Portions copyright (c) 2012 Stanford University and the Authors. Authors: Christopher M. Bruns Contributors: Peter Eastman Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. )divisionprint_functionabsolute_importzChristopher M. Brunsz0.5) string_typesPY3)rangeN)*)Unitis_unit dimensionlessc@seZdZdZdZd{ddZddZdd Zd d Zd d Z ddZ ddZ ddZ ddZ ddZddZddZddZddZd d!Zd"d#Zd$d%Zd&dZiZd|d'd(Zd)d*Zd+d,Zd-d.ZeZd/d0ZeZd1d2Zd3d4Zd5d6Z d7d8Z!d9d:Z"d;d<Z#d=d>Z$d}d@dAZ%dBdCZ&dDdEZ'dFdGZ(dHdIZ)dJdKZ*dLdMZ+dNdOZ,dPdQZ-dRdSZ.dTdUZ/dVdWZ0dXdYZ1dZd[Z2d~d]d^Z3d_d`Z4dadbZ5dcddZ6dedfZ7dgdhZ8didjZ9dkdlZ:dmdnZ;dodpZdudvZ?dwdxZ@dydzZAdS)QuantityaPhysical quantity, such as 1.3 meters per second. Quantities contain both a value, such as 1.3; and a unit, such as 'meters per second'. Supported value types include: 1 - numbers (float, int, long) 2 - lists of numbers, e.g. [1,2,3] 3 - tuples of numbers, e.g. (1,2,3) Note - unit conversions will cause tuples to be converted to lists 4 - lists of tuples of numbers, lists of lists of ... etc. of numbers 5 - numpy.arrays cNc Cs|dkrXt|r|}g}n:t|r6|j}|j}n"t|trHt}nd}y t|}Wntk rpd}YnX|rTt |dkrt}nJt t|}yt ||k}Wnt k rd}YnX|rt}n t |j}t g|}x|D]}|t |qWy4ddl} t|| jr | |j}n ||j}Wn"tk rP||j}YnXnt}t|rr||j}|j}|dkrg}||_||_dS)z Create a new Quantity from a value and a unit. Parameters - value: (any type, usually a number) Measure of this quantity - unit: (Unit) the physical unit, e.g. simtk.unit.meters. NTFrr)r is_quantityunit_value isinstancerr iter TypeErrorlennextbool ValueErrorr appendnumpyZndarrayZarray __class__ ImportError) selfvaluerZ is_containeriZ first_itemZisstrZ new_containeritemrr!3lib/python3.7/site-packages/parmed/unit/quantity.py__init__csV              zQuantity.__init__cCst}|j|d<|j|d<|S)Nrr)dictrr)rstater!r!r" __getstate__s  zQuantity.__getstate__cCs|d|_|d|_dS)Nrr)rr)rr%r!r!r" __setstate__s  zQuantity.__setstate__cCstt|j|jS)z Shallow copy produces a new Quantity with the shallow copy of value and the same unit. Because we want copy operations to work just the same way they would on the underlying value. )r copyrr)rr!r!r"__copy__szQuantity.__copy__cCstt|j||jS)z Deep copy produces a new Quantity with a deep copy of the value, and the same unit. Because we want copy operations to work just the same way they would on the underlying value. )r r(deepcopyrr)rmemor!r!r" __deepcopy__szQuantity.__deepcopy__cCst|j|}|S)zU Delegate unrecognized attribute calls to the underlying value type. )getattrr)rZ attributeZret_valr!r!r" __getattr__s zQuantity.__getattr__cCst|jdt|jS)zPrintable string version of this Quantity. Returns a string consisting of quantity number followed by unit abbreviation.  )strrr get_symbol)rr!r!r"__str__szQuantity.__str__cCs&tjdt|jdt|jdS)z z(value=z, unit=))r __name__reprrr0r)rr!r!r"__repr__szQuantity.__repr__cCs||jdt|jS)Nr/)rr0rr1)r format_specr!r!r"formatszQuantity.formatcCsD|j|js"td|j|jf|j||j}|j}t||S)a=Add two Quantities. Only Quantities with the same dimensions (e.g. length) can be added. Raises TypeError otherwise. Parameters - self: left hand member of sum - other: right hand member of sum Returns a new Quantity that is the sum of the two arguments. z@Cannot add two quantities with incompatible units "%s" and "%s".)r is_compatiblerr value_in_unitr )rotherrrr!r!r"__add__s zQuantity.__add__cCsD|j|js"td|j|jf|j||j}|j}t||S)a\Subtract two Quantities. Only Quantities with the same dimensions (e.g. length) can be subtracted. Raises TypeError otherwise. Parameters - self: left hand member (a) of a - b. - other: right hand member (b) of a - b. Returns a new Quantity that is the difference of the two arguments. zECannot subtract two quantities with incompatible units "%s" and "%s".)rr9rrr:r )rr;rrr!r!r"__sub__s zQuantity.__sub__cCs0t|s dS|j|jsdS||j|jkS)z F)rrr9r:r)rr;r!r!r"__eq__s zQuantity.__eq__cCs || S)z )r>)rr;r!r!r"__ne__ szQuantity.__ne__cCs|j||jkS)zCompares two quantities. Raises TypeError if the Quantities are of different dimension (e.g. length vs. mass) Returns True if self < other, False otherwise. )rr:r)rr;r!r!r"__lt__szQuantity.__lt__cCs|j||jkS)N)rr:r)rr;r!r!r"__ge__szQuantity.__ge__cCs|j||jkS)N)rr:r)rr;r!r!r"__gt__szQuantity.__gt__cCs|j||jkS)N)rr:r)rr;r!r!r"__le__szQuantity.__le__cCs|j||jkS)N)rr:r)rr;r!r!r"r@!sc Cs|j|f}|tjkr&tj|\}}n4d}i}|dk rhx0|D]$\}}|}||kr@|dg||<q@Wxb|jD]T\}}|}||kr||g||<qt||||d|9}||d|7<qtWi} x4|D],}||\}}|dkr|| kst|| |<qWt| dkrt}nt | }| rL|t} | dkrH|| 9}t}||ftj|<t|j |} |dkrx| |} | r|tkstt | rt | j } | S)z Combine similar component units and scale, to form an equal Quantity in simpler units. Returns underlying value type if unit is dimensionless. g?Nrr)rr _reduce_cacheZiter_base_or_scaled_unitsZget_dimension_tupleconversion_factor_toAssertionErrorrr r is_dimensionlessrrr(r*) rZ guide_unitkeyrZ value_factorZcanonical_unitsuexponentdZnew_base_units unit_factorresultr!r!r" reduce_unit&sN              zQuantity.reduce_unitcCsTt|r&|j|}t|j||jSt|r>||j|jS|j|j|ddSdS)zMultiply a quantity by another object Returns a new Quantity that is the product of the self * other, unless the resulting unit is dimensionless, in which case the underlying value type is returned, instead of a Quantity. F) post_multiplyN)r rr rrNr_change_units_with_factor)rr;rr!r!r"__mul__as  zQuantity.__mul__cCs:t|rtdn$t|r$tdn|j|j|ddSdS)zMultiply a scalar by a Quantity Returns a new Quantity with the same units as self, but with the value multiplied by other. z>programmer is surprised __rmul__ was called instead of __mul__T)rON)r NotImplementedErrorrrPr)rr;r!r!r"__rmul__ys   zQuantity.__rmul__cCs@t|r|t|dSt|r.||j|jS|t|dSdS)zDivide a Quantity by another object Returns a new Quantity, unless the resulting unit type is dimensionless, in which case the underlying value type is returned. gN)r powrrr)rr;r!r!r" __truediv__s zQuantity.__truediv__cCs6t|rtdn t|r$tdn|t|dSdS)zDivide a scalar by a quantity. Returns a new Quantity. The resulting units are the inverse of the self argument units. zFprogrammer is surprised __rtruediv__ was called instead of __truediv__gN)r rRrrT)rr;r!r!r" __rtruediv__s   zQuantity.__rtruediv__cCstt|j|t|j|S)zRaise a Quantity to a power. Generally both the value and the unit of the Quantity are affected by this operation. Returns a new Quantity equal to self**exponent. )r rTrr)rrJr!r!r"__pow__szQuantity.__pow__cCsHt|j}|j}|j||}|dkr<|t|9}t||dS)z Returns square root of a Quantity. Raises ArithmeticError if component exponents are not even. This behavior can be changed if you present a reasonable real life case to me. g?)rr)mathsqrtrrrEr )rZ new_valuenew_unitrLr!r!r"rYs   z Quantity.sqrtcOsy|jj||}Wnjtk r||s*|r2tdt|jdkrFd}n2|jd}x&tdt|jD]}||j|7}qbWYnXt||jS)a Computes the sum of a sequence, with the result having the same unit as the current sequence. If the value is not iterable, it raises a TypeError (same behavior as if you tried to iterate over, for instance, an integer). This function can take as arguments any arguments recognized by `numpy.sum`. If arguments are passed to a non-numpy array, a TypeError is raised z&Unsupported arguments for Quantity.sumrr)rsumAttributeErrorrrrr r)rargskwargsZmysumrr!r!r"r[s  z Quantity.sumcOsXy|jj||}Wn8tk rJ|s*|r2td|t|jj}YnXt||jS)a` Computes the mean of a sequence, with the result having the same unit as the current sequence. If the value is not iterable, it raises a TypeError This function can take as arguments any arguments recognized by `numpy.mean`. If arguments are passed to a non-numpy array, a TypeError is raised z'Unsupported arguments for Quantity.mean)rmeanr\rr[rr r)rr]r^r_r!r!r"r_s z Quantity.meancOsy|jj||}Wnntk r|s*|r2td|j}d}x"|jD]}||}|||7}qHW|t|j}t|}YnXt||j S)av Computes the square root of the variance of a sequence, with the result having the same unit as the current sequence. If the value is not iterable, it raises a TypeError This function can take as arguments any arguments recognized by `numpy.std`. If arguments are passed to a non-numpy array, a TypeError is raised z&Unsupported arguments for Quantity.stdr) rstdr\rr_rrXrYr r)rr]r^r`r_varvalZresr!r!r"r`s   z Quantity.stdcOsNy|jj||}Wn.tk r@|s*|r2tdt|j}YnXt||jS)aj Computes the maximum value of the sequence, with the result having the same unit as the current sequence. If the value is not iterable, it raises a TypeError This function can take as arguments any arguments recognized by `numpy.max`. If arguments are passed to a non-numpy array, a TypeError is raised z&Unsupported arguments for Quantity.max)rmaxr\rr r)rr]r^Zmymaxr!r!r"rcs z Quantity.maxcOsNy|jj||}Wn.tk r@|s*|r2tdt|j}YnXt||jS)aj Computes the minimum value of the sequence, with the result having the same unit as the current sequence. If the value is not iterable, it raises a TypeError This function can take as arguments any arguments recognized by `numpy.min`. If arguments are passed to a non-numpy array, a TypeError is raised z&Unsupported arguments for Quantity.min)rminr\rr r)rr]r^Zmyminr!r!r"rd%s z Quantity.minCcCs:yt|jj||d|jStk r4tdYnXdS)z Same as numpy.ndarray.reshape, except the result is a Quantity with the same units as the current object rather than a plain numpy.ndarray )orderz1Only numpy array Quantity objects can be reshapedN)r rreshaperr\)rshaperfr!r!r"rg9szQuantity.reshapecCstt|j|jS)z Return absolute value of a Quantity. The unit is unchanged. A negative value of self will result in a positive value in the result. )r absrr)rr!r!r"__abs__DszQuantity.__abs__cCst|j |jS)z. Returns a reference to self. )r rr)rr!r!r"__pos__MszQuantity.__pos__cCst|j |jS)z_Negate a Quantity. Returns a new Quantity with a different sign on the value. )r rr)rr!r!r"__neg__SszQuantity.__neg__cCs t|jS)zLReturns True if value underlying Quantity is zero, False otherwise. )rr)rr!r!r" __nonzero__ZszQuantity.__nonzero__cCs t|jS)N)rr)rr!r!r"__bool___szQuantity.__bool__cCstt|j|jS)N)r complexrr)rr!r!r" __complex__bszQuantity.__complex__cCstt|j|jS)N)r floatrr)rr!r!r" __float__dszQuantity.__float__cCstt|j|jS)N)r intrr)rr!r!r"__int__fszQuantity.__int__cCstt|j|jS)N)r rsrr)rr!r!r"__long__hszQuantity.__long__cCs ||}t|r|jS|SdS)zC Returns underlying value, in the specified units. N) in_units_ofrr)rrrbr!r!r"r:ks zQuantity.value_in_unitcCs ||}t|r|jS|SdS)zb Returns the underlying value type, after conversion to a particular unit system. N)in_unit_systemrr)rsystemrMr!r!r"value_in_unit_systemus zQuantity.value_in_unit_systemcCs$||j}|j|}|||S)zb Returns a new Quantity equal to this one, expressed in a particular unit system. )Z express_unitrrErP)rrxZ new_unitsfr!r!r"rws  zQuantity.in_unit_systemcCs6|j|std|j|f|j|}|||S)a Returns an equal Quantity expressed in different units. If the units are the same as those in self, a reference to self is returned. Raises a TypeError if the new unit is not compatible with the original unit. The post_multiply argument is used in case the multiplication operation is not commutative. i.e. result = factor * value when post_multiply is False and result = value * factor when post_multiply is True z+Unit "%s" is not compatible with Unit "%s".)rr9rrErP)rZ other_unitrzr!r!r"rvs  zQuantity.in_units_ofTc Csd}y|dkrd}Wntk r(YnX|rBtt|j|}n^y(|rT|j|}n ||j}t||}Wn4tk rt|j}t|||||}YnX|r|jS|SdS)NFg?T)rr r(r*rr_scale_sequencerG)rrZfactorrOZfactor_is_identityrMrr!r!r"rPs&   z"Quantity._change_units_with_factorc s@yr|}n|}Wntk r:yr~t|trVtfdd|D}qxntt|D]}||||<qdWnHt|trtfdd|D}n&x$tt|D]}||||<qWWnltk r4t|trtfdd|D}n.x,tt|D]}||||<qWYnXYnX|S)Ncsg|] }|qSr!r!).0x)r|r!r" sz,Quantity._scale_sequence..csg|] }|qSr!r!)r}r~)r|r!r"rscsg|]}|qSr!)r{)r}r~)r|rOrr!r"rs)rrtuplerrr{)rrr|rOrr!)r|rOrr"r{s*    (zQuantity._scale_sequencecCs t|jS)z5 Return size of internal value type. )rr)rr!r!r"__len__szQuantity.__len__cCs$t|j|rtt|j||jS)z< Keep the same units on contained elements. )rrrFr r)rrHr!r!r" __getitem__szQuantity.__getitem__cCst|tr8|t|}xvt|D]}||||<q"WnX|jrLt|rLn"|j|jsntd|j|jf||j|j |<t |j |rt dS)Nz+Unit "%s" is not compatible with Unit "%s".) rsliceindicesrrrrGr9rrrrF)rrHrrrr!r!r" __setitem__s zQuantity.__setitem__cCs |j|=dS)N)r)rrHr!r!r" __delitem__szQuantity.__delitem__cCs|j||jS)N)r __contains__r:r)rr r!r!r"rszQuantity.__contains__ccs"x|jD]}t||jVqWdS)N)rr r)rr r!r!r"__iter__s zQuantity.__iter__cCs|j||jS)N)rcountr:r)rr r!r!r"rszQuantity.countcCs|j||jS)N)rindexr:r)rr r!r!r"rszQuantity.indexcCs>t|r|j||jSt|jr2|j|StddS)Nz5Cannot append item without units into list with units)rrrr:rrGr)rr r!r!r"rs   zQuantity.appendcCs|j||jdS)N)rextendr:r)rZrhsr!r!r"rszQuantity.extendcCs|j|||jdS)N)rinsertr:r)rrr r!r!r"rszQuantity.insertcCs|j|dS)N)rremove)rr r!r!r"r szQuantity.removecGs|jj||jS)N)rpopr)rr]r!r!r"r sz Quantity.pop)NN)N)re)T)Br4 __module__ __qualname____doc__Z__array_priority__r#r&r'r)r,r.r2r6r8r<r=r>r?r@rArBrCrDrNrQrSrUZ__div__rVZ__rdiv__rWrYr[r_r`rcrdrgrjrkrlrmrnrprrrtrur:ryrwrvrPr{rrrrrrrrrrrrrr!r!r!r"r Ss  L   ;      #r cCs t|tS)z; Returns True if x is a Quantity, False otherwise. )rr )r~r!r!r"rsrcCs*t|r|St|r"|jSdSdS)z TN)r rGrr)r~r!r!r"rGs  rG__main__)rZ __future__rrr __author__ __version__Zparmed.utils.sixrrZparmed.utils.six.movesrrXr(Zstandard_dimensionsrr r r objectr rmrrGr4ZdoctestsysZtestmodmodulesr!r!r!r"Es, D