From 8fa52e084adbd483a0f16ae31430fc43f808fc32 Mon Sep 17 00:00:00 2001 From: odow Date: Thu, 1 Jul 2021 09:57:53 +1200 Subject: [PATCH 1/3] List model attributes in documentation --- docs/src/manual/models.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/src/manual/models.md b/docs/src/manual/models.md index 346b6881ba..269ee350ef 100644 --- a/docs/src/manual/models.md +++ b/docs/src/manual/models.md @@ -50,3 +50,22 @@ Attributes can be set in different ways: * or it is set to contain the result of the optimization during [`optimize!`](@ref) like [`VariablePrimal`](@ref). +The following attributes are available for models: + + * [`Name`](@ref) + + * [`ObjectiveFunction`](@ref) + * [`ObjectiveFunctionType`](@ref) + * [`ObjectiveSense`](@ref) + + * [`NumberOfVariables`](@ref) + * [`ListOfVariableIndices`](@ref) + + * [`ListOfConstraintTypesPresent`](@ref) + * [`NumberOfConstraints`](@ref) + * [`ListOfConstraintIndices`](@ref) + + * [`ListOfOptimizerAttributesSet`](@ref) + * [`ListOfModelAttributesSet`](@ref) + * [`ListOfVariableAttributesSet`](@ref) + * [`ListOfConstraintAttributesSet`](@ref) From c9db1e7ab5d3555aebce352bcbcaa716c59991ad Mon Sep 17 00:00:00 2001 From: odow Date: Thu, 1 Jul 2021 14:40:28 +1200 Subject: [PATCH 2/3] Expand section --- docs/src/manual/models.md | 74 ++++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 17 deletions(-) diff --git a/docs/src/manual/models.md b/docs/src/manual/models.md index 269ee350ef..437540a0b5 100644 --- a/docs/src/manual/models.md +++ b/docs/src/manual/models.md @@ -17,10 +17,9 @@ from the [`ModelLike`](@ref) abstract type. Notably missing from the model API is the method to solve an optimization problem. `ModelLike` objects may store an instance (e.g., in memory or backed by a file format) without being linked to a particular solver. In addition to the -model API, MOI defines [`AbstractOptimizer`](@ref). - -*Optimizers* (or solvers) implement the model API (inheriting from `ModelLike`) -and additionally provide methods to solve the model. +model API, MOI defines [`AbstractOptimizer`](@ref) and provides methods to solve +the model and interact with solutions. See the [Optimizers](@ref) section for +more details. !!! info Throughout the rest of the manual, `model` is used as a generic `ModelLike`, @@ -39,33 +38,74 @@ and additionally provide methods to solve the model. ## Attributes -Attributes can be set in different ways: +Attributes are properties of the model that can be queried and modified. These +include constants such as the number of variables in a model [`NumberOfVariables`](@ref)), +and properties of variables and constraints such as the name of a variable +([`VariableName`](@ref)). + +There are four types of attributes: + + * Model attributes (subtypes of [`AbstractModelAttribute`](@ref)) refer to + properties of a model. + * Optimizer attributes (subtypes of [`AbstractOptimizerAttribute`](@ref)) refer + to properties of an optimizer. + * Constraint attributes (subtypes of [`AbstractConstraintAttribute`](@ref)) + refer to properties of an individual constraint. + * Variable attributes (subtypes of [`AbstractVariableAttribute`](@ref)) refer + to properties of an individual variable. + +Some attributes are constants that can be queried by the user but not modified, +while other attributes can be modified by the user. -* it is either set when the model is created like [`SolverName`](@ref) and - [`RawSolver`](@ref), -* or explicitly when the model is copied like [`ObjectiveSense`](@ref), -* or implicitly, e.g., [`NumberOfVariables`](@ref) is implicitly set by - [`add_variable`](@ref) and [`ConstraintFunction`](@ref) is implicitly set by - [`add_constraint`](@ref). -* or it is set to contain the result of the optimization during - [`optimize!`](@ref) like [`VariablePrimal`](@ref). +All interactions with attributes occur through the [`get`](@ref) and [`set`](@ref) +functions. + +Consult the docstsrings of each attribute for information on what it represents. + +## Model attributes The following attributes are available for models: * [`Name`](@ref) - * [`ObjectiveFunction`](@ref) * [`ObjectiveFunctionType`](@ref) * [`ObjectiveSense`](@ref) - * [`NumberOfVariables`](@ref) * [`ListOfVariableIndices`](@ref) - * [`ListOfConstraintTypesPresent`](@ref) * [`NumberOfConstraints`](@ref) * [`ListOfConstraintIndices`](@ref) - * [`ListOfOptimizerAttributesSet`](@ref) * [`ListOfModelAttributesSet`](@ref) * [`ListOfVariableAttributesSet`](@ref) * [`ListOfConstraintAttributesSet`](@ref) + +## Optimizer attributes + +The following attributes are available for optimizers: + + - [`SolverName`](@ref) + - [`RawOptimizerAttribute`](@ref) + - [`Silent`](@ref) + - [`TimeLimitSec`](@ref) + - [`NumberOfThreads`](@ref) + - [`RawSolver`](@ref) + +In addition, optimizers should implement the following attributes to provide +access to solutions: + + - [`TerminationStatus`](@ref) + - [`TerminationStatusCode`](@ref) + - [`PrimalStatus`](@ref) + - [`DualStatus`](@ref) + - [`ResultStatusCode`](@ref) + - [`RawStatusString`](@ref) + - [`ResultCount`](@ref) + - [`ObjectiveValue`](@ref) + - [`DualObjectiveValue`](@ref) + - [`ObjectiveBound`](@ref) + - [`RelativeGap`](@ref) + - [`SolveTimeSec`](@ref) + - [`SimplexIterations`](@ref) + - [`BarrierIterations`](@ref) + - [`NodeCount`](@ref) From 2ae80bed5f3a858847d5c8a7a732d491c9201be5 Mon Sep 17 00:00:00 2001 From: odow Date: Thu, 1 Jul 2021 15:13:49 +1200 Subject: [PATCH 3/3] Fix docs --- docs/src/manual/models.md | 6 +++--- docs/src/manual/solutions.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/manual/models.md b/docs/src/manual/models.md index 437540a0b5..cca29e34de 100644 --- a/docs/src/manual/models.md +++ b/docs/src/manual/models.md @@ -18,8 +18,8 @@ Notably missing from the model API is the method to solve an optimization problem. `ModelLike` objects may store an instance (e.g., in memory or backed by a file format) without being linked to a particular solver. In addition to the model API, MOI defines [`AbstractOptimizer`](@ref) and provides methods to solve -the model and interact with solutions. See the [Optimizers](@ref) section for -more details. +the model and interact with solutions. See the [Solutions](@ref manual_solutions) +section for more details. !!! info Throughout the rest of the manual, `model` is used as a generic `ModelLike`, @@ -54,7 +54,7 @@ There are four types of attributes: * Variable attributes (subtypes of [`AbstractVariableAttribute`](@ref)) refer to properties of an individual variable. -Some attributes are constants that can be queried by the user but not modified, +Some attributes are values that can be queried by the user but not modified, while other attributes can be modified by the user. All interactions with attributes occur through the [`get`](@ref) and [`set`](@ref) diff --git a/docs/src/manual/solutions.md b/docs/src/manual/solutions.md index 620d921ee7..b1e2840cd7 100644 --- a/docs/src/manual/solutions.md +++ b/docs/src/manual/solutions.md @@ -7,7 +7,7 @@ end DocTestFilters = [r"MathOptInterface|MOI"] ``` -# Solutions +# [Solutions](@id manual_solutions) ## Solving and retrieving the results