Merge pull request #76 from BlockScience/staging

Update README.md

README.md

@@ -1,178 +1,50 @@
 ```
-                    __________   ____ 
+                    __________   ____
   ________ __ _____/ ____/   |  / __ \
  / ___/ __` / __  / /   / /| | / / / /
-/ /__/ /_/ / /_/ / /___/ ___ |/ /_/ / 
+/ /__/ /_/ / /_/ / /___/ ___ |/ /_/ /
-\___/\__,_/\__,_/\____/_/  |_/_____/  
+\___/\__,_/\__,_/\____/_/  |_/_____/
 by BlockScience
+======================================
+       Complex Adaptive Dynamics       
+       o       i        e
+       m       d        s
+       p       e        i
+       u       d        g
+       t                n
+       e
+       r
 ```
+***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:**
+# Getting Started
+## 1. Installation: 
+Requires [Python 3](https://www.python.org/downloads/) 
 
-***cadCAD*** is a Python library that assists in the processes of designing, testing and validating complex systems through 
+**Option A: Install Using [pip](https://pypi.org/project/cadCAD/)** 
-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
 ```bash
-pip install cadCAD
+pip3 install cadCAD
 ```
 
 **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
+ 
+## 2. Learn the basics
+**Tutorials:** available both as [Jupyter Notebooks](tutorials) 
+and [videos](https://www.youtube.com/watch?v=uJEiYHRWA9g&list=PLmWm8ksQq4YKtdRV-SoinhV6LbQMgX1we) 
 
-***IMPORTANT NOTE:*** Tokens are issued to those with access to proprietary builds of cadCAD and BlockScience employees **ONLY**. 
+Familiarize yourself with some system modelling concepts and cadCAD terminology.
-Replace \<TOKEN\> with an issued token in the script below.
-```bash
-pip3 install pandas pathos fn funcy tabulate 
-pip3 install cadCAD --extra-index-url https://<TOKEN>@repo.fury.io/blockscience/
-```
 
+## 3. Documentation:
+* [System Model Configuration](documentation)
+* [System Simulation Execution](documentation/Simulation_Execution.md)
+* [Policy Aggregation](documentation/Policy_Aggregation.md)
+* [System Model Parameter Sweep](documentation/System_Model_Parameter_Sweep.md)
 
-#### 1. [Configure System Model](documentation/Simulation_Configuration.md)
+## 4. Connect
-
+Find other cadCAD users at our [Discourse](https://community.cadcad.org/). We are a small but rapidly growing community.
-#### 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()
-```