HalfIntegerArrays

CartesianIndexHalfInt(i, j, k...) -> I
CartesianIndexHalfInt((i, j, k...)) -> I

Create a multidimensional index I, which can be used for indexing a multidimensional AbstractHalfIntegerArray. In particular, for an array A, the operation A[I] is equivalent to A[i,j,k...]. One can freely mix integer, half-integer and CartesianIndex indices; for example, A[Ipre, i, Ipost] (where Ipre and Ipost are CartesianIndex indices and i is an integer or a half-integer) can be a useful expression when writing algorithms that work along a single dimension of an array of arbitrary dimensionality.

Examples

julia> h = HalfIntArray(reshape(1:4, 2, 2), -1//2:1//2, -1//2:1//2)
2×2 HalfIntArray(reshape(::UnitRange{Int64}, 2, 2), -1/2:1/2, -1/2:1/2) with eltype Int64 with indices -1/2:1/2×-1/2:1/2:
 1  3
 2  4

julia> h[CartesianIndexHalfInt(-1//2, 1//2)]
3

julia> h[CartesianIndexHalfInt(-1//2), 1//2]
3

CartesianIndicesHalfInt((istart:istop, jstart:jstop, ...)) -> R

Define a region R spanning a multidimensional rectangular range of integer indices. These are most commonly encountered in the context of iteration, where for I in R ... end will return CartesianIndexHalfInt indices I equivalent to the nested loops

for j = jstart:jstop
    for i = istart:istop
        ...
    end
end

Consequently these can be useful for writing algorithms that work in arbitrary dimensions.

A CartesianIndicesHalfInt type is equivalent to a CartesianIndices type for integer ranges. The difference is that a CartesianIndicesHalfInt allows the ranges to be half-integer AbstractUnitRanges. They are therefore suitable for indexing into AbstractHalfIntegerArrays.

CartesianIndicesHalfInt(A::AbstractArray) -> R

As a convenience, constructing a CartesianIndicesHalfInt from an array makes a range of its indices.

Examples

julia> h = HalfIntArray(reshape(1:4, 2, 2), -1//2:1//2, -1//2:1//2)
2×2 HalfIntArray(reshape(::UnitRange{Int64}, 2, 2), -1/2:1/2, -1/2:1/2) with eltype Int64 with indices -1/2:1/2×-1/2:1/2:
 1  3
 2  4

julia> c = CartesianIndicesHalfInt(h)
2×2 CartesianIndicesHalfInt{2,Tuple{Base.OneTo{Int64},Base.OneTo{Int64}}} with indices -1/2:1/2×-1/2:1/2:
 CartesianIndexHalfInt(-1/2, -1/2)  CartesianIndexHalfInt(-1/2, 1/2)
 CartesianIndexHalfInt(1/2, -1/2)   CartesianIndexHalfInt(1/2, 1/2)

julia> c[1/2,1/2]
CartesianIndexHalfInt(1/2, 1/2)

HalfIntArray(A::AbstractArray, indices::AbstractUnitRange...)

Return a HalfIntArray that shares that shares element type and size with the first argument, but used the given indices, which are checked for compatible size.

The indices may be Integer or HalfInteger ranges with a unit step. Rational ranges over integer or half-integer values may also be provided.

Examples

julia> h = HalfIntArray(reshape(1:9,3,3), -1:1, -1:1)
3×3 HalfIntArray(reshape(::UnitRange{Int64}, 3, 3), -1:1, -1:1) with eltype Int64 with indices -1:1×-1:1:
 1  4  7
 2  5  8
 3  6  9

julia> h[-1, -1]
1

julia> h = HalfIntArray(reshape(1:4,2,2), -1//2:1//2, -1//2:1//2)
2×2 HalfIntArray(reshape(::UnitRange{Int64}, 2, 2), -1/2:1/2, -1/2:1/2) with eltype Int64 with indices -1/2:1/2×-1/2:1/2:
 1  3
 2  4

julia> h[1//2, 1//2]
4

HalfIntArray{T}(init, indices::AbstractUnitRange...)

Return a HalfIntArray having elements of type T and axes as specified by indices. The initializer init may be one of undef, missing or nothing.

Examples

julia> HalfIntArray{Union{Int,Missing}}(undef, 0:1, 0:1)
2×2 HalfIntArray(::Array{Union{Missing, Int64},2}, 0:1, 0:1) with eltype Union{Missing, Int64} with indices 0:1×0:1:
 missing  missing
 missing  missing

LinearIndicesHalfInt(A::AbstractArray)

Return a LinearIndicesHalfInt array with the same shape and axes as A, holding the linear index of each entry in A. Indexing this array with cartesian indices allows mapping them to linear indices.

For arrays with conventional indexing (indices start at 1), or any multidimensional array, linear indices range from 1 to length(A). However, for AbstractVectors linear indices are axes(A, 1), and therefore do not start at 1 for vectors with unconventional indexing.

Calling this function is the "safe" way to write algorithms that exploit linear indexing.

LinearIndicesHalfInt are equivalent to LinearIndices for arrays with integer axes, however LinearIndicesHalfInt also support arrays with half-integer axes. They are therefore the suitable for working with AbstractHalfIntegerArrays.

Examples

julia> h = HalfIntArray(reshape(1:4, 2, 2), -1//2:1//2, -1//2:1//2)
2×2 HalfIntArray(reshape(::UnitRange{Int64}, 2, 2), -1/2:1/2, -1/2:1/2) with eltype Int64 with indices -1/2:1/2×-1/2:1/2:
 1  3
 2  4

julia> linds = LinearIndicesHalfInt(h)
2×2 LinearIndicesHalfInt{2,Tuple{Base.OneTo{Int64},Base.OneTo{Int64}}} with indices -1/2:1/2×-1/2:1/2:
 1  3
 2  4

julia> linds[1/2, 1/2]
4

julia> linds[CartesianIndexHalfInt(1/2, 1/2)]
4

julia> v = HalfIntArray([1,2,3], -1:1)
3-element HalfIntArray(::Array{Int64,1}, -1:1) with eltype Int64 with indices -1:1:
 1
 2
 3

julia> lindsv = LinearIndicesHalfInt(v)
3-element LinearIndicesHalfInt{1,Tuple{Base.OneTo{Int64}}} with indices -1:1:
 -1
  0
  1

julia> lindsv[0]
0

SpinMatrix(A::AbstractMatrix, [j::Real])

Return a SpinMatrix that allows the underlying matrix A to be indexed using integers or half-integers, depending on the value of the angular momentum j. The value of j needs to be either an Integer a half-integral Real number. If it is not provided it is automatically inferred from the size of the array A. The parent matrix A needs to use 1-based indexing, and have a size of (2j+1, 2j+1).

The axes of the SpinMatrix for an angular momentum j will necessarily be (-j:j, -j:j).

Examples

julia> SpinMatrix(reshape(1:4,2,2))
2×2 SpinMatrix(reshape(::UnitRange{Int64}, 2, 2), 1/2) with eltype Int64 with indices -1/2:1/2×-1/2:1/2:
 1  3
 2  4

julia> SpinMatrix(zeros(ComplexF64,3,3), 1)
3×3 SpinMatrix(::Array{Complex{Float64},2}, 1) with eltype Complex{Float64} with indices -1:1×-1:1:
 0.0+0.0im  0.0+0.0im  0.0+0.0im
 0.0+0.0im  0.0+0.0im  0.0+0.0im
 0.0+0.0im  0.0+0.0im  0.0+0.0im

See also: HalfIntArray

SpinMatrix{T}(init, j)

Create a SpinMatrix of type T for the angular momentum j. An underlying Matrix of size (2j+1, 2j+1) is allocated in the process, with values set by the initializer init that may be one of undef, missing or nothing.

Examples

julia> SpinMatrix{Union{Int,Missing}}(undef, 1//2)
2×2 SpinMatrix(::Array{Union{Missing, Int64},2}, 1/2) with eltype Union{Missing, Int64} with indices -1/2:1/2×-1/2:1/2:
 missing  missing
 missing  missing

AbstractHalfIntegerArray{T,N}

Supertype for N-dimensional arrays (or array-like types) with elements of type T. Such arrays may be indexed using integers as well as half-integers.

AbstractHalfIntegerWrapper{T,N} <: AbstractHalfIntegerArray{T,N}

Supertype for N-dimensional arrays (or array-like types) with elements of type T that wrap a parent array that has integer indices. The wrapper acts as a map between the indices of the array and those of the parent.

Subtypes of AbstractHalfIntegerWrapper must define a method for Base.parent that returns the underlying array.

HalfIntArray, SpinMatrix and other types are subtypes of this.

HalfIntSubArray{T,N,P,I,L}

N-dimensional view into a parent array (of type P) with an element type T, restricted by a tuple of indices (of type I). L is true for types that support fast linear indexing, and false otherwise.

Their behavior is analogous to SubArrays, except that they enable indexing with half-integers.

Construct HalfIntSubArrays from AbstractHalfIntegerArrays using the view function, or equivalently the @view macro.

Example

julia> h = HalfIntArray(reshape(1:9, 3, 3), -1:1, -1:1)
3×3 HalfIntArray(reshape(::UnitRange{Int64}, 3, 3), -1:1, -1:1) with eltype Int64 with indices -1:1×-1:1:
 1  4  7
 2  5  8
 3  6  9

julia> hv = @view h[-1:1, 0]
3-element view(HalfIntArray(reshape(::UnitRange{Int64}, 3, 3), -1:1, -1:1), -1:1, 0) with eltype Int64:
 4
 5
 6

julia> hv[1]
4

julia> h = HalfIntArray(reshape(collect(1:4), 2, 2), -1//2:1//2, -1//2:1//2)
2×2 HalfIntArray(::Array{Int64,2}, -1/2:1/2, -1/2:1/2) with eltype Int64 with indices -1/2:1/2×-1/2:1/2:
 1  3
 2  4

julia> hv = @view h[:, 1//2]
2-element view(HalfIntArray(::Array{Int64,2}, -1/2:1/2, -1/2:1/2), :, 1/2) with eltype Int64 with indices -1/2:1/2:
 3
 4

julia> hv[1//2] = 10
10

julia> h
2×2 HalfIntArray(::Array{Int64,2}, -1/2:1/2, -1/2:1/2) with eltype Int64 with indices -1/2:1/2×-1/2:1/2:
 1   3
 2  10

ro = IdOffsetRange(r::AbstractUnitRange, offset::HalfInteger)

Construct an "identity offset range". Numerically, collect(ro) == collect(r) .+ offset, with the additional property that axes(ro,1) = axes(r, 1) .+ offset. When r starts at 1, then ro[i] == i and even ro[ro] == ro, i.e., it's the "identity," which is the origin of the "Id" in IdOffsetRange. The element type is a HalfInteger.

HalfIntegerArrays.OneTo(n)

Define an AbstractUnitRange that behaves like 1:n, with the added distinction that the lower limit is guaranteed (by the type system) to be 1. The elements are integers, but of a HalfInteger type.