How to Contribute

This system is developed in Python programming language, using poetry as project and package manager, unittest library for unit testing and Sphinx system for documentation generation. Same tool set should be use for contribution to the project.

Contribution is encouraged in following four domains:

1. Designing novel optimization methods. Requirements:

   1. Algorithms should be derived from the specified class.

      • Class that implements metaheuristic optimization should be derived either from the uo.algorithm.metaheuristic.single_solution_metaheuristic.SingleSolutionMetaheuristic class, or from the uo.algorithm.metaheuristic.population_based_metaheuristic.PopulationBasedMetaheuristic. It should be placed into separate directory within /uo/algorithm/metaheuristic/ directory.

      • Class that implements exact optimization should be derived from the uo.algorithm.Algorithm class. That class should be placed into separate directory within /uo/algorithm/ directory.

   2. Type hints and documentation.

      • All programming objects (classes, functions, variables, parameters, optional parameters etc.) should be type-hinted

      • All programming objects (classes, functions, etc.) should be properly documented using the system Sphinx, reStructuredText and doc comments within the code.

      • Each of the implemented algorithm should have separate documentation web page, where that algorithm is described and documented. At least, there should be the link from doc comments within implemented functionality toward the web page that explains algorithm and vice versa.

   3. Unit testing coverage.

      • Implemented programming code should be fully covered with unit tests.

      • Here, unittest framework used.

      • Test should be placed into separate sub-directory under /uo/tests/ directory. Directory structure within /uo/tests/ directory should mirror directory structure of the /uo/ directory.

      • All developed code should be covered with unit test, and test coverage rate should be not less than 80%.

2. Building application for solving optimization problems. Requirements:

   1. Program code for specific problem should to be put into the respective directory.

      • Each of the problems should have its own directory, with name equals to problem name.

      • Code for multi-objective optimization should be placed under /opt/multi_objective/ directory, while code for single-objective optimization should be placed under /opt/single_objective/ directory.

      • Code for single-objective combinatorial optimization should be placed under opt/single_objective/comb/ directory, for single-objective constraint optimization within the /opt/single_objective/constraint/ directory, and code for single-objective global optimization in /opt/single_objective/global/ directory.

   2. Implemented applications should have examples of use for every approach contained within application.

      • Those examples should be placed in root / directory, and file name for example should be <problem>_<algorithm>_<representation>_exec.py.

   3. For each problem under consideration, the problem class for specific problem should have method that read textual file and create instance of that specific problem.

   4. For each problem under consideration, there should be one file (named solver.py, within the respective problem directory). That file will be entry point for all the methods aimed at solving the specific problem. All parameters that governs methods execution should be accessible to user through command-line parameters. Command-line parameters should have sufficient and adequate help system.

   5. Type hints and documentation.

      • All programming objects (classes, functions, variables, parameters, optional parameters etc.) should be type-hinted

      • All programming objects (classes, functions, etc.) should be properly documented using the system Sphinx, reStructuredText and doc comments within the code.

      • Problem that is solved should have separate documentation web page, where that problem is described and documented. At least, there should be the link from problem web page toward the web page that explains method that is used and vice versa.

   6. Unit testing coverage.

      • Implemented programming code should be fully covered with unit tests, and unittest framework is used.

      • Test should be placed into separate sub-directory under /opt/tests/ directory. Directory structure within /opt/tests/ directory should mirror directory structure of the /opt/ directory.

      • All developed code should be covered with unit test, and test coverage rate should be not less than 80%.

3. Designing and executing comparison experiments, using previously builded applications. Requirements:

   1. Experiments should use only previously developed applications, not Python programming constructs. Comparison experiments should be invoked by batch/command file.

   2. Comparison experiments should be placed under /comparison/ directory.

4. Visualizing experimentally obtained data (either data about comparison, either data about algorithm execution). Requirements:

   1. Developed solution for the problems under consideration should be visualized. Visualizations should be invoked by batch/command file.

   2. Visualization efforts should be placed under /visualization/ directory.

Contributors

Contribution domains

1. Contribution in the designing novel optimization methods:

   a.1. Library and application:

   1. Initial overall structure and organization - [VladimirFilipovic]

   a.2. Total Enumeration (TE) exact algorithm:

   2. Structure, organization and main loop implementation - [VladimirFilipovic]

   3. Implementation with bit-array based complex counters (class ComplexCounterBitArrayFull, using bitstring.BitArray class) - [VladimirFilipovic]

   4. Implementation with int based complex counters (classes ComplexCounterUniformFull and ComplexCounterUniformAscending, using int values) - [VladimirFilipovic]

   a.3. Variable Neighborhood Search Variable Neighborhood Search (VNS) metaheuristics:

   5. Structure, organization and main loop implementation - [VladimirFilipovic]

   6. Implementation of shaking and local searches with binary representation (in class VnsShakingSupportStandardInt, using int predefined type) - [VladimirFilipovic]

   7. Implementation of shaking and local searches with binary representation (in class VnsShakingSupportStandardBitArray,using bitstring.BitArray class) - [VladimirFilipovic]

   a.4. Genetic Algorithms Genetic Algorithm (GA) metaheuristics:

   8. Structure, organization and main loop implementation - [MarkoRadosavljevic], [VladimirFilipovic]

   9. Making class uo.algorithm.metaheuristic.genetic_algorithm.GaOptimizer to be abstract and dividing its functionality into non-abstract classes uo.algorithm.metaheuristic.genetic_algorithm.GaOptimizerGenerational and uo.algorithm.metaheuristic.genetic_algorithm.GaOptimizerSteadyState - [VladimirFilipovic]

   10. Implementation of GA selection methods (in classes: GaSelectionIdle, GaSelectionRoulette) - [MarkoRadosavljevic]

   11. Implementation of GA crossover one point method (contained within class: GaCrossoverSupportOnePointBitArray), with binary representation (using bitstring.BitArray class) - [MarkoRadosavljevic]

   12. Implementation of GA mutation one point method (contained within class: GaMutationSupportOnePointBitArray), with binary representation (using bitstring.BitArray class) - [MarkoRadosavljevic]

   a.4. Electromagnetism-like Algorithm_Electromagnetism_Like_Metaheuristic (EM) metaheuristics:

   13. Structure, organization and main loop implementation - [AndjelaDamnjanovic]

2. Contribution in solving combinatorial optimization problems:

   b.1. Ones Count Max Problem Ones Count Max Problem:

   1. Representation of the problem (in class MaxOnesCountProblem) and solution (BitArray-based in class MaxOnesCountProblemBitArraySolution and int-based in class MaxOnesCountProblemIntSolution) - [VladimirFilipovic]

   2. Integer Linear Programming method (using linopy library) - [VladimirFilipovic]

   3. Total Enumeration method, with solution that has binary BitArray representation - [VladimirFilipovic]

   4. Variable Neighborhood Search method, with solution that has binary BitArray representation - [VladimirFilipovic]

   5. Variable Neighborhood Search method, with solution that has binary int representation - [VladimirFilipovic]

   6. Genetic Algorithm method, with solution that has binary BitArray representation - [VladimirFilipovic]

   7. Entry point of the all methods for solving this problem, in file /opt/single_objective/comb/ones_count_max_problem/solver.py. All parameters that governs method execution are accessible to user through command-line. - [VladimirFilipovic]

   b.2. Minimum Multi Cut Problem Minimum Multi Cut Problem:

   8. Representation of the problem (in class MinMultiCutProblem, that uses ng.Graph class for class representation) and solution with BitArray-based representation (in class MinMultiCutProblemBitArraySolution) - [MarkoRadosavljevic]

   9. Variable Neighborhood Search method, with solution that has binary BitArray representation - [MarkoRadosavljevic]

   10. Genetic Algorithm method, with solution that has binary BitArray representation - [MarkoRadosavljevic]

   b.3. Set Covering Problem Minimum Set Cover Problem:

   11. Representation of the problem (in class MinSetCoverProblem`and solution with `BitArray-based representation (in class MinSetCoverProblemBitArraySolution) - [AndjelaDamnjanovic]

   12. Electromagnetism-like Metaheuristic method, with solution that has binary BitArray representation - [AndjelaDamnjanovic]

   13. ILP model, with linopy library and Gurobi solver - [AndjelaDamnjanovic]

3. Contribution in solving global optimization problems:

   c.1. Max Function One Variable Problem:

   1. Variable Neighborhood Search method, with solution that has binary BitArray representation - [VladimirFilipovic]

   2. Variable Neighborhood Search method, with solution that has binary int representation - [VladimirFilipovic]

   3. Entry point of the all methods for solving this problem, in file /opt/single_objective/glob/max_function_one_variable_problem/solver.py. All parameters that governs method execution are accessible to user through command-line. - [VladimirFilipovic]

Contributor List

[VladimirFilipovic] (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)

Vladimir Filipović, https://github.com/vladofilipovic e-mail: vladofilipovic@hotmail.com

[MarkoRadosavljevic] (1,2,3,4,5,6,7)

Marko Radosavljević, https://github.com/Markic01 e-mail: mi20079@alas.matf.bg.ac.rs

[AndjelaDamnjanovic] (1,2,3,4)

Anđela Damjanović, https://github.com/AndjelaDamnjanovic e-mail: mi19059@alas.matf.bg.ac.rs