Merge pull request lbl-srg#96 from lbl-srg/issue95_sequenceDescription

Issue95 sequence description

.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 \

specification/source/index.rst

@@ -23,6 +23,7 @@ OpenBuildingControl (Working Draft)
    requirements
    softwareArchitecture
    cdl
+   sequenceDocumentation
    controlsLibrary
    codeGeneration
    verification

specification/source/sequenceDocumentation.rst

@@ -0,0 +1,185 @@
+.. _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 currently being developed.
+Approach 2 is described in :numref:`sec_seq_doc_cdl`.
+
+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.
+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
+``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 <https://github.com/lbl-srg/modelica-buildings/blob/e7728dcee22f72a8d823fcab6edbbabfe1fd742c/Buildings/ThermalZones/EnergyPlus/Examples/SingleFamilyHouse/RadiantHeatingCooling.mo>`_.
+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 <https://github.com/lbl-srg/modelica-buildings/blob/e7728dcee22f72a8d823fcab6edbbabfe1fd742c/Buildings/Controls/OBC/RadiantSystems/Heating/HighMassSupplyTemperature_TRoom.mo#L238>`_
+and in
+`Buildings.Controls.OBC.RadiantSystems.Cooling.HighMassSupplyTemperature_TRoomRelHum <https://github.com/lbl-srg/modelica-buildings/blob/e7728dcee22f72a8d823fcab6edbbabfe1fd742c/Buildings/Controls/OBC/RadiantSystems/Cooling/HighMassSupplyTemperature_TRoomRelHum.mo#L273>`_
+using 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 <code>TSupSetMin</code> and <code>TSupSetMax</code> based on ...``
+        becomes
+        ``... between <code>TSupSetMin</code> (=20&deg; adjustable) and <code>TSupSetMax</code> (=40&deg; 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::
+
+   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";
+
+      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="<html>
+            <p>
+            Controller for a radiant heating system.
+            </p>
+            <p>
+            The controller tracks the room temperature set point <code>TRooSet</code> by
+            adjusting the supply water temperature set point <code>TSupSet</code> linearly between
+            <code>TSupSetMin</code> and <code>TSupSetMax</code>
+
+            PI-controller likely saturate due to the slow system response.
+            </p>
+            </html>"
+          ),
+          __cdl(
+            Documentation(
+              info="<html>
+                <p>
+                Controller for a radiant heating system.
+                </p>
+                <p>
+                The controller shall track the room temperature set point by
+                adjusting the supply water temperature set point <code>TSupSet</code> linearly between
+                <code>TSupSetMin</code> and <code>TSupSetMax</code>
+                based on the output signal of the proportional controller.
+                The pump shall be either off or be operating at full speed, in which case <code>yPum = 1</code>.
+                The pump control shall be based on a hysteresis that switches the pump on when the output of the
+                proportional controller <code>y</code> exceeds <i>0.2</i>, and the pump shall be commanded off when the output falls
+                below <i>0.1</i>. See figure below for the control charts.
+                </p>
+                <p align="center">
+                <img alt="Image of control output"
+                src="modelica://Buildings/Resources/Images/Controls/OBC/RadiantSystems/Heating/HighMassSupplyTemperature_TRoom.png"/>
+                </p>
+                <p>
+                <-- cdl(visible=(not (controllerType is final))) or controllerType <> CDL.Types.SimpleController.P -->
+                <b>Note:</b>
+                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.
+                </p>
+                <-- end cdl -->
+              </html>"
+           )
+        )
+      );
+   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..."
+
+``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
+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.