sympy/sympy — pull request #848 by flacjacket (2011-12-16 05:33:26+00:00)
Title: Arbitrary angular momentum coupling

This pull is primarily finishing up the coupled spin states and the coupling/uncoupling between states. In addition to this, this pull includes Wigner6j and Wigner9j symbols (similar in implementation to Wigner3j and CG) and some minor fixes to the test_args for physics classes.

With the coupled states, the primary change in the handling of states is a jcoupling option that allows one to define the order in which states are coupled. I wasn't sure the best way to do this, as for coupling 2 spaces it is not necessary and having to pass an empty list for this case every time seemed bad, but I remember being told not to use default parameter values in __new__ methods, so this was the best I could come up with.

The couple and uncouple methods are re-done with the ability to handle an arbitrary number of spin spaces, in addition to adding parameters, like jcoupling, to define how the states are coupled in the case a normal state is used to uncouple or a specific coupling is desired for coupling a tensor product state. I try to describe the algorithm I use, but I'll explain it briefly, since it's not very apparent. Basically, it uses the fact for both coupling and uncoupling, there is some maximum value for some quantum number and the actual value it takes, and in the total number of couplings, the value drops from this maximum to the actual value. For example, when coupling a tensor product state, the maximum coupled j is j1+...+jn, but it attains some j<=j1+...jn; uncoupling has a similar case for m values. Then, the heart of the algorithm is this is treated as a n balls in m boxes to distribute the drop from the max value to the actual value, which is a simple combinatorial computation. Each of these cases is then iterated over.

Of note with this is the _huge_ number of coupling and uncoupling tests implemented. I will note I only hand checked these calculations for a few (selectively chosen) cases, however, should any change arise, this will definitely trigger a failure, forcing a closer look. In generating the tests, I did run the script and check that all of the states are normalized, and they all are, which is very promising for how accurate the methods are.

Any feedback would be greatly appreciated.