improve documents

README.md

@@ -7,7 +7,7 @@
 
 [[中文](README_zh.md)]
 
-A package to calculate CG-coefficient, Racah coefficient, and Wigner 3j, 6j, 9j symbols.
+A package to calculate CG-coefficient, Racah coefficient, Wigner 3j, 6j, 9j symbols and Moshinsky brakets.
 
 One can get the exact result with `SqrtRational` type, which use `BigInt` to avoid overflow. And we also offer float version for numeric calculation, which is about twice faster than [GNU Scientific Library](https://www.gnu.org/software/gsl/).
 
@@ -38,6 +38,41 @@ julia> f6j(6,6,6,6,6,6)
 
 For more examples please see the document.
 
+### API
+
+This package contains two types of functions:
+
+1. The exact functions return `SqrtRational`, which are designed for demonstration. They use `BigInt` in the internal calculation, and do not cache the binomial table, so they are not efficient.
+2. The floating-point functions return `Float64`, which are designed for numeric calculation. They use `Int, Float64` in the internal calculation, and you should pre-call `wigner_init_float` to calculate and cache the binomial table for later calculation. They may give inaccurate result for vary large angular momentum, due to floating-point arithmetic. They are trustworthy for angular momentum number `Jmax <= 60`.
+
+#### Exact functions
+
+- `CG(j1, j2, j3, m1, m2, m3)`, CG-coefficient, arguments are `HalfInt`s, aka `Integer` or `Rational` like `3//2`.
+- `CG0(j1, j2, j3)`, CG-coefficient for `m1 = m2 = m3 = 0`, only integer angular momentum number is meaningful.
+- `threeJ(j1, j2, j3, m1, m2, m3)`, Wigner 3j-symbol, `HalfInt` arguments.
+- `sixJ(j1, j2, j3, j4, j5, j6)`, Wigner 6j-symbol, `HalfInt` arguments.
+- `Racah(j1, j2, j3, j4, j5, j6)`, Racah coefficient, `HalfInt` arguments.
+- `nineJ(j1, j2, j3, j4, j5, j6, j7, j8, j9)`, Wigner 9j-symbol, `HalfInt` arguments.
+- `norm9J(j2, j3, j4, j5, j5, j6, j7, j8, j9)`, normalized 9j-symbol, `HalfInt` arguments.
+- `lsjj(l1, l2, j1, j2, L, S, J)`, LS-coupling to jj-coupling transform coefficient. It actually equals to a normalized 9j-symbol, but easy to use and faster. `j1, j2` can be `HalfInt`.
+- `Moshinsky(N, L, n, l, n1, l1, n2, l2, Λ)`, Moshinsky brakets, `Integer` arguments.
+
+#### Float functions
+
+For faster numeric calculation, if the angular momentum number can be half-integer, the argument of the functions is actually double of the number. So that all arguments are integers. The doubled arguments are named starts with `d`.
+
+- `fCG(dj1, dj2, dj3, dm1, dm2, dm3)`, CG-coefficient.
+- `fCG0(j1, j2, j3)`, CG-coefficient for `m1 = m2 = m3 = 0`.
+- `fCGspin(ds1, ds2, S)`, quicker CG-coefficient for two spin-1/2 coupling.
+- `f3j(dj1, dj2, dj3, dm1, dm2, dm3)`, Wigner 3j-symbol.
+- `f6j(dj1, dj2, dj3, dj4, dj5, dj6)`, Wigner 6j-symbol.
+- `fRacah(dj1, dj2, dj3, dj4, dj5, dj6)`, Racah coefficient.
+- `f9j(dj1, dj2, dj3, dj4, dj5, dj6, dj7, dj8, dj9)`, Wigner 9j-symbol.
+- `fnorm9j(dj1, dj2, dj3, dj4, dj5, dj6, dj7, dj8, dj9)`, normalized 9j-symbol.
+- `flsjj(l1, l2, dj1, dj2, L, S, J)`, LS-coupling to jj-coupling transform coefficient.
+- `fMoshinsky(N, L, n, l, n1, l1, n2, l2, Λ)`, Moshinsky brakets.
+- `dfunc(dj, dm1, dm2, β)`, Wigner d-function.
+
 ### Reference
 
 - [https://github.com/ManyBodyPhysics/CENS](https://github.com/ManyBodyPhysics/CENS)

README_zh.md

@@ -7,7 +7,7 @@
 
 [[English](README.md)]
 
-计算CG系数，Racah系数和Wigner 3j, 6j, 9j系数。
+计算CG系数，Racah系数，Wigner 3j, 6j, 9j系数，Moshinsky系数等。
 
 你可以使用定义的`SqrtRational`类型以保存准确结果，它内部使用`BigInt`计算以避免溢出。同时我们也提供浮点数运算的快速版本，比[GNU Scientific Library](https://www.gnu.org/software/gsl/)快一倍。
 
@@ -38,7 +38,43 @@ julia> f6j(6,6,6,6,6,6)
 
 更多示例请看文档。
 
-### 参考
+### 函数列表
+
+这个包提供两类函数。
+
+1. 精确函数。返回`SqrtRational`；这类函数主要是为了演示，内部使用`BigInt`进行计算，不需要缓存，计算速度相对较慢。
+2. 浮点数函数。返回双精度浮点数；这类函数主要是为了数值计算，内部使用`Float64`进行计算。在使用之前，你需要先调用`wigner_init_float`来预想计算二项式系数表并缓存这个表，用于后面的计算。当角动量量子数非常大的时候，它们可能会由于浮点数计算产生一些误差，但对于角动量量子数`Jmax <= 60`，计算都是可信的。
+
+#### 精确函数
+
+- `CG(j1, j2, j3, m1, m2, m3)`, CG系数，参数是所谓`HalfInt`，也就是整数或者`3//2`这样分数类型。
+- `CG0(j1, j2, j3)`, CG系数特殊情况`m1 = m2 = m3 = 0`，此时当然角动量是整数才有意义。
+- `threeJ(j1, j2, j3, m1, m2, m3)`, Wigner 3j系数，参数均为`HalfInt`。
+- `sixJ(j1, j2, j3, j4, j5, j6)`, Wigner 6j系数，参数均为`HalfInt`。
+- `Racah(j1, j2, j3, j4, j5, j6)`, Racah系数，参数均为`HalfInt`。
+- `nineJ(j1, j2, j3, j4, j5, j6, j7, j8, j9)`, Wigner 9j系数，参数均为`HalfInt`。
+- `norm9J(j2, j3, j4, j5, j5, j6, j7, j8, j9)`, normalized 9j系数，参数均为`HalfInt`。
+- `lsjj(l1, l2, j1, j2, L, S, J)`, LS耦合到jj耦合的转换系数，它实际上等于一个normalized 9j系数，但更易于使用且更快。`j1, j2`是`HalfInt`，其余必须是整数。
+- `Moshinsky(N, L, n, l, n1, l1, n2, l2, Λ)`, Moshinsky括号，参数均为`HalfInt`。
+
+#### 浮点数函数
+
+对于数值计算而言，为了效率我们避免使用分数类型，如果某个参数可能是半整数，函数的则使用两倍的角动量量子数作为参数，以此避免半整数。在形参命名中，如果某个参数接受两倍的角动量，那么会有一个`d`前缀。
+
+- `fCG(dj1, dj2, dj3, dm1, dm2, dm3)`, CG系数
+- `fCG0(j1, j2, j3)`, CG系数特殊情况`m1 = m2 = m3 = 0`。
+- `fCGspin(ds1, ds2, S)`, 快速计算1/2自旋的CG系数。
+- `f3j(dj1, dj2, dj3, dm1, dm2, dm3)`, Wigner 3j系数。
+- `f6j(dj1, dj2, dj3, dj4, dj5, dj6)`, Wigner 6j系数。
+- `fRacah(dj1, dj2, dj3, dj4, dj5, dj6)`, Racah系数。
+- `f9j(dj1, dj2, dj3, dj4, dj5, dj6, dj7, dj8, dj9)`, Wigner 9j系数。
+- `fnorm9j(dj1, dj2, dj3, dj4, dj5, dj6, dj7, dj8, dj9)`, normalized 9j系数。
+- `flsjj(l1, l2, dj1, dj2, L, S, J)`, LS耦合到jj耦合的转换系数。
+- `fMoshinsky(N, L, n, l, n1, l1, n2, l2, Λ)`, oshinsky括号
+- `dfunc(dj, dm1, dm2, β)`, Wigner d 函数。
+
+
+### 参考资料
 
 - [https://github.com/ManyBodyPhysics/CENS](https://github.com/ManyBodyPhysics/CENS)
 - D. A. Varshalovich, A. N. Moskalev and V. K. Khersonskii, *Quantum Theory of Angular Momentum*, (World Scientific, 1988).

src/WignerSymbols.jl

@@ -315,7 +315,7 @@ CG coefficient ``\langle j_1m_1 j_2m_2 | j_3m_3 \rangle``
 
 @doc raw"""
     CG0(j1::Integer, j2::Integer, j3::Integer)
-CG coefficient special case: ``\langle j1 0 j2 0 | j3 0 \rangle``.
+CG coefficient special case: ``\langle j_1 0 j_2 0 | j_3 0 \rangle``.
 """
 @inline CG0(j1::Integer, j2::Integer, j3::Integer) = simplify(_CG0(big(j1), big(j2), big(j3)))
 
@@ -398,16 +398,16 @@ j_7 & j_8 & j_9
     lsjj(l1::Integer, l2::Integer, j1::HalfInt, j2::HalfInt, L::Integer, S::Integer, J::Integer)
 LS-coupling to jj-coupling transformation coefficient
 ```math
-|l1 l2 j1 j2; J\rangle = \sum_{LS} \langle l1 l2 LSJ | l1 l2 j1 j2; J \rangle |l1 l2 LSJ \rangle
+|l_1 l_2 j_1 j_2; J\rangle = \sum_{LS} \langle l_1 l_2 LSJ | l_1 l_2 j_1 j_2; J \rangle |l_1 l_2 LSJ \rangle
 ```
 """
 @inline lsjj(l1::Integer, l2::Integer, j1::HalfInt, j2::HalfInt, L::Integer, S::Integer, J::Integer) = simplify(_lsjj(BigInt.((l1, l2, 2j1, 2j2, L, S, J))...))
 
 
 @doc raw"""
-    Moshinsky(N,L,n,l,n1,l1,n2,l2,Λ)
+    Moshinsky(N::Integer, L::Integer, n::Integer, l::Integer, n1::Integer, l1::Integer, n2::Integer, l2::Integer, Λ::Integer)
 Moshinsky bracket，Ref: Buck et al. Nuc. Phys. A 600 (1996) 387-402.
 Since this function is designed for demonstration the exact result,
 It only calculate the case of ``\tan(\beta) = 1``.
 """
-@inline Moshinsky(N, L, n, l, n1, l1, n2, l2, Λ) = simplify(_Moshinsky(BigInt.((N, L, n, l, n1, l1, n2, l2, Λ))...))
+@inline Moshinsky(N::Integer, L::Integer, n::Integer, l::Integer, n1::Integer, l1::Integer, n2::Integer, l2::Integer, Λ::Integer) = simplify(_Moshinsky(BigInt.((N, L, n, l, n1, l1, n2, l2, Λ))...))

src/floatWignerSymbols.jl

@@ -459,7 +459,7 @@ end
 
 """
     dfunc(dj::Integer, dm1::Integer, dm2::Integer, β::Float64)
-Wigner-d function.
+Wigner d-function.
 """
 @inline function dfunc(dj::Integer, dm1::Integer, dm2::Integer, β::Float64)
     return _dfunc(Int.((dj, dm1, dm2))..., β)