commit f9f945c20f1dd11a87177b4911b4d6f056faf1ca Author: Joshua E. Jodesty Date: Thu Jan 10 13:44:55 2019 -0500 init diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4ec1adb --- /dev/null +++ b/.gitignore @@ -0,0 +1,14 @@ +demos +SimCAD +simularions +setup.py +build + +.ipynb_checkpoints +.DS_Store +.idea +SimCAD.egg-info +__pycache__ +Pipfile +Pipfile.lock +.mypy_cache \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..04c5891 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,119 @@ +TRIAL LICENSE AGREEMENT + +BACKGROUND + +Company has developed and intends to market and license a certain software product and service called ”SimCAD” which, +among other things, is a scientific engineering simulation tool (“Software”). Company wishes to provide access, on a +trial basis, to users of a “beta” version of the Software to test and provide feedback to Company. Licensee wishes to +participate in Company’s beta trial of the Software and to provide feedback to Company with respect to Licensee’s use +thereof. + +Accordingly, the parties hereby agree as follows: + +1. BETA PRODUCT. + +This Agreement applies to any pre­release version of the Software and any updates and changes thereto during the Term +(collectively, “Beta Product”). As an essential condition of this Agreement, Licensee understands and acknowledges that: +(a) Licensee is participating in a beta test of the Beta Product; (b) the Beta Product has not been field tested or +trialed; and (c) the Beta Product may not operate properly or be error free and may not perform all functions for +which it is intended or represented. + +2. FEEDBACK. + +As a condition of this Agreement, during the Term of this Agreement, Licensee agrees to provide Company with comments, +feedback, criticisms, and suggestions for changes to the Beta Product (“Feedback”), and to help Company identify errors +or malfunctions, and performance issues, in the operation of the Beta Product, as Company may reasonably request. All +rights to any Feedback or other intellectual property derived from Licensee’s use of or relating to the Beta Product, +as well any data collected from the use of the Beta Product, belong solely to Company and Licensee hereby irrevocably +assigns all such rights to Company. Company reserves the right to use all Feedback and data collected as a result of the +use of the Beta Product to advertise and promote the Company and the Software. + +3. LICENSE AND RESERVATION OF RIGHTS. + +3.1 Subject to the terms and conditions set forth in this Agreement, Company hereby grants Licensee, and Licensee +accepts, during the Term, a non­exclusive, royalty­free, revocable, non­transferable, limited license to access and use +the Beta Product for its internal, non­commercial use for evaluation purposes only, and to give permission to employees +of Licensee and employees of Licensee’s subsidiaries (“Permitted Users”) to use the Beta Product in accordance with the +foregoing. + +3.2 The Beta Product and the Software comprise the intellectual property of Company. All right, title and interest in +and to the Beta Product (and, more generally, in and to the Software), and to all Feedback and data arising from its +use, in whole or in part, and all patent, copyright, trade­marks, trade secret and all other intellectual and industrial +property rights therein and the structure, sequence and organization of same, and the media on which such material is +contained belong exclusively to Company. Licensee and its Permitted Users will not, directly or indirectly: reverse +engineer, decompile, disassemble or otherwise attempt to discover the source code, object code or underlying structure, +ideas, know­how or algorithms relevant to the Beta Product; modify, adapt, alter, edit, correct, translate, publish, +sell, transfer, assign, convey, rent, lease, loan, pledge, sublicense, distribute, export, enhance or create derivative +works based on the Beta Product; or remove, alter, cover or otherwise obscure any proprietary notices or labels +displayed on or within the Beta Product any documentation relating thereto. + +4. DISCLAIMER. + +4.1 COMPANY MAKES NO WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, WITH RESPECT TO THE BETA PRODUCT, +INCLUDING, BUT NOT LIMITED TO, THE AVAILABILITY, QUALITY OR PERFORMANCE OF THE BETA PRODUCT. COMPANY SPECIFICALLY +DISCLAIMS ALL EXPRESS, STATUTORY AND IMPLIED WARRANTIES AND CONDITIONS, INCLUDING, WITHOUT LIMITATION (A) THE IMPLIED +WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON­INFRINGEMENT, (B) ANY WARRANTIES AGAINST HIDDEN +OR LATENT DEFECTS, (C) AND ANY WARRANTIES AND CONDITIONS ARISING OUT OF COURSE OF DEALING OR USAGE OF TRADE AND (D) ANY +WARRANTY OR REPRESENTATION THAT THE BETA PRODUCT IS ERROR­FREE, VIRUS­FREE, SECURE, UNINTERRUPTED, OR FREE FROM +UNAUTHORIZED ACCESS (INCLUDING, BUT NOT LIMITED TO, THIRD PARTY HACKERS OR DENIAL OF SERVICE ATTACKS). THE BETA PRODUCT +IS SUPPLIED ON AN “AS IS”, “AS AVAILABLE” BASIS WITHOUT WARRANTY. + +4.2 NEITHER PARTY SHALL BE LIABLE FOR SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR INDIRECT DAMAGES OR LOSS +(INCLUDING DEATH AND PERSONAL INJURY), IRRESPECTIVE OF THEIR CAUSE, NOTWITHSTANDING THAT A PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH LOSS OR DAMAGE, NOR FOR ANY CLAIMS FOR SUCH LOSS OR DAMAGE INSTITUTED AGAINST A PARTY OR ITS +CUSTOMERS BY ANY THIRD PARTY. + +5. CONFIDENTIALITY + +5.1 All Confidential Information disclosed by either party shall be kept by the receiving party in strict confidence and +shall not be disclosed to any third party without the disclosing party’s express written consent. For purposes of this +Agreement, “Confidential Information” means all information regarding either party’s business which has been marked or +is otherwise communicated as being “proprietary” or “confidential” or which reasonably should be known by the receiving +party to be proprietary or confidential information. Without limiting the generality of the foregoing, Confidential +Information of Company includes non­public information regarding features, functionality and performance of the Beta +Product, including all Feedback and related data. Notwithstanding the foregoing, each party’s confidentiality +obligations hereunder shall not apply to information that: (a) is already known to the receiving party without a +pre­existing restriction as to disclosure; (b) is or becomes publicly available without fault of the receiving party; +(c) is rightfully obtained by the receiving party from a third party without restriction as to disclosure, or is +approved for release by written authorization of the disclosing party; (d) is developed independently by the receiving +party without use of the disclosing party’s Confidential Information; or (e) is required to be disclosed by law or +regulation, including, but not limited to, supplying such information or making such statements or disclosures relating +to this Agreement before any competent court, governmental agency or authority in response to a lawful requirement or +request from a court of governmental agency or authority, provided that the disclosing party shall give the other party +prompt notice of such request, to the extent practicable, so that the other party may seek (at its sole cost and +expense) an appropriate protective order or similar relief. + +5.2 In the event of a breach of Sections 2, 3 or this Section 5, the non­breaching party shall be entitled to seek +equitable relief to protect its interests, including, but not limited to, injunctive relief. In the event of expiration +or earlier termination of this Agreement, each party shall immediately return to the other party such other party’s +Confidential Information, or at such other party’s option, destroy any remaining Confidential Information and certify +that such destruction has taken place. + +6. FEES; EXPENSES. + +Neither party shall be entitled to any compensation in connection with this Agreement or its use or provision of the +Beta Product. Each party shall bear its own costs and expenses arising from this Agreement and its use or provision of +the Beta Product, as the case may be. + +7. TERM OF AGREEMENT. + +This Agreement shall begin on the Effective Date and shall continue until it has been terminated (such period, the +“Term”). Either party shall have the right to terminate this Agreement at any time on one (1) month written notice to +the other party, or in the case of a breach of this Agreement by Licensee or its Permitted Users, Company may terminate +this Agreement immediately on written notice to Licensee. Upon termination of this Agreement, all rights granted to +Licensee (and any Permitted User) under this Agreement will immediately terminate and Licensee (and all Permitted Users) +must immediately cease all use of the Beta Product at such time. Notwithstanding any termination of this Agreement, +Sections 2, 3.2, 4, 5, 6, this Section 7 and Section 8 shall survive and remain binding on the parties. + +8. MISCELLANEOUS. + +This Agreement shall be governed by and construed in accordance with the laws of the State of New York. All disputes +relating to this Agreement shall be resolved in the federal and state courts of New York County, New York and the +parties submit to the jurisdiction of such courts. This Agreement does not create any agency, partnership, or joint +venture relationship between Licensee and Company. This Agreement is the entire understanding of the parties with +respect to the subject matter hereof and supersedes any previous or contemporaneous communications, representations, +warranties, discussions, arrangements or commitments, whether oral or written with respect to such subject matter. This +Agreement cannot be amended except by a written amendment that expressly refers to this Agreement and is signed by an +authorized representative of each party. This Agreement may be executed in one or more counterparts, including via +facsimile or email (or any other electronic means such as “.pdf” or “.tiff” files), each of which shall be deemed an +original, and all of which shall constitute one and the same Agreement. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..97f3511 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# SimCad +**Warning**: +**Do not** publish this package / software to **any** software repository **except** one permitted by BlockScience. + +**Description:** + +SimCAD is a differential games based simulation software package for research, validation, and Computer \ +Aided Design of economic systems. An economic system is treated as a state based model and defined through a \ +set of endogenous and exogenous state variables which are updated through mechanisms and environmental \ +processes, respectively. Behavioral models, which may be deterministic or stochastic, provide the evolution of \ +the system within the action space of the mechanisms. Mathematical formulations of these economic games \ +treat agent utility as derived from state rather than direct from action, creating a rich dynamic modeling framework. + +Simulations may be run with a range of initial conditions and parameters for states, behaviors, mechanisms, \ +and environmental processes to understand and visualize network behavior under various conditions. Support for \ +A/B testing policies, monte carlo analysis and other common numerical methods is provided. + +**1. Install Dependencies:** +```bash +pip install -r requirements.txt +pip install -e . +``` + +**2. Configure Simulation:** + +Intructions: +`/Simulation.md` + +Examples: +`/simulations/validation/*` + +**3. Import SimCAD & Run Simulation:** + +Example: +`/demos/sim_test.py` or `test.ipynb` + +```python +import pandas as pd +from tabulate import tabulate + +# The following imports NEED to be in the exact order +from SimCAD.engine import ExecutionMode, ExecutionContext, Executor +from simulations.validation import config1, config2 +from SimCAD import configs + +exec_mode = ExecutionMode() + + +print("Simulation Execution 1") +print() +first_config = [configs[0]] # from config1 +single_proc_ctx = ExecutionContext(context=exec_mode.single_proc) +run1 = Executor(exec_context=single_proc_ctx, configs=first_config) +run1_raw_result, tensor_field = run1.main() +result = pd.DataFrame(run1_raw_result) +print() +print("Tensor Field:") +print(tabulate(tensor_field, headers='keys', tablefmt='psql')) +print("Output:") +print(tabulate(result, headers='keys', tablefmt='psql')) +print() + +print("Simulation Execution 2: Pairwise Execution") +print() +multi_proc_ctx = ExecutionContext(context=exec_mode.multi_proc) +run2 = Executor(exec_context=multi_proc_ctx, configs=configs) +for raw_result, tensor_field in run2.main(): + result = pd.DataFrame(raw_result) + print() + print("Tensor Field:") + print(tabulate(tensor_field, headers='keys', tablefmt='psql')) + print("Output:") + print(tabulate(result, headers='keys', tablefmt='psql')) + print() +``` + +The above can be run in Jupyter. +```bash +jupyter notebook +``` diff --git a/SimCAD/__init__.py b/SimCAD/__init__.py new file mode 100644 index 0000000..b4234cb --- /dev/null +++ b/SimCAD/__init__.py @@ -0,0 +1,2 @@ +name = "SimCAD" +configs = [] \ No newline at end of file diff --git a/SimCAD/configuration/__init__.py b/SimCAD/configuration/__init__.py new file mode 100644 index 0000000..400fe9d --- /dev/null +++ b/SimCAD/configuration/__init__.py @@ -0,0 +1,97 @@ +from functools import reduce +from fn.op import foldr +import pandas as pd + +from SimCAD.utils import key_filter +from SimCAD.configuration.utils.behaviorAggregation import dict_elemwise_sum + + +class Configuration: + def __init__(self, sim_config, state_dict, seed, exogenous_states, env_processes, mechanisms, behavior_ops=[foldr(dict_elemwise_sum())]): + self.sim_config = sim_config + self.state_dict = state_dict + self.seed = seed + self.exogenous_states = exogenous_states + self.env_processes = env_processes + self.behavior_ops = behavior_ops + self.mechanisms = mechanisms + + +class Identity: + def __init__(self, behavior_id={'identity': 0}): + self.beh_id_return_val = behavior_id + + def b_identity(self, step, sL, s): + return self.beh_id_return_val + + def behavior_identity(self, k): + return self.b_identity + + def no_state_identity(self, step, sL, s, _input): + return None + + def state_identity(self, k): + return lambda step, sL, s, _input: (k, s[k]) + + def apply_identity_funcs(self, identity, df, cols): + def fillna_with_id_func(identity, df, col): + return df[[col]].fillna(value=identity(col)) + + return list(map(lambda col: fillna_with_id_func(identity, df, col), cols)) + + +class Processor: + def __init__(self, id=Identity()): + self.id = id + self.b_identity = id.b_identity + self.behavior_identity = id.behavior_identity + self.no_state_identity = id.no_state_identity + self.state_identity = id.state_identity + self.apply_identity_funcs = id.apply_identity_funcs + + def create_matrix_field(self, mechanisms, key): + if key == 'states': + identity = self.state_identity + elif key == 'behaviors': + identity = self.behavior_identity + df = pd.DataFrame(key_filter(mechanisms, key)) + col_list = self.apply_identity_funcs(identity, df, list(df.columns)) + if len(col_list) != 0: + return reduce((lambda x, y: pd.concat([x, y], axis=1)), col_list) + else: + return pd.DataFrame({'empty': []}) + + def generate_config(self, state_dict, mechanisms, exo_proc): + + def no_update_handler(bdf, sdf): + if (bdf.empty == False) and (sdf.empty == True): + bdf_values = bdf.values.tolist() + sdf_values = [[self.no_state_identity] * len(bdf_values) for m in range(len(mechanisms))] + return sdf_values, bdf_values + elif (bdf.empty == True) and (sdf.empty == False): + sdf_values = sdf.values.tolist() + bdf_values = [[self.b_identity] * len(sdf_values) for m in range(len(mechanisms))] + return sdf_values, bdf_values + else: + sdf_values = sdf.values.tolist() + bdf_values = bdf.values.tolist() + return sdf_values, bdf_values + + def only_ep_handler(state_dict): + sdf_functions = [ + lambda step, sL, s, _input: (k, v) for k, v in zip(state_dict.keys(), state_dict.values()) + ] + sdf_values = [sdf_functions] + bdf_values = [[self.b_identity] * len(sdf_values)] + return sdf_values, bdf_values + + if len(mechanisms) != 0: + bdf = self.create_matrix_field(mechanisms, 'behaviors') + sdf = self.create_matrix_field(mechanisms, 'states') + sdf_values, bdf_values = no_update_handler(bdf, sdf) + zipped_list = list(zip(sdf_values, bdf_values)) + else: + sdf_values, bdf_values = only_ep_handler(state_dict) + zipped_list = list(zip(sdf_values, bdf_values)) + + return list(map(lambda x: (x[0] + exo_proc, x[1]), zipped_list)) \ No newline at end of file diff --git a/SimCAD/configuration/utils/__init__.py b/SimCAD/configuration/utils/__init__.py new file mode 100644 index 0000000..09bd90b --- /dev/null +++ b/SimCAD/configuration/utils/__init__.py @@ -0,0 +1,58 @@ +from datetime import datetime, timedelta +from decimal import Decimal +from fn.func import curried +import pandas as pd + + +class TensorFieldReport: + def __init__(self, config_proc): + self.config_proc = config_proc + + def create_tensor_field(self, mechanisms, exo_proc, keys=['behaviors', 'states']): + dfs = [self.config_proc.create_matrix_field(mechanisms, k) for k in keys] + df = pd.concat(dfs, axis=1) + for es, i in zip(exo_proc, range(len(exo_proc))): + df['es' + str(i + 1)] = es + df['m'] = df.index + 1 + return df + + +def bound_norm_random(rng, low, high): + # Add RNG Seed + res = rng.normal((high+low)/2,(high-low)/6) + if (reshigh): + res = bound_norm_random(rng, low, high) + return Decimal(res) + + +@curried +def proc_trigger(trigger_step, update_f, step): + if step == trigger_step: + return update_f + else: + return lambda x: x + + +t_delta = timedelta(days=0, minutes=0, seconds=30) +def time_step(dt_str, dt_format='%Y-%m-%d %H:%M:%S', _timedelta = t_delta): + dt = datetime.strptime(dt_str, dt_format) + t = dt + _timedelta + return t.strftime(dt_format) + + +t_delta = timedelta(days=0, minutes=0, seconds=1) +def ep_time_step(s, dt_str, fromat_str='%Y-%m-%d %H:%M:%S', _timedelta = t_delta): + if s['mech_step'] == 0: + return time_step(dt_str, fromat_str, _timedelta) + else: + return dt_str + + +def exo_update_per_ts(ep): + @curried + def ep_decorator(f, y, step, sL, s, _input): + if s['mech_step'] + 1 == 1: + return f(step, sL, s, _input) + else: + return (y, s[y]) + return {es: ep_decorator(f, es) for es, f in ep.items()} \ No newline at end of file diff --git a/SimCAD/configuration/utils/behaviorAggregation.py b/SimCAD/configuration/utils/behaviorAggregation.py new file mode 100644 index 0000000..5bcdd1a --- /dev/null +++ b/SimCAD/configuration/utils/behaviorAggregation.py @@ -0,0 +1,45 @@ +from fn.op import foldr +from fn.func import curried + + +def get_base_value(datatype): + if datatype is str: + return '' + elif datatype is int: + return 0 + elif datatype is list: + return [] + return 0 + + +def behavior_to_dict(v): + return dict(list(zip(map(lambda n: 'b' + str(n + 1), list(range(len(v)))), v))) + + +add = lambda a, b: a + b + + +@curried +def foldr_dict_vals(f, d): + return foldr(f)(list(d.values())) + + +def sum_dict_values(): + return foldr_dict_vals(add) + + +@curried +def dict_op(f, d1, d2): + def set_base_value(target_dict, source_dict, key): + if key not in target_dict: + return get_base_value(type(source_dict[key])) + else: + return target_dict[key] + + key_set = set(list(d1.keys()) + list(d2.keys())) + + return {k: f(set_base_value(d1, d2, k), set_base_value(d2, d1, k)) for k in key_set} + + +def dict_elemwise_sum(): + return dict_op(add) \ No newline at end of file diff --git a/SimCAD/engine/__init__.py b/SimCAD/engine/__init__.py new file mode 100644 index 0000000..4e8bc6d --- /dev/null +++ b/SimCAD/engine/__init__.py @@ -0,0 +1,75 @@ +from pathos.multiprocessing import ProcessingPool as Pool + +from SimCAD.utils import flatten +from SimCAD.configuration import Processor +from SimCAD.configuration.utils import TensorFieldReport +from SimCAD.engine.simulation import Executor as SimExecutor + + +class ExecutionMode: + single_proc = 'single_proc' + multi_proc = 'multi_proc' + + +class ExecutionContext: + def __init__(self, context=ExecutionMode.multi_proc): + self.name = context + self.method = None + + def single_proc_exec(simulation_execs, states_lists, configs_structs, env_processes_list, Ts, Ns): + l = [simulation_execs, states_lists, configs_structs, env_processes_list, Ts, Ns] + simulation, states_list, config, env_processes, T, N = list(map(lambda x: x.pop(), l)) + result = simulation(states_list, config, env_processes, T, N) + return flatten(result) + + def parallelize_simulations(fs, states_list, configs, env_processes, Ts, Ns): + l = list(zip(fs, states_list, configs, env_processes, Ts, Ns)) + with Pool(len(configs)) as p: + results = p.map(lambda t: t[0](t[1], t[2], t[3], t[4], t[5]), l) + return results + + if context == 'single_proc': + self.method = single_proc_exec + elif context == 'multi_proc': + self.method = parallelize_simulations + + +class Executor: + def __init__(self, exec_context, configs): + self.SimExecutor = SimExecutor + self.exec_method = exec_context.method + self.exec_context = exec_context.name + self.configs = configs + self.main = self.execute + + def execute(self): + config_proc = Processor() + create_tensor_field = TensorFieldReport(config_proc).create_tensor_field + + print(self.exec_context+": "+str(self.configs)) + states_lists, Ts, Ns, eps, configs_structs, env_processes_list, mechanisms, simulation_execs = \ + [], [], [], [], [], [], [], [] + config_idx = 0 + for x in self.configs: + states_lists.append([x.state_dict]) + Ts.append(x.sim_config['T']) + Ns.append(x.sim_config['N']) + eps.append(list(x.exogenous_states.values())) + configs_structs.append(config_proc.generate_config(x.state_dict, x.mechanisms, eps[config_idx])) + env_processes_list.append(x.env_processes) + mechanisms.append(x.mechanisms) + simulation_execs.append(SimExecutor(x.behavior_ops).simulation) + + config_idx += 1 + + if self.exec_context == ExecutionMode.single_proc: + tensor_field = create_tensor_field(mechanisms.pop(), eps.pop()) + result = self.exec_method(simulation_execs, states_lists, configs_structs, env_processes_list, Ts, Ns) + return result, tensor_field + elif self.exec_context == ExecutionMode.multi_proc: + if len(self.configs) > 1: + simulations = self.exec_method(simulation_execs, states_lists, configs_structs, env_processes_list, Ts, Ns) + results = [] + for result, mechanism, ep in list(zip(simulations, mechanisms, eps)): + results.append((flatten(result), create_tensor_field(mechanism, ep))) + return results diff --git a/SimCAD/engine/simulation.py b/SimCAD/engine/simulation.py new file mode 100644 index 0000000..9b91402 --- /dev/null +++ b/SimCAD/engine/simulation.py @@ -0,0 +1,92 @@ +from copy import deepcopy +from fn.op import foldr, call +from SimCAD.engine.utils import engine_exception + +id_exception = engine_exception(KeyError, KeyError, None) + + +class Executor: + def __init__(self, behavior_ops, behavior_update_exception=id_exception, state_update_exception=id_exception): + self.behavior_ops = behavior_ops + self.state_update_exception = state_update_exception + self.behavior_update_exception = behavior_update_exception + + def get_behavior_input(self, step, sL, s, funcs): + ops = self.behavior_ops[::-1] + + def get_col_results(step, sL, s, funcs): + return list(map(lambda f: f(step, sL, s), funcs)) + + return foldr(call, get_col_results(step, sL, s, funcs))(ops) + + def apply_env_proc(self, env_processes, state_dict, step): + for state in state_dict.keys(): + if state in list(env_processes.keys()): + env_state = env_processes[state] + if (env_state.__name__ == '_curried') or (env_state.__name__ == 'proc_trigger'): + state_dict[state] = env_state(step)(state_dict[state]) + else: + state_dict[state] = env_state(state_dict[state]) + + def mech_step(self, m_step, sL, state_funcs, behavior_funcs, env_processes, t_step, run): + last_in_obj = sL[-1] + + _input = self.state_update_exception(self.get_behavior_input(m_step, sL, last_in_obj, behavior_funcs)) + + last_in_copy = dict([self.behavior_update_exception(f(m_step, sL, last_in_obj, _input)) for f in state_funcs]) + + for k in last_in_obj: + if k not in last_in_copy: + last_in_copy[k] = last_in_obj[k] + + del last_in_obj + + self.apply_env_proc(env_processes, last_in_copy, last_in_copy['timestamp']) + + last_in_copy["mech_step"], last_in_copy["time_step"], last_in_copy['run'] = m_step, t_step, run + sL.append(last_in_copy) + del last_in_copy + + return sL + + def mech_pipeline(self, states_list, configs, env_processes, t_step, run): + m_step = 0 + states_list_copy = deepcopy(states_list) + genesis_states = states_list_copy[-1] + genesis_states['mech_step'], genesis_states['time_step'] = m_step, t_step + states_list = [genesis_states] + + m_step += 1 + for config in configs: + s_conf, b_conf = config[0], config[1] + states_list = self.mech_step(m_step, states_list, s_conf, b_conf, env_processes, t_step, run) + m_step += 1 + + t_step += 1 + + return states_list + + def block_pipeline(self, states_list, configs, env_processes, time_seq, run): + time_seq = [x + 1 for x in time_seq] + simulation_list = [states_list] + # print(len(configs)) + for time_step in time_seq: + pipe_run = self.mech_pipeline(simulation_list[-1], configs, env_processes, time_step, run) + _, *pipe_run = pipe_run + simulation_list.append(pipe_run) + + return simulation_list + + def simulation(self, states_list, configs, env_processes, time_seq, runs): + pipe_run = [] + for run in range(runs): + run += 1 + states_list_copy = deepcopy(states_list) + head, *tail = self.block_pipeline(states_list_copy, configs, env_processes, time_seq, run) + genesis = head.pop() + genesis['mech_step'], genesis['time_step'], genesis['run'] = 0, 0, run + first_timestep_per_run = [genesis] + tail.pop(0) + pipe_run += [first_timestep_per_run] + tail + del states_list_copy + + return pipe_run \ No newline at end of file diff --git a/SimCAD/engine/utils.py b/SimCAD/engine/utils.py new file mode 100644 index 0000000..bcf1507 --- /dev/null +++ b/SimCAD/engine/utils.py @@ -0,0 +1,33 @@ +from datetime import datetime +from fn.func import curried + + +def datetime_range(start, end, delta, dt_format='%Y-%m-%d %H:%M:%S'): + reverse_head = end + [start, end] = [datetime.strptime(x, dt_format) for x in [start, end]] + + def _datetime_range(start, end, delta): + current = start + while current < end: + yield current + current += delta + + reverse_tail = [dt.strftime(dt_format) for dt in _datetime_range(start, end, delta)] + return reverse_tail + [reverse_head] + + +def last_index(l): + return len(l)-1 + + +def retrieve_state(l, offset): + return l[last_index(l) + offset + 1] + + +@curried +def engine_exception(ErrorType, error_message, exception_function, try_function): + try: + return try_function + except ErrorType: + print(error_message) + return exception_function diff --git a/SimCAD/utils/__init__.py b/SimCAD/utils/__init__.py new file mode 100644 index 0000000..435ee87 --- /dev/null +++ b/SimCAD/utils/__init__.py @@ -0,0 +1,24 @@ +def pipe(x): + return x + + +def print_pipe(x): + print(x) + return x + + +def flatten(l): + return [item for sublist in l for item in sublist] + + +def flatmap(f, items): + return list(map(f, items)) + + +def key_filter(l, keyname): + return [v[keyname] for k, v in l.items()] + + +def rename(new_name, f): + f.__name__ = new_name + return f \ No newline at end of file diff --git a/Simulation.md b/Simulation.md new file mode 100644 index 0000000..81d1ece --- /dev/null +++ b/Simulation.md @@ -0,0 +1,151 @@ +# SimmCAD Documentation + +## Introduction + +A blockchain is a distributed ledger with economic agents transacting in a network. The state of the network evolves with every new transaction, which can be a result of user behaviors, protocol-defined system mechanisms, or external processes. + +It is not uncommon today for blockchain projects to announce a set of rules for their network and make claims about their system level behvaior. However, the validity of those claims is hardly validated. Furthermore, it is difficult to know the potential system-level impact when the network is considering an upgrade to their system rules and prameters. + +To rigorously and reliably analyze, design, and improve cryptoeconomic networks, we are introducing this Computer Aided Design Engine where we define a cryptoeconomic network with its state and exogneous variables, model transactions as a result of agent behaviors, state mechanisms, and environmental processes. We can then run simulations with different initial states, mechanisms, environmental processes to understand and visualize network behavior under different conditions. + +## State Variables and Transitions + +We now define variables and different transition mechanisms that will be inputs to the simulation engine. + +- ***State variables*** are defined to capture the shape and property of the network, such as a vector or a dictionary that captures all user balances. +- ***Exogenous variables*** are variables that represent external input and signal. They are only affected by environmental processes and are not affected by system mechanisms. Nonetheless, exgoneous variables can be used as an input to a mechanism that impacts state variables. They can be considered as read-only variables to the system. +- ***Behaviors per transition*** model agent behaviors in reaction to state variables and exogenous variables. The resulted user action will become an input to state mechanisms. Note that user behaviors should not directly update value of state variables. +- ***State mechanisms per transition*** are system defined mechanisms that take user actions and other states as inputs and produce updates to the value of state variables. +- ***Exogenous state updates*** specify how exogenous variables evolve with time which can indirectly impact state variables through behavior and state mechanisms. +- ***Environmental processes*** model external changes that directly impact state or exogenous variables at specific timestamps or conditions. + +A state evolves to another state via state transition. Each transition is composed of behavior and state mechanisms as functions of state and exogenous variables. A flow of the state transition is as follows. + +Given some state and exogenous variables of the system at the onset of a state transition, agent behavior takes in these variables as input and return a set of agent actions. This models after agent behavior and reaction to a set of variables. Given these agent actions, state mechanism, as defined by the protocol, takes these actions, state, and exogenous variables as inputs and return a new set of state variables. + +## System Configuration File + +Simulation engine takes in system configuration files, e.g. `config.py`, where all the above variables and mechanisms are defined. The following import statements should be added at the beginning of the configuration files. +```python +from decimal import Decimal +import numpy as np +from datetime import timedelta + +from SimCAD import configs +from SimCAD.configuration import Configuration +from SimCAD.configuration.utils import exo_update_per_ts, proc_trigger, bound_norm_random, \ + ep_time_step +``` + +State variables and their initial values can be defined as follows. Note that `timestamp` is a required field for this iteration of SimCAD for `env_proc` to work. Future iterations will strive to make this more generic and timestamp optional. +```python +genesis_dict = { + 's1': Decimal(0.0), + 's2': Decimal(0.0), + 's3': Decimal(1.0), + 'timestamp': '2018-10-01 15:16:24' +} +``` + +Each potential transition and its state and behavior mechanisms can be defined in the following dictionary object. +```python +transitions = { + "m1": { + "behaviors": { + "b1": b1m1, + "b2": b2m1 + }, + "states": { + "s1": s1m1, + "s2": s2m1 + } + }, + "m2": {...} +} +``` +Every behavior per transition should return a dictionary as actions taken by the agents. They will then be aggregated through addition in this version of SimCAD. Some examples of behaviors per transition are as follows. More flexible and user-defined aggregation functions will be introduced in future iterations but no example is provided at this point. +```python +def b1m1(step, sL, s): + return {'param1': 1} + +def b1m2(step, sL, s): + return {'param1': 'a', 'param2': 2} + +def b1m3(step, sL, s): + return {'param1': ['c'], 'param2': np.array([10, 100])} +``` +State mechanism per transition on the other hand takes in the output of behavior mechanisms (`_input`) and returns a tuple of the name of the variable and the new value for the variable. Some examples of a state mechanism per transition are as follows. Note that each state mechanism is supposed to change one state variable at a time. Changes to multiple state variables should be done in separate mechanisms. +```python +def s1m1(step, sL, s, _input): + y = 's1' + x = _input['param1'] + 1 + return (y, x) + +def s1m2(step, sL, s, _input): + y = 's1' + x = _input['param1'] + return (y, x) +``` +Exogenous state update functions, for example `es3p1`, `es4p2` and `es5p2` below, update exogenous variables at every timestamp. Note that every timestamp is consist of all behaviors and state mechanisms in the order defined in `transitions` dictionary. If `exo_update_per_ts` is not used, exogenous state updates will be applied at every mechanism step (`m1`, `m2`, etc). Otherwise, exogenous state updates will only be applied once for every timestamp after all the mechanism steps are executed. +```python +exogenous_states = exo_update_per_ts( + { + "s3": es3p1, + "s4": es4p2, + "timestamp": es5p2 + } +) +``` +To model randomness, we should also define pseudorandom seeds in the configuration as follows. +```python +seed = { + 'z': np.random.RandomState(1), + 'a': np.random.RandomState(2), + 'b': np.random.RandomState(3), + 'c': np.random.RandomState(3) +} +``` +SimCAD currently supports generating random number from a normal distribution through `bound_norm_random` with `min` and `max` values specified. Examples of environmental processes with randomness are as follows. We also define timestamp format with `ts_format` and timestamp changes with `t_delta`. Users can define other distributions to update exogenous variables. +```python +proc_one_coef_A = 0.7 +proc_one_coef_B = 1.3 + +def es3p1(step, sL, s, _input): + y = 's3' + x = s['s3'] * bound_norm_random(seed['a'], proc_one_coef_A, proc_one_coef_B) + return (y, x) + +def es4p2(step, sL, s, _input): + y = 's4' + x = s['s4'] * bound_norm_random(seed['b'], proc_one_coef_A, proc_one_coef_B) + return (y, x) + +ts_format = '%Y-%m-%d %H:%M:%S' +t_delta = timedelta(days=0, minutes=0, seconds=1) +def es5p2(step, sL, s, _input): + y = 'timestamp' + x = ep_time_step(s, s['timestamp'], fromat_str=ts_format, _timedelta=t_delta) + return (y, x) +``` +User can also define specific external events such as market shocks at specific timestamps through `env_processes` with `proc_trigger`. An environmental process with no `proc_trigger` will be called at every timestamp. In the example below, it will return the value of `s3` at every timestamp. Logical event triggers, such as a big draw down in exogenous variables, will be supported in a later version of SimCAD. +```python +def env_a(x): + return x +def env_b(x): + return 10 + +env_processes = { + "s3": env_a, + "s4": proc_trigger('2018-10-01 15:16:25', env_b) +} +``` + +Lastly, we set the overall simulation configuration and initialize the `Configuration` class with the following. `T` denotes the time range and `N` refers to the number of simulation runs. Each run will start from the same initial states and run for `T` time range. Every transition is consist of behaviors, state mechanisms, exogenous updates, and potentially environmental processes. All of these happen within one time step in the simulation. +```python +sim_config = { + "N": 2, + "T": range(5) +} + +configs.append(Configuration(sim_config, state_dict, seed, exogenous_states, env_processes, mechanisms)) +``` diff --git a/demos/sim_test.py b/demos/sim_test.py new file mode 100644 index 0000000..ae58ba4 --- /dev/null +++ b/demos/sim_test.py @@ -0,0 +1,37 @@ +import pandas as pd +from tabulate import tabulate + +# The following imports NEED to be in the exact order +from SimCAD.engine import ExecutionMode, ExecutionContext, Executor +from simulations.validation import config1, config2 +from SimCAD import configs + +exec_mode = ExecutionMode() + + +print("Simulation Execution 1") +print() +first_config = [configs[0]] # from config1 +single_proc_ctx = ExecutionContext(context=exec_mode.single_proc) +run1 = Executor(exec_context=single_proc_ctx, configs=first_config) +run1_raw_result, tensor_field = run1.main() +result = pd.DataFrame(run1_raw_result) +print() +print("Tensor Field:") +print(tabulate(tensor_field, headers='keys', tablefmt='psql')) +print("Output:") +print(tabulate(result, headers='keys', tablefmt='psql')) +print() + +print("Simulation Execution 2: Pairwise Execution") +print() +multi_proc_ctx = ExecutionContext(context=exec_mode.multi_proc) +run2 = Executor(exec_context=multi_proc_ctx, configs=configs) +for raw_result, tensor_field in run2.main(): + result = pd.DataFrame(raw_result) + print() + print("Tensor Field:") + print(tabulate(tensor_field, headers='keys', tablefmt='psql')) + print("Output:") + print(tabulate(result, headers='keys', tablefmt='psql')) + print() \ No newline at end of file diff --git a/demos/test.ipynb b/demos/test.ipynb new file mode 100644 index 0000000..e3c6800 --- /dev/null +++ b/demos/test.ipynb @@ -0,0 +1,137 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "# The following imports NEED to be in the exact order\n", + "from SimCAD.engine import ExecutionMode, ExecutionContext, Executor\n", + "from simulations.validation import config1, config2\n", + "from SimCAD import configs\n", + "\n", + "exec_mode = ExecutionMode()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(\"Simulation Execution 1\")\n", + "print()\n", + "first_config = [configs[0]] # from config1\n", + "single_proc_ctx = ExecutionContext(context=exec_mode.single_proc)\n", + "run1 = Executor(exec_context=single_proc_ctx, configs=first_config)\n", + "run1_raw_result, raw_tensor_field = run1.main()\n", + "result = pd.DataFrame(run1_raw_result)\n", + "tensor_field = pd.DataFrame(raw_tensor_field)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(\"Tensor Field:\")\n", + "tensor_field" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(\"Output:\")\n", + "result" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(\"Simulation Execution 2: Pairwise Execution\")\n", + "print()\n", + "multi_proc_ctx = ExecutionContext(context=exec_mode.multi_proc)\n", + "run2 = Executor(exec_context=multi_proc_ctx, configs=configs)\n", + "results = []\n", + "tensor_fields = []\n", + "for raw_result, raw_tensor_field in run2.main():\n", + " results.append(pd.DataFrame(raw_result))\n", + " tensor_fields.append(pd.DataFrame(raw_tensor_field))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "\n", + "print(\"Tensor Field A:\")\n", + "tensor_fields[0]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(\"Output A:\")\n", + "results[0]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(\"Tensor Field B:\")\n", + "tensor_fields[1]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(\"Output B:\")\n", + "results[1]" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 2", + "language": "python", + "name": "python2" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 2 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython2", + "version": "2.7.6" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..48a300b --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +pathos +fn +tabulate \ No newline at end of file diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..5165a7f --- /dev/null +++ b/setup.py @@ -0,0 +1,23 @@ +from setuptools import setup + +long_description = "SimCAD is a differential games based simulation software package for research, validation, and \ + Computer Aided Design of economic systems. An economic system is treated as a state based model and defined through \ + a set of endogenous and exogenous state variables which are updated through mechanisms and environmental processes, \ + respectively. Behavioral models, which may be deterministic or stochastic, provide the evolution of the system \ + within the action space of the mechanisms. Mathematical formulations of these economic games treat agent utility as \ + derived from state rather than direct from action, creating a rich dynamic modeling framework. Simulations may be \ + run with a range of initial conditions and parameters for states, behaviors, mechanisms, and environmental \ + processes to understand and visualize network behavior under various conditions. Support for A/B testing policies, \ + monte carlo analysis and other common numerical methods is provided." + +setup(name='SimCAD', + version='0.1', + description = "SimCAD: a differential games based simulation software package for research, validation, and \ + Computer Aided Design of economic systems", + long_description=long_description, + url='https://github.com/BlockScience/SimCAD-Beta', + author='Joshua E. Jodesty', + author_email='joshua@block.science', + license='LICENSE.txt', + packages=['SimCAD'], +) \ No newline at end of file diff --git a/simulations/validation/config1.py b/simulations/validation/config1.py new file mode 100644 index 0000000..1d0387e --- /dev/null +++ b/simulations/validation/config1.py @@ -0,0 +1,171 @@ +from decimal import Decimal +import numpy as np +from datetime import timedelta + +from SimCAD import configs +from SimCAD.configuration import Configuration +from SimCAD.configuration.utils import exo_update_per_ts, proc_trigger, bound_norm_random, \ + ep_time_step + + +seed = { + 'z': np.random.RandomState(1), + 'a': np.random.RandomState(2), + 'b': np.random.RandomState(3), + 'c': np.random.RandomState(3) +} + + +# Behaviors per Mechanism +def b1m1(step, sL, s): + return {'param1': 1} +def b2m1(step, sL, s): + return {'param2': 4} + +def b1m2(step, sL, s): + return {'param1': 'a', 'param2': 2} +def b2m2(step, sL, s): + return {'param1': 'b', 'param2': 4} + +def b1m3(step, sL, s): + return {'param1': ['c'], 'param2': np.array([10, 100])} +def b2m3(step, sL, s): + return {'param1': ['d'], 'param2': np.array([20, 200])} + + +# Internal States per Mechanism +def s1m1(step, sL, s, _input): + y = 's1' + x = _input['param1'] + return (y, x) +def s2m1(step, sL, s, _input): + y = 's2' + x = _input['param2'] + return (y, x) + +def s1m2(step, sL, s, _input): + y = 's1' + x = _input['param1'] + return (y, x) +def s2m2(step, sL, s, _input): + y = 's2' + x = _input['param2'] + return (y, x) + +def s1m3(step, sL, s, _input): + y = 's1' + x = _input['param1'] + return (y, x) +def s2m3(step, sL, s, _input): + y = 's2' + x = _input['param2'] + return (y, x) + + +# Exogenous States +proc_one_coef_A = 0.7 +proc_one_coef_B = 1.3 + +def es3p1(step, sL, s, _input): + y = 's3' + x = s['s3'] * bound_norm_random(seed['a'], proc_one_coef_A, proc_one_coef_B) + return (y, x) + +def es4p2(step, sL, s, _input): + y = 's4' + x = s['s4'] * bound_norm_random(seed['b'], proc_one_coef_A, proc_one_coef_B) + return (y, x) + +ts_format = '%Y-%m-%d %H:%M:%S' +t_delta = timedelta(days=0, minutes=0, seconds=1) +def es5p2(step, sL, s, _input): + y = 'timestamp' + x = ep_time_step(s, dt_str=s['timestamp'], fromat_str=ts_format, _timedelta=t_delta) + return (y, x) + + +# Environment States +def env_a(x): + return 5 +def env_b(x): + return 10 +# def what_ever(x): +# return x + 1 + + +# Genesis States +genesis_states = { + 's1': Decimal(0.0), + 's2': Decimal(0.0), + 's3': Decimal(1.0), + 's4': Decimal(1.0), + 'timestamp': '2018-10-01 15:16:24' +} + + +# remove `exo_update_per_ts` to update every ts +exogenous_states = exo_update_per_ts( + { + "s3": es3p1, + "s4": es4p2, + "timestamp": es5p2 + } +) + + +env_processes = { + "s3": env_a, + "s4": proc_trigger('2018-10-01 15:16:25', env_b) +} + + +mechanisms = { + "m1": { + "behaviors": { + "b1": b1m1, + "b2": b2m1 + }, + "states": { + "s1": s1m1, + "s2": s2m1 + } + }, + "m2": { + "behaviors": { + "b1": b1m2, + "b2": b2m2 + }, + "states": { + "s1": s1m2, + "s2": s2m2 + } + }, + "m3": { + "behaviors": { + "b1": b1m3, + "b2": b2m3 + }, + "states": { + "s1": s1m3, + "s2": s2m3 + } + } +} + + +sim_config = { + "N": 2, + "T": range(5) +} + + +configs.append( + Configuration( + sim_config=sim_config, + state_dict=genesis_states, + seed=seed, + exogenous_states=exogenous_states, + env_processes=env_processes, + mechanisms=mechanisms + ) +) \ No newline at end of file diff --git a/simulations/validation/config2.py b/simulations/validation/config2.py new file mode 100644 index 0000000..e4c83c6 --- /dev/null +++ b/simulations/validation/config2.py @@ -0,0 +1,171 @@ +from decimal import Decimal +import numpy as np +from datetime import timedelta + +from SimCAD import configs +from SimCAD.configuration import Configuration +from SimCAD.configuration.utils import exo_update_per_ts, proc_trigger, bound_norm_random, \ + ep_time_step + + +seed = { + 'z': np.random.RandomState(1), + 'a': np.random.RandomState(2), + 'b': np.random.RandomState(3), + 'c': np.random.RandomState(3) +} + + +# Behaviors per Mechanism +def b1m1(step, sL, s): + return {'param1': 1} +def b2m1(step, sL, s): + return {'param2': 4} + +def b1m2(step, sL, s): + return {'param1': 'a', 'param2': 2} +def b2m2(step, sL, s): + return {'param1': 'b', 'param2': 4} + +def b1m3(step, sL, s): + return {'param1': ['c'], 'param2': np.array([10, 100])} +def b2m3(step, sL, s): + return {'param1': ['d'], 'param2': np.array([20, 200])} + + +# Internal States per Mechanism +def s1m1(step, sL, s, _input): + y = 's1' + x = _input['param1'] + return (y, x) +def s2m1(step, sL, s, _input): + y = 's2' + x = _input['param2'] + return (y, x) + +def s1m2(step, sL, s, _input): + y = 's1' + x = _input['param1'] + return (y, x) +def s2m2(step, sL, s, _input): + y = 's2' + x = _input['param2'] + return (y, x) + +def s1m3(step, sL, s, _input): + y = 's1' + x = _input['param1'] + return (y, x) +def s2m3(step, sL, s, _input): + y = 's2' + x = _input['param2'] + return (y, x) + + +# Exogenous States +proc_one_coef_A = 0.7 +proc_one_coef_B = 1.3 + +def es3p1(step, sL, s, _input): + y = 's3' + x = s['s3'] * bound_norm_random(seed['a'], proc_one_coef_A, proc_one_coef_B) + return (y, x) + +def es4p2(step, sL, s, _input): + y = 's4' + x = s['s4'] * bound_norm_random(seed['b'], proc_one_coef_A, proc_one_coef_B) + return (y, x) + +ts_format = '%Y-%m-%d %H:%M:%S' +t_delta = timedelta(days=0, minutes=0, seconds=1) +def es5p2(step, sL, s, _input): + y = 'timestamp' + x = ep_time_step(s, dt_str=s['timestamp'], fromat_str=ts_format, _timedelta=t_delta) + return (y, x) + + +# Environment States +def env_a(x): + return 10 +def env_b(x): + return 10 +# def what_ever(x): +# return x + 1 + + +# Genesis States +genesis_states = { + 's1': Decimal(0.0), + 's2': Decimal(0.0), + 's3': Decimal(1.0), + 's4': Decimal(1.0), + 'timestamp': '2018-10-01 15:16:24' +} + + +# remove `exo_update_per_ts` to update every ts +exogenous_states = exo_update_per_ts( + { + "s3": es3p1, + "s4": es4p2, + "timestamp": es5p2 + } +) + + +env_processes = { + "s3": proc_trigger('2018-10-01 15:16:25', env_a), + "s4": proc_trigger('2018-10-01 15:16:25', env_b) +} + + +mechanisms = { + "m1": { + "behaviors": { + "b1": b1m1, + # "b2": b2m1 + }, + "states": { + "s1": s1m1, + # "s2": s2m1 + } + }, + "m2": { + "behaviors": { + "b1": b1m2, + # "b2": b2m2 + }, + "states": { + "s1": s1m2, + # "s2": s2m2 + } + }, + "m3": { + "behaviors": { + "b1": b1m3, + "b2": b2m3 + }, + "states": { + "s1": s1m3, + "s2": s2m3 + } + } +} + + +sim_config = { + "N": 2, + "T": range(5) +} + + +configs.append( + Configuration( + sim_config=sim_config, + state_dict=genesis_states, + seed=seed, + exogenous_states=exogenous_states, + env_processes=env_processes, + mechanisms=mechanisms + ) +) \ No newline at end of file