`SubObjectIterator`

Many of the objects in the field of Polyhedral Geometry mask a BigObject from Polymake.jl. These big objects have properties which can easily be accessed via julia's dot syntax. The return commonly does not adhere to the mathematical or the typing conventions of Oscar; many properties encode information about a collection of mathematical objects within a single data object.

The SubObjectIterator is a precise and flexible tool to directly access and/or process the desired properties of any Polymake.BigObject, but it requires specific interface definitions to work properly for each context. The user can thus profit from an easily understandable and usable iterator.

This guide is meant to communicate the application of the SubObjectIterator for developers, utilizing existing code as reference and examples.

Creating a working `SubObjectIterator`

The formal definition of the SubObjectIterator in src/PolyhedralGeometry/iterators is:

struct SubObjectIterator{T} <: AbstractVector{T}
    Obj::Polymake.BigObject
    Acc::Function
    n::Int
    options::NamedTuple
end

An instance can be created by passing values for all fields, while options is optional.

Trivially, Obj is the Polymake.BigObject whose property is to be accessed. The other fields will each be explained in an upcoming section.

Length

As an AbstractVector, the SubObjectIterator has a length. Due to the nature of Polymake.BigObjects this length is constant for any property. Sometimes the length can easily be derived as a by-product of pre-computations when creating an instance of SubObjectIterator. To avoid performing unnecessary computations afterwards, the value is set at construction in n.

Access function

Optimally retrieving and converting the elements varies strongly between the contexts in which a SubObjectIterator is created. Thus its getindex method redirects the call to the (internal) function Acc:

function Base.getindex(iter::SubObjectIterator{T}, i::Base.Integer) where T
    @boundscheck 1 <= i && i <= iter.n
    return iter.Acc(T, iter.Obj, i; iter.options...)
end

From this call we can see that the access function's signature needs to satisfy certain requirements for the SubObjectIterator to work. The arguments are:

T: The return type.
iter.Obj: The Polymake.BigObject whose property is to be accessed.
i: The index.
iter.options: Additional arguments. Will be explained later.

Let us look at an example how we can utilize this interface. The following is the implementation to access the rays of a Cone:

rays(as::Type{RayVector{T}}, C::Cone) where T = SubObjectIterator{as}(pm_object(C), _ray_cone, n_rays(C))

_ray_cone(::Type{T}, C::Polymake.BigObject, i::Base.Integer) where T = T(C.RAYS[i, :])

Typing r = rays(RayVector{Polymake.Rational}, C) with a Cone C returns a SubObjectIterator over RayVector{Polymake.Rational} elements of length n_rays(C) with access function _ray_cone. With the given method of this function, getindex(r, i) returns a RayVector{Polymake.Rational} constructed from the i-th row of the property RAYS of the Polymake.BigObject.

The user does never directly create a SubObjectIterator, so type restrictions made where it is created can be assumed to hold. In our example _ray_cone will always be called with T<:RayVector.

One can define several methods of the access function to ideally read and process data. Consider facets(as::Type{T}, C::Cone). Depending on the return type we offer three methods:

_facet_cone(::Type{T}, C::Polymake.BigObject, i::Base.Integer) where T<:Union{Polyhedron, AffineHalfspace} = T(-C.FACETS[[i], :], 0)

_facet_cone(::Type{LinearHalfspace}, C::Polymake.BigObject, i::Base.Integer) = LinearHalfspace(-C.FACETS[[i], :])

_facet_cone(::Type{Cone}, C::Polymake.BigObject, i::Base.Integer) = cone_from_inequalities(-C.FACETS[[i], :])

Additional Methods

The SubObjectIterator can moreover be understood as a mathematical collection the sense that one can

ask for specific information encoded in the data or
use this collection as an argument for construction another mathematical object.

The first case is covered by adding methods to specific internal functions. Remember implementation of rays discussed above. It makes sense to define a vector_matrix method on its output, encoding the rays of the cone as a single matrix based on a convention applied throughout Oscar. The function's implementation a user calls in this case is evaluated to these lines:

vector_matrix(iter::SubObjectIterator{<:AbstractVector{Polymake.Rational}}) = matrix(QQ, Matrix{QQFieldElem}(_vector_matrix(Val(iter.Acc), iter.Obj; iter.options...)))
vector_matrix(iter::SubObjectIterator{<:AbstractVector{Polymake.Integer}}) = matrix(ZZ, _vector_matrix(Val(iter.Acc), iter.Obj; iter.options...))
_vector_matrix(::Any, ::Polymake.BigObject) = throw(ArgumentError("Vector Matrix not defined in this context."))

Two functionalities are defined this way:

The call of vector_matrix(iter) is redirected to _vector_matrix(Val(iter.Acc), iter.Obj). If that method is not defined for the value type of the access function, it falls back to throwing an error.
The matrix received from step 1 is converted from Polymake.jl format to Oscar format.

So by defining the following we have a fully functional vector_matrix method in the context of rays:

_vector_matrix(::Val{_ray_cone}, C::Polymake.BigObject) = C.RAYS

The second case is solved with defining a special _matrix_for_polymake method. One just hast to name the internal function that returns the desired matrix. This way one has the ability to precisely control how the iterator works internally in specific contexts, even if there happen to be multiple additional matrix functions.

Again, the call matrix_for_polymake(iter) will either redirect to the defined method or fall back to throwing an error if there is none:

function matrix_for_polymake(iter::SubObjectIterator)
    if hasmethod(_matrix_for_polymake, Tuple{Val{iter.Acc}})
        return _matrix_for_polymake(Val(iter.Acc))(Val(iter.Acc), iter.Obj; iter.options...)
    else
        throw(ArgumentError("Matrix for Polymake not defined in this context."))
    end
end

For rays(C::Cone) this reduces the implementation to the following line:

_matrix_for_polymake(::Val{_ray_cone}) = _vector_matrix

With matrix_for_polymake the output of rays can be handled as a usual matrix and constructors or other functions can easily be extended by additionally allowing SubObjectIterator as an argument type. E.g. the signature of one of the Cone constructors now looks like this while the body has not changed:

Cone(R::Union{SubObjectIterator{<:RayVector}, Oscar.MatElem, AbstractMatrix}, L::Union{SubObjectIterator{<:RayVector}, Oscar.MatElem, AbstractMatrix, Nothing} = nothing; non_redundant::Bool = false)

There also are linear_matrix_for_polymake and affine_matrix_for_polymake used in the context of linear and affine halfspaces/hyperplanes. Defining this functionality in a context works the same way as for matrix_for_polymake; you can create a new method of _linear_matrix_for_polymake or _affine_matrix_for_polymake. It suffices to define the most relevant of these two; the other one will be derived, if possible. Also, halfspace_matrix_pair is defined in terms of affine_matrix_for_polymake, so this does not need another implementation.

The example code for rays(C::Cone) has covered every line of the implementation by now, but we had different code in between, so let us summarize and take a look at what the whole implementation actually looks like:

rays(as::Type{RayVector{T}}, C::Cone) where T = SubObjectIterator{as}(pm_object(C), _ray_cone, n_rays(C))

_ray_cone(::Type{T}, C::Polymake.BigObject, i::Base.Integer) where T = T(C.RAYS[i, :])

_vector_matrix(::Val{_ray_cone}, C::Polymake.BigObject) = C.RAYS

_matrix_for_polymake(::Val{_ray_cone}) = _vector_matrix

`options`

Sometimes you need further arguments to specify the returned data. These arguments are set at construction of the SubObjectIterator and later passed to the corresponding functions as keyword arguments.

A good example how to use this is faces(C::Cone, face_dim::Int). It is not enough to know that our SubObjectIterator is set in the context of faces of cones; face_dim will be relevant for any type of access occurring in the future.

function faces(C::Cone, face_dim::Int)
   n = face_dim - length(lineality_space(C))
   n < 1 && return nothing
   return SubObjectIterator{Cone}(C.pm_cone, _face_cone, size(Polymake.polytope.faces_of_dim(pm_object(C), n), 1), (f_dim = n,))
end

When this method is called with meaningful input, it creates a SubObjectIterator where the last argument is a NamedTuple specifying that f_dim = n. The information encoded in this NamedTuple will be passed as keyword arguments when calling the access function or any additional method (reconsider their definitions). This allows us to directly ask for that data when implementing these methods:

function _face_cone(::Type{Cone}, C::Polymake.BigObject, i::Base.Integer; f_dim::Int = 0)
   return Cone(Polymake.polytope.Cone(RAYS = C.RAYS[collect(Polymake.to_one_based_indexing(Polymake.polytope.faces_of_dim(C, f_dim)[i])), :], LINEALITY_SPACE = C.LINEALITY_SPACE))
end

function _ray_indices(::Val{_face_cone}, C::Polymake.BigObject; f_dim::Int = 0)
   f = Polymake.to_one_based_indexing(Polymake.polytope.faces_of_dim(C, f_dim))
   return IncidenceMatrix([collect(f[i]) for i in 1:length(f)])
end

Extending the interface

The additional methods offer an intuitive way of interaction for the user, but their current selection is not carved in stone. You can easily add more similar methods by extending the list that is iterated over to generate the code. Which list that is usually depends on the output format. vector_matrix returns matrices with either integer or rational elements. The same capabilities hold for point_matrix and generator_matrix:

for (sym, name) in (("point_matrix", "Point Matrix"), ("vector_matrix", "Vector Matrix"), ("generator_matrix", "Generator Matrix"))
    M = Symbol(sym)
    _M = Symbol(string("_", sym))
    @eval begin
        $M(iter::SubObjectIterator{<:AbstractVector{Polymake.Rational}}) = matrix(QQ, Matrix{QQFieldElem}($_M(Val(iter.Acc), iter.Obj; iter.options...)))
        $M(iter::SubObjectIterator{<:AbstractVector{Polymake.Integer}}) = matrix(ZZ, $_M(Val(iter.Acc), iter.Obj; iter.options...))
        $_M(::Any, ::Polymake.BigObject) = throw(ArgumentError(string($name, " not defined in this context.")))
    end
end

The second string (name) of each pair determines the name that is printed in error messages.

If required, one can of course write completely new functions to extend the interface.

SubObjectIterator

Creating a working SubObjectIterator