From 4fe3419b23970d3c9fae2d7e98345234953a1fda Mon Sep 17 00:00:00 2001 From: Markus Buhatem Koch <34865315+markusbkoch@users.noreply.github.com> Date: Thu, 19 Sep 2019 22:32:40 -0300 Subject: [PATCH 1/3] Update README.md --- README.md | 174 +++--------------------------------------------------- 1 file changed, 9 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index 00d7355..843df14 100644 --- a/README.md +++ b/README.md @@ -6,173 +6,17 @@ \___/\__,_/\__,_/\____/_/ |_/_____/ by BlockScience ``` +***cadCAD*** is a Python package that assists in the processes of designing, testing and validating complex systems through simulation, with support for Monte Carlo methods, A/B testing and parameter sweeping. -**Introduction:** - -***cadCAD*** is a Python library that assists in the processes of designing, testing and validating complex systems through -simulation. At its core, cadCAD is a differential games engine that supports parameter sweeping and Monte Carlo analyses -and can be easily integrated with other scientific computing Python modules and data science workflows. - -**Description:** - -cadCAD (complex adaptive systems computer-aided design) is a python based, unified modeling framework for stochastic -dynamical systems and differential games for research, validation, and Computer Aided Design of economic systems created -by BlockScience. It is capable of modeling systems at all levels of abstraction from Agent Based Modeling (ABM) to -System Dynamics (SD), and enabling smooth integration of computational social science simulations with empirical data -science workflows. - - -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 the state rather than direct from -an 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. - - -For example, cadCAD tool allows us to represent a company’s or community’s current business model along with a desired -future state and helps make informed, rigorously tested decisions on how to get from today’s stage to the future state. -It allows us to use code to solidify our conceptualized ideas and see if the outcome meets our expectations. We can -iteratively refine our work until we have constructed a model that closely reflects reality at the start of the model, -and see how it evolves. We can then use these results to inform business decisions. - -#### Documentation: -* ##### [Tutorials](tutorials) -* ##### [System Model Configuration](documentation/Simulation_Configuration.md) -* ##### [System Simulation Execution](documentation/Simulation_Execution.md) -* ##### [Policy Aggregation](documentation/Policy_Aggregation.md) -* ##### [System Model Parameter Sweep](documentation/System_Model_Parameter_Sweep.md) - -#### 0. Installation: - -**Python 3.6.5** :: Anaconda, Inc. - -**Option A:** [PyPi](https://pypi.org/project/cadCAD/): pip install +# Getting Started +## 1. Install cadCAD +cadCAD requires [Python 3](https://www.python.org/downloads/) +cadCAD can be installed using Python’s package manager, [pip](https://pypi.org/project/cadCAD/) ```bash pip install cadCAD ``` +## 2. Learn the basics +Check out our tutorials (available both as [Jupyter Notebooks](tutorials) and [videos](https://www.youtube.com/watch?v=uJEiYHRWA9g&list=PLmWm8ksQq4YKtdRV-SoinhV6LbQMgX1we)) to familiarize yourself with some system modelling concepts and cadCAD terminology. Alternatively, go straight to the [documentation](documentation/Simulation_Configuration.md). -**Option B:** Build From Source -```bash -pip3 install -r requirements.txt -python3 setup.py sdist bdist_wheel -pip3 install dist/*.whl -``` - -**Option C:** Proprietary Build Access - -***IMPORTANT NOTE:*** Tokens are issued to those with access to proprietary builds of cadCAD and BlockScience employees **ONLY**. -Replace \ with an issued token in the script below. -```bash -pip3 install pandas pathos fn funcy tabulate -pip3 install cadCAD --extra-index-url https://@repo.fury.io/blockscience/ -``` - - -#### 1. [Configure System Model](documentation/Simulation_Configuration.md) - -#### 2. [Execute Simulations:](documentation/Simulation_Execution.md) - -##### Single Process Execution: -Example System Model Configurations: -* [System Model A](documentation/examples/sys_model_A.py): -`/documentation/examples/sys_model_A.py` -* [System Model B](documentation/examples/sys_model_B.py): -`/documentation/examples/sys_model_B.py` - -Example Simulation Executions: -* [System Model A](documentation/examples/sys_model_A_exec.py): -`/documentation/examples/sys_model_A_exec.py` -* [System Model B](documentation/examples/sys_model_B_exec.py): -`/documentation/examples/sys_model_B_exec.py` - -```python -import pandas as pd -from tabulate import tabulate -from cadCAD.engine import ExecutionMode, ExecutionContext, Executor -from documentation.examples import sys_model_A -from cadCAD import configs - -exec_mode = ExecutionMode() - -# Single Process Execution using a Single System Model Configuration: -# sys_model_A -sys_model_A = [configs[0]] # sys_model_A -single_proc_ctx = ExecutionContext(context=exec_mode.single_proc) -sys_model_A_simulation = Executor(exec_context=single_proc_ctx, configs=sys_model_A) - -sys_model_A_raw_result, sys_model_A_tensor_field = sys_model_A_simulation.execute() -sys_model_A_result = pd.DataFrame(sys_model_A_raw_result) -print() -print("Tensor Field: sys_model_A") -print(tabulate(sys_model_A_tensor_field, headers='keys', tablefmt='psql')) -print("Result: System Events DataFrame") -print(tabulate(sys_model_A_result, headers='keys', tablefmt='psql')) -print() -``` - -##### Multiple Simulations (Concurrent): -###### Multiple Simulation Execution (Multi Process Execution) -System Model Configurations: -* [System Model A](documentation/examples/sys_model_A.py): -`/documentation/examples/sys_model_A.py` -* [System Model B](documentation/examples/sys_model_B.py): -`/documentation/examples/sys_model_B.py` - -[Example Simulation Executions:](documentation/examples/sys_model_AB_exec.py) -`/documentation/examples/sys_model_AB_exec.py` - -```python -import pandas as pd -from tabulate import tabulate -from cadCAD.engine import ExecutionMode, ExecutionContext, Executor -from documentation.examples import sys_model_A, sys_model_B -from cadCAD import configs - -exec_mode = ExecutionMode() - -# # Multiple Processes Execution using Multiple System Model Configurations: -# # sys_model_A & sys_model_B -multi_proc_ctx = ExecutionContext(context=exec_mode.multi_proc) -sys_model_AB_simulation = Executor(exec_context=multi_proc_ctx, configs=configs) - -i = 0 -config_names = ['sys_model_A', 'sys_model_B'] -for sys_model_AB_raw_result, sys_model_AB_tensor_field in sys_model_AB_simulation.execute(): - sys_model_AB_result = pd.DataFrame(sys_model_AB_raw_result) - print() - print(f"Tensor Field: {config_names[i]}") - print(tabulate(sys_model_AB_tensor_field, headers='keys', tablefmt='psql')) - print("Result: System Events DataFrame:") - print(tabulate(sys_model_AB_result, headers='keys', tablefmt='psql')) - print() - i += 1 -``` - -##### Parameter Sweep Simulation (Concurrent): -[Example:](documentation/examples/param_sweep.py) -`/documentation/examples/param_sweep.py` - -```python -import pandas as pd -from tabulate import tabulate -# The following imports NEED to be in the exact order -from cadCAD.engine import ExecutionMode, ExecutionContext, Executor -from documentation.examples import param_sweep -from cadCAD import configs - -exec_mode = ExecutionMode() -multi_proc_ctx = ExecutionContext(context=exec_mode.multi_proc) -run = Executor(exec_context=multi_proc_ctx, configs=configs) - -for raw_result, tensor_field in run.execute(): - 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() -``` +## 3. Connect +Find other cadCAD users at our [Discourse](https://community.cadcad.org/). We are a small but rapidly growing community. From 4e5dca0cf919a57e8c7c79ce3c96c50d273423d3 Mon Sep 17 00:00:00 2001 From: Markus Buhatem Koch <34865315+markusbkoch@users.noreply.github.com> Date: Thu, 19 Sep 2019 22:33:06 -0300 Subject: [PATCH 2/3] Rename Simulation_Configuration.md to README.md --- documentation/{Simulation_Configuration.md => README.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename documentation/{Simulation_Configuration.md => README.md} (100%) diff --git a/documentation/Simulation_Configuration.md b/documentation/README.md similarity index 100% rename from documentation/Simulation_Configuration.md rename to documentation/README.md From 837aad310edcd1276cf7e6270670aa261720777e Mon Sep 17 00:00:00 2001 From: Markus Buhatem Koch <34865315+markusbkoch@users.noreply.github.com> Date: Thu, 19 Sep 2019 22:33:54 -0300 Subject: [PATCH 3/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 843df14..4d85680 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ cadCAD can be installed using Python’s package manager, [pip](https://pypi.org pip install cadCAD ``` ## 2. Learn the basics -Check out our tutorials (available both as [Jupyter Notebooks](tutorials) and [videos](https://www.youtube.com/watch?v=uJEiYHRWA9g&list=PLmWm8ksQq4YKtdRV-SoinhV6LbQMgX1we)) to familiarize yourself with some system modelling concepts and cadCAD terminology. Alternatively, go straight to the [documentation](documentation/Simulation_Configuration.md). +Check out our tutorials (available both as [Jupyter Notebooks](tutorials) and [videos](https://www.youtube.com/watch?v=uJEiYHRWA9g&list=PLmWm8ksQq4YKtdRV-SoinhV6LbQMgX1we)) to familiarize yourself with some system modelling concepts and cadCAD terminology. Alternatively, go straight to the [documentation](documentation). ## 3. Connect Find other cadCAD users at our [Discourse](https://community.cadcad.org/). We are a small but rapidly growing community.