From 3edb4146f2ab7c6de0400a4fe58f53a6fffa696a Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Thu, 23 Sep 2021 11:48:15 -0700 Subject: [PATCH 1/5] Added new section for sequence export For #95 --- specification/source/index.rst | 1 + .../source/sequenceDocumentation.rst | 160 ++++++++++++++++++ 2 files changed, 161 insertions(+) create mode 100644 specification/source/sequenceDocumentation.rst diff --git a/specification/source/index.rst b/specification/source/index.rst index 403766cc..c5c45ef1 100755 --- a/specification/source/index.rst +++ b/specification/source/index.rst @@ -23,6 +23,7 @@ OpenBuildingControl (Working Draft) requirements softwareArchitecture cdl + sequenceDocumentation controlsLibrary codeGeneration verification diff --git a/specification/source/sequenceDocumentation.rst b/specification/source/sequenceDocumentation.rst new file mode 100644 index 00000000..8353a813 --- /dev/null +++ b/specification/source/sequenceDocumentation.rst @@ -0,0 +1,160 @@ +.. _sec_seq_doc: + +Documentation of Control Sequences +---------------------------------- + +Introduction +^^^^^^^^^^^^ + +This section describes how to generate a control sequence description +based on a CDL specification. + +There are two distinct situations: +1. The control sequence could be from +a publication such as ASHRAE Guideline 36 for which a Microsoft Word +version exists, or +2. The control sequence could be for a sequence that only exists in CDL. + +The approach for 1. is being developed. For 2. while the section with +general requirements (such as what sensor or actuators need to be used) +is not in CDL, these requirements could be added manually. What this description +is focusing on is how to generate a description of the control sequence. + +Editing a Sequence that is Specified in a Word Document +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is currently being specified and will be added later. + + +Exporting the Control Logic from a CDL Model +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This section describes how a English language description of a sequence could be exported +from the CDL implementation. For this purpose, we introduce a new optional annotation +``annotation(__CDL(Documentation(info=STRING)))`` +where ``STRING`` is an html formatted string that contains the sequence description. +E.g., the annotation is in the same format as the CDL annotation +``annotation((Documentation(info=STRING))``. +The new optional annotation is introduced solely for the purpose that in the buildings industry, +control specifications use a different form than what is usually used in Modelica. +I.e., Modelica documentation describe what a sequence does, whereas for construction documents, +the sequence description must follow the structure dictated by the +Construction Specification Institute (CSI) and the American Institute of Architects (AIA) +because they become legal documents. + +How to generate the sequence description that can be inserted into these construction +documents is described using a small example. +Consider the model +`Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.RadiantHeatingCooling `_. +This model has two sequences, +one for the radiant heating and one for the radiant cooling. These two sequences +are described in +`Buildings.Controls.OBC.RadiantSystems.Heating.HighMassSupplyTemperature_TRoom `_ +and in +`Buildings.Controls.OBC.RadiantSystems.Cooling.HighMassSupplyTemperature_TRoomRelHum `_ +html format. + +To export sequences from these models, ``modelica-json`` will need to generate a +Microsoft Word document using the following procedure. + +1. Read the top-level Modelica file and extract each block that is + in the package ``Buildings.Controls.OBC``. Put the names of these blocks in a list. +2. Remove from this list all blocks that are in ``Buildings.Controls.OBC.CDL``. + (These are are elementary blocks that need not be documented.) +3. Read the top-level Modelica file and extract all blocks that contain in their class + definition the annotation ``__cld(document=true)``. Add these blocks to the list. + (This will allow users to add composite control blocks that will be documented.) +4. For each block in the list. + + a. If the block contains a section ``annotation(__CDL(Documentation(info=STRING)))``, + use the value of this section as the sequence documentation of this block. Goto step d) + b. If the block contains a section ``annotation(Documentation(info=STRING))``, + use the value of this section as the sequence documentation of this block. Goto step d) + c. Issue a warning that this block contains no control sequence description and proceed to + the next block. + d. In the sequence description of this block, for each parameter that is in the description, + add the value and units. For example, an entry such as + ``... between TSupSetMin and TSupSetMax based on ...`` + becomes + ``... between TSupSetMin (=20° adjustable) and TSupSetMax (=40° adjustable) based on ...``. + Note that the word "adjustable" must not be added if the parameter value is declared as ``final``. + Proceed to the next block. + +5. Collect the descriptions of each block and output it in a Word document. + +As an example, consider the following snippet of a composite control block. + +.. code-block:: modelica + + HigMassSupplyTemperature_TRoom con(TSubSet_max=303.15, final TSubSet_min=293.15); + + block HighMassSupplyTemperature_TRoom + "Room temperature controller for radiant heating with constant mass flow and variable supply temperature" + + parameter Real TSupSet_max( + final unit="K", + displayUnit="degC") "Maximum heating supply water temperature"; + parameter Real TSupSet_min( + final unit="K", + displayUnit="degC") = 293.15 "Minimum heating supply water temperature"; + + annotation( + Documentation( + info=" +

+ Controller for a radiant heating system. +

+

+ The controller tracks the room temperature set point TRooSet by + adjusting the supply water temperature set point TSupSet linearly between + TSupSetMin and TSupSetMax + ... + PI-controller likely saturate due to the slow system response. +

+ " + ), + __cdl( + Documentation( + info=" +

+ Controller for a radiant heating system. +

+

+ The controller shall track the room temperature set point by + adjusting the supply water temperature set point TSupSet linearly between + TSupSetMin and TSupSetMax + based on the output signal of the proportional controller. + The pump shall be either off or be operating at full speed, in which case yPum = 1. + The pump control shall be based on a hysteresis that switches the pump on when the output of the + proportional controller y exceeds 0.2, and the pump shall be commanded off when the output falls + below 0.1. See figure below for the control charts. +

+

+ Image of control output +

+

+ Note: + For systems with high thermal mass, this controller should be left configured + as a P-controller, which is the default setting. + PI-controller likely saturate due to the slow system response. +

+ " + ) + ) + ); + end HighMassSupplyTemperature_TRoom; + +For this control block, ``modelica-json`` will produce content for the Word description that looks like + + "The controller shall track the room temperature set point by + adjusting the supply water temperature set point ``TSupSet`` linearly between + ``TSupSetMin`` (:math:`=20^\circ`) and ``TSupSetMax`` (:math:`=30^\circ` adjustable) + based on the output signal of the proportional controller..." + +To use IP units, ``modelica-json`` will have a configuration that specifies what units should be used. +The documentation will also include the figure as declared in the CDL specification. + +The Control Sequence Selection and Configuration tool could make the section +``annotation(__CDL(Documentation(info=STRING)))`` editable, thereby allowing +users to customize the description of the sequence and add any other desired documentation. \ No newline at end of file From 53b3e1855a6681f260dd70973f52af7a221b2313 Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Thu, 23 Sep 2021 12:12:00 -0700 Subject: [PATCH 2/5] Added removal of text --- .../source/sequenceDocumentation.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/specification/source/sequenceDocumentation.rst b/specification/source/sequenceDocumentation.rst index 8353a813..646dad9a 100644 --- a/specification/source/sequenceDocumentation.rst +++ b/specification/source/sequenceDocumentation.rst @@ -84,7 +84,7 @@ Microsoft Word document using the following procedure. As an example, consider the following snippet of a composite control block. -.. code-block:: modelica +.. code-block:: HigMassSupplyTemperature_TRoom con(TSubSet_max=303.15, final TSubSet_min=293.15); @@ -98,6 +98,12 @@ As an example, consider the following snippet of a composite control block. final unit="K", displayUnit="degC") = 293.15 "Minimum heating supply water temperature"; + parameter Controls.OBC.CDL.Types.SimpleController + controllerType = Buildings.Controls.OBC.CDL.Types.SimpleController.P + "Type of controller" annotation (Dialog(group="Control gains")); + + ... [omitted] + annotation( Documentation( info=" @@ -108,7 +114,7 @@ As an example, consider the following snippet of a composite control block. The controller tracks the room temperature set point TRooSet by adjusting the supply water temperature set point TSupSet linearly between TSupSetMin and TSupSetMax - ... + PI-controller likely saturate due to the slow system response.

" @@ -134,11 +140,13 @@ As an example, consider the following snippet of a composite control block. src="modelica://Buildings/Resources/Images/Controls/OBC/RadiantSystems/Heating/HighMassSupplyTemperature_TRoom.png"/>

+ <-- cdl(visible=(not (controllerType is final))) or controllerType <> CDL.Types.SimpleController.P --> Note: For systems with high thermal mass, this controller should be left configured as a P-controller, which is the default setting. PI-controller likely saturate due to the slow system response.

+ <-- end cdl --> " ) ) @@ -152,9 +160,16 @@ For this control block, ``modelica-json`` will produce content for the Word desc ``TSupSetMin`` (:math:`=20^\circ`) and ``TSupSetMax`` (:math:`=30^\circ` adjustable) based on the output signal of the proportional controller..." +Note that ``modelica-json`` removes the notice at the end of the sequence description +if the ``controllerType`` is +declared as ``final`` (because then, no other choice can be made). +Through this mechanism, sections and images can be removed or enabled in the generated +sequence description. + To use IP units, ``modelica-json`` will have a configuration that specifies what units should be used. The documentation will also include the figure as declared in the CDL specification. + The Control Sequence Selection and Configuration tool could make the section ``annotation(__CDL(Documentation(info=STRING)))`` editable, thereby allowing users to customize the description of the sequence and add any other desired documentation. \ No newline at end of file From 4018132b8d6d354c6ceba49037e3ecfe3065bea1 Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Thu, 23 Sep 2021 12:14:16 -0700 Subject: [PATCH 3/5] Removed setuptools See https://app.travis-ci.com/github/lbl-srg/obc/builds/238359928 --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 29261e9c..c9875695 100644 --- a/.travis.yml +++ b/.travis.yml @@ -21,7 +21,7 @@ addons: # the html output may have small formatting differences which causes # the test to fail install: - - pip3 install --upgrade pip setuptools wheel + - pip3 install --upgrade pip wheel - pip3 install sphinx==2.1.2 \ sphinx-bootstrap-theme==0.7.1 \ sphinxcontrib-bibtex==0.4.2 \ From a4bba4d612aabaaf2fede20ba9073906ad70360e Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Thu, 23 Sep 2021 12:26:39 -0700 Subject: [PATCH 4/5] Revised description --- .../source/sequenceDocumentation.rst | 27 ++++++++++++------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/specification/source/sequenceDocumentation.rst b/specification/source/sequenceDocumentation.rst index 646dad9a..96f9cacf 100644 --- a/specification/source/sequenceDocumentation.rst +++ b/specification/source/sequenceDocumentation.rst @@ -15,10 +15,8 @@ a publication such as ASHRAE Guideline 36 for which a Microsoft Word version exists, or 2. The control sequence could be for a sequence that only exists in CDL. -The approach for 1. is being developed. For 2. while the section with -general requirements (such as what sensor or actuators need to be used) -is not in CDL, these requirements could be added manually. What this description -is focusing on is how to generate a description of the control sequence. +The approach for 1. is currently being developed. +Approach 2 is described in :numref:`sec_seq_doc_cdl`. Editing a Sequence that is Specified in a Word Document ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -26,11 +24,22 @@ Editing a Sequence that is Specified in a Word Document This is currently being specified and will be added later. +.. _sec_seq_doc_cdl: + Exporting the Control Logic from a CDL Model ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This section describes how a English language description of a sequence could be exported -from the CDL implementation. For this purpose, we introduce a new optional annotation +from the CDL implementation. +This will allow libraries and also users to build up repositories of control sequences +for which an English language specification can be exported without having to have +a template Word document (which generally does not exist for this use case). +While control sequence submittal typically contain additional requirements +that are not part of the sequence description, such as what energy code to follow or what type of valve to be used, +such information can be integrated manually by the user. Thus, the here described export +will document only the sequences, which can then be combined by the user with other documentation. + +To export sequence descriptions, we introduce a new optional annotation ``annotation(__CDL(Documentation(info=STRING)))`` where ``STRING`` is an html formatted string that contains the sequence description. E.g., the annotation is in the same format as the CDL annotation @@ -52,7 +61,7 @@ are described in `Buildings.Controls.OBC.RadiantSystems.Heating.HighMassSupplyTemperature_TRoom `_ and in `Buildings.Controls.OBC.RadiantSystems.Cooling.HighMassSupplyTemperature_TRoomRelHum `_ -html format. +using html format. To export sequences from these models, ``modelica-json`` will need to generate a Microsoft Word document using the following procedure. @@ -67,9 +76,9 @@ Microsoft Word document using the following procedure. 4. For each block in the list. a. If the block contains a section ``annotation(__CDL(Documentation(info=STRING)))``, - use the value of this section as the sequence documentation of this block. Goto step d) + use the value of this section as the sequence documentation of this block. Goto step d). b. If the block contains a section ``annotation(Documentation(info=STRING))``, - use the value of this section as the sequence documentation of this block. Goto step d) + use the value of this section as the sequence documentation of this block. Goto step d). c. Issue a warning that this block contains no control sequence description and proceed to the next block. d. In the sequence description of this block, for each parameter that is in the description, @@ -160,7 +169,7 @@ For this control block, ``modelica-json`` will produce content for the Word desc ``TSupSetMin`` (:math:`=20^\circ`) and ``TSupSetMax`` (:math:`=30^\circ` adjustable) based on the output signal of the proportional controller..." -Note that ``modelica-json`` removes the notice at the end of the sequence description +``modelica-json`` will remove the notice at the end of the sequence description if the ``controllerType`` is declared as ``final`` (because then, no other choice can be made). Through this mechanism, sections and images can be removed or enabled in the generated From f6024327f95ff0e83dee64cd0e580c52a9a79173 Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Thu, 23 Sep 2021 12:28:39 -0700 Subject: [PATCH 5/5] Revised description --- specification/source/sequenceDocumentation.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/source/sequenceDocumentation.rst b/specification/source/sequenceDocumentation.rst index 96f9cacf..76617282 100644 --- a/specification/source/sequenceDocumentation.rst +++ b/specification/source/sequenceDocumentation.rst @@ -10,10 +10,11 @@ This section describes how to generate a control sequence description based on a CDL specification. There are two distinct situations: -1. The control sequence could be from -a publication such as ASHRAE Guideline 36 for which a Microsoft Word -version exists, or -2. The control sequence could be for a sequence that only exists in CDL. + + 1. The control sequence could be from + a publication such as ASHRAE Guideline 36 for which a Microsoft Word + version exists, or + 2. The control sequence could be for a sequence that only exists in CDL. The approach for 1. is currently being developed. Approach 2 is described in :numref:`sec_seq_doc_cdl`.