From b1f0b0ba1be97da9a93076b4f04eda002553ff53 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 09:52:26 -0500 Subject: [PATCH 01/13] Begin fixed state and fixed parameters --- pyproject.toml | 2 +- src/math_spec_mapping/Classes/MathSpec.py | 25 +++++++++++++++++++++-- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 33cd362..0bd9951 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "math-spec-mapping" -version = "0.4.1.2" +version = "0.4.2" authors = [ { name="Sean McOwen", email="Sean@Block.Science" }, ] diff --git a/src/math_spec_mapping/Classes/MathSpec.py b/src/math_spec_mapping/Classes/MathSpec.py index d17bd1d..c4149a3 100644 --- a/src/math_spec_mapping/Classes/MathSpec.py +++ b/src/math_spec_mapping/Classes/MathSpec.py @@ -1041,10 +1041,25 @@ def build_cadCAD( blocks, state_preperation_functions=[], parameter_preperation_functions=[], + fixed_parameters=None, + fixed_state=None, ): out = {} out["StateSpace"] = self._build_state_space() + if fixed_state: + for key in fixed_state: + assert ( + key in out["StateSpace"] + ), "The fixed parameter {} is not in the state space".format(key) + out["StateSpace"].pop(key) + out["ParameterSpace"] = self._build_parameter_space() + if fixed_parameters: + for key in fixed_parameters: + assert ( + key in out["ParameterSpace"] + ), "The fixed parameter {} is not in the parameter space".format(key) + out["ParameterSpace"].pop(key) out["Model"] = cadCADModel( self, out["StateSpace"], @@ -1052,6 +1067,8 @@ def build_cadCAD( blocks, state_preperation_functions=state_preperation_functions, parameter_preperation_functions=parameter_preperation_functions, + fixed_parameters=fixed_parameters, + fixed_state=fixed_state, ) return out @@ -1079,6 +1096,8 @@ def __init__( blocks, state_preperation_functions=[], parameter_preperation_functions=[], + fixed_parameters=None, + fixed_state=None, ): self.ms = ms self.state_space = state_space @@ -1086,6 +1105,8 @@ def __init__( self.blocks = blocks self.state_preperation_functions = state_preperation_functions self.parameter_preperation_functions = parameter_preperation_functions + self.fixed_parameters = fixed_parameters + self.fixed_state = fixed_state def create_experiment( self, state, params, record_trajectory=False, use_deepcopy=True @@ -1180,11 +1201,11 @@ def __init__(self, model, state, params, ms, record_trajectory, use_deepcopy=Tru def step(self): for experiment in self.experiments: experiment.step() - + def run(self, t): for experiment in self.experiments: experiment.run(t) - + @property def trajectories(self): return [experiment.trajectories for experiment in self.experiments] From 2d9847cec09a7d7ce4f13c730628c39017441fe5 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 12:15:42 -0500 Subject: [PATCH 02/13] Finish up fixed state and fixed parameters --- src/math_spec_mapping/Classes/MathSpec.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/math_spec_mapping/Classes/MathSpec.py b/src/math_spec_mapping/Classes/MathSpec.py index c4149a3..3972b05 100644 --- a/src/math_spec_mapping/Classes/MathSpec.py +++ b/src/math_spec_mapping/Classes/MathSpec.py @@ -1111,6 +1111,12 @@ def __init__( def create_experiment( self, state, params, record_trajectory=False, use_deepcopy=True ): + if self.fixed_state: + for x in self.fixed_state: + state[x] = self.fixed_state[x] + if self.fixed_parameters: + for x in self.fixed_parameters: + params[x] = self.fixed_parameters[x] return Experiment( self, state, From 7cef90b2b9ac60bab7ee6ee0856a7602c2a5f85f Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 12:21:36 -0500 Subject: [PATCH 03/13] Concept spec schema --- research_notes/WIP Concept Specs.md | 30 +++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 research_notes/WIP Concept Specs.md diff --git a/research_notes/WIP Concept Specs.md b/research_notes/WIP Concept Specs.md new file mode 100644 index 0000000..af10257 --- /dev/null +++ b/research_notes/WIP Concept Specs.md @@ -0,0 +1,30 @@ +# Concept Specs Ideation + + +## Proposed JSON Schema + +### Space + +1. Name: PrimaryKey, string +2. Description: Optional, string + +### Block + +1. Name: PrimaryKey, string +2. Description: Optional, string +3. Domain: ForeignKeys to Space.Name, List[string] +4. Codomain: ForeignKeys to Space.Name, List[string] + +### Wiring + +#### Option 1: + +1. Source: string, such as "BlockA-1" for second port of BlockA codomain +2. Target: string, such as "BlockB-0" for first port of BlockB domain + +#### Option 2: + +1. SourceBlock: ForeignKey to Block.Name, string +2. TargetBlock: ForeignKey to Block.Name, string +3. Source Port: Related to SourceBlock.Codomain as the index, integer +4. Target Port: Related to TargetBlock.Domain as the index, integer \ No newline at end of file From 07ea46fa16a4eb84f6bce3fdda4ad4e2b1de61b3 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 12:30:30 -0500 Subject: [PATCH 04/13] Finish concept math spec ideation --- research_notes/WIP Concept Specs.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/research_notes/WIP Concept Specs.md b/research_notes/WIP Concept Specs.md index af10257..bc2b730 100644 --- a/research_notes/WIP Concept Specs.md +++ b/research_notes/WIP Concept Specs.md @@ -1,5 +1,10 @@ -# Concept Specs Ideation +# Concept Math Specs Ideation +## Executive Summary + +- The following research note defines out the most parsimonious schemas and relations for a concept math spec +- The idea is that this can be further enhanced and plugged into other interoperable workflows +- For example, schemas for the spaces can be added in at a further point and potentially have specified types ## Proposed JSON Schema @@ -27,4 +32,16 @@ 1. SourceBlock: ForeignKey to Block.Name, string 2. TargetBlock: ForeignKey to Block.Name, string 3. Source Port: Related to SourceBlock.Codomain as the index, integer -4. Target Port: Related to TargetBlock.Domain as the index, integer \ No newline at end of file +4. Target Port: Related to TargetBlock.Domain as the index, integer + + +## Current MSML Wiring & Comparison + +- Currently a wiring needs two components - the type (either stack or parallel) and the components, a list of blocks or wirings (there is a recursive wiring builder that makes sure the wirings get created in the right order) +- For a stack block, all adjacent blocks have validations that domain and codomain map +- Internally, all the port wirings are automatically built out for both mapping as well as execution +- Wirings in this way can be built out to automatically map to the proposed "Wiring" schema in concept specs or potentially changed +- The wirings are similar to a DAG +- A stack block wiring has domain of the first component and codomain of the last component +- A parallel block has the summation of component domains and component codomains +- There are future potential wiring types such as a looping block or having a notation for multiple outputs of the spaces, i.e. similar to if we have 1-N outputs that are variable between a block but they all follow the same codomain space schema \ No newline at end of file From 9ff8482cf90ada20bb24e669685d9389894c93d8 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 12:31:06 -0500 Subject: [PATCH 05/13] Quick fix --- .../{WIP Concept Specs.md => 2025-01-27 Concept Specs.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename research_notes/{WIP Concept Specs.md => 2025-01-27 Concept Specs.md} (100%) diff --git a/research_notes/WIP Concept Specs.md b/research_notes/2025-01-27 Concept Specs.md similarity index 100% rename from research_notes/WIP Concept Specs.md rename to research_notes/2025-01-27 Concept Specs.md From 02819fc8db425687329efe951f3d1b29ac63a2c2 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 12:36:47 -0500 Subject: [PATCH 06/13] Add systems --- research_notes/2025-01-27 Concept Specs.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/research_notes/2025-01-27 Concept Specs.md b/research_notes/2025-01-27 Concept Specs.md index bc2b730..bb382f5 100644 --- a/research_notes/2025-01-27 Concept Specs.md +++ b/research_notes/2025-01-27 Concept Specs.md @@ -22,6 +22,9 @@ ### Wiring +- Might need a name or something for IDs +- Might want to consider allowing multiple target and source ports + #### Option 1: 1. Source: string, such as "BlockA-1" for second port of BlockA codomain @@ -35,6 +38,13 @@ 4. Target Port: Related to TargetBlock.Domain as the index, integer +### Systems + +1. Name: PrimaryKey, string +2. Description: Optional, string +3. Wirings: ForeignKeys to Wiring, List[strings] + + ## Current MSML Wiring & Comparison - Currently a wiring needs two components - the type (either stack or parallel) and the components, a list of blocks or wirings (there is a recursive wiring builder that makes sure the wirings get created in the right order) From 5c0a2aac855a43b58aff4284af814789709cacc3 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 13:40:24 -0500 Subject: [PATCH 07/13] Issue 628 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eb53319..c184f97 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ One good example is the [wiring report](https://github.com/BlockScience/Predator ## Installing the library -To install the library, simply pip install by running "pip install math_spec_mapping" +To install the library, simply pip install by running "pip install math-spec-mapping". The pypi package can be found [here](https://pypi.org/project/math-spec-mapping/). ## Why MSML? From 7b51af63dffb578fe0e7138c9d2cecd2fa4a3add Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 27 Jan 2025 17:40:24 -0500 Subject: [PATCH 08/13] Update research note --- dev/TypedDictionary.ipynb | 147 +++++++++++++++++++++ research_notes/2025-01-27 Concept Specs.md | 77 ++++++++++- 2 files changed, 223 insertions(+), 1 deletion(-) create mode 100644 dev/TypedDictionary.ipynb diff --git a/dev/TypedDictionary.ipynb b/dev/TypedDictionary.ipynb new file mode 100644 index 0000000..cff6a44 --- /dev/null +++ b/dev/TypedDictionary.ipynb @@ -0,0 +1,147 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 31, + "metadata": {}, + "outputs": [], + "source": [ + "from typing import TypedDict\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "metadata": {}, + "outputs": [], + "source": [ + "a = TypedDict(\"EntityType\", {\"Words\": str, \"Total Length\": int})" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "metadata": {}, + "outputs": [], + "source": [ + "a.__repr__ = lambda x: \"A\"" + ] + }, + { + "cell_type": "code", + "execution_count": 48, + "metadata": {}, + "outputs": [ + { + "ename": "TypeError", + "evalue": "dict expected at most 1 argument, got 2", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mTypeError\u001b[0m Traceback (most recent call last)", + "\u001b[0;32m/var/folders/y0/fwkpk2ps087b_2qxvhjstrfr0000gn/T/ipykernel_57262/3336926982.py\u001b[0m in \u001b[0;36m\u001b[0;34m\u001b[0m\n\u001b[1;32m 6\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 7\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 8\u001b[0;31m \u001b[0mTypedDict2\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"EntityType\"\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m{\u001b[0m\u001b[0;34m\"Words\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m\"Total Length\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0mint\u001b[0m\u001b[0;34m}\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m", + "\u001b[0;31mTypeError\u001b[0m: dict expected at most 1 argument, got 2" + ] + } + ], + "source": [ + "class TypedDict2(TypedDict):\n", + " def __init__(self, typename, fields):\n", + " super().__init__(typename, fields)\n", + " def __repr__(self) -> str:\n", + " return f\"CustomTypedDict({super().__repr__()})\"\n", + " \n", + " \n", + "TypedDict2(\"EntityType\", {\"Words\": str, \"Total Length\": int})" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "\"Volume_per_Unit\"\n", + "\n", + "\"VolumeperUnit\"" + ] + }, + { + "cell_type": "code", + "execution_count": 49, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'Words': str, 'Total Length': int}" + ] + }, + "execution_count": 49, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "TypedDict2({\"Words\": str, \"Total Length\": int})" + ] + }, + { + "cell_type": "code", + "execution_count": 50, + "metadata": {}, + "outputs": [], + "source": [ + "class Test(TypedDict):\n", + " Words: str\n", + " Total_Length: int" + ] + }, + { + "cell_type": "code", + "execution_count": 47, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n" + ] + } + ], + "source": [ + "print(Test)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "BlockScience", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/research_notes/2025-01-27 Concept Specs.md b/research_notes/2025-01-27 Concept Specs.md index bb382f5..ab71590 100644 --- a/research_notes/2025-01-27 Concept Specs.md +++ b/research_notes/2025-01-27 Concept Specs.md @@ -54,4 +54,79 @@ - The wirings are similar to a DAG - A stack block wiring has domain of the first component and codomain of the last component - A parallel block has the summation of component domains and component codomains -- There are future potential wiring types such as a looping block or having a notation for multiple outputs of the spaces, i.e. similar to if we have 1-N outputs that are variable between a block but they all follow the same codomain space schema \ No newline at end of file +- There are future potential wiring types such as a looping block or having a notation for multiple outputs of the spaces, i.e. similar to if we have 1-N outputs that are variable between a block but they all follow the same codomain space schema + + +## Proposed Relational Schema V2 + +### Space + +1. ID: PrimaryKey +2. Name: string +3. Description: Optional, string + +### Block + +1. ID: PrimaryKey +2. Name: string +3. Description: Optional, string + +### Ports + +1. ID: PrimaryKey +2. Name: string +3. Index: Integer +4. Space: ForeignKey to Space.Name, string + +### Terminals + +1. ID: PrimaryKey +2. Name: string +3. Index: Integer +4. Space: ForeignKey to Space.Name, string + +## Proposed Schema V2 + +### Space + +{"ID": PrimaryKey, +"Name": string, +"Description": string} + +### Block + +{"ID": PrimaryKey, +"Name": string, +"Description": string, +"Domain": List[Space.ID], +"Codomain": List[Space.ID]} + +## Concrete Block + +{"ID": PrimaryKey, +"Name": string, +"Description": string, +"Parent": Block.ID} + +- It is legal to have many to one concrete blocks of abstract blocks + +## Wire (Concrete Space) + +{"ID": PrimaryKey, +"Parent": Space.ID, +"SourceBlock": ConcreteBlock.ID, +"TargetBlock": ConcreteBlock.ID, +"SourceIndex": int, +"TargetIndex": int} + +- Check matches up + +## System + +{"ConcreteBlocks": List[ConcreteBlock.ID], +"Wires": List[Wire.ID]} + +- Check that: + - All of the ports/domain need to be filled + - All domain ports only get one input + - Terminals can go 0...N ports (and they would just be sending replicas of the same output) \ No newline at end of file From 900c3a9250d0ba662d140784f98f6b7fe0a0760c Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Thu, 30 Jan 2025 22:44:34 -0500 Subject: [PATCH 09/13] Issue 634 --- src/math_spec_mapping/Load/load.py | 4 ++++ src/math_spec_mapping/Reports/markdown.py | 5 ++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/math_spec_mapping/Load/load.py b/src/math_spec_mapping/Load/load.py index c41928c..41972fa 100644 --- a/src/math_spec_mapping/Load/load.py +++ b/src/math_spec_mapping/Load/load.py @@ -86,4 +86,8 @@ def load_from_json(json: Dict, spec_path=None) -> MathSpec: if spec_path: tree = load_spec_tree(spec_path, ms) ms._add_spec_tree(tree) + else: + print( + "Add spec path to load_from_json to load spec tree and allow linking to the code in Obsidian" + ) return ms diff --git a/src/math_spec_mapping/Reports/markdown.py b/src/math_spec_mapping/Reports/markdown.py index 02f62c1..e79770e 100644 --- a/src/math_spec_mapping/Reports/markdown.py +++ b/src/math_spec_mapping/Reports/markdown.py @@ -70,7 +70,10 @@ def write_source_code_block(component, text, path): if hasattr(component, "source_code_location"): file_path = component.source_code_location else: - file_path = component["Source Code Location"] + try: + file_path = component["Source Code Location"] + except: + file_path = None if file_path: file_path = os.path.relpath(file_path, path) text += "## Spec Source Code Location\n\n" From c54ebfa06aedbd0ee2764643334a334bd9a8c320 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Fri, 31 Jan 2025 14:55:15 -0500 Subject: [PATCH 10/13] Begin printing function --- src/math_spec_mapping/Convenience/__init__.py | 1 + src/math_spec_mapping/Convenience/cadCAD.py | 12 ++++++++++++ src/math_spec_mapping/__init__.py | 1 + 3 files changed, 14 insertions(+) create mode 100644 src/math_spec_mapping/Convenience/cadCAD.py diff --git a/src/math_spec_mapping/Convenience/__init__.py b/src/math_spec_mapping/Convenience/__init__.py index 7c50460..59838f1 100644 --- a/src/math_spec_mapping/Convenience/__init__.py +++ b/src/math_spec_mapping/Convenience/__init__.py @@ -6,3 +6,4 @@ create_priority_label_matrix, create_milestone_label_matrix, ) +from .cadCAD import get_nested_types diff --git a/src/math_spec_mapping/Convenience/cadCAD.py b/src/math_spec_mapping/Convenience/cadCAD.py new file mode 100644 index 0000000..bbedfac --- /dev/null +++ b/src/math_spec_mapping/Convenience/cadCAD.py @@ -0,0 +1,12 @@ +from copy import deepcopy +from typing import _TypedDictMeta + + +def get_nested_types(data): + data = deepcopy(data) + for key in data: + print(type(data[key])) + if type(data[key]) == _TypedDictMeta: + data[key] = get_nested_types(data[key].__annotations__) + + return data diff --git a/src/math_spec_mapping/__init__.py b/src/math_spec_mapping/__init__.py index 6ef95e9..1597d2f 100644 --- a/src/math_spec_mapping/__init__.py +++ b/src/math_spec_mapping/__init__.py @@ -36,6 +36,7 @@ find_open_issues, create_priority_label_matrix, create_milestone_label_matrix, + get_nested_types, ) # from .Convenience import write_top_level_json_description From 0a9f4a0a19574546676466a18f96437710e76935 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Fri, 31 Jan 2025 15:04:01 -0500 Subject: [PATCH 11/13] get_underlying_type --- src/math_spec_mapping/Convenience/cadCAD.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/math_spec_mapping/Convenience/cadCAD.py b/src/math_spec_mapping/Convenience/cadCAD.py index bbedfac..79c397a 100644 --- a/src/math_spec_mapping/Convenience/cadCAD.py +++ b/src/math_spec_mapping/Convenience/cadCAD.py @@ -1,5 +1,13 @@ from copy import deepcopy -from typing import _TypedDictMeta +from typing import _TypedDictMeta, _GenericAlias + + +def get_underlying_type(data): + if type(data) == _GenericAlias: + data.__args__ = [get_underlying_type(x) for x in data.__args__] + elif type(data) == _TypedDictMeta: + data = get_nested_types(data.__annotations__) + return data def get_nested_types(data): @@ -8,5 +16,7 @@ def get_nested_types(data): print(type(data[key])) if type(data[key]) == _TypedDictMeta: data[key] = get_nested_types(data[key].__annotations__) + elif type(data[key]) == _GenericAlias: + data[key] = get_underlying_type(data[key]) return data From cf52b40230a9fcb079211feb954f698ec40daa33 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Fri, 31 Jan 2025 15:07:05 -0500 Subject: [PATCH 12/13] Finish get_nested_types for now --- src/math_spec_mapping/Convenience/cadCAD.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/math_spec_mapping/Convenience/cadCAD.py b/src/math_spec_mapping/Convenience/cadCAD.py index 79c397a..3123e3b 100644 --- a/src/math_spec_mapping/Convenience/cadCAD.py +++ b/src/math_spec_mapping/Convenience/cadCAD.py @@ -4,7 +4,7 @@ def get_underlying_type(data): if type(data) == _GenericAlias: - data.__args__ = [get_underlying_type(x) for x in data.__args__] + data = [get_underlying_type(x) for x in data.__args__] elif type(data) == _TypedDictMeta: data = get_nested_types(data.__annotations__) return data @@ -13,7 +13,6 @@ def get_underlying_type(data): def get_nested_types(data): data = deepcopy(data) for key in data: - print(type(data[key])) if type(data[key]) == _TypedDictMeta: data[key] = get_nested_types(data[key].__annotations__) elif type(data[key]) == _GenericAlias: From 70ca64568c40203862c9a749ed096902eb8a7888 Mon Sep 17 00:00:00 2001 From: SeanMcOwen Date: Mon, 3 Feb 2025 16:46:51 -0500 Subject: [PATCH 13/13] cadCAD builder docs --- docs/FAQ.md | 2 +- docs/cadCADBuilder.md | 55 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 1 deletion(-) create mode 100644 docs/cadCADBuilder.md diff --git a/docs/FAQ.md b/docs/FAQ.md index dcce999..d070e43 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,7 +1,7 @@ --- title: FAQ layout: page -nav_order: 5 +nav_order: 6 --- The following are frequently asked questions with regards to MSML. diff --git a/docs/cadCADBuilder.md b/docs/cadCADBuilder.md new file mode 100644 index 0000000..401c2c8 --- /dev/null +++ b/docs/cadCADBuilder.md @@ -0,0 +1,55 @@ +--- +title: cadCAD Builder +layout: page +nav_order: 5 +--- + +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. + +## Components + +### Inputs + +The following is required for building the cadCAD model: + +1. A math spec object with code bindings +2. A list of blocks which should be executed for each timestep +3. What state preparation and parameter preparation functions should be included to automatically run on experiment creation + + +### Outputs + +The following is outputted by the creation function: + +1. State Space: The nested and typed dictionary of all types for the state in the simulation that the data scientist needs to define +2. Parameter Space: The dictionary of parameters that the data scientist needs to define +3. Model: The executable model that can spawn experiments to run given valid state space and parameter space passed + +## Creating a cadCAD Model in a Notebook + +The [template notebook on building cadCAD models](https://github.com/BlockScience/MSML-Template/blob/main/notebooks/Build%20cadCAD.ipynb) shows how to create a cadCAD model from an MSML model. + +## Using cadCAD Model Repositories + +A recommended design pattern is to have MSML developers create a batch of cadCAD models to be run within a cadCADModels folder [similar to the template](https://github.com/BlockScience/MSML-Template/tree/main/cadCADModels). + +The template also has an example of running the pre-built cadCAD models [here](https://github.com/BlockScience/MSML-Template/blob/main/notebooks/Pre-built%20cadCAD.ipynb). + + +## Model Functionality + +### Experiment Creation + +- To create an experiment, one runs model.create_experiment(state, params) and passes in a valid state and parameter dictionary +- The record_trajectory flag if set to true will record the state after each step of the simulation +- The use_deepcopy flag if set to true will use deepcopy for the trajectory recording + + +### Running Experiments + +- Using experiment.run(T) where T is the number of time steps will advance the simulations that many timesteps +- If record_trajectory was set to true then the trajectories can be accessed from experiment.trajectories, if not you can always access the current state of the experiment by calling experiment.state + +### Batch Experiments + +- Batch experiments can be created and run through model.create_batch_experiments(...). An example of it is shown in the pre-built cadCAD notebook. \ No newline at end of file