Documentation for most of the Model parts

.gitignore

@@ -3,6 +3,7 @@ __pycache__
 ./data/__pycache__
 ./Model/__pycache__
 ./Model/parts/__pycache__
+qtmvenv
 .ipynb_checkpoints
 ./Model/simulationData.db
 simulationData.db

Model/parts/agents_behavior/__init__.py

@@ -0,0 +1,12 @@
+"""Describes the agent behaviour and meta bucket allocations.
+
+Contains policy functions and state update functions relevant for behaviour
+of each type of agent and for meta bucket allocations. Allows for stochastic
+or static behaviour.
+
+Modules:
+    agent_meta_bucket_behavior: agent and meta bucket related state update
+        functions and policy functions
+
+
+"""

Model/parts/agents_behavior/agent_meta_bucket_behavior.py

@@ -1,7 +1,45 @@
+"""Agent and meta bucket related state update and policy functions.
+
+Contains policy functions (PF) and state update functions (SUF) 
+relevant for behaviour of each type of agent and for meta bucket allocations.
+
+
+Functions:
+    generate_agent_meta_bucket_behavior: (PF) Define the agent behavior.
+    
+    agent_meta_bucket_allocations: (PF) Define the meta bucket token allocations 
+        of all agents.
+
+    update_agent_meta_bucket_behavior: (SUF) Function to update the agent behaviors.
+
+    update_agent_meta_bucket_allocations: (SUF) Function to update the agent meta 
+        bucket token allocations.
+
+    update_token_economy_meta_bucket_allocations: (SUF) Update the meta bucket 
+            allocations for the token economy.
+
+"""
+
 # POLICY FUNCTIONS
 def generate_agent_meta_bucket_behavior(params, substep, state_history, prev_state, **kwargs):
     """
-    Define the agent behavior for each agent type
+    Define the agent behavior for each agent type.
+
+    Policy function.
+
+    First, checks if the agent behaviour is set up to be stochastic. 
+    If stochastic, agent actions are based on a weighted random choices.
+    If static, define the agent behavior for each agent type based on previous state.
+    If neither, raise an error.
+
+    Returns: 
+        A dict with key 'agent_behavior_dict' and value being a dict, mapping agent
+        types to agent behaviour. 
+
+    Raises:    
+        ValueError: params['agent_behavior'] must be either 'stochastic' or 'static'.
+        KeyError: Missing required parameter.
+
     """
 
     try:
@@ -133,7 +171,21 @@ def generate_agent_meta_bucket_behavior(params, substep, state_history, prev_sta
 
 def agent_meta_bucket_allocations(params, substep, state_history, prev_state, **kwargs):
     """
-    Define the meta bucket token allocations of all agents with respect to 'sell' 'hold' and 'utility'
+    Define the meta bucket token allocations of all agents with respect to 'sell',
+    'hold' and 'utility'.    
+
+    Policy function.
+
+    Updates agent token allocations and updates the meta bucket allocations w.r.t. each agents contribution.
+    Note that protocol buckets are not used for meta bucket allocations
+
+    Returns: 
+        A dict which allows to group the agents according to the following keys: 
+        'meta_bucket_allocations','agent_allocations', 'agent_from_holding_allocations'. 
+        Each agent from any of these groups reports the allocations for 'sell',
+        'hold' and 'utility'.    
+
+
     """
 
     # get state variables
@@ -204,7 +256,15 @@ def agent_meta_bucket_allocations(params, substep, state_history, prev_state, **
 # STATE UPDATE FUNCTIONS
 def update_agent_meta_bucket_behavior(params, substep, state_history, prev_state, policy_input, **kwargs):
     """
-    Function to update the agent behaviors
+    Function to update the agent behaviors. 
+    
+    State update function.
+
+    Returns:
+        A tuple ('agents', updated_agents), where updated_agents is a dict mapping
+        each agent to their updated behaviour.
+    
+
     """
     updated_agents = prev_state['agents']
     agent_behavior_dict = policy_input['agent_behavior_dict']
@@ -216,7 +276,13 @@ def update_agent_meta_bucket_behavior(params, substep, state_history, prev_state
 
 def update_agent_meta_bucket_allocations(params, substep, state_history, prev_state, policy_input, **kwargs):
     """
-    Function to update the agent meta bucket token allocations
+    Function to update the agent meta bucket token allocations.
+
+    State update function.
+
+    Returns: 
+        A tuple ('agents', updated_agents), where updated_agents is a dict mapping
+        each agent to their updated meta bucket token allocation.
     """
 
     # get state variables
@@ -242,7 +308,14 @@ def update_agent_meta_bucket_allocations(params, substep, state_history, prev_st
 
 def update_token_economy_meta_bucket_allocations(params, substep, state_history, prev_state, policy_input, **kwargs):
     """
-    Function to update the meta bucket allocations for the token economy
+    Function to update the meta bucket allocations for the token economy.
+
+    State update function.
+
+    Returns: 
+        A tuple ('token_economy', updated_token_economy), where updated_token_economy is
+        a dict providing values of updated meta bucket allocations for, respectively,
+        token economy selling/utility/holding allocations and their cumulative values.
     """
 
     # get state variables

Model/parts/business/business_assumptions.py

@@ -1,9 +1,38 @@
+"""Set business assumption metrics or update business assumptions.
+
+Contains policy functions (PF) and state update functions (SUF) 
+relevant for behaviour of each type of agent and for meta bucket allocations.
+
+
+Functions:
+    business_assumption_metrics: (PF): Set up the business assumption metrics.
+
+    update_business_assumptions: (SUF): Update the business assumptions.
+
+"""
+
+
 from ..utils import *
 
 
 
 # POLICY FUNCTIONS
 def business_assumption_metrics(params, substep, state_history, prev_state, **kwargs):
+    """
+    Set up the business assumption metrics.
+
+    Policy function.
+
+    Reads a range of parameters (originally from QTM input tab 'cadCAD_inputs'), and
+    the state of: cash balance, revenue streams. 
+    Then calculates: expenditures, buyback, liquidity requirements, sum of raised capital,
+    and cash flow.
+
+    Returns:
+        Returns dict that maps 'cash_flow' to 'buybacks' to their respective values for
+        the current time step.
+
+    """
 
     # parameters
     product_income_per_month = params['product_income_per_month']
@@ -78,7 +107,16 @@ def business_assumption_metrics(params, substep, state_history, prev_state, **kw
 # STATE UPDATE FUNCTIONS
 def update_business_assumptions(params, substep, state_history, prev_state, policy_input, **kwargs):
     """
-    Function to update the business assumptions
+    Function to update the business assumptions.
+
+    State update function.
+
+    Uses cash flow and buyback variables to update business assumptions.
+
+    Returns:
+        Returns a tuple ('business_assumptions', updated_business_assumptions),
+        where updated_business_assumptions gives latest buybacks and updated cash flow.
+
     """
     # parameters
 

Model/parts/business/user_adoption.py

@@ -1,20 +1,38 @@
+"""Calculate and update user adoption metrics.
+
+Contains policy functions (PF) and state update functions (SUF).
+
+
+Functions:
+    calculate_user_adoption: Take in user adoption data and calculate the amount of adoption.
+
+    user_adoption_metrics (PF): Calculate the metrics relevant for monitoring user adoption.
+
+    update_user_adoption (SUF): Function to update the user adoption metrics.
+
+"""
+
 import math
 from Model.parts.utils import *
 
 
 
 def calculate_user_adoption(initial_users,final_users,velocity,timestamp,total_days):
     """
-    Definition:
-        Function to take in user adoption data and calculate the amount of adoption, can be used for token adoption and product users
-    
-    Parameters:
+    Take in user adoption data and calculate the amount of adoption.
+
+    Can be used for token adoption and product users.
+  
+    Args:
         initial_users: starting amount of users
         final_users: ending amount of users
         velocity: speed of adoption on those users
         timstep: current timestep in days
-        total_days: length of full simulation
+        total_days: length of full simulation.
     
+    Returns:
+        Number representing the user adoption.    
+
     """
 
     term1 = (1 / (1 + math.exp(-velocity * 0.002 * (timestamp - 1825) / velocity))) * final_users + initial_users
@@ -29,7 +47,17 @@ def calculate_user_adoption(initial_users,final_users,velocity,timestamp,total_d
 # POLICY FUNCTIONS
 def user_adoption_metrics(params, substep, state_history, prev_state, **kwargs):
     """
-    Calculate the initial token economy metrics, such as MC, FDV MC, circ. supply, and tokens locked.
+    Calculate the metrics relevant for monitoring user adoption.
+
+    Policy function.
+
+    Token adoption and product users are calculated according to the logic provided in the
+    calculate_user_adoption function.
+
+    Returns:
+        A dict which provides information on product users, token holders, product
+        revenue and token buys.
+    
     """
 
     current_month = prev_state['timestep']
@@ -84,7 +112,15 @@ def user_adoption_metrics(params, substep, state_history, prev_state, **kwargs):
 # STATE UPDATE FUNCTIONS
 def update_user_adoption(params, substep, state_history, prev_state, policy_input, **kwargs):
     """
-    Function to update the user adoption metrics
+    Function to update the user adoption metrics.
+
+    State update function.
+
+    Returns:
+        A tuple ('user_adoption', updated_user_adoption), where updated_user_adoption
+        provides updated information on product users, token holders, product revenue
+        and token buys.
+    
     """
 
     product_users = policy_input['ua_product_users']

Model/parts/ecosystem/__init__.py

@@ -0,0 +1,19 @@
+"""Describes the ecosystem level events.
+
+Contains policy functions and state update functions with the affect at the
+level of the whole ecosystem, as well as affecting individual agents.
+
+Modules:
+    airdrops: Calculate and process airdrops.
+
+    burn: Calculation and processing of token burning at ecosystem level.
+
+    incentivisation: Calculation and processing of ecosystem incentivisation.
+
+    liquidity_pool: Liquidity pool initialisation and updating after transactions.
+
+    token_economy: Provide date and token economy metrics.
+
+    vesting: Vesting tokens and updating the amount of vested tokens held.
+
+"""

Model/parts/ecosystem/airdrops.py

@@ -1,9 +1,34 @@
+"""Calculate and process airdrops.
+
+Contains policy functions (PF) and state update functions (SUF) 
+relevant for behaviour of each type of agent and for meta bucket allocations.
+
+
+Functions:
+    airdrops (PF): Policy function to calculate airdrop amount for current period.
+
+    update_agents_after_airdrops (SUF): Function to update information on airdrop 
+        receiving agent after airdrops distribution.
+
+    update_token_economy_after_airdrops (SUF): Function to update the token economy 
+        after airdrops distribution.
+
+"""
+
 import pandas as pd
 
 # POLICY FUNCTIONS
 def airdrops(params, substep, state_history, prev_state, **kwargs):
     """
-    Policy function to incentivise the ecosystem
+    Policy function to calculate airdrop amount for current period.
+
+    Airdrop amounts are provided as percentages of the airdrop allocation for
+    the predefined airdrop dates. The amounts of airdropped tokens for each 
+    date are calculated based on the total token supply, airdrop allocation 
+    percentage and the airdrop amount. 
+
+    Returns: 
+        A dict where key 'te_airdrop_tokens' gets assigned a nonnegative value. 
     """
     # get parameters
     total_token_supply = params['initial_total_supply']
@@ -35,7 +60,17 @@ def airdrops(params, substep, state_history, prev_state, **kwargs):
 # STATE UPDATE FUNCTIONS
 def update_agents_after_airdrops(params, substep, state_history, prev_state, policy_input, **kwargs):
     """
-    Function to update the vested tokens for each investor based on some criteria
+    Function to update information on airdrop receiving agent after airdrops distribution. 
+    
+    State update function.
+
+    Returns:
+        Tuple ('agents', updated_agents), where updated_agents holds information on the agents
+        who are labeled as airdrop receivers.
+
+    Raises:
+        ValueError: No airdrop receivers found; Request to add at least one.
+
     """
     # get parameters
 
@@ -66,7 +101,15 @@ def update_agents_after_airdrops(params, substep, state_history, prev_state, pol
 
 def update_token_economy_after_airdrops(params, substep, state_history, prev_state, policy_input, **kwargs):
     """
-    Function to update the token economy after incentivisation
+    Function to update the token economy after airdrops distribution.
+    
+    State update function.
+
+    Returns:
+        Tuple ('token_economy', updated_token_economy), where updated_token_economy 
+        is a dict which holds information on the tokens distributed as airdrops
+        in the current period (token amount, cumulative amount, USD value).
+
     """
     # get parameters