{
    "info": {
        "author": "Tom Pike",
        "author_email": "tpike3@gmu.edu",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 2 - Pre-Alpha",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: MIT License",
            "Natural Language :: English",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3 :: Only",
            "Topic :: Scientific/Engineering",
            "Topic :: Scientific/Engineering :: Artificial Intelligence",
            "Topic :: Scientific/Engineering :: Artificial Life"
        ],
        "description": "# Bilateral Shapley\nCreates a package of the bilateral shapley value from coalition game theory. Package is typically used with MESA, python's agent based model package (MESA 0.8.3 or greater).\n\n## What is the Bilateral Shapley Value?\n\nThe Shapley value is a key part of coalition game theory and was developed by Lloyd Shapley (https://en.wikipedia.org/wiki/Lloyd_Shapley). The central question of coalition game theory is the division of payoffs to the coalition of agents [Shoham and Leyton-Brown, 2009]. In other words, when we work together to get some payoff, how do we split up the payoff? The Shapley Value splits by marginal contribution, so the payoff is divided up by each agents relative contribution. This particular instantiation of the Shapley value borrows from two agent based implementations. First, Steven Ketchpel description \"Coalition Formation Among Autonomous Agents\" [1995] and second Mark Abdollahian, Zining Yang and Hal Nelson's implementation in \"Techno-Social Energy Infrastructure Siting: Sustainable Energy Modeling Programming (SEMPro)\" [2013]. A more detailed description of how specifically the module runs can be found below the implementation description. \n\n## Uses\n\nTo assess how different agents may coalesce into groups. \n\n## Requirements\n\nThe Bilateral Shapley module requires networkx 2.0 or greater \n\n## Installation \n\n    pip install bilateralshapley\nor\n    pip install git+https://github.com/tpike3/bilateralshapley.git \n\n## Implementation\n\n    from bilateralshapley import BSV\n\n    coalition = BSV(agents, power_attribute, preference_attribute, \n                efficiency_parameter, agent_id, compromise_parameter, verbose)\n\n    # Show a list of how agents group together\n    print (coalition.result)\n\n    # Show a list of how agents grouped together and each groups power and preference attribute\n    print (coalition.result_verbose)\n\n    # Show a dictionary of each group, the agents within that group\n    # and each agents updated power and preference value based on their assimilation into the group\n    print (coalition.subresults)\n\n## Required Parameters \n\n**agents:** requires list of agent objects; \"self.schedule.agents\" from mesa is an easy choice \n\n**power_attribute:** requires string; agent attribute which assigns a numerical value of each agents relative power\n\n**preference_attribute:** requires string; agent attribute which assigns a numerical preference on a one-dimensional spectrum of each agents relative preference\n\n## Default Parameters \n\n**efficiency_parameter:**  default = 1.5, requires float\n\ninteresting coalition formations typically fall between > 1.0 and < 2.0. 1.0 or less results in no incentive to join a coalition (i.e. no coalitions) and usually more than 2.0 results in everyone joining the same coalition\n\n**agent_id:**  default = \"unique_id\", requires string\n\nuses mesa unique_id attribute as default, module treats this value as a string\n\n**compromise_parameter:** default = 0.95, requires float between 0 and 1\n\nat 1.0 when agents join a coalition their preference will become that of the coalitions; at 0.0 the agents will not alter their preference\n\n**verbose:**  default = True, True or False input\n\nif True module will print out progress of algorithm showing how many iterations were required until optimal group formation\n\n## Example Implementation\n\n    from mesa import Model\n    from mesa.time import RandomActivation\n    from mesa import Agent\n    from bilateralshapley import BSV\n    import numpy as np\n\n\n    class TestAgent(Agent):\n        '''Initialize agents with values for power and preference (in this case affinity as preference)'''\n        def __init__(self, unique_id, model, maxaffinity, maxeconomic, maxmilitary):\n            # use Mesa agent module\n            super().__init__(unique_id, model)\n            # preference attribute of each agent\n            self.affinity = np.random.uniform(1, maxaffinity)\n            # economic value of each agent which is combined with military for power\n            self.economic = np.random.uniform(1,maxeconomic)\n            # military value of each agent which is combined with economic for power\n            self.military = np.random.uniform(1,maxmilitary)\n            # calculate power as average economic and military power\n            self.power = (self.economic+self.military) / 2\n\n\n    class TestModel(Model):\n        '''Initialize model'''\n        def __init__(self, N, maxaffinity, maxeconomic, maxmilitary):\n            self.numagents = N\n            self.schedule = RandomActivation(self)\n            for i in range(self.numagents):\n                a = TestAgent(i, self, maxaffinity, maxeconomic, maxmilitary)\n                self.schedule.add(a)\n\n\n        '''Call the bsv module'''        \n        def execution(self):\n            testnet = BSV(self.schedule.agents, \"power\", \"affinity\", verbose = False)\n            return testnet    \n\n\n    test = TestModel(500, 20, 100, 100)\n    test = test.execution()\n    print (\"Numer of Groups: \", len(test.result))\n    print (\"Group list: \", test.result)\n\n\n## Detailed Description of Module\n\n\n**Description**\nThis implementation of the Bilateral Shapley Value has three methods. \n\n**Method 1: self.assess_coalitions(self.net)**\n\nEach agent computes the Shapley value with every other agent (see flow diagram) and creates a sorted list of the most preferred alliances  \n\n**Method 2: self.make_alliance(self.net, 'one')**\n\nEach agent tries to form a coalition with the most preferred agent in its sorted list of preferred coalitions. The combinations can get tricky as each agent may want to form a coalition with one agent. For example, in a list of 3 agent objects, Agent 1 and 2's most preferred agent may be agent 3. Whichever agent, agent 3 prefers the most will be the two who form a coalition. If they are all equal then the coalition will form based on the the order determined by the python sort function. As the function will iterate until no more alliance can be formed, the specific order becomes inconsequential if every agent has the same value. The one input indicates the algorithm is performing at the group level and not inside the groups. \n\n**Method 3: self.new_node(self.net)**\n\nOnce each agent has found their preferred coalition they then form a new node in the network graph with a new name, which is each agent's identifier separated by a \".\" (e.g. agent1.agent2). The coalition preference and power is calculated and a new graph which retains the information of each individual agent is created and stored in the sub results. \n\n**Breaking alliances**\n\nAfter the coalition has been optimized, the module will go through each subgraph (agents within the coalition) and make sure each agent still wants to be a part of the coalition based on the coalition's preference and power relative to the individual agent's preference and power. If the agent no longer wants to participate then the agent leaves the coalition.   \n\n**Module Flow Diagram**\n\n![bilateralshapleyflow](https://user-images.githubusercontent.com/22775448/35524085-d16ba7cc-04f6-11e8-801b-32569ec3594c.jpg)\n\n\n## Weaknesses and Choices\n\nAs cooperative game theory examines combinations, increased agents increases computation time exponentially. Therefore, this module can not efficiently handle thousands of agents. \n\nIn order to reduce the computational burden and prevent the possibility of an infinite loop the module makes the choice for agents only to reexamine their alliances after the optimal coalition has been formed. As opposed to reexamining if an agent should be stay after each iteration of bilateral coalition formation. If the user wants the agents to reexamine their participation in the coalition after each iteration they can do this by simply tabbing lines #403 to #408 to be inside the primary loop. \n\n\n## Happy Modeling!\n\n\n[2013] Abdollahian, Mark, Yang Zinig, and Hal Nelson. 2013. \u201cTechno-Social Energy Infrastructure Siting\u202f: Sustainable Energy Modeling Programming ( SEMPro ).\u201d Journal of Artifical Socieities and Simulation 16 (3): 1\u201312.\n\n[1995] Ketchpel, S P. 1995. \u201cCoalition Formation among Autonomous Agents.\u201d From Reaction to Cognition, no. 957: 73\u201388.\n\n[Shoham and Leyton-Brown, 2009] Yoav, Shoham, and Kevin Leyton-Brown. 2009. Multiagent Systems: Algorithmic, Game-Theoretic, and Logical Foundations. Kindle. New York: Cambridge University Press.\n\n\n\n\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/tpike3/bilateralshapley",
        "keywords": "agent based modeling model ABM simulation multi-agent coaltion game theory",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "bilateralshapley",
        "package_url": "https://pypi.org/project/bilateralshapley/",
        "platform": "",
        "project_url": "https://pypi.org/project/bilateralshapley/",
        "project_urls": {
            "Homepage": "https://github.com/tpike3/bilateralshapley"
        },
        "release_url": "https://pypi.org/project/bilateralshapley/0.0.3/",
        "requires_dist": [
            "networkx"
        ],
        "requires_python": "",
        "summary": "Employs Bilateral Shapley Value from coalition game theory as a tool to assess agent coalition formation",
        "version": "0.0.3"
    },
    "last_serial": 4705252,
    "releases": {
        "0.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cfb69d4d59dae970c7ba3f65bd45b918",
                    "sha256": "781cbe3abfe4cd5775ce6c592e362f89157ad3b1f8b9e95ecc70dd4ecb275eae"
                },
                "downloads": -1,
                "filename": "bilateralshapley-0.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "cfb69d4d59dae970c7ba3f65bd45b918",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 6300,
                "upload_time": "2019-01-06T12:29:09",
                "url": "https://files.pythonhosted.org/packages/48/e9/8ab14bcd9f96776f60aef6498ac061dcb49f45076824dc7af7dfb9ab7eb8/bilateralshapley-0.0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "4f1c88caa2416ac96d4145ff59ac2994",
                    "sha256": "27dd9d542daa2abe1befac5ad73619a2ea7ed28349e41fd59e96583305920b69"
                },
                "downloads": -1,
                "filename": "bilateralshapley-0.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "4f1c88caa2416ac96d4145ff59ac2994",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 5719,
                "upload_time": "2019-01-06T12:29:11",
                "url": "https://files.pythonhosted.org/packages/69/ab/60ed3bd3e227645776296940f4630941b734c9726d27fe8fd7779b0b0fed/bilateralshapley-0.0.1.tar.gz"
            }
        ],
        "0.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "7999e124c8b8e8f893a48ef58569667a",
                    "sha256": "20199c2f20eb5682bbd3160f89e6eab8feb080ec6fb762da549d74520fd8793c"
                },
                "downloads": -1,
                "filename": "bilateralshapley-0.0.2-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "7999e124c8b8e8f893a48ef58569667a",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 10173,
                "upload_time": "2019-01-06T21:53:40",
                "url": "https://files.pythonhosted.org/packages/33/8f/1a88e5b17d9bc605d33dbeadf812661faf862a804770bbea99fb7e03d872/bilateralshapley-0.0.2-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "b26c9e29dcc57c756a2be7416896dfa2",
                    "sha256": "f34f67d3db88efa0130a751199e54ede630be5504acf56d576aedbb791bf420e"
                },
                "downloads": -1,
                "filename": "bilateralshapley-0.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "b26c9e29dcc57c756a2be7416896dfa2",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9416,
                "upload_time": "2019-01-06T21:53:41",
                "url": "https://files.pythonhosted.org/packages/a7/f3/e85cb311444d9b3b0cce8da05987be488e13a230506a0a26ab039da0a3f5/bilateralshapley-0.0.2.tar.gz"
            }
        ],
        "0.0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "611aa6b5b64a1f891337ffe7053074e4",
                    "sha256": "4b93b82853eea73b99d3e267c63ad791371d695f3d3a42eff834e982feb8a0be"
                },
                "downloads": -1,
                "filename": "bilateralshapley-0.0.3-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "611aa6b5b64a1f891337ffe7053074e4",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 10299,
                "upload_time": "2019-01-16T21:37:45",
                "url": "https://files.pythonhosted.org/packages/b7/65/7949b31acde3cb6c413c4afd83cb06d2d26e692dbbe972b3a5b39be1477b/bilateralshapley-0.0.3-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "c342c98abb0dafea738113a81617f9f1",
                    "sha256": "3ae9959c6abe17feeceb70ae251da6a2245d668dac8ff8e9663869107d06fe0d"
                },
                "downloads": -1,
                "filename": "bilateralshapley-0.0.3.tar.gz",
                "has_sig": false,
                "md5_digest": "c342c98abb0dafea738113a81617f9f1",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9540,
                "upload_time": "2019-01-16T21:37:47",
                "url": "https://files.pythonhosted.org/packages/a1/e5/d9e6a7d7925e8eaf018cdbc27ff06864d33dd1cfbd4bac368a9d2004131b/bilateralshapley-0.0.3.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "611aa6b5b64a1f891337ffe7053074e4",
                "sha256": "4b93b82853eea73b99d3e267c63ad791371d695f3d3a42eff834e982feb8a0be"
            },
            "downloads": -1,
            "filename": "bilateralshapley-0.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "611aa6b5b64a1f891337ffe7053074e4",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 10299,
            "upload_time": "2019-01-16T21:37:45",
            "url": "https://files.pythonhosted.org/packages/b7/65/7949b31acde3cb6c413c4afd83cb06d2d26e692dbbe972b3a5b39be1477b/bilateralshapley-0.0.3-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "c342c98abb0dafea738113a81617f9f1",
                "sha256": "3ae9959c6abe17feeceb70ae251da6a2245d668dac8ff8e9663869107d06fe0d"
            },
            "downloads": -1,
            "filename": "bilateralshapley-0.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "c342c98abb0dafea738113a81617f9f1",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 9540,
            "upload_time": "2019-01-16T21:37:47",
            "url": "https://files.pythonhosted.org/packages/a1/e5/d9e6a7d7925e8eaf018cdbc27ff06864d33dd1cfbd4bac368a9d2004131b/bilateralshapley-0.0.3.tar.gz"
        }
    ]
}