What is the point of the space() method used in siteind()?

Question

I was looking at various parts of the ITensors.jl code, and I happened to notice something I really don't understand.

In the file ITensors.jl/src/physics/sitetype.jl, it seems that the more involved siteind() methods calls this space() method (and the other siteind() methods call one of these more involved ones). But the first space() method just returns nothing, and the second one seems to just call the first one. As such, I really don't know what the point of this method is.

Could someone clarify what is going on here? For convenience, I have put below the entire block of code for the siteind system. Any help on this would be greatly appreciated.

#---------------------------------------
#
# siteind system
#
#---------------------------------------

space(st::SiteType; kwargs...) = nothing

space(st::SiteType, n::Int; kwargs...) =
  space(st; kwargs...)

function space_error_message(st::SiteType)
  return "Overload of \"space\",\"siteind\", or \"siteinds\" functions not found for Index tag: $(tag(st))"
end

function siteind(st::SiteType; addtags = "", kwargs...) 
  sp = space(st; kwargs...)
  isnothing(sp) && return nothing
  return Index(sp, "Site, $(tag(st)), $addtags")
end

function siteind(st::SiteType, n; kwargs...)
  s = siteind(st; kwargs...)
  !isnothing(s) && return addtags(s, "n=$n")
  sp = space(st, n; kwargs...)
  isnothing(sp) && error(space_error_message(st))
  return Index(sp, "Site, $(tag(st)), n=$n")
end

siteind(tag::String; kwargs...) =
  siteind(SiteType(tag); kwargs...)

siteind(tag::String, n; kwargs...) =
  siteind(SiteType(tag), n; kwargs...)

# Special case of `siteind` where integer (dim) provided
# instead of a tag string
siteind(d::Integer,n::Integer; kwargs...) = Index(d,"Site,n=$n")

Answer 1

Over all, the point of the space function is to define the Hilbert space of a physical site. If no QNs are being used, it is just an integer (so the size of the Hilbert space), while if QNs are being used the space is split up into different blocks for different quantum numbers.

What you are looking at there are just generic fallbacks for when the space function is not defined for a specific SiteType, and isn't relevant for user code. Most of the time only the first one is relevant, and that is what a user would overload for their own SiteType. You might imagine that it should return an error instead of nothing, however we don't want it to error because internally we sometimes check if space is defined for a certain tag, and move on if it isn't (so we don't always want an error). You can think of it returning nothing as a way to avoid doing exception handling with try ... catch.

The second definition can be used in the case when a site location is relevant for the space function, for example if you were conserving momentum where the momentum quantum number depends on the site (see https://github.com/ITensor/ITensors.jl/blob/master/examples/src/electronk.jl#L7-L71 as an example). This usually isn't the case, however. Possibly that interface could change if we come up with a better design for that feature.

I would focus on these two pages by Miles:

http://itensor.org/docs.cgi?vers=julia&page=formulas/sitetype_basic

http://itensor.org/docs.cgi?vers=julia&page=formulas/sitetype_qns

which explain the user interface for this system.