diff --git a/.travis.yml b/.travis.yml index fcff94f7..684603e6 100644 --- a/.travis.yml +++ b/.travis.yml @@ -50,33 +50,26 @@ before_install: cd -; echo "Set up modelica-buildings at ${MODELICAPATH}"; -# For sphinx, we need to install specific package versions, otherwise -# the html output may have small formatting differences which causes -# the test to fail install: - pip3 install --upgrade pip wheel - - pip3 install sphinx==4.3.2 \ - sphinx-bootstrap-theme==0.8.0 \ - sphinxcontrib-bibtex==2.4.1 \ - sphinxcontrib-plantuml==0.22 \ - alabaster==0.7.12 \ - MarkupSafe==1.1.1 \ - Pygments==2.4.2 \ - snowballstemmer==1.9.0 \ - docutils==0.17.1 \ - Babel==2.7.0 \ - requests==2.27.0 \ - Jinja2==2.11.3 \ - latexcodec==1.0.7 \ - pybtex==0.24.0 \ - pybtex-docutils==1.0.1 \ - oset==0.1.3 \ - PyYAML==5.4 - - pip3 install -r ${TRAVIS_BUILD_DIR}/software/verification/requirements.txt # Execute tests script: - - (cd specification; make clean html; cd ..) - - (cd specification; make latex; cd ..) - - (cd specification; make linkcheck SPHINXOPTS=-W; cd ..) - - (cd software/verification; make test-verification; cd ../..) + - | + cd specification + python -m venv venv + source venv/bin/activate + pip install -r ${TRAVIS_BUILD_DIR}/specification/requirements.txt + make clean html + make latex + make linkcheck SPHINXOPTS=-W + deactivate + rm -rf venv + - | + cd software/verification + python -m venv venv + source venv/bin/activate + pip install -r ${TRAVIS_BUILD_DIR}/software/verification/requirements.txt + make test-verification + deactivate + rm -rf venv diff --git a/specification/requirements.txt b/specification/requirements.txt new file mode 100644 index 00000000..2fb8e672 --- /dev/null +++ b/specification/requirements.txt @@ -0,0 +1,7 @@ +Sphinx==5.3.0 +sphinx-bootstrap-theme==0.8.1 +sphinxcontrib-bibtex==2.6.5 +sphinxcontrib-htmlhelp==2.1.0 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-plantuml==0.31 +pillow==11.3.0 diff --git a/specification/source/cdl.rst b/specification/source/cdl.rst index 3a3f102c..245e6680 100644 --- a/specification/source/cdl.rst +++ b/specification/source/cdl.rst @@ -796,20 +796,20 @@ a translator from ``CDL-JSON`` to a control product line is allowed to ignore th Example 1: If a controller has two samplers called ``sam1`` and ``sam2`` and their parameter ``samplePeriod`` must satisfy ``sam1.samplePeriod = sam2.samplePeriod`` for the logic to work correctly, then the controller can be implemented using - `CDL.Logical.Sources.SampleTrigger `_ + `CDL.Logical.Sources.SampleTrigger `_ and connect its output to two instances of - `CDL.Discrete.TriggeredSampler `_ + `CDL.Discrete.TriggeredSampler `_ that sample the corresponding signals. Example 2: If a controller normalized two input signals by dividing it by a gain ``k1``, then rather than using two instances of - `CDL.Reals.MultiplyByParameter `_ + `CDL.Reals.MultiplyByParameter `_ with parameter ``k = 1/k1``, one could use a constant source - `CDL.Reals.Sources.Constant `_ + `CDL.Reals.Sources.Constant `_ with parameter ``k=k1`` and two instances of - `CDL.Reals.Divide `_, + `CDL.Reals.Divide `_, and then connect the output of the constant source with the inputs of the division blocks. @@ -1079,6 +1079,7 @@ 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. +Set ``interval = 0`` to trend the value each time it changes. The field ``enable`` is optional, with default value of ``true``, and it can be used to overwrite the value used in the sequence declaration. @@ -1582,10 +1583,10 @@ Thus, extension blocks can contain any declarations that are allowed in a Modeli - implement state machines. For example, the demand response client - `Buildings.Controls.DemandResponse.Client `_ + `Buildings.Controls.DemandResponse.Client `_ would be an extension block if it were to contain the annotation ``__cdl(extensionBlock=true)``, as would the Kalman filter that is used in the Example - `Buildings.Utilities.IO.Python_3_8.Examples.KalmanFilter `_. + `Buildings.Utilities.IO.Python_3_8.Examples.KalmanFilter `_. Translation of an extension block to json must reproduce the following: @@ -1850,7 +1851,7 @@ Semantic Information The buildings industry has started to integrate different metadata languages such as `Brick `_ and `Project Haystack `_ into their -control software and technology. `ASHRAE Standard 223p `_ +control software and technology. `ASHRAE Standard 223p `_ is another upcoming metadata language that will describe the equipment topology in buildings and also the flow of different media. This section specifies the syntax to support these metadata languages and include the semantic information represented using these languages in a CDL class. @@ -1879,8 +1880,8 @@ All semantic information shall be included under the ``semantic`` section within where ```` is a place holder for the semantic information. -The ``semantic`` annotation declared in the class definition shall -optionally contain the ``metadataLanguageDefinition`` or the +The ``semantic`` annotation declared in the class definition shall +optionally contain the ``metadataLanguageDefinition`` or the ``naturalLanguageDefinition`` for each of the languages used. The ``metadataLanguageDefinition`` and ``naturalLanguageDefinition`` are used to provide additional information about the different metadata @@ -1971,7 +1972,7 @@ language and can also be represented in multiple formats such as ``text/zinc``, ``text/turtle`` and ``application/ld+json``. -Semantic information in the class definition annotations shall optionally be used to +Semantic information in the class definition annotations shall optionally be used to define class level information about the metadata languages. These include, but are not restricted to, namespace definitions (namespaces in ontologies provide a means to unambiguously interpret @@ -2055,17 +2056,17 @@ Example: ] -````: The text ```` (including the ``<`` -and ``>`` characters) within the metadata of an annotation containing semantic +````: The text ```` (including the ``<`` +and ``>`` characters) within the metadata of an annotation containing semantic information shall be replaced with the fully qualified name of the instance that contains the semantic annotation. A fully qualified name to an instance -refers to the complete hierarchical path that specifies the instance's -location within an object structure. This qualified name shall include all -parent instances leading up to the current instance, with each level of +refers to the complete hierarchical path that specifies the instance's +location within an object structure. This qualified name shall include all +parent instances leading up to the current instance, with each level of instantiation separated by an underscore (“_”). If an instance is nested -within multiple levels of instance definitions, the text that -replaces ```` shall reflect the entire chain of instantiation. -This avoids the user having to repeat the name of the instance and +within multiple levels of instance definitions, the text that +replaces ```` shall reflect the entire chain of instantiation. +This avoids the user having to repeat the name of the instance and makes it less prone to errors and inconsistencies. [An example of CDL semantic information for an instance in a class with @@ -2104,20 +2105,20 @@ Example: ] ````: This syntax allows for a value of a parameter to be used -within an annotation containing semantic information where the ``parameter`` -shall refer to the name of a parameter instance within the -class. The text ```` (including the ``<`` and ``>`` characters) -shall be replaced by the value of the parameter. The class must have an -instance of a parameter with the name specified by ````, +within an annotation containing semantic information where the ``parameter`` +shall refer to the name of a parameter instance within the +class. The text ```` (including the ``<`` and ``>`` characters) +shall be replaced by the value of the parameter. The class must have an +instance of a parameter with the name specified by ````, otherwise the specification is not valid. [In the below example, if the fully qualified name of ``reaFloSup`` is -``reaFloSup``, the ```` will be replaced by ``reaFloSup``. +``reaFloSup``, the ```` will be replaced by ``reaFloSup``. The location of the sensor, represented by the ``brick:hasLocation`` -relationship, after replacing ```` will be ``bldg:``. +relationship, after replacing ```` will be ``bldg:``. ```` refers to the value of the ``zon`` parameter within the instantiated -``reaFloSup``, which is ``east``. Hence, the completely evaluated semantic -information becomes: +``reaFloSup``, which is ``east``. Hence, the completely evaluated semantic +information becomes: .. code-block:: modelica @@ -2130,7 +2131,7 @@ Example: MyCompositeBlock.MyFlowSensor reaFloSup (zon="east") "Supply Air Flow Rate" annotation ( __cdl(semantic( - metadataLanguage="Brick 1.3 text/turtle" + metadataLanguage="Brick 1.3 text/turtle" "bldg: a brick:Supply_Air_Flow_Sensor; brick:hasLocation bldg: ."))); diff --git a/specification/source/codeGeneration.rst b/specification/source/codeGeneration.rst index 508924a7..c22b343b 100644 --- a/specification/source/codeGeneration.rst +++ b/specification/source/codeGeneration.rst @@ -244,7 +244,7 @@ Finally, to import the FMU-ME in a runtime environment, various tools can be use * Dymola (https://www.3ds.com/products-services/catia/products/dymola/) * MapleSim (https://www.maplesoft.com/products/maplesim/) * SimulationX (https://www.esi-group.com/products/system-simulation) - * SystemModeler (https://www.wolfram.com/system-modeler/index.html) + * SystemModeler (https://www.wolfram.com/system-modeler/) See also https://fmi-standard.org/tools/ for other tools. @@ -347,7 +347,7 @@ be replaced. Moreover, certain transformations that do not change the response of the block are permissible: For example, consider the -`PID controller in the CDL library `_. +`PID controller in the CDL library `_. The implementation has a parameter for the time constant of the integrator block. If a control vendor requires the specification of an integrator gain rather than diff --git a/specification/source/conf.py b/specification/source/conf.py index 23909866..9a49548a 100644 --- a/specification/source/conf.py +++ b/specification/source/conf.py @@ -147,7 +147,7 @@ # ], # Render the next and previous page links in navbar. (Default: true) - 'navbar_sidebarrel': True, + 'navbar_sidebarrel': False, # Render the current pages TOC in the navbar. (Default: true) 'navbar_pagenav': True, @@ -174,7 +174,7 @@ # Fix navigation bar to top of page? # Values: "true" (default) or "false" - 'navbar_fixed_top': "false", + 'navbar_fixed_top': "true", # Location of link to source. # Options are "nav" (default), "footer" or anything else to exclude. @@ -340,7 +340,7 @@ \end{center} \hrule ~\\[2mm] -Copyright (c) 2017-2023\\ +Copyright (c) 2017-2025\\ The Regents of the University of California (through Lawrence Berkeley National Laboratory),\\ subject to receipt of any required approvals from U.S. Department of Energy.\\ @@ -519,8 +519,8 @@ %\hypersetup{hidelinks = true} % Makefile enables this for the 2 page printout % Set format of table of content. Otherwise, the titles stick to the page numbers in some cases -\usepackage[tocgraduated]{tocstyle} -\usetocstyle{nopagecolumn} +%\usepackage[tocgraduated]{tocstyle} +%\usetocstyle{nopagecolumn} \usepackage{pdfpages} \usepackage{tikz} diff --git a/specification/source/example.rst b/specification/source/example.rst index 0824c9da..4f565287 100644 --- a/specification/source/example.rst +++ b/specification/source/example.rst @@ -240,7 +240,7 @@ with their minimum and maximum values denoted by ``Min`` and ``Max``. .. figure:: img/case_study1/SystemRequests.* Composite block that implements the sequence for the VAV terminal units that output the system requests. - (`Browsable version `_.) + (`Browsable version `_.) .. _fig_dam_val_reh: @@ -708,7 +708,7 @@ implementations of the sequences published in Guideline 36. Such implementations would encapsulate the complexity and provide assurances that energy modeler and control providers have correct implementations. With the implementation in -the Modelica package +the Modelica package `Buildings.Controls.OBC.ASHRAE.G36 `_, we made such an implementation and laid out the structure and conventions. diff --git a/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.html b/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.html index af42d73d..c139de27 100644 --- a/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.html +++ b/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.html @@ -116,7 +116,7 @@

CustomPWithLimiter

Custom implementation of a P controller with variable output limiter

Functionality

- +

Block that outputs y = min(yMax, k*e), where @@ -169,7 +169,7 @@

Blocks

- CDL.Interfaces.RealInput + CDL.Interfaces.RealInput @@ -184,7 +184,7 @@

Blocks

- CDL.Interfaces.RealInput + CDL.Interfaces.RealInput @@ -199,7 +199,7 @@

Blocks

- CDL.Interfaces.RealOutput + CDL.Interfaces.RealOutput @@ -214,7 +214,7 @@

Blocks

- CDL.Reals.MultiplyByParameter + CDL.Reals.MultiplyByParameter @@ -236,7 +236,7 @@

Blocks

- CDL.Reals.Min + CDL.Reals.Min diff --git a/specification/source/references.bib b/specification/source/references.bib index 3700d985..d517403b 100755 --- a/specification/source/references.bib +++ b/specification/source/references.bib @@ -89,7 +89,7 @@ @Article{WetterZuoNouiduiPang2014 number = {4}, pages = {253--270}, year = {2014}, - doi = {DOI:10.1080/19401493.2013.765506} + url = {https://simulationresearch.lbl.gov/wetter/download/LBNL-1002944.pdf} } @@ -168,6 +168,6 @@ @inproceedings{KoehlerEtAl2016:1 Organization = {Modelica Association}, Pages = {35--42}, Title = {{Modelica-Association - Project "System Structure and Parameterization" - Early Insights}}, - doi = {DOI:10.3384/ecp1612435}, + doi = {10.3384/ecp1612435}, Url = {http://dx.doi.org/10.3384/ecp1612435}, Year = {2016}} diff --git a/specification/source/sequenceDocumentation.rst b/specification/source/sequenceDocumentation.rst index 511e0291..75bc1e46 100644 --- a/specification/source/sequenceDocumentation.rst +++ b/specification/source/sequenceDocumentation.rst @@ -74,13 +74,13 @@ 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_9_6_0.Examples.SingleFamilyHouse.RadiantHeatingCooling_TSurface `_. +`Buildings.ThermalZones.EnergyPlus_24_2_0.Examples.SingleFamilyHouse.RadiantHeatingCooling_TSurface `_. 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 `_ +`Buildings.Controls.OBC.RadiantSystems.Heating.HighMassSupplyTemperature_TRoom `_ and in -`Buildings.Controls.OBC.RadiantSystems.Cooling.HighMassSupplyTemperature_TRoomRelHum `_ +`Buildings.Controls.OBC.RadiantSystems.Cooling.HighMassSupplyTemperature_TRoomRelHum `_ using html format. To export sequences from these models, ``modelica-json`` will need to generate a diff --git a/specification/source/softwareArchitecture.rst b/specification/source/softwareArchitecture.rst index 598b9852..6cb5c069 100644 --- a/specification/source/softwareArchitecture.rst +++ b/specification/source/softwareArchitecture.rst @@ -46,8 +46,8 @@ a `CDL Parser` which parses the CDL language. This parser is currently in development at https://github.com/lbl-srg/modelica-json. [#parser]_ The CDL parser reads a `CDL-compliant Control Sequence`, which may be provided by the user or taken from -https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Controls_OBC_ASHRAE.html -and the `CDL Library`, see https://simulationresearch.lbl.gov/modelica/releases/v10.0.0/help/Buildings_Controls_OBC_CDL.html +https://simulationresearch.lbl.gov/modelica/releases/v12.1.0/help/Buildings_Controls_OBC_ASHRAE.html +and the `CDL Library`, see https://simulationresearch.lbl.gov/modelica/releases/v12.1.0/help/Buildings_Controls_OBC_CDL.html All these components will be made available through OpenStudio. This allows using the OpenStudio model authoring and simulation capability that is being developed diff --git a/specification/source/useCases.rst b/specification/source/useCases.rst index 58933214..32af8fb9 100644 --- a/specification/source/useCases.rst +++ b/specification/source/useCases.rst @@ -25,7 +25,7 @@ Loading a Standard Sequence from a Library This use case describes how to load, edit and store a control sequence from a library. For illustration, we use here -a sequence from the `Guideline 36 library `_. +a sequence from the `Guideline 36 library `_. .. table:: :class: longtable diff --git a/specification/source/verification.rst b/specification/source/verification.rst index 834582d3..6d59b26c 100644 --- a/specification/source/verification.rst +++ b/specification/source/verification.rst @@ -349,7 +349,7 @@ We configured the CDL PID controller parameters such that they correspond to the ALC PI controller. The ALC PID controller implementation is described in the ALC EIKON software help section, while the CDL PID controller is described in the info section of the model -`Buildings.Controls.OBC.CDL.Reals.LimPID `_. +`Buildings.Controls.OBC.CDL.Reals.PID `_. The ALC controller tracks the temperature in degree Fahrenheit, while CDL uses SI units. An additional implementation difference is that for cooling applications, the ALC @@ -515,7 +515,7 @@ iii. Optionally, a boolean variable in the model that we call an indicator varia must not be tested at that time instant. For example, consider the validation test -`OBC.ASHRAE.G36.AHUs.SingleZone.VAV.SetPoints.Validation.Supply_u `_. +`OBC.ASHRAE.G36.AHUs.SingleZone.VAV.SetPoints.Validation.Supply_u `_. and suppose we want to verify the sequences of its instances ``setPoiVAV`` and ``setPoiVAV1``. To do so, we first write a specification as shown in :numref:`sec_ver_spe_tes_set`.