:py:mod:`desdeo_mcdm.interactive.NIMBUS` ======================================== .. py:module:: desdeo_mcdm.interactive.NIMBUS Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: desdeo_mcdm.interactive.NIMBUS.NimbusClassificationRequest desdeo_mcdm.interactive.NIMBUS.NimbusSaveRequest desdeo_mcdm.interactive.NIMBUS.NimbusIntermediateSolutionsRequest desdeo_mcdm.interactive.NIMBUS.NimbusMostPreferredRequest desdeo_mcdm.interactive.NIMBUS.NimbusStopRequest desdeo_mcdm.interactive.NIMBUS.NIMBUS Functions ~~~~~~~~~ .. autoapisummary:: desdeo_mcdm.interactive.NIMBUS.f_1 .. py:exception:: NimbusException Bases: :py:obj:`Exception` Risen when an error related to NIMBUS is encountered. .. py:class:: NimbusClassificationRequest(method: NIMBUS, ref: numpy.ndarray) Bases: :py:obj:`desdeo_tools.interaction.request.BaseRequest` A request to handle the classification of objectives in the synchronous NIMBUS method. :param method: The instance of the NIMBUS method the request should be initialized for. :type method: NIMBUS :param ref: Objective values used as a reference the decision maker is classifying the objectives. :type ref: np.ndarray .. attribute:: self._valid_classifications The valid classifications. Defaults is ['<', '<=', '=', '>=', '0'] :type: List[str] .. py:method:: 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. :param response: See the documentation for `validator`. :type response: Dict :raises NimbusException: Some discrepancy is encountered in the parsing of the response. .. py:class:: NimbusSaveRequest(solution_vectors: List[numpy.ndarray], objective_vectors: List[numpy.ndarray]) Bases: :py:obj:`desdeo_tools.interaction.request.BaseRequest` A request to handle archiving of the solutions computed with NIMBUS. :param solution_vectors: A list of numpy arrays each representing a decision variable vector. :type solution_vectors: List[np.ndarray] :param objective_vectors: A list of numpy arrays each representing an objective vector. :type objective_vectors: List[np.ndarray] .. note:: The objective vector at position 'i' in `objective_vectors` should correspond to the decision variables at position 'i' in `solution_vectors`. .. py:method:: 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`. :param response: See the documentation for `validator`. :type response: Dict :raises NimbusException: Some discrepancy is encountered in the parsing of `response`. .. py:class:: NimbusIntermediateSolutionsRequest(solution_vectors: List[numpy.ndarray], objective_vectors: List[numpy.ndarray]) Bases: :py:obj:`desdeo_tools.interaction.request.BaseRequest` A request to handle the computation of intermediate points between two previously computed points. :param solution_vectors: A list of numpy arrays each representing a decision variable vector. :type solution_vectors: List[np.ndarray] :param objective_vectors: A list of numpy arrays each representing an objective vector. :type objective_vectors: List[np.ndarray] .. 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. .. py:method:: 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. :param response: See the documentation for `validator`. :type response: Dict :raises NimbusException: Some discrepancy is encountered in the parsing of `response`. .. py:class:: NimbusMostPreferredRequest(solution_vectors: List[numpy.ndarray], objective_vectors: List[numpy.ndarray]) Bases: :py:obj:`desdeo_tools.interaction.request.BaseRequest` A request to handle the indication of a preferred point. :param solution_vectors: A list of numpy arrays each representing a decision variable vector. :type solution_vectors: List[np.ndarray] :param objective_vectors: A list of numpy arrays each representing an objective vector. :type objective_vectors: List[np.ndarray] .. 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`. .. py:method:: 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. :param response: See the documentation for `validator`. :type response: Dict :raises NimbusException: Some discrepancy is encountered in the parsing of `response`. .. py:class:: NimbusStopRequest(solution_final: numpy.ndarray, objective_final: numpy.ndarray) Bases: :py:obj:`desdeo_tools.interaction.request.BaseRequest` A request to handle the termination of Synchronous NIMBUS. :param solutions_final: A numpy array containing the final decision variable values. :type solutions_final: np.ndarray :param objective_final: A numpy array containing the final objective variables which correspond to :type objective_final: np.ndarray :param `solution_final`.: .. note:: This request expects no response. .. py:class:: NIMBUS(problem: Union[desdeo_problem.problem.MOProblem, desdeo_problem.problem.DiscreteDataProblem], scalar_method: Optional[Union[desdeo_tools.solver.ScalarSolver.ScalarMethod, str]] = 'scipy_de', starting_point: Optional[numpy.ndarray] = None) Bases: :py:obj:`desdeo_mcdm.interactive.InteractiveMethod.InteractiveMethod` Implements the synchronous NIMBUS algorithm. :param problem: The problem to be solved. :type problem: MOProblem :param scalar_method: The method used to solve the various ASF minimization problems present in the method. Defaults to 'scipy_de' (differential evolution). :type scalar_method: Optional[Union[ScalarMethod, str]], optional :param starting_point: The initial solution (objectives) to start classification from. If None, a neutral starting point will be computed. :type starting_point: Optional[np.ndarray], optional .. 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! .. py:method:: 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. :rtype: Tuple[NimbusClassificationRequest, SimplePlotRequest] .. py:method:: request_classification() -> Tuple[NimbusClassificationRequest, desdeo_tools.interaction.request.SimplePlotRequest] .. py:method:: create_plot_request(objectives: numpy.ndarray, msg: str) -> desdeo_tools.interaction.request.SimplePlotRequest Used to create a plot request for visualizing objective values. :param objectives: A 2D numpy array containing objective vectors to be visualized. :type objectives: np.ndarray :param msg: A message to be displayed in the context of a visualization. :type msg: str :returns: A plot request to create a visualization. :rtype: SimplePlotRequest .. py:method:: handle_classification_request(request: NimbusClassificationRequest) -> Tuple[NimbusSaveRequest, desdeo_tools.interaction.request.SimplePlotRequest] Handles a classification request. :param request: A classification request with the response attribute set. :type request: NimbusClassificationRequest :returns: A NIMBUS save request and a plot request with the solutions the decision maker can choose from to save for alter use. :rtype: Tuple[NimbusSaveRequest, SimplePlotRequest] .. py:method:: handle_save_request(request: NimbusSaveRequest) -> Tuple[NimbusIntermediateSolutionsRequest, desdeo_tools.interaction.request.SimplePlotRequest] Handles a save request. :param request: A save request with the response attribute set. :type request: NimbusSaveRequest :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. :rtype: Tuple[NimbusIntermediateSolutionsRequest, SimplePlotRequest] .. py:method:: handle_intermediate_solutions_request(request: NimbusIntermediateSolutionsRequest) -> Tuple[Union[NimbusSaveRequest, NimbusMostPreferredRequest], desdeo_tools.interaction.request.SimplePlotRequest] Handles an intermediate solutions request. :param request: A NIMBUS intermediate solutions request with the response attribute set. :type request: NimbusIntermediateSolutionsRequest :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. :rtype: Tuple[Union[NimbusSaveRequest, NimbusMostPreferredRequest], SimplePlotRequest,] .. py:method:: handle_most_preferred_request(request: NimbusMostPreferredRequest) -> Tuple[Union[NimbusClassificationRequest, NimbusStopRequest], desdeo_tools.interaction.request.SimplePlotRequest] Handles a preferred solution request. :param request: A NIMBUS preferred solution request with the response attribute set. :type request: NimbusMostPreferredRequest :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. :rtype: Tuple[Union[NimbusClassificationRequest, NimbusStopRequest], SimplePlotRequest] .. py:method:: 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. :rtype: Tuple[NimbusStopRequest, SimplePlotRequest] .. py:method:: request_most_preferred_solution(solutions: numpy.ndarray, objectives: numpy.ndarray) -> Tuple[NimbusMostPreferredRequest, desdeo_tools.interaction.request.SimplePlotRequest] Create a NimbusMostPreferredRequest. :param solutions: A 2D numpy array of decision variable vectors. :type solutions: np.ndarray :param objectives: A 2D numpy array of objective value vectors. :type objectives: np.ndarray :returns: The requests based on the given arguments. :rtype: Tuple[NimbusMostPreferredRequest, SimplePlotRequest] .. note:: The 'i'th decision variable vector in `solutions` should correspond to the 'i'th objective value vector in `objectives`. .. py:method:: compute_intermediate_solutions(solutions: numpy.ndarray, n_desired: int) -> Tuple[NimbusSaveRequest, desdeo_tools.interaction.request.SimplePlotRequest] Computes intermediate solution between two solutions computed earlier. :param solutions: The solutions between which the intermediate solutions should be computed. :type solutions: np.ndarray :param n_desired: The number of intermediate solutions desired. :type n_desired: int :raises NimbusException: :returns: A save request with the computed intermediate points, and a plot request to visualize said points. :rtype: Tuple[NimbusSaveRequest, SimplePlotRequest] .. py:method:: 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. :param objectives: Available objectives. :type objectives: np.ndarray :param decision_variables: Available solutions. :type decision_variables: np.ndarray :param indices: Indices of the solutions to be saved. :type indices: List[int] :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. :rtype: Tuple[NimbusIntermediateSolutionsRequest, None] .. py:method:: 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. :param number_of_solutions: Number of solutions, should be between 1 and 4. :type number_of_solutions: int :param levels: Aspiration and upper bounds relevant to the some of the classifications. :type levels: np.ndarray :param improve_inds: Indices corresponding to the objectives which should be improved. :type improve_inds: np.ndarray :param improve_until_inds: Like above, but improved until an aspiration level is reached. :type improve_until_inds: np.ndarray :param acceptable_inds: Indices of objectives which are acceptable as they are now. :type acceptable_inds: np.ndarray :param impaire_until_inds: Indices of objectives which may be impaired until an upper limit is reached. :type impaire_until_inds: np.ndarray :param free_inds: Indices of objectives which may change freely. :type free_inds: np.ndarray :returns: A save request with the newly computed solutions, and a plot request to visualize said solutions. :rtype: Tuple[NimbusSaveRequest, SimplePlotRequest] .. py:method:: 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. :param solutions: A 2D numpy array of decision variable vectors. :type solutions: np.ndarray :param objectives: A 2D numpy array of objective value vectors. :type objectives: np.ndarray :param index: The index of the solution in `solutions` and `objectives`. :type index: int :returns: The requests based on the given arguments. :rtype: Tuple[NimbusMostPreferredRequest, SimplePlotRequest] .. note:: The 'i'th decision variable vector in `solutions` should correspond to the 'i'th objective value vector in `objectives`. .. py:method:: iterate(request: Union[NimbusClassificationRequest, NimbusSaveRequest, NimbusIntermediateSolutionsRequest, NimbusMostPreferredRequest, NimbusStopRequest]) -> Tuple[Union[NimbusClassificationRequest, NimbusSaveRequest, NimbusIntermediateSolutionsRequest], Union[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. :param request: A request based on the next step in the NIMBUS algorithm is taken. :type request: Union[NimbusClassificationRequest,NimbusSaveRequest,NimbusIntermediateSolutionsRequest,NimbusMostPreferredRequest,NimbusStopRequest,] :raises NimbusException: If a wrong type of request is supplied based on the current state NIMBUS is in. :returns: The next logically sound request. :rtype: Tuple[Union[NimbusClassificationRequest,NimbusSaveRequest,NimbusIntermediateSolutionsRequest,],Union[SimplePlotRequest, None],] .. py:function:: f_1(x)