From ed2d5865ba2d09b8dcfd9b74910383d522b4b224 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Mon, 27 Apr 2020 22:52:25 -0700 Subject: [PATCH 01/28] drafting point list specification [ci skip] --- specification/source/cdl.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 5f5b9696..60fc7b1f 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -582,6 +582,42 @@ because if a building automation system cannot conditionally remove instances, then the block (or input connector) upstream of the output will always be present (or will have a default value). +.. _sec_point_list: + +Point list generation +..................... + +The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` and further +generate the point list table. In default, + +* The connector ``RealInput`` and ``IntegerInput`` are analog input. +* The connector ``RealOutput`` and ``IntegerOutput`` are analog output. +* The connector ``BooleanInput`` and ``BooleanOutput`` are digital input and output. + +The vendor annotation ``__cdl(generatePointlist=true)`` in class level specifies +whether to generate point list of the sequence. The vendor annotation +``__cdl(controlPoint=true, hardwired=false)`` of each connector specifies if the +connector is a control point and if it is a hardwired points. + +[For example, blocks of the form + +.. code-block:: modelica + + CDL.Interfaces.BooleanInput uWin + "Windows status" + annotation (__cdl(controlPoint=true, hardwired=false)); + + CDL.Interfaces.RealOutput yHea + "Heating loop output"; + + equation + ...; + + annotation (__cdl(generatePointlist=true)); + +specifies that it should generate point list of the sequence, and the ``uWin`` is a +control point that is not hardwired and the ``yHea`` is not a control point.] + .. _sec_connectors: Connectors From 85c0bac9d987723925db70cbff0db74cbacc75e8 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Mon, 27 Apr 2020 22:58:22 -0700 Subject: [PATCH 02/28] added hyperlink [ci skip] --- specification/source/cdl.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 60fc7b1f..124fc627 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -587,8 +587,8 @@ then the block (or input connector) upstream of the output will always be presen Point list generation ..................... -The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` and further -generate the point list table. In default, +The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` +(:numref:`fig_cdl_pro_lin`) and further generate the point list table. In default, * The connector ``RealInput`` and ``IntegerInput`` are analog input. * The connector ``RealOutput`` and ``IntegerOutput`` are analog output. @@ -603,12 +603,10 @@ connector is a control point and if it is a hardwired points. .. code-block:: modelica - CDL.Interfaces.BooleanInput uWin - "Windows status" + CDL.Interfaces.BooleanInput uWin "Windows status" annotation (__cdl(controlPoint=true, hardwired=false)); - CDL.Interfaces.RealOutput yHea - "Heating loop output"; + CDL.Interfaces.RealOutput yHea "Heating loop output"; equation ...; From f1306c760011b6f3d6f3ee642eaa03c58cf18584 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Mon, 4 May 2020 22:18:46 -0700 Subject: [PATCH 03/28] updated specification --- specification/source/cdl.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 124fc627..3a693d45 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -595,9 +595,11 @@ The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` * The connector ``BooleanInput`` and ``BooleanOutput`` are digital input and output. The vendor annotation ``__cdl(generatePointlist=true)`` in class level specifies -whether to generate point list of the sequence. The vendor annotation -``__cdl(controlPoint=true, hardwired=false)`` of each connector specifies if the -connector is a control point and if it is a hardwired points. +whether to generate point list of the sequence. It allows that a sequence do not generate +the point list in the case when it is used for composing other sequence so it does not +connect externally. The vendor annotation ``__cdl(controlPoint=true, hardwired=false)`` +of each connector specifies if the connector is a control point and if it is a +hardwired points. [For example, blocks of the form From b77100f8ebab2411a8432a5f8304ab4239aa2290 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Mon, 4 May 2020 22:21:05 -0700 Subject: [PATCH 04/28] corrected grammar --- specification/source/cdl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 3a693d45..4830bb0a 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -595,7 +595,7 @@ The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` * The connector ``BooleanInput`` and ``BooleanOutput`` are digital input and output. The vendor annotation ``__cdl(generatePointlist=true)`` in class level specifies -whether to generate point list of the sequence. It allows that a sequence do not generate +whether to generate point list of the sequence. It allows a sequence to not generate the point list in the case when it is used for composing other sequence so it does not connect externally. The vendor annotation ``__cdl(controlPoint=true, hardwired=false)`` of each connector specifies if the connector is a control point and if it is a From b13556986bb87e59fcb85ca019e6e30dd32cd425 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Mon, 4 May 2020 22:22:10 -0700 Subject: [PATCH 05/28] improved section title --- specification/source/cdl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 4830bb0a..0a6c6bca 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -584,8 +584,8 @@ then the block (or input connector) upstream of the output will always be presen .. _sec_point_list: -Point list generation -..................... +Point list +.......... The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` (:numref:`fig_cdl_pro_lin`) and further generate the point list table. In default, From fd455d62303c6237ebd1f60de9a963234b0151dd Mon Sep 17 00:00:00 2001 From: Jianjun Hu Date: Mon, 11 May 2020 21:42:14 -0700 Subject: [PATCH 06/28] updated specification for point list --- specification/source/cdl.rst | 50 ++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 0a6c6bca..11a40fd3 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -596,27 +596,51 @@ The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` The vendor annotation ``__cdl(generatePointlist=true)`` in class level specifies whether to generate point list of the sequence. It allows a sequence to not generate -the point list in the case when it is used for composing other sequence so it does not -connect externally. The vendor annotation ``__cdl(controlPoint=true, hardwired=false)`` -of each connector specifies if the connector is a control point and if it is a -hardwired points. +the point list in the case when it is used for composing other sequence so it is not +connected externally. The connector could have the vendor annotation like +``__cdl(hardwired=false, application={"trend", "alarm"})``. It indicates that if it +is hardwired point and what it could be used for, i.e. "tread", "alarm", "schedule". -[For example, blocks of the form +For example, a block includes .. code-block:: modelica - CDL.Interfaces.BooleanInput uWin "Windows status" - annotation (__cdl(controlPoint=true, hardwired=false)); - - CDL.Interfaces.RealOutput yHea "Heating loop output"; + within Buildings.Controls.OBC.ASHRAE.G36_PR1.TerminalUnits + block Controller "Controller for room VAV box" + ...; - equation - ...; + CDL.Interfaces.BooleanInput uWin "Windows status" + annotation (__cdl(hardwired=true, application={"trend", "alarm"})); + + CDL.Interfaces.RealOutput yVal "Signal for heating coil valve" + annotation (__cdl(hardwired=false, application={"trend"})); + + ...; + equations + ...; annotation (__cdl(generatePointlist=true)); -specifies that it should generate point list of the sequence, and the ``uWin`` is a -control point that is not hardwired and the ``yHea`` is not a control point.] +It specifies that the sequence should have a point list, and the ``uWin`` is a +hardwired digital input point that can be used for trending and alarming, +and the ``yVal`` is not a hardwired point that can be used for trending. The point +list table will be like: + +.. _tab_sample_point_list: + +.. table:: Sample point list table generated by the ``modelica-json`` tool + :class: longtable + + ======================== =========== ========= ========== ======== ======== ======== ================================================ + System/Equipment Name Type Hardwired? Trend Alarm Schedule Notes + ======================== =========== ========= ========== ======== ======== ======== ================================================ + Terminal unit ``uWin`` DI Y Y Y N Windows status + ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ + Terminal unit ``yVal`` AO N Y N N Signal for heating coil valve + ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ + Terminal unit ... ... ... ... ... ... ... + ======================== =========== ========= ========== ======== ======== ======== ================================================ + .. _sec_connectors: From c79235032174f329fa6e97c25b5f8fc76821797e Mon Sep 17 00:00:00 2001 From: Jianjun Hu Date: Mon, 11 May 2020 21:46:39 -0700 Subject: [PATCH 07/28] rmoved empty line --- specification/source/cdl.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 11a40fd3..a86b62fa 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -608,17 +608,13 @@ For example, a block includes within Buildings.Controls.OBC.ASHRAE.G36_PR1.TerminalUnits block Controller "Controller for room VAV box" ...; - CDL.Interfaces.BooleanInput uWin "Windows status" annotation (__cdl(hardwired=true, application={"trend", "alarm"})); - CDL.Interfaces.RealOutput yVal "Signal for heating coil valve" annotation (__cdl(hardwired=false, application={"trend"})); - ...; equations ...; - annotation (__cdl(generatePointlist=true)); It specifies that the sequence should have a point list, and the ``uWin`` is a From 9ae1ca7f1ccb8e2dd413ad86c1ea243d2f1f7b10 Mon Sep 17 00:00:00 2001 From: Jianjun Hu Date: Mon, 11 May 2020 21:53:13 -0700 Subject: [PATCH 08/28] reformatted --- specification/source/cdl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index a86b62fa..52901282 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -617,7 +617,7 @@ For example, a block includes ...; annotation (__cdl(generatePointlist=true)); -It specifies that the sequence should have a point list, and the ``uWin`` is a +It specifies that the sequence should have a point list, the ``uWin`` is a hardwired digital input point that can be used for trending and alarming, and the ``yVal`` is not a hardwired point that can be used for trending. The point list table will be like: @@ -634,7 +634,7 @@ list table will be like: ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ Terminal unit ``yVal`` AO N Y N N Signal for heating coil valve ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ - Terminal unit ... ... ... ... ... ... ... + ... ... ... ... ... ... ... ... ======================== =========== ========= ========== ======== ======== ======== ================================================ From 761ee75b04660bd9c9d7400494190150298ffeea Mon Sep 17 00:00:00 2001 From: Jianjun Hu Date: Tue, 12 May 2020 16:42:05 -0700 Subject: [PATCH 09/28] updated spe --- specification/source/cdl.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 52901282..69e07662 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -609,9 +609,12 @@ For example, a block includes block Controller "Controller for room VAV box" ...; CDL.Interfaces.BooleanInput uWin "Windows status" - annotation (__cdl(hardwired=true, application={"trend", "alarm"})); + annotation (__cdl(hardwired=true, + trend(interval=3600, enable=true), + alarm(flag=true, level=1, enable=true))); CDL.Interfaces.RealOutput yVal "Signal for heating coil valve" - annotation (__cdl(hardwired=false, application={"trend"})); + annotation (__cdl(hardwired=false, + trend(interval=3600, enable=true))); ...; equations ...; @@ -619,8 +622,8 @@ For example, a block includes It specifies that the sequence should have a point list, the ``uWin`` is a hardwired digital input point that can be used for trending and alarming, -and the ``yVal`` is not a hardwired point that can be used for trending. The point -list table will be like: +and the ``yVal`` is not a hardwired point that can only be used for trending. +The point list table will be like: .. _tab_sample_point_list: @@ -630,9 +633,9 @@ list table will be like: ======================== =========== ========= ========== ======== ======== ======== ================================================ System/Equipment Name Type Hardwired? Trend Alarm Schedule Notes ======================== =========== ========= ========== ======== ======== ======== ================================================ - Terminal unit ``uWin`` DI Y Y Y N Windows status + Terminal unit ``uWin`` DI Y 3600 true N Windows status ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ - Terminal unit ``yVal`` AO N Y N N Signal for heating coil valve + Terminal unit ``yVal`` AO N 3600 N N Signal for heating coil valve ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ ... ... ... ... ... ... ... ... ======================== =========== ========= ========== ======== ======== ======== ================================================ From 5c1a76643c7a994ee4bd0ef4407530a7f06bface Mon Sep 17 00:00:00 2001 From: Jianjun Hu Date: Tue, 12 May 2020 16:43:23 -0700 Subject: [PATCH 10/28] simplified table --- specification/source/cdl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 69e07662..894f2717 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -633,9 +633,9 @@ The point list table will be like: ======================== =========== ========= ========== ======== ======== ======== ================================================ System/Equipment Name Type Hardwired? Trend Alarm Schedule Notes ======================== =========== ========= ========== ======== ======== ======== ================================================ - Terminal unit ``uWin`` DI Y 3600 true N Windows status + Terminal unit ``uWin`` DI X 3600 true Windows status ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ - Terminal unit ``yVal`` AO N 3600 N N Signal for heating coil valve + Terminal unit ``yVal`` AO 3600 Signal for heating coil valve ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ ... ... ... ... ... ... ... ... ======================== =========== ========= ========== ======== ======== ======== ================================================ From c425419b34b75c9cf258e1fcbc5207df1e049047 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Mon, 13 Jul 2020 10:02:56 -0700 Subject: [PATCH 11/28] improved wording --- specification/source/cdl.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 878e4e59..3168da8a 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -599,7 +599,7 @@ Point list .......... The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` -(:numref:`fig_cdl_pro_lin`) and further generate the point list table. In default, +(:numref:`fig_cdl_pro_lin`) and further generate the point list table. By default, * The connector ``RealInput`` and ``IntegerInput`` are analog input. * The connector ``RealOutput`` and ``IntegerOutput`` are analog output. @@ -609,8 +609,8 @@ The vendor annotation ``__cdl(generatePointlist=true)`` in class level specifies whether to generate point list of the sequence. It allows a sequence to not generate the point list in the case when it is used for composing other sequence so it is not connected externally. The connector could have the vendor annotation like -``__cdl(hardwired=false, application={"trend", "alarm"})``. It indicates that if it -is hardwired point and what it could be used for, i.e. "tread", "alarm", "schedule". +``__cdl(hardwired=false, trend(), alarm(), schedule())``. It indicates that if it +is hardwired point and what it is used for, i.e. "trend", "alarm", "schedule". For example, a block includes @@ -631,7 +631,7 @@ For example, a block includes ...; annotation (__cdl(generatePointlist=true)); -It specifies that the sequence should have a point list, the ``uWin`` is a +It specifies that a point list should be generated for the sequence, the ``uWin`` is a hardwired digital input point that can be used for trending and alarming, and the ``yVal`` is not a hardwired point that can only be used for trending. The point list table will be like: From 45af74176f9e884deb6226624592d20bdb997275 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Mon, 3 Aug 2020 13:27:18 -0700 Subject: [PATCH 12/28] changed notation --- specification/source/cdl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 3168da8a..440f3f3d 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -644,7 +644,7 @@ The point list table will be like: ======================== =========== ========= ========== ======== ======== ======== ================================================ System/Equipment Name Type Hardwired? Trend Alarm Schedule Notes ======================== =========== ========= ========== ======== ======== ======== ================================================ - Terminal unit ``uWin`` DI X 3600 true Windows status + Terminal unit ``uWin`` DI Yes 3600 true Windows status ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ Terminal unit ``yVal`` AO 3600 Signal for heating coil valve ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ From 8ddf43a50d5a2ec04acd5fd80859f0fd60ec4e4d Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Thu, 3 Sep 2020 16:57:35 -0700 Subject: [PATCH 13/28] revised specification based on Paul's comment --- specification/source/cdl.rst | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 440f3f3d..b1603193 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -609,8 +609,8 @@ The vendor annotation ``__cdl(generatePointlist=true)`` in class level specifies whether to generate point list of the sequence. It allows a sequence to not generate the point list in the case when it is used for composing other sequence so it is not connected externally. The connector could have the vendor annotation like -``__cdl(hardwired=false, trend(), alarm(), schedule())``. It indicates that if it -is hardwired point and what it is used for, i.e. "trend", "alarm", "schedule". +``__cdl(hardwired=false, trend())``. It indicates that if it +is hardwired point and how it is used for trending. For example, a block includes @@ -621,8 +621,7 @@ For example, a block includes ...; CDL.Interfaces.BooleanInput uWin "Windows status" annotation (__cdl(hardwired=true, - trend(interval=3600, enable=true), - alarm(flag=true, level=1, enable=true))); + trend(interval=3600, enable=true))); CDL.Interfaces.RealOutput yVal "Signal for heating coil valve" annotation (__cdl(hardwired=false, trend(interval=3600, enable=true))); @@ -632,8 +631,8 @@ For example, a block includes annotation (__cdl(generatePointlist=true)); It specifies that a point list should be generated for the sequence, the ``uWin`` is a -hardwired digital input point that can be used for trending and alarming, -and the ``yVal`` is not a hardwired point that can only be used for trending. +digital input point that is hardwired, and the ``yVal`` is a analog output point that +is not hardwired. Both of them can be trended with time interval of 1 hour. The point list table will be like: .. _tab_sample_point_list: @@ -641,15 +640,15 @@ The point list table will be like: .. table:: Sample point list table generated by the ``modelica-json`` tool :class: longtable - ======================== =========== ========= ========== ======== ======== ======== ================================================ - System/Equipment Name Type Hardwired? Trend Alarm Schedule Notes - ======================== =========== ========= ========== ======== ======== ======== ================================================ - Terminal unit ``uWin`` DI Yes 3600 true Windows status - ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ - Terminal unit ``yVal`` AO 3600 Signal for heating coil valve - ------------------------ ----------- --------- ---------- -------- -------- -------- ------------------------------------------------ - ... ... ... ... ... ... ... ... - ======================== =========== ========= ========== ======== ======== ======== ================================================ + ======================== =========== ========= ========== ======== ================================================ + System/Equipment Name Type Hardwired? Trend Notes + ======================== =========== ========= ========== ======== ================================================ + Terminal unit ``uWin`` DI Yes 3600 Windows status + ------------------------ ----------- --------- ---------- -------- ------------------------------------------------ + Terminal unit ``yVal`` AO No 3600 Signal for heating coil valve + ------------------------ ----------- --------- ---------- -------- ------------------------------------------------ + ... ... ... ... ... ... + ======================== =========== ========= ========== ======== ================================================ .. _sec_connectors: From 936db6fd1225c56ee0be282abe9c113fb40aa6c2 Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Mon, 14 Sep 2020 08:59:29 -0700 Subject: [PATCH 14/28] Revised point list, added todo --- specification/source/cdl.rst | 70 ++++++++++++++++++++++++++---------- 1 file changed, 51 insertions(+), 19 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index b1603193..3b46e327 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -601,18 +601,51 @@ Point list The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` (:numref:`fig_cdl_pro_lin`) and further generate the point list table. By default, -* The connector ``RealInput`` and ``IntegerInput`` are analog input. -* The connector ``RealOutput`` and ``IntegerOutput`` are analog output. -* The connector ``BooleanInput`` and ``BooleanOutput`` are digital input and output. +* The connectors ``RealInput`` and ``IntegerInput`` are analog input. +* The connectors ``RealOutput`` and ``IntegerOutput`` are analog output. +* The connectors ``BooleanInput`` and ``BooleanOutput`` are digital input and output. -The vendor annotation ``__cdl(generatePointlist=true)`` in class level specifies -whether to generate point list of the sequence. It allows a sequence to not generate -the point list in the case when it is used for composing other sequence so it is not -connected externally. The connector could have the vendor annotation like -``__cdl(hardwired=false, trend())``. It indicates that if it -is hardwired point and how it is used for trending. +The vendor annotation ``__cdl(generatePointlist=Boolean)`` at the block level specifies +that a point list of the sequence is generated. +If not specified, it is assumed that ``__cdl(generatePointlist=false)``. +[Hence, if not specified, or if ``__cdl(generatePointlist=false)`` is specified, +no point list is generated. This typically is used for subsequences that are +not connected to external signals.] -For example, a block includes +When instantiating a block, this annotation can also be added to the instantiation clause, +and it will overwrite the class level declaration. + +[For example, consider the pseude-code + +.. code-block:: modelica + + MyController con1 annotation(__cdl(generatePointlist=true); + MyController con2 annotation(__cdl(generatePointlist=false); + + ... + + block MyController + ... + annotation(__cdl(generatePointlist=true)); + end MyController; + +This will generate a point list for ``con1`` but not for ``con2``. +] + +Connectors can have a vendor annotation of the form +``__cdl(connection(hardwired=Boolean)``. +The field ``hardwired`` specifies whether the connection should be hardwired or not, +the default value is ``false``. + +Connectors can have a vendor annotation of the form +``__cdl(trend(interval=Real, enable=Boolean)``. +The field ``interval`` must be specified and its value is the trending interval in seconds, +and the field ``enable`` is optional, with default value of ``true``, and +it can be used to overwrite the value used in the sequence declaration. + +.. todo:: Specify how to overwrite these annotation in blocks and connectors that are part of a subsequence of an instanciated controller. + +[For example, consider the pseudo-code .. code-block:: modelica @@ -621,18 +654,16 @@ For example, a block includes ...; CDL.Interfaces.BooleanInput uWin "Windows status" annotation (__cdl(hardwired=true, - trend(interval=3600, enable=true))); + trend(interval=60, enable=true))); CDL.Interfaces.RealOutput yVal "Signal for heating coil valve" annotation (__cdl(hardwired=false, - trend(interval=3600, enable=true))); - ...; - equations - ...; + trend(interval=60, enable=true))); + ... annotation (__cdl(generatePointlist=true)); It specifies that a point list should be generated for the sequence, the ``uWin`` is a digital input point that is hardwired, and the ``yVal`` is a analog output point that -is not hardwired. Both of them can be trended with time interval of 1 hour. +is not hardwired. Both of them can be trended with time interval of 1 minute. The point list table will be like: .. _tab_sample_point_list: @@ -641,15 +672,16 @@ The point list table will be like: :class: longtable ======================== =========== ========= ========== ======== ================================================ - System/Equipment Name Type Hardwired? Trend Notes + System/Equipment Name Type Hardwired? Trend Description ======================== =========== ========= ========== ======== ================================================ - Terminal unit ``uWin`` DI Yes 3600 Windows status + Terminal unit ``uWin`` DI Yes 60 Windows status ------------------------ ----------- --------- ---------- -------- ------------------------------------------------ - Terminal unit ``yVal`` AO No 3600 Signal for heating coil valve + Terminal unit ``yVal`` AO No 60 Signal for heating coil valve ------------------------ ----------- --------- ---------- -------- ------------------------------------------------ ... ... ... ... ... ... ======================== =========== ========= ========== ======== ================================================ +] .. _sec_connectors: From 5b961c4ce342a4b57f91fca72f371c884edc791e Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Tue, 27 Oct 2020 11:21:37 -0700 Subject: [PATCH 15/28] added vendor annotation propagate specification --- specification/source/cdl.rst | 88 +++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 2 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 3b46e327..edcf0960 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -615,7 +615,7 @@ not connected to external signals.] When instantiating a block, this annotation can also be added to the instantiation clause, and it will overwrite the class level declaration. -[For example, consider the pseude-code +[For example, consider the pseudo-code .. code-block:: modelica @@ -637,12 +637,96 @@ Connectors can have a vendor annotation of the form The field ``hardwired`` specifies whether the connection should be hardwired or not, the default value is ``false``. -Connectors can have a vendor annotation of the form +Connectors can also have a vendor annotation of the form ``__cdl(trend(interval=Real, enable=Boolean)``. The field ``interval`` must be specified and its value is the trending interval in seconds, and the field ``enable`` is optional, with default value of ``true``, and it can be used to overwrite the value used in the sequence declaration. +When translating the CDL sequences to ``CDL-JSON``, the ``modelica-json`` tool will +create a list which shows how the annotations propagate from top level controller to +the subsequence. It propagates the block level annotation through the class instantiation +and the connector annotations through the connection. +The propagations will overwrite the corresponding annotations in the subsequences. + +[For example, consider the pseudo-code + +.. code-block:: modelica + + block Controller + ... + Interfaces.RealInput u1 + annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true)); + Interfaces.RealInput u2 + annotation(__cdl(connection(hardwired=true), trend(interval=120, enable=true)); + ... + MyController con1 annotation(__cdl(generatePointlist=true); + MyController con2 annotation(__cdl(generatePointlist=false); + ... + equation + connect(u1, con1.u); + connect(u2, con2.u); + ... + annotation(__cdl(generatePointlist=true)); + end Controller; + + ... + + block MyController + Interfaces.RealInput u + annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true)); + ... + annotation(__cdl(generatePointlist=true)); + end MyController; + +The parser will generate a list of how the specifications being propagated as below + +.. code-block:: JSON + [ + { + "className": "Controller", + "points": [ + { + "name": "u1", + "hardwired": true, + "trend": { + "enable": true, + "interval": 60 + } + }, + { + "name": "u2", + "hardwired": true, + "trend": { + "enable": true, + "interval": 120 + } + } + ] + }, + { + "className": "Controller.con1", + "points": [ + { + "name": "u", + "hardwired": true, + "trend": { + "enable": true, + "interval": 60 + } + } + ] + } + ] + +] + + + + + + + .. todo:: Specify how to overwrite these annotation in blocks and connectors that are part of a subsequence of an instanciated controller. [For example, consider the pseudo-code From 8c0ed143e19abb2672cc61690ff0125b6e455210 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Tue, 27 Oct 2020 11:23:13 -0700 Subject: [PATCH 16/28] corrected format --- specification/source/cdl.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index edcf0960..f94fb34f 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -682,6 +682,7 @@ The propagations will overwrite the corresponding annotations in the subsequence The parser will generate a list of how the specifications being propagated as below .. code-block:: JSON + [ { "className": "Controller", @@ -718,7 +719,7 @@ The parser will generate a list of how the specifications being propagated as be ] } ] - + ] From 804afef2144a383cf43f74eb895f000d42f7407d Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Tue, 27 Oct 2020 11:25:30 -0700 Subject: [PATCH 17/28] revise text --- specification/source/cdl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index f94fb34f..aadb364e 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -679,7 +679,7 @@ The propagations will overwrite the corresponding annotations in the subsequence annotation(__cdl(generatePointlist=true)); end MyController; -The parser will generate a list of how the specifications being propagated as below +The parser will generate an annotation propagation list as below: .. code-block:: JSON From ec8676c97b75509cc66b32480ecd9d970dd95aa8 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Tue, 27 Oct 2020 11:42:51 -0700 Subject: [PATCH 18/28] reformated text --- specification/source/cdl.rst | 36 ++++++------------------------------ 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index aadb364e..3620f17d 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -615,23 +615,6 @@ not connected to external signals.] When instantiating a block, this annotation can also be added to the instantiation clause, and it will overwrite the class level declaration. -[For example, consider the pseudo-code - -.. code-block:: modelica - - MyController con1 annotation(__cdl(generatePointlist=true); - MyController con2 annotation(__cdl(generatePointlist=false); - - ... - - block MyController - ... - annotation(__cdl(generatePointlist=true)); - end MyController; - -This will generate a point list for ``con1`` but not for ``con2``. -] - Connectors can have a vendor annotation of the form ``__cdl(connection(hardwired=Boolean)``. The field ``hardwired`` specifies whether the connection should be hardwired or not, @@ -643,10 +626,10 @@ The field ``interval`` must be specified and its value is the trending interval and the field ``enable`` is optional, with default value of ``true``, and it can be used to overwrite the value used in the sequence declaration. -When translating the CDL sequences to ``CDL-JSON``, the ``modelica-json`` tool will -create a list which shows how the annotations propagate from top level controller to -the subsequence. It propagates the block level annotation through the class instantiation -and the connector annotations through the connection. +When translating the CDL sequences to ``CDL-JSON`` (:numref:`fig_cdl_pro_lin`), +the ``modelica-json`` tool will create a list which shows how the annotations propagate +from top level controller to the subsequence. It propagates the block level annotation +through the class instantiation and the connector annotations through the connection. The propagations will overwrite the corresponding annotations in the subsequences. [For example, consider the pseudo-code @@ -679,7 +662,8 @@ The propagations will overwrite the corresponding annotations in the subsequence annotation(__cdl(generatePointlist=true)); end MyController; -The parser will generate an annotation propagation list as below: +The translator will generate an annotation propgation list as below. There will be point +list for ``Controller.con1`` but not for ``Controller.con2``. .. code-block:: JSON @@ -722,14 +706,6 @@ The parser will generate an annotation propagation list as below: ] - - - - - - -.. todo:: Specify how to overwrite these annotation in blocks and connectors that are part of a subsequence of an instanciated controller. - [For example, consider the pseudo-code .. code-block:: modelica From 011998ec58c8f642baad4a798b7d1b2e0fafac1e Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Fri, 30 Oct 2020 14:48:45 -0700 Subject: [PATCH 19/28] added warning specification --- specification/source/cdl.rst | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 3620f17d..1cffa14b 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -631,6 +631,12 @@ the ``modelica-json`` tool will create a list which shows how the annotations pr from top level controller to the subsequence. It propagates the block level annotation through the class instantiation and the connector annotations through the connection. The propagations will overwrite the corresponding annotations in the subsequences. +When in subsequence a connector is specified as hardwired point while its upstream +connector in top level is specified as software point, it will trigger a +warning and the annotations in subsequence will not be overwritten. +However, by specifying a vendor annotation ``__cdl(connection(suppressWarning=true))`` will +suppress the warning and allow the subsequence annotation being overwritten. The field +``suppressWarning`` has default value of ``false``. [For example, consider the pseudo-code @@ -641,14 +647,16 @@ The propagations will overwrite the corresponding annotations in the subsequence Interfaces.RealInput u1 annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true)); Interfaces.RealInput u2 - annotation(__cdl(connection(hardwired=true), trend(interval=120, enable=true)); + annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true)); ... MyController con1 annotation(__cdl(generatePointlist=true); MyController con2 annotation(__cdl(generatePointlist=false); ... equation - connect(u1, con1.u); - connect(u2, con2.u); + connect(u1, con1.u1); + connect(u2, con1.u2); + connect(u1, con2.u1); + connect(u2. con2.u2); ... annotation(__cdl(generatePointlist=true)); end Controller; @@ -656,8 +664,10 @@ The propagations will overwrite the corresponding annotations in the subsequence ... block MyController - Interfaces.RealInput u + Interfaces.RealInput u1 annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true)); + Interfaces.RealInput u2 + annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true)); ... annotation(__cdl(generatePointlist=true)); end MyController; @@ -681,7 +691,7 @@ list for ``Controller.con1`` but not for ``Controller.con2``. }, { "name": "u2", - "hardwired": true, + "hardwired": false, "trend": { "enable": true, "interval": 120 @@ -693,7 +703,15 @@ list for ``Controller.con1`` but not for ``Controller.con2``. "className": "Controller.con1", "points": [ { - "name": "u", + "name": "u1", + "hardwired": true, + "trend": { + "enable": true, + "interval": 60 + } + }, + { + "name": "u2", "hardwired": true, "trend": { "enable": true, From f9f8db34f32fbdd952cb4b202aa10d246aad73c3 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Fri, 30 Oct 2020 14:55:42 -0700 Subject: [PATCH 20/28] added the warning specification when the annotation is not specified --- specification/source/cdl.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 1cffa14b..b1605bc8 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -636,7 +636,8 @@ connector in top level is specified as software point, it will trigger a warning and the annotations in subsequence will not be overwritten. However, by specifying a vendor annotation ``__cdl(connection(suppressWarning=true))`` will suppress the warning and allow the subsequence annotation being overwritten. The field -``suppressWarning`` has default value of ``false``. +``suppressWarning`` has default value of ``false`` and if it is not specified, the +warning will not be suppressed. [For example, consider the pseudo-code From f29a08bcde1fe66d226c2ebb765faa2cff319778 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Fri, 30 Oct 2020 15:01:56 -0700 Subject: [PATCH 21/28] updated example --- specification/source/cdl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index b1605bc8..66e269a5 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -733,10 +733,10 @@ list for ``Controller.con1`` but not for ``Controller.con2``. block Controller "Controller for room VAV box" ...; CDL.Interfaces.BooleanInput uWin "Windows status" - annotation (__cdl(hardwired=true, + annotation (__cdl(connection(hardwired=true), trend(interval=60, enable=true))); CDL.Interfaces.RealOutput yVal "Signal for heating coil valve" - annotation (__cdl(hardwired=false, + annotation (__cdl(connection(hardwired=false), trend(interval=60, enable=true))); ... annotation (__cdl(generatePointlist=true)); From 7c2d8a8fbb1ba877122b6ae99e806bc7bca6cba2 Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Wed, 2 Dec 2020 18:28:48 -0800 Subject: [PATCH 22/28] Revised point list specification --- specification/source/cdl.rst | 167 +++++++++++++++++++++++++++-------- 1 file changed, 128 insertions(+), 39 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 9c8aa201..db0c4285 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -789,47 +789,131 @@ then the block (or input connector) upstream of the output will always be presen Point list .......... -The ``modelica-json`` tool translates the CDL sequences to ``CDL-JSON`` -(:numref:`fig_cdl_pro_lin`) and further generate the point list table. By default, +From CDL-conforming sequences, point lists can be generated. +[This could be accomplished using the ``modelica-json`` tool, +see :numref:`fig_cdl_pro_lin`.] -* The connectors ``RealInput`` and ``IntegerInput`` are analog input. -* The connectors ``RealOutput`` and ``IntegerOutput`` are analog output. -* The connectors ``BooleanInput`` and ``BooleanOutput`` are digital input and output. +For point lists, -The vendor annotation ``__cdl(generatePointlist=Boolean)`` at the block level specifies +* the connectors ``RealInput`` and ``IntegerInput`` are analog inputs. +* the connectors ``RealOutput`` and ``IntegerOutput`` are analog outputs. +* the connectors ``BooleanInput`` and ``BooleanOutput`` are digital inputs and outputs. + +.. _sec_ann_cau_poi_lis: + +Annotations that Cause Point Lists to be Generated +__________________________________________________ + + +The vendor annotation ``__cdl(generatePointlist=Boolean)`` at the class level specifies that a point list of the sequence is generated. If not specified, it is assumed that ``__cdl(generatePointlist=false)``. -[Hence, if not specified, or if ``__cdl(generatePointlist=false)`` is specified, -no point list is generated. This typically is used for subsequences that are -not connected to external signals.] -When instantiating a block, this annotation can also be added to the instantiation clause, -and it will overwrite the class level declaration. +When instantiating a block, the ``__cdl(generatePointlist=Boolean)`` annotation +can also be added to the instantiation clause, +and it will override the class level declaration. + +[For example, + +.. code-block:: modelica + + block A + MyController con1; + MyController con2 annotation(__cdl(generatePointlist=false)); + annotation(__cdl(generatePointlist=true)); + end A; + +generates a point list for `A.con1` only, while + +.. code-block:: modelica + + block A + MyController con1; + MyController con2 annotation(__cdl(generatePointlist=true)); + annotation(__cdl(generatePointlist=false)); + end A; + +generates a point list for `A.con2` only.] + +The `generatePointlist` annotation can be propagated down in a hierarchical controller +by specifying in the instantiantion clause the annotation + +.. code-block:: modelica + + __cdl(propagate(instance="subCon1", generatePointlist=true)) + +Controllers deeper in the hierarchy are referred to using the dot notation, such as in +``instance="subCon1.subSubCon1"`` where ``subSubCon1`` is an instance in ``subCon1``. + +The instance in the ``instance=`` must exist, but it can be conditionally removed (see :numref:`sec_con_rem_ins`), +in which case the declaration can safely be ignored. + +Higher-level declarations override lower-level declarations. + +[For example, assume `con1` has a block called `subCon1`. Then, the declaration + +.. code-block:: modelica + + MyController con1 annotation(__cdl(propagate(instance="subCon1", generatePointlist=true))); + +sets ``generatePointlist=true`` in the instance ``con1.subCon1``.] + + +Annotations for Connectors +__________________________ Connectors can have a vendor annotation of the form -``__cdl(connection(hardwired=Boolean)``. + +.. code-block:: modelica + + __cdl(connection(hardwired=Boolean)) + The field ``hardwired`` specifies whether the connection should be hardwired or not, the default value is ``false``. Connectors can also have a vendor annotation of the form -``__cdl(trend(interval=Real, enable=Boolean)``. -The field ``interval`` must be specified and its value is the trending interval in seconds, -and the field ``enable`` is optional, with default value of ``true``, and + +.. code-block:: modelica + + __cdl(trend(interval=Real, enable=Boolean)) + +The field ``interval`` must be specified and its value is the trending interval in seconds. +The field ``enable`` is optional, with default value of ``true``, and it can be used to overwrite the value used in the sequence declaration. -When translating the CDL sequences to ``CDL-JSON`` (:numref:`fig_cdl_pro_lin`), +Similar to ``generatePointlist``, the ``connection`` and ``trend`` annotations can be +propagated as +``__cdl(propagate(instance="subCon1", connection(hardwired=Boolean)))`` +or as +``__cdl(propagate(instance="subCon1", trend(interval=Real, enable=Boolean)))``. +As in :numref:`sec_ann_cau_poi_lis`, the instance in ``instance=`` must exist, and higher-level declarations override lower-level declarations. + + +**I don't think the paragraph below is needed anymore** + +[When translating the CDL sequences to ``CDL-JSON`` (:numref:`fig_cdl_pro_lin`), the ``modelica-json`` tool will create a list which shows how the annotations propagate -from top level controller to the subsequence. It propagates the block level annotation -through the class instantiation and the connector annotations through the connection. -The propagations will overwrite the corresponding annotations in the subsequences. -When in subsequence a connector is specified as hardwired point while its upstream +from the top level controller to the subsequences. +Because by the above convention, instance-level declarations have priority over class-level declarations, +the ``modelica-json`` tool +propagates block level annotations +through the class instantiations. +Similarly, it also propagates connector annotations through the ``connect`` statements **I don't think this propagation is needed**. +The propagations will overwrite the corresponding annotations in the subsequences.] + +**I don't think the paragraph below is needed anymore** + +When in a subsequence a connector is specified as hardwired point while its upstream connector in top level is specified as software point, it will trigger a -warning and the annotations in subsequence will not be overwritten. +warning and the annotation in the subsequence will not be overwritten. However, by specifying a vendor annotation ``__cdl(connection(suppressWarning=true))`` will suppress the warning and allow the subsequence annotation being overwritten. The field ``suppressWarning`` has default value of ``false`` and if it is not specified, the warning will not be suppressed. +**I don't see a use for ``suppressWarning`` anymore** + + [For example, consider the pseudo-code .. code-block:: modelica @@ -864,7 +948,7 @@ warning will not be suppressed. annotation(__cdl(generatePointlist=true)); end MyController; -The translator will generate an annotation propgation list as below. There will be point +The translator will generate an annotation propagation list as shown below. There will be point list for ``Controller.con1`` but not for ``Controller.con2``. .. code-block:: JSON @@ -914,9 +998,13 @@ list for ``Controller.con1`` but not for ``Controller.con2``. } ] -] +] + +Example for a Point List +________________________ -[For example, consider the pseudo-code + +For an example of a point list generation, consider the pseudo-code shown below. .. code-block:: modelica @@ -932,27 +1020,28 @@ list for ``Controller.con1`` but not for ``Controller.con2``. ... annotation (__cdl(generatePointlist=true)); -It specifies that a point list should be generated for the sequence, the ``uWin`` is a -digital input point that is hardwired, and the ``yVal`` is a analog output point that -is not hardwired. Both of them can be trended with time interval of 1 minute. -The point list table will be like: +It specifies that a point list should be generated for the sequence, that ``uWin`` is a +digital input point that is hardwired, and that ``yVal`` is a analog output point that +is not hardwired. Both of them can be trended with a time interval of 1 minute. +The point list table will look as shown in :numref:`tab_sample_point_list`. + +**In the table below, from where do you deduce programmatically the information that it is a "Terminal unit"?** .. _tab_sample_point_list: -.. table:: Sample point list table generated by the ``modelica-json`` tool +.. table:: Sample point list table generated by the ``modelica-json`` tool. :class: longtable - ======================== =========== ========= ========== ======== ================================================ - System/Equipment Name Type Hardwired? Trend Description - ======================== =========== ========= ========== ======== ================================================ - Terminal unit ``uWin`` DI Yes 60 Windows status - ------------------------ ----------- --------- ---------- -------- ------------------------------------------------ - Terminal unit ``yVal`` AO No 60 Signal for heating coil valve - ------------------------ ----------- --------- ---------- -------- ------------------------------------------------ - ... ... ... ... ... ... - ======================== =========== ========= ========== ======== ================================================ + ======================== =========== ========= ========== =========== ================================================ + System/Equipment Name Type Hardwired? Trend [s] Description + ======================== =========== ========= ========== =========== ================================================ + Terminal unit ``uWin`` DI Yes 60 Windows status + ------------------------ ----------- --------- ---------- ----------- ------------------------------------------------ + Terminal unit ``yVal`` AO No 60 Signal for heating coil valve + ------------------------ ----------- --------- ---------- ----------- ------------------------------------------------ + ... ... ... ... ... ... + ======================== =========== ========= ========== =========== ================================================ -] .. _sec_connectors: From fd7c0d77d0b675b7e0aed9cc85e3e41f5a9d35b6 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Tue, 15 Dec 2020 14:45:54 -0800 Subject: [PATCH 23/28] cleaned specification and added comments --- specification/source/cdl.rst | 87 +++++++++++++++++------------------- 1 file changed, 41 insertions(+), 46 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index db0c4285..1394958c 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -857,7 +857,7 @@ Higher-level declarations override lower-level declarations. MyController con1 annotation(__cdl(propagate(instance="subCon1", generatePointlist=true))); sets ``generatePointlist=true`` in the instance ``con1.subCon1``.] - +[**What if `con1` has another block called `subCon2` and also needs to generate the point list? It seems that the `instance` should be specified to be an array, like `{"subCon1", "subCon2"}`.**] Annotations for Connectors __________________________ @@ -886,54 +886,32 @@ propagated as ``__cdl(propagate(instance="subCon1", connection(hardwired=Boolean)))`` or as ``__cdl(propagate(instance="subCon1", trend(interval=Real, enable=Boolean)))``. -As in :numref:`sec_ann_cau_poi_lis`, the instance in ``instance=`` must exist, and higher-level declarations override lower-level declarations. - - -**I don't think the paragraph below is needed anymore** - -[When translating the CDL sequences to ``CDL-JSON`` (:numref:`fig_cdl_pro_lin`), -the ``modelica-json`` tool will create a list which shows how the annotations propagate -from the top level controller to the subsequences. -Because by the above convention, instance-level declarations have priority over class-level declarations, -the ``modelica-json`` tool -propagates block level annotations -through the class instantiations. -Similarly, it also propagates connector annotations through the ``connect`` statements **I don't think this propagation is needed**. -The propagations will overwrite the corresponding annotations in the subsequences.] - -**I don't think the paragraph below is needed anymore** - -When in a subsequence a connector is specified as hardwired point while its upstream -connector in top level is specified as software point, it will trigger a -warning and the annotation in the subsequence will not be overwritten. -However, by specifying a vendor annotation ``__cdl(connection(suppressWarning=true))`` will -suppress the warning and allow the subsequence annotation being overwritten. The field -``suppressWarning`` has default value of ``false`` and if it is not specified, the -warning will not be suppressed. - -**I don't see a use for ``suppressWarning`` anymore** - +[**Is the `subCon1` the instance inside `con1`? Should the `instance="subCon1"` be `instance="con1"`, or even `instance={"con1", "con2"}`, as `con1` and `con2` connect to the connector?**] +As in :numref:`sec_ann_cau_poi_lis`, the instance in ``instance=`` must exist, and higher-level +declarations override lower-level declarations. [For example, consider the pseudo-code .. code-block:: modelica block Controller - ... + Interfaces.RealInput u1 - annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true)); + annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true))); Interfaces.RealInput u2 - annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true)); - ... - MyController con1 annotation(__cdl(generatePointlist=true); - MyController con2 annotation(__cdl(generatePointlist=false); - ... - equation + annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true), + propagate(instance="con1", connection(hardwired=false), trend(interval=120, enable=true)))); + + MyController con1 annotation(__cdl(generatePointlist=true)); + MyController con2 annotation(__cdl(generatePointlist=false, + propagate(instance={"subCon1", "subCon2"}, generatePointlist=true))); + + equation connect(u1, con1.u1); connect(u2, con1.u2); connect(u1, con2.u1); - connect(u2. con2.u2); - ... + connect(u2, con2.u2); + annotation(__cdl(generatePointlist=true)); end Controller; @@ -941,15 +919,20 @@ warning will not be suppressed. block MyController Interfaces.RealInput u1 - annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true)); + annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true))); Interfaces.RealInput u2 - annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true)); + annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true))); + ... + SubController1 subCon1; + SubController2 subCon2; ... annotation(__cdl(generatePointlist=true)); end MyController; The translator will generate an annotation propagation list as shown below. There will be point -list for ``Controller.con1`` but not for ``Controller.con2``. +list for ``Controller``, ``Controller.con1``, ``Controller.con2.subCon1`` and +``Controller.con2.subCon1``. Also, the annotation `connection(hardwired=true), trend(interval=60, enable=true)` +of `con1.u2` will be overridden as `connection(hardwired=false), trend(interval=120, enable=true)`. .. code-block:: JSON @@ -980,21 +963,33 @@ list for ``Controller.con1`` but not for ``Controller.con2``. "points": [ { "name": "u1", - "hardwired": true, + "hardwired": false, "trend": { "enable": true, - "interval": 60 + "interval": 120 } }, { "name": "u2", - "hardwired": true, + "hardwired": false, "trend": { "enable": true, - "interval": 60 + "interval": 120 } } ] + }, + { + "className": "Controller.con2.subCon1", + "points": [ + ... + ] + }, + { + "className": "Controller.con2.subCon2", + "points": [ + ... + ] } ] @@ -1018,7 +1013,7 @@ For an example of a point list generation, consider the pseudo-code shown below. annotation (__cdl(connection(hardwired=false), trend(interval=60, enable=true))); ... - annotation (__cdl(generatePointlist=true)); + annotation (__cdl(generatePointlist=true, controlledDevice="Terminal unit")); It specifies that a point list should be generated for the sequence, that ``uWin`` is a digital input point that is hardwired, and that ``yVal`` is a analog output point that From d27ae255a991323af49d1962e5283abec8f63121 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Tue, 15 Dec 2020 14:52:09 -0800 Subject: [PATCH 24/28] updated format --- specification/source/cdl.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 1394958c..d29c9e8f 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -857,7 +857,7 @@ Higher-level declarations override lower-level declarations. MyController con1 annotation(__cdl(propagate(instance="subCon1", generatePointlist=true))); sets ``generatePointlist=true`` in the instance ``con1.subCon1``.] -[**What if `con1` has another block called `subCon2` and also needs to generate the point list? It seems that the `instance` should be specified to be an array, like `{"subCon1", "subCon2"}`.**] +[**What if ``con1`` has another block called ``subCon2`` and also needs to generate the point list? It seems that the ``instance`` should be specified to be an array, like ``{"subCon1", "subCon2"}``.**] Annotations for Connectors __________________________ @@ -886,7 +886,7 @@ propagated as ``__cdl(propagate(instance="subCon1", connection(hardwired=Boolean)))`` or as ``__cdl(propagate(instance="subCon1", trend(interval=Real, enable=Boolean)))``. -[**Is the `subCon1` the instance inside `con1`? Should the `instance="subCon1"` be `instance="con1"`, or even `instance={"con1", "con2"}`, as `con1` and `con2` connect to the connector?**] +[**Is the ``subCon1`` the instance inside ``con1``? Should the ``instance="subCon1"`` be ``instance="con1"``, or even ``instance={"con1", "con2"}``, as ``con1`` and ``con2`` connect to the connector?**] As in :numref:`sec_ann_cau_poi_lis`, the instance in ``instance=`` must exist, and higher-level declarations override lower-level declarations. @@ -931,8 +931,8 @@ declarations override lower-level declarations. The translator will generate an annotation propagation list as shown below. There will be point list for ``Controller``, ``Controller.con1``, ``Controller.con2.subCon1`` and -``Controller.con2.subCon1``. Also, the annotation `connection(hardwired=true), trend(interval=60, enable=true)` -of `con1.u2` will be overridden as `connection(hardwired=false), trend(interval=120, enable=true)`. +``Controller.con2.subCon1``. Also, the annotation ``connection(hardwired=true), trend(interval=60, enable=true)`` +of ``con1.u2`` will be overridden as ``connection(hardwired=false), trend(interval=120, enable=true)``. .. code-block:: JSON From 9c85bc44f993817feb556e40dd0b0b0cf0172fa5 Mon Sep 17 00:00:00 2001 From: JayHuLBL Date: Tue, 15 Dec 2020 14:54:18 -0800 Subject: [PATCH 25/28] removed comment --- specification/source/cdl.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index d29c9e8f..1fd2e438 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -1020,8 +1020,6 @@ digital input point that is hardwired, and that ``yVal`` is a analog output poi is not hardwired. Both of them can be trended with a time interval of 1 minute. The point list table will look as shown in :numref:`tab_sample_point_list`. -**In the table below, from where do you deduce programmatically the information that it is a "Terminal unit"?** - .. _tab_sample_point_list: .. table:: Sample point list table generated by the ``modelica-json`` tool. From 7bad0488a2de5996d38ff4cce6b24c9703421b90 Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Wed, 16 Dec 2020 06:04:34 -0800 Subject: [PATCH 26/28] Revised to allow multiple instances in propagate annotation --- specification/source/cdl.rst | 85 ++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 18 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 1fd2e438..87252686 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -835,7 +835,7 @@ generates a point list for `A.con1` only, while generates a point list for `A.con2` only.] -The `generatePointlist` annotation can be propagated down in a hierarchical controller +The `generatePointlist` annotation can be propagated down in a composite block (see :numref:`sec_com_blo`) by specifying in the instantiantion clause the annotation .. code-block:: modelica @@ -843,9 +843,11 @@ by specifying in the instantiantion clause the annotation __cdl(propagate(instance="subCon1", generatePointlist=true)) Controllers deeper in the hierarchy are referred to using the dot notation, such as in -``instance="subCon1.subSubCon1"`` where ``subSubCon1`` is an instance in ``subCon1``. +``instance="subCon1.subSubCon1"`` where ``subSubCon1`` is an instance of an elementary or composite block in ``subCon1``. -The instance in the ``instance=`` must exist, but it can be conditionally removed (see :numref:`sec_con_rem_ins`), +The value of ``instance=`` must be an elementary block (see :numref:`sec_ele_bui_blo`) +or a composite block (see :numref:`sec_com_blo`). It +must declared, but it can be conditionally removed (see :numref:`sec_con_rem_ins`), in which case the declaration can safely be ignored. Higher-level declarations override lower-level declarations. @@ -857,12 +859,28 @@ Higher-level declarations override lower-level declarations. MyController con1 annotation(__cdl(propagate(instance="subCon1", generatePointlist=true))); sets ``generatePointlist=true`` in the instance ``con1.subCon1``.] -[**What if ``con1`` has another block called ``subCon2`` and also needs to generate the point list? It seems that the ``instance`` should be specified to be an array, like ``{"subCon1", "subCon2"}``.**] + +There can be any number of ``propagate(...)`` annotations for a controller. +[Specifying multiple ``propagate(...)`` annotations is useful for composite controllers. +For example, + +.. code-block:: modelica + + MyController con1 annotation( + __cdl( + propagate(instance="subCon1", generatePointlist=true), + propagate(instance="subCon1.subSubCon1", generatePointlist=true), + propagate(instance="subCon1.subSubCon2", generatePointlist=false) + ) + ); + +allows a finegrained propagation to individual blocks of a composite block. +] Annotations for Connectors __________________________ -Connectors can have a vendor annotation of the form +Connectors (see :numref:`sec_connectors`) can have a vendor annotation of the form .. code-block:: modelica @@ -882,13 +900,40 @@ The field ``enable`` is optional, with default value of ``true``, and it can be used to overwrite the value used in the sequence declaration. Similar to ``generatePointlist``, the ``connection`` and ``trend`` annotations can be -propagated as -``__cdl(propagate(instance="subCon1", connection(hardwired=Boolean)))`` -or as -``__cdl(propagate(instance="subCon1", trend(interval=Real, enable=Boolean)))``. -[**Is the ``subCon1`` the instance inside ``con1``? Should the ``instance="subCon1"`` be ``instance="con1"``, or even ``instance={"con1", "con2"}``, as ``con1`` and ``con2`` connect to the connector?**] -As in :numref:`sec_ann_cau_poi_lis`, the instance in ``instance=`` must exist, and higher-level -declarations override lower-level declarations. +propagated. If a composite block contains a block ``con1``, which in turn contains a block ``subCon1`` that +has an input ``u``, the declaration + +.. code-block:: modelica + + MyController con1 annotation( + __cdl(propagate(instance="subCon1.u", connection(hardwired=Boolean))); + +can be used to set the type of connection of input (or output) ``con1.subCon1.u``. +The value of ``instance==`` must be a connector. + +Similarly, the declaration + +.. code-block:: modelica + + MyController con1 annotation( + __cdl(propagate(instance="subCon1.u", trend(interval=Real, enable=Boolean))); + +can be used to set how to trend that input (or output). + +These statements can also be combined into + +.. code-block:: modelica + + MyController con1 annotation( + __cdl(propagate(instance="subCon1.u", connection(hardwired=Boolean), + trend(interval=Real, enable=Boolean))); + + +As in :numref:`sec_ann_cau_poi_lis`, + +- the instance in ``instance=`` must exist, (but it can be conditionally removed in which case the annotation can be ignored), +- higher-level declarations override lower-level declarations, and +- any number of ``propagate(...)`` annotations can be present. [For example, consider the pseudo-code @@ -899,14 +944,18 @@ declarations override lower-level declarations. Interfaces.RealInput u1 annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true))); Interfaces.RealInput u2 - annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true), - propagate(instance="con1", connection(hardwired=false), trend(interval=120, enable=true)))); + annotation(__cdl(connection(hardwired=false), + trend(interval=120, enable=true), + propagate(instance="con1.u1", + connection(hardwired=false), + trend(interval=120, enable=true)))); MyController con1 annotation(__cdl(generatePointlist=true)); MyController con2 annotation(__cdl(generatePointlist=false, - propagate(instance={"subCon1", "subCon2"}, generatePointlist=true))); + propagate(instance="subCon1", generatePointlist=true), + propagate(instance="subCon2", generatePointlist=true))); - equation + equation connect(u1, con1.u1); connect(u2, con1.u2); connect(u1, con2.u1); @@ -921,7 +970,7 @@ declarations override lower-level declarations. Interfaces.RealInput u1 annotation(__cdl(connection(hardwired=false), trend(interval=120, enable=true))); Interfaces.RealInput u2 - annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true))); + annotation(__cdl(connection(hardwired=true), trend(interval=60, enable=true))); ... SubController1 subCon1; SubController2 subCon2; @@ -934,7 +983,7 @@ list for ``Controller``, ``Controller.con1``, ``Controller.con2.subCon1`` and ``Controller.con2.subCon1``. Also, the annotation ``connection(hardwired=true), trend(interval=60, enable=true)`` of ``con1.u2`` will be overridden as ``connection(hardwired=false), trend(interval=120, enable=true)``. -.. code-block:: JSON +.. code-block:: javascript [ { From 52e668ba3638a38eb62d81c13bd4ebab2b93342c Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Tue, 5 Jan 2021 13:04:11 -0800 Subject: [PATCH 27/28] Added explanation for controlledDevice --- specification/source/cdl.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 87252686..03b3d629 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -1064,7 +1064,8 @@ For an example of a point list generation, consider the pseudo-code shown below. ... annotation (__cdl(generatePointlist=true, controlledDevice="Terminal unit")); -It specifies that a point list should be generated for the sequence, that ``uWin`` is a +It specifies that a point list should be generated for the sequence that controls the +system or equipment specified by ``controlledDevice``, that ``uWin`` is a digital input point that is hardwired, and that ``yVal`` is a analog output point that is not hardwired. Both of them can be trended with a time interval of 1 minute. The point list table will look as shown in :numref:`tab_sample_point_list`. From 27be74f3080c43e5498fca9552fad42db0352293 Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Tue, 5 Jan 2021 13:17:28 -0800 Subject: [PATCH 28/28] Added controlledDevice explanation --- specification/source/cdl.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 03b3d629..bedbae04 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -805,9 +805,11 @@ Annotations that Cause Point Lists to be Generated __________________________________________________ -The vendor annotation ``__cdl(generatePointlist=Boolean)`` at the class level specifies +The vendor annotation ``__cdl(generatePointlist=Boolean, controlledDevice=String)`` at the class level specifies that a point list of the sequence is generated. If not specified, it is assumed that ``__cdl(generatePointlist=false)``. +The key ``controlledDevice`` is optional. It can be used to list the device that is being controlled. +Its value will be written to the point list, but not used otherwise, see :numref:`tab_sample_point_list` for an example. When instantiating a block, the ``__cdl(generatePointlist=Boolean)`` annotation can also be added to the instantiation clause, @@ -1044,11 +1046,8 @@ of ``con1.u2`` will be overridden as ``connection(hardwired=false), trend(interv ] -Example for a Point List -________________________ - -For an example of a point list generation, consider the pseudo-code shown below. +[For an example of a point list generation, consider the pseudo-code shown below. .. code-block:: modelica @@ -1085,6 +1084,7 @@ The point list table will look as shown in :numref:`tab_sample_point_list`. ... ... ... ... ... ... ======================== =========== ========= ========== =========== ================================================ +] .. _sec_connectors: