This is a short guide to writing new functions for the MOEADr package. This package provides a component-based framework for developing (and applying) Multiobjective Evolutionary Algorithms based on Decomposition (MOEA/D)1.
The modular implementation provided in this package provides control over the following aspects of the algorithm:
This document describes how to write functions implementing new variants for any of these modules. A general description of the algorithm and the component-based interpretation behind the MOEADr package is available in our paper2
Functions should be preferably defined in the form verb_object (e.g., generate_weights or evaluate_population)
Please try to follow the policy one function, one file, same name (very short functions for general use can be exceptions - in this case they should be placed, e.g., in the utils.R file.
When passing variables between functions, there are three main rules that should be observed:
Unless absolutely impossible, functions should always receive all variables used in the function body via formal arguments, plus whatever other variables may be used downstream using the ... input.
If it is absolutely necessary, a function can eventually access variables from parent frames using, for instance, parent.frame()$variable_name, but this is not encouraged. It is definitely not kosher for functions to directly modify variables in the parent environment by any means except by formal, explicit outputs. Previous (development) versions of the MOEADr package used to allow it, but the resulting confusion (particularly when writing unit tests or debugging) heavily outweighted the benefits.
Functions should, with few exceptions, be able to handle any number of “useless” variables that may be passed to them (using the ... formal argument).
Documentation should be complete. Please use roxygen2-style documentation in all functions. This version of the package uses roxygen2 version 6.0.1 (which means some degree of markdown support and other conveniences).
Also, please make liberal use of in-code comments to clarify any non-trivial operation.
To discover the available decomposition strategies, use get_decomposition_methods(). Decomposition functions are called from within generate_weights().
?moead and ?decomposition_sld to get details on the structure of decomp). Any other required inputs should be explicitly declared in the function definition.decomp$name).get_decomposition_methods() won’t be able to correctly list the method).Check decomposition_sld.R for a good example of decomposition routine (e.g., to use as a template).
To discover the available decomposition strategies, use get_scalarization_methods(). Scalarization functions are called from within scalarize_values().
?moead and ?scalarization_pbi to get details on the structure of aggfun). Any other required inputs (e.g., W, Y, etc.) should be explicitly declared in the function definition.get_scalarization_methods() won’t be able to correctly list the method.Check scalarize_pbi.R for a good example of decomposition routine (e.g., to use as a template).
The strategy for defining the neighborhood structure in the MOEADr package is essentially the same (use Euclidean distances and use the neighbors$T nearest subproblems as a neighborhood). The only difference is the space in which the distances are calculated, which has implications in the need for re-calculating the neighborhood structure. The neighborhoods are defined using an efficient C implementation of the k-nearest-neighbors algorithm available in function FNN::get.knn, which is the only reason why package MOEADr lists FNN in its Imports field (see DESCRIPTION).
The neighborhood assignment function is define_neighborhood(), which is called directly from the main function moead().
?moead and ?define_neighborhood to get details on the structure of aggfun). Any other required inputs should be explicitly declared in the function definition.neighbors$T - 1 elements are the neighbor indices). This is a N x T matrix.1 / N.define_neighborhood. Other possibilities (e.g., to deal with adaptive weights, which would require periodic recalculation) can, at least in principle, use the same strategy. However, if an alternative assignment method becomes too different from the one currently implemented, it may be better to break the options and use the one function, one file, same name policy. In this case, the current options should be moved to independent functions starting with a common preffix (as is the case with other modules, e.g., decomposition).Check define_neighborhood.R for the current neighborhood assignment alternatives (e.g., to use as a template).
To discover the available variation operators, use get_variation_operators(). Variation methods are called from within perform_variation().
?moead and ?perform_variation to get details on the structure of variation). Any other required inputs should be explicitly declared in the function definition.X containing the (modified) points, or a list object containing the matrix X as well as a counter nfe, containing the number of additional function evaluations performed by that operator..variation_localsearch(). Local search methods should follow the naming convention ls_XYZ, and available methods are discovered using get_localsearch_methods(). See ?variation_localsearch and the Variation section of ?moead for details.get_variation_operators() and get_localsearch_methods() won’t be able to correctly list the method.Check variation_sbx.R for a good example of a non-local search variation operator, and variation_localsearch.R and ls_dvls.R for local search methods (e.g., to use as a template).
To discover the available decomposition strategies, use get_update_methods(). Update functions are called from within update_population().
?moead and ?update_population to get details on the structure of update). Any other required inputs should be explicitly declared in the function definition.get_update_methods() won’t be able to correctly list the method.Check update_standard.R for a good example of update routine (e.g., to use as a template).
To discover the available constraint handling strategies, use get_constraint_methods(). Constraint handling methods are called from within order_neighborhood().
?moead to get details on the structure of constraint). Any other required inputs should be explicitly declared in the function definition.get_constraint_methods() won’t be able to correctly list the method.Check constraint_penalty.R for a good example of constraint handling routine (e.g., to use as a template).
The strategies for objective scaling currently available in the MOEADr package are essentially “none” (i.e., no scaling) and “simple” (simple linear scaling to the interval [0,1]).The scaling function is scale_objectives().
?moead and ?scale_objectives to get details on the structure of scaling). Any other required inputs should be explicitly declared in the function definition.0s and a vector of 1s, if any scaling different from “none” is used).scale_objectives(). Other possibilities can, at least in principle, use the same strategy. However, if an alternative assignment method becomes too different from the one currently implemented, it may be better to break the options and use the one function, one file, same name policy. In this case, the current options should be moved to independent functions starting with a common preffix (as is the case with other modules, e.g., decomposition).To discover the available termination criteria, use get_stop_criteria(). Termination methods are called from within check_stop_criteria().
?moead and ?get_stop_criteria to get details on the structure of stopcrit). Any other required inputs should be explicitly declared in the function definition.TRUE) or not (FALSE).get_stop_criteria() won’t be able to correctly list the method.Check stop_maxiter.R for a good example of constraint handling routine (e.g., to use as a template).