The API supports guest users as well. These users will not need to be registered and credentials for guest users may be requested at any time. When created, default test problems will be added to the guest user.
Note
Notice that guest users will have access to only the pre-defined test problems and cannot define their own multiobjective optimization problems. Guest users cannot save any data to the database and will be deleted periodically. The name of the guest user is always prefixed with guest_ followed by random 5 characters, e.g., guest_abc12.
To request credentials for a guest user, use the following endpoint:
Solutions related to defined problems can be saved and fetched from the database. Currently, only a single archive of solutions can exists for each problem.
Add solutions to an archive for a specific problem. Example for problem with 3 variables and 2 objectives.
When iterated, each 'GET' and 'POST' call to interactive methods will return a JSON object with at least the field 'response'. This field will contain all the relevant information that is needed to show information about the problem being solved and the state of the interactive method. This information can then be used, for example, to show relevant visualizations in a graphical user interface.
Note
For EA methods, sometimes a 'response' field will not be present. See RVEA.
Below, a short summary of the contents of these JSON objects is given for some methods. For additional information, one should check DESDEO's documentation for the different methods both in desdeo-mcdm's documentation and in desdeo-emo's documentation.
The requests returned by 'GET' and 'POST' contain a JSON object with contents as shown below:
json
- {
"response": { "message": "...", "ideal": "...", "nadir": "...", "reachable_lb": "...", "reachable_ub": "...", "user_bounds": "...", "reachable_idx": "...", "step_number": "...", "steps_remaining": "...", "distance": "...", "allowed_speeds": "...", "current_speed": "...", "navigation_point": "...", },
}
Most of the information in the above JSON object can be used to show the user information related to the problem being solved. Not all entries are necessarily relevant or defined. However, the entries 'ideal', 'nadir', 'reachable_lb', 'reachable_ub', 'step_number', and 'steps_remaining' are always defined. The default number of steps taken in NAUTILUS Navigator defaults to '100', which should be kept in mind when using the method.
To continue iterating, NAUTILUS Navigator expects a response in subsequent 'POST' requests with the following JSON contents defined:
json
- {
"response": { "reference_point": "...", "speed": "...", "go_to_previous": "...", "stop": "...", "user_bounds": "...", },
}
Each of these fields must always be defined. User bounds may default to 'NaN's as long as the dimension of the array matches the number of objectives present in the multiobjective optimization problem being solved. Notice that if a step is taken backwards, the response supplied in the 'POST' request by the caller must also contain that step's original information present in that step's original response. I.e., if a step is to be taken backwards from step number x to step y (y < x), then the response from x must contain all the information that was present in the original response in step y returned by the API (the fields 'ideal', 'nadir', 'reachable_lb', etc...).
Note
It is a good idea to store the information in each of the JSON objects returned by the requests issued by a client so that stepping back is possible to any point from the current point.
When E-NAUTILUS is first started, the first request returned by E-NAUTILUS will look as the example shown below:
json
- {
- "response": {
"message": "...", "ideal": "[0.4, 0.9, 0.11]", "nadir": "[5.9, 9.8, 12.3]",
},
}
The ideal and nadir entries will show the best and worst reachable values from the starting point, which in E-NAUTILUS is the nadir point. As a response to this request, a JSON object with the following contents is expected (with example values):
json
- {
- "response": {
"n_iterations": 10, "n_points": 3,
},
}
In the above object, n_iterations is the number of total iterations that should be taken in the E-NAUTILUS method and n_points is the number of intermediate points shown in each iteration. The number of iterations may be changed during the course of the method.
After E-NAUTILUS has been initialized by providing the above response to the first request, subsequent requests will have the following (example) contents:
json
- {
- "response": {
"message": "...", "ideal": "[0.4, 0.9, 0.11]", "nadir": "[5.9, 9.8, 12.3]", "points": "[[1.2, 3.2, 2.2], [0.8, 3.1, 3.9]]", "lower_bounds": "[[0.9, 1.2, 2.2], [0.5, 1.1, 1.9]]", "upper_bounds": "[[3.9, 3.2, 4.2], [3.5, 3.1, 4.9]]", "n_iterations_left": 4, "distances": "[0.66, 0.56]",
},
}
In these requests, the entry points will be a 2-dimensional array with the intermediate points returned by E-NAUTILUS in an intermediate iteration. Likewise, lower_bounds and upper_bounds are the lower and upper bounds of the reachable from each intermediate point. n_iterations_left is the number of iterations left and distances are the distances (0-100, zero being farthest from the Pareto front and 100 being closest) of each intermediate point to the Pareto optimal front. points, lower_bounds, and upper_bounds are ordered by index, meaning that the bounds of the point at index n in points are located at index n in lower_bounds and upper_bounds, respectively.
The response expected to the above type of requests should have the following fields (with examples given):
json
- {
- "response": {
"preferred_point_index": 1, "step_back": false, "change_remaining": true, "iterations_left": 5,
},
}
Above, preferred_point_index is the index of the point in points which should be selected for the next iteration in E-NAUTILUS. step_back indicates that the method should go back to a previous iteration. change_remaining indicates that the remaining number of iterations should be changed. iterations_left is required only when either step_back or change_remaining is true.
Note
When stepping back in E-NAUTILUS (i.e., step_back is set to true), a response with the follwoing example contents is expected:
json
- {
- "response": {
"preferred_point_index": "...", "step_back": true, "change_remaining": "...", "prev_solutions": "[[1.2, 3.2, 2.2], [0.8, 3.1, 3.9]]", "prev_lower_bounds": "[[0.9, 1.2, 2.2], [0.5, 1.1, 1.9]]", "prev_upper_bounds": "[[3.9, 3.2, 4.2], [3.5, 3.1, 4.9]]", "iterations_left": 3, "prev_distances": "[0.66, 0.56]",
}
}
In other words, the full state of the E-NAUTILUS method in the previous iterations, to which we wish to return, must be supplied is the response. It is therefore a good idea to keep track of previous states in any application making use of this API.
When E-NAUTILUS is iterated for the last time, a request with the following example contents is returned:
json
- {
- "response": {
"message": "...", "solution": "[1.0, 1.1, 1.2]",
},
}
The solution entry contains the final (Pareto optimal) solution found by the E-NAUTILUS method in the objective space of the problem being solved.
Note
At the moment, only the objective values of the solution are returned.
Warning
For the time being, setting the initialization parameters for RVEA is not possible using the web API. This means that default values will be used. See RVEA in desdeo-emo's documenation for the default values. RVEA will be initialized in its interactive form when used through the web API.
The requests returned by GET and POST contain a JSON object with both a response and preference_type field. An example of a JSON object returned by RVEA is shown below:
json
- {
"response": [{ "message": "...", "validator": "...", }, { "message": "...", "validator": "...", }, { "message": "...", "validator": "...", "dimensions_data": "...", }, { "message": "...", "validator": "...", "dimensions_data": "...", }], "preference_type": "integer value", "individuals": "...", "objectives": "...",
}
The validator in the above response field in the JSON is a string with the name of the validator, which is used internally in DESDEO. Its use in a front-end application will be informative at best. On the other hand, dimensions_data contains useful information regarding individual objectives. An example of the contents of dimensions_data is as follows:
json
- {
"dimensions_data": { "('f1',)": { "minimize": 1, "ideal": "some_value", "nadir": "some_value", }, "('f2',)": { "minimize": 1, "ideal": "some_value", "nadir": "some_value", }, }
}
In the above JSON object, the example contains dimensions_data for two objectives. Depeding on the problem, the names and number of objectives will vary.
The individuals and objectives fields contain the population (i.e., the individual decision variable vectors) and objective vector associated with each individual, respectively.
Note
The individuals and objectives returned in requests from intermediatre iterations are not necessarely non-dominated. When stopping the method (see below) returned solutions will be non-dominated.
The preference_type field is used to indicate which kind of preference information is given in a response returned from a client side application (i.e., in a POST request). In other words, this integer valued field is used to select one of the responses in the list of objects in the response field in the JSON file at the beginning of this subsection. A positive integer value for preference_type will be understood as a selection of a preference type while a value of '-1' will be understood as a request to stop the method and end iterating. A stop request will return the final population (i.e., decision variable vectors) and their associated objective vectors in a JSON file as shown:
json
- {
"individuals": ["list elements"], "objectives": ["list elements"],
}
Note
The individuals and objectives returned when stopping the mehtod will be non-dominated. Notice also that there is no response field when stopping the method (this is to keep a consistent logic of having these two fields at "the top level" of the JSON objects, like in the ones returned from iterating the method).
When iterating RVEA (a POST request is made to the server), a JSON file with the following contents is expected in the request:
json
- {
"response": { "preference_data": "some data", "preference_type": "integer value", },
}
In the above, the preference_type field is the same as discussed previously. The preference_data field contains preference information, which varies depending on the specified preference_type.
For example, if preference is to be given by choosing available solutions from a list as indices of those solutions, the above JSON object might look as follows:
json
- {
"response": { "preference_data": [2,4,1], "preference_type": 0, },
}
Other types of preference available are: specifying indices of solution which are not preferred, specifying a reference point, and specifying a desired range for each objective as upper and lower bound pairs. Examples of JSON objects with different kinds of preference types for a problem with three objectives are as follows:
Specifying indices of solutions which are not preferred:
json
- {
"response": { "preference_data": [6,10,42], "preference_type": 1, },
}
Specifying a reference point:
json
- {
"response": { "preference_data": [0.2, 0.5, 0.1], "preference_type": 2, },
}
Specifying a desired range for each objective as upper and lower bound pairs:
json
- {
"response": { "preference_data": [ [0.3, 0.6], [0.2, 0.3], [0.9, 1.0], ], "preference_type": 3, },
}
Note
For a more detailed discussion on the various preference types, please see the related page in desdeo-emo's documentation: Interaction in EAs.