Merge pull request #76 from BlockScience/staging

Update README.md

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to cadCAD (Draft)
+
+:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
+
+The following is a set of guidelines for contributing to cadCAD. These are mostly guidelines, not rules. 
+Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+### Pull Requests:
+
+Pull Request (PR) presented as "->".
+
+General Template:
+fork/branch -> BlockScience/staging
+
+Contributing a new feature:
+fork/feature -> BlockScience/staging
+
+Contributing to an existing feature:
+fork/feature -> BlockScience/feature
+
+Thanks! :heart:

README.md

@@ -1,173 +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. 
+
+# Getting Started
+## 1. Installation: 
+Requires [Python 3](https://www.python.org/downloads/) 
+
+**Option A: Install Using [pip](https://pypi.org/project/cadCAD/)** 
+```bash
+pip3 install cadCAD
 ```
 
-**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:** Build From Source
-```bash
+**Option B:** Build From Source
+```
 pip3 install -r requirements.txt
 python3 setup.py sdist bdist_wheel
 pip3 install dist/*.whl
 ```
 
-**Option B:** 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**. 
-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/
-```
+Familiarize yourself with some system modelling concepts and cadCAD terminology.
 
+## 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)
-
-#### 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()
-```
+## 4. Connect
+Find other cadCAD users at our [Discourse](https://community.cadcad.org/). We are a small but rapidly growing community.

setup.py

@@ -7,7 +7,6 @@ by BlockScience. It is capable of modeling systems at all levels of abstraction
 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. 
@@ -19,7 +18,7 @@ provided.
 """
 
 setup(name='cadCAD',
-      version='0.3.0',
+      version='0.3.1',
       description="cadCAD: a differential games based simulation software package for research, validation, and \
         Computer Aided Design of economic systems",
       long_description=long_description,
@@ -27,5 +26,13 @@ setup(name='cadCAD',
       author='Joshua E. Jodesty',
       author_email='joshua@block.science, joshua.jodesty@gmail.com',
       license='LICENSE.txt',
-      packages=find_packages()
-)
+      packages=find_packages(),
+      install_requires=[
+            "pandas",
+            "wheel",
+            "pathos",
+            "fn",
+            "tabulate",
+            "funcy"
+      ]
+)