Merge pull request #642 from BlockScience/0.4.3

0.4.3

Author: SeanMcOwen

docs/1 Overview.md

@@ -1,7 +1,7 @@
 ---
 title: Canonical Examples
 layout: page
-nav_order: 4
+nav_order: 7
 ---
 
 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.

docs/4 JSON Specification.md

@@ -1,7 +1,7 @@
 ---
 title: FAQ
 layout: page
-nav_order: 6
+nav_order: 9
 ---
 
 The following are frequently asked questions with regards to MSML.

docs/CanonicalExamples.md

@@ -1,3 +1,9 @@
+---
+title: GDS Fundamentals
+nav_order: 2
+layout: page
+---
+
 # GDS Fundamentals
 
 For more information with regards to the GDS fundamentals, one can look at this [repository](https://github.com/BlockScience/GDS-MSML-cadCAD). Below is abbreviated documentation describing the fundamentals of Generalized Dynamical Systems (GDS).

docs/FAQ.md

@@ -1,11 +1,13 @@
 ---
 title: Getting Started
-nav_order: 2
+nav_order: 4
 layout: page
 ---
 
 Getting started with your first MSML specification can seem like a daunting task but this short guide will hopefully make it easier.
 
+If you want to view the in-depth JSON specification you can find it here [here](./JSON-Specification/README). This is what is passed to MSML to create the specification object.
+
 ## 1. Review the Concepts
 
 - Within this documentation, you can find specific technical documentation including the background theory and the components under "Technical Documentation"

docs/2 GDS Fundamentals.md renamed to docs/GDS Fundamentals.md

@@ -1,3 +1,9 @@
+---
+title: MSML Enhancements
+nav_order: 3
+layout: page
+---
+
 # MSML Enhancements
 
 MSML provides certain enhancements beyond the generalized blocks and spaces that can be utilized when building out specifications.

docs/GettingStarted.md

@@ -0,0 +1,14 @@
+---
+title: Reports
+layout: page
+nav_order: 6
+---
+
+MSML has a variety of reports that can be produced in markdown files which can also be converted to PDF.
+
+## PDF Conversion
+
+- To use PDF conversion, a few other things need to be installed
+- One must install pandoc, which can be done with "brew install pandoc" on a mac
+- Installing pdflatex might be required which can be done with "brew install --cask basictex" on a mac
+- If the pdflatex path is not recognized by the system, you may need to pass the path to it. For example, on a mac this would be: pdflatex_path='/Library/TeX/texbin/pdflatex'

docs/3 MSML Enhancements.md renamed to docs/MSML Enhancements.md

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

docs/Reports.md

@@ -11,5 +11,10 @@ defaults:
     values:
       layout: "default"
 
+mermaid:
+  # Version of mermaid library
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+  version: "9.1.3"
+
 aux_links:
   MSML Repository Repository: https://github.com/BlockScience/MSML

docs/TechnicalDocumentation.md

@@ -1,7 +1,7 @@
 ---
 title: cadCAD Builder
 layout: page
-nav_order: 5
+nav_order: 8
 ---
 
 MSML provides interfaces for creating cadCAD style models that don't require end users poking around the actual code to use. The idea is that it provides a layer for data scientists to experiment just with toggling starting state and parameters and executing pre-packaged models.

docs/_config.yml

@@ -36,8 +36,13 @@ Writing mathematical specifications can be a difficult process, especially when
 
 ## How does MSML work?
 
-
-![mermaid](mermaid.png)
+```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
 

docs/cadCADBuilder.md

@@ -3,7 +3,7 @@ requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 [project]
 name = "math-spec-mapping"
-version = "0.4.2"
+version = "0.4.3"
 authors = [
   { name="Sean McOwen", email="[email protected]" },
 ]
@@ -14,7 +14,8 @@ dependencies = [
   "pandas>=1.4",
   "jsonschema>=4.21.1",
   "PyGithub==2.5.0",
-  "python-dotenv>=1.0.0"
+  "python-dotenv>=1.0.0",
+  "pypandoc>=1.15",
 ]
 readme = "README.md"
 requires-python = ">=3.7"

docs/index.md

@@ -3,4 +3,5 @@ ipython>=7.7.0
 pandas>=1.4
 jsonschema>=4.21.1
 PyGithub==2.5.0
-python-dotenv>=1.0.0
+python-dotenv>=1.0.0
+pypandoc>=1.15

pyproject.toml

@@ -0,0 +1,17 @@
+# Advanced Reports
+
+1. Glossary
+
+## Glossary
+
+- An advanced report which just lists out the components and their descripitions.
+
+## Parameter Impact Report
+
+- Given a parameter will show all directly affected blocks and all downstream blocks
+- Likely will want to use a mermaid rendering for the blocks impacted
+
+## State Variable Impact Report
+
+- Given a state variable, will map out all the paths to modifying it
+- Can do recursive things to figure out what wirings or policies are upstream from it

requirements.txt

@@ -2,7 +2,7 @@
 from .boundary_actions import write_out_boundary_actions
 from .policies import write_out_policies
 from .mechanisms import write_out_mechanisms
-from .general import load_svg_graphviz
+from .general import load_svg_graphviz, convert_markdown_to_pdf
 from .html import (
     write_basic_report_full,
     write_action_chain_reports,
@@ -32,3 +32,4 @@
     write_initial_state_variables_tables,
 )
 from .parameters import write_parameter_table_markdown
+from .advanced import write_glossary_report

research_notes/2025-02-11 Advanced Reports.md

@@ -0,0 +1,57 @@
+from ..Classes import MathSpec
+from .state import write_state_section
+
+
+def write_glossary_report(ms: MathSpec, directory: str) -> None:
+    """Function to write a report of each component and its description in MSML
+
+    Args:
+        ms (MathSpec): The mathematical specification object
+        directory (str): Directory to put reports into
+    """
+    out = "# Glossary\n\n"
+
+    out += "## Entities\n\n"
+    for entity in ms.entities:
+        if entity == "Global":
+            continue
+        entity = ms.entities[entity]
+        out += "**{}**: {}".format(entity.name, entity.notes)
+        out += "\n\n"
+    out += "\n"
+
+    out += "## State\n\n"
+    states = list(ms.state.keys())
+    states.remove("Global State")
+    states = ["Global State"] + states
+    for state in states:
+        out += "### {}\n\n".format(state)
+        out += write_state_section(ms.state[state])
+        out += "\n\n"
+    out += "\n\n"
+
+    for name, component in [
+        ["Types", ms.types],
+        ["Spaces", ms.spaces],
+        ["Boundary Actions", ms.boundary_actions],
+        ["Control Actions", ms.control_actions],
+        ["Policies", ms.policies],
+        ["Mechanisms", ms.mechanisms],
+        ["Wiring", ms.wiring],
+        ["Parameters", ms.parameters.parameter_map],
+        ["Stateful Metrics", ms.stateful_metrics],
+        ["Metrics", ms.metrics],
+    ]:
+        out += "## {}\n\n".format(name)
+        for key in component:
+            if hasattr(component[key], "description"):
+                desc = component[key].description
+            else:
+                desc = component[key].notes
+
+            out += "**{}**: {}\n\n".format(key, desc)
+        out += "\n\n"
+
+    path = directory + "/Glossary.md"
+    with open(path, "w") as f:
+        f.write(out)

src/math_spec_mapping/Reports/__init__.py

@@ -1,5 +1,6 @@
 from graphviz import Digraph
 import os
+import pypandoc
 
 
 def load_svg_graphviz(graph: Digraph, overwrite: bool = False) -> str:
@@ -23,7 +24,7 @@ def load_svg_graphviz(graph: Digraph, overwrite: bool = False) -> str:
         assert "{}.gv".format(graph.name) not in os.listdir(".")
 
     # Render the graph
-    graph.render(directory=".", format='svg')
+    graph.render(directory=".", format="svg")
 
     # Read the svg
     with open("./{}.gv.svg".format(graph.name), "r") as f:
@@ -35,6 +36,7 @@ def load_svg_graphviz(graph: Digraph, overwrite: bool = False) -> str:
 
     return svg
 
+
 def write_header() -> str:
     out = '<p>For explanations of generalized dynamical systems as well as how the mathematical specification library works in detail, please consult the documentation <a href="https://github.com/BlockScience/MSML/tree/main/docs">here</a></p>'
     out += "Graph Legend:<br/>"
@@ -43,4 +45,20 @@ def write_header() -> str:
     out += "Red Square: Policy<br/>"
     out += "Blue Circle: Mechanism<br/>"
     out += "Transparent Circle: State Variable"
-    return out
+    return out
+
+
+def convert_markdown_to_pdf(md_path, pdf_path, pdflatex_path=None):
+    if pdflatex_path:
+        pypandoc.convert_file(
+            md_path,
+            "pdf",
+            outputfile=pdf_path,
+            extra_args=["--pdf-engine={}".format(pdflatex_path)],
+        )
+    else:
+        pypandoc.convert_file(
+            md_path,
+            "pdf",
+            outputfile=pdf_path,
+        )

src/math_spec_mapping/Reports/advanced.py

@@ -28,6 +28,8 @@
     write_state_variable_table_markdown,
     write_initial_state_variables_tables,
     write_parameter_table_markdown,
+    write_glossary_report,
+    convert_markdown_to_pdf,
 )
 from .schema import schema
 from .Convenience import (