desdeo_mcdm.interactive.NIMBUS

Module Contents

Classes

NimbusClassificationRequest	A request to handle the classification of objectives in the synchronous NIMBUS method.
NimbusSaveRequest	A request to handle archiving of the solutions computed with NIMBUS.
NimbusIntermediateSolutionsRequest	A request to handle the computation of intermediate points between two previously computed points.
NimbusMostPreferredRequest	A request to handle the indication of a preferred point.
NimbusStopRequest	A request to handle the termination of Synchronous NIMBUS.
NIMBUS	Implements the synchronous NIMBUS algorithm.

Functions

f_1(x)

exception desdeo_mcdm.interactive.NIMBUS.NimbusException

Bases: Exception

Risen when an error related to NIMBUS is encountered.

class desdeo_mcdm.interactive.NIMBUS.NimbusClassificationRequest(method: NIMBUS, ref: numpy.ndarray)

Bases: desdeo_tools.interaction.request.BaseRequest

A request to handle the classification of objectives in the synchronous NIMBUS method.

Parameters:

• method (NIMBUS) – The instance of the NIMBUS method the request should be initialized for.

• ref (np.ndarray) – Objective values used as a reference the decision maker is classifying the objectives.

self._valid_classifications

The valid classifications. Defaults is [‘<’, ‘<=’, ‘=’, ‘>=’, ‘0’]

Type:

List[str]

validator(response: Dict) → None

Validates a dictionary containing the response of a decision maker. Should contain the keys ‘classifications’, ‘levels’, and ‘number_of_solutions’.

‘classifications’ should be a list of strings, where the number of elements is equal to the number of objectives being classified, and the elements are found in _valid_classifications. ‘levels’ should have either aspiration levels or bounds for each objective depending on that objective’s classification. ‘number_of_solutions’ should be an integer between 1 and 4 indicating the number of intermediate solutions to be computed.

Parameters:

response (Dict) – See the documentation for validator.

Raises:

NimbusException – Some discrepancy is encountered in the parsing of the response.

class desdeo_mcdm.interactive.NIMBUS.NimbusSaveRequest(solution_vectors: List[numpy.ndarray], objective_vectors: List[numpy.ndarray])

Bases: desdeo_tools.interaction.request.BaseRequest

A request to handle archiving of the solutions computed with NIMBUS.

Parameters:

• solution_vectors (List[np.ndarray]) – A list of numpy arrays each representing a decision variable vector.

• objective_vectors (List[np.ndarray]) – A list of numpy arrays each representing an objective vector.

Note

The objective vector at position ‘i’ in objective_vectors should correspond to the decision variables at position ‘i’ in solution_vectors.

validator(response: Dict) → None

Validates a response dictionary. The dictionary should contain the keys ‘indices’.

‘indices’ should be a list of integers representing an index to the lists solutions_vectors and objective_vectors.

Parameters:

response (Dict) – See the documentation for validator.

Raises:

NimbusException – Some discrepancy is encountered in the parsing of response.

class desdeo_mcdm.interactive.NIMBUS.NimbusIntermediateSolutionsRequest(solution_vectors: List[numpy.ndarray], objective_vectors: List[numpy.ndarray])

Bases: desdeo_tools.interaction.request.BaseRequest

A request to handle the computation of intermediate points between two previously computed points.

Parameters:

• solution_vectors (List[np.ndarray]) – A list of numpy arrays each representing a decision variable vector.

• objective_vectors (List[np.ndarray]) – A list of numpy arrays each representing an objective vector.

Note

The objective vector at position ‘i’ in objective_vectors should correspond to the decision variables at position ‘i’ in solution_vectors. Only the two first entries in each of the lists is relevant. The rest is ignored.

validator(response: Dict)

Validates a response dictionary. The dictionary should contain the keys ‘indices’ and ‘number_of_solutions’.

‘indices’ should be a list of integers representing an index to the lists solutions_vectors and objective_vectors. ‘number_of_solutions’ should be an integer greater or equal to 1.

Parameters:

response (Dict) – See the documentation for validator.

Raises:

NimbusException – Some discrepancy is encountered in the parsing of response.

class desdeo_mcdm.interactive.NIMBUS.NimbusMostPreferredRequest(solution_vectors: List[numpy.ndarray], objective_vectors: List[numpy.ndarray])

Bases: desdeo_tools.interaction.request.BaseRequest

A request to handle the indication of a preferred point.

Parameters:

• solution_vectors (List[np.ndarray]) – A list of numpy arrays each representing a decision variable vector.

• objective_vectors (List[np.ndarray]) – A list of numpy arrays each representing an objective vector.

Note

The objective vector at position ‘i’ in objective_vectors should correspond to the decision variables at position ‘i’ in solution_vectors. Only the two first entries in each of the lists are relevant. The preferred solution will be selected from objective_vectors.

validator(response: Dict)

Validates a response dictionary. The dictionary should contain the keys ‘index’ and ‘continue’.

‘index’ is an integer and should indicate the index of the preferred solution is objective_vectors. ‘continue’ is a boolean and indicates whether to stop or continue the iteration of Synchronous NIMBUS.

Parameters:

response (Dict) – See the documentation for validator.

Raises:

NimbusException – Some discrepancy is encountered in the parsing of response.

class desdeo_mcdm.interactive.NIMBUS.NimbusStopRequest(solution_final: numpy.ndarray, objective_final: numpy.ndarray)

Bases: desdeo_tools.interaction.request.BaseRequest

A request to handle the termination of Synchronous NIMBUS.

Parameters:

• solutions_final (np.ndarray) – A numpy array containing the final decision variable values.

• objective_final (np.ndarray) – A numpy array containing the final objective variables which correspond to

• solution_final. –

Note

This request expects no response.

class desdeo_mcdm.interactive.NIMBUS.NIMBUS(problem: desdeo_problem.problem.MOProblem | desdeo_problem.problem.DiscreteDataProblem, scalar_method: desdeo_tools.solver.ScalarSolver.ScalarMethod | str | None = 'scipy_de', starting_point: numpy.ndarray | None = None)

Bases: desdeo_mcdm.interactive.InteractiveMethod.InteractiveMethod

Implements the synchronous NIMBUS algorithm.

Parameters:

• problem (MOProblem) – The problem to be solved.

• scalar_method (Optional[Union[ScalarMethod, str]], optional) – The method used to solve the various ASF minimization problems present in the method. Defaults to ‘scipy_de’ (differential evolution).

• starting_point (Optional[np.ndarray], optional) – The initial solution (objectives) to start classification from. If None, a neutral starting point will be computed.

Note

When a starting point is supplied, decision variables of that point will be approximated to be the variables of the solution closest to the starting point. In other words, the decision variables associated to the initial point may be inaccurate!

start() → Tuple[NimbusClassificationRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Return the first request to start iterating NIMBUS.

Returns:

The first request and and a plot request to visualize relevant data.

Return type:

Tuple[NimbusClassificationRequest, SimplePlotRequest]

request_classification() → Tuple[NimbusClassificationRequest, desdeo_tools.interaction.request.SimplePlotRequest]

create_plot_request(objectives: numpy.ndarray, msg: str) → desdeo_tools.interaction.request.SimplePlotRequest

Used to create a plot request for visualizing objective values.

Parameters:

• objectives (np.ndarray) – A 2D numpy array containing objective vectors to be visualized.

• msg (str) – A message to be displayed in the context of a visualization.

Returns:

A plot request to create a visualization.

Return type:

SimplePlotRequest

handle_classification_request(request: NimbusClassificationRequest) → Tuple[NimbusSaveRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Handles a classification request.

Parameters:

request (NimbusClassificationRequest) – A classification request with the response attribute set.

Returns:

A NIMBUS save request and a plot request with the solutions the decision maker can choose from to save for alter use.

Return type:

Tuple[NimbusSaveRequest, SimplePlotRequest]

handle_save_request(request: NimbusSaveRequest) → Tuple[NimbusIntermediateSolutionsRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Handles a save request.

Parameters:

request (NimbusSaveRequest) – A save request with the response attribute set.

Returns:

Return an intermediate solution request where the decision maker can specify whether they would like to see intermediate solution between two previously computed solutions. The plot request has the available solutions.

Return type:

Tuple[NimbusIntermediateSolutionsRequest, SimplePlotRequest]

handle_intermediate_solutions_request(request: NimbusIntermediateSolutionsRequest) → Tuple[NimbusSaveRequest | NimbusMostPreferredRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Handles an intermediate solutions request.

Parameters:

request (NimbusIntermediateSolutionsRequest) – A NIMBUS intermediate solutions request with the response attribute set.

Returns:

Return either a save request or a preferred solution request. The former is returned if the decision maker wishes to see intermediate points, the latter otherwise. Also a plot request is returned with the solutions available in it.

Return type:

Tuple[Union[NimbusSaveRequest, NimbusMostPreferredRequest], SimplePlotRequest,]

handle_most_preferred_request(request: NimbusMostPreferredRequest) → Tuple[NimbusClassificationRequest | NimbusStopRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Handles a preferred solution request.

Parameters:

request (NimbusMostPreferredRequest) – A NIMBUS preferred solution request with the response attribute set.

Returns:

Return a classification request if the decision maker wishes to continue. If the decision maker wishes to stop, return a stop request. Also return a plot request with all the solutions saved so far.

Return type:

Tuple[Union[NimbusClassificationRequest, NimbusStopRequest], SimplePlotRequest]

request_stop() → Tuple[NimbusStopRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Create a NimbusStopRequest based on self.

Returns:

A stop request and a plot request with the final solution chosen in it.

Return type:

Tuple[NimbusStopRequest, SimplePlotRequest]

request_most_preferred_solution(solutions: numpy.ndarray, objectives: numpy.ndarray) → Tuple[NimbusMostPreferredRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Create a NimbusMostPreferredRequest.

Parameters:

• solutions (np.ndarray) – A 2D numpy array of decision variable vectors.

• objectives (np.ndarray) – A 2D numpy array of objective value vectors.

Returns:

The requests based on the given arguments.

Return type:

Tuple[NimbusMostPreferredRequest, SimplePlotRequest]

Note

The ‘i’th decision variable vector in solutions should correspond to the ‘i’th objective value vector in objectives.

compute_intermediate_solutions(solutions: numpy.ndarray, n_desired: int) → Tuple[NimbusSaveRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Computes intermediate solution between two solutions computed earlier.

Parameters:

• solutions (np.ndarray) – The solutions between which the intermediate solutions should be computed.

• n_desired (int) – The number of intermediate solutions desired.

Raises:

NimbusException –

Returns:

A save request with the computed intermediate points, and a plot request to visualize said points.

Return type:

Tuple[NimbusSaveRequest, SimplePlotRequest]

save_solutions_to_archive(objectives: numpy.ndarray, decision_variables: numpy.ndarray, indices: List[int]) → Tuple[NimbusIntermediateSolutionsRequest, None]

Save solutions to the archive. Saves also the corresponding objective function values.

Parameters:

• objectives (np.ndarray) – Available objectives.

• decision_variables (np.ndarray) – Available solutions.

• indices (List[int]) – Indices of the solutions to be saved.

Returns:

An intermediate solutions request asking the decision maker whether they would like to generate intermediata solutions between two existing solutions. Also returns a plot request to visualize the available solutions between which the intermediate solutions should be computed.

Return type:

Tuple[NimbusIntermediateSolutionsRequest, None]

calculate_new_solutions(number_of_solutions: int, levels: numpy.ndarray, improve_inds: numpy.ndarray, improve_until_inds: numpy.ndarray, acceptable_inds: numpy.ndarray, impaire_until_inds: numpy.ndarray, free_inds: numpy.ndarray) → Tuple[NimbusSaveRequest, desdeo_tools.interaction.request.SimplePlotRequest]

Calculates new solutions based on classifications supplied by the decision maker by

solving ASF problems.

Parameters:

• number_of_solutions (int) – Number of solutions, should be between 1 and 4.

• levels (np.ndarray) – Aspiration and upper bounds relevant to the some of the classifications.

• improve_inds (np.ndarray) – Indices corresponding to the objectives which should be improved.

• improve_until_inds (np.ndarray) – Like above, but improved until an aspiration level is reached.

• acceptable_inds (np.ndarray) – Indices of objectives which are acceptable as they are now.

• impaire_until_inds (np.ndarray) – Indices of objectives which may be impaired until an upper limit is reached.

• free_inds (np.ndarray) – Indices of objectives which may change freely.

Returns:

A save request with the newly computed solutions, and a plot request to visualize said solutions.

Return type:

Tuple[NimbusSaveRequest, SimplePlotRequest]

update_current_solution(solutions: numpy.ndarray, objectives: numpy.ndarray, index: int) → None

Update the state of self with a new current solution and the corresponding objective values. This solution is used in the classification phase of synchronous NIMBUS.

Parameters:

• solutions (np.ndarray) – A 2D numpy array of decision variable vectors.

• objectives (np.ndarray) – A 2D numpy array of objective value vectors.

• index (int) – The index of the solution in solutions and objectives.

Returns:

The requests based on the given arguments.

Return type:

Tuple[NimbusMostPreferredRequest, SimplePlotRequest]

Note

The ‘i’th decision variable vector in solutions should correspond to the ‘i’th objective value vector in objectives.

iterate(request: NimbusClassificationRequest | NimbusSaveRequest | NimbusIntermediateSolutionsRequest | NimbusMostPreferredRequest | NimbusStopRequest) → Tuple[NimbusClassificationRequest | NimbusSaveRequest | NimbusIntermediateSolutionsRequest, desdeo_tools.interaction.request.SimplePlotRequest | None]

Implements a finite state machine to iterate over the different steps defined in Synchronous NIMBUS based on a supplied request.

Parameters:

request (Union[NimbusClassificationRequest,NimbusSaveRequest,NimbusIntermediateSolutionsRequest,NimbusMostPreferredRequest,NimbusStopRequest,]) – A request based on the next step in the NIMBUS algorithm is taken.

Raises:

NimbusException – If a wrong type of request is supplied based on the current state NIMBUS is in.

Returns:

The next logically sound request.

Return type:

Tuple[Union[NimbusClassificationRequest,NimbusSaveRequest,NimbusIntermediateSolutionsRequest,],Union[SimplePlotRequest, None],]

desdeo_mcdm.interactive.NIMBUS.f_1(x)