Solver SDK Platform - Object-Oriented Calls, Callbacks, and Error Handling

Today, most software development is done in modern languages such as C++ or C#, Visual Basic or VB.NET, Java, and MATLAB.  Each of these languages supports features such as object-oriented programming, properties, events, and exceptions -- all of which contribute to faster development and fewer errors.

Calling the SDK via Properties and Methods

Although you can call a series of API functions using the Solver SDK Platform's Procedural API, it's much easier to implicitly call upon the SDK's capabilities by simply defining your model, using the objects and properties provided by the SDK.  For example:

Problem problem = new Problem(Solver_Type.Minimize, nvars, ncons);

creates a new problem, and implicitly creates one block of decision variables, one block of constraints, and one objective function.  Simply assigning the UpperBound property of the constraint object:

problem.FcnConstraint.UpperBound.Array = rhs;

defines a set of <= constraints.  You can also define constraints with explicit relations and right hand sides, or define lower bounds of zero with a statement such as problem.VarDecision.NonNegative().  To define a quadratic objective, you can write:

problem.Model.FcnQuadratic[Function_Type.Objective, 0] =
   new DoubleMatrix(Array_Order.ByCol, nvars, nvars, qmatval);

to create a DoubleMatrix (an object supplied by the SDK) from a plain array, and assign it to the appropriate property of the Model object.Moreover, IntelliSense in Microsoft Visual Studio shows you dynamically -- as you type -- what objects and properties are available at each point.  The result is faster development with fewer errors!

Callbacks from the SDK via Events and Delegates

Where other optimization libraries use low-level, error-prone "callback functions" to pass control to your code during the solution process, the Solver SDK Platform supports the "natural", high-level notification mechanisms in each language, such as events, delegates, and interfaces in object-oriented languages.  Of course, in procedural languages such as C, you can still use callback functions with the SDK via its Procedural API.

For example, you might define an Evaluator that should be called on each new iteration, or trial solution, found during the optimization process.  In C# and .NET, which supports events as a high-level notification mechanism, you can pass a reference to your Evaluator via:

problem.Evaluators[Eval_Type.Iteration].OnEvaluate +=
   new EvaluateEventHandler(MyEvaluator);

In Visual Basic 6, which supports a slightly different style of events using Microsoft COM, you would write a function EvalIteration_Evaluate() and pass a reference to your Evaluator via:

Set EvalIteration = New SolverPlatform.Evaluator
prob.Evaluators.Item(Eval_Type_Iteration) = EvalIteration

In both cases, your code will be called, in a type-safe manner, on each Solver engine iteration.  In your Evaluator, you can reference the SDK object model to access, for example, the current iteration and value of the objective..  In C# syntax:

private Engine_Action EvalIteration_Evaluate (Evaluator evaluator)
{
   m_Log.Dump("Iteration = " + evaluator.Problem.Engine.Stat.Iterations +
      ", Objective = " + evaluator.Problem.FcnObjective.Value[0]);
}

Error Handling in the SDK via Exceptions

Other "callable library" packages for optimization provide only a procedural API, where you must write code to check the result returned by each API call for possible errors.  This makes code harder to write, harder to read, and invites "skipping the checks" which can lead to hard-to-diagnose problems later.

In contrast, the Solver SDK Platform's object-oriented API uses the exception handling mechanism built-in to most modern programming languages, reporting all errors by raising a SolverException.  This allows you to write code such as (in C# syntax):

try
{
   Problem problem = new Problem(Solver_Type.Minimize, nvars, ncons);
   problem.FcnConstraint.UpperBound.Array = rhs;
   problem.Model.FcnQuadratic[Function_Type.Objective, 0] =
      new DoubleMatrix(Array_Order.ByCol, nvars, nvars, qmatval);
}
catch (SolverException ex)
{
   m_Log.Dump("Exception " + ex.ExceptionType);
   m_Log.Dump("Exception " + ex.Message);
}

thereby centralizing your error checking, keeping your mainline code readable, and -- most important -- ensuring that no error condition is ever ignored.

< Back to Solver SDK Platform Product Overview