Merge pull request #609 from BlockScience/0.3.21

0.3.21

.gitmodules

@@ -7,3 +7,9 @@
 [submodule "examples/MSML-Template"]
 	path = examples/MSML-Template
 	url = https://github.com/BlockScience/MSML-Template
+[submodule "examples/Retirement-Planning-MSML"]
+	path = examples/Retirement-Planning-MSML
+	url = https://github.com/BlockScience/Retirement-Planning-MSML
+[submodule "examples/Predator-Prey-MSML"]
+	path = examples/Predator-Prey-MSML
+	url = https://github.com/BlockScience/Predator-Prey-MSML

README.md

@@ -1,12 +1,14 @@
-# MSML
+# Mathematical Specification Mapping Library (MSML)
+
+For documentation and getting started with MSML, please refer to the site for MSML [here](https://blockscience.github.io/MSML/).
 
 ## What is the Mathematical Specification Mapping Library (MSML)?
 
 MSML is a library for standardizing the creation of mathematical specifications as JSON objects as well as aiding in the automation of report and visualization creation from these standardized JSON. 
 
 It uses block diagram wirings and spaces to represent the actions in complex systems in line with current BlockScience research on Generalized Dynamical Systems. It also adds some enhancements to the primitive blocks to represent richer sets of behaviors.
 
-One good example is the [wiring report](https://github.com/SeanMcOwen/Root-Finding-Simulation/blob/main/MSML/reports/Simulation%20Block.md) for the Root Finding Simulation canonical example.
+One good example is the [wiring report](https://github.com/BlockScience/Predator-Prey-MSML/blob/main/reports/obsidian/Wiring/Hunt%20Prey%20Wiring.md) for hunt prey wiring in the predator prey example (although it is best viewed in Obsidian where all the linking will work).
 
 ## Installing the library
 
@@ -16,6 +18,12 @@ To install the library, simply pip install by running "pip install math_spec_map
 
 Writing mathematical specifications can be a difficult process, especially when variable names are changed or new mechanisms are introduced. MSML seeks to streamline the process with automations as well as enhance the abilities of static math specs to deliver deeper insights. Because it is automated, one can write specifications at different levels of details or for different purposes.
 
+### Stakeholder Communications
+
+- In organizations, senior people / non-developers don't always have as intimate a view of the underlying code as the primary developers in a system because of time constraints and not working as directly with the code as the primary developers
+- Often this means that there is a reliance on asking the primary developers for clarifications and relying on "front-end" kinds of stuff such as visualizations or outputs of the model as opposed to combing through the underlying code
+- MSML seeks to help bridge this gap by allowing for the Obsidian markdown vault that can showcase every component and its dependencies for easier consumption.... this reduces the barriers to entry on understanding the back-end/underlying model
+- Also through things such as code linking, MSML allows for those with code fluency to jump into underlying code if they need to without even opening up the actual project repository
 
 ## What are some of the solutions offered?
 
@@ -64,34 +72,6 @@ Thanks to some of the more advanced features, MSML can be used as an aid for deb
 
 The ability to fork the repository of an MSML spec as well as the ability to use it for A/B testing with the policy options makes it well suited for iterating on model evolution. 
 
-## Technical Details
-
-The documentation on the technical details of using the MSML can be found [here](https://github.com/BlockScience/MSML/tree/main/docs)
-
-## Canonical Examples
-
-[Dummy/Starter Repository](https://github.com/BlockScience/MSML/tree/main/examples/StarterRepo)
-[Root Finding Simulation](https://github.com/SeanMcOwen/Root-Finding-Simulation)
-
-### Comparison of Canonical Example Features
-
-| Feature | Dummy | Root Finding |
-| --- | --- | --- |
-| Action Transmission Channels | X | X |
-| Stack Block | X | X |
-| Parallel Block |  | X |
-| Split Block |  |  |
-| Boundary Actions | X |  |
-| Control Actions | X | X |
-| Entities | X |  |
-| Mechanisms | X | X |
-| Parameters | X | X |
-| Policies | X | X |
-| Spaces | X | X |
-| State | X | X |
-| Stateful Metrics |  |  |
-| State Update Transmission Channels | X | X |
-| Reports | X | X |
 
 ##  Other Related Repositories
 

docs/CanonicalExamples.md

@@ -0,0 +1,29 @@
+---
+title: Canonical Examples
+layout: page
+nav_order: 4
+---
+
+As part of MSML, there are multiple canonical examples which are meant to showcase how the library gets used. The table below describes the features that each one has as well as the level of completion for each.
+
+
+## Comparison of Canonical Examples
+
+| Feature/Attribute | [MSML Template](https://github.com/BlockScience/MSML-Template) | [Predator Prey](https://github.com/BlockScience/Predator-Prey-MSML) | [Root Finding](https://github.com/SeanMcOwen/Root-Finding-Simulation) | [Retirement Planning](https://github.com/BlockScience/Retirement-Planning-MSML) |
+| --- | --- | --- | --- | --- |
+| Description | A template for using MSML. It implements very basic functionality. | An example of building out an agent based simulation for modeling predators and prey based on multiple actions. | A simulation of different root finding techniques and their relative speed/accuracy | A canonical example to showcase how to simulate changing behavioral patterns and their impacts on final results|
+| Spec Implementation Complete? | X | X | WIP | WIP |
+| Code Implementations Complete? | X | X |  | WIP |
+| Simulations/Experiments Complete? | X | WIP|  | |
+| Comes with tutorial? |  |  |  | WIP |
+| Boundary Actions | X | X |  | X |
+| Control Actions | X | X | X | X |
+| Policies | X | X | X | X |
+| Mechanisms | X | X | X | X |
+| Displays | X | X | X | X |
+| Parallel Block | X | X | X | X |
+| Stack Block | X | X | X | X |
+| Split Block |  |  |  |  |
+| Looping Block |  |  |  | WIP |
+| Stateful Metrics| X | X | X | X |
+| Metrics | X | X | X | X |

docs/FAQ.md

@@ -1,7 +1,39 @@
 ---
 title: FAQ
 layout: page
-nav_order: 3
+nav_order: 5
 ---
 
-FAQs
+The following are frequently asked questions with regards to MSML.
+
+## What structure or paradigm is MSML based off of?
+
+- The structure is based off of Generalzied Dynamical Systems but with some semantic additions mainly coming out of past specs that were built at BlockScience
+- This, however, may soon change to be an ontology based version where there is the super class of "Block" and then users bring their own ontologies instead of having blocks defined out as boundary actions, control actions, policies, mechanisms and wirings
+
+## What are the capabilities of MSML?
+
+- Writing a spec that has automated reporting attached to it in the form of an obsidian vault
+- Binding code and trying out running blocks of logic
+- Mini simulations
+- Future capabilities that are in flight including more reporting styles, meta-programming to cadCAD, bigger simulation running and canonical examples
+
+## What deliverables can MSML produce?
+
+- The short answer is the main deliverables can be seen in the [MSML template](https://github.com/BlockScience/MSML-Template), otherwise below are some of the main deliverables
+- Obsidian vault creation for internal development in the beginning and then eventually easily interfacing with clients, markdown files are created for every component for easily zooming in and out of the system
+- Notebooks and paradigms for internal dev of testing and playgrounds for testing out bound code on specs
+- Single simulation and simulation sweep notebooks for creating interfaces that clients can easily modify for running their own experiments as well as setting up experiment notebooks for client deliverables
+
+## What is the difference between MSML and cadCAD?
+
+- The underlying paradigm of GDS is the same but right now cadCAD only does the general block approach and not the semantic enhancements of things like boundary action, but because all the blocks in MSML are still the same block base class they all will function the same in cadCAD
+- Spaces are the same (but with respect to cadCAD 1.0 and not cadCAD legacy)
+- cadCAD should be for running large scale simulations optimized for speed, versus MSML can be used for scaffolding
+- MSML should be better suited for ideation and working through “bread-boarding” before moving on to a stricter paradigm of cadCAD for more optimized simulations
+
+
+## What level of customization does MSML provide?
+
+- The actual writing of specs is very flexible as one can encode nearly anything into them
+- There are future issues to tackle on expanding the customizability of reporting outputs

docs/GettingStarted.md

@@ -4,4 +4,4 @@ nav_order: 2
 layout: page
 ---
 
-Getting started
+Placeholder for getting started guide

docs/TechnicalDocumentation.md

@@ -0,0 +1,7 @@
+---
+title: Technical Documentation
+layout: page
+nav_order: 3
+---
+
+Placeholder for future documentation on all the technical details of MSML

docs/_config.yml

@@ -1,4 +1,4 @@
-title: Mathematical Specification Mapping Library Documentation
+title: Mathematical Specification Mapping Library
 description: Documentation for getting started modeling with MSML
 theme: just-the-docs
 

docs/index.md

@@ -4,4 +4,78 @@ layout: home
 nav_order: 1
 ---
 
-MSML is a library for standardizing the creation of mathematical specifications as JSON objects as well as aiding in the automation of report and visualization creation from these standardized JSON.
+## What is the Mathematical Specification Mapping Library (MSML)?
+
+MSML is a library for standardizing the creation of mathematical specifications as JSON objects as well as aiding in the automation of report and visualization creation from these standardized JSON. 
+
+It uses block diagram wirings and spaces to represent the actions in complex systems in line with current BlockScience research on Generalized Dynamical Systems. It also adds some enhancements to the primitive blocks to represent richer sets of behaviors.
+
+One good example is the [wiring report](https://github.com/BlockScience/Predator-Prey-MSML/blob/main/reports/obsidian/Wiring/Hunt%20Prey%20Wiring.md) for hunt prey wiring in the predator prey example (although it is best viewed in Obsidian where all the linking will work).
+
+## Installing the library
+
+To install the library, simply pip install by running "pip install math_spec_mapping"
+
+## Why MSML?
+
+Writing mathematical specifications can be a difficult process, especially when variable names are changed or new mechanisms are introduced. MSML seeks to streamline the process with automations as well as enhance the abilities of static math specs to deliver deeper insights. Because it is automated, one can write specifications at different levels of details or for different purposes.
+
+### Stakeholder Communications
+
+- In organizations, senior people / non-developers don't always have as intimate a view of the underlying code as the primary developers in a system because of time constraints and not working as directly with the code as the primary developers
+- Often this means that there is a reliance on asking the primary developers for clarifications and relying on "front-end" kinds of stuff such as visualizations or outputs of the model as opposed to combing through the underlying code
+- MSML seeks to help bridge this gap by allowing for the Obsidian markdown vault that can showcase every component and its dependencies for easier consumption.... this reduces the barriers to entry on understanding the back-end/underlying model
+- Also through things such as code linking, MSML allows for those with code fluency to jump into underlying code if they need to without even opening up the actual project repository
+
+## What are some of the solutions offered?
+
+- **Automation**: Automate writing of a specification
+- **Standardization**: Ensure standardization across teams working to spec out a system
+- **Flexibility**: Allow for creating views on the fly and in multiple ways depending on what stakeholders find important
+- **Trackability**: Keep a repository of a JSON file to track changes to the spec with the same enhancements git provides for projects already
+
+## How does MSML work?
+
+
+```mermaid
+graph TD
+A[JSON Object \n\n Each spec has a repo for tracking changes \n Must conform to the json specification \n Defines all aspects of the spec including blocks, spaces and actions] -->B[MSML Object \n\n JSON file is parsed, with validations and mappings along the way \n Can show different views on the fly]
+    B --> C[Report Outputs & Obsidian Directory \n\n Automatically build reports for the full spec or subviews \n Example: all blocks with an effect on variable XYZ\n Also builds an entire Obsidian directory of all components as linked notes]
+D[Python Function Implementations \n\n Optional enhancement to actually execute code\n Done for each referenced policy option, mechanism, etc. \n Just needs a function definition for each] --> B 
+B --> E[Python Wirings & Simulations \n\n MSML can be used to run blocks \n Wirings automatically work to pass between domain/codomains \n Entire simulations can be built up as composed wirings]
+```
+
+## MSML in the Engineering Lifecycle
+
+The engineering lifecycle as defined and visualized in ["Block by Block: Managing Complexity with Model-Based Systems Engineering"
+](https://blog.block.science/block-by-block-managing-complexity-with-model-based-systems-engineering/) is depicted below.
+
+![Systems Engineering Diagram](SystemsEngineering.png)
+
+MSML can aid in all five of these phases in different ways.
+
+### Ideation and Conceptualization
+
+During ideation phases, users of MSML can leverage the markdown writing tool to begin organizing different thoughts into components. For example, if one were trying to model a system that has multiple currencies, i.e. USD and the Euro, those could be added in as MSML types as they are discovered. The markdown report writing supports wiki-links for use in Obsidian or a similar tool allowing users to iteratively catalog different components they find in their research and ideation. 
+
+### Requirements and Design
+
+When moving into requirements and design, MSML provides a suite of reports so that presentations to stakeholders can be insightful but tailored to the different audiences. Feedback can be iteratively incorporated into the spec with reports being re-run.
+
+### Implementation, Integration, and Testing
+
+In its basic form, a spec from MSML can be used to guide implementations because blocks can be transformed into actual code/functions and spaces act as the parameterizations of those functions. There is also experimental work being done on meta-programming so that MSML could either template simulation models or even be used to hold and write code where applicable for things such as A/B testing.
+
+### Operations and Maintenance
+
+Thanks to some of the more advanced features, MSML can be used as an aid for debugging and system validation. The functionality around seeing what parameters effect which blocks directly or downstream indirectly helps developers quickly identify root causes of issues. The linkages between mechanisms and what pieces of state they update allows for developers to quickly see all possible paths to variable changes there are in case something looks amiss.
+
+### Governance and Evolution
+
+The ability to fork the repository of an MSML spec as well as the ability to use it for A/B testing with the policy options makes it well suited for iterating on model evolution. 
+
+
+
+##  Other Related Repositories
+
+[GDS-MSML-cadCAD Repository](https://github.com/BlockScience/GDS-MSML-cadCAD)