math-spec-mapping 0.3.19__tar.gz → 0.3.21__tar.gz

{math_spec_mapping-0.3.19/src/math_spec_mapping.egg-info → math_spec_mapping-0.3.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: math-spec-mapping
-Version: 0.3.19
+Version: 0.3.21
 Summary: A library for easy mapping of mathematical specifications.
 Author-email: Sean McOwen <Sean@Block.Science>
 Classifier: Programming Language :: Python :: 3
@@ -13,7 +13,9 @@ Requires-Dist: graphviz>=0.20.1
 Requires-Dist: ipython>=7.7.0
 Requires-Dist: pandas>=1.4
 
-# 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)?
 
@@ -21,7 +23,7 @@ MSML is a library for standardizing the creation of mathematical specifications
 
 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
 
@@ -31,6 +33,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?
 
@@ -79,34 +87,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
 

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/README.md

@@ -1,4 +1,6 @@
-# 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)?
 
@@ -6,7 +8,7 @@ MSML is a library for standardizing the creation of mathematical specifications
 
 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
 

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 [project]
 name = "math-spec-mapping"
-version = "0.3.19"
+version = "0.3.21"
 authors = [
   { name="Sean McOwen", email="Sean@Block.Science" },
 ]

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/Classes/Block.py

@@ -75,7 +75,7 @@ class Block:
         if self.block_type == "Mechanism":
             for u in sorted(self.updates, key=lambda x: x[0].name + "-" + x[1].name):
                 out += "\n"
-                out += "X{} --> {}".format(
+                out += 'X{} --"State Update"--> {}'.format(
                     i,
                     (u[0].name + "-" + u[1].name).replace(" ", "-"),
                 )
@@ -248,7 +248,7 @@ class ParallelBlock(Block):
                 self.all_updates, key=lambda x: x[0].name + "-" + x[1].name
             ):
                 out += "\n"
-                out += "X{} --> {}".format(
+                out += 'X{} --"State Update"--> {}'.format(
                     i,
                     (u[0].name + "-" + u[1].name).replace(" ", "-"),
                 )
@@ -445,7 +445,7 @@ class StackBlock(Block):
                 self.all_updates, key=lambda x: x[0].name + "-" + x[1].name
             ):
                 out += "\n"
-                out += "X{} --> {}".format(
+                out += 'X{} --"State Update"--> {}'.format(
                     i,
                     (u[0].name + "-" + u[1].name).replace(" ", "-"),
                 )

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/Classes/MathSpec.py

@@ -8,7 +8,7 @@ import os
 from copy import deepcopy
 import shutil
 import pandas as pd
-from inspect import signature, getsource, getfile
+from inspect import signature, getsource, getfile, getsourcelines
 from IPython.display import display, Markdown
 
 
@@ -971,23 +971,31 @@ using .Spaces: generate_space_type
         with open(path, "w") as f:
             f.write(out)
 
-    def build_implementation(self, params):
-        return MathSpecImplementation(self, params)
+    def build_implementation(self, params, domain_codomain_checking=False):
+        return MathSpecImplementation(
+            self, params, domain_codomain_checking=domain_codomain_checking
+        )
 
     def _set_source_code(self):
         if "python" not in self.implementations:
             self.source_code = None
             return
         self.source_code = deepcopy(self.implementations["python"])
+        self.source_code_lines = {}
         for x in self.source_code:
+            self.source_code_lines[x] = {}
             for y in self.source_code[x]:
+                self.source_code_lines[x][y] = "#L{}".format(
+                    getsourcelines(self.source_code[x][y])[1]
+                )
                 self.source_code[x][y] = getsource(self.source_code[x][y])
 
 
 class MathSpecImplementation:
-    def __init__(self, ms: MathSpec, params):
+    def __init__(self, ms: MathSpec, params, domain_codomain_checking):
         self.ms = deepcopy(ms)
         self.params = params
+        self.domain_codomain_checking = domain_codomain_checking
         self.control_actions = self.load_control_actions()
         self.boundary_actions = self.load_boundary_actions()
         self.policies = self.load_policies()
@@ -1323,6 +1331,60 @@ class MathSpecImplementation:
         self.components.update(self.mechanisms)
         self.components.update(self.wiring)
 
+        self.components_enhanced = {}
+
+        def create_wrapper(component, domain_codomain_checking):
+            def wrapper(
+                state,
+                params,
+                spaces,
+                domain_codomain_checking=self.domain_codomain_checking,
+            ):
+                domain = spaces
+
+                # Domain Checking
+                if domain_codomain_checking:
+                    prototype_spaces = self.ms.blocks[component].domain
+                    prototype_spaces = [
+                        x.schema for x in prototype_spaces if x.name != "Empty Space"
+                    ]
+                    assert len(prototype_spaces) == len(
+                        domain
+                    ), "Length of domain incorrect for {}".format(component)
+                    for space1, space2 in zip(domain, prototype_spaces):
+                        assert set(space1.keys()) == set(
+                            space2.keys()
+                        ), "Keys for domain schema of {} is not matched by {} in {} component".format(
+                            set(space2.keys()), set(space1.keys()), component
+                        )
+
+                codomain = self.components[component](state, params, spaces)
+
+                # Codomain Checking
+                if domain_codomain_checking and codomain:
+                    prototype_spaces = self.ms.blocks[component].codomain
+                    prototype_spaces = [
+                        x.schema for x in prototype_spaces if x.name != "Empty Space"
+                    ]
+                    assert len(prototype_spaces) == len(
+                        codomain
+                    ), "Length of codomain incorrect for {}".format(component)
+                    for space1, space2 in zip(codomain, prototype_spaces):
+                        assert set(space1.keys()) == set(
+                            space2.keys()
+                        ), "Keys for codomain schema of {} is not matched by {} in {} component".format(
+                            set(space2.keys()), set(space1.keys()), component
+                        )
+                return codomain
+
+            return wrapper
+
+        for component in self.components:
+
+            self.components_enhanced[component] = create_wrapper(
+                component, self.domain_codomain_checking
+            )
+
     def execute_blocks(self, state, params, blocks):
         for block in blocks:
             self.components[block](state, params, [])

math_spec_mapping-0.3.21/src/math_spec_mapping/Classes/Space.py

@@ -0,0 +1,33 @@
+from typing import Dict
+
+
+class Space:
+    def __init__(self, data: Dict):
+        self.name = data["name"]
+        self.schema = data["schema"]
+        self.metadata = data["metadata"]
+        self.description = data["description"]
+        self.name_variable = self.name.replace(" ", "").replace("-", "_")
+        self.domain_blocks = []
+        self.codomain_blocks = []
+
+    def __repr__(self):
+        return self.name
+
+
+TerminatingSpace = Space(
+    {
+        "name": "Terminating Space",
+        "schema": {},
+        "metadata": {},
+        "description": "Built-in space for denoting termination of block",
+    }
+)
+EmptySpace = Space(
+    {
+        "name": "Empty Space",
+        "schema": {},
+        "metadata": {},
+        "description": "Built-in space for denoting returning no data",
+    }
+)

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/Classes/Type.py

@@ -7,3 +7,6 @@ class Type:
         self.notes = data["notes"]
         self.metadata = data["metadata"]
         self.original_type_name = data["original_type_name"]
+
+    def __repr__(self):
+        return self.name

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/Load/spaces.py

@@ -20,6 +20,9 @@ def convert_space(ms, data: Dict) -> Space:
         )
         data["schema"][x] = ms["Types"][data["schema"][x]]
 
+    if "description" not in data:
+        data["description"] = None
+
     # Build the space object
     return Space(data)
 

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/Load/spec_tree.py

@@ -2,6 +2,18 @@ import ast
 import os
 
 
+def index_to_line_and_column(lines, index):
+    cumulative_length = 0
+    for line_number, line in enumerate(lines):
+        line_length = len(line) + 1  # +1 for the newline character
+        if cumulative_length + line_length > index:
+            column = index - cumulative_length
+            return line_number, column
+        cumulative_length += line_length
+
+    raise ValueError("Index out of range")
+
+
 def load_spec_tree(path, ms):
     tree = {}
     for folder in [
@@ -61,11 +73,20 @@ def load_spec_tree(path, ms):
                     assert False, "Not implemented for imports that are not import from"
                 elif isinstance(node, ast.ImportFrom):
                     if node.module:
-                        for name in node.names:
-                            file_path = "{}/{}/{}.py".format(path, folder, node.module)
-                            with open(file_path, "r") as file2:
-                                contents = file2.read()
-                            for key in keys:
-                                if key in contents:
-                                    tree[folder][key] = os.path.abspath(file_path)
+                        file_path = "{}/{}/{}.py".format(path, folder, node.module)
+
+                        with open(file_path, "r") as file2:
+                            contents = file2.read()
+                        split = contents.split("\n")
+                        for key in keys:
+                            if key in contents:
+                                line_number = (
+                                    index_to_line_and_column(
+                                        split, contents.index(key)
+                                    )[0]
+                                    + 1
+                                )
+                                tree[folder][key] = os.path.abspath(
+                                    file_path
+                                ) + "#L{}".format(line_number)
     return tree

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/Load/stateful_metrics.py

@@ -41,8 +41,8 @@ def convert_stateful_metric(ms, data: Dict) -> StatefulMetricSet:
             )
 
         assert (
-            var["type"] in ms["Types"]
-        ), "{} type referenced by {} is not present in math spec".format(
+            var["type"] in ms["Types"] or var["type"] in ms["Spaces"]
+        ), "{} type/space referenced by {} is not present in math spec".format(
             var["type"], var["name"]
         )
 

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/Reports/markdown.py

@@ -1,6 +1,6 @@
 import os
 from .state import write_state_section
-from inspect import signature, getsource, getfile
+from inspect import signature, getsource, getfile, getsourcelines
 
 
 def get_source_code(
@@ -16,7 +16,7 @@ def get_source_code(
 {}```""".format(
         getsource(code)
     )
-    file_path = getfile(code)
+    file_path = getfile(code) + "#L{}".format(getsourcelines(code)[1])
     return source_code, file_path
 
 
@@ -437,6 +437,13 @@ def write_space_markdown_report(ms, path, space, add_metadata=True):
                 "\n".join(["{}: {}".format(x, metadata[x]) for x in metadata])
             )
 
+    if space.description:
+        out += "## Description"
+        out += "\n"
+        out += space.description
+        out += "\n"
+        out += "\n"
+
     out += "## Schema"
     out += "\n"
     out += "\n"
@@ -858,6 +865,8 @@ def write_state_variables_markdown_reports(ms, path, state, add_metadata=True):
         out += "Description: "
         out += variable.description
         out += "\n\n"
+        out += "Underlying state: [[{}]]".format(state.name)
+        out += "\n\n"
         out += "Type: [["
         out += variable.type.name
         out += "]]\n\n"

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21}/src/math_spec_mapping/schema.schema.json

@@ -441,6 +441,9 @@
                 "name": {
                     "type": "string"
                 },
+                "description": {
+                    "type": "string"
+                },
                 "schema": {
                     "$ref": "./schema.schema.json/#/definitions/Schema"
                 }

{math_spec_mapping-0.3.19 → math_spec_mapping-0.3.21/src/math_spec_mapping.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: math-spec-mapping
-Version: 0.3.19
+Version: 0.3.21
 Summary: A library for easy mapping of mathematical specifications.
 Author-email: Sean McOwen <Sean@Block.Science>
 Classifier: Programming Language :: Python :: 3
@@ -13,7 +13,9 @@ Requires-Dist: graphviz>=0.20.1
 Requires-Dist: ipython>=7.7.0
 Requires-Dist: pandas>=1.4
 
-# 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)?
 
@@ -21,7 +23,7 @@ MSML is a library for standardizing the creation of mathematical specifications
 
 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
 
@@ -31,6 +33,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?
 
@@ -79,34 +87,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
 

math_spec_mapping-0.3.19/src/math_spec_mapping/Classes/Space.py

@@ -1,18 +0,0 @@
-from typing import Dict
-
-
-class Space:
-    def __init__(self, data: Dict):
-        self.name = data["name"]
-        self.schema = data["schema"]
-        self.metadata = data["metadata"]
-        self.name_variable = self.name.replace(" ", "").replace("-", "_")
-        self.domain_blocks = []
-        self.codomain_blocks = []
-
-    def __repr__(self):
-        return self.name
-
-
-TerminatingSpace = Space({"name": "Terminating Space", "schema": {}, "metadata": {}})
-EmptySpace = Space({"name": "Empty Space", "schema": {}, "metadata": {}})