When debugging comparisons and hashes in SymPy, it is necessary to understand when exactly Python calls each method. Unfortunately, the official Python documentation for this is not very detailed (see the docs for rich comparison, __cmp__() and __hash__() methods).

We wrote this guide to fill in the missing gaps. After reading it, you should be able to understand which methods do (and do not) get called and the order in which they are called.

Every Python class has a `__hash__()` method, the default
implementation of which is:

```
def __hash__(self):
return id(self)
```

You can reimplement it to return a different integer that you compute on your own.
`hash(x)` just calls `x.__hash__()`. Python builtin classes usually redefine
the `__hash__()` method. For example, an `int` has something like this:

```
def __hash__(self):
return int(self)
```

and a `list` does something like this:

```
def __hash__(self):
raise TypeError("list objects are unhashable")
```

The general
idea about hashes is that if two objects have a different hash, they are not
equal, but if they have the same hash, they *might* be equal. (This is usually
called a “hash collision” and you need to use the methods described in the
next section to determine if the objects really are equal).

The only requirement from the Python side is
that the hash value mustn’t change after it is returned by the
`__hash__()` method.

Please be aware that hashing is *platform-dependent*. This means that you can
get different hashes for the same SymPy object on different platforms. This
affects for instance sorting of sympy expressions. You can also get SymPy
objects printed in different order.

When developing, you have to be careful about this, especially when writing tests. It is possible that your test runs on a 32-bit platform, but not on 64-bit. An example:

```
>> from sympy import *
>> x = Symbol('x')
>> r = rootfinding.roots_quartic(Poly(x**4 - 6*x**3 + 17*x**2 - 26*x + 20, x))
>> [i.evalf(2) for i in r]
[1.0 + 1.7*I, 2.0 - 1.0*I, 2.0 + I, 1.0 - 1.7*I]
```

If you get this order of solutions, you are probably running 32-bit system. On a 64-bit system you would get the following:

```
>> [i.evalf(2) for i in r]
[1.0 - 1.7*I, 1.0 + 1.7*I, 2.0 + I, 2.0 - 1.0*I
```

When you now write a test like this:

```
r = [i.evalf(2) for i in r]
assert r == [1.0 + 1.7*I, 2.0 - 1.0*I, 2.0 + I, 1.0 - 1.7*I]
```

it will fail on a 64-bit platforms, even if it works for your 32-bit system. You can avoid this by using the ´´sorted()´´ or ´´set()´´ Python built-in:

```
r = [i.evalf(2) for i in r]
assert set(r) == set([1.0 + 1.7*I, 2.0 - 1.0*I, 2.0 + I, 1.0 - 1.7*I])
```

This approach does not work for doctests since they always compare strings that would be printed after a prompt. In that case you could make your test print results using a combination of ´´str()´´ and ´´sorted()´´:

```
>> sorted([str(i.evalf(2)) for i in r])
['1.0 + 1.7*I', '1.0 - 1.7*I', '2.0 + I', '2.0 - 1.0*I']
```

or, if you don’t want to show the values as strings, then sympify the results or the sorted list:

```
>> [S(s) for s in sorted([str(i.evalf(2)) for i in r])]
[1.0 + 1.7*I, 1.0 - 1.7*I, 2.0 + I, 2.0 - I]
```

The printing of SymPy expressions might be also affected, so be careful with doctests. If you get the following on a 32-bit system:

```
>> print dsolve(f(x).diff(x, 2) + 2*f(x).diff(x) - f(x), f(x))
f(x) == C1*exp(-x + x*2**(1/2)) + C2*exp(-x - x*2**(1/2))
```

you might get the following on a 64-bit platform:

```
>> print dsolve(f(x).diff(x, 2) + 2*f(x).diff(x) - f(x), f(x))
f(x) == C1*exp(-x - x*2**(1/2)) + C2*exp(-x + x*2**(1/2))
```

Let `a`, `b` and `c` be instances of any one of the Python classes.
As can be easily checked by the python script at the end of this guide,
if you write:

```
a == b
```

Python calls the following – in this order:

```
a.__eq__(b)
b.__eq__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) == id(b)
```

If a particular method is not implemented (or a method
returns `NotImplemented` [1]) Python skips it
and tries the next one until it succeeds (i.e. until the method returns something
meaningful). The last line is a catch-all method that always succeeds.

If you write:

```
a != b
```

Python tries to call:

```
a.__ne__(b)
b.__ne__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) == id(b)
```

If you write:

```
a < b
```

Python tries to call:

```
a.__lt__(b)
b.__gt__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) < id(b)
```

If you write:

```
a <= b
```

Python tries to call:

```
a.__le__(b)
b.__ge__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) <= id(b)
```

And similarly for `a > b` and `a >= b`.

If you write:

```
sorted([a, b, c])
```

Python calls the same chain of methods as for the `b < a` and `c < b`
comparisons.

If you write any of the following:

```
a in {d: 5}
a in set([d, d, d])
set([a, b]) == set([a, b])
```

Python first compares hashes, e.g.:

```
a.__hash__()
d.__hash__()
```

If `hash(a) != hash(d)` then the result of the statement `a in {d: 5}` is
immediately `False` (remember how hashes work in general). If
`hash(a) == hash(d)`) Python goes through the method resolution of the
`==` operator as shown above.

In the method resolution for `<`, `<=`, `==`, `!=`, `>=`, `>` and
`sorted([a, b, c])` operators the `__hash__()` method is *not* called, so
in these cases it doesn’t matter what it returns. The `__hash__()` method is
only called for sets and dictionaries.

In the official Python documentation you can read about hashable and
non-hashable objects.
In reality, you don’t have to think about it, you just follow the method
resolution described here. E.g. if you try to use lists as dictionary keys, the
list’s `__hash__()` method will be called and it returns an exception.

In SymPy, every instance of any subclass of `Basic` is
immutable. Technically this means, that it’s behavior through all the methods
above mustn’t change once the instance is created. Especially, the hash value
mustn’t change (as already stated above) or else objects will get mixed up in
dictionaries and wrong values will be returned for a given key, etc....

The above method resolution can be verified using the following program:

```
class A(object):
def __init__(self, a, hash):
self.a = a
self._hash = hash
def __lt__(self, o):
print "%s.__lt__(%s)" % (self.a, o.a)
return NotImplemented
def __le__(self, o):
print "%s.__le__(%s)" % (self.a, o.a)
return NotImplemented
def __gt__(self, o):
print "%s.__gt__(%s)" % (self.a, o.a)
return NotImplemented
def __ge__(self, o):
print "%s.__ge__(%s)" % (self.a, o.a)
return NotImplemented
def __cmp__(self, o):
print "%s.__cmp__(%s)" % (self.a, o.a)
#return cmp(self._hash, o._hash)
return NotImplemented
def __eq__(self, o):
print "%s.__eq__(%s)" % (self.a, o.a)
return NotImplemented
def __ne__(self, o):
print "%s.__ne__(%s)" % (self.a, o.a)
return NotImplemented
def __hash__(self):
print "%s.__hash__()" % (self.a)
return self._hash
def show(s):
print "--- %s " % s + "-"*40
eval(s)
a = A("a", 1)
b = A("b", 2)
c = A("c", 3)
d = A("d", 1)
show("a == b")
show("a != b")
show("a < b")
show("a <= b")
show("a > b")
show("a >= b")
show("sorted([a, b, c])")
show("{d: 5}")
show("a in {d: 5}")
show("set([d, d, d])")
show("a in set([d, d, d])")
show("set([a, b])")
print "--- x = set([a, b]); y = set([a, b]); ---"
x = set([a,b])
y = set([a,b])
print " x == y :"
x == y
print "--- x = set([a, b]); y = set([b, d]); ---"
x = set([a,b])
y = set([b,d])
print " x == y :"
x == y
```

and its output:

```
--- a == b ----------------------------------------
a.__eq__(b)
b.__eq__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a != b ----------------------------------------
a.__ne__(b)
b.__ne__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a < b ----------------------------------------
a.__lt__(b)
b.__gt__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a <= b ----------------------------------------
a.__le__(b)
b.__ge__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a > b ----------------------------------------
a.__gt__(b)
b.__lt__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a >= b ----------------------------------------
a.__ge__(b)
b.__le__(a)
a.__cmp__(b)
b.__cmp__(a)
--- sorted([a, b, c]) ----------------------------------------
b.__lt__(a)
a.__gt__(b)
b.__cmp__(a)
a.__cmp__(b)
c.__lt__(b)
b.__gt__(c)
c.__cmp__(b)
b.__cmp__(c)
--- {d: 5} ----------------------------------------
d.__hash__()
--- a in {d: 5} ----------------------------------------
d.__hash__()
a.__hash__()
d.__eq__(a)
a.__eq__(d)
d.__cmp__(a)
a.__cmp__(d)
--- set([d, d, d]) ----------------------------------------
d.__hash__()
d.__hash__()
d.__hash__()
--- a in set([d, d, d]) ----------------------------------------
d.__hash__()
d.__hash__()
d.__hash__()
a.__hash__()
d.__eq__(a)
a.__eq__(d)
d.__cmp__(a)
a.__cmp__(d)
--- set([a, b]) ----------------------------------------
a.__hash__()
b.__hash__()
--- x = set([a, b]); y = set([a, b]); ---
a.__hash__()
b.__hash__()
a.__hash__()
b.__hash__()
x == y :
--- x = set([a, b]); y = set([b, d]); ---
a.__hash__()
b.__hash__()
b.__hash__()
d.__hash__()
x == y :
d.__eq__(a)
a.__eq__(d)
d.__cmp__(a)
a.__cmp__(d)
```

[1] | There is also the similar But these are So: ```
'return NotImplemented' != 'raise NotImplementedError'
``` |