`desdeo_mcdm.interactive.Nautilus`

NAUTILUS 1

Module Contents

Classes

`NautilusInitialRequest`	A request class to handle the Decision maker's initial preferences for the first iteration round.
`NautilusRequest`	A request class to handle the Decision maker's preferences after the first iteration round.
`NautilusStopRequest`	A request class to handle termination.
`Nautilus`	Implements the basic NAUTILUS method as presented in \|Miettinen_2010\|.

Functions

`validate_response`(→ None)	Validate decision maker's response.
`validate_preferences`(→ None)	Validate decision maker's preferences.
`validate_n_iterations`(→ None)	Validate decision maker's preference for number of iterations.
`f1`(xs)

desdeo_mcdm.interactive.Nautilus.validate_response(n_objectives: int, z_current: numpy.ndarray, nadir: numpy.ndarray, response: Dict, first_iteration_bool: bool) → None[source]

Validate decision maker’s response.

Parameters:

n_objectives (int) – Number of objectives.
z_current (np.ndarray) – Current iteration point.
nadir (np.ndarray) – Nadir point.
response (Dict) – Decision maker’s response containing preference information.
first_iteration_bool (bool) – Indicating whether the iteration round is the first one (True) or not (False).

Raises:

NautilusException – In case Decision maker’s response is not valid.

desdeo_mcdm.interactive.Nautilus.validate_preferences(n_objectives: int, response: Dict) → None[source]

Validate decision maker’s preferences.

Parameters:

n_objectives (int) – Number of objectives in problem.
response (Dict) – Decision maker’s response containing preference information.

Raises:

NautilusException – In case preference info is not valid.

desdeo_mcdm.interactive.Nautilus.validate_n_iterations(n_it: int) → None[source]

Validate decision maker’s preference for number of iterations.

Parameters:: n_it (int) – Number of iterations.
Raises:: NautilusException – If number of iterations given is not an positive integer greater than zero.

exception desdeo_mcdm.interactive.Nautilus.NautilusException[source]

Bases: Exception

Raised when an exception related to Nautilus is encountered.

class desdeo_mcdm.interactive.Nautilus.NautilusInitialRequest(ideal: numpy.ndarray, nadir: numpy.ndarray)[source]

Bases: desdeo_tools.interaction.request.BaseRequest

A request class to handle the Decision maker’s initial preferences for the first iteration round.

classmethod init_with_method(method: desdeo_mcdm.interactive.InteractiveMethod.InteractiveMethod)[source]

Initialize request with given instance of Nautilus method.

Parameters:: method (Nautilus) – Instance of Nautilus-class.
Returns:: Initial request.
Return type:: NautilusInitialRequest

class desdeo_mcdm.interactive.Nautilus.NautilusRequest(z_current: numpy.ndarray, nadir: numpy.ndarray, lower_bounds: numpy.ndarray, upper_bounds: numpy.ndarray, distance: numpy.ndarray)[source]

Bases: desdeo_tools.interaction.request.BaseRequest

A request class to handle the Decision maker’s preferences after the first iteration round.

Parameters:

z_current (np.ndarray) – Current iteration point.
nadir (np.ndarray) – Nadir point.
lower_bounds (np.ndarray) – Lower bounds for objective functions for next iteration.
upper_bounds (np.ndarray) – Upper bounds for objective functions for next iteration.
distance (np.ndarray) – Closeness to Pareto optimal front.

class desdeo_mcdm.interactive.Nautilus.NautilusStopRequest(x_h: numpy.ndarray, f_h: numpy.ndarray)[source]

Bases: desdeo_tools.interaction.request.BaseRequest

A request class to handle termination.

class desdeo_mcdm.interactive.Nautilus.Nautilus(problem: desdeo_problem.problem.MOProblem, ideal: numpy.ndarray, nadir: numpy.ndarray, epsilon: float = 1e-06, objective_names: List[str] | None = None, minimize: List[int] | None = None)[source]

Bases: desdeo_mcdm.interactive.InteractiveMethod.InteractiveMethod

Implements the basic NAUTILUS method as presented in |Miettinen_2010|.

In NAUTILUS, starting from the nadir point, a solution is obtained at each iteration which dominates the previous one. Although only the last solution will be Pareto optimal, the decision maker never looses sight of the Pareto optimal set, and the search is oriented so that (s)he progressively focusses on the preferred part of the Pareto optimal set. Each new solution is obtained by minimizing an achievement scalarizing function including preferences about desired improvements in objective function values.

The decision maker has two possibilities to provide her/his preferences:

1. The decision maker can rank the objectives according to the relative importance of improving each current objective value.

Note

This ranking is not a global preference ranking of the objectives, but represents the local importance of improving each of the current objective values at that moment.

2. The decision maker can specify percentages reflecting how (s)he would like to improve the current objective values, by answering to the following question:

“Assuming you have one hundred points available, how would you distribute them among the current objective values so that the more points you allocate, the more improvement on the corresponding current objective value is desired?”

After each iteration round, the decision maker specifies whether (s)he wishes to continue with the previous preference information, or define a new one.

In addition to this, the decision maker can influence the solution finding process by taking a step back to previous iteration point. This enables the decision maker to provide new preferences and change the direction of solution seeking process. Furthermore, the decision maker can also take a half-step in case (s)he feels that a full step limits the reachable area of Pareto optimal set too much.

NAUTILUS is specially suitable for avoiding undesired anchoring effects, for example in negotiation support problems, or just as a means of finding an initial Pareto optimal solution for any interactive procedure.

Parameters:

problem (MOProblem) – Problem to be solved.
ideal (np.ndarray) – The ideal objective vector of the problem.
nadir (np.ndarray) – The nadir objective vector of the problem. This may also be the “worst” objective vector provided by the Decision maker if the approximation of Nadir vector is not applicable or if the Decision maker wishes to provide even worse objective vector than what the approximated Nadir vector is.
epsilon (float) – A small number used in calculating the utopian point.
objective_names (Optional[List[str]], optional) – Names of the objectives. List must match the number of columns in ideal.
minimize (Optional[List[int]], optional) – Multipliers for each objective. ‘-1’ indicates maximization and ‘1’ minimization. Defaults to all objective values being minimized.

Raises:

NautilusException – One or more dimension mismatches are encountered among the supplies arguments.

start() → NautilusInitialRequest[source]

Start the solution process with initializing the first request.

Returns:: Initial request.
Return type:: NautilusInitialRequest

iterate(request: NautilusInitialRequest | NautilusRequest | NautilusStopRequest) → NautilusRequest | NautilusStopRequest[source]

Perform the next logical iteration step based on the given request type.

Parameters:: request (Union[NautilusInitialRequest, NautilusRequest]) – Either initial or intermediate request.
Returns:: A new request with content depending on the Decision maker’s preferences.
Return type:: Union[NautilusRequest, NautilusStopRequest]

handle_initial_request(request: NautilusInitialRequest) → NautilusRequest[source]

Handles the initial request by parsing the response appropriately.

Parameters:: request (NautilusInitialRequest) – Initial request including Decision maker’s initial preferences.
Returns:: New request with updated solution process information.
Return type:: NautilusRequest

handle_request(request: NautilusRequest) → NautilusRequest | NautilusStopRequest[source]

Handle Decision maker’s requests after the first iteration round, so called intermediate requests.

Parameters:: request (NautilusRequest) – Intermediate request including Decision maker’s response.
Returns:: In case last iteration, request to stop the solution process. Otherwise, new request with updated solution process information.
Return type:: Union[NautilusRequest, NautilusStopRequest]

calculate_preferential_factors(pref_method: int, pref_info: numpy.ndarray, nadir: numpy.ndarray, utopian: numpy.ndarray) → numpy.ndarray[source]

Calculate preferential factors based on the Decision maker’s preference information. These preferential factors are used as weights for objectives when solving an Achievement scalarizing function. The Decision maker (DM) has two possibilities to provide her/his preferences:

1. The DM can rank the objectives according to the relative importance of improving each current objective value.

Note

This ranking is not a global preference ranking of the objectives, but represents the local importance of improving each of the current objective values at that moment.

2. The DM can specify percentages reflecting how (s)he would like to improve the current objective values, by answering to the following question:

“Assuming you have one hundred points available, how would you distribute them among the current objective values so that the more points you allocate, the more improvement on the corresponding current objective value is desired?”

Parameters:

pref_method (int) – Preference information method (either ranks (1) or percentages (2)).
pref_info (np.ndarray) – Preference information on how the DM wishes to improve the values of each objective function.
nadir (np.ndarray) – Nadir vector.
utopian (np.ndarray) – Utopian vector.

Returns:

Weights assigned to each of the objective functions in achievement scalarizing function.

Return type:

np.ndarray

Examples

>>> pref_method = 1  # ranks
>>> pref_info = np.array([2, 2, 1, 1])  # first and second objective are the most important to improve
>>> nadir = np.array([-4.75, -2.87, -0.32, 9.71])
>>> utopian = np.array([-6.34, -3.44, -7.5, 0.])
>>> calculate_preferential_factors(pref_method, pref_info, nadir, utopian)
array([0.31446541, 0.87719298, 0.13927577, 0.10298661])

>>> pref_method = 2  # percentages
>>> pref_info = np.array([10, 30, 40, 20])  # DM wishes to improve most the value of objective 3, then 2,4,1
>>> nadir = np.array([-4.75, -2.87, -0.32, 9.71])
>>> utopian = np.array([-6.34, -3.44, -7.5, 0.])
>>> calculate_preferential_factors(pref_method, pref_info, nadir, utopian)
array([6.28930818, 5.84795322, 0.34818942, 0.51493306])

solve_asf(ref_point: numpy.ndarray, x0: numpy.ndarray, preferential_factors: numpy.ndarray, nadir: numpy.ndarray, utopian: numpy.ndarray, objectives: Callable, variable_bounds: numpy.ndarray | None, method: desdeo_tools.solver.ScalarSolver.ScalarMethod | str | None) → dict[source]

Solve Achievement scalarizing function.

Parameters:

ref_point (np.ndarray) – Reference point.
x0 (np.ndarray) – Initial values for decision variables.
preferential_factors (np.ndarray) – preferential factors on how much would the decision maker wish to improve the values of each objective function.
nadir (np.ndarray) – Nadir vector.
utopian (np.ndarray) – Utopian vector.
objectives (np.ndarray) – The objective function values for each input vector.
variable_bounds (Optional[np.ndarray) – Lower and upper bounds of each variable as a 2D numpy array. If undefined variables, None instead.
method (Union[ScalarMethod, str, None) – The optimization method the scalarizer should be minimized with

Returns:

A dictionary with at least the following entries: ‘x’ indicating the optimal variables found, ‘fun’ the optimal value of the optimized function, and ‘success’ a boolean indicating whether the optimization was conducted successfully.

Return type:

Dict

calculate_iteration_point(itn: int, z_prev: numpy.ndarray, f_current: numpy.ndarray) → numpy.ndarray[source]

Calculate next iteration point towards the Pareto optimal solution.

Parameters:

itn (int) – Number of iterations left.
z_prev (np.ndarray) – Previous iteration point.
f_current (np.ndarray) – Current optimal objective vector.

Returns:

Next iteration point.

Return type:

np.ndarray

calculate_bounds(objectives: Callable, n_objectives: int, x0: numpy.ndarray, epsilons: numpy.ndarray, bounds: numpy.ndarray | None, constraints: Callable | None, method: desdeo_tools.solver.ScalarSolver.ScalarMethod | str | None) → numpy.ndarray[source]

Calculate the new bounds using Epsilon constraint method.

Parameters:

objectives (np.ndarray) – The objective function values for each input vector.
n_objectives (int) – Total number of objectives.
x0 (np.ndarray) – Initial values for decision variables.
epsilons (np.ndarray) – Previous iteration point.
bounds (Union[np.ndarray, None) – Bounds for decision variables.
constraints (Callable) – Constraints of the problem.
method (Union[ScalarMethod, str, None]) – The optimization method the scalarizer should be minimized with.

Returns:

New lower bounds for objective functions.

Return type:

new_lower_bounds (np.ndarray)

calculate_distance(z_current: numpy.ndarray, nadir: numpy.ndarray, f_current: numpy.ndarray) → numpy.ndarray[source]

Calculates the distance from current iteration point to the Pareto optimal set.

Parameters:

z_current (np.ndarray) – Current iteration point.
nadir (np.ndarray) – Nadir vector.
f_current (np.ndarray) – Current optimal objective vector.

Returns:

Distance to the Pareto optimal set.

Return type:

np.ndarray

desdeo_mcdm.interactive.Nautilus.f1(xs)[source]

desdeo_mcdm.interactive.Nautilus

Module Contents

Classes

Functions

`desdeo_mcdm.interactive.Nautilus`