documentation update

CHANGELOG.md

@@ -1,16 +1,32 @@
 # Changelog:
 
 ### May 21, 2021
+
+### New Features:
 * **ver. ≥ `0.4.24`:**
-    * **Hot-Fixes:** 
-        * [#257](https://github.com/cadCAD-org/cadCAD/issues/257)
-            * The `append_model` method of `cadCAD.configuration.Experiment` will no longer throw mis-leading error message 
-              during simulation execution.
-        * [#242](https://github.com/cadCAD-org/cadCAD/issues/242)
-            * Parallelized simulations re-enabled with the re-inclusion of `ProcessPool`.
-        * [#250](https://github.com/cadCAD-org/cadCAD/issues/250)
-            * First Partial State Update Block at first timestep no longer equals to 0 instead of the expected 1 in simulation 
-              output.
+    * ##### [Experiments](documentation#experiments)
+        * ##### [System Model Configurations]
+          * Configurations (`cadCAD.utils.Configuration`'s) as are no longer a part of the `cadCAD` module 
+            (as `cadCAD.configs`) and are now accessed via the `configs` member of `cadCAD.configuration.Experiment`.
+            Example: `cadCAD.configuration.Experiment().configs`
+        * `cadCAD.configuration.Experiment` is unique representation of an experiment of one or more configured System 
+        Models. An `Experiment`'s `append_model` method stores multiple system model `Configuration`'s for simulation 
+        execution.
+            * The `Experiment`'s `append_model` method requires a `model_id` parameter that is auto-created as `'sys_model_#'`.
+            * **Requirements:** 
+              * Users must use different `model_id`'s when appending multiple System Model Configurations.
+              * Users can no longer use the `config_list` method of `cadCAD.configuration.Experiment`
+            * **Backwards Compatibility:** The `append_model` method of `cadCAD.configuration.Experiment` can also be used as 
+              the `append_configs` method.
+* **Hot-Fixes:** 
+    * [#257](https://github.com/cadCAD-org/cadCAD/issues/257)
+        * The `append_model` method of `cadCAD.configuration.Experiment` will no longer throw mis-leading error message 
+          during simulation execution.
+    * [#242](https://github.com/cadCAD-org/cadCAD/issues/242)
+        * Parallelized simulations re-enabled with the re-inclusion of `ProcessPool`.
+    * [#250](https://github.com/cadCAD-org/cadCAD/issues/250)
+        * First Partial State Update Block at first timestep no longer equals to 0 instead of the expected 1 in simulation 
+          output.
 
 
 ### September 22, 2020

README.md

@@ -4,7 +4,7 @@
  / ___/ __` / __  / /   / /| | / / / /
 / /__/ /_/ / /_/ / /___/ ___ |/ /_/ /
 \___/\__,_/\__,_/\____/_/  |_/_____/
-by cadCAD                  ver. 0.4.23
+by cadCAD                  ver. 0.4.24
 ======================================
        Complex Adaptive Dynamics       
        o       i        e
@@ -21,7 +21,7 @@ through simulation, with support for Monte Carlo methods, A/B testing and parame
 # Getting Started
 
 
-#### Change Log: [ver. 0.4.23](CHANGELOG.md)
+#### Change Log: [ver. 0.4.24](CHANGELOG.md)
 
 [Previous Stable Release (No Longer Supported)](https://github.com/cadCAD-org/cadCAD/tree/b9cc6b2e4af15d6361d60d6ec059246ab8fbf6da)
 

documentation/Policy_Aggregation.md

@@ -49,7 +49,7 @@ def p2_psu3(_params, step, sH, s, **kwargs):
 from cadCAD.configuration import Experiment
 
 exp = Experiment()
-exp.append_configs(
+exp.append_model(
     sim_configs=???,
     initial_state=???,
     partial_state_update_blocks=???,

documentation/README.md

@@ -12,37 +12,33 @@ cadCAD according to the definitions set by the user in [Partial State Update Blo
 A Simulation Configuration is comprised of a [System Model](#System-Model) and a set of [Simulation Properties](#Simulation-Properties).
 
 ### Experiments
-`cadCAD.configuration.Experiment` (Alpha) is in development and needed to be released to support the development of web 
-applications and proprietary feature extensions to be [Executed](Simulation_Execution.md) by cadCAD. 
-
-It is intended to represent a unique identifier of an experiment of one or more configured System Models / 
-Configurations. For this reason, `append_configs` is a method of `Experiment`.
-
-As of now it does not support multi - system model simulation because configurations are still appended globally despite 
-`append_config` being a method of `Experiment`.
+`cadCAD.configuration.Experiment` is a unique representation of an experiment of one or more configured System Models. 
+The `append_model` method of `Experiment` appends a System Model configurations, each representing a single `run`.
 
 ```python
 from cadCAD.configuration import Experiment
 
 exp = Experiment()
-exp.append_configs(
-    user_id = ..., # OPTIONAL: cadCAD Session User ID
+exp.append_model(
+    model_id = ..., # System Model
     initial_state = ..., # System Model
     partial_state_update_blocks = ..., # System Model
     policy_ops = ..., # System Model
-    sim_configs = ... # Simulation Properties
+    sim_configs = ..., # Simulation Properties
+    user_id = ..., # OPTIONAL: Configuration User ID
 )
 ```
-Parameters: `append_configs`
-* **user_id** : str - OPTIONAL: cadCAD Session User ID
+Parameters: `append_model`
+* **model_id** : str - System Model Identification
 * **initial_state** : _dict_ - [State Variables](#State-Variables) and their initial values
 * **partial_state_update_blocks** : List[dict[dict]] - List of [Partial State Update Blocks](#Partial-State-Update-Blocks)
 * **policy_ops** : List[functions] - See [Policy Aggregation](Policy_Aggregation.md) 
 * **sim_configs** - See [System Model Parameter Sweep](System_Model_Parameter_Sweep.md)
+* **user_id** : str - OPTIONAL: Configuration User ID
 
 ## Simulation Properties
 
-Simulation properties are passed to `append_configs` in the `sim_configs` parameter. To construct this parameter, we 
+Simulation properties are passed to `append_model` in the `sim_configs` parameter. To construct this parameter, we 
 use the `config_sim` function in `cadCAD.configuration.utils`
 
 ```python
@@ -58,7 +54,7 @@ sim_config_dict = {
 c = config_sim(sim_config_dict)
 
 exp = Experiment()
-exp.append_configs(
+exp.append_model(
     ...
     sim_configs = c # Simulation Properties
 )
@@ -105,7 +101,7 @@ absence of any external forces affecting the system. ([source: Wikipedia](https:
 cadCAD can handle state variables of any Python data type, including custom classes. It is up to the user of cadCAD to 
 determine the state variables needed to **sufficiently and accurately** describe the system they are interested in.
 
-State Variables are passed to `append_configs` along with its initial values, as a Python `dict` where the `dict_keys` 
+State Variables are passed to `append_model` along with its initial values, as a Python `dict` where the `dict_keys` 
 are the names of the variables and the `dict_values` are their initial values.
 
 ```python
@@ -119,7 +115,7 @@ genesis_states = {
 }
 
 exp = Experiment()
-exp.append_configs(
+exp.append_model(
     initial_state = genesis_states,
     ...
 )
@@ -207,7 +203,7 @@ impact the State Update Functions and Policy Functions in that PSUB - only those
 
 ![](https://i.imgur.com/9rlX9TG.png)
 
-Partial State Update Blocks are passed to `append_configs` as a List of Python `dicts` where the `dict_keys` are named 
+Partial State Update Blocks are passed to `append_model` as a List of Python `dicts` where the `dict_keys` are named 
 `"policies"` and `"variables"` and the values are also Python `dicts` where the keys are the names of the policy and 
 state update functions and the values are the functions.
 
@@ -233,7 +229,7 @@ PSUBs = [
 ]
 
 exp = Experiment()
-exp.append_configs(
+exp.append_model(
     ...
     partial_state_update_blocks = PSUBs,
     ...

documentation/Simulation_Execution.md

@@ -8,11 +8,11 @@ Configurations. There are multiple simulation Execution Modes and Execution Cont
 `cadCAD` executes a process per System Model Configuration and a thread per System Simulation.
 #### Class: `cadCAD.engine.ExecutionMode`
 #### Attributes:
-* **Local Mode (Default):** Automatically selects Single Threaded or Multi-Process/Threaded Modes (Example: 
+* **Local Mode (Default):** Automatically selects Single Threaded or Multi-Process Modes (Example: 
 `cadCAD.engine.ExecutionMode().local_mode`).
 * **Single Threaded Mode:** A single threaded Execution Mode for a single System Model Configuration (Example: 
 `cadCAD.engine.ExecutionMode().single_mode`).
-* **Multi-Process/Threaded Mode:** Execution Mode for System Model Simulations which executes Multiple threads within 
+* **Multi-Process Mode:** Execution Mode for System Model Simulations which executes Multiple processes within 
 multiple processes per given System Model Configuration (Example: `cadCAD.engine.ExecutionMode().multi_mode`).
 
 ### 2. *Create Execution Context using Execution Mode*
@@ -25,8 +25,8 @@ local_mode_ctx = ExecutionContext(context=exec_mode.local_mode)
 ### 3. *Create Simulation Executor*
 ```python
 from cadCAD.engine import Executor
-from cadCAD import configs
-simulation = Executor(exec_context=local_mode_ctx, configs=configs)
+from ... import exp # import of an instantiated of an `cadCAD.configuration.Experiment` object 
+simulation = Executor(exec_context=local_mode_ctx, configs=exp.configs)
 ```
 
 ### 4. *Execute Simulation & Produce System Event Dataset*
@@ -86,14 +86,14 @@ 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
+from documentation.examples.sys_model_A import exp
 
 exec_mode = ExecutionMode()
 
 # Single Process Execution using a Single System Model Configuration:
 # sys_model_A
 local_mode_ctx = ExecutionContext(context=exec_mode.local_mode)
-sys_model_A_simulation = Executor(exec_context=local_mode_ctx, configs=configs)
+sys_model_A_simulation = Executor(exec_context=local_mode_ctx, configs=exp.configs)
 
 sys_model_A_raw_result, sys_model_A_tensor_field, sessions = sys_model_A_simulation.execute()
 sys_model_A_result = pd.DataFrame(sys_model_A_raw_result)
@@ -119,15 +119,14 @@ 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
+from documentation.examples import sys_model_A, sys_model_B, system_model_AB_exp
 
 exec_mode = ExecutionMode()
 
 # # Multiple Processes Execution using Multiple System Model Configurations:
 # # sys_model_A & sys_model_B
 local_mode_ctx = ExecutionContext(context=exec_mode.local_mode)
-sys_model_AB_simulation = Executor(exec_context=local_mode_ctx, configs=configs)
+sys_model_AB_simulation = Executor(exec_context=local_mode_ctx, configs=system_model_AB_exp.configs)
 
 sys_model_AB_raw_result, sys_model_AB_tensor_field, sessions = sys_model_AB_simulation.execute()
 sys_model_AB_result = pd.DataFrame(sys_model_AB_raw_result)
@@ -148,11 +147,11 @@ from tabulate import tabulate
 
 from cadCAD.engine import ExecutionMode, ExecutionContext, Executor
 from documentation.examples import param_sweep
-from cadCAD import configs
+from documentation.examples.param_sweep import exp
 
 exec_mode = ExecutionMode()
 local_mode_ctx = ExecutionContext(context=exec_mode.local_mode)
-run = Executor(exec_context=local_mode_ctx, configs=configs)
+run = Executor(exec_context=local_mode_ctx, configs=exp.configs)
 
 raw_result, tensor_field, sessions = run.execute()
 result = pd.DataFrame(raw_result)
@@ -162,4 +161,4 @@ print(tabulate(tensor_field, headers='keys', tablefmt='psql'))
 print("Output:")
 print(tabulate(result, headers='keys', tablefmt='psql'))
 print()
-```
+```

documentation/System_Configuration.md

@@ -4,9 +4,9 @@
 
 See [CHANGELOG](CHANGELOG.md)
 
-The `configs` (System Model Configurations) `list` has been **temporarily** flattened to contain single run 
-`Configuration` objects to support elastic workloads. This functionality will be restored in a subsequent release by a 
-class that returns `configs`'s original representation in ver. `0.3.1`.
+The `cadCAD.configuration.Experiment().configs` (System Model Configurations) `list` has been flattened 
+to contain single run `Configuration` objects. This functionality will be restored in a 
+subsequent release by a class that returns the original representation in ver. `0.3.1`.
 * The conversion utilities have been provided to restore its original representation of configurations with 
 runs >= 1
     * System Configuration Conversions:
@@ -28,8 +28,9 @@ Example:
 * `Configuration` objects at `0x10790e470` and `0x1143dd630` are reconstituted into objects at `0x10790e7b8` 
 and `0x116268908` respectively.
 ```python
-from cadCAD import configs
-flattened_configs = configs
+from ... import exp # import of an instantiated `cadCAD.configuration.Experiment` object 
+
+flattened_configs = exp.configs
 
 print('Flattened Format: Temporary')  
 pprint(flattened_configs)

documentation/System_Model_Parameter_Sweep.md

@@ -3,7 +3,7 @@ System Model Parameter Sweep
 Parametrization of a System Model configuration that produces multiple configurations.
 
 ##### Set Parameters
-*Note:* `M` values require up to a maximum of 2 distinct lengths
+*Note:* `params` values require up to a maximum of 2 distinct lengths
 ```python
 params = {
     'alpha': [1],

documentation/examples/__init__.py

@@ -0,0 +1,3 @@
+from cadCAD.configuration import Experiment
+
+system_model_AB_exp = Experiment()

documentation/examples/example_1.py

@@ -4,16 +4,15 @@
 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
+from documentation.examples import sys_model_A, sys_model_B, system_model_AB_exp
+from documentation.examples.sys_model_A import exp
 
 exec_mode = ExecutionMode()
 
 # Single Process Execution using a Single System Model Configuration:
 # sys_model_A
-sys_model_A = [configs[0]]
 local_proc_ctx = ExecutionContext(context=exec_mode.local_mode)
-sys_model_A_simulation = Executor(exec_context=local_proc_ctx, configs=sys_model_A)
+sys_model_A_simulation = Executor(exec_context=local_proc_ctx, configs=exp.configs)
 
 sys_model_A_raw_result, sys_model_A_tensor_field, sessions = sys_model_A_simulation.execute()
 sys_model_A_result = pd.DataFrame(sys_model_A_raw_result)
@@ -27,15 +26,14 @@
 # # 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)
+sys_model_AB_simulation = Executor(exec_context=multi_proc_ctx, configs=system_model_AB_exp.configs)
 
 sys_model_AB_raw_result, sys_model_AB_tensor_field, sessions = sys_model_AB_simulation.execute()
 print()
-pprint(sys_model_AB_raw_result)
-# sys_model_AB_result = pd.DataFrame(sys_model_AB_raw_result)
+sys_model_AB_result = pd.DataFrame(sys_model_AB_raw_result)
 print()
 print(f"Tensor Field:")
 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()
+print("Result: System Events DataFrame:")
+print(tabulate(sys_model_AB_result, headers='keys', tablefmt='psql'))
+print()

documentation/examples/historical_state_access.py

@@ -4,7 +4,6 @@
 from cadCAD.configuration.utils import config_sim, access_block
 from cadCAD.engine import ExecutionMode, ExecutionContext, Executor
 from cadCAD.configuration import Experiment
-from cadCAD import configs
 
 policies, variables = {}, {}
 exclusion_list = ['nonexsistant', 'last_x', '2nd_to_last_x', '3rd_to_last_x', '4th_to_last_x']
@@ -88,15 +87,16 @@ def fourth_to_last_x(_g, substep, sH, s, _input):
 )
 
 exp = Experiment()
-exp.append_configs(
+exp.append_model(
+    model_id='hist_state_access',
     sim_configs=sim_config,
     initial_state=genesis_states,
     partial_state_update_blocks=psubs
 )
 
 exec_mode = ExecutionMode()
 local_proc_ctx = ExecutionContext(context=exec_mode.local_mode)
-run = Executor(exec_context=local_proc_ctx, configs=configs)
+run = Executor(exec_context=local_proc_ctx, configs=exp.configs)
 
 raw_result, tensor_field, sessions = run.execute()
 result = pd.DataFrame(raw_result)
@@ -108,4 +108,4 @@ def fourth_to_last_x(_g, substep, sH, s, _input):
 print(tabulate(tensor_field, headers='keys', tablefmt='psql'))
 print("Output:")
 print(tabulate(result, headers='keys', tablefmt='psql'))
-print()
+print()

documentation/examples/param_sweep.py

@@ -7,7 +7,6 @@
 from cadCAD.configuration.utils import env_trigger, var_substep_trigger, config_sim, psub_list
 from cadCAD.engine import ExecutionMode, ExecutionContext, Executor
 from cadCAD.configuration import Experiment
-from cadCAD import configs
 
 pp = pprint.PrettyPrinter(indent=4)
 
@@ -93,7 +92,8 @@ def sweeped(_params, step, sH, s, _input):
 print()
 
 exp = Experiment()
-exp.append_configs(
+exp.append_model(
+    model_id='param_sweep',
     sim_configs=sim_config,
     initial_state=genesis_states,
     env_processes=env_process,
@@ -102,7 +102,7 @@ def sweeped(_params, step, sH, s, _input):
 
 exec_mode = ExecutionMode()
 local_proc_ctx = ExecutionContext(context=exec_mode.local_mode)
-run = Executor(exec_context=local_proc_ctx, configs=configs)
+run = Executor(exec_context=local_proc_ctx, configs=exp.configs)
 
 raw_result, tensor_field, sessions = run.execute()
 result = pd.DataFrame(raw_result)
@@ -111,4 +111,4 @@ def sweeped(_params, step, sH, s, _input):
 print(tabulate(tensor_field, headers='keys', tablefmt='psql'))
 print("Output:")
 print(tabulate(result, headers='keys', tablefmt='psql'))
-print()
+print()