API Clients

The SOLVER-AI API provides a set of client classes to facilitate the integration of Python, JavaScript, and C++ with the API. It also provides examples to help you understand how the API works. This document provides a detailed guide on how to use the API.

Note: Browsable API and code are interchangable and can be used together for differnet portions of setup and execution of a Problem.

The clients with its examples can be downloaded from https://github.com/SOLVER-AI-LTD/client.

As first thing, edit the setup/setup.txt file and replace REPLACEWITHSOLVERAITOKENHERE with your token (which you can obtained from Account).

The client folder contains the following sub-folders:

• setup: Contains the setup.txt file.
• cpp: C++ client classes and example files.
• python: Python client classes and example files.
• js: JavaScript client classes and example files.
• example_files: Data files used in the examples.

setup Folder

This folder contains the setup.txt file.

cpp, python and js Folders

The cpp, python and js folders contain the client classes:

• SolverAiClientSetup.*
• SolverAiClientCompute.*
• SolverAiComputeInput.*
• SolverAiComputeResults.*
• SolverAiResultsWriter.*

the examples files which contain the code for the examples presented in this documentation:

• example_*

the helper code for deleting for cleaning the data on your account:

• delete_everything.*

example_files Folder

This folder contains the data used by the examples.

delete_everything code (USE WITH CAUTION)

The delete_everything code allows deleting all of the Problem and modules.

This code can be used as a starting point for deletin batches of Problems and modules making use of regular expressions based on Problem and module names. It leverages the following member functions of the SolverAiClientSetup class (see below):

• deleteProblems
• deleteEquations
• deleteCodes
• deleteHardDatas
• deleteSoftDatas

C++

The cpp folder contains a Makefile for compileing all of the code with GCC. Compile from within the folder with command

make -f Makefile

SolverAiClientSetup

This class is used to set up the modules (Equation, Code, HardData and SoftData) and then set up a Problem for those modules. It also allows deletion of the modules and Problem as well as a complete cleanup after the solver has run. The class contains the following methods:

• postEquation: This method is used to post an Equation module.
• patchEquation: This method is used to patch Equation module.
• deleteEquation: This method is used to delete an Equation module.
• deleteEquations: This method is used to delete any number of Equation modules, it takes a regular expression string as input, which has default value “.*”.

• postCode: This method is used to post a Code module.
• patchCode: This method is used to patch a Code module.
• deleteCode: This method is used to delete a Code module.
• deleteCodes: This method is used to delete any number of Code modules, it takes a regular expression string as input, which has default value “.*”.

• postHardData: This method is used to post a HardData module.
• patchHardData: This method is used to patch a HardData module.
• deleteHardData: This method is used to delete a HardData module.
• deleteHardDatas: This method is used to delete any number of HardData modules, it takes a regular expression string as input, which has default value “.*”.

• postSoftData: This method is used to post a SoftData module.
• patchSoftData: This method is used to patch a SoftData module.
• deleteSoftData: This method is used to delete a SoftData module.
• deleteSoftDatas: This method is used to delete any number of SoftData modules, it takes a regular expression string as input, which has default value “.*”.

• postProblem: This method is used to post a Problem.
• patchProblem: This method is used to patch a Problem.
• deleteProblem: This method is used to delete a Problem.
• deleteProblems: This method is used to delete any number of Problem, it takes a regular expression string as input, which has default value “.*”.
• deleteAll: This method is used to delete a Problem and the listed modules, it takes as input the ID of the problem module and arrays/vectors/lists of the Equation, Code, HardData, SoftData modules.

IMPORTANT: Remember that modules which have been associated with an existing Problem will not be allowed to be deleted, returning an error for those which have not been deleted.

SolverAiClientCompute

This class is used to run the solver for the problem set up by the SolverAiClientSetup class. It contains the following methods:

• getProblemSetup: This method is used to get the setup of the problem from the API, which consists in the inputs and outputs, which is a list / array / vector (depending on the programming language) of names of the variables required for setting up the problem.
• runSolver: This method is used to run the solver on the API. It takes a SolverAiComputeInput as input.

SolverAiComputeInput

This class is used to define the input for the solver, input to function runSolver of an object of class SolverAiClientCompute . It contains the following methods:

• setSolverSetup: This method is used for setting up parameters:
  • includeLeastInfeasible: (see Include Least Infeasible Solutions in Solver)
  • solutionQuality: (see Solution Quality in Solver)
• addInput: This method is used to add an input to the problem. Use this function to setup each of the inputs.
• addConstraint: This method is used to add a constraint to the problem. Use this function to setup any of the outputs as constraint, choosing among the available CONSTRAINT options.
• addObjective: This method is used to add a constraint to the problem. Use this function to setup any of the outputs as constraint, choosing among the available OBJECTIVE options.

SolverAiComputeResults

This class is used to handle the results from the solver. It contains the following methods:

• getNumberOfResults: This method is used to get the number of results.
• getObjectiveVariableNames: This method is used to get the names of the objective variables.
• getConstraintVariableNames: This method is used to get the names of the constraint variables.
• getInputVariableNames: This method is used to get the names of the input variables.
• getOutputVariableNames: This method is used to get the names of the output variables.
• getX: This method is used to get the X values of the results.
• getY: This method is used to get the Y values of the results.

SolverAiResultsWriter

This class is used for writing the results (SolverAiComputeResults) to a csv file. It contains the following methods:

• write: This method is used to write the results to a csv file at a specified path.

The examples in the python, js, and cpp folders demonstrate how to use the Client classes. They all perform the same actions, but in different languages. The examples have beed defined so to make them as clear as possible. The examples and data are intentionally extremely simple to help you understand how the SOLVER-AI API works.

Note that although the examples create, execute and delete the problem, this is not required or expected. The modules and Problem could be created via the Browsabel API and the Problem ID simply used in code. Or different codes could perform different operations depending on the work to be performed.

Here are brief descriptions of the examples:

• example_equation_patch: This example shows you how to set up a Problem with a single Equation:
  1. An Equationmodule is created and a Problem is created.
  2. The inputs and outputs are retrieved and checked.
  3. The input for running the solver is prepared.
  4. The solver is run and the results are retrieved and checked.
  5. The Equation module is modified.
  6. The new inputs and outputs are retrieved and checked.
• example_code_patch: This example is the same as the example_equation_patch but, for the Code module.
• example_hard_data_patch: This example shows you how to set up a Problem with a single HardData:
  1. An HardDatamodule is created and a Problem is created.
  2. The inputs and outputs are retrieved and checked.
  3. The input for running the solver is prepared.
  4. The solver is run and the results are retrieved and checked.
  5. The equation module is modified.
  6. The solver is run and the results are retrieved and checked.
• example_soft_data_patch: This example is the same as the example_hard_data_patch, but for the SoftData module.
• example_hard_data_multiple: This example shows you how to set up a Problem with multiple HardData tables which have columns with same headers.
  1. Multiple HardDatamodules are created and a Problem is created.
  2. The inputs and outputs are retrieved and checked.
  3. The input for running the solver is prepared.
  4. The solver is run and the results are retrieved and checked.
• example_getting_started: This problem coincides with the example given in the Getting Started with SOLVER-AI, more details can be found in Programmatic API Example.

The solver is run as:

results = solverAiClientCompute.runSolver(input)

where input is of type SolverAiComputeInput and results is of type SolverAiComputeResults.

As the solver is capable of obtaining one or more solutions (depending on the problem) the data type returned by functions getX and getY of the SolverAiComputeResults will be different depending on the implementation:

• C++:
  

  std::vector<std::vector<std::variant<std::<float, std::string>>>>

• Python:
  

  list(list())

• JavaScript:
  

  Array(Array())

An object results of type SolverAiComputeResults is such that assuming, getX or getY returned objects X and Y, respectively:

• X and Y would have as many elements as results.getNumberOfResults().
• For X:
  • X[i] will be relative to result i.
  • X[i][j] will contain the value relative to the input variable named inputVariable[j], where:
    

    inputVariable = results.getInputVariableNames()

• For Y:
  • Y[i] will be relative to result i.
  • Y[i][k] will contain the value relative to the output variable named outputVariable[k], where:
    

    outputVariable = results.getOutputVariableNames()