Internal API
These functions and types are for internal usage and should generally not be accessed during normal use of the package. This will likely be useful if implementing an extension to the package.
Fully documenting every function is currently ongoing. Please raise an issue if information is missing.
Core
DirectSearch.EvaluateInitialPoint
— FunctionEvaluateInitialPoint(p::DSProblem)
Evaluate the initial point.
Throws an error if the initial point is not feasible.
DirectSearch.EvaluatePoint!
— FunctionEvaluatePoint!(p::DSProblem{FT}, trial_points)::IterationOutcome where {FT<:AbstractFloat}
Determine whether the set of trial points result in a dominating, improving, or unsuccesful algorithm iteration. Update the feasible and infeasible incumbent points of p
.
DirectSearch.EvaluatePointSequential!
— FunctionEvaluatePointSequential(p::DSProblem{FT}, trial_points::Vector{Vector{FT}})::IterationOutcome where {FT<:AbstractFloat}
Single-threaded evaluation of set of trial points.
DirectSearch.EvaluatePointParallel!
— FunctionEvaluatePointParallel!(p::DSProblem{FT}, trial_points::Vector{Vector{FT}})::IterationOutcome where {FT<:AbstractFloat}
Multi-threaded evaluation of set of trial points. Uses the number of threads that Julia was started with.
DirectSearch.function_evaluation
— Functionfunction_evaluation(p::DSProblem{T}, trial_point::Vector{T})::(T, Bool) where T
Evaluate a single trial point with the objective function of p
.
By default calls the function with the trial point and returns the result. Override to provide custom evaluation behaviour.
DirectSearch.function_evaluation_parallel
— Functionfunction_evaluation_parallel(p::DSProblem{T}, trial_point::Vector{T})::Tuple{T, Bool} where T
Evaluate a single trial point with the objective function of p
using multiple threads.
Constraints
Missing docstring for DirectSearch.AbstractConstraint
. Check Documenter's build log for details.
DirectSearch.IterationOutcome
— Type@enum IterationOutcome
Has values Dominating, Improving, or Unsuccessful. Corresponding to the three iteration outcomes in MADS-PB.
DirectSearch.ConstraintOutcome
— Type@enum ConstraintOutcome
Has the values Feasible
, WeakInfeasible
, or StrongInfeasible
to classify the outcome of the constraint evaluations of a single point.
A Feasible
point meets the requirement of all constraints with no relaxation.
A WeakInfeasible
outcome has at least one relaxable constraint violated but no unrelaxable constraints violated.
A StrongInfeasible
outcome indicates at least one unrelaxable constraint has been violated or the relaxable constraint violation is reater than hmax.
DirectSearch.CollectionIndex
— TypeCollectionIndex
An Int
wrapper that is used for indexing constraint collections within a Constraints
object.
DirectSearch.ConstraintIndex
— TypeCollectionIndex
An Int
wrapper that is used for indexing constraints within a ConstraintCollection
object.
DirectSearch.ConstraintCollection
— TypeConstraintCollection{FT,C}(h_max::FT,
h_max_update::Function,
aggregator::Function
) where {FT<:AbstractFloat,C<:AbstractConstraint}
Contains multiple constraints of the same type that have the same settings applied to them.
h_max
is the initial hmax value. h_max_update
is a function that should update h_max
given an IterationOutcome
value. aggregator
is a function that will bring all constraint violations of a collection into a single h
result.
Defaults for each of these values are set in the AddProgressiveCollection
and AddExtremeCollection
functions.
Missing docstring for DirectSearch.h_max_update
. Check Documenter's build log for details.
DirectSearch.AbstractProgressiveConstraint
— TypeAbstractProgressiveConstraint <: AbstractConstraint
Parent type for progressive contraints.
DirectSearch.ProgressiveConstraint
— TypeProgressiveConstraint(f::Function)
Create a progressive barrier constraint.
Argument f
is a function that should take a single vector argument and return a value that gives the amount the constraint function has been violated.
A value greater than 0 indicates the function has been violated, 0 shows that the input lies on the constraint, and negative numbers show a feasible value.
Negative numbers may be truncated to 0 without affecting the algorithm.
DirectSearch.ExtremeConstraint
— TypeExtremeConstraint(f::Function)
Create an extreme barrier constraint. Function f
should take a vector argument and return true
or false
to indicate if the vector meets the constraint.
DirectSearch.Constraints
— TypeConstraints{FT<:AbstractFloat}()
Create an object that constains multiple ConstraintCollection
objects and their corresponding ConstraintCache
.
Upon creation Constraints
is automaticvally populated with two constraint collections, an ExtremeCollection
and a ProgressiveCollection
.
DirectSearch.CollectionTypeCount
— FunctionCollectionTypeCount(c::Constraints{T}, C::AbstractConstraint)::Int where T
Return the total number of constraints of type C
that are stored in all collections.
Missing docstring for DirectSearch.ConstraintUpdate!
. Check Documenter's build log for details.
DirectSearch.ConstraintEvaluation
— FunctionConstraintEvaluation(constraints::Constraints{T}, p::Vector{T})::Tuple{ConstraintOutcome,T} where T
Evaluate point p
over all constraint collections in constraints
. Returns a ConstraintOutcome indicating the result of the evaluation:
Feasible
: p
evaluated as feasible for all constraints (extreme and progressive barrier)
WeakInfeasible
: p
evaluated as feasible for all extreme barrier constraints, and had no progressive barrier constraint violations greater than h_max
StrongInfeasible
: At least one extreme barrier constraint evaluated as infeasible, or at least one progressive barrier constraint had a violation greater than h_max
The second returned value is the sum of h_max values evaluated during the constraint checks.
Missing docstring for DirectSearch.GetHmaxSum
. Check Documenter's build log for details.
Missing docstring for DirectSearch.ConstraintCollectionEvaluation(::DirectSearch.ConstraintCollection{T,DirectSearch.ProgressiveConstraint}, ::Vector{T}) where T
. Check Documenter's build log for details.
Missing docstring for DirectSearch.ConstraintCollectionEvaluation(::DirectSearch.ConstraintCollection{T,DirectSearch.ExtremeConstraint}, ::Vector{T}) where T
. Check Documenter's build log for details.
Mesh
DirectSearch.AbstractMesh
— Typeabstract type AbstractMesh end
Parent type of any struct implementing the construction of a mesh. To maintain compatibility with other aspects of the package, the naming convention for variables within structs must be followed. These respect the notation used within Audet, Le Digabel & Tribes 2019.
DirectSearch.MeshSetup!
— FunctionMeshSetup!(p::DSProblem)
Set up the mesh with the parameters defined for problem.
MeshSetup!(p::DSProblem, m::AnisotropicMesh)
Set up the anisotropic mesh with the parameters defined for problem.
DirectSearch.MeshUpdate!
— FunctionMeshUpdate!(p::DSProblem, result::IterationOutcome)
Update the mesh in p
based on the outcome of the most recent iteration.
MeshUpdate!(mesh::AnisotropicMesh, ::AbstractPoll, result::IterationOutcome, dir::Union{Vector,Nothing})
Implements update rule from Audet, Le Digabel & Tribes 2019 adapted for progressive barrier constraints with Audet & Dennis 2009 expression 2.4.
dir
is the direction of success of the iteration, equal to nothing
, if there is none.
MeshUpdate!(m::IsotropicMesh, ::AbstractPoll, result::IterationOutcome, ::Union{Vector,Nothing})
Implements update rule for the isotropic mesh m
with a generic polling scheme using Audet & Dennis 2006 pg. 23, with slight modifications to handle progressive barrier constrained optimization from Audet & Dennis 2009 expression 2.4.
MeshUpdate!(m::IsotropicMesh, o::OrthoMADS, result::IterationOutcome, ::Union{Vector,Nothing})
Implements the OrthoMads update rules for the Isotropic mesh.
Missing docstring for DirectSearch.SetMeshParameters!
. Check Documenter's build log for details.
Missing docstring for DirectSearch.SetMeshSizeVector!
. Check Documenter's build log for details.
Missing docstring for DirectSearch.SetPollSizeVector!
. Check Documenter's build log for details.
Missing docstring for DirectSearch.SetRatioVector!
. Check Documenter's build log for details.
Missing docstring for DirectSearch.init_a_and_b!
. Check Documenter's build log for details.
DirectSearch.get_poll_size_estimate
— Functionget_poll_size_estimate(x⁰::T, lower_bound::Union{T,Nothing}, upper_bound::Union{T,Nothing})::T where T
Calculates the initial poll size, as given in Audet, Le Digabel & Tribes 2019 expression 3.3, using the initial point and variable bounds, if specified.
Poll
DirectSearch.Poll
— FunctionPoll(p::DSProblem{T})::IterationOutcome where T
Generate points and call evaluate on them.
DirectSearch.GeneratePollPoints
— FunctionGeneratePollPoints(p::DSProblem{T}, ::AbstractMesh)::Vector{Vector{T}} where T
Generate a set of directions with the configured polling algorithm, then return the set of points these directions give from the incumbent points.
DirectSearch.GenerateDirections
— MethodGenerateDirections(p::DSProblem)
Generate a set of directions with the configured polling algorithm.
Missing docstring for DirectSearch.SafePointGeneration
. Check Documenter's build log for details.
DirectSearch.ScaleDirection
— FunctionScaleDirection(p::AnisotropicMesh, dir::Vector{T}) where T
Scale the direction vector dir
using the scaling information in the mesh m
. On Anistropic meshes, this uses the vector ρ
, which is the mesh ratio.
ScaleDirection(m::IsotropicMesh, dir::Vector{T}) where T
Scale the direction vector dir
using the scaling information in the mesh m
. For the isotropic mesh, this operation is a nop because the mesh has no scaling applied.
Search
DirectSearch.Search
— FunctionSearch(p::DSProblem{T})::IterationOutcome where T
Generate search points and call evaluate on them.
DirectSearch.GenerateSearchPoints
— MethodGenerateSearchPoints(p::DSProblem{T})::Vector{Vector{T}} where T
Calls GenerateSearchPoints
for the search step within p
.
DirectSearch.GenerateSearchPoints
— MethodGenerateSearchPoints(p::DSProblem{T}, ::RandomSearch)::Vector{Vector{T}} where T
Finds points that are Δᵐ distance from any point in the mesh in a uniformly random direction.
DirectSearch.GenerateSearchPoints
— MethodGenerateSearchPoints(p::DSProblem, ::NullSearch)
Search method that returns an empty vector.
Use when no search method is desired.
LTMADS
DirectSearch.GenerateDirections
— MethodGenerateDirections(p::AbstractProblem, DG::LTMADS{T})::Matrix{T}
Generates columns and forms a basis matrix for direction generation.
Missing docstring for DirectSearch.form_basis_matrix
. Check Documenter's build log for details.
Missing docstring for DirectSearch.LT_basis_generation
. Check Documenter's build log for details.
Missing docstring for DirectSearch.B′_generation
. Check Documenter's build log for details.
Missing docstring for DirectSearch.b_l_generation
. Check Documenter's build log for details.
Missing docstring for DirectSearch.L_generation
. Check Documenter's build log for details.
Missing docstring for DirectSearch.B_generation
. Check Documenter's build log for details.
OrthoMADS
DirectSearch.GenerateDirections
— MethodGenerateDirections(p::DSProblem{T}, DG::LTMADS{T})::Vector{Vector{T}}
Generates columns and forms a basis matrix for direction generation.
Missing docstring for DirectSearch.GenerateDirectionsOnUnitSphere
. Check Documenter's build log for details.
Missing docstring for DirectSearch.HouseholderTransform
. Check Documenter's build log for details.
Cache
DirectSearch.AbstractCache
— Typeabstract type AbstractCache end
Parent type of any struct implementing the cache.
DirectSearch.PointCache
— TypePointCache{T} <: AbstractCache
An abstract cache subtype that contains a dictionary of points/costs and a vector that stores the order of incumbent points.
DirectSearch.CachePush
— MethodCachePush(p::AbstractProblem, x::Vector, cost)
Add point x
and its cost cost
to the cache of p
.
DirectSearch.CachePush
— MethodCachePush(p::AbstractProblem)
Add the feasible and infeasible incumbent points (assuming neither are nothing
) to the cache.
DirectSearch.CacheQuery
— MethodCacheQuery(p::AbstractProblem, x::Vector)
Query the cache of p
to find if it has a cost value for point x
. Alias to haskey
.
DirectSearch.CacheGet
— MethodCacheGet(p::AbstractProblem, x::Vector)
Return the cost of point x
in the cache of p
. Does not check if x
is in the cache, use CacheQuery
to check.
DirectSearch.CacheRandomSample
— MethodCacheRandomSample(p::AbstractProblem, n::Int)
Returns a uniformly sampled collection of n
points from the cache. Points can be repeated in the sample.
DirectSearch.CacheInitialPoint
— MethodCacheInitialPoint(p::AbstractProblem)
Return a tuple of the initial point added to the cache and its cost.
DirectSearch.CacheGetRange
— MethodCacheGetRange(p::AbstractProblem, points::Vector)::Vector{Vector}
Return a vector of costs corresponding to the vector of points.
DirectSearch.CacheFilter
— MethodCacheFilter(p::AbstractProblem{T}, points::Vector{T})::Tuple{Vector{Vector{T}},Vector{Vector{T}}} where T
Return a tuple where the first entry is the set of input points in the cache and the second is the set of input points not in the cache.