From 1ce3f15ca7f0fa2c1be54b99fb2bb8bd41779108 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Fri, 5 Jun 2026 16:18:58 +0200 Subject: [PATCH] Document public cone API Export the high-level cone constructor and property helpers. Add docstrings with doctest examples. Co-authored-by: Codex --- README.md | 27 +---------- docs/src/index.md | 27 ++++++----- src/Normaliz.jl | 111 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index f55ca8f..b4b9a10 100644 --- a/README.md +++ b/README.md @@ -17,32 +17,9 @@ To install this package, enter this into the Julia prompt: using Pkg; Pkg.develop(url="https://github.com/Normaliz/Normaliz.jl") ``` -## Basic usage - -Here is an example of using Normaliz.jl: - -```julia -julia> using Normaliz - -julia> xx = Normaliz.NmzMatrix{Normaliz.NmzRational}([1 2 ; 3 5]) -2×2 Normaliz.NmzMatrixAllocated{Normaliz.NmzRational}: - 1 2 - 3 5 - -julia> yy = Normaliz.LongLongCone( Dict( :cone => xx ) ) -Normaliz cone - -julia> Normaliz.get_matrix_cone_property( yy, "ExtremeRays" ) -2×2 Normaliz.NmzMatrixAllocated{CxxWrap.CxxWrapCore.CxxLongLong}: - 1 2 - 3 5 - -julia> Normaliz.get_matrix_cone_property( yy, "SupportHyperplanes" ) -2×2 Normaliz.NmzMatrixAllocated{CxxWrap.CxxWrapCore.CxxLongLong}: - -5 3 - 2 -1 -``` +## Documentation +For more usage information, please [consult the documentation](https://normaliz.github.io/Normaliz.jl). ## Contact diff --git a/docs/src/index.md b/docs/src/index.md index 7d9d9a2..6454051 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -21,21 +21,24 @@ Here is an example of using Normaliz.jl: ```jldoctest julia> using Normaliz -julia> xx = Normaliz.NmzMatrix{Normaliz.NmzRational}([1 2 ; 3 5]) -2×2 Normaliz.NmzMatrixAllocated{Normaliz.NmzRational}: - 1 2 - 3 5 - -julia> yy = Normaliz.LongLongCone( Dict( :cone => xx ) ) +julia> C = Cone(; cone = [1 2; 3 5], grading = [1 1]) Normaliz cone -julia> Normaliz.get_matrix_cone_property( yy, "ExtremeRays" ) -2×2 Normaliz.NmzMatrixAllocated{CxxWrap.CxxWrapCore.CxxLongLong}: +julia> cone_property(C, :HilbertBasis) +2×2 Matrix{BigInt}: 1 2 3 5 -julia> Normaliz.get_matrix_cone_property( yy, "SupportHyperplanes" ) -2×2 Normaliz.NmzMatrixAllocated{CxxWrap.CxxWrapCore.CxxLongLong}: - -5 3 - 2 -1 +julia> cone_property(C, :EmbeddingDim) +2 +``` + +## Public API + +```@docs +Cone +cone_property +known_cone_properties +computed_cone_properties +is_computed ``` diff --git a/src/Normaliz.jl b/src/Normaliz.jl index d6ed8da..ecb776d 100644 --- a/src/Normaliz.jl +++ b/src/Normaliz.jl @@ -5,6 +5,9 @@ import normaliz_jll using CxxWrap +export Cone +export computed_cone_properties, cone_property, is_computed, known_cone_properties + get_libnormaliz_julia_path() = joinpath(@__DIR__, "..", "deps", "src", "build", "lib", "libnormaliz_julia.$(Libdl.dlext)") @wrapmodule(get_libnormaliz_julia_path, :define_module_normaliz) @@ -52,8 +55,66 @@ Base.show(io::IO,x::Cone) = print(io,"Normaliz cone") _string_vector(x) = String.(collect(x)) +""" + known_cone_properties() -> Vector{String} + +Return the names of cone properties known to Normaliz. + +# Examples + +```jldoctest +julia> using Normaliz + +julia> "HilbertBasis" in known_cone_properties() +true +``` +""" known_cone_properties() = _string_vector(_known_cone_properties()) + +""" + computed_cone_properties(cone::Cone) -> Vector{String} + +Return the names of properties that have already been computed for `cone`. + +# Examples + +```jldoctest +julia> using Normaliz + +julia> C = Cone(; cone = [1 2; 3 5]); + +julia> "ExtremeRays" in computed_cone_properties(C) +false + +julia> cone_property(C, :ExtremeRays); + +julia> "ExtremeRays" in computed_cone_properties(C) +true +``` +""" computed_cone_properties(cone::Cone) = _string_vector(_computed_cone_properties(cone)) + +""" + is_computed(cone::Cone, property::Union{AbstractString,Symbol}) -> Bool + +Return whether `property` has already been computed for `cone`. + +# Examples + +```jldoctest +julia> using Normaliz + +julia> C = Cone(; cone = [1 2; 3 5]); + +julia> is_computed(C, :ExtremeRays) +false + +julia> cone_property(C, :ExtremeRays); + +julia> is_computed(C, :ExtremeRays) +true +``` +""" is_computed(cone::Cone, property::AbstractString) = _is_computed(cone, property) is_computed(cone::Cone, property::Symbol) = is_computed(cone, String(property)) @@ -67,6 +128,31 @@ _julia_cone_property(x::CxxWrap.StdLib.StdVector{NmzInteger}) = _julia_cone_property(x::CxxWrap.StdLib.StdVector{NmzRational}) = convert.(Rational{BigInt}, collect(x)) +""" + cone_property(cone::Cone, property::Union{AbstractString,Symbol}) + +Compute and return `property` for `cone`. + +The result is converted to ordinary Julia objects where this is supported, +for example `Matrix{BigInt}`, `Vector{BigInt}`, `BigInt`, +`Rational{BigInt}`, `Float64`, `Int`, or `Bool`. + +# Examples + +```jldoctest +julia> using Normaliz + +julia> C = Cone(; cone = [1 2; 3 5], grading = [1 1]); + +julia> cone_property(C, :HilbertBasis) +2×2 Matrix{BigInt}: + 1 2 + 3 5 + +julia> cone_property(C, :EmbeddingDim) +2 +``` +""" function cone_property(cone::Cone, property::AbstractString) output_type = _cone_property_output_type(property) if output_type == "Matrix" @@ -171,6 +257,31 @@ function LongLongCone(input::AbstractDict) return _LongLongCone(input_keys, input_matrices) end +""" + Cone(input::AbstractDict; type::Symbol = :gmp) + Cone(; type::Symbol = :gmp, kwargs...) + +Construct a Normaliz cone from Julia matrices. + +Inputs use Normaliz input names as keyword arguments or as `Symbol` keys in a +dictionary, for example `:cone` and `:grading`. Matrix entries must be +convertible to rational numbers. By default, Normaliz uses arbitrary precision +integer arithmetic; pass `type = :longlong` to use 64-bit integer arithmetic. + +# Examples + +```jldoctest +julia> using Normaliz + +julia> C = Cone(; cone = [1 2; 3 5], grading = [1 1]) +Normaliz cone + +julia> cone_property(C, :HilbertBasis) +2×2 Matrix{BigInt}: + 1 2 + 3 5 +``` +""" function Cone(input::AbstractDict; type::Symbol = :gmp) if type in (:gmp, :bigint, :NmzInteger) return GMPCone(input)