unyt Documentation Release v2.8.0 The yt Project Oct 05, 2020 Contents: 1 Installation 3 1.1 Stable release...............................................3 1.2 From source...............................................3 1.3 Running the tests.............................................4 2 Working with unyt 5 2.1 Basic Usage...............................................5 2.1.1 An Example from High School Physics............................5 2.1.2 Arithmetic and units......................................6 2.1.3 Powers, Logarithms, Exponentials, and Trigonometric Functions...............8 2.1.4 Printing Units..........................................9 2.1.5 Simplifying Units........................................9 2.1.6 Checking Units......................................... 10 2.1.7 Temperature Units....................................... 10 2.2 Unit Conversions and Unit Systems................................... 11 2.2.1 Converting Data to Arbitrary Units............................... 11 2.2.2 Converting Units In-Place................................... 11 2.2.3 Converting to MKS and CGS Base Units............................ 12 2.2.4 Other Unit Systems....................................... 12 2.3 Equivalencies............................................... 15 2.4 Dealing with code that doesn’t use unyt ................................ 16 2.4.1 Stripping units off of data.................................... 17 2.4.2 Applying units to data..................................... 17 2.4.3 Working with code that uses astropy.units ....................... 18 2.4.4 Working with code that uses Pint ............................... 18 2.5 User-Defined Units............................................ 19 2.6 Dealing with data types......................................... 19 2.7 Integrating unyt Into a Python Library................................. 20 2.7.1 Unit registries.......................................... 20 2.7.2 Custom Unit Systems...................................... 22 2.7.3 Writing Data with Units to Disk................................ 22 2.7.4 Performance Considerations.................................. 25 2.8 unyt_array.name attribute..................................... 26 2.9 Plotting with Matplotlib......................................... 26 3 Listing of Units 31 i 4 Listing of Physical Constants 35 5 unyt package 37 5.1 Submodules............................................... 38 5.1.1 unyt.array module........................................ 38 5.1.2 unyt.dimensions module.................................... 56 5.1.3 unyt.equivalencies module................................... 60 5.1.4 unyt.exceptions module..................................... 64 5.1.5 unyt.mpl_interface module................................... 68 5.1.6 unyt.physical_constants module................................ 68 5.1.7 unyt.testing module....................................... 69 5.1.8 unyt.unit_object module.................................... 70 5.1.9 unyt.unit_registry module.................................... 74 5.1.10 unyt.unit_symbols module................................... 75 5.1.11 unyt.unit_systems module................................... 77 6 Contributing 81 6.1 Code of Conduct............................................. 81 6.2 Types of Contributions.......................................... 81 6.2.1 Report Bugs........................................... 81 6.2.2 Fix Bugs............................................. 82 6.2.3 Implement Features....................................... 82 6.2.4 Write Documentation...................................... 82 6.2.5 Submit Feedback........................................ 82 6.3 Get Started!................................................ 82 6.4 Testing unyt............................................... 83 6.5 Pull Request Guidelines......................................... 84 6.6 Deploying................................................ 84 7 Citing unyt 85 8 Credits 87 8.1 Contributors............................................... 87 9 History 89 9.1 2.8.0 (2020-10-05)............................................ 89 9.2 2.7.2 (2020-06-29)............................................ 89 9.3 2.7.1 (2020-02-17)............................................ 90 9.4 2.7.0 (2020-02-06)............................................ 90 9.5 2.6.0 (2020-01-22)............................................ 90 9.6 2.5.0 (2020-01-20)............................................ 90 9.7 2.4.1 (2020-01-10)............................................ 91 9.8 2.4.0 (2019-10-25)............................................ 91 9.9 2.3.1 (2019-08-21)............................................ 91 9.10 2.3.0 (2019-08-14)............................................ 91 9.11 2.2.2 (2019-07-03)............................................ 91 9.12 2.2.1 (2019-07-02)............................................ 91 9.13 2.2.0 (2019-04-03)............................................ 92 9.14 2.1.1 (2019-03-27)............................................ 92 9.15 2.1.0 (2019-03-26)............................................ 92 9.16 2.0.0 (2019-03-08)............................................ 92 9.17 1.0.7 (2018-08-13)............................................ 94 9.18 1.0.6 (2018-08-13)............................................ 94 9.19 1.0.5 (2018-08-03)............................................ 94 9.20 1.0.4 (2018-06-08)............................................ 95 ii 9.21 1.0.3 (2018-06-06)............................................ 95 9.22 1.0.2 (2018-06-06)............................................ 95 9.23 1.0.1 (2018-05-24)............................................ 95 9.24 1.0.0 (2018-05-24)............................................ 95 10 Indices and tables 97 Python Module Index 99 Index 101 iii iv unyt Documentation, Release v2.8.0 This is the documentation for unyt (pronounced like “unit”). This package provides a python library for working with data that has physical units. It was originally developed as part of The yt Project but was split out as an independent project so that other Python projects can easily make use of it. The unyt library defines the unyt.array.unyt_array and unyt.array.unyt_quantity classes for han- dling arrays and scalars with units, respectively. In addition, unyt provides a number of predefined units and physical constants that can be directly imported from from the unyt namespace: >>> from unyt import G, Mearth, Rearth >>> v_esc=(2 *G*Mearth/Rearth)**(1./2) >>> print(v_esc.to('km/s')) 11.254544657958482 km/s Contents: 1 unyt Documentation, Release v2.8.0 2 Contents: CHAPTER 1 Installation 1.1 Stable release To install unyt, run this command in your terminal: $ pip install unyt If you have a C compiler available, we also suggest installing fastcache, which will improve the performance of SymPy. If you don’t have pip installed, this Python installation guide can guide you through the process. If you use conda, unyt is available via conda-forge: $ conda install -c conda-forge unyt It is not necessary to explicitly install fastcache if you use conda because it will be installed automatically as a dependency of SymPy. 1.2 From source The sources for unyt can be downloaded from the Github repo. You can either clone the public repository: $ git clone git://github.com/yt-project/unyt Or download the tarball: $ curl -OL https://github.com/yt-project/unyt/tarball/master Once you have a copy of the source, you can install it by navigating to the root of the installation and issuing the following command: 3 unyt Documentation, Release v2.8.0 $ pip install . If you would like to make an “editable” where you can directly edit the Python source files of the installed version of unyt, then you can do: $ pip install -e . 1.3 Running the tests You can check that unyt is working properly by running the unit tests on your intalled copy: >>> import unyt >>> unyt.test() 4 Chapter 1. Installation CHAPTER 2 Working with unyt 2.1 Basic Usage To use unyt in a project: >>> import unyt The top-level unyt namespace defines both a number of useful functions as well as a number of units and physical constants populated from the unyt.unit_symbols and unyt.physical_constants namespaces you can use to attach units to NumPy arrays and other common python data container types like list and tuple. For an exhaustive listing of units and physical constants defined in unyt, see Listing of Units. 2.1.1 An Example from High School Physics To see how you might use unyt to solve a problem where units might be a headache, let’s estimate the orbital periods of Jupiter’s Galilean moons, assuming they have circular orbits and their masses are negligible compared to Jupiter. Under these assumptions, the orbital period is (︂ r3 )︂1=2 T = 2휋 : GM For this exercise let’s calculate the orbital period in days. While it’s possible to do this using plain old floating point numbers (you probably had to do something similar on a calculator in a high school physics class, looking up and plugging in conversion factors by hand), it’s much easier to do this sort of thing symbolically and let unyt handle the unit conversions. To do this we’ll need to know the mass of Jupiter (fortunately that is built into unyt) and the semimajor axis of the orbits of Jupiter’s moons, which we can look up from Wikipedia and enter by hand: >>> from unyt import Mjup, G, AU >>> from math import pi ... (continues on next page) 5 unyt Documentation, Release v2.8.0 (continued from previous page) >>> moons=['Io','Europa','Ganymede','Callisto'] >>> semimajor_axis=[.002819,.0044856,.00715526,.01258513]