Mathematica Package TuGames.m Version 2.4
==============================
Contents:
 1. Introduction
 2. Installation
 2.1 Unix
 2.2 Windows
 2.3 MacOSX
 2.4 Trouble Shooting
 3. Getting Started
 4. Running the Package in Parallel
 4.1 General Procedure
 4.2 Running the cddmathlink libraries in Parallel
 5. MATLink and MATtug (Matlab toolbox MatTuGames)
 6. Documentation
 7. General Remarks
 8. Graphics

1. Introduction
===============

TuGames is a Mathematica package to determine and to check some 
game properties of transferable utility games. It provides more 
than 100 different functions to calculate, for instance, (pre-)kernel 
elements, the (pre-)nucleolus, the Shapley value, excess payoffs, the 
tau-value, the vertices of a core, and much more. Moreover, it verifies 
if the game is convex, average-convex or superadditive just to mention 
some interesting game properties. It can be used in serial as well as in 
parallel mode, and in conjunction with MATLink to build up a Matlab 
connection to invoke the toolbox MatTuGames. This package is exclusively 
dedicated to Mathematica version 8.x and higher. In this respect, the graphical 
features should run on all platforms. As a highlight, a new and fast algorithm 
to seek for a pre-kernel element is implemented in the updated package. This 
algorithm is described in the book

The Pre-Kernel as a Tractable Solution for Cooperative Games
An Exercise in Algorithmic Game Theory
Series: Theory and Decision Library C, Vol. 45
Meinhardt, Holger Ingmar
2014, XXXIII, 242 p. 8 illus., 4 illus. in color
http://www.springer.com/economics/game+theory/book/978-3-642-39548-2   

Moreover, we have included a new package called ParaTuGames to literally run the 
major commands of TuGames in parallel. Notice that this package has not passed
its stage of development. Hence, the user should use it with care and for testing
only. This package must be located in the same folder as the TuGames file.
In addition, note that these functions/interfaces had to be provided in a Global context 
to call the parallel commands of Mathematica within a package. This design requires 
that during a running session with ParaTuGames no other variables of Global context
should be defined to avoid name conflicts and wrong results. Though use only the 
commands that start with the prefix Para, and which returns a description of how to 
use it. To get an idea of its usage, see the notebook file ParaExpGameP12b.nb in
the Documentation folder. Finally, this package does not require the configuration 
procedure as under section 4.

A modified version of the package CooperativeGames that has been developed 
by M.Carter to run properly with Mathematica 10.x and higher is enclosed. 
It must be mentioned in this place that some commands of TuGames require 
routines that have been provided by the package CooperativeGames. Therefore, 
you have also to install the package CooperativeGames to use the new functions 
properly. A description of the package CooperativeGames can be found in 

Hal R. Varian, Economic and Financial Modeling with Mathematica, 
Telos  Springer Publisher,1993, Chapter 8. 

Furthermore, if one is interested in computing the vertices of a core 
the Mathematica package VertexEnum written by K. Fukuda and I. Mizukoshi 
must also be installed on the computer. But note that this function is very 
slow in computing all vertices of a core even for modern computers. You can 
overcome these shortcomings of VertexEnum by installing the C-library 
cddmathlink written by the same authors to perform the same computational task 
more efficiently. It can be found under 

http://www.inf.ethz.ch/personal/fukudak/cdd_home/ 

for various UNIX, MacOSX and for Window systems. The library is linked via MathLink 
with the Mathematica Kernel. Under Linux and Mathematica 10 we complied successfully
the binaries using the following compiler flags

MLFLAGS = -lML64i4 -lpthread -lrt -luuid -ldl  

See also my post at 

http://mathematica.stackexchange.com/questions/59660/any-packages-for-vertex-enumeration-on-mathematica

to overcome possible pitfalls, which might occur during a compilation of the 
Cddmathlink binaries.

For Windows and MacOSX Operating Systems pre-build binaries are   
available under 

ftp://ftp.ifor.math.ethz.ch/pub/fukuda/cdd/cddlibml_binary/

This C-library is required to use the graphical features of the package.
Notice that the functions that based on this library are activated. To deactivate them 
uncomment the corresponding lines in the TuGames.m file. Moreover, you have to adjust 
the $Path variable where the library can be found. The default value is set to 
"/usr/local/bin" for UNIX systems. For changing this value edit the file TUGames.m with 
an editor of your choice and search for SetDirectory[]. 

The author has tested the functions extensively under LINUX x86/64, HP-UX and AIX. 
Furthermore, the package was also be installed and tested successfully under Windows XP 
and MacOSX. For more recent Windows OS the author has no experience.  But the 
programming language of Mathematica is system independent, thus, there should no problems 
occur on these operating systems to run the basic functions of the package. 

2. Installation
===============
2.1 Unix
========

1. Create  a directory "TuGames" in your 
$HOME/.Mathematica/AddOns/Applications directory. 

2. Copy now all files in the directory "TuGames". 

2.1 Create for the file CooperativeGames.m a 
subdirectory "coop" in TuGames and move the file in this subdirectory.

2.2 Create for the file VertexEnum.m  a 
subdirectory "vertex" in TuGames and move the file in this subdirectory.

3. Create the variable $TuGamesPath in the init.m file in your 
$HOME/.Mathematica/Kernel directory. If no init.m file exists, 
create the file. Set this variable to

$TuGamesPath = $HomeDirectory<>".Mathematica/AddOns/Applications/TuGames"

4. Add to the global variable $Path in the init.m file the location of TuGames by
AppendTo[$Path, $TuGamesPath]

Now you can start TuGames.

Note that for UNIX/LINUX systems is also a graphical extension
available. See also the remark at the end of this README file.


2.2 Windows
===========

1. Create the directory "AddOns\\Applications\\TuGames" 
at the location where your Mathematica files are located.  
This can be find out by typing

$TopDirectory

in your Mathematica Notebook. 

2.1 Copy now all files in this directory. Create for the file 
CooperativeGames.m the subdirectory "coop" and move the file in 
this directory.

2.2 Create for the file VertexEnum.m the subdirectory "vertex" 
and move the file in this directory.

2.3 Create for the library cddml_w32new the subdirectory "cddml" 
and move the file in this directory.

3. Create in your init.m file the variable $TuGamesPath to locate 
the various packages. See the example file in the directory mamakernel.
Set this variable to 

$TuGamesPath = $TopDirectory<>"\\AddOns\\Applications\\TuGames"

Note that the double backslash is important. A simple backslash
is not sufficient to set the directory path correctly.
The above procedure is the recommended way to set the path. 
But in cases that you have trouble with your init.m file set the 
path variable in your sysinit.m file. The sysinit.m file can be found 

$TOPDirectory\\SystemFiles\\Kernel\\SystemResources\\Windows

Make a copy of your original sysinit.m file and open an editor 
like winedit or winshell to search in the sysinit.m 
file for 

====================================
/* sysinit.m code portion starts */
====================================

Begin[ "Global`"];
(*
  We need to find init.m on the path before adding Configuration/Kernel.
*)
 
System`Private`tmp = System`Private`FindFile[ "init.m"]
 
AppendTo[ $Path, ToFileName[ {$TopDirectory, "Configuration"},"Kernel"]]

=================================
/* sysinit.m code portion ends */
=================================

and change it to 

======================================
/* changes in sysinit.m file starts */
======================================

Begin[ "Global`"];
 
(*
  We need to find init.m on the path before adding Configuration/Kernel.
*)
 
System`Private`tmp = System`Private`FindFile[ "init.m"]
 
AppendTo[ $Path, ToFileName[ {$TopDirectory, "Configuration"},"Kernel"]]
$TuGamesPath = ToFileName[ {$TopDirectory, "AddOns", "Applications"}, "TuGames"]
AppendTo[$Path, $TuGamesPath]

====================================
/* changes in sysinit.m file ends */
====================================

4. Add to the variable $Path in the init.m file the location of TuGames
AppendTo[$Path, $TuGamesPath]


Now you can start TuGames.

2.3 MacOSX
==========

Follow the instructions given in the UNIX section.


2.4 Trouble Shooting
====================

For setting correctly the PATH variables, see 

README_PATH.txt

In case that you get error messages like 

Needs["coop`CooperativeGames`"]

Get::noopen : Cannot open coop`CooperativeGames` .>>
Needs::nocont: Context coop`CooperativeGames` was not created when Needs[] was evaluated. >>

indicates that Mathematica was not able to create the Context related to the
package CooperativeGames. This message is caused by the fact that the file
CooperativeGames.m is not located in the subfolder coop. In order get rid from 
these error messages, the simplest way it to create a folder coop and move the 
file in this subdirectory. There is also the possibility to leave the file in the
current directory, but then one has to change the following entry in the file 
CooperativeGames.m from

BeginPackage["coop`CooperativeGames`"]

to

BeginPackage["CooperativeGames`"].


3. Getting Started
==================

In the next step we assume that you have installed properly the 
files mentioned above on your computer. To start with the calculation, 
we have first to load some packages. This can be done by the 
following commands. 

Needs["coop`CooperativeGames`"]
Needs["TuGames`"]

and optional 
Needs["TuGamesAux`"]; to call some auxiliaries commands.
Needs["vertex`VertexEnum`"] to invoke some additional commands to analyze the core.
or
Needs["VertexEnum`"]
it depends where you have installed VertexEnum.m.

It is obligatory to keep the above order of loading the packages. Don't load the
package TuGames` before coop`CooperativeGames` is loaded.  


4. Running the Package in Parallel
=================================
4.1 General Procedure
=====================

In order to run the TuGame package in parallel, we recommend to put at least in the Kernel 
init.m file a new variable called $ParaMode while setting its value to "False". For doing so, open 
the init.m  file under "~/.Mathematica/Kernel" by your favorite editor. Then copy the variable 
below with its value at the end of your Kernel init.m file, that is,

# init.m 
$ParaMode="False";
 
Now open a notebook to start a Mathematica session. In order to run a session in parallel 
at the least the following commands must be invoked from your notebook:

LaunchKernels[]; or LaunchKernels[8]; or any other number reflecting the number of cores you can address. 
$KernelCount
Needs["coop`CooperativeGames`"];
Needs["TuGames`"];
Needs["TuGamesAux`"];
$ParaMode="True";
ParallelNeeds["coop`CooperativeGames`"];
ParallelNeeds["TuGames`"];
ParallelNeeds["TuGamesAux`"];

To be sure that everything is distributed correctly, we distribute the definitions of the packages 
to all SubKernels.

DistributeDefinitions["coop`CooperativeGames`*"];

Then define your game using Set[] rather than SetDelayed[], let us say ExpGame, and invoke in addition:

SetSharedVariable[ExpGame];

Moreover, if some of the Mathematica packages which are used by TuGames are located on a different
folder, you probably have to invoke in addition

LaunchKernels[];
....
....
ParallelEvaluate[AppendTo[$Path,"/Path/to/the/required/Packages"]];
ParallelNeeds["coop`CooperativeGames`"];
ParallelNeeds["TuGames`"];
....
....

For more information have also a look on the notebook file TuGamesParallel.nb in 
the Documentation directory. 


4.2 Running the cddmathlink libraries in Parallel
======================================

If you plan to run even the cddmathlink libraries in parallel, you have to set an additional variable
to the already set variable $ParaMode in the Kernel init.m file. For doing so, open again the init.m 
file under "~/.Mathematica/Kernel" by an editor. Then copy the variable $NotebookMode below with its 
assigned value at the end of your Kernel init.m file, that is,

# init.m 
$ParaMode="False";
$NotebookMode="True";

Here, we assumed that most people want to use the parallel mode within a notebook. In case that you
mostly use Mathematica from the command line or even on a compute node, then set the value of
the variable $NotebookMode to "False".

In the second step open now a notebook and put to the above commands under 4.1 the additional commands 
in between, hence

LaunchKernels[];
.....
.....
Needs["TuGames`"];
ParallelNeeds[$ParaMode="True"];
ParallelNeeds[$NotebookMode="True"];
ParallelNeeds["coop`CooperativeGames`"];
ParallelNeeds["TuGames`"]; 
.....
.....
SetSharedVariable[YourDefinedGame];

In case that you intend to run cddmathlink libraries in parallel on a compute node or from the command
line, then you have to put into your input file the following commands:

LaunchKernels[];
.....
.....
Needs["TuGames`"] ;
ParallelNeeds[$ParaMode="True"];
ParallelNeeds[$NotebookMode="False"];
ParallelNeeds["coop`CooperativeGames`"];
ParallelNeeds["TuGames`"];
.....
.....     
SetSharedVariable[YourDefinedGame];

If you encounter problems with the cddmathlink libraries in parallel, then the following site might also be helpful

http://mathematica.stackexchange.com/questions/25561/how-to-run-an-external-program-in-parallel-with-a-mathematica-package/25818#25818

As an example see also the notebook file TuGamesMovieParaModeV6.nb.



5. MATLink and MATtug 
=====================

If you want to use MATtug that launches MATLink 

http://matlink.org

to open a Matlab connection within Mathematica in order to be able 
to use the Matlab toolbox MatTuGames available under

http://www.mathworks.de/matlabcentral/fileexchange/35933-mattugames

then copy the file MATtug.m into the folder where the TuGames.m
file is located. 

6. Documentation
================

See the notebook files in the 

Documentation/English/

folder. Graphical demonstration files in cdf format can be found in the
Demonstration folder.


7. General Remarks
==================

You may modify your copy or copies of the Package or any portion
of it. To let profit other users from your modifications forward 
these as well as any bug reports to the address mentioned below. 
By forwarding your modifications please keep the convention to list 
first the old code portion and then the part you have modified 
with a brief explanation. 

8. Graphics
===========
There are also some graphical capabilities available, which should work
under all platforms whenever the cddmathlink libraries are installed.
Features are for instance: plotting the core and strong epsilon core 
skeleton together with the nucleolus, kernel and Shapley value 
up to four players.  


Address:
=======
Holger I. Meinhardt
Institute of Operations Research
University of Karlsruhe (KIT) 
E-mail: Holger.Meinhardt@wiwi.uni-karlsruhe.de
