Mathematica Package TuGames.m Version 2.2
==============================
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 an upgrade
of the package TuGames version 1.1 from the URL
http://library.wolfram.com/infocenter/MathSource/5709/
which is now 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
A modified version of the package CooperativeGames that has been developed
by M.Carter to run properly with Mathematica 8.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. For Windows Operating Systems pre-build binaries are
available and are included in the subdirectory cddml. Binaries for MacOSX and
Linux-x86 can be found 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 disbrituted 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 form 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