Merge branch 'main' into mkExRnble

Author: JacquesCarette

.github/ISSUE_TEMPLATE/tmpltMeetIssue.md

@@ -8,15 +8,19 @@ assignees:
  - JacquesCarette
  - smiths
  - sarrasoussia
- - jackwyand
+ - B-rando1
+ - Xinlu-Y
+ - JoeZZG
+ 
 
 ---
 
 **Agenda**
 
 1. Blockers for @sarrasoussia
-
-2. Blockers for @jackwyand
+2. Blockers for @B-rando1 
+3. Blockers for @Xinlu-Y 
+4. Blockers for @JoeZZG 
 
 Regrets:
 

.github/workflows/Build.yaml

@@ -29,7 +29,7 @@ jobs:
     name: "Build & Deploy"
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: "Update apt package list"
         run: |
@@ -65,7 +65,7 @@ jobs:
           stack-version: 'latest'
 
       - name: "Cache dependencies"
-        uses: actions/cache@v4.2.3
+        uses: actions/cache@v4.2.4
         with:
           path: |
             ~/.stack
@@ -127,6 +127,12 @@ jobs:
         run: make mdbook_build
         if: ${{ steps.changes.outputs.md == 'true' || fromJSON(env.is_deployment) }}
 
+      - name: "Extract HTML copies of Jupyter Notebooks"
+        run: |
+          sudo apt-get install -y --fix-missing jupyter
+          make jupyter_html
+        if: ${{ steps.changes.outputs.md == 'true' || fromJSON(env.is_deployment) }}
+
       - name: "Build website generator"
         run: make website
 

.github/workflows/Lint.yaml

@@ -16,7 +16,7 @@ jobs:
     name: "Linter"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       # Prepare more specific paths filters
       - uses: dorny/paths-filter@v3.0.2
@@ -34,7 +34,7 @@ jobs:
         if: ${{ steps.filter.outputs.hs == 'true' }}
         uses: haskell-actions/hlint-setup@v2
         with: # DO NOT MODIFY THE BELOW LINE MANUALLY -- code/scripts/update_default_stackage.sh is in charge of this!
-          version: '3.6.1' # HLINT VERSION TIED TO CURRENT TARGET (LTS-22.31)
+          version: '3.6.1' # HLINT VERSION TIED TO CURRENT TARGET (LTS-22.44)
 
       - name: 'Run HLint'
         if: ${{ steps.filter.outputs.hs == 'true' }}

.github/workflows/Wiki.yaml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'pull_request'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
@@ -49,7 +49,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with: # Fetch enough history to resolve HEAD^ -- https://github.com/actions/checkout?tab=readme-ov-file#checkout-head
           fetch-depth: 2
 

CITATION.cff

@@ -105,3 +105,7 @@ authors:
     given-names: Brandon
     email: "brandobosman@gmail.com"
     website: "https://github.com/B-rando1"
+  - family-names: Wyand
+    given-names: Jack
+    email: "wyandj@mcmaster.ca"
+    website: "https://github.com/jackwyand"

People/JackWyand/Wyand_Jack_2025_Poster.pdf

@@ -78,6 +78,7 @@ INSTALL_E_SUFFIX = _install
 DEBUG_E_SUFFIX = _debug
 MDBOOK_BUILD_E_SUFFIX = _mdbook_build
 MDBOOK_SERVER_E_SUFFIX = _mdbook_server
+JUPYTER_HTML_E_SUFFIX = _juphtml
 
 # add example names with the appropriate suffixes to create per-example targets
 GEN_EXAMPLES = $(addsuffix $(GEN_E_SUFFIX), $(EXAMPLES))
@@ -92,6 +93,7 @@ INSTALL_EXAMPLES = $(addsuffix $(INSTALL_E_SUFFIX), $(EXAMPLES))
 DEBUG_EXAMPLES = $(addsuffix $(DEBUG_E_SUFFIX), $(EXAMPLES))
 MDBOOK_BUILD_EXAMPLES = $(addsuffix $(MDBOOK_BUILD_E_SUFFIX), $(EXAMPLES))
 MDBOOK_SERVER_EXAMPLES = $(addsuffix $(MDBOOK_SERVER_E_SUFFIX), $(EXAMPLES))
+JUPYTER_HTML_EXAMPLES = $(addsuffix $(JUPYTER_HTML_E_SUFFIX), $(EXAMPLES))
 
 # Website names with appropriate suffixes.
 TEST_WEBSITE = $(addsuffix $(TEST_E_SUFFIX), $(WEBSITE_FOLDER_NAME))
@@ -113,6 +115,14 @@ ALL_EXPANDED_TARGETS = $(foreach P, $(PACKAGE_GEN_TARGET), $($(P)_PACKAGES)) $(f
 
 # make variables/configuration
 DIFF = diff --strip-trailing-cr -r -X ../.gitignore --exclude='*.prof' --exclude='.drasil' # Excludes are to ignore the data the 'debug'-related targets generate.
+DIFF_PREFIX ?=
+
+# Run diff and capture both stdout and stderr into a log file. Redirecting
+# stderr to stdout to populate logs when issues with performing the diff occurs
+# (e.g., when `stable/` does not exist).
+# $1: stable path, $2: build path, $3: log path
+DO_DIFF = $(DIFF_PREFIX)$(DIFF) "$1" "$2" > "$3" 2>&1
+
 LOG_SUFFIX = _log.log
 MIN_STACK_VER = 2.3.1  # Match stack.yaml see PR #2142 for more info.
 CACHED_MSV_FILE = .drasil-min-stack-ver
@@ -241,12 +251,15 @@ examples: $(GEN_EXAMPLES) ##@Examples Run all examples (no traceability graphs).
 # First build all the Drasil packages, then run all examples and generate graphs for them.
 tracegraphs: $(TRACE_GRAPH_EXAMPLES) ##@Examples Run examples with traceability graphs.
 
-# First build all the Drasil packages, run all examples (no traceability graphs),
-# and then test the generated contents with those in the stable folder.
-test: $(TEST_EXAMPLES) ##@Examples Run all examples and compare against the stable folder examples.
-	@echo ----------------------------
-	@echo Make complete, checking logs
-	@echo ----------------------------
+# Build all the Drasil packages (via 'code' dep.), run all examples, and then
+# test generated artifacts with stable/. Defer 'diff' exit codes to the log
+# checking script.
+test: code ##@Examples Test examples en masse against stable, only failing at the end if there were diffs.
+	@echo "Running tests (ignoring diff exit codes)..."
+	@$(MAKE) DIFF_PREFIX=- $(TEST_EXAMPLES)
+	@echo ---------------------------------------
+	@echo Tests complete, checking logs
+	@echo ---------------------------------------
 	@LOG_FOLDER="$(LOG_FOLDER)" LOG_SUFFIX="$(LOG_SUFFIX)" NOISY=$(NOISY) "$(SHELL)" "$(SCRIPT_FOLDER)log_check.sh"
 
 # First builds the website and then tests the generated contenst with those in
@@ -287,15 +300,17 @@ packagedeps: graphmod check_dot
 # and then build the generated mdBook projects.
 mdbook_build: $(MDBOOK_BUILD_EXAMPLES) ##@Examples Build all generated mdBook projects.
 
+jupyter_html: $(JUPYTER_HTML_EXAMPLES) ##@Examples Extract HTML copies from all Jupyter SRS Notebooks.
+
 #--------------------------------------------------------------#
 #--- Targets that are used for individual packages/examples ---#
 #--------------------------------------------------------------#
 # Use filter to make a target for every package (second argument of filter)
 # with an appended suffix (first argument of filter).
 
 # Variables needed to create individual example targets using filter.
-%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX): EXAMPLE=$(shell echo $* | tr a-z A-Z)
-%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX): EDIR=$($(EXAMPLE)_DIR)
+%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX) %$(JUPYTER_HTML_E_SUFFIX): EXAMPLE=$(shell echo $* | tr a-z A-Z)
+%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX) %$(JUPYTER_HTML_E_SUFFIX): EDIR=$($(EXAMPLE)_DIR)
 %$(GEN_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX): EEXE=$($(EXAMPLE)_EXE)
 
 # Build individual Drasil packages. Each package will have the target packageName_build.
@@ -313,15 +328,15 @@ $(filter %$(GEN_E_SUFFIX), $(GEN_EXAMPLES)): %$(GEN_E_SUFFIX):
 
 # Compiles GOOL examples to concrete code (Java, C++, etc.)
 $(GOOLTEST)$(GEN_E_SUFFIX):
-	- rm -rf "$(BUILD_FOLDER)$(GOOLTEST_DIR)"
+	rm -rf "./$(BUILD_FOLDER)$(GOOLTEST_DIR)"
 	stack build $(stackArgs) "drasil-code:exe:$(GOOLTEST_EXE)"
 	@mkdir -p "$(BUILD_FOLDER)$(GOOLTEST_DIR)"
 	cd "$(BUILD_FOLDER)$(GOOLTEST_DIR)" && $(STACK_EXEC) -- "$(GOOLTEST_EXE)"
 
 
 $(GOOLTEST)$(TEST_E_SUFFIX): $(GOOLTEST)$(GEN_E_SUFFIX) $(CLEAN_GF_PREFIX)$(LOG_FOLDER_NAME)
 	@mkdir -p "$(LOG_FOLDER)"
-	- $(DIFF) "$(STABLE_FOLDER)$(GOOLTEST_DIR)/" "$(BUILD_FOLDER)$(GOOLTEST_DIR)/" > "$(LOG_FOLDER)$(GOOLTEST_DIR)$(LOG_SUFFIX)"
+	$(call DO_DIFF,$(STABLE_FOLDER)$(GOOLTEST_DIR)/,$(BUILD_FOLDER)$(GOOLTEST_DIR)/,$(LOG_FOLDER)$(GOOLTEST_DIR)$(LOG_SUFFIX))
 	@LOG_FOLDER="$(LOG_FOLDER)" LOG_SUFFIX="$(LOG_SUFFIX)" NOISY=$(NOISY) "$(SHELL)" "$(SCRIPT_FOLDER)log_check.sh"
 
 # Install individual Drasil examples
@@ -350,41 +365,44 @@ $(filter %$(TRACE_GRAPH_SUFFIX), $(TRACE_GRAPH_EXAMPLES)): %$(TRACE_GRAPH_SUFFIX
 # to those in the stable folder. Targets will have the form exampleName_diff.
 $(filter %$(TEST_E_SUFFIX), $(TEST_EXAMPLES)): %$(TEST_E_SUFFIX): $(CLEAN_GF_PREFIX)$(LOG_FOLDER_NAME) %$(GEN_E_SUFFIX)
 	@mkdir -p "$(LOG_FOLDER)"
-	- $(DIFF) "$(STABLE_FOLDER)$*/" "$(BUILD_FOLDER)$(EDIR)/" > "$(LOG_FOLDER)$(EDIR)$(LOG_SUFFIX)"
+	$(call DO_DIFF,$(STABLE_FOLDER)$*/,$(BUILD_FOLDER)$(EDIR)/,$(LOG_FOLDER)$(EDIR)$(LOG_SUFFIX))
 
 # Website diff tests. First builds the website and then compares the generated
 # contents in the Website folder to those in the stable-website folder. 
 # Target will have the form Website_diff.
 $(filter %$(TEST_E_SUFFIX), $(TEST_WEBSITE)): %$(TEST_E_SUFFIX): $(CLEAN_GF_PREFIX)$(LOG_FOLDER_NAME) website
 	@mkdir -p "$(LOG_FOLDER)"
-	- $(DIFF) "$(STABLE_WEBSITE_FOLDER)" "$(WEBSITE_FOLDER)" > "$(LOG_FOLDER)$(WEBSITE_FOLDER_NAME)$(LOG_SUFFIX)"
+	$(call DO_DIFF,$(STABLE_WEBSITE_FOLDER),$(WEBSITE_FOLDER),$(LOG_FOLDER)$(WEBSITE_FOLDER_NAME)$(LOG_SUFFIX))
 
 # Individual example build cleans. Removes a specific example from the build folder.
 # Targets will have the form exampleName_build_clean.
 $(filter %$(BC_E_SUFFIX), $(BC_EXAMPLES)): %$(BC_E_SUFFIX):
-	- rm -rf "$(BUILD_FOLDER)$(EDIR)"
+	rm -rf "./$(BUILD_FOLDER)$(EDIR)"
 
 # The website build cleans. 
 # Target will have the form Website_build_clean
 $(filter %$(BC_E_SUFFIX), $(BC_WEBSITE)): %$(BC_E_SUFFIX):
-	- rm -rf "$(WEBSITE_FOLDER)"
+	rm -rf "./$(WEBSITE_FOLDER)"
 
 # Individual example stabilization. First builds all Drasil packages,
 # runs all examples, and then copies contents from the build folder into stable.
 # Targets will have the form exampleName_stabilize.
 $(filter %$(STABILIZE_E_SUFFIX), $(STABILIZE_EXAMPLES)): %$(STABILIZE_E_SUFFIX): %$(BC_E_SUFFIX) %$(GEN_E_SUFFIX)
-	- rm -rf "$(STABLE_FOLDER)$*/"
+	rm -rf "./$(STABLE_FOLDER)$*/"
+	@mkdir -p "$(STABLE_FOLDER)"
 	- cp -r "$(BUILD_FOLDER)$(EDIR)" "$(STABLE_FOLDER)$*/"
 
 $(GOOLTEST)$(STABILIZE_E_SUFFIX): $(GOOLTEST)$(GEN_E_SUFFIX)
-	- rm -rf "$(STABLE_FOLDER)$(GOOLTEST_DIR)/"
+	rm -rf "./$(STABLE_FOLDER)$(GOOLTEST_DIR)/"
+	@mkdir -p "$(STABLE_FOLDER)"
 	- cp -r "$(BUILD_FOLDER)$(GOOLTEST_DIR)/" "$(STABLE_FOLDER)$(GOOLTEST_DIR)"
 
 # The website stabilization. First builds the website, and then copies the
 # contents from the website folder into stable-website.
 # Target will have the form Website_stabilize.
 $(filter %$(STABILIZE_E_SUFFIX), $(STABILIZE_WEBSITE)): %$(STABILIZE_E_SUFFIX): %$(BC_E_SUFFIX) website
-	- rm -rf "$(STABLE_WEBSITE_FOLDER)"
+	rm -rf "./$(STABLE_WEBSITE_FOLDER)"
+	@mkdir -p "$(STABLE_WEBSITE_FOLDER)"
 	- cp -r "$(WEBSITE_FOLDER)" "$(STABLE_WEBSITE_FOLDER)"
 
 # Generate individual example pdfs. Needs Graphviz to work.
@@ -407,12 +425,16 @@ $(filter %$(MDBOOK_SERVER_E_SUFFIX), $(MDBOOK_SERVER_EXAMPLES)): %$(MDBOOK_SERVE
 	- "$(SHELL)" "$(SCRIPT_FOLDER)copy_example_assets.sh" "$(BUILD_FOLDER)$(EDIR)/SRS/mdBook"
 	mdbook serve --open "$(BUILD_FOLDER)$(EDIR)/SRS/mdBook"
 
+# Targets will have the form exampleName_juphtml.
+$(filter %$(JUPYTER_HTML_E_SUFFIX), $(JUPYTER_HTML_EXAMPLES)): %$(JUPYTER_HTML_E_SUFFIX): %$(GEN_E_SUFFIX)
+	jupyter nbconvert --to html "$(BUILD_FOLDER)$(EDIR)/SRS/Jupyter/*.ipynb"
+
 #----------------------------------------------------------------------------------#
 #--- Generate analysis of module, class, datatype, and class instance structure ---#
 #----------------------------------------------------------------------------------#
 
 graphs: $(GRAPH_PACKAGES) packagedeps ##@Analysis Generate all module dependency graphs.
-	- echo "Graphs generated in local '$(GRAPH_FOLDER)' folder."
+	@echo "Graphs generated in local '$(GRAPH_FOLDER)' folder."
 
 # Generate individual package module dependency graphs.
 $(filter %$(GRAPH_P_SUFFIX), $(GRAPH_PACKAGES)): %$(GRAPH_P_SUFFIX): graphmod check_dot
@@ -424,7 +446,7 @@ $(filter %$(GRAPH_P_SUFFIX), $(GRAPH_PACKAGES)): %$(GRAPH_P_SUFFIX): graphmod ch
 # We also add example to these variables so that we can still
 # make the graphs for that folder (although it's technically not a package itself).
 analysis: graphmod ##@Analysis Generate a table and some graphs to analyze Drasil's class, datatype, and instance structures.
-	- rm -rf "$(ANALYSIS_FOLDER)"
+	rm -rf "./$(ANALYSIS_FOLDER)"
 	@mkdir -p "$(ANALYSIS_FOLDER)"
 	cd $(SCRIPT_FOLDER) && stack ClassInstDepGen.hs
 	cd $(SCRIPT_FOLDER) && stack TypeDepGen.hs
@@ -587,6 +609,7 @@ help:  ##@Help Show this help.
 	@echo "  X$(DCP_E_SUFFIX)  Get all generated code file paths in the example."
 	@echo "  X$(MDBOOK_BUILD_E_SUFFIX)      Build the mdBook SRS of an individual example."
 	@echo "  X$(MDBOOK_SERVER_E_SUFFIX)     Launch local server for the mdBook SRS of an individual example."
+	@echo "  X$(JUPYTER_HTML_E_SUFFIX)           Extract an HTML copy out of a Juypter Notebook."
 	@echo ""
 	@echo "Set a 'DEBUG_ENV' environment variable to 'true' if you want to check out the list of chunks in a Drasil run."
 	@echo ""
@@ -604,4 +627,4 @@ help_packages: ##@Help Lists all packages.
 		echo "  $$package"; \
 	done
 
-.PHONY: help setup_debug_vars clean clean_artifacts cleanArtifacts gool code deps hlint hot_hlint analysis tex doc debug test graphs graphmod check_stack nographs graphs website deploy_code_path deploy deploy_lite all install examples tracegraphs doxygen shellcheck mdbook_build $(GOOLTEST) $(ALL_EXPANDED_TARGETS)
+.PHONY: help setup_debug_vars clean clean_artifacts cleanArtifacts gool code deps hlint hot_hlint analysis tex doc debug test graphs graphmod check_stack nographs graphs website deploy_code_path deploy deploy_lite all install examples tracegraphs doxygen shellcheck mdbook_build jupyter_html $(GOOLTEST) $(ALL_EXPANDED_TARGETS)

People/JackWyand/Wyand_Jack_2025_Poster.pptx

@@ -17,7 +17,7 @@
 #
 # resolver: ./custom-snapshot.yaml
 # resolver: https://example.com/snapshots/2018-01-01.yaml
-resolver: lts-22.31
+resolver: lts-22.44
 
 # User packages to be built.
 # Various formats can be used as shown in the example below.

code/Makefile

@@ -7,13 +7,14 @@ module Data.Drasil.ExternalLibraries.ODELibraries (
   -- * Apache Commons (Java)
   apacheODEPckg, apacheODESymbols,
   -- * Odeint (C++)
-  odeintPckg, odeintSymbols
+  odeintPckg, odeintSymbols, diffCodeChunk,
+  odeInfoChunks
 ) where
 
 import Language.Drasil (HasSymbol(symbol), HasUID(uid), MayHaveUnit(getUnit),
   HasSpace(typ), Space (Actor, Natural, Real, Void, Boolean, String, Array, Vect), implVar, implVar',
   compoundPhrase, nounPhrase, nounPhraseSP, label, sub, Idea(getA), NamedIdea(term), Stage(..),
-  (+++), dccAWDS, dqd', Definition (defn), (+:+), Sentence (S), DefinedQuantityDict, dqdWr)
+  (+++), Definition (defn), (+:+), Sentence (S), DefinedQuantityDict, dqdWr, implVarAU')
 import Language.Drasil.Display (Symbol(Label, Concat))
 
 import Language.Drasil.Code (Lang(..), ExternalLibrary, Step, Argument,
@@ -630,10 +631,10 @@ odeMethodUnavailable = "Chosen ODE solving method is not available" ++
 
 -- | Change in @X@ chunk constructor (where @X@ is a given argument).
 diffCodeChunk :: CodeVarChunk -> CodeVarChunk
-diffCodeChunk c = quantvar $ dqd' (dccAWDS (show $ c +++ "d" )
+diffCodeChunk c = quantvar $ implVarAU' (show $ c +++ "d" )
   (compoundPhrase (nounPhraseSP "change in") (c ^. term)) 
-  (S "the change in" +:+ (c ^. defn)) (getA c)) 
-  (const (Concat [label "d", symbol c Implementation])) (c ^. typ) (getUnit c)
+  (S "the change in" +:+ (c ^. defn)) (getA c) 
+  (c ^. typ) (Concat [label "d", symbol c Implementation]) (getUnit c)
 
 -- FIXME: This is surely a hack, but I can't think of a better way right now.
 -- | Some libraries use an array instead of a list to internally represent the ODE.
@@ -674,3 +675,14 @@ modifiedODESyst sufx info = map replaceDepVar (odeSyst info)
       (replaceDepVar e1) (replaceDepVar e2)
     replaceDepVar (Operator ao dd e)      = Operator ao dd $ replaceDepVar e
     replaceDepVar e = e
+
+-- | Collect all chunks related to a specific ODE
+odeInfoChunks :: ODEInfo -> [DefinedQuantityDict]
+odeInfoChunks info =
+  let dv = depVar info
+  in map dqdWr [ dv
+               , listToArray dv
+               , arrayVecDepVar info
+               , diffCodeChunk dv
+               , listToArray $ diffCodeChunk dv
+               ]