diff --git a/.github/workflows/cadcad-ci.yml b/.github/workflows/cadcad-ci.yml index a574076d..5bf094b8 100644 --- a/.github/workflows/cadcad-ci.yml +++ b/.github/workflows/cadcad-ci.yml @@ -12,6 +12,43 @@ permissions: contents: read jobs: + windows-build: + continue-on-error: true + + runs-on: windows-latest + + strategy: + matrix: + python-version: ["3.9", "3.10", "3.11", "3.12"] + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + + - name: Display Python version + run: python -c "import sys; print(sys.version)" + + - name: Install test and build dependencies + run: | + python -m pip install --upgrade pip + python -m pip install jupyter + pip install -r requirements.txt + + - name: Build cadCAD + shell: cmd + run: | + python setup.py bdist_wheel + for %%x in ("dist\*.whl") do python -m pip install %%x --force-reinstall + + - name: Run tests + run: | + python -m pytest + build: continue-on-error: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f4469a9..5f910569 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,79 +1,88 @@ # Changelog: -### 0.5.0 - December 18 2023 +## 0.5.1 - December 21, 2023 -#### New User Features +### Bugs fixed + +- Fixed a bug where the single_proc mode would result in a missing simulation key ([#332](https://github.com/cadCAD-org/cadCAD/issues/332)); +- Fixed a bug where the single_proc mode would not return results ([#335](https://github.com/cadCAD-org/cadCAD/issues/335)); +- Fixed a wrong parameter order when doing single runs ([#337](https://github.com/cadCAD-org/cadCAD/issues/337)). +- Added a Windows CI pipeline; + +## 0.5.0 - December 20, 2023 + +### New User Features - Added toggle for enabling users to deactivate deepcopying. This is done by passing an additional object on the `ExecutionContext`, eg. `ExecutionContext(mode, additional_objs={'deepcopy_off': True})` -#### New Submodules +### New Submodules - A collection of type annotations for encapsuling `cadCAD` projects is now implemented through the `cadCAD.types` submodules - Added `cadCAD.tools` as a submodule, which is originated from the `cadCAD_tools` Python package. This submodule contains several helper functions for making the simulation experience more straightforward as well as a collection of performance profiling tools. - Added `cadCAD.diagram` as a submodule, which is originated from the `cadCAD_diagram` Python package. This submodule contains functions for programatically generating block diagrams from existing models. - More informative error messages when policies and SUFs are wrongly implemented. (Issues #288 and #258) -#### Backend Improvements +### Backend Improvements - Merged repo with the `cadCAD_legacy_devel`, which includes performance improvements. In particular, simulations will start up faster due to code optimizations. -- `cadCAD` now uses `pytest` as the testing framework. This was made possible by isolating the existing tests and wrapping them into functions. +- `cadCAD` now uses `pytest` as the testing framework. This was made possible by isolating the existing tests and wrapping them into functions. -#### Fixes +### Fixes - cadCAD is now Python 3.10+ compatible (Issue #306 and #301) - Proper support for `ExecutionMode.single_mode` (Issue #253 and #254) -### September 28, 2021 -#### New Features: +## September 28, 2021 +### New Features: * **ver. ≥ `0.4.28`:** - * ##### [Experiments](documentation#experiments) - * ##### System Model Configuration + * #### [Experiments](documentation#experiments) + * #### System Model Configuration * Configurations (`cadCAD.utils.Configuration`'s) are now accessed via the `configs` member of `cadCAD.configuration.Experiment`. [Example:](documentation#experiments) `cadCAD.configuration.Experiment().configs` * `cadCAD.configs` has been re-included for backwards compatibility and has been assigned `cadCAD.experiment.configs` - * ##### Experiments - * `cadCAD.configuration.Experiment()` is unique representation of an experiment of one or more configured System + * #### Experiments + * `cadCAD.configuration.Experiment()` is unique representation of an experiment of one or more configured System Models. - * The `cadCAD` module now contains a default Experiment object `cadCAD.experiment` as an instantiation of + * The `cadCAD` module now contains a default Experiment object `cadCAD.experiment` as an instantiation of `cadCAD.configuration.Experiment()` - * An `Experiment`'s `append_model` method stores multiple system model `Configuration`'s for simulation + * An `Experiment`'s `append_model` method stores multiple system model `Configuration`'s for simulation execution within `cadCAD.configuration.Experiment().configs`. - `cadCAD.configuration.Experiment().model_ids` contains system model labels and/or indexes for + `cadCAD.configuration.Experiment().model_ids` contains system model labels and/or indexes for `cadCAD.configuration.Experiment().configs` - * The `Experiment`'s `append_model` method is defined with `model_id` parameter that accepts a system model + * The `Experiment`'s `append_model` method is defined with `model_id` parameter that accepts a system model label. * If duplicate `model_id`'s are specified, an index is appended to the label after the `@` symbol. - (Example: `cadCAD.configuration.Experiment().model_ids = ['sys_model', 'sys_model@1', 'sys_model@2', ...]`) - * If `model_id`'s are not specified or duplicate, the label is auto-generated as a string indicating the + (Example: `cadCAD.configuration.Experiment().model_ids = ['sys_model', 'sys_model@1', 'sys_model@2', ...]`) + * If `model_id`'s are not specified or duplicate, the label is auto-generated as a string indicating the system model index within `cadCAD.configuration.Experiment().configs`. - (Example of unspecified system models at indexes 1, 3, and 4: + (Example of unspecified system models at indexes 1, 3, and 4: `cadCAD.configuration.Experiment().model_ids = ['sys_model', '1', 'sys_model@2', '3', '4', ...]`) - * ##### [Upgrade Guide:](https://github.com/cadCAD-org/cadCAD/blob/master/documentation/cadCAD-v0.4.28-Model-Upgrade-Guide.md) specific to feature changes / additions + * #### [Upgrade Guide:](https://github.com/cadCAD-org/cadCAD/blob/master/documentation/cadCAD-v0.4.28-Model-Upgrade-Guide.md) specific to feature changes / additions -### August 25, 2021 -#### New Features: +## August 25, 2021 +### New Features: * **ver. ≥ `0.4.27`:** - * ##### [Experiments](documentation#experiments) - * ##### System Model Configurations - * Configurations (`cadCAD.utils.Configuration`'s) as are no longer a part of the `cadCAD` module + * #### [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:](documentation#experiments) `cadCAD.configuration.Experiment().configs` - * ##### Experiments - * `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 + * #### Experiments + * `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:** + * **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 + * **Backwards Compatibility:** The `append_model` method of `cadCAD.configuration.Experiment` can also be used as the `append_configs` method. * Removed [Nix](https://nixos.org/) - * ##### [Upgrade Guide:](https://github.com/cadCAD-org/cadCAD/blob/master/documentation/cadCAD-v0.4.27-Model-Upgrade-Guide.md) specific to feature changes / additions -* **Fixes:** + * #### [Upgrade Guide:](https://github.com/cadCAD-org/cadCAD/blob/master/documentation/cadCAD-v0.4.27-Model-Upgrade-Guide.md) specific to feature changes / additions +* **Fixes:** * [#248](https://github.com/cadCAD-org/cadCAD/issues/248) - * The previous release was returning partial results. An A/B test for this has been included and will be for + * The previous release was returning partial results. An A/B test for this has been included and will be for future releases * [#242](https://github.com/cadCAD-org/cadCAD/issues/242) * Parallelized simulations enabled with the re-inclusion of `ProcessPool`. @@ -83,26 +92,26 @@ * [#252](https://github.com/cadCAD-org/cadCAD/issues/252) * Jupyter lab and Jupyter notebook recognises cadCAD module - -### September 22, 2020 -##### [Multi - System Model Execution](https://github.com/cadCAD-org/cadCAD/blob/master/documentation/Simulation_Execution.md#multiple-simulation-execution) + +## September 22, 2020 +#### [Multi - System Model Execution](https://github.com/cadCAD-org/cadCAD/blob/master/documentation/Simulation_Execution.md#multiple-simulation-execution) * **ver. ≥ `0.4.23`:** * **Hot-Fix:** [#203](https://github.com/cadCAD-org/cadCAD/pull/203) (**No Breaking Changes**) - * Multi - System Model simulation results will no longer return truncated results (exclude the results of the last + * Multi - System Model simulation results will no longer return truncated results (exclude the results of the last `cadCAD.configuration.Configuration` appended to `cadCAD.configs`). * Issue: [#195](https://github.com/cadCAD-org/cadCAD/issues/195) * Parameter Sweep value `M` (Params) requires up to a maximum of 2 distinct lengths -### August 5, 2020 -##### [Experiments](documentation#experiments) -* `cadCAD.configuration.Experiment` (Alpha) is in development and needed to be released to support the implementation of -web applications and proprietary feature extensions. It is intended to represent a unique identifier of an experiment of -one or more configured System Models. For this reason, `append_configs` is a method of -`cadCAD.configuration.Experiment`. As of now it does not support multi - system model simulation because configurations +## August 5, 2020 +#### [Experiments](documentation#experiments) +* `cadCAD.configuration.Experiment` (Alpha) is in development and needed to be released to support the implementation of +web applications and proprietary feature extensions. It is intended to represent a unique identifier of an experiment of +one or more configured System Models. For this reason, `append_configs` is a method of +`cadCAD.configuration.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. -###### Examples: +##### Examples: * **ver. ≥ `0.4.22`:** ```python from cadCAD.configuration import Experiment @@ -116,56 +125,56 @@ are still appended globally despite `append_config` being a method of Experiment ``` -### June 22, 2020 +## June 22, 2020 * Bug Fix: Multiprocessing error for Windows -### June 19, 2020 - -### New Features: -##### [Local Execution Mode (Default)](documentation/Simulation_Execution.md#simulation-execution-modes) -* Local Execution Mode (Default): Implicit parallelization of Monte-Carlo / Stochastic simulations (Automatically +## June 19, 2020 + +## New Features: +#### [Local Execution Mode (Default)](documentation/Simulation_Execution.md#simulation-execution-modes) +* Local Execution Mode (Default): Implicit parallelization of Monte-Carlo / Stochastic simulations (Automatically selects Multi-Threaded Mode if simulations are configured for more than a single run) * **Backwards Compatibility:** `cadCAD.engine.ExecutionMode` accepts legacy execution modes from ver. `0.3.1` - -###### Examples: + +##### Examples: * **ver. ≥ `0.4.22`:** ```python from cadCAD.engine import ExecutionMode, ExecutionContext exec_mode = ExecutionMode() local_ctx = ExecutionContext(context=exec_mode.local_mode) ``` -* **ver. `0.3.1`:** - +* **ver. `0.3.1`:** + Multi-Threaded: ```python from cadCAD.engine import ExecutionMode, ExecutionContext - + exec_mode = ExecutionMode() single_ctx = ExecutionContext(context=exec_mode.multi_proc) ``` - + Single-Thread: ```python from cadCAD.engine import ExecutionMode, ExecutionContext - + exec_mode = ExecutionMode() multi_ctx = ExecutionContext(context=exec_mode.single_proc) ``` - -##### cadCAD Post-Processing Enhancements / Modifications -* [**Single Result Dataset**](documentation/Simulation_Execution.md#4-execute-simulation--produce-system-event-dataset) + +#### cadCAD Post-Processing Enhancements / Modifications +* [**Single Result Dataset**](documentation/Simulation_Execution.md#4-execute-simulation--produce-system-event-dataset) as a 2 dimensional `list` * Returns a single dataset instead of multiple datasets per Monte Carlo simulation as in `0.3.1`: - * New System Metrics as dataset attributes: - * **Simulation** (Alpha) is a unique identifier being developed to represent Experiments as stated above and + * New System Metrics as dataset attributes: + * **Simulation** (Alpha) is a unique identifier being developed to represent Experiments as stated above and will be renamed accordingly * **Subset** is a unique identifier of Monte-Carlo simulations produced by parameter sweeps - * Note: Returning a single dataset was originally specified during the project’s inception instead of multiple per + * Note: Returning a single dataset was originally specified during the project’s inception instead of multiple per simulation -###### Examples: +##### Examples: * **ver. ≥ `0.4.22`:** ```python import pandas as pd @@ -173,12 +182,12 @@ as a 2 dimensional `list` from cadCAD.engine import ExecutionMode, ExecutionContext, Executor import system_model_A, system_model_B from cadCAD import configs - + exec_mode = ExecutionMode() local_ctx = ExecutionContext(context=exec_mode.local_mode) simulation = Executor(exec_context=local_ctx, configs=configs) raw_result, sys_model, _ = simulation.execute() - + result = pd.DataFrame(raw_result) print(tabulate(result, headers='keys', tablefmt='psql')) ``` @@ -204,12 +213,12 @@ as a 2 dimensional `list` from cadCAD.engine import ExecutionMode, ExecutionContext, Executor import system_model_A, system_model_B from cadCAD import configs - + exec_mode = ExecutionMode() - + multi_ctx = ExecutionContext(context=exec_mode.multi_proc) simulation = Executor(exec_context=multi_ctx, configs=configs) - + i = 0 config_names = ['sys_model_A', 'sys_model_B'] for raw_result, _ in simulation.execute(): @@ -235,42 +244,42 @@ as a 2 dimensional `list` | 7 | ['c', 'd'] | [ 30 300] | 5 | 2018-10-01 15:16:25 | 1 | 3 | 1 | +----+------------+-----------+----+---------------------+-----+---------+----------+ ``` - -* **Flattened Configuration list:** The `cadCAD.configs` (System Model Configuration) `list` has been **temporarily** -flattened to contain single run `cadCAD.configuration.Configuration` objects to both fault-tolerant simulation and -elastic workloads. This functionality will be restored in a subsequent release by a class that returns + +* **Flattened Configuration list:** The `cadCAD.configs` (System Model Configuration) `list` has been **temporarily** +flattened to contain single run `cadCAD.configuration.Configuration` objects to both fault-tolerant simulation and +elastic workloads. This functionality will be restored in a subsequent release by a class that returns `cadCAD.configs`'s original representation in ver. `0.3.1`. - * The conversion utilities have been provided to restore its original representation of configurations with + * The conversion utilities have been provided to restore its original representation of configurations with runs >= 1 * [System Configuration Conversions](documentation/System_Configuration.md) - * Configuration as list of Configuration Objects (as in ver. `0.3.1`) + * Configuration as list of Configuration Objects (as in ver. `0.3.1`) * New: System Configuration as a Pandas DataFrame * New: System Configuration as list of Dictionaries - -###### Examples: + +##### Examples: * Notes: - * `configs` is temporarily returned in a flattened format and reformatted into its intended format - * `Configuration` objects at `0x10790e470` and `0x1143dd630` are reconstituted into objects at `0x10790e7b8` + * `configs` is temporarily returned in a flattened format and reformatted into its intended format + * `Configuration` objects at `0x10790e470` and `0x1143dd630` are reconstituted into objects at `0x10790e7b8` and `0x116268908` respectively. -* **ver. ≥ `0.4.22`:** +* **ver. ≥ `0.4.22`:** ```python from pprint import pprint from documentation.examples import sys_model_A, sys_model_B from cadCAD.configuration.utils import configs_as_objs, configs_as_dataframe, configs_as_dicts from cadCAD import configs - + flattened_configs = configs - - print('Flattened Format: Temporary') + + print('Flattened Format: Temporary') pprint(flattened_configs) print() - + print('Intended Format:') intended_configs = configs_as_objs(flattened_configs) pprint(intended_configs) print() ``` - + Result: ```bash Flattened Format: Temporary @@ -278,21 +287,21 @@ elastic workloads. This functionality will be restored in a subsequent release b , , ] - + Intended Format: [, ] ``` -##### Expandable state and policy update parameter space: -* Enables the development of feature enhancements that involve the use of additional parameters without requiring users -to modify their update parameters spaces when upgrading to newer versions. For this reason state / policy update +#### Expandable state and policy update parameter space: +* Enables the development of feature enhancements that involve the use of additional parameters without requiring users +to modify their update parameters spaces when upgrading to newer versions. For this reason state / policy update examples in documentation include an additional `**kwargs` parameter. * [State Updates](documentation/README.md#state-update-functions) * [Policy Updates](documentation/README.md#state-update-functions) - -###### Examples: + +##### Examples: * **ver. ≥ `0.4.22`:** ```python def state_update(_params, substep, sH, s, _input, **kwargs): @@ -316,7 +325,7 @@ examples in documentation include an additional `**kwargs` parameter. ``` -### May 29, 2020 -* Packaging: Add [Nix](https://nixos.org/) derivation and shell for local development and distribution of cadCAD package -using Nix. Nix is a powerful package manager for Linux and other Unix systems that makes package management reliable and +## May 29, 2020 +* Packaging: Add [Nix](https://nixos.org/) derivation and shell for local development and distribution of cadCAD package +using Nix. Nix is a powerful package manager for Linux and other Unix systems that makes package management reliable and reproducible, allowing you to share your development and build environments across different machines. diff --git a/README.md b/README.md index ea165f20..472b00d1 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ / ___/ __` / __ / / / /| | / / / / / /__/ /_/ / /_/ / /___/ ___ |/ /_/ / \___/\__,_/\__,_/\____/_/ |_/_____/ -by cadCAD ver. 0.5.0 +by cadCAD ver. 0.5.1 ====================================== - Complex Adaptive Dynamics + Complex Adaptive Dynamics o i e m d s p e i @@ -15,12 +15,12 @@ by cadCAD ver. 0.5.0 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. +***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 -#### Change Log: [ver. 0.5.0](CHANGELOG.md) +#### Change Log: [ver. 0.5.1](CHANGELOG.md) [Previous Stable Release (No Longer Supported)](https://github.com/cadCAD-org/cadCAD/tree/b9cc6b2e4af15d6361d60d6ec059246ab8fbf6da) @@ -44,10 +44,10 @@ $ source ~/cadcad/bin/activate $ ``` -## 1. Installation: -Requires [>= Python 3.6.13](https://www.python.org/downloads/) +## 1. Installation: +Requires [>= Python 3.9.0](https://www.python.org/downloads/) -**Option A:** Install Using **[pip](https://pypi.org/project/cadCAD/)** +**Option A:** Install Using **[pip](https://pypi.org/project/cadCAD/)** ```bash pip3 install cadCAD ``` diff --git a/cadCAD/__init__.py b/cadCAD/__init__.py index 8a276188..f98d93cd 100644 --- a/cadCAD/__init__.py +++ b/cadCAD/__init__.py @@ -2,7 +2,7 @@ from cadCAD.configuration import Experiment name = "cadCAD" -version = "0.5.0" +version = "0.5.1" experiment = Experiment() configs = experiment.configs diff --git a/setup.py b/setup.py index 785f3aee..f62f37e8 100644 --- a/setup.py +++ b/setup.py @@ -1,45 +1,38 @@ -from setuptools import setup, find_packages +from setuptools import find_packages, setup short_description = "cadCAD: a differential games based simulation software package for research, validation, and \ Computer Aided Design of economic systems" long_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 +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 +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. """ name = "cadCAD" -version = "0.5.0" +version = "0.5.1" -setup(name=name, - version=version, - description=short_description, - long_description=long_description, - url='https://github.com/cadCAD-org/cadCAD', - author='cadCAD-org Developers', - author_email='info@block.science', - license='LICENSE.txt', - packages=find_packages(), - install_requires=[ - "pandas", - "funcy", - "dill", - "pathos", - "numpy", - "pytz", - "six" - ], - python_requires='>=3.8.0' -) \ No newline at end of file +setup( + name=name, + version=version, + description=short_description, + long_description=long_description, + url="https://github.com/cadCAD-org/cadCAD", + author="cadCAD-org Developers", + author_email="info@block.science", + license="LICENSE.txt", + packages=find_packages(), + install_requires=["pandas", "funcy", "dill", "pathos", "numpy", "pytz", "six"], + python_requires=">=3.9.0", +)