added domain-related functions and docs

Author: e-duar-do

docs/make.jl

@@ -3,6 +3,12 @@ using Documenter
 
 DocMeta.setdocmeta!(DynOptInterface, :DocTestSetup, :(using DynOptInterface); recursive=true)
 
+const _PAGES = [
+    "API Reference" => [
+        "reference/domains.md",
+    ],
+]
+
 makedocs(;
     modules=[DynOptInterface],
     authors="Eduardo M. G. Vila <72969764+e-duar-do@users.noreply.github.com> and contributors",
@@ -12,12 +18,10 @@ makedocs(;
         edit_link="dev",
         assets=String[],
     ),
-    pages=[
-        "Home" => "index.md",
-    ],
+    pages=_PAGES,
 )
 
 deploydocs(;
     repo="github.com/JuDO-dev/DynOptInterface.jl",
     devbranch="dev",
-)
+)

docs/src/reference/domains.md

@@ -0,0 +1,15 @@
+```@meta
+CurrentModule = DynOptInterface
+```
+
+# Domains
+
+```@docs
+AbstractDomain
+DomainIndex
+supports_domain
+UnsupportedDomain
+AddDomainNotAllowed
+add_domain
+Interval
+```

src/DynOptInterface.jl

@@ -2,8 +2,6 @@ module DynOptInterface
 
 import MathOptInterface as MOI
 
-abstract type AbstractDomain end
-
 include("domains.jl")
 
 end

src/domains.jl

@@ -1,26 +1,88 @@
+"""
+    AbstractDomain
+
+Abstract supertype for domains.
+"""
+abstract type AbstractDomain end
+
+"""
+    DomainIndex{D}
+
+A type-safe wrapper for `Int64` for use in referencing domains.
+The parameter `D` is the type of the domain.
+"""
+struct DomainIndex{D}
+    value::Int64
+end
+
 """
     supports_domain(
-        model::MOI.ModelLike,
-        ::Type{<:AbstractDomain},
-    )::Bool
+        model::ModelLike,
+        ::Type{D},
+    ) where {D<:AbstractDomain}
 
-Returns true if a domain type is supported and false ortherwise.
+Return a `Bool` indicating whether `model` supports domains of type `D`.
 """
-function supports_domain(
-    ::MOI.ModelLike,
-    ::Type{<:AbstractDomain})
+function supports_domain(::Model, ::Type{<:AbstractDomain})
     return false
 end
 
 """
-    FixedDomain{T} <: AbstractDomain
-        initial::T
-        final::T
+    struct UnsupportedDomain{D<:AbstractDomain} <: MOI.UnsupportedError
+        message::String
+    end
+
+An error indicating that domains of type `D` are not supported by the model,
+that is, that [`supports_domain`](@ref) returns `false`.
+"""
+struct UnsupportedDomain{D<:AbstractDomain} <: MOI.UnsupportedError
+    message::String
+end
+
+"""
+    struct AddDomainNotAllowed{D<:AbstractDomain} <: MOI.NotAllowedError
+        message::String
+    end
+
+An error indicating that domains of type `D` are supported but cannot be added 
+to the current state of the model.
+"""
+struct AddDomainNotAllowed{D<:AbstractDomain} <: MOI.NotAllowedError
+    message::String
+end
+AddDomainNotAllowed{D}() where {D} = AddDomainNotAllowed{D}("")
+
+"""
+    add_domain()
+
+Add `domain` to the model. An [`UnsupportedDomain`](@ref) error is thrown if 
+`model` does not support 
+"""
+function add_domain(model::MOI.ModelLike, domain::AbstractDomain)
+    return throw_add_domain_error_fallback(model, domain)
+end
+
+function throw_add_domain_error_fallback(
+    model::MOI.ModelLike,
+    domain::AbstractDomain;
+    error_if_supported = AddDomainNotAllowed{typeof(domain)}(),
+)
+    if supports_domain(model, typeof(domain))
+        throw(error_if_supported)
+    else
+        throw(UnsupportedConstraint{typeof(domain)}())
+    end
+end
+
+"""
+    struct Interval{T0, TF} <: AbstractDomain
+        t_0::T0
+        t_f::TF
     end
 
-A domain type with fixed initial and final limits.
+A one-dimensional domain where `t_0` and `t_f` may be real numbers or variable indices.  
 """
-struct FixedDomain{T} <: AbstractDomain
-    initial::T
-    final::T
+struct Interval{T0, TF} <: AbstractDomain
+    t_0::T0
+    t_f::TF
 end