Reference · 2.0 development

C++ API

These declarations are extracted from the selected public-facing headers. Some declarations still need explanatory API comments; see the guides for usage.

Solver

class Solver

Public Functions

Solver()

Solver(std::shared_ptr<spdlog::sinks::sink> consoleSink)

Solver(EnvironmentPtr environment)

~Solver()

EnvironmentPtr getEnvironment()

bool setOptionsFromFile(std::string fileName)

bool setOptionsFromString(std::string options)

bool setOptionsFromOSoL(std::string options)

std::string getSettingsAsMarkup()

bool setLogFile(std::string filename)

void updateLogLevels()

bool setProblem(std::string fileName)

bool setProblem(ProblemPtr problem, ProblemPtr reformulatedProblem, ModelingSystemPtr modelingSystem = nullptr)

inline bool setProblem(ProblemPtr problem, ModelingSystemPtr modelingSystem = nullptr)

inline ProblemPtr getOriginalProblem()

inline ProblemPtr getReformulatedProblem()

bool solveProblem()

void outputSolverHeader()

void outputOptionsReport()

void outputProblemInstanceReport()

void outputSolutionReport()

int registerCallback(E_CallbackLocation locations, CallbackFunction callback)

Registers a callback for one or several locations in the solution process.

The callback is given a context with the state of the solver and the actions that are available at the location. The context is of the class for the location, which CallbackContext::as<T>() returns:

solver.registerCallback(E_CallbackLocation::PrimalCandidateCheck | E_CallbackLocation::TerminationCheck, [](CallbackContext& context) { auto candidate = context.as<PrimalCandidateCheckContext>();

if(candidate != nullptr && reject(candidate->getPoint())) candidate->rejectCandidate();

if(context.getElapsedTime() > 60) context.terminate(); });

Callbacks can be registered before or after setProblem(), but not while solveProblem() runs. If a callback throws, SHOT terminates and solveProblem() rethrows the exception. See docs/Callbacks.md for the locations.

Parameters:

• locations – The locations to call the callback at, combined with operator|

• callback – The callback

Returns:

A handle for removeCallback()

template<typename T>
inline int registerCallback(std::function<void(T&)> callback)

Registers a callback for the location of a context class, e.g., PrimalCandidateCheckContext.

solver.registerCallback<TerminationCheckContext>([](TerminationCheckContext& context) { context.terminate(); });

bool removeCallback(int handle)

Removes a registered callback; returns false if there is no callback with the handle.

std::string getOptionsOSoL()

std::string getOptions()

std::string getResultsOSrL()

std::string getResultsTrace()

std::string getResultsSol()

inline void updateSetting(std::string settingName, int value)

inline void updateSetting(std::string settingName, std::string value)

inline void updateSetting(std::string settingName, double value)

inline void updateSetting(std::string settingName, bool value)

inline void updateSetting(std::string settingName, int value, E_SettingPriority priority)

inline void updateSetting(std::string settingName, std::string value, E_SettingPriority priority)

inline void updateSetting(std::string settingName, double value, E_SettingPriority priority)

inline void updateSetting(std::string settingName, bool value, E_SettingPriority priority)

template<typename T>
inline T getSetting(std::string settingName)

inline E_SettingPriority getSettingPriority(std::string settingName)

VectorString getSettingIdentifiers(E_SettingType type)

double getCurrentDualBound()

double getGlobalDualBound()

double getPrimalBound()

double getAbsoluteObjectiveGap()

double getRelativeObjectiveGap()

bool hasPrimalSolution()

PrimalSolution getPrimalSolution()

std::vector<PrimalSolution> getPrimalSolutions()

inline SolutionStatistics getSolutionStatistics()

E_TerminationReason getTerminationReason()

E_ModelReturnStatus getModelReturnStatus()

Public Static Functions

static std::vector<ES_ModelingSystem> getSupportedModelingSystems()

static std::vector<ES_MIPSolver> getSupportedMIPSolvers()

static std::vector<ES_PrimalNLPSolver> getSupportedNLPSolvers()

static bool hasModelingSystem(ES_ModelingSystem format)

static bool hasMIPSolver(ES_MIPSolver solver)

static bool hasNLPSolver(ES_PrimalNLPSolver solver)

Settings

class Settings

Public Functions

Settings(OutputPtr outputPtr)

~Settings()

template<typename T>
void updateSetting(std::string name, std::string category, T value, E_SettingPriority priority = E_SettingPriority::SolverInternal)

template<typename T>
inline void updateSetting(std::string settingName, T value, E_SettingPriority priority = E_SettingPriority::SolverInternal)

template<typename T>
inline T getSetting(std::string name, std::string category)

template<typename T>
inline T getSetting(std::string settingName)

inline std::string getSettingDescription(std::string name, std::string category)

inline std::string getSettingDescription(std::string settingName)

inline PairDouble getSettingBounds(std::string name, std::string category)

inline PairDouble getSettingBounds(std::string settingName)

void createSetting(std::string settingName, std::string value, std::string description, bool isPrivate = false)

void createSetting(std::string settingName, int value, std::string description, double minVal = 0, double maxVal = SHOT_INT_MAX, bool isPrivate = false)

void createSetting(std::string settingName, double value, std::string description, double minVal = SHOT_DBL_MIN, double maxVal = SHOT_DBL_MAX, bool isPrivate = false)

void createSetting(std::string settingName, int value, std::string description, VectorString enumDesc, int startValue = 0, bool isPrivate = false)

void createSetting(std::string settingName, bool value, std::string description, bool isPrivate = false)

inline void createSettingGroup(std::string mainLevel, std::string subLevel, std::string header, std::string description)

inline PairString getCategoryDescription(std::string category)

std::string getEnumDescriptionList(std::string name, std::string category)

std::string getEnumDescriptionListMarkup(std::string name, std::string category)

std::vector<std::pair<int, std::string>> getEnumDescription(std::string name, std::string category)

std::string getSettingsAsOSoL()

std::string getSettingsAsString(bool showUnchanged, bool showDescriptions)

std::string getSettingsAsMarkup()

VectorString getChangedSettings()

VectorString getSettingIdentifiers(E_SettingType type)

VectorPairString getSettingSplitIdentifiers(E_SettingType type)

E_SettingPriority getSettingPriority(std::string name, std::string category)

inline E_SettingPriority getSettingPriority(std::string settingName)

bool isSettingAtDefault(std::string name, std::string category)

inline bool isSettingAtDefault(std::string settingName)

VectorString getSettingsAtPriority(E_SettingPriority priority)

bool hasSettingAtPriority(std::string name, std::string category, E_SettingPriority priority)

inline bool hasSettingAtPriority(std::string settingName, E_SettingPriority priority)

std::vector<E_SettingPriority> getSettingPriorityHistory(std::string name, std::string category)

inline std::vector<E_SettingPriority> getSettingPriorityHistory(std::string settingName)

template<typename T>
inline T getSettingAtPriority(std::string name, std::string category, E_SettingPriority priority)

template<typename T>
inline T getSettingAtPriority(std::string settingName, E_SettingPriority priority)

bool readSettingsFromOSoL(std::string osol)

bool readSettingsFromString(std::string options)

Public Members

bool settingsInitialized = false

Results

class Results

Public Functions

Results(EnvironmentPtr envPtr)

~Results()

void addPrimalSolution(PrimalSolution solution)

double getPrimalBound()

void setPrimalBound(double value, bool resetStagnationCounters = true)

void addDualSolution(DualSolution solution)

double getCurrentDualBound()

double getGlobalDualBound()

void setDualBound(double value, bool forceGlobal = false)

bool isPrimalSolutionAtArtificialBound()

bool isRelativeObjectiveGapToleranceMet()

bool isAbsoluteObjectiveGapToleranceMet()

double getAbsoluteGlobalObjectiveGap()

double getRelativeGlobalObjectiveGap()

double getAbsoluteCurrentObjectiveGap()

double getRelativeCurrentObjectiveGap()

void createIteration()

IterationPtr getCurrentIteration()

IterationPtr getPreviousIteration()

std::optional<IterationPtr> getLastFeasibleIteration()

int getNumberOfIterations()

E_ModelReturnStatus getModelReturnStatus()

bool hasPrimalSolution()

std::string getResultsOSrL()

std::string getResultsTrace()

std::string getResultsSol()

void savePrimalSolutionToFile(const PrimalSolution &solution, const VectorString &variables, const std::string &fileName)

void savePrimalSolutionToFile(const PrimalSolution &solution, const Variables &variables, const std::string &fileName)

void increaseAuxiliaryVariableCounter(E_AuxiliaryVariableType type)

int getAuxiliaryVariableCounter(E_AuxiliaryVariableType type)

Public Members

VectorDouble primalSolution

std::vector<PrimalSolution> primalSolutions

std::map<E_PrimalSolutionSource, int> primalSolutionSourceStatistics

std::map<E_AuxiliaryVariableType, int> auxiliaryVariablesIntroduced

std::vector<DualSolution> dualSolutions

double currentDualBound = NAN

double currentPrimalBound = NAN

double globalDualBound = NAN

std::vector<IterationPtr> iterations

E_TerminationReason terminationReason = E_TerminationReason::NotTerminated

std::string terminationReasonDescription

E_SolutionStrategy usedSolutionStrategy = E_SolutionStrategy::None

ES_MIPSolver usedMIPSolver = ES_MIPSolver::NotUsed

ES_PrimalNLPSolver usedPrimalNLPSolver = ES_PrimalNLPSolver::NotUsed

std::string usedPrimalNLPSolverDescription = ""

bool solutionIsGlobal = true

Callbacks

namespace SHOT

The Supporting Hyperplane Optimization Toolkit (SHOT).

Author

Andreas Lundell, Åbo Akademi University

LICENSE

This software is licensed under the Eclipse Public License 2.0. Please see the README and LICENSE files for more information.

Typedefs

using CallbackFunction = std::function<void(CallbackContext&)>

Enums

enum class E_CallbackLocation : std::uint64_t

The locations in the solution process where SHOT calls the registered callbacks.

The values are bit flags, so one callback can be registered for several locations by combining them with operator|. The callback is given a context of the class for the location, e.g., a PrimalCandidateCheckContext for PrimalCandidateCheck, and can use CallbackContext::as<T>() to get it. See docs/Callbacks.md for where each location is reached in the solution strategies.

Values:

enumerator None

enumerator InteriorPointSearch

After the interior point search for the ESH dual strategy.

enumerator DualBoundUpdate

When SHOT can accept a dual bound from the user.

enumerator PrimalCandidateSearch

When SHOT collects primal solution candidates.

enumerator PrimalCandidateCheck

Before a primal solution candidate is checked.

enumerator NewPrimalSolution

After a primal solution has been stored.

enumerator TerminationCheck

When SHOT checks whether to terminate.

enumerator HyperplaneSelection

When SHOT selects the hyperplanes to add to the dual problem.

Functions

constexpr E_CallbackLocation operator|(E_CallbackLocation first, E_CallbackLocation second)

constexpr E_CallbackLocation operator&(E_CallbackLocation first, E_CallbackLocation second)

constexpr bool hasCallbackLocation(E_CallbackLocation mask, E_CallbackLocation location)

Whether the location is one of the locations in the mask.

std::string getCallbackLocationName(E_CallbackLocation location)

The name of a single location, as used in messages and in the Python interface.

Variables

constexpr E_CallbackLocation AllCallbackLocations = static_cast<E_CallbackLocation>((1ull << 7) - 1)

All the locations, for registering a callback that is called everywhere.

class CallbackContext : public std::enable_shared_from_this<CallbackContext>

#include <Callback.h>

The information and actions available to a callback.

The context is only valid while the callback it is given to runs. It holds a snapshot of the state of the solver, taken when SHOT reaches the location, so all callbacks called at the same location see the same values, and none of them sees the actions of another. The actions are applied by SHOT after all the callbacks have returned.

Values that are not available are reported as infinite: the dual bound before the first dual problem has been solved, the primal bound before a primal solution has been found, and the gaps while either bound is missing.

The problems returned by getOriginalProblem() and getReformulatedProblem() can be used to evaluate functions, but must not be modified.

SHOT creates the contexts with std::make_shared, so that a context kept by the Python interface after the callback has returned is still an object, whose methods throw CallbackContextExpired.

Subclassed by SHOT::DualBoundUpdateContext, SHOT::HyperplaneSelectionContext, SHOT::InteriorPointSearchContext, SHOT::NewPrimalSolutionContext, SHOT::PrimalCandidateCheckContext, SHOT::PrimalCandidateSearchContext, SHOT::TerminationCheckContext

Public Functions

virtual ~CallbackContext() = default

CallbackContext(const CallbackContext&) = delete

CallbackContext &operator=(const CallbackContext&) = delete

inline E_CallbackLocation getLocation() const

The location the callback is called at; can also be used after the context has expired.

inline bool isValid() const

Whether the context can still be used, i.e., the callback it was given to has not returned.

bool isMinimization() const

int getIterationNumber() const

The number of the current iteration, or 0 before the first iteration.

double getElapsedTime() const

The time since SHOT was started, in seconds.

double getDualBound() const

The current dual bound, which is the one the termination criteria use.

double getGlobalDualBound() const

The dual bound that is valid for the whole problem.

double getPrimalBound() const

double getRelativeGap() const

The relative gap between the current dual bound and the primal bound.

double getAbsoluteGap() const

The absolute gap between the current dual bound and the primal bound.

SolutionStatistics getSolutionStatistics() const

A copy of the statistics of the solution process.

ProblemPtr getOriginalProblem() const

ProblemPtr getReformulatedProblem() const

bool hasPrimalSolution() const

VectorDouble getPrimalSolution() const

The best primal solution, in the variables of the original problem; throws if there is none.

void terminate()

Requests SHOT to terminate at its next termination check; available at every location.

bool isTerminationRequested() const

Whether terminate() has been called in this context, by this or an earlier callback at the same location.

bool isTerminationPending() const

Whether termination was requested before SHOT reached the location, e.g., by a callback at another location, so that SHOT is stopping. Stays true while the solution is finalized

bool isFinalizing() const

Whether SHOT is finalizing the solution, for any termination reason.

template<typename T>
inline T *as()

The context as the class of a location, or nullptr if the callback is called at another location.

template<typename T>
inline const T *as() const

void invalidate()

Called by SHOT when the callbacks have returned; the context cannot be used after this.

virtual void discardActions()

Called by SHOT when a callback has failed, so that no action of the callbacks is applied.

Protected Functions

CallbackContext(EnvironmentPtr envPtr, E_CallbackLocation location)

void checkValid() const

Throws CallbackContextExpired if the callback has returned.

inline virtual void releaseData()

Releases the data held by a derived class when the context is invalidated.

void validatePoint(const VectorDouble &point, bool allowOriginal, bool allowReformulated, const std::string &description) const

Throws std::invalid_argument if the point is neither in the variables of the original problem nor in those of the reformulated problem (as allowed), or if a value is not finite

Private Members

E_CallbackLocation location

bool valid = true

bool terminationRequested = false

EnvironmentPtr env

ProblemPtr originalProblem

ProblemPtr reformulatedProblem

bool minimization = true

int iterationNumber = 0

double elapsedTime = 0.0

double dualBound

double globalDualBound

double primalBound

double relativeGap

double absoluteGap

bool primalSolutionAvailable = false

bool terminationPending = false

bool finalizing = false

SolutionStatistics solutionStatistics

class CallbackContextExpired : public std::logic_error

#include <Callback.h>

Thrown when a callback context is used after the callback it was given to has returned.

class CallbackHandler

#include <Callback.h>

Calls the callbacks registered for a location.

The callbacks are called one at a time, also when SHOT reaches a location from several threads, and in the order they were registered. If a callback throws, the remaining callbacks are not called, the actions of all callbacks at that location are discarded, no callback is called again, and SHOT terminates. The exception is rethrown from Solver::solveProblem().

Public Functions

CallbackHandler(EnvironmentPtr envPtr)

int add(E_CallbackLocation locations, CallbackFunction callback)

Registers a callback for the locations in the mask; returns a handle for remove()

bool remove(int handle)

Removes a callback; returns false if there is no callback with the handle.

inline bool isActive(E_CallbackLocation location) const

Whether a callback is registered for the location, and callbacks have not been disabled by a failure.

void invoke(CallbackContext &context)

Calls the callbacks registered for the location of the context. A requested termination is passed on to the task handler, the other actions are applied by the caller

inline bool hasFailed() const

inline std::string getFailureMessage() const

The message of the exception of a failed callback.

void rethrowFailure()

Rethrows the exception of a failed callback, if there is one, and forgets it.

Private Functions

void updateActiveLocations()

Private Members

std::vector<RegisteredCallback> callbacks

std::atomic<std::uint64_t> activeLocations = {0}

int nextHandle = 1

std::mutex invokeMutex

std::atomic<bool> failed = {false}

std::exception_ptr failure

std::string failureMessage

EnvironmentPtr env

struct RegisteredCallback

Public Members

int handle

E_CallbackLocation locations

CallbackFunction function

class DualBoundUpdateContext : public SHOT::CallbackContext

#include <Callback.h>

Called when SHOT can accept a dual bound from the user.

Public Functions

DualBoundUpdateContext(EnvironmentPtr envPtr)

void setDualBound(double value)

Proposes a dual bound; SHOT uses it if it is better than the current dual bound. If several are proposed, the tightest one is used

std::optional<double> getProposedDualBound() const

virtual void discardActions() override

Called by SHOT when a callback has failed, so that no action of the callbacks is applied.

Public Static Attributes

static constexpr E_CallbackLocation Location = E_CallbackLocation::DualBoundUpdate

Private Members

std::optional<double> proposedDualBound

class HyperplaneSelectionContext : public SHOT::CallbackContext

#include <Callback.h>

Called when SHOT selects the hyperplanes to add to the dual problem; hyperplanes can be added.

Public Functions

HyperplaneSelectionContext(EnvironmentPtr envPtr, std::vector<SolutionPoint> points)

const std::vector<SolutionPoint> &getSolutionPoints() const

The solution points of the dual problem, in the variables of the reformulated problem.

void addHyperplane(const ExternalHyperplane &hyperplane)

Adds a hyperplane in the variables of the reformulated problem; can be called several times.

const std::vector<ExternalHyperplane> &getAddedHyperplanes() const

virtual void discardActions() override

Called by SHOT when a callback has failed, so that no action of the callbacks is applied.

Public Static Attributes

static constexpr E_CallbackLocation Location = E_CallbackLocation::HyperplaneSelection

Protected Functions

virtual void releaseData() override

Releases the data held by a derived class when the context is invalidated.

Private Members

std::vector<SolutionPoint> solutionPoints

std::vector<ExternalHyperplane> addedHyperplanes

DualSolverPtr dualSolver

class InteriorPointSearchContext : public SHOT::CallbackContext

#include <Callback.h>

Called after the interior point search for the ESH dual strategy; the interior points can be replaced.

Public Functions

InteriorPointSearchContext(EnvironmentPtr envPtr, std::vector<VectorDouble> points)

const std::vector<VectorDouble> &getInteriorPoints() const

The interior points SHOT has found, in the variables of the reformulated problem; can be empty.

void setInteriorPoints(const std::vector<VectorDouble> &points)

Replaces the interior points. The points can be in the variables of either the original or the reformulated problem, and there must be at least one. If called several times, the last call is used

const std::optional<std::vector<VectorDouble>> &getReplacementInteriorPoints() const

The replacement points, or nullopt if the current points are kept.

virtual void discardActions() override

Called by SHOT when a callback has failed, so that no action of the callbacks is applied.

Public Static Attributes

static constexpr E_CallbackLocation Location = E_CallbackLocation::InteriorPointSearch

Protected Functions

virtual void releaseData() override

Releases the data held by a derived class when the context is invalidated.

Private Members

std::vector<VectorDouble> interiorPoints

std::optional<std::vector<VectorDouble>> replacementInteriorPoints

class NewPrimalSolutionContext : public SHOT::CallbackContext

#include <Callback.h>

Called when a primal solution has been stored; no actions except terminate()

Public Functions

NewPrimalSolutionContext(EnvironmentPtr envPtr, VectorDouble solutionPoint, double solutionObjective, E_PrimalSolutionSource source, bool isIncumbentSolution)

const VectorDouble &getPoint() const

The solution, in the variables of the original problem.

double getObjectiveValue() const

E_PrimalSolutionSource getSource() const

bool isIncumbent() const

Whether the solution is better than the best one SHOT had before it.

Public Static Attributes

static constexpr E_CallbackLocation Location = E_CallbackLocation::NewPrimalSolution

Protected Functions

virtual void releaseData() override

Releases the data held by a derived class when the context is invalidated.

Private Members

VectorDouble point

double objectiveValue

E_PrimalSolutionSource sourceType

bool incumbent

class PrimalCandidateCheckContext : public SHOT::CallbackContext

#include <Callback.h>

Called for each primal solution candidate before SHOT checks it; the candidate can be rejected.

Public Functions

PrimalCandidateCheckContext(EnvironmentPtr envPtr, VectorDouble candidatePoint, double candidateObjective, E_PrimalSolutionSource source)

const VectorDouble &getPoint() const

The candidate, in the variables of the original problem.

double getObjectiveValue() const

E_PrimalSolutionSource getSource() const

void rejectCandidate()

SHOT will not check the candidate, so it cannot become a primal solution.

bool isCandidateRejected() const

virtual void discardActions() override

Called by SHOT when a callback has failed, so that no action of the callbacks is applied.

Public Static Attributes

static constexpr E_CallbackLocation Location = E_CallbackLocation::PrimalCandidateCheck

Protected Functions

virtual void releaseData() override

Releases the data held by a derived class when the context is invalidated.

Private Members

VectorDouble point

double objectiveValue

E_PrimalSolutionSource sourceType

bool rejected = false

class PrimalCandidateSearchContext : public SHOT::CallbackContext

#include <Callback.h>

Called when SHOT collects primal solution candidates; candidates can be added.

Public Functions

PrimalCandidateSearchContext(EnvironmentPtr envPtr)

void addPrimalSolution(const VectorDouble &point)

Adds a candidate, in the variables of either the original or the reformulated problem; can be called several times

const std::vector<VectorDouble> &getAddedPrimalSolutions() const

virtual void discardActions() override

Called by SHOT when a callback has failed, so that no action of the callbacks is applied.

Public Static Attributes

static constexpr E_CallbackLocation Location = E_CallbackLocation::PrimalCandidateSearch

Protected Functions

virtual void releaseData() override

Releases the data held by a derived class when the context is invalidated.

Private Members

std::vector<VectorDouble> addedPrimalSolutions

class TerminationCheckContext : public SHOT::CallbackContext

#include <Callback.h>

Called when SHOT checks whether to terminate; no actions except terminate()

Public Functions

TerminationCheckContext(EnvironmentPtr envPtr)

Public Static Attributes

static constexpr E_CallbackLocation Location = E_CallbackLocation::TerminationCheck