====== 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//.

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

----
===== setup.txt (IMPORTANT) =====

As first thing, edit the //setup/setup.txt// file and replace //REPLACEWITHSOLVERAITOKENHERE// with your token (which you can obtained from [[https://www.solver-ai.com/accountmanagement|Account]]).

----
===== Folder Structure =====
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 //Problem//s 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
<code>
make -f Makefile
</code>

----
===== Classes =====

__**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 [[api_reference:solver|Solver]])
    * ''solutionQuality'': (see **Solution Quality** in [[api_reference:solver|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.

----
===== Examples =====

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//:
    - An //Equation//module is created and a //Problem// is created.
    - The ''inputs'' and ''outputs'' are retrieved and checked.
    - The ''input'' for running the solver is prepared.
    - The solver is run and the results are retrieved and checked.
    - The //Equation// module is modified.
    - 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//:
    - An //HardData//module is created and a //Problem// is created.
    - The ''inputs'' and ''outputs'' are retrieved and checked.
    - The ''input'' for running the solver is prepared.
    - The solver is run and the results are retrieved and checked.
    - The equation module is modified.
    - 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.
    - Multiple //HardData//modules are created and a //Problem// is created.
    - The ''inputs'' and ''outputs'' are retrieved and checked.
    - The ''input'' for running the solver is prepared.
    - 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|Getting Started with SOLVER-AI]], more details can be found in [[getting_started:programmatic_example|Programmatic API Example]].

----

===== Running the Solver =====

The solver is run as:
<code>
results = solverAiClientCompute.runSolver(input)
</code>
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++: \\ <code>std::vector<std::vector<std::variant<std::<float, std::string>>>></code>
  * Python: \\ <code>list(list())</code>
  * JavaScript: \\ <code>Array(Array())</code>

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: \\ <code>inputVariable = results.getInputVariableNames()</code>
  * 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: \\ <code>outputVariable = results.getOutputVariableNames()</code>