JCSP (Java Cell Suppression Problem) Version 2.0

Copyright (C) 2014 Department for Statistical Studies of National Tax Agency, 
Madrid, Spain. All rights reserved.
E-mail: <diego.porrase@correo.aeat.es>,<felix.sazm@correo.aeat.es>,	<david.perezf@correo.aeat.es>

JCSP 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.

See the file COPYING for the GNU General Public License.

See the file INSTALL for compilation and installation instructions.


INTRODUCTION
JCSP is a Java program that solves the Cell Suppression Problem for tabular data.

JCSP is intended for solving large-scale tabular data confidentiality problem. 
It takes files in CSPlib format and generates a solution file, .sol.

JCSP uses GLPK (GNU Linear Programming Kit) as an embedded solver for LP and MIP optimization problems resolution.

See http://webpages.ull.es/users/jjsalaza/curriculum/articles/MS01csp.pdf for the integer model and algorithm used to solve CSP problems using branch-and-cut

See the file /doc/CSPIntegerModel_ES.pdf for a summary (in Spanish) of the previous article 


LIBRARIES
GLPK library is used to solve LP and MIP optimization problems.
http://www.gnu.org/software/glpk/ 

GLPK-Java is a Java Binding library that allows Java programs call to GLPK library functions 
http://glpk-java.sourceforge.net/
  

PROGRAM OPTIONS
The JCSP program has the following options:
		-h,-?						to show help
		-f <name>				to select an unique input file (*.ecu, *.csp)
		-i <name>				to select the input directory with input files (*.ecu, *.csp)
			If an input directory and an input file are selected, the file is ignored
		-t <count>				to select the time limit in seconds
		-o <name>				to select the output directory to write the output files (*.sol, *.heur)
		-e <name>				to select the error directory to write the error files
		-td <name>			to select the directory for input files that exceed time limit
		-ed <name>			to select not eliminate duplicate cells
		-fh <name>			to select an heuristic file
		-dh <name>			to select a directory with heuristic files
		-m <bc|cb|heur>		to select the resolution method
				bc: Branch & Cut
				cb: Cut & Branch
				heur: Heuristic used
		-l <name>				to select the log file
		-c <idCluster>		to execute multiprocess (idCluster=0 master idCluster>0 slaves)


INPUT FORMAT: CSPlib format (see doc/CSPlib_Format.txt)
There are two types of CSPlib formats: Non dimensional (recommended) and dimensional. 
Non dimensional format is not restricted in the number of dimensions used and the order of cells is irrelevant.
Dimensional CSPlib format is limited to 4 dimensions in JCSP. 


OUTPUT FORMAT
Output and heuristic files (*.sol, *.solN, *.heur) contain a solution of the problem included in the input file
	List of lines with the cells to be suppressed (i.e.  CellId=1.0)   and at the end of the file:
	Sum of values of the suppressed cells.
	Sum of weights of the suppressed cells.  
The *.sol files contain the optimal integer solution of the problem
The *.solN and *.heur contain an integer solution of the problem but not necessary the optimal one. 


CONFIGURATION FILES
mpi configuration file JCSP_HOME/lib/mpj/conf/local2.conf
	In order to execute in multiprocess mode	
	You must indicate the number of processors and for each processor the ip address, port (always a even number) and rank (idCluster) 
	Example:
			#<<---Number of hosts--->>
			3
			#<<---Limit of Protocol Switch --->>
			131072
			#<<---Processes--->>
			#IP/FULLY_QUALIFIED_HOSTNAME@PORT_NUM@RANK
			localhost@20000@0
			192.168.1.1@20002@1
			192.168.1.2@20004@2


The logger configuration file is log4j.xml
	Example:
			<?xml version="1.0" encoding="UTF-8"?>
			<configuration>
				<appenders>
				<Console name="Console" target="SYSTEM_OUT">
					<PatternLayout pattern="%d{HH:mm:ss}  %-5level %logger{36} - %msg%n"/>
				</Console>
				</appenders>
				<loggers>
					<!-- some levels "fatal", "error", "warn", "info","debug"-->
					<root level="error">
						<appender-ref ref="Console" />
					</root>
				</loggers>
			</configuration>


EXECUTING WITH ECLIPSE
Using windows
	You must define a new variable of environment called PATH with the value .\lib\w32
	You must add /lib/w32/glpk-java.jar to the classpath
Using linux
	You must define a new variable of environment called LD_LIBRARY_PATH with the value ./lib/linux64
	You must add /lib/linux64/glpk-java.jar to the classpath	 and eliminate /lib/w32/glpk-java.jar 


See JCSP webpage <http://administracionelectronica.gob.es/es/ctt/controlestadisti#>

Please report bugs to <diego.porrase@correo.aeat.es>,<felix.sazm@correo.aeat.es>,<david.perezf@correo.aeat.es>
