How much do we want to use immutability?

Equality conditions on Quantity's don't work for numpy arrays of quantities.

Minimal working example to reproduce is below

from ilaff import units
import numpy as np
#A single. This works                                                                                                  
b = 1 * units.fm
if b == b:
    print('Singleton works')
#A numpy single. This works                                                                                            
b = np.arange(0,1) * units.fm    #i.e. np.array([0])*units.fm                                                          
if b == b:
    print('Numpy singleton works')
#A list of quantities. This works                                                                                                                                                                                  
b = [1*units.fm]*2
if b == b:
    print('List of quantities works')
#A nump array. This doesn't work                                                                                       
b = np.arange(0,2) * units.fm    #i.e. np.array([0,1])*units.fm                                                        
if b == b:
    print('Numpy array doesnt work')
#Error is                                                                                                              
#ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()               

I believe the desired/expected behaviour is all(). This is a simple change on the face of it, change i.e.
return self.value == other.value however this breaks the first case considered. Looking around, the two solutions to test if something is an iterable (and hence eligible for all() ) are

def iterable(obj):
    try:
        iter(obj)
    except Exception:
        return False
    else:
        return True

Or

from collections.abc import Iterable   # drop `.abc` with Python 2.7 or lower
def iterable(obj):
    return isinstance(obj, Iterable)

where apparently the first is preferred. Does anyone else have thoughts about this? Or is this something that iterably will fix @FinnStokes ?

Calculating the mean with numpy works as expected,

>>> lat=units.Lattice()
>>> test=np.array([1,2,3,4])*units.a(lat)
>>> np.mean(test)
Quantity(value=2.5, dimension=Dimension(mass_dim=-1), scale=Lattice())

But the standard deviation does not.

>>> np.std(test)
AttributeError: 'Quantity' object has no attribute 'conjugate'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<__array_function__ internals>", line 5, in std
  File "/home/rperry/anaconda2/envs/py38/lib/python3.8/site-packages/numpy/core/fromnumeric.py", line 3496, in std
    return _methods._std(a, axis=axis, dtype=dtype, out=out, ddof=ddof,
  File "/home/rperry/anaconda2/envs/py38/lib/python3.8/site-packages/numpy/core/_methods.py", line 233, in _std
    ret = _var(a, axis=axis, dtype=dtype, out=out, ddof=ddof,
  File "/home/rperry/anaconda2/envs/py38/lib/python3.8/site-packages/numpy/core/_methods.py", line 214, in _var
    x = um.multiply(x, um.conjugate(x), out=x).real
TypeError: loop of ufunc does not support argument 0 of type Quantity which has no callable conjugate method

Implement proper support for numpy's ufunc architecture by implementing __array_ufunc__. This would replace the current __add__, __mul__, etc implementations, and additionally allow using ufuncs like sin, exp, etc for unitless quantities.

What license do we want to use?

Implement __len__, __getitem__, __iter__, and __reversed__ on Quantity. The implementations of these methods should call the method on the wrapped value and wrap the returned value (or each yielded value) in a Quantity that matches the units of self. This allows for indexing and iteration of wrapped arrays.

I know Rob was uncomfortable with the current class names in the units module, and I ran into some awkwardness when writing the documentation. Here is my proposed alternative:

• Quantity is the main class (previously called Value). Each quantity has:
  • a value (which is a float, numpy array or similar),
  • a Dimension
  • a Scale
• Dimension simply tracks the mass dimension of the quantity as an integer, though it could be generalised to include fractional mass dimensions other dimensionalities for to allow e.g. SI units
• Scale indicates how the physical scale of the quantities is set, current options are:
  • Physical quantites are stored in terms of powers of GeV and are compatible with all other physical quantities (hence, all instances of Physical compare equal)
  • Lattice quantities are stored in terms of powers of the lattice spacing and are only compatible with qunatities defined on the same lattice (corresponding to an instance of the Lattice class, hence different instances of Lattice do not compare equal)
• units are simply specific quantities that correspond to some unit of measure. Currently we define
  • fm, GeV, MeV are constants corresponding to SI units with a Physical scale
  • a is a method that returns a unit corresponding to the lattice spacing in a given Lattice scale

What do people think about this convention? Does it resolve your issues Rob?

We should generate documentation from the docstrings in our code. The most popular option seems to be Sphinx, but there is also pdoc, which is apparently easier to set up for simpler projects. I think given the build infrasructure we already have set up, Sphinx shouldn't be too much extra burden.

I lean towards using Google or NumPy-style docstrings, which would mean using the inbuilt Napoleon extension if we use Sphinx.

Once we get it set up, it would be good to add the documentation generation to the CI and upload as build artifacts and/or push to GitHub Pages or Read the Docs

Perhaps we should add something like pytest-cov to our CI in order to track our test coverage.