Merged plugins 232

README.md

@@ -54,3 +54,51 @@ More complete examples of projects using the ASHRAE Standard 232P framework incl
 - [ASHRAE Standard 205](https://github.com/open205/schema-205) (transitioning to lattice)
 - [ASHRAE Standard 229](https://github.com/open229/ruleset-model-description-schema) (does not use lattice...yet)
 
+### C++ Library Code Generation
+
+Lattice's C++ code generation is achieved by calling the function `generate_cpp_project()`. Its only parameter is a list of submodule URLs.
+
+#### Translations
+
+Schema can be converted into C++ classes with the following mappings:
+
+| Object Type           | C++ type   |
+|-------------------    | --------   |
+| Data Group            | `struct`     |
+| Data Element          | public data member |
+| Enumerator            | `enum`       |
+| Data Group Template   | base class*|
+|
+
+ *with optional methods, including initialize()
+
+| Data Type             | C++ type  |
+|-------------------    | --------  |
+| Integer               | `int`       |
+| Numeric               | `float`     |
+| String                | `std::string` |
+| {}                    | `struct`    |
+| <>                    | `enum`      |
+| []                    | `std::vector` |
+| list "(A,B)"          | `std::unique_ptr<BaseOfAB>`|
+|
+
+#### Inheritance
+
+The code generator will assume that *Data Group* schema elements with a *Data Group Template* parameter use that template as the element's superclass. An `#include` statement for the expected superclass file is listed at the top of the schema's implemenation (cpp) file (note: see Big Ladder file naming conventions). If the superclass file is not found, the C++ generator will create a stub file for the class. If it is found, any virtual functions in the superclass will appear as overridden function stubs in the subclassed *Data Group*'s struct. Any additional code (members, methods) for the superclass itself must be provided by the **lattice** user.
+
+In the event that the source schema contains a *Data Element* with a "selector constraint" (i.e. a list of possible *Data Type*s combined with an associated list of possible enumerator values for the selector *Data Element*), the C++ generated code will assume that the *Data Type*s in the list all derive from a common base class, named by the *Data Group Template* of the first *Data Type* in the list. (The *Data Group Template* may be defined in a different schema than the *Data Type*.) An `#include` statement for the base class will be generated, as above. The code that populates the *Data Group* (the struct's `from_json` function) will use a conditional statement to create a new object of the correct subclass and assign it to a member `unique_ptr`, calling directly the derived class' auto-generated `from_json` functions.
+
+Note: If the first *Data Type* in a selector constraint list does not have a *Data Group Template* tag in its schema, the `unique_ptr`'s base class will default to "MissingType."
+
+#### Build information
+
+In addition to `.h` and `.cpp` files containing translated schema data, the code generator adds Git repository and CMake build support to the schema code, creating most of the structure necessary to test-build the schema code as a library. Necessary submodules are also downloaded: [fmt](https://github.com/fmtlib/fmt.git), [json](https://github.com/nlohmann/json), and [courier](https://github.com/bigladder/courier.git). To build a generated project, navigate to your **lattice** project's build directory, cpp subdirectory (e.g. /.lattice/cpp), and use a standard cmake build sequence:
+
+> cmake -B build
+>
+> cmake --build build --config release
+
+
+
+

dodo.py

@@ -1,5 +1,6 @@
-from lattice import Lattice
 from pathlib import Path
+from lattice import Lattice
+from lattice.cpp.header_entry_extension_loader import load_extensions
 
 from doit.tools import create_folder
 
@@ -29,7 +30,7 @@ def task_generate_meta_schemas():
         name = Path(example.root_directory).name
         yield {
             "name": name,
-            "file_dep": [schema.path for schema in example.schemas]
+            "file_dep": [schema.file_path for schema in example.schemas]
             + [BASE_META_SCHEMA_PATH, CORE_SCHEMA_PATH, Path(SOURCE_PATH, "meta_schema.py")],
             "targets": [schema.meta_schema_path for schema in example.schemas],
             "actions": [(example.generate_meta_schemas, [])],
@@ -44,7 +45,7 @@ def task_validate_schemas():
         yield {
             "name": name,
             "task_dep": [f"generate_meta_schemas:{name}"],
-            "file_dep": [schema.path for schema in example.schemas]
+            "file_dep": [schema.file_path for schema in example.schemas]
             + [schema.meta_schema_path for schema in example.schemas]
             + [BASE_META_SCHEMA_PATH, CORE_SCHEMA_PATH, Path(SOURCE_PATH, "meta_schema.py")],
             "actions": [(example.validate_schemas, [])],
@@ -58,7 +59,7 @@ def task_generate_json_schemas():
         yield {
             "name": name,
             "task_dep": [f"validate_schemas:{name}"],
-            "file_dep": [schema.path for schema in example.schemas]
+            "file_dep": [schema.file_path for schema in example.schemas]
             + [schema.meta_schema_path for schema in example.schemas]
             + [CORE_SCHEMA_PATH, BASE_META_SCHEMA_PATH, Path(SOURCE_PATH, "schema_to_json.py")],
             "targets": [schema.json_schema_path for schema in example.schemas],
@@ -88,7 +89,7 @@ def task_generate_markdown():
         yield {
             "name": name,
             "targets": [template.markdown_output_path for template in example.doc_templates],
-            "file_dep": [schema.path for schema in example.schemas]
+            "file_dep": [schema.file_path for schema in example.schemas]
             + [template.path for template in example.doc_templates]
             + [Path(SOURCE_PATH, "docs", "grid_table.py")],
             "task_dep": [f"validate_schemas:{name}"],
@@ -104,13 +105,13 @@ def task_generate_cpp_code():
         yield {
             "name": name,
             "task_dep": [f"validate_schemas:{name}"],
-            "file_dep": [schema.path for schema in example.cpp_schemas]
+            "file_dep": [schema.file_path for schema in example.cpp_schemas]
             + [schema.meta_schema_path for schema in example.schemas]
-            + [CORE_SCHEMA_PATH, BASE_META_SCHEMA_PATH, Path(SOURCE_PATH, "header_entries.py")],
-            "targets": [schema.cpp_header_path for schema in example.cpp_schemas]
-            + [schema.cpp_source_path for schema in example.cpp_schemas]
-            + example.cpp_support_headers(),
-            "actions": [(example.generate_cpp_headers, [])],
+            + [CORE_SCHEMA_PATH, BASE_META_SCHEMA_PATH, Path(SOURCE_PATH, "cpp", "header_entries.py"), Path(SOURCE_PATH, "cpp", "cpp_entries.py")],
+            "targets": [schema.cpp_header_file_path for schema in example.cpp_schemas]
+            + [schema.cpp_source_file_path for schema in example.cpp_schemas]
+            + example.cpp_support_headers + [example.cpp_output_dir / "CMakeLists.txt", example.cpp_output_dir / "src" / "CMakeLists.txt"],
+            "actions": [(load_extensions, [Path(example.root_directory, "cpp", "extensions")]), (example.generate_cpp_project, [["https://github.com/nlohmann/json.git", "https://github.com/bigladder/courier.git", "https://github.com/fmtlib/fmt.git"]])],
             "clean": True,
         }
 
@@ -122,7 +123,7 @@ def task_generate_web_docs():
         yield {
             "name": name,
             "task_dep": [f"validate_schemas:{name}", f"generate_json_schemas:{name}", f"validate_example_files:{name}"],
-            "file_dep": [schema.path for schema in example.schemas]
+            "file_dep": [schema.file_path for schema in example.schemas]
             + [template.path for template in example.doc_templates]
             + [Path(SOURCE_PATH, "docs", "mkdocs_web.py")],
             "targets": [Path(example.web_docs_directory_path, "public")],

examples/fan_spec/cpp/extensions/grid_var_enum.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+from lattice.cpp.header_entries import HeaderEntry
+from lattice.cpp.header_entries import register_data_element_operation
+
+@dataclass
+class GridVarCounterEnum(HeaderEntry):
+    elements_dict: dict
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.type = "enum"
+        self._closure = "};"
+        self._enumerants = list()
+
+        for element in self.elements_dict:
+            self._enumerants.append(f"{element}_index")
+        self._enumerants.append("index_count");
+
+    def __str__(self):
+        enums = self._enumerants
+        tab = "\t"
+        entry = f"{self._level * tab}{self.type} {self._opener}\n"
+        entry += ",\n".join([f"{(self._level + 1) * tab}{e}" for e in enums])
+        entry += f"\n{self._level * tab}{self._closure}"
+        return entry
+
+def register():
+    register_data_element_operation("GridVariablesTemplate", GridVarCounterEnum)

examples/fan_spec/cpp/extensions/lookup_struct.py

@@ -0,0 +1,29 @@
+import re
+from dataclasses import dataclass
+from lattice.cpp.header_entries import DataElement, Struct
+from lattice.cpp.header_entries import register_data_group_operation
+
+@dataclass
+class LookupStruct(Struct):
+    """
+    Special case struct for Lookup Variables. Its str overload adds a LookupStruct declaration.
+    """
+
+    def __str__(self):
+        """Two C++ entries share the schema child-entries, so one HeaderEntry subclass creates both."""
+        struct = super().__str__()
+
+        # Add a LookupStruct that offers a SOA access rather than AOS
+        tab = "\t"
+        struct += "\n"
+        struct += f"{self._level * tab}{self.type} {self.name}Struct {self._opener}\n"
+        for c in [ch for ch in self.child_entries if isinstance(ch, DataElement)]:
+            m = re.match(r'std::vector\<(.*)\>', c.type)
+            assert m is not None
+            struct += f"{(self._level+1) * tab}{m.group(1)} {c.name};\n"
+        struct += f"{self._level * tab}{self._closure}"
+
+        return struct
+
+def register():
+    register_data_group_operation("LookupVariablesTemplate", LookupStruct)

examples/fan_spec/examples/Fan-Continuous.RS0003.a205.json

@@ -1,12 +1,13 @@
 {
     "metadata": {
         "schema_author": "ASHRAE_205",
-        "schema": "RS0003",
+        "schema_name": "RS0003",
         "schema_version": "0.2.0",
+        "author": "SSPC 205 Working Group",
         "description": "Continuous Fan",
         "id": "123e4567-e89b-12d3-a456-426614174000",
-        "timestamp": "2020-05-11T00:00Z",
-        "version": 1,
+        "time_of_creation": "2020-05-11T00:00Z",
+        "version": "1.0.0",
         "disclaimer": "Example data not to be used for simulation"
     },
     "description": {

examples/fan_spec/schema/ASHRAE205.schema.yaml

@@ -25,15 +25,15 @@ PerformanceMapTemplate:
 GridVariablesTemplate:
   Object Type: "Data Group Template"
   Required Data Types:
-    - "[Numeric][1..]"
-    - "[Integer][1..]"
+    - "[Numeric]"
+    - "[Integer]"
   Data Elements Required: True
 
 LookupVariablesTemplate:
   Object Type: "Data Group Template"
   Required Data Types:
-    - "[Numeric][1..]"
-    - "[Integer][1..]"
+    - "[Numeric]"
+    - "[Integer]"
   Data Elements Required: True
 
 RepresentationSpecificationTemplate:

examples/fan_spec/schema/RS0003.schema.yaml

@@ -217,14 +217,18 @@ SystemCurve:
   Data Elements:
     standard_air_volumetric_flow_rate:
       Description: "Volumetric air flow rate through an air distribution system at standard air conditions"
-      Data Type: "[Numeric][2..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[2..]"
       Units: "m3/s"
       Required: True
     static_pressure_difference:
       Description: "Static pressure difference of an air distribution system"
-      Data Type: "[Numeric][2..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[2..]"
       Units: "Pa"
       Required: True
 
@@ -247,14 +251,18 @@ GridVariablesContinuous:
   Data Elements:
     standard_air_volumetric_flow_rate:
       Description: "Volumetric air flow rate through fan assembly at standard air conditions"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "m3/s"
       Required: True
     static_pressure_difference:
       Description: "External static pressure across fan assembly at dry coil conditions"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "Pa"
       Notes: "Any static pressure deduction (or addition) for wet coil is specified by `wet_pressure_difference` in 'assembly_components' data group"
       Required: True
@@ -265,14 +273,18 @@ LookupVariablesContinuous:
   Data Elements:
     impeller_rotational_speed:
       Description: "Rotational speed of fan impeller"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "rev/s"
       Required: True
     shaft_power:
       Description: "Mechanical shaft power input to fan assembly"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "W"
       Notes: "Does not include the mechanical efficiency of any mechanical drive used to modify rotational speed between the motor and impeller"
       Required: True
@@ -296,15 +308,19 @@ GridVariablesDiscrete:
   Data Elements:
     speed_number:
       Description: "Number indicating discrete speed of fan impeller in rank order (with 1 being the lowest speed)"
-      Data Type: "[Integer][1..]"
-      Constraints: ">=0"
+      Data Type: "[Integer]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "-"
       Notes: "Data shall be provided for all allowable discrete speeds or settings"
       Required: True
     static_pressure_difference:
       Description: "External static pressure across fan assembly at dry coil conditions"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "Pa"
       Notes: "Any static pressure deduction (or addition) for wet coil is specified by `wet_pressure_difference` in 'assembly_components' data group"
       Required: True
@@ -315,20 +331,26 @@ LookupVariablesDiscrete:
   Data Elements:
     standard_air_volumetric_flow_rate:
       Description: "Volumetric air flow rate through fan assembly at standard air conditions"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "m3/s"
       Required: True
     shaft_power:
       Description: "Mechanical shaft power input to fan assembly"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "W"
       Notes: "Does not include the mechanical efficiency of any mechanical drive used to modify rotational speed between the motor and impeller"
       Required: True
     impeller_rotational_speed:
       Description: "Rotational speed of fan impeller"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "rev/s"
       Required: True

examples/fan_spec/schema/RS0005.schema.yaml

@@ -103,14 +103,18 @@ GridVariables:
   Data Elements:
     shaft_power:
       Description: "Delivered rotational shaft power"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "W"
       Required: True
     shaft_rotational_speed:
       Description: "Rotational speed of shaft"
-      Data Type: "[Numeric][1..]"
-      Constraints: ">=0.0"
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "[1..]"
       Units: "rev/s"
       Required: True
 
@@ -120,14 +124,20 @@ LookupVariables:
   Data Elements:
     efficiency:
       Description: "Efficiency of motor"
-      Data Type: "[Numeric][1..]"
-      Constraints: [">=0.0", "<=1.0"]
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "<=1.0"
+        - "[1..]"
       Units: "-"
       Notes: "Defined as the ratio of mechanical shaft power to electrical input power of the motor"
       Required: True
     power_factor:
       Description: "Power factor of the motor"
-      Data Type: "[Numeric][1..]"
-      Constraints: [">=0.0", "<=1.0"]
+      Data Type: "[Numeric]"
+      Constraints:
+        - ">=0.0"
+        - "<=1.0"
+        - "[1..]"
       Units: "-"
       Required: True