multi-agent-coordination 0.1__tar.gz

multi-agent-coordination-0.1/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 ankur-tutlani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

multi-agent-coordination-0.1/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.1
+Name: multi-agent-coordination
+Version: 0.1
+Summary: Identification of strategic choices under multi-agent systems, coordination game and social networks
+Home-page: https://github.com/ankur-tutlani/multi-agent-coordination
+Download-URL: https://github.com/ankur-tutlani/multi_agent_coordination/archive/refs/tags/v_01.tar.gz
+Author: ankurtutlani
+Author-email: ankur.tutlani@gmail.com
+License: MIT
+Keywords: game theory,evolutionary game,social norms,multi-agent systems,evolution,social network,computational economics,simulation,agent-based modeling,computation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+
+# Evolution of Strategic Choices under Coordination and Social Networks
+
+This library is used to understand how specific actions or choices can evolve as the dominant choices when agents donot have any specific choices to begin with and they form their opinions based upon their interactions with other agents repeatedly. Agents have incentives to coordinate with other agents and are connected with each other through a specific social network. The strategies or actions which satisfy the norm criteria are potential candidates for setting the norm. In simple terms, norm is something which is played by more number of agents and for a longer periods of time.
+
+## How to use it?
+
+
+```bash
+  # Install
+  pip install multi-agent-coordination
+  
+  # Import
+  from multi_agent_coordination import simulation
+
+  # Execute 
+  simulation.network_simulations(iteration_name = "test",
+                        path_to_save_output = "C:\\Users\\Downloads\\",
+                        num_neighbors = 2,
+                        num_agents = 20,
+                        prob_edge_rewire = 0.5,
+                        grid_network_m = 5,
+                        grid_network_n = 4,
+                        name_len = 4,
+                        num_of_trials = 20,
+                        perturb_ratio = 0.05,
+                        fixed_agents=[],
+                        prob_new_name = 0,
+                        network_name = "complete",
+                        random_seed = 96852,
+                        function_to_use = "perturbed_response1",
+                        norms_agents_frequency = 0.7,
+                        norms_time_frequency = 0.5
+                        
+                       )
+
+
+```
+    
+## Function parameters
+Following are the parameters which are required to be specified. At the end in the parenthesis, it shows the data type of the parameter which is required or the possible values which is required to be used. In following we will use agents' strategies, actions, choices, responses, names proposed interchangeably. These all represent same intent and meaning in our context.
+
+1. iteration_name: Iteration name. (String)
+2. path_to_save_output: Path to save output files. (String)
+3. num_neighbors: Number of neighbours. (Integer)
+4. num_agents: Number of agents. (Integer)
+5. prob_edge_rewire: Small world network parameter. Probability of rewiring existing edges or adding new edges. (Float)
+6. grid_network_m:  2-dimensional grid network parameter. Number of nodes. (Integer)
+7. grid_network_n:  2-dimensional grid network parameter. Number of nodes. (Integer)
+8. name_len: Length of random keywords created by the game. (Integer)
+9. num_of_trials: Number of trials, how long the game should run. (Integer)
+10. perturb_ratio: Probability of agents taking action randomly. (Float)
+11. fixed_agents: Agents assumed as fixed. e.g. [2,3] shows we want agents 2 and 3 to be fixed. (List)
+12. prob_new_name: Probability of agent suggesting new name at any time during the game. (Float)
+13. network_name: Specify one of these values. A detailed explanation is provided below. ["small_world1","small_world2","small_world3","complete","random","grid2d"]. (String)
+14. random_seed: Random seed value to reproduce results. (Integer)
+15. function_to_use: Specify one of these values. A detailed explanation is provided below. ["perturbed_response1","perturbed_response2","perturbed_response3","perturbed_response4"]. (String)
+16. norm_agents_frequency: Norm condition. Minimum percentage of agents require to propose same name at any given time. Specify number from 0 (0% agents) to 1(100% agents). (Float)
+17. norm_time_frequency: Norm condition. Minimum percentage of times agents require to propose same name. Specify number from 0 (no time period) to 1 (all time periods). (Float)
+
+<br />
+
+In the "function_to_use" parameter above, below is the explanation for what these different values mean inside the list specified above.
+
+1. perturbed_response1: Agents select the best response (1-"perturb_ratio")*100% times among the strategies which are most frequently used. If there is more than one such strategy, then agents select any one strategy randomly. Agents select random strategy ("perturb_ratio")*100% times among the strategies which are not most frequently used. Here also, if there is more than one such strategy, then agents select any one strategy randomly out of these.
+2. perturbed_response2: Agent selects strategy randomly according to the relative weightage of different strategies. These relative weights are the % of times the respective strategy has been used by opponents in the past. 
+3. perturbed_response3: This is same as "perturbed_response1" function except agent selects random strategy ("perturb_ratio")*100% times from all the possible strategies and not only from the ones which were not used most frequently by their opponents.
+4. perturbed_response4: Agent selects the best response 100% of times among the strategies which are most frequently used. If there is more than one such strategy, then agents select any one strategy randomly. There is no perturbation element ("perturb_ratio" is considered as zero).
+
+In all the four different response functions, agents propose new name at any point during the game with probability of "prob_new_name".
+
+
+<br/>
+
+In the "network_name" parameter above, below is the explanation for what these different values mean inside the list specified above.
+1. small_world1: Returns a Watts Strogatz small-world graph. Here number of edges remained constant once we increase the "prob_edge_rewire" value. Shortcut edges if added would replace the existing ones. But total count of edges remained constant.
+2. small_world2: Returns a Newman Watts Strogatz small-world graph. Here number of edges increased once we increase the "prob_edge_rewire" value. It would add more shortcut edges in addition to what already exist.
+3. small_world3: Returns a connected Watts Strogatz small-world graph. Rest of the explanation remains as small_world1.
+4. complete: Returns the complete graph.
+5. random: Compute a random graph by swapping edges of a given graph. The given graph used is Watts Strogatz small-world graph (the one produced by "small_world1").
+6. grid2d: Return the 2d grid graph of mxn nodes, each connected to its nearest neighbors.
+
+We have used the networkx python library to populate these graphs. For more information around these graphs and how these are produced please refer to the link in the reference section.
+
+
+
+## Function explanation
+Here we explain the underlying functioning of this library with the help of an example. But the logic can be replicated to any coordination game where there is a positive reward if agents follow the same strategy as their neighbour/opponent, and zero/negative reward if agents follow different strategy.
+
+We assume agents play naming game as defined in Young (2015). Naming game is a coordination game wherein two agents are shown a picture of a face and they simultaneously and independently suggest names for it. If agents provide same name, they earn a positive reward and if they provide different names, they pay a small penalty (negative reward). There is no restriction on the names that agents can provide, this is left to their imagination. Agents do not know with whom they are paired or their identities. Agents can recollect the names provided by their partners in previous rounds.
+
+We assume there are 20 ("num_agents") agents and are connected with 2 ("num_neighbors") other agents in their neighbourhood. We assume that the positive reward and negative reward are constant values. If we assume agents are connected via ring network structure, the network looks like as in below figure. For instance, agent 0 relates to 2 agents, agent 1 and 19. Similarly, agent 5 is connected with agents 4 and 6. We assume the network to be undirected.
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/input_network.png)
+
+
+
+We start the game with one edge of the network is selected at any given point. Edge of the network is represented as (0,1), (5,4) etc, implying agents 0 and 1 are connected with each other, agents 5 and 4 are connected with each other. During each time period, all edges are selected sequentially and the agents associated with those edges play the game.
+
+To begin with, agents do not have history to look back into, hence agents propose names randomly. Agents do not know the identity of the other agents with whom they are being paired. At the end of a given time period, agents do know the names proposed by other agents. Once agents have history of names proposed by other agents, they take into consideration the names proposed by their opponents in the next successive plays. This way agents get to know the names which are popular among the agents.
+
+We assume name to be any string of length "name_len", a combination of alpha and numeric characters generated randomly. Agents keep track of names proposed by other agents and accordingly update their actions in the successive rounds of play. We assume agents have bounded rationality and engaged in limited calculations to decide upon what action to take.
+
+We have considered different combinations of approaches or methods that agents can adopt while taking actions. We assume that agents use perturbed best response implying agents can take action randomly with a certain probability (Young, 2015). At each time when agents require to take action, they consider the names proposed in the past by their opponents and decide what name to propose in the current period. We have tested four different ways which agents can use to decide what action to take. The "function_to_use" parameter provides details about these and how these are different to each other.
+
+When the simulations are run for "num_of_trials" timeperiod, we get the percentage distribution of different names (strategies) which agents proposed. The names which satisfy the two conditions for norm specified by "norms_agents_frequency" and "norms_time_frequency" are considered as norm. We have looked at two dimensions of norms, number of agents following the norm and for how long it has been followed. We can see the output like below. In below graph, X-axis shows the timeperiod, and Y-axis shows the % of agents who proposed the respective name. Y-axis values are in ratio format (range from 0 - 1), so would need to multiply by 100 to get this in percentage format.
+
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/top_names.png)
+
+
+
+In above figure, name "1E1C" satisfies the norm criteria, when we assume "norms_agents_frequency" as 0.7 and "norms_time_frequency" as 0.5. This implies at least 70% of agents following "1E1C" for at least 50% of times. The network structure looks like below by the end of "num_of_trials" timeperiods. Agents who proposed same name majority of times during the run are colored in same colour. Color itself has no significance here, it is just used to denote agents proposing same name. Same color agents taking same action majority of the times.
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/network_after_50_timeperiods.png)
+
+
+The detailed explanation of the output generated is provided in the next section.
+
+
+## How to interpret output?
+There are total 9 files generated in the output when there is at least 1 name which satisfies the norm criteria.
+
+    input_network_complete_2023-02-01-15-24-22.png
+    network_after_50_timeperiods_complete_2023-02-01-15-24-22.png
+	top_names_complete_2023-02-01-15-24-22.png
+    parameters_complete_2023-02-01-15-24-22.xlsx
+    aggregate_data_detailed_agent_complete_2023-02-01-15-24-22.xlsx
+	normcandidates_complete_2023-02-01-15-24-22.xlsx
+    time_when_reached_norm_complete_2023-02-01-15-24-22.xlsx
+    first_agent_proposed_norm_complete_2023-02-01-15-24-22.xlsx
+	fixed_agent_name_proposed_smallworld_10_2023-02-01-17-16-19.xlsx
+    
+
+
+The image files (.png) show the network graphs and the strategy trend graph for the simulation. The "input_network_.." file is the input network with which the game is started. The "network_after_..." file is the network state at the end of game. Agents following the same strategy most frequently, they would be coloured in the same colour in this file. The "top_names_.." png file shows the percent of times specific name is proposed over a period of time.
+
+Parameters file "parameters_.." lists all the parameters which have been specified in the function call. File "aggregate_data_detailed_.." has the information on names proposed by each agents at all time periods. 
+
+Norm file "normcandidates_..." shows names that satisfy the norm criteria laid out. File "time_when_reached_norm_..." shows the time period number when the name met the norm criteria. "first_agent_proposed_norm_" file shows the agent information who proposed that name first during the simulation run. These 3 files are generated only when at least one name satisfies the norm criteria. 
+
+When there is at least one fixed agent specified, we will see "fixed_agent_name_proposed_.." file also gets generated. This file shows the names proposed by fixed agents.
+
+All the file names end with date and time stamp when the function was executed. It also contains information on network structure used like "complete" or "smallworld" network etc.
+
+
+## References
+1. Young, H.P. "The evolution of social norms" Annual Review of Economics. 2015 (7),pp.359-387
+2. https://pypi.org/project/networkx/ 
+

multi-agent-coordination-0.1/README.md

@@ -0,0 +1,153 @@
+
+# Evolution of Strategic Choices under Coordination and Social Networks
+
+This library is used to understand how specific actions or choices can evolve as the dominant choices when agents donot have any specific choices to begin with and they form their opinions based upon their interactions with other agents repeatedly. Agents have incentives to coordinate with other agents and are connected with each other through a specific social network. The strategies or actions which satisfy the norm criteria are potential candidates for setting the norm. In simple terms, norm is something which is played by more number of agents and for a longer periods of time.
+
+## How to use it?
+
+
+```bash
+  # Install
+  pip install multi-agent-coordination
+  
+  # Import
+  from multi_agent_coordination import simulation
+
+  # Execute 
+  simulation.network_simulations(iteration_name = "test",
+                        path_to_save_output = "C:\\Users\\Downloads\\",
+                        num_neighbors = 2,
+                        num_agents = 20,
+                        prob_edge_rewire = 0.5,
+                        grid_network_m = 5,
+                        grid_network_n = 4,
+                        name_len = 4,
+                        num_of_trials = 20,
+                        perturb_ratio = 0.05,
+                        fixed_agents=[],
+                        prob_new_name = 0,
+                        network_name = "complete",
+                        random_seed = 96852,
+                        function_to_use = "perturbed_response1",
+                        norms_agents_frequency = 0.7,
+                        norms_time_frequency = 0.5
+                        
+                       )
+
+
+```
+    
+## Function parameters
+Following are the parameters which are required to be specified. At the end in the parenthesis, it shows the data type of the parameter which is required or the possible values which is required to be used. In following we will use agents' strategies, actions, choices, responses, names proposed interchangeably. These all represent same intent and meaning in our context.
+
+1. iteration_name: Iteration name. (String)
+2. path_to_save_output: Path to save output files. (String)
+3. num_neighbors: Number of neighbours. (Integer)
+4. num_agents: Number of agents. (Integer)
+5. prob_edge_rewire: Small world network parameter. Probability of rewiring existing edges or adding new edges. (Float)
+6. grid_network_m:  2-dimensional grid network parameter. Number of nodes. (Integer)
+7. grid_network_n:  2-dimensional grid network parameter. Number of nodes. (Integer)
+8. name_len: Length of random keywords created by the game. (Integer)
+9. num_of_trials: Number of trials, how long the game should run. (Integer)
+10. perturb_ratio: Probability of agents taking action randomly. (Float)
+11. fixed_agents: Agents assumed as fixed. e.g. [2,3] shows we want agents 2 and 3 to be fixed. (List)
+12. prob_new_name: Probability of agent suggesting new name at any time during the game. (Float)
+13. network_name: Specify one of these values. A detailed explanation is provided below. ["small_world1","small_world2","small_world3","complete","random","grid2d"]. (String)
+14. random_seed: Random seed value to reproduce results. (Integer)
+15. function_to_use: Specify one of these values. A detailed explanation is provided below. ["perturbed_response1","perturbed_response2","perturbed_response3","perturbed_response4"]. (String)
+16. norm_agents_frequency: Norm condition. Minimum percentage of agents require to propose same name at any given time. Specify number from 0 (0% agents) to 1(100% agents). (Float)
+17. norm_time_frequency: Norm condition. Minimum percentage of times agents require to propose same name. Specify number from 0 (no time period) to 1 (all time periods). (Float)
+
+<br />
+
+In the "function_to_use" parameter above, below is the explanation for what these different values mean inside the list specified above.
+
+1. perturbed_response1: Agents select the best response (1-"perturb_ratio")*100% times among the strategies which are most frequently used. If there is more than one such strategy, then agents select any one strategy randomly. Agents select random strategy ("perturb_ratio")*100% times among the strategies which are not most frequently used. Here also, if there is more than one such strategy, then agents select any one strategy randomly out of these.
+2. perturbed_response2: Agent selects strategy randomly according to the relative weightage of different strategies. These relative weights are the % of times the respective strategy has been used by opponents in the past. 
+3. perturbed_response3: This is same as "perturbed_response1" function except agent selects random strategy ("perturb_ratio")*100% times from all the possible strategies and not only from the ones which were not used most frequently by their opponents.
+4. perturbed_response4: Agent selects the best response 100% of times among the strategies which are most frequently used. If there is more than one such strategy, then agents select any one strategy randomly. There is no perturbation element ("perturb_ratio" is considered as zero).
+
+In all the four different response functions, agents propose new name at any point during the game with probability of "prob_new_name".
+
+
+<br/>
+
+In the "network_name" parameter above, below is the explanation for what these different values mean inside the list specified above.
+1. small_world1: Returns a Watts Strogatz small-world graph. Here number of edges remained constant once we increase the "prob_edge_rewire" value. Shortcut edges if added would replace the existing ones. But total count of edges remained constant.
+2. small_world2: Returns a Newman Watts Strogatz small-world graph. Here number of edges increased once we increase the "prob_edge_rewire" value. It would add more shortcut edges in addition to what already exist.
+3. small_world3: Returns a connected Watts Strogatz small-world graph. Rest of the explanation remains as small_world1.
+4. complete: Returns the complete graph.
+5. random: Compute a random graph by swapping edges of a given graph. The given graph used is Watts Strogatz small-world graph (the one produced by "small_world1").
+6. grid2d: Return the 2d grid graph of mxn nodes, each connected to its nearest neighbors.
+
+We have used the networkx python library to populate these graphs. For more information around these graphs and how these are produced please refer to the link in the reference section.
+
+
+
+## Function explanation
+Here we explain the underlying functioning of this library with the help of an example. But the logic can be replicated to any coordination game where there is a positive reward if agents follow the same strategy as their neighbour/opponent, and zero/negative reward if agents follow different strategy.
+
+We assume agents play naming game as defined in Young (2015). Naming game is a coordination game wherein two agents are shown a picture of a face and they simultaneously and independently suggest names for it. If agents provide same name, they earn a positive reward and if they provide different names, they pay a small penalty (negative reward). There is no restriction on the names that agents can provide, this is left to their imagination. Agents do not know with whom they are paired or their identities. Agents can recollect the names provided by their partners in previous rounds.
+
+We assume there are 20 ("num_agents") agents and are connected with 2 ("num_neighbors") other agents in their neighbourhood. We assume that the positive reward and negative reward are constant values. If we assume agents are connected via ring network structure, the network looks like as in below figure. For instance, agent 0 relates to 2 agents, agent 1 and 19. Similarly, agent 5 is connected with agents 4 and 6. We assume the network to be undirected.
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/input_network.png)
+
+
+
+We start the game with one edge of the network is selected at any given point. Edge of the network is represented as (0,1), (5,4) etc, implying agents 0 and 1 are connected with each other, agents 5 and 4 are connected with each other. During each time period, all edges are selected sequentially and the agents associated with those edges play the game.
+
+To begin with, agents do not have history to look back into, hence agents propose names randomly. Agents do not know the identity of the other agents with whom they are being paired. At the end of a given time period, agents do know the names proposed by other agents. Once agents have history of names proposed by other agents, they take into consideration the names proposed by their opponents in the next successive plays. This way agents get to know the names which are popular among the agents.
+
+We assume name to be any string of length "name_len", a combination of alpha and numeric characters generated randomly. Agents keep track of names proposed by other agents and accordingly update their actions in the successive rounds of play. We assume agents have bounded rationality and engaged in limited calculations to decide upon what action to take.
+
+We have considered different combinations of approaches or methods that agents can adopt while taking actions. We assume that agents use perturbed best response implying agents can take action randomly with a certain probability (Young, 2015). At each time when agents require to take action, they consider the names proposed in the past by their opponents and decide what name to propose in the current period. We have tested four different ways which agents can use to decide what action to take. The "function_to_use" parameter provides details about these and how these are different to each other.
+
+When the simulations are run for "num_of_trials" timeperiod, we get the percentage distribution of different names (strategies) which agents proposed. The names which satisfy the two conditions for norm specified by "norms_agents_frequency" and "norms_time_frequency" are considered as norm. We have looked at two dimensions of norms, number of agents following the norm and for how long it has been followed. We can see the output like below. In below graph, X-axis shows the timeperiod, and Y-axis shows the % of agents who proposed the respective name. Y-axis values are in ratio format (range from 0 - 1), so would need to multiply by 100 to get this in percentage format.
+
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/top_names.png)
+
+
+
+In above figure, name "1E1C" satisfies the norm criteria, when we assume "norms_agents_frequency" as 0.7 and "norms_time_frequency" as 0.5. This implies at least 70% of agents following "1E1C" for at least 50% of times. The network structure looks like below by the end of "num_of_trials" timeperiods. Agents who proposed same name majority of times during the run are colored in same colour. Color itself has no significance here, it is just used to denote agents proposing same name. Same color agents taking same action majority of the times.
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/network_after_50_timeperiods.png)
+
+
+The detailed explanation of the output generated is provided in the next section.
+
+
+## How to interpret output?
+There are total 9 files generated in the output when there is at least 1 name which satisfies the norm criteria.
+
+    input_network_complete_2023-02-01-15-24-22.png
+    network_after_50_timeperiods_complete_2023-02-01-15-24-22.png
+	top_names_complete_2023-02-01-15-24-22.png
+    parameters_complete_2023-02-01-15-24-22.xlsx
+    aggregate_data_detailed_agent_complete_2023-02-01-15-24-22.xlsx
+	normcandidates_complete_2023-02-01-15-24-22.xlsx
+    time_when_reached_norm_complete_2023-02-01-15-24-22.xlsx
+    first_agent_proposed_norm_complete_2023-02-01-15-24-22.xlsx
+	fixed_agent_name_proposed_smallworld_10_2023-02-01-17-16-19.xlsx
+    
+
+
+The image files (.png) show the network graphs and the strategy trend graph for the simulation. The "input_network_.." file is the input network with which the game is started. The "network_after_..." file is the network state at the end of game. Agents following the same strategy most frequently, they would be coloured in the same colour in this file. The "top_names_.." png file shows the percent of times specific name is proposed over a period of time.
+
+Parameters file "parameters_.." lists all the parameters which have been specified in the function call. File "aggregate_data_detailed_.." has the information on names proposed by each agents at all time periods. 
+
+Norm file "normcandidates_..." shows names that satisfy the norm criteria laid out. File "time_when_reached_norm_..." shows the time period number when the name met the norm criteria. "first_agent_proposed_norm_" file shows the agent information who proposed that name first during the simulation run. These 3 files are generated only when at least one name satisfies the norm criteria. 
+
+When there is at least one fixed agent specified, we will see "fixed_agent_name_proposed_.." file also gets generated. This file shows the names proposed by fixed agents.
+
+All the file names end with date and time stamp when the function was executed. It also contains information on network structure used like "complete" or "smallworld" network etc.
+
+
+## References
+1. Young, H.P. "The evolution of social norms" Annual Review of Economics. 2015 (7),pp.359-387
+2. https://pypi.org/project/networkx/ 
+

multi-agent-coordination-0.1/multi_agent_coordination/__init__.py

@@ -0,0 +1 @@
+from multi_agent_coordination.simulation import perturbed_response1,perturbed_response2,perturbed_response3,perturbed_response4,network_simulations

multi-agent-coordination-0.1/multi_agent_coordination/simulation.py

@@ -0,0 +1,480 @@
+
+import numpy as np   
+import pandas as pd
+import networkx as nx
+import matplotlib.pyplot as plt
+import datetime
+import random
+import string
+
+
+
+# 1.iteration_name: iteration name. String
+# 2.path_to_save_output: path to save output files. String 
+# 3.num_neighbors: number of neighbours. Integer
+# 4.num_agents: number of agents. Integer
+# 5.prob_edge_rewire: small world network parameter. Probability of rewiring each edge. Float
+# 6.grid_network_m:  2-dimensional grid network parameter. Number of nodes. Integer
+# 7.grid_network_n:  2-dimensional grid network parameter. Number of nodes. Integer
+# 8.name_len: length of random keywords created by the game. Integer
+# 9.num_of_trials: number of trials. Integer    
+# 10.perturb_ratio: probability of agents taking action randomly. Float
+# 11.fixed_agents: agents assumed as fixed. List
+# 12.prob_new_name: probability of agent suggesting new name. Float
+# 13.network_name: specify one of these values [small_world1,small_world2,small_world3,complete,random,grid2d]. String
+# 14.random_seed: random seed value. Integer 
+# 15.function_to_use: specify one of these values [perturbed_response1,perturbed_response2,perturbed_response3,perturbed_response4]. String  
+# 16.norm_agents_frequency: norm condition. Minimum percentage of agents require to propose same name. Specify number from 0 to 1. Float
+# 17.norm_time_frequency: norm condition. Minimum percentage of times agents require to propose same name. Specify number from 0 to 1. Float     
+
+# function_to_use
+# perturbed_response1: Agent selects the best response (1-perturb_ratio)*100% times among the strategies which are most frequently used. Agents selects random strategy (perturb_ratio)*100% times from which are not most frequently used. Agents propose new name at any point during the game with probability of prob_new_name.
+# perturbed_response2: Agent selects strategy according to the % share in which it has been used by opponents in the past.Agents propose new name at any point during the game with probability of prob_new_name.
+# perturbed_response3: This is same as perturbed_response1 function except agent selects random strategy (perturb_ratio)*100% times from all the strategies. Agents propose new name at any point during the game with probability of prob_new_name.
+# perturbed_response4: Agent selects the best response 100% times among the strategies which are most frequently used. There is no perturbation element.Agents propose new name at any point during the game with probability of prob_new_name.
+    
+ 
+# Note there may be instances wherein more than 1 strategy has been used by opponent agents more frequently.
+# E.g. if an agent comes across s1 and s2 strategy used by their opponent agents most frequently during any history and both s1 and s2
+# have been used equally in the past, in that case agent deciding to take action will select randomly from s1 and s2.
+
+
+# network_name
+# small_world1: Returns a Watts–Strogatz small-world graph. Here number of edges remained constant once we increase the prob_edge_rewire value.Shortcut edges if added would replace the existing ones. But total count of edges remained constant.
+# small_world2: Returns a Newman–Watts–Strogatz small-world graph. Here number of edges increased once we increase the prob_edge_rewire value. Would add more shortcut edges in addition to what already exist.
+# small_world3: Returns a connected Watts–Strogatz small-world graph.
+# complete: Returns the complete graph.
+# random: Compute a random graph by swapping edges of a given graph.
+# grid2d: Return the 2d grid graph of mxn nodes, each connected to its nearest neighbors.
+
+
+
+
+def perturbed_response1(AGENT_NO,data_to_look,perturb_ratio,name_len,prob_new_name):
+
+    try:
+        count_pd = data_to_look.loc[data_to_look["agent"]==AGENT_NO]["name_offered_by_opponent"].value_counts().reset_index()
+        count_pd["tot_sum"] = count_pd["name_offered_by_opponent"] / sum(count_pd["name_offered_by_opponent"])
+        best_response = count_pd.loc[count_pd["tot_sum"] == max(count_pd["tot_sum"])]['index'].tolist()
+        draw1= random.choices(population=best_response,k=1)
+
+        Nonbest_response = count_pd.loc[count_pd["tot_sum"] != max(count_pd["tot_sum"])]['index'].tolist()
+        if len(Nonbest_response) > 0:
+            draw2= random.choices(population=Nonbest_response,k=1)
+            best_response = random.choices(population=[draw1[0],draw2[0]],weights=[1-perturb_ratio,perturb_ratio],k=1)
+            best_response = best_response[0]
+        else:
+            best_response = draw1[0]
+
+
+    except:
+        best_response = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+        best_response = best_response[0]
+
+
+    best_response2 = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+    best_response2 = best_response2[0]
+
+    best_response3 = random.choices(population=[best_response,best_response2],weights=[1-prob_new_name,prob_new_name],k=1)[0]
+
+    return best_response3
+
+
+
+
+def perturbed_response2(AGENT_NO,data_to_look,name_len,prob_new_name):
+    try:
+        count_pd = data_to_look.loc[data_to_look["agent"]==AGENT_NO]["name_offered_by_opponent"].value_counts().reset_index()
+        count_pd["tot_sum"] = count_pd["name_offered_by_opponent"] / sum(count_pd["name_offered_by_opponent"])
+        names_list = count_pd['index'].tolist()
+        share_list = count_pd['tot_sum'].tolist()
+        draw1= random.choices(population=names_list,weights=share_list,k=1)
+        best_response = draw1[0]
+
+
+    except:
+        best_response = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+        best_response = best_response[0]
+
+    best_response2 = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+    best_response2 = best_response2[0]
+
+    best_response3 = random.choices(population=[best_response,best_response2],weights=[1-prob_new_name,prob_new_name],k=1)[0]
+
+
+    return best_response3
+
+
+
+
+def perturbed_response3(AGENT_NO,data_to_look,perturb_ratio,name_len,prob_new_name):
+    try:
+        count_pd = data_to_look.loc[data_to_look["agent"]==AGENT_NO]["name_offered_by_opponent"].value_counts().reset_index()
+        count_pd["tot_sum"] = count_pd["name_offered_by_opponent"] / sum(count_pd["name_offered_by_opponent"])
+        best_response = count_pd.loc[count_pd["tot_sum"] == max(count_pd["tot_sum"])]['index'].tolist()
+        draw1= random.choices(population=best_response,k=1)
+
+        Nonbest_response = count_pd['index'].tolist()
+        draw2= random.choices(population=Nonbest_response,k=1)
+        best_response = random.choices(population=[draw1[0],draw2[0]],weights=[1-perturb_ratio,perturb_ratio],k=1)
+        best_response = best_response[0]
+
+    except:
+        best_response = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+        best_response = best_response[0]
+
+    best_response2 = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+    best_response2 = best_response2[0]
+
+    best_response3 = random.choices(population=[best_response,best_response2],weights=[1-prob_new_name,prob_new_name],k=1)[0]
+
+    return best_response3
+
+
+
+
+def perturbed_response4(AGENT_NO,data_to_look,name_len,prob_new_name):
+    try:
+        count_pd = data_to_look.loc[data_to_look["agent"]==AGENT_NO]["name_offered_by_opponent"].value_counts().reset_index()
+        count_pd["tot_sum"] = count_pd["name_offered_by_opponent"] / sum(count_pd["name_offered_by_opponent"])
+        best_response = count_pd.loc[count_pd["tot_sum"] == max(count_pd["tot_sum"])]['index'].tolist()
+        draw1= random.choices(population=best_response,k=1)
+        best_response = draw1[0]
+
+    except:
+        best_response = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+        best_response = best_response[0]
+
+    best_response2 = [''.join(random.choices(string.ascii_uppercase+string.digits,k=name_len))]
+    best_response2 = best_response2[0]
+
+    best_response3 = random.choices(population=[best_response,best_response2],weights=[1-prob_new_name,prob_new_name],k=1)[0]
+
+    return best_response3
+
+
+
+
+def network_simulations(iteration_name,
+                        path_to_save_output,
+                        num_neighbors,
+                        num_agents,
+                        prob_edge_rewire,
+                        grid_network_m,
+                        grid_network_n,
+                        name_len,
+                        num_of_trials,
+                        perturb_ratio,
+                        fixed_agents,
+                        prob_new_name,
+                        network_name,
+                        random_seed,
+                        function_to_use,
+                        norms_agents_frequency,
+                        norms_time_frequency
+                        
+                       ):
+    
+    
+    iteration_name = iteration_name
+    today = datetime.datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
+    path_to_save_output = path_to_save_output
+    num_neighbors = num_neighbors
+    num_agents= num_agents
+    prob_edge_rewire = prob_edge_rewire
+    grid_network_m=grid_network_m
+    grid_network_n=grid_network_n
+    name_len = name_len
+    num_of_trials =  num_of_trials
+    perturb_ratio = perturb_ratio
+    fixed_agents = fixed_agents
+    prob_new_name=prob_new_name
+    network_name = network_name
+    random_seed = random_seed
+    function_to_use =  function_to_use
+    norms_agents_frequency = norms_agents_frequency
+    norms_time_frequency = norms_time_frequency
+
+    random.seed(random_seed)
+    
+    if network_name == 'small_world1': 
+        G = nx.watts_strogatz_graph(num_agents,num_neighbors,prob_edge_rewire)
+    if network_name == 'small_world2': 
+        G = nx.newman_watts_strogatz_graph(n=num_agents,k=num_neighbors,p=prob_edge_rewire,seed=random_seed)
+    if network_name == 'small_world3':
+        G = nx.connected_watts_strogatz_graph(n=num_agents,k=num_neighbors,p=prob_edge_rewire,seed=random_seed)
+    if network_name == 'complete':
+        G = nx.complete_graph(num_agents)
+    if network_name == 'random':
+        G = nx.watts_strogatz_graph(num_agents,num_neighbors,prob_edge_rewire)
+        G = nx.random_reference(G, niter=5, connectivity=True, seed=random_seed)
+    if network_name == 'grid2d':
+        G = nx.grid_2d_graph(m=grid_network_m,n=grid_network_n)
+        mapping = dict(zip(G, range(len(G))))
+        G = nx.relabel_nodes(G, mapping)
+        
+        
+    nx.draw(G,with_labels=True)
+    plt.savefig(path_to_save_output+"input_network_"+iteration_name+"_"+today+".png")
+    plt.clf()
+    
+    potential_edges = list(G.edges)
+    
+    empty_df_to_fill_trial = pd.DataFrame()
+    empty_df_to_fill_trial["agent"] = -1
+    empty_df_to_fill_trial["name_offered"] = ''
+    empty_df_to_fill_trial["opponentagent"] = -1
+    empty_df_to_fill_trial["name_offered_by_opponent"] = ''
+    empty_df_to_fill_trial["pair"] = ""
+    empty_df_to_fill_trial["timeperiod"] = -1
+
+    
+    fixed_values_to_use = dict()
+    num_of_rounds = len(potential_edges)
+    norms_db_to_fill = pd.DataFrame()
+    norms_db_to_fill['name'] = ''
+    norms_db_to_fill['percent_count'] = ''
+    norms_db_to_fill['timeperiod'] = ''
+    
+    
+    for timeperiod in range(1,num_of_trials+1):
+        empty_df_to_fill_temp = empty_df_to_fill_trial[0:0]
+        for v in range(num_of_rounds):
+            vcheck = potential_edges[v]
+            agent1 = vcheck[0]
+            agent2 = vcheck[1]
+
+            if function_to_use == 'perturbed_response1':
+                if len(empty_df_to_fill_temp) > len(empty_df_to_fill_trial):
+
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                else:
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+
+            elif function_to_use == 'perturbed_response2':
+                if len(empty_df_to_fill_temp) > len(empty_df_to_fill_trial):
+
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                else:
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+
+
+
+            elif function_to_use == 'perturbed_response3':
+                if len(empty_df_to_fill_temp) > len(empty_df_to_fill_trial):
+
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                else:
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+
+
+
+            elif function_to_use == 'perturbed_response4':
+                if len(empty_df_to_fill_temp) > len(empty_df_to_fill_trial):
+
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_temp,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                else:
+                    name_to_fill1 = perturbed_response1(AGENT_NO = agent1,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+                    name_to_fill2 = perturbed_response1(AGENT_NO = agent2,data_to_look = empty_df_to_fill_trial,perturb_ratio=perturb_ratio,name_len=name_len,prob_new_name=prob_new_name)
+
+
+
+            if (agent1 in fixed_agents or agent2 in fixed_agents) and len(fixed_values_to_use) < len(fixed_agents):
+                for jj in fixed_agents:
+                    if jj not in list(fixed_values_to_use.keys()):
+                        xx = empty_df_to_fill_temp.loc[empty_df_to_fill_temp["agent"]==jj].sort_values(["timeperiod"],ascending=True).head(1)
+                        if len(xx) > 0:
+                            fixed_values_to_use[xx["agent"].values[0]]=xx["name_offered"].values[0]
+
+            if agent1 in fixed_agents:
+                try:
+                    name_offered = fixed_values_to_use[agent1]
+                except:
+                    name_offered = name_to_fill1
+            else:
+                name_offered = name_to_fill1
+
+
+            if agent2 in fixed_agents:
+                try:
+                    name_offered_by_opponent = fixed_values_to_use[agent2]
+                except:
+                    name_offered_by_opponent = name_to_fill2
+            else:
+                name_offered_by_opponent = name_to_fill2
+
+
+            data_to_append = pd.DataFrame({'agent':agent1,
+                                               'name_offered':name_offered,
+                                               'name_offered_by_opponent':name_offered_by_opponent,
+                                               'opponentagent':agent2,
+                                               'pair':str(vcheck), 
+                                               'timeperiod':timeperiod
+                                               },index=[0])
+
+            data_to_append2 = pd.DataFrame({'agent':agent2,
+                                               'name_offered':name_offered_by_opponent,
+                                               'name_offered_by_opponent':name_offered,
+                                               'opponentagent':agent1,
+                                               'pair':str(vcheck), 
+                                               'timeperiod':timeperiod
+                                               },index=[0])
+
+
+            empty_df_to_fill_temp = pd.concat([empty_df_to_fill_temp,data_to_append,data_to_append2],ignore_index=True,sort=False)
+
+
+        empty_df_to_fill_trial = pd.concat([empty_df_to_fill_trial,empty_df_to_fill_temp],ignore_index=True,sort=False)
+        footemp = empty_df_to_fill_temp['name_offered'].value_counts(normalize=True).to_frame()
+        footemp.columns = ['percent_count']
+        footemp['name'] = footemp.index.values
+        footemp=footemp[['name','percent_count']].reset_index(drop=True)
+        footemp['timeperiod'] = timeperiod
+
+        norms_db_to_fill = pd.concat([norms_db_to_fill,footemp],ignore_index=True,sort=False)
+        
+        
+    norms_candidates = norms_db_to_fill.loc[norms_db_to_fill['percent_count']>=norms_agents_frequency]
+    norms_to_store = []
+    percent_time_frequency = []
+    if len(norms_candidates) > 0:
+        potential_norms_candidate = np.unique(norms_candidates['name']).tolist()
+        for k in potential_norms_candidate:
+            norms_candidates2 = norms_candidates.loc[norms_candidates['name']==k]
+            distinct_timeperiod = len(np.unique(norms_candidates2['timeperiod']))
+            norms_candidates2 = round(distinct_timeperiod/len(np.unique(norms_db_to_fill['timeperiod'])),2)
+            if norms_candidates2 >= norms_time_frequency:
+                norms_to_store.append(k)
+                percent_time_frequency.append(norms_candidates2)
+                
+    
+    try:
+        norms_candidates2 = pd.DataFrame()
+        norms_candidates2["percent_count"] = percent_time_frequency
+        norms_candidates2["name"] = norms_to_store
+        if len(norms_candidates2) > 0:
+            norms_candidates2.to_excel(path_to_save_output+"normcandidates_"+iteration_name+"_"+today+".xlsx",index=None)
+    except:
+        pass
+    
+    
+    
+    
+    db_to_fill2 = pd.DataFrame()
+    db_to_fill2["timeperiod"] = -1
+    db_to_fill2["name_offered"] = -1
+
+    if len(norms_to_store) > 0:
+        for j in norms_to_store:
+            foocheck = norms_candidates.loc[norms_candidates["name"]==j]
+            foocheck = foocheck.sort_values(["timeperiod"])
+            foocheck["count_names_offered"] = (foocheck["name"]==j).cumsum()
+            foocheck["cum_perc"] = foocheck["count_names_offered"]/len(np.unique(norms_db_to_fill['timeperiod'])) ## divide by total timeperiod.
+            xxxx= foocheck.loc[foocheck["cum_perc"]>=norms_time_frequency][["timeperiod"]].head(1)
+            if xxxx.shape[0] > 0:
+                timev = foocheck.loc[foocheck["cum_perc"]>=norms_time_frequency][["timeperiod"]].head(1)["timeperiod"].values[0]
+                foodb = pd.DataFrame({"timeperiod":[timev],"name_offered":[j]})
+                db_to_fill2 = pd.concat([db_to_fill2,foodb],ignore_index=True,sort=False)
+                
+    
+    try:
+        if len(db_to_fill2) > 0:
+            db_to_fill2.to_excel(path_to_save_output+"time_when_reached_norm_"+iteration_name+"_"+today+".xlsx",index=None)
+    except:
+        pass
+    
+    
+    
+    empty_df_to_fill_trial = empty_df_to_fill_trial.sort_values(["timeperiod"])
+    agent_no_to_fill = []
+    if len(norms_to_store) > 0:
+        for j in norms_to_store:
+            xx = empty_df_to_fill_trial.loc[empty_df_to_fill_trial["name_offered"]==j].head(1)["agent"].values[0]
+            agent_no_to_fill.append(xx)
+            
+    
+    data1_to_save = pd.DataFrame({'first_agent_propose_the_name':agent_no_to_fill,'name_proposed':norms_to_store})
+    try:
+        if len(data1_to_save) > 0:
+            data1_to_save.to_excel(path_to_save_output+"first_agent_proposed_norm_"+iteration_name+"_"+today+".xlsx",index=None)
+    except:
+        pass
+    
+    
+    if len(fixed_agents) > 0:
+        fixed_agents_data =empty_df_to_fill_trial.loc[empty_df_to_fill_trial["agent"].isin(fixed_agents)][["agent","name_offered","timeperiod"]]
+        fixed_agents_data=fixed_agents_data.sort_values(["agent","timeperiod"])
+        fixed_agents_data = fixed_agents_data.groupby("agent").first().reset_index()
+        fixed_agents_data.to_excel(path_to_save_output+"fixed_agent_name_proposed_"+iteration_name+"_"+today+".xlsx",index=None)
+
+    
+    list_to_fill_for_labels_2 = []
+    for i in range(len(G)):
+        perct_share = empty_df_to_fill_trial.loc[empty_df_to_fill_trial["agent"]==i]["name_offered"].value_counts(normalize=True).to_frame()
+        perct_share["name_index"] = perct_share.index.tolist()
+        xx = perct_share.head(1)["name_index"][0]
+        list_to_fill_for_labels_2.append(xx)
+        
+    
+    selected_norms = list(set(list_to_fill_for_labels_2))
+    
+    fig,ax = plt.subplots()
+    data_for_trend_plot = norms_db_to_fill.loc[norms_db_to_fill['name'].isin(selected_norms)]
+    data_for_trend_plot = data_for_trend_plot.reset_index(drop=True)
+    for label,grp in data_for_trend_plot.groupby('name'):
+        grp.plot(x='timeperiod',y='percent_count',ax=ax,label=label)
+    ax.set_xlabel('Timeperiod')
+    ax.set_ylabel('Count %')
+    # plt.show()
+    plt.savefig(path_to_save_output+"top_names_"+iteration_name+"_"+today+".png")
+    plt.clf()
+    
+    names_to_check = list(np.unique(empty_df_to_fill_trial['name_offered']))
+    get_colors = lambda n: list(map(lambda i: "#" + "%06x" % random.randint(0, 0xFFFFFF),range(n)))
+    list_of_colors = get_colors(len(names_to_check))
+    
+    perct_share_temp=empty_df_to_fill_trial.copy()
+    list_to_fill_for_labels = []
+    for i in range(len(G)):
+        perct_share = perct_share_temp.loc[perct_share_temp["agent"]==i]["name_offered"].value_counts(normalize=True).to_frame()
+        perct_share["name_index"] = perct_share.index.tolist()
+        xx = perct_share.head(1)["name_index"][0]
+        list_to_fill_for_labels.append(xx)
+      
+    
+    color_map = []
+    for j in range(len(list_to_fill_for_labels)):
+        for i in range(len(names_to_check)):
+            if list_to_fill_for_labels[j] == names_to_check[i]:
+                color_map.append(list_of_colors[i])
+                
+    
+    nx.draw(G,with_labels=True,node_color=color_map)
+    l,r = plt.xlim()
+    plt.xlim(l-0.05,r+0.05)
+    plt.savefig(path_to_save_output+"network_after_"+str(num_of_trials)+'_timeperiods_'+iteration_name+"_"+today+".png")
+    plt.clf()
+    
+    empty_df_to_fill_trial.to_excel(path_to_save_output+"aggregate_data_detailed_agent_"+iteration_name+"_"+today+".xlsx",index=None)
+    
+    parameters_pd = pd.DataFrame([{'iteration_name':iteration_name,'path_to_save_output':path_to_save_output,
+                  'datetime':today,'num_neighbors':num_neighbors,'num_agents':num_agents,
+                  'prob_edge_rewire':prob_edge_rewire,'grid_network_m':grid_network_m,
+                  'grid_network_n':grid_network_n,'name_len':name_len,
+                  'num_of_trials':num_of_trials,'fixed_agents':str(fixed_agents),'prob_new_name':prob_new_name,
+                   'perturb_ratio':perturb_ratio,'network_name':network_name,'random_seed':random_seed,
+                  'function_to_use':function_to_use,'norms_agents_frequency':norms_agents_frequency,
+                   'norms_time_frequency':norms_time_frequency}]).T
+    parameters_pd.columns=["parameter_values"]
+    parameters_pd["parameter"]=parameters_pd.index
+    parameters_pd[["parameter","parameter_values"]].to_excel(path_to_save_output+"parameters_"+iteration_name+"_"+today+".xlsx",index=None)
+
+
+    return(print("done"))

multi-agent-coordination-0.1/multi_agent_coordination.egg-info/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.1
+Name: multi-agent-coordination
+Version: 0.1
+Summary: Identification of strategic choices under multi-agent systems, coordination game and social networks
+Home-page: https://github.com/ankur-tutlani/multi-agent-coordination
+Download-URL: https://github.com/ankur-tutlani/multi_agent_coordination/archive/refs/tags/v_01.tar.gz
+Author: ankurtutlani
+Author-email: ankur.tutlani@gmail.com
+License: MIT
+Keywords: game theory,evolutionary game,social norms,multi-agent systems,evolution,social network,computational economics,simulation,agent-based modeling,computation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+
+# Evolution of Strategic Choices under Coordination and Social Networks
+
+This library is used to understand how specific actions or choices can evolve as the dominant choices when agents donot have any specific choices to begin with and they form their opinions based upon their interactions with other agents repeatedly. Agents have incentives to coordinate with other agents and are connected with each other through a specific social network. The strategies or actions which satisfy the norm criteria are potential candidates for setting the norm. In simple terms, norm is something which is played by more number of agents and for a longer periods of time.
+
+## How to use it?
+
+
+```bash
+  # Install
+  pip install multi-agent-coordination
+  
+  # Import
+  from multi_agent_coordination import simulation
+
+  # Execute 
+  simulation.network_simulations(iteration_name = "test",
+                        path_to_save_output = "C:\\Users\\Downloads\\",
+                        num_neighbors = 2,
+                        num_agents = 20,
+                        prob_edge_rewire = 0.5,
+                        grid_network_m = 5,
+                        grid_network_n = 4,
+                        name_len = 4,
+                        num_of_trials = 20,
+                        perturb_ratio = 0.05,
+                        fixed_agents=[],
+                        prob_new_name = 0,
+                        network_name = "complete",
+                        random_seed = 96852,
+                        function_to_use = "perturbed_response1",
+                        norms_agents_frequency = 0.7,
+                        norms_time_frequency = 0.5
+                        
+                       )
+
+
+```
+    
+## Function parameters
+Following are the parameters which are required to be specified. At the end in the parenthesis, it shows the data type of the parameter which is required or the possible values which is required to be used. In following we will use agents' strategies, actions, choices, responses, names proposed interchangeably. These all represent same intent and meaning in our context.
+
+1. iteration_name: Iteration name. (String)
+2. path_to_save_output: Path to save output files. (String)
+3. num_neighbors: Number of neighbours. (Integer)
+4. num_agents: Number of agents. (Integer)
+5. prob_edge_rewire: Small world network parameter. Probability of rewiring existing edges or adding new edges. (Float)
+6. grid_network_m:  2-dimensional grid network parameter. Number of nodes. (Integer)
+7. grid_network_n:  2-dimensional grid network parameter. Number of nodes. (Integer)
+8. name_len: Length of random keywords created by the game. (Integer)
+9. num_of_trials: Number of trials, how long the game should run. (Integer)
+10. perturb_ratio: Probability of agents taking action randomly. (Float)
+11. fixed_agents: Agents assumed as fixed. e.g. [2,3] shows we want agents 2 and 3 to be fixed. (List)
+12. prob_new_name: Probability of agent suggesting new name at any time during the game. (Float)
+13. network_name: Specify one of these values. A detailed explanation is provided below. ["small_world1","small_world2","small_world3","complete","random","grid2d"]. (String)
+14. random_seed: Random seed value to reproduce results. (Integer)
+15. function_to_use: Specify one of these values. A detailed explanation is provided below. ["perturbed_response1","perturbed_response2","perturbed_response3","perturbed_response4"]. (String)
+16. norm_agents_frequency: Norm condition. Minimum percentage of agents require to propose same name at any given time. Specify number from 0 (0% agents) to 1(100% agents). (Float)
+17. norm_time_frequency: Norm condition. Minimum percentage of times agents require to propose same name. Specify number from 0 (no time period) to 1 (all time periods). (Float)
+
+<br />
+
+In the "function_to_use" parameter above, below is the explanation for what these different values mean inside the list specified above.
+
+1. perturbed_response1: Agents select the best response (1-"perturb_ratio")*100% times among the strategies which are most frequently used. If there is more than one such strategy, then agents select any one strategy randomly. Agents select random strategy ("perturb_ratio")*100% times among the strategies which are not most frequently used. Here also, if there is more than one such strategy, then agents select any one strategy randomly out of these.
+2. perturbed_response2: Agent selects strategy randomly according to the relative weightage of different strategies. These relative weights are the % of times the respective strategy has been used by opponents in the past. 
+3. perturbed_response3: This is same as "perturbed_response1" function except agent selects random strategy ("perturb_ratio")*100% times from all the possible strategies and not only from the ones which were not used most frequently by their opponents.
+4. perturbed_response4: Agent selects the best response 100% of times among the strategies which are most frequently used. If there is more than one such strategy, then agents select any one strategy randomly. There is no perturbation element ("perturb_ratio" is considered as zero).
+
+In all the four different response functions, agents propose new name at any point during the game with probability of "prob_new_name".
+
+
+<br/>
+
+In the "network_name" parameter above, below is the explanation for what these different values mean inside the list specified above.
+1. small_world1: Returns a Watts Strogatz small-world graph. Here number of edges remained constant once we increase the "prob_edge_rewire" value. Shortcut edges if added would replace the existing ones. But total count of edges remained constant.
+2. small_world2: Returns a Newman Watts Strogatz small-world graph. Here number of edges increased once we increase the "prob_edge_rewire" value. It would add more shortcut edges in addition to what already exist.
+3. small_world3: Returns a connected Watts Strogatz small-world graph. Rest of the explanation remains as small_world1.
+4. complete: Returns the complete graph.
+5. random: Compute a random graph by swapping edges of a given graph. The given graph used is Watts Strogatz small-world graph (the one produced by "small_world1").
+6. grid2d: Return the 2d grid graph of mxn nodes, each connected to its nearest neighbors.
+
+We have used the networkx python library to populate these graphs. For more information around these graphs and how these are produced please refer to the link in the reference section.
+
+
+
+## Function explanation
+Here we explain the underlying functioning of this library with the help of an example. But the logic can be replicated to any coordination game where there is a positive reward if agents follow the same strategy as their neighbour/opponent, and zero/negative reward if agents follow different strategy.
+
+We assume agents play naming game as defined in Young (2015). Naming game is a coordination game wherein two agents are shown a picture of a face and they simultaneously and independently suggest names for it. If agents provide same name, they earn a positive reward and if they provide different names, they pay a small penalty (negative reward). There is no restriction on the names that agents can provide, this is left to their imagination. Agents do not know with whom they are paired or their identities. Agents can recollect the names provided by their partners in previous rounds.
+
+We assume there are 20 ("num_agents") agents and are connected with 2 ("num_neighbors") other agents in their neighbourhood. We assume that the positive reward and negative reward are constant values. If we assume agents are connected via ring network structure, the network looks like as in below figure. For instance, agent 0 relates to 2 agents, agent 1 and 19. Similarly, agent 5 is connected with agents 4 and 6. We assume the network to be undirected.
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/input_network.png)
+
+
+
+We start the game with one edge of the network is selected at any given point. Edge of the network is represented as (0,1), (5,4) etc, implying agents 0 and 1 are connected with each other, agents 5 and 4 are connected with each other. During each time period, all edges are selected sequentially and the agents associated with those edges play the game.
+
+To begin with, agents do not have history to look back into, hence agents propose names randomly. Agents do not know the identity of the other agents with whom they are being paired. At the end of a given time period, agents do know the names proposed by other agents. Once agents have history of names proposed by other agents, they take into consideration the names proposed by their opponents in the next successive plays. This way agents get to know the names which are popular among the agents.
+
+We assume name to be any string of length "name_len", a combination of alpha and numeric characters generated randomly. Agents keep track of names proposed by other agents and accordingly update their actions in the successive rounds of play. We assume agents have bounded rationality and engaged in limited calculations to decide upon what action to take.
+
+We have considered different combinations of approaches or methods that agents can adopt while taking actions. We assume that agents use perturbed best response implying agents can take action randomly with a certain probability (Young, 2015). At each time when agents require to take action, they consider the names proposed in the past by their opponents and decide what name to propose in the current period. We have tested four different ways which agents can use to decide what action to take. The "function_to_use" parameter provides details about these and how these are different to each other.
+
+When the simulations are run for "num_of_trials" timeperiod, we get the percentage distribution of different names (strategies) which agents proposed. The names which satisfy the two conditions for norm specified by "norms_agents_frequency" and "norms_time_frequency" are considered as norm. We have looked at two dimensions of norms, number of agents following the norm and for how long it has been followed. We can see the output like below. In below graph, X-axis shows the timeperiod, and Y-axis shows the % of agents who proposed the respective name. Y-axis values are in ratio format (range from 0 - 1), so would need to multiply by 100 to get this in percentage format.
+
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/top_names.png)
+
+
+
+In above figure, name "1E1C" satisfies the norm criteria, when we assume "norms_agents_frequency" as 0.7 and "norms_time_frequency" as 0.5. This implies at least 70% of agents following "1E1C" for at least 50% of times. The network structure looks like below by the end of "num_of_trials" timeperiods. Agents who proposed same name majority of times during the run are colored in same colour. Color itself has no significance here, it is just used to denote agents proposing same name. Same color agents taking same action majority of the times.
+
+
+![](https://github.com/ankur-tutlani/multi-agent-coordination/raw/main/network_after_50_timeperiods.png)
+
+
+The detailed explanation of the output generated is provided in the next section.
+
+
+## How to interpret output?
+There are total 9 files generated in the output when there is at least 1 name which satisfies the norm criteria.
+
+    input_network_complete_2023-02-01-15-24-22.png
+    network_after_50_timeperiods_complete_2023-02-01-15-24-22.png
+	top_names_complete_2023-02-01-15-24-22.png
+    parameters_complete_2023-02-01-15-24-22.xlsx
+    aggregate_data_detailed_agent_complete_2023-02-01-15-24-22.xlsx
+	normcandidates_complete_2023-02-01-15-24-22.xlsx
+    time_when_reached_norm_complete_2023-02-01-15-24-22.xlsx
+    first_agent_proposed_norm_complete_2023-02-01-15-24-22.xlsx
+	fixed_agent_name_proposed_smallworld_10_2023-02-01-17-16-19.xlsx
+    
+
+
+The image files (.png) show the network graphs and the strategy trend graph for the simulation. The "input_network_.." file is the input network with which the game is started. The "network_after_..." file is the network state at the end of game. Agents following the same strategy most frequently, they would be coloured in the same colour in this file. The "top_names_.." png file shows the percent of times specific name is proposed over a period of time.
+
+Parameters file "parameters_.." lists all the parameters which have been specified in the function call. File "aggregate_data_detailed_.." has the information on names proposed by each agents at all time periods. 
+
+Norm file "normcandidates_..." shows names that satisfy the norm criteria laid out. File "time_when_reached_norm_..." shows the time period number when the name met the norm criteria. "first_agent_proposed_norm_" file shows the agent information who proposed that name first during the simulation run. These 3 files are generated only when at least one name satisfies the norm criteria. 
+
+When there is at least one fixed agent specified, we will see "fixed_agent_name_proposed_.." file also gets generated. This file shows the names proposed by fixed agents.
+
+All the file names end with date and time stamp when the function was executed. It also contains information on network structure used like "complete" or "smallworld" network etc.
+
+
+## References
+1. Young, H.P. "The evolution of social norms" Annual Review of Economics. 2015 (7),pp.359-387
+2. https://pypi.org/project/networkx/ 
+

multi-agent-coordination-0.1/multi_agent_coordination.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE.txt
+README.md
+setup.cfg
+setup.py
+multi_agent_coordination/__init__.py
+multi_agent_coordination/simulation.py
+multi_agent_coordination.egg-info/PKG-INFO
+multi_agent_coordination.egg-info/SOURCES.txt
+multi_agent_coordination.egg-info/dependency_links.txt
+multi_agent_coordination.egg-info/requires.txt
+multi_agent_coordination.egg-info/top_level.txt

multi-agent-coordination-0.1/multi_agent_coordination.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

multi-agent-coordination-0.1/multi_agent_coordination.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+pandas
+networkx
+matplotlib
+setuptools

multi-agent-coordination-0.1/multi_agent_coordination.egg-info/top_level.txt

@@ -0,0 +1 @@
+multi_agent_coordination

multi-agent-coordination-0.1/setup.cfg

@@ -0,0 +1,8 @@
+[metadata]
+description-file = README.md
+license_files = LICENSE.txt
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

multi-agent-coordination-0.1/setup.py

@@ -0,0 +1,38 @@
+from setuptools import setup
+import os
+
+def read_file(filename):
+    with open(os.path.join(os.path.dirname(__file__), filename)) as file:
+        return file.read()
+
+setup(
+  name = 'multi-agent-coordination',         
+  packages = ['multi_agent_coordination'],   
+  version = '0.1',      
+  license='MIT',        
+  description = 'Identification of strategic choices under multi-agent systems, coordination game and social networks',  
+  long_description=read_file('README.md'),
+  long_description_content_type='text/markdown',  
+  author = 'ankurtutlani',                   
+  author_email = 'ankur.tutlani@gmail.com',      
+  url = 'https://github.com/ankur-tutlani/multi-agent-coordination',   
+  download_url = 'https://github.com/ankur-tutlani/multi_agent_coordination/archive/refs/tags/v_01.tar.gz',    
+  keywords = ['game theory', 'evolutionary game', 'social norms','multi-agent systems','evolution','social network','computational economics','simulation','agent-based modeling','computation'],   
+  install_requires=[            
+          'numpy',
+		  'pandas',
+		  'networkx',
+		  'matplotlib',
+		  'setuptools'
+		  
+		  
+      ],
+  classifiers=[
+    'Development Status :: 3 - Alpha',      
+    'Intended Audience :: Developers',      
+    'Topic :: Software Development :: Build Tools',
+    'License :: OSI Approved :: MIT License',   
+												
+	'Programming Language :: Python :: 3.7',
+  ],
+)