Support for LP solvers

README.md

@@ -22,6 +22,19 @@ Next you can add choices, which the users will have to rate later on.
 After the rating period has finished, you can allocate the users automatically or manually. Upon publishing the results, users will be able to see which choice they have been allocated to.
 For more information please visit the [moodle wiki](https://docs.moodle.org/31/en/Ratingallocate).
 
+Configuration
+=============
+General
+---------
+You can configure ``mod/ratingallocate`` using moodles administration interface. Three different solvers are available for selection. For LP it is necessary to configure the way it will use the external LP solver by selecting an executor.
+
+
+Webservice backend
+------------
+Using the webservice executor mod_ratingallocate can use an external lp solver which is not on the same machine as the moodle instance.
+A working webserver with PHP is needed. Clone the mod_ratingallocate into the document root and take a look into ``webservice/config.php`` for configuring the executors backend. A strong secret and HTTPS are recommended.
+
+
 Moodle version
 ======================
 The plugin is continously tested with all moodle versions, which are security supported by the moodle headquarter.
@@ -30,8 +43,8 @@ In addition to all stable branches the version is also tested against the master
 
 Algorithm
 =========
-This module uses a modified Edmonds-karp algorithm to solve the minimum-cost flow problem. Augmenting paths are found using Bellman-Ford, but the user ratings are multiplied with -1 first.
-
-Worst-Case complexity is O(m^2n^2) with m,n being number of edges (#users+#choices+#ratings_users_gave) and nodes (2+#users+#choices) in the graph.
+Using the Edmonds-Karp algorithm the Worst-Case complexity is O(m^2n^2) with m,n being number of edges (#users+#choices+#ratings_users_gave) and nodes (2+#users+#choices) in the graph.
 Distributing 500 users to 21 choices takes around 11sec.
 
+Measurements for using the LP solver or Ford-Fulkerson are not available.
+

classes/local/group.php

@@ -0,0 +1,153 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace mod_ratingallocate\local;
+
+class group {
+
+    private $id = '';
+    private $limit = 0;
+    private $assigned_users = [];
+
+    /**
+     * Creates a new group
+     *
+     * @param $id Id of the group
+     * @param $limit Group limit
+     */
+    public function __construct($id, $limit = 0) {
+        $this->id = $id;
+        $this->set_limit($limit);
+    }
+
+    /**
+     * Returns the group id
+     *
+     * @return Id of the group
+     */
+    public function get_id() {
+        return $this->id;
+    }
+
+    /**
+     * Checks if the group has a limit (limit is zero)
+     *
+     * @return True if the group has a limit
+     */
+    public function has_limit() {
+        return $this->limit != 0;
+    }
+
+    /**
+     * Returns the group limit
+     *
+     * @return Group limit
+     */
+
+    public function get_limit() {
+        return $this->limit;
+    }
+
+    /**
+     * Checks if the group is empty
+     *
+     * @return True if the group is empty
+     */
+    public function is_empty() {
+        return empty($this->assigned_users);
+    }
+
+    /**
+     * Checks if the group is full (limit has been reached)
+     *
+     * @return True if the group is full
+     */
+    public function is_full() {
+        if($this->limit == 0)
+            return false;
+
+        return count($this->assigned_users) == $this->limit;
+    }
+
+    /**
+     * Sets the group limit (zero for no limit)
+     *
+     * @param $limit The new group limit
+     * @throws exception if the group limit is negative
+     */
+    public function set_limit($limit) {
+        if($limit < 0)
+            throw new \exception('Limit cannot be negative!');
+
+        $this->limit = $limit;
+    }
+
+    /**
+     * Returns an array of users which are assigned to the group
+     *
+     * @return Array of users which are assigned to the group
+     */
+    public function get_assigned_users() {
+        return $this->assigned_users;
+    }
+
+    /**
+     * Adds an assigned user to the group
+     *
+     * @param $user User that gets added to the group
+     *
+     * @throws exception if the group limit has been reached or the user has been already assigned to a group
+     */
+    public function add_assigned_user(&$user) {
+        if($this->exists_assigned_user($user))
+            return;
+
+        if($this->is_full())
+            throw new \exception('Limit has been reached!');
+
+        if($user->get_assigned_group() && $user->get_assigned_group() != $this)
+            throw new \exception('User has been already assigned to another group!');
+
+        $user->set_assigned_group($this);
+        $this->assigned_users[$user->get_id()] = $user;
+    }
+
+    /**
+     * Checks if user belongs to this group
+     *
+     * @param $user User that gets checked
+     *
+     * @return True if user belongs to this group
+     */
+    public function exists_assigned_user($user) {
+        return isset($this->assigned_users[$user->get_id()]);
+    }
+
+    /**
+     * Removes a user from the group
+     *
+     * @param $user User that gets removed from the group
+     *
+     * @throws exception If user was not assigned from the group
+     */
+    public function remove_assigned_user($user) {
+        if(!$this->exists_assigned_user($user))
+            throw new \exception('User has not been assigned to this group!');
+
+        unset($this->assigned_users[$user->get_id()]);
+    }
+
+}

classes/local/lp/engine.php

@@ -0,0 +1,39 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace mod_ratingallocate\local\lp;
+
+abstract class engine {
+
+    /**
+     * Reads the content of the stream and returns the variables and their optimized values
+     *
+     * @param $stream Output stream of the program that was executed
+     *
+     * @return Array of variables and their values
+     */
+    abstract public function read($stream);
+
+    /**
+     * Returns the command that gets executed
+     *
+     * @param $input_file Name of the input file
+     *
+     * @returns Command as a string
+     */
+    abstract public function get_command($input_file);
+
+};

classes/local/lp/engines/cplex.php

@@ -0,0 +1,55 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace mod_ratingallocate\local\lp\engines;
+
+class cplex extends \mod_ratingallocate\local\lp\engine {
+
+    /**
+     * Returns the command that gets executed
+     *
+     * @param $input_file Name of the input file
+     *
+     * @returns Command as a string
+     */
+    public function get_command($input_file) {
+        return "cplex -c \"read $input_file\" \"optimize\" \"display solution variables -\"";
+    }
+
+    /**
+     * Reads the content of the stream and returns the variables and their optimized values
+     *
+     * @param $stream Output stream of the program that was executed
+     *
+     * @return Array of variables and their values
+     */
+    public function read($stream) {
+        $content = stream_get_contents($stream);
+        $solution = [];
+
+        foreach(array_slice(explode("\n", substr($content, strpos($content, "Solution Value"))), 1) as $variable) {
+            $parts = explode(' ', preg_replace('!\s+!', ' ', $variable));
+
+            if(count($parts) < 2)
+                break;
+
+            $solution[$parts[0]] = intval($parts[1]);
+        }
+
+        return $solution;
+    }
+
+}

classes/local/lp/engines/scip.php

@@ -0,0 +1,55 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace mod_ratingallocate\local\lp\engines;
+
+class scip extends \mod_ratingallocate\local\lp\engine {
+
+    /**
+     * Returns the command that gets executed
+     *
+     * @param $input_file Name of the input file
+     *
+     * @returns Command as a string
+     */
+    public function get_command($input_file) {
+        return "scip -f $input_file";
+    }
+
+    /**
+     * Reads the content of the stream and returns the variables and their optimized values
+     *
+     * @param $stream Output stream of the program that was executed
+     *
+     * @return Array of variables and their values
+     */
+    public function read($stream) {
+        $content = stream_get_contents($stream);
+        $solution = [];
+
+        foreach(array_slice(explode("\n", substr($content, strpos($content, 'objective value:'))), 1) as $variable) {
+            $parts = explode(' ', preg_replace('!\s+!', ' ', $variable));
+
+            if(empty($parts[0]))
+                break;
+
+            $solution[$parts[0]] = $parts[1];
+        }
+
+        return $solution;
+    }
+
+}