This is Matlab/C++ implementation for minimizing balanced k-cut (unconstrained and transductive setting) using the method described in  
S. S. Rangapuram, P. K. Mudrakarta and M. Hein. 
Tight Continuous relaxation of the Balanced k-Cut Problem. NIPS 2014.
Cite the above paper if you are using this code.

Dependencies:
-------------
We use the following publicly available Normalized cut codes for computing starting points for our method:
(i) GraphDemos: http://www.ml.uni-saarland.de/code/GraphDemo/GraphDemo.htm
(ii) NCut9: http://www.timotheecour.com/software/ncut/ncut.html

These are already included here.

Install:
--------
Everything is setup for linux 64 bit machines.
For other systems, run these commands on Matlab command prompt:

1. setup.m % this will compile our code
2. cd Ncut9; compileDir_simple; % this will compile Ncut9 code; ignore the warnings as suggested in http://www.timotheecour.com/software/ncut/ncut.html

For any issue with Ncut9 code, please check the link: http://www.timotheecour.com/software/ncut/ncut.html
If there is any problem with eigenvector computation, then you have to uncomment (depending on your Matlab version) 
either the line 80 or line 81 and comment line 82 in the file ncut.m in the folder Ncut9.


Usage of code: 
--------------
Change to the folder balancedKCuts and run test.m to see if everything is installed properly.

The code can be used to solve a variety of balanced k-cut problems including
(i) Ratio/Normalized cuts, 
(ii) Ratio/Normalized Cheeger cuts and 
(iii) Asymmetric Ratio/Normalized Cheeger cuts 

By default our method solves asymmetric ratio Cheeger cut problem.

For more options/help, type at Matlab prompt: help balancedKCut.m

Clustering error is computed using majority voting (see the function: cluster_err_maj_voting.m)

Transducitve setting:
--------------------
When the label information is available use the function: transductiveBalancedKCut.m

For more options/help, type at Matlab prompt: help transductiveBalancedKCut.m

NOTE:
-----
We use the same procedure for generating the starting points as described in the paper,
X. Bresson, T. Laurent, D. Uminsky and J.H. von Brecht, "Multiclass Total Variation Clustering", NIPS 2013.
The contents of the file getDiffusedStart.m are taken from their code to generate these special starting points via the diffusion procedure.
Note that we do not use their solution as a starting point to our method and their code is not included here.

LICENSE:
--------
This program 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, version 3 of the License.

This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

If you use this code, please include a reference to the paper: 
S. S. Rangapuram, P. K. Mudrakarta and M. Hein. Tight Continuous relaxation of the Balanced k-Cut Problem. NIPS 2014.

(C)2014-15 Syama Sundar Rangapuram, Pramod Kaushik Mudrakarta and Matthias Hein
Machine Learning Group, Saarland University, Germany
http://www.ml.uni-saarland.de

CONTACT:
--------
For problems/suggestions/success stories contact:
Syama Sundar Rangapuram - srangapu@mpi-inf.mpg.de
