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