From aade2d1ea613d974a13f2e8f70359a479533dc80 Mon Sep 17 00:00:00 2001 From: Oscar Dowson Date: Mon, 10 Aug 2026 15:07:10 +1200 Subject: [PATCH] [docs] make a single public API page --- docs/DocumenterReference.jl | 234 ++++++++++++++++++++ docs/Project.toml | 1 + docs/make.jl | 54 ++++- docs/src/reference/callbacks.md | 51 ----- docs/src/reference/constraints.md | 48 ---- docs/src/reference/errors.md | 86 ------- docs/src/reference/models.md | 171 -------------- docs/src/reference/modification.md | 19 -- docs/src/reference/nonlinear.md | 49 ---- docs/src/reference/standard_form.md | 161 -------------- docs/src/reference/variables.md | 33 --- docs/src/submodules/FileFormats/overview.md | 2 +- docs/src/submodules/Nonlinear/overview.md | 4 +- docs/src/submodules/Utilities/reference.md | 1 + 14 files changed, 281 insertions(+), 633 deletions(-) create mode 100644 docs/DocumenterReference.jl delete mode 100644 docs/src/reference/callbacks.md delete mode 100644 docs/src/reference/constraints.md delete mode 100644 docs/src/reference/errors.md delete mode 100644 docs/src/reference/models.md delete mode 100644 docs/src/reference/modification.md delete mode 100644 docs/src/reference/nonlinear.md delete mode 100644 docs/src/reference/standard_form.md delete mode 100644 docs/src/reference/variables.md diff --git a/docs/DocumenterReference.jl b/docs/DocumenterReference.jl new file mode 100644 index 0000000000..1d021b1fe4 --- /dev/null +++ b/docs/DocumenterReference.jl @@ -0,0 +1,234 @@ +# Copyright 2023, Oscar Dowson and contributors +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, You can obtain one at https://mozilla.org/MPL/2.0/. + +module DocumenterReference + +import Documenter +import Markdown +import MarkdownAST + +@enum( + DocType, + DOCTYPE_ABSTRACT_TYPE, + DOCTYPE_CONSTANT, + DOCTYPE_FUNCTION, + DOCTYPE_MACRO, + DOCTYPE_MODULE, + DOCTYPE_STRUCT, +) + +struct _Config + current_module::Module + subdirectory::String + modules::Dict{Module,<:Vector} + sort_by::Function + filter::Function +end + +const CONFIG = _Config[] + +abstract type APIBuilder <: Documenter.Builder.DocumentPipeline end + +Documenter.Selectors.order(::Type{APIBuilder}) = 0.0 + +""" + automatic_reference_documentation(; + subdirectory::String, + modules::Dict{Module,Vector{Pair{String,DocType}}}, + sort_by::Function = identity, + filter::Function = _ -> true, + ) + +Automatically creates the API reference documentation for `current_module` and +returns a `Vector` which can be used in the `pages` argument of +`Documenter.makedocs`. + +## Arguments + + * `current_module`: the module from which to create an API reference. + * `subdirectory`: the directory relative to the documentation root in which to + write the API files. + * `modules`: a dictionary mapping modules to a vector of non-exported + docstrings to include in the API reference. Each element is a pair which maps + the docstring signature to a [`DocumenterReference.DocType`](@ref) enum. + +## Multiple instances + +Each time you call this function, a new object is added to the global variable +`DocumenterReference.CONFIG`. +""" +function automatic_reference_documentation(; + subdirectory::String, + modules::Vector, + sort_by::Function = identity, + filter::Function = _ -> true, +) + _to_extras(m::Module) = m => Any[] + _to_extras(m::Pair) = m + _modules = Dict(_to_extras(m) for m in modules) + list_of_pages = Any[] + for m in modules + current_module = first(_to_extras(m)) + pages = _automatic_reference_documentation( + current_module; + subdirectory, + modules = _modules, + sort_by, + filter, + ) + push!(list_of_pages, "$current_module" => pages) + end + return "API Reference" => list_of_pages +end + +function _automatic_reference_documentation( + current_module::Module; + subdirectory::String, + modules::Dict{Module,<:Vector}, + sort_by::Function, + filter::Function, +) + config = _Config(current_module, subdirectory, modules, sort_by, filter) + push!(CONFIG, config) + return "$subdirectory/$current_module.md" +end + +function _exported_symbols(mod, config) + contents = Pair{Symbol,DocType}[] + for n in filter(config.filter, names(mod; all = true)) + f = getfield(mod, n) + f_str = string(f) + if startswith(f_str, "@") + push!(contents, n => DOCTYPE_MACRO) + elseif startswith(f_str, "Abstract") + push!(contents, n => DOCTYPE_ABSTRACT_TYPE) + elseif f isa Type + push!(contents, n => DOCTYPE_STRUCT) + elseif f isa Function + if islowercase(f_str[1]) + push!(contents, n => DOCTYPE_FUNCTION) + else + push!(contents, n => DOCTYPE_STRUCT) + end + elseif f isa Module + push!(contents, n => DOCTYPE_MODULE) + else + push!(contents, n => DOCTYPE_CONSTANT) + end + end + order = Dict( + DOCTYPE_MODULE => 0, + DOCTYPE_MACRO => 1, + DOCTYPE_FUNCTION => 2, + DOCTYPE_ABSTRACT_TYPE => 3, + DOCTYPE_STRUCT => 4, + DOCTYPE_CONSTANT => 5, + ) + return sort(contents; by = x -> (order[x[2]], "$(x[1])")) +end + +function _iterate_over_symbols(f, config) + current_module = config.current_module + modules = get(config.modules, config.current_module, Any[]) + key_types = vcat(_exported_symbols(current_module, config), modules) + for (key, type) in key_types + if key isa Symbol + doc = Base.Docs.doc(Base.Docs.Binding(current_module, key)) + if occursin("No documentation found.", string(doc)) + if type == DOCTYPE_MODULE + mod = getfield(current_module, key) + if mod == current_module || !haskey(config.modules, mod) + continue + end + else + error("Documentation missing for $key") + end + end + end + f(key, type) + end + return +end + +function _to_string(x::DocType) + if x == DOCTYPE_ABSTRACT_TYPE + return "abstract type" + elseif x == DOCTYPE_CONSTANT + return "constant" + elseif x == DOCTYPE_FUNCTION + return "function" + elseif x == DOCTYPE_MACRO + return "macro" + elseif x == DOCTYPE_MODULE + return "module" + elseif x == DOCTYPE_STRUCT + return "struct" + end +end + +function _build_api_page(document::Documenter.Document, config::_Config) + subdir = config.subdirectory + overview_md = """ + ```@meta + CurrentModule = MathOptInterface + DocTestSetup = quote + import MathOptInterface as MOI + end + DocTestFilters = [r"MathOptInterface|MOI"] + EditURL = nothing + ``` + + # [$(config.current_module)](@id DocumenterReference_$(config.current_module)) + + This page lists the public API of `$(config.current_module)`. + + !!! info + This page is an unstructured list of the $(config.current_module) API. For a + more structured overview, read the Manual or Tutorial parts of this + documentation. + + Because we use names similar to `Base` like `get` and `set`, MathOptInterface + intentionally does not `export` the public API. Instead, to use MOI, import it + as follows: + ```julia + import MathOptInterface as MOI + ``` + """ + list_of_docstrings = String[] + _iterate_over_symbols(config) do key, type + if type == DOCTYPE_MODULE + return + end + push!( + list_of_docstrings, + "## `$key`\n\n```@docs\n$(config.current_module).$key\n```\n\n", + ) + return + end + md_page = Markdown.parse(overview_md * join(list_of_docstrings, "\n")) + filename = "$subdir/$(config.current_module).md" + document.blueprint.pages[filename] = Documenter.Page( + joinpath(document.user.source, filename), + joinpath(document.user.build, filename), + document.user.build, + md_page.content, + Documenter.Globals(), + convert(MarkdownAST.Node, md_page), + ) + return +end + +function Documenter.Selectors.runner( + ::Type{APIBuilder}, + document::Documenter.Document, +) + @info "APIBuilder: creating API reference" + for config in CONFIG + _build_api_page(document, config) + end + return +end + +end # module diff --git a/docs/Project.toml b/docs/Project.toml index 26713e4f16..df41d49df6 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -2,6 +2,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6" JSONSchema = "7d188eb4-7ad8-530c-ae41-71a32a6d4692" +MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391" MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee" [compat] diff --git a/docs/make.jl b/docs/make.jl index 0bd6f6f707..081f7d1c50 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -16,6 +16,45 @@ const _IS_GITHUB_ACTIONS = get(ENV, "GITHUB_ACTIONS", "false") == "true" # Pass --pdf to build the PDF. On GitHub actions, we always build the PDF. const _PDF = findfirst(isequal("--pdf"), ARGS) !== nothing || _IS_GITHUB_ACTIONS +# ============================================================================== +# API +# ============================================================================== + +include(joinpath(@__DIR__, "DocumenterReference.jl")) +empty!(DocumenterReference.CONFIG) + +api_reference = DocumenterReference.automatic_reference_documentation(; + subdirectory = "api", + modules = [MathOptInterface], + filter = (name::Symbol) -> begin + if name in [ + :AnyAttribute, + :FunctionTypeMismatch, + :Index, + :SetTypeMismatch, + :correct_throw_add_constraint_error_fallback, + :dict_compare, + :eval, + :fix_message, + :func_type, + :get_fallback, + :include, + :precompile_constraint, + :precompile_model, + :precompile_variables, + :set_type, + :sum_dict, + :supports_fallback, + :throw_add_constraint_error_fallback, + :throw_modify_not_allowed, + :throw_set_error_fallback, + ] + return false + end + return !any(k -> startswith("$name", k), ["#", "_", "@_"]) + end, +) + # ============================================================================== # Documentation structure # ============================================================================== @@ -43,16 +82,7 @@ const _PAGES = [ "background/infeasibility_certificates.md", "background/naming_conventions.md", ], - "API Reference" => [ - "reference/standard_form.md", - "reference/models.md", - "reference/variables.md", - "reference/constraints.md", - "reference/modification.md", - "reference/nonlinear.md", - "reference/callbacks.md", - "reference/errors.md", - ], + api_reference, "Submodules" => [ "Benchmarks" => [ "Overview" => "submodules/Benchmarks/overview.md", @@ -147,8 +177,7 @@ Documenter.DocMeta.setdocmeta!( size_threshold_ignore = [ "changelog.md", "release_notes.md", - "reference/models.md", - "reference/standard_form.md", + "api/MathOptInterface.md", "submodules/Bridges/list_of_bridges.md", "submodules/Bridges/reference.md", "submodules/Utilities/reference.md", @@ -164,6 +193,7 @@ Documenter.DocMeta.setdocmeta!( "https://arxiv.org/abs/2002.03447", # https://github.com/JuliaDocs/Documenter.jl/issues/2834 "https://lpsolve.sourceforge.net/5.5/CPLEX-format.htm", + "https://www.fico.com/fico-xpress-optimization/docs/dms2021-01/solver/optimizer/HTML/chapter10_sec_section102.html", ], modules = [MathOptInterface], checkdocs = :exports, diff --git a/docs/src/reference/callbacks.md b/docs/src/reference/callbacks.md deleted file mode 100644 index 573b5023b8..0000000000 --- a/docs/src/reference/callbacks.md +++ /dev/null @@ -1,51 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# Callbacks - -```@docs -AbstractCallback -AbstractSubmittable -submit -``` - -## Attributes - -```@docs -CallbackNodeStatus -CallbackVariablePrimal -CallbackNodeStatusCode -CALLBACK_NODE_STATUS_INTEGER -CALLBACK_NODE_STATUS_FRACTIONAL -CALLBACK_NODE_STATUS_UNKNOWN -``` - -## Lazy constraints - -```@docs -LazyConstraintCallback -LazyConstraint -``` - -## User cuts - -```@docs -UserCutCallback -UserCut -``` - -## Heuristic solutions - -```@docs -HeuristicCallback -HeuristicSolution -HeuristicSolutionStatus -HEURISTIC_SOLUTION_ACCEPTED -HEURISTIC_SOLUTION_REJECTED -HEURISTIC_SOLUTION_UNKNOWN -``` diff --git a/docs/src/reference/constraints.md b/docs/src/reference/constraints.md deleted file mode 100644 index bc45abc2a6..0000000000 --- a/docs/src/reference/constraints.md +++ /dev/null @@ -1,48 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# [Constraints](@id constraints_ref) - -## Types - -```@docs -ConstraintIndex -``` - -## Functions - -```@docs -is_valid(::ModelLike,::ConstraintIndex) -add_constraint -add_constraints -transform -supports_constraint -``` - -## Attributes - -```@docs -AbstractConstraintAttribute -ConstraintName -ConstraintPrimalStart -ConstraintDualStart -ConstraintPrimal -ConstraintDual -ConstraintBasisStatus -ConstraintFunction -CanonicalConstraintFunction -ConstraintSet -BasisStatusCode -BASIC -NONBASIC -NONBASIC_AT_LOWER -NONBASIC_AT_UPPER -SUPER_BASIC -LagrangeMultiplier -LagrangeMultiplierStart -``` diff --git a/docs/src/reference/errors.md b/docs/src/reference/errors.md deleted file mode 100644 index 2e8d914db5..0000000000 --- a/docs/src/reference/errors.md +++ /dev/null @@ -1,86 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# Errors - -When an MOI call fails on a model, precise errors should be thrown when possible -instead of simply calling `error` with a message. The docstrings for the -respective methods describe the errors that the implementation should throw in -certain situations. This error-reporting system allows code to distinguish -between internal errors (that should be shown to the user) and unsupported -operations which may have automatic workarounds. - -When an invalid index is used in an MOI call, an [`InvalidIndex`](@ref) is -thrown: -```@docs -InvalidIndex -``` - -When an invalid result index is used to retrieve an attribute, a -[`ResultIndexBoundsError`](@ref) is thrown: -```@docs -ResultIndexBoundsError -check_result_index_bounds -``` - -As discussed in [JuMP mapping](@ref), for scalar constraint with a nonzero -function constant, a [`ScalarFunctionConstantNotZero`](@ref) exception may be -thrown: -```@docs -ScalarFunctionConstantNotZero -``` - -Some [`VariableIndex`](@ref) constraints cannot be combined on the same -variable: -```@docs -LowerBoundAlreadySet -UpperBoundAlreadySet -``` - -As discussed in [`AbstractCallback`](@ref), trying to [`get`](@ref) attributes -inside a callback may throw: -```@docs -OptimizeInProgress -``` - -Trying to submit the wrong type of [`AbstractSubmittable`](@ref) inside an -[`AbstractCallback`](@ref) (for example, a [`UserCut`](@ref) inside a -[`LazyConstraintCallback`](@ref)) will throw: -```@docs -InvalidCallbackUsage -``` - -The rest of the errors defined in MOI fall in two categories represented by the -following two abstract types: -```@docs -UnsupportedError -NotAllowedError -``` - -The different [`UnsupportedError`](@ref) and [`NotAllowedError`](@ref) are the -following errors: -```@docs -UnsupportedAttribute -GetAttributeNotAllowed -SetAttributeNotAllowed -AddVariableNotAllowed -UnsupportedConstraint -AddConstraintNotAllowed -ModifyConstraintNotAllowed -ModifyObjectiveNotAllowed -DeleteNotAllowed -UnsupportedSubmittable -SubmitNotAllowed -UnsupportedNonlinearOperator -``` - -Note that setting the [`ConstraintFunction`](@ref) of a [`VariableIndex`](@ref) -constraint is not allowed: -```@docs -SettingVariableIndexNotAllowed -``` diff --git a/docs/src/reference/models.md b/docs/src/reference/models.md deleted file mode 100644 index c9cef1e483..0000000000 --- a/docs/src/reference/models.md +++ /dev/null @@ -1,171 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# Models - -## Attribute interface - -```@docs -is_set_by_optimize -is_copyable -get -get! -set -supports -attribute_value_type -``` - -## Model interface - -```@docs -ModelLike -is_empty -empty! -write_to_file -read_from_file -supports_incremental_interface -copy_to -IndexMap -``` - -## Model attributes - -```@docs -AbstractModelAttribute -Name -ObjectiveFunction -ObjectiveFunctionType -ObjectiveSense -OptimizationSense -MIN_SENSE -MAX_SENSE -FEASIBILITY_SENSE -NumberOfVariables -ListOfVariableIndices -ListOfConstraintTypesPresent -NumberOfConstraints -ListOfConstraintIndices -ListOfOptimizerAttributesSet -ListOfModelAttributesSet -ListOfVariableAttributesSet -ListOfVariablesWithAttributeSet -ListOfConstraintAttributesSet -ListOfConstraintsWithAttributeSet -UserDefinedFunction -ListOfSupportedNonlinearOperators -ConstraintBridgingCost -VariableBridgingCost -``` - -## Optimizer interface - -```@docs -AbstractOptimizer -OptimizerWithAttributes -optimize! -optimize!(::ModelLike, ::ModelLike) -instantiate -default_cache -``` - -## Optimizer attributes - -```@docs -AbstractOptimizerAttribute -SolverName -SolverVersion -Silent -TimeLimitSec -ObjectiveLimit -SolutionLimit -NodeLimit -RawOptimizerAttribute -NumberOfThreads -RawSolver -AbsoluteGapTolerance -RelativeGapTolerance -AutomaticDifferentiationBackend -``` - -List of attributes useful for optimizers - -```@docs -TerminationStatus -TerminationStatusCode -OPTIMIZE_NOT_CALLED -OPTIMAL -INFEASIBLE -DUAL_INFEASIBLE -LOCALLY_SOLVED -LOCALLY_INFEASIBLE -INFEASIBLE_OR_UNBOUNDED -ALMOST_OPTIMAL -ALMOST_INFEASIBLE -ALMOST_DUAL_INFEASIBLE -ALMOST_LOCALLY_SOLVED -ITERATION_LIMIT -TIME_LIMIT -NODE_LIMIT -SOLUTION_LIMIT -MEMORY_LIMIT -OBJECTIVE_LIMIT -NORM_LIMIT -OTHER_LIMIT -SLOW_PROGRESS -NUMERICAL_ERROR -INVALID_MODEL -INVALID_OPTION -INTERRUPTED -OTHER_ERROR -PrimalStatus -DualStatus -RawStatusString -ResultCount -ObjectiveValue -DualObjectiveValue -ObjectiveBound -RelativeGap -SolveTimeSec -SimplexIterations -BarrierIterations -NodeCount -``` - -### Result Status - -```@docs -ResultStatusCode -NO_SOLUTION -FEASIBLE_POINT -NEARLY_FEASIBLE_POINT -INFEASIBLE_POINT -INFEASIBILITY_CERTIFICATE -NEARLY_INFEASIBILITY_CERTIFICATE -REDUCTION_CERTIFICATE -NEARLY_REDUCTION_CERTIFICATE -UNKNOWN_RESULT_STATUS -OTHER_RESULT_STATUS -``` - -### Conflict Status - -```@docs -compute_conflict! -ConflictStatus -ConflictStatusCode -COMPUTE_CONFLICT_NOT_CALLED -NO_CONFLICT_EXISTS -NO_CONFLICT_FOUND -CONFLICT_FOUND -ConflictCount -ConstraintConflictStatus -ConflictParticipationStatusCode -NOT_IN_CONFLICT -IN_CONFLICT -MAYBE_IN_CONFLICT -``` diff --git a/docs/src/reference/modification.md b/docs/src/reference/modification.md deleted file mode 100644 index 65a50c22fa..0000000000 --- a/docs/src/reference/modification.md +++ /dev/null @@ -1,19 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# Modifications - -```@docs -modify -AbstractFunctionModification -ScalarConstantChange -VectorConstantChange -ScalarCoefficientChange -ScalarQuadraticCoefficientChange -MultirowChange -``` diff --git a/docs/src/reference/nonlinear.md b/docs/src/reference/nonlinear.md deleted file mode 100644 index b904b0ca6d..0000000000 --- a/docs/src/reference/nonlinear.md +++ /dev/null @@ -1,49 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# Nonlinear programming - -## Types -```@docs -AbstractNLPEvaluator -NLPBoundsPair -NLPBlockData -``` - -## Attributes - -```@docs -NLPBlock -NLPBlockDual -NLPBlockDualStart -``` - -## Functions - -```@docs -initialize -features_available -eval_objective -eval_constraint -eval_objective_gradient -jacobian_structure -eval_constraint_gradient -constraint_gradient_structure -eval_constraint_jacobian -eval_constraint_jacobian_product -eval_constraint_jacobian_transpose_product -hessian_lagrangian_structure -hessian_objective_structure -hessian_constraint_structure -eval_hessian_objective -eval_hessian_constraint -eval_hessian_lagrangian -eval_hessian_lagrangian_product -objective_expr -constraint_expr -``` diff --git a/docs/src/reference/standard_form.md b/docs/src/reference/standard_form.md deleted file mode 100644 index 2008be8cd0..0000000000 --- a/docs/src/reference/standard_form.md +++ /dev/null @@ -1,161 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# Standard form - -## Functions - -```@docs -AbstractFunction -output_dimension -constant -``` - -## Scalar functions - -```@docs -AbstractScalarFunction -VariableIndex -ScalarAffineTerm -ScalarAffineFunction -ScalarQuadraticTerm -ScalarQuadraticFunction -ScalarNonlinearFunction -``` - -## Vector functions - -```@docs -AbstractVectorFunction -VectorOfVariables -VectorAffineTerm -VectorAffineFunction -VectorQuadraticTerm -VectorQuadraticFunction -VectorNonlinearFunction -``` - -## Sets - -```@docs -AbstractSet -AbstractScalarSet -AbstractVectorSet -``` - -### Utilities - -```@docs -dimension -dual_set -dual_set_type -constant(s::EqualTo) -supports_dimension_update -update_dimension -``` - -## Scalar sets - -List of recognized scalar sets. -```@docs -GreaterThan -LessThan -EqualTo -Interval -Integer -ZeroOne -Semicontinuous -Semiinteger -Parameter -``` - -## Vector sets - -List of recognized vector sets. -```@docs -Reals -Zeros -Nonnegatives -Nonpositives -NormInfinityCone -NormOneCone -NormCone -SecondOrderCone -RotatedSecondOrderCone -GeometricMeanCone -DualGeometricMeanCone -ExponentialCone -DualExponentialCone -PowerCone -DualPowerCone -RelativeEntropyCone -NormSpectralCone -NormNuclearCone -SOS1 -SOS2 -Indicator -ActivationCondition -ACTIVATE_ON_ZERO -ACTIVATE_ON_ONE -Complements -HyperRectangle -Scaled -VectorNonlinearOracle -``` - -## Constraint programming sets - -```@docs -AllDifferent -BinPacking -Circuit -CountAtLeast -CountBelongs -CountDistinct -CountGreaterThan -Cumulative -Path -Reified -Table -``` - -## Matrix sets - -Matrix sets are vectorized to be subtypes of [`AbstractVectorSet`](@ref). - -For sets of symmetric matrices, storing both the -`(i, j)` and `(j, i)` elements is redundant. Use the -[`AbstractSymmetricMatrixSetTriangle`](@ref) set to represent only the -vectorization of the upper triangular part of the matrix. - -When the matrix of expressions constrained to be in the set is not symmetric, -and hence additional constraints are needed to force the equality of the -`(i, j)` and `(j, i)` elements, use the -[`AbstractSymmetricMatrixSetSquare`](@ref) set. - -The [`Bridges.Constraint.SquareBridge`](@ref) can transform a set from the -square form to the [`triangular_form`](@ref) by adding appropriate constraints -if the `(i, j)` and `(j, i)` expressions are different. - -```@docs -AbstractSymmetricMatrixSetTriangle -AbstractSymmetricMatrixSetSquare -side_dimension -triangular_form -``` - -List of recognized matrix sets. -```@docs -PositiveSemidefiniteConeTriangle -PositiveSemidefiniteConeSquare -HermitianPositiveSemidefiniteConeTriangle -LogDetConeTriangle -LogDetConeSquare -RootDetConeTriangle -RootDetConeSquare -``` diff --git a/docs/src/reference/variables.md b/docs/src/reference/variables.md deleted file mode 100644 index d4233e7bf5..0000000000 --- a/docs/src/reference/variables.md +++ /dev/null @@ -1,33 +0,0 @@ -```@meta -CurrentModule = MathOptInterface -DocTestSetup = quote - import MathOptInterface as MOI -end -DocTestFilters = [r"MathOptInterface|MOI"] -``` - -# Variables - -## Functions - -```@docs -add_variable -add_variables -add_constrained_variable -add_constrained_variables -supports_add_constrained_variable -supports_add_constrained_variables -is_valid(::ModelLike,::VariableIndex) -delete(::ModelLike, ::VariableIndex) -delete(::ModelLike, ::Vector{VariableIndex}) -``` - -## Attributes - -```@docs -AbstractVariableAttribute -VariableName -VariablePrimalStart -VariablePrimal -VariableBasisStatus -``` diff --git a/docs/src/submodules/FileFormats/overview.md b/docs/src/submodules/FileFormats/overview.md index 9982fe3f88..af87aa18b7 100644 --- a/docs/src/submodules/FileFormats/overview.md +++ b/docs/src/submodules/FileFormats/overview.md @@ -207,7 +207,7 @@ julia> src_2 = MOI.FileFormats.Model(format = MOI.FileFormats.FORMAT_MPS); julia> read!(io, src_2); ``` -## ScalarNonlinearFunction +## [ScalarNonlinearFunction](@id FileFormats_ScalarNonlinearFunction) By default, reading a `.nl` or `.mof.json` that contains nonlinear expressions will create an [`NLPBlock`](@ref). diff --git a/docs/src/submodules/Nonlinear/overview.md b/docs/src/submodules/Nonlinear/overview.md index f93d8b470c..7e70b39dca 100644 --- a/docs/src/submodules/Nonlinear/overview.md +++ b/docs/src/submodules/Nonlinear/overview.md @@ -266,7 +266,7 @@ julia> Nonlinear.register_operator(model, :my_g2, 2, g, ∇g) MathOptInterface communicates the nonlinear portion of an optimization problem to solvers using concrete subtypes of [`AbstractNLPEvaluator`](@ref), which -implement the [Nonlinear programming](@ref) API. +implement the Nonlinear programming API. Create an [`AbstractNLPEvaluator`](@ref) from [`Nonlinear.Model`](@ref) using [`Nonlinear.Evaluator`](@ref). @@ -286,7 +286,7 @@ julia> evaluator = Nonlinear.Evaluator(model, Nonlinear.ExprGraphOnly(), [x]) Nonlinear.Evaluator with available features: * :ExprGraph ``` -The functions of the [Nonlinear programming](@ref) API implemented by +The functions of the Nonlinear programming API implemented by [`Nonlinear.Evaluator`](@ref) depends upon the chosen [`Nonlinear.AbstractAutomaticDifferentiation`](@ref) backend. diff --git a/docs/src/submodules/Utilities/reference.md b/docs/src/submodules/Utilities/reference.md index 745ead9bc0..92ed63bd15 100644 --- a/docs/src/submodules/Utilities/reference.md +++ b/docs/src/submodules/Utilities/reference.md @@ -228,6 +228,7 @@ Utilities.AbstractDistance Utilities.ProjectionUpperBoundDistance Utilities.distance_to_set Utilities.set_dot +Utilities.SetDotScalingVector ``` ## DoubleDicts