diff --git a/.gitignore b/.gitignore index b2d6de3..2b7f59d 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ .env.development.local .env.test.local .env.production.local +.vscode npm-debug.log* yarn-debug.log* diff --git a/docs/guide.mdx b/docs/guide.md similarity index 51% rename from docs/guide.mdx rename to docs/guide.md index b8ec35d..50ef205 100644 --- a/docs/guide.mdx +++ b/docs/guide.md @@ -6,9 +6,9 @@ sidebar_position: 1 ## Interface Class -### What Shall Be Declared? +***What shall be declared?*** -#### All outside connectors needed by any derived class +### Outside Connectors Needed by Any Derived Class :::danger Important @@ -27,47 +27,41 @@ This ensures the [plug-compatibility](https://specification.modelica.org/maint/3 Type compatibility: -> Each reference is checked, whether it is a valid reference, e.g. the referenced object belongs to or is an instance, where all *existing conditional declaration expressions evaluate to true|false* or it is a constant in a package. +> Each reference is checked, whether it is a valid reference, e.g. the referenced object belongs to or is an instance, where all *existing conditional declaration expressions evaluate to true|false*, or it is a constant in a package. So checking that the redeclared component is a subtype of the constraining class is done with all the conditional connectors considered present (even if the redeclared component removes them). *How does it differ from interface classes in MBL?* -Interface classes are usually implemented with the minimum set of connectors (and other variables) and derived classes extend that set (which ensures type compatibility). -See for instance `Buildings.Fluid.Boilers.BaseClasses.PartialBoiler`: +Interface classes are usually implemented with the minimum set of connectors (and other variables) and derived classes extend that set, which ensures *type* compatibility. +See for instance: -```mo -// Buildings.Fluid.Boilers.BaseClasses.PartialBoiler - extends Interfaces.TwoPortHeatMassExchanger(...); // Interface class used by the model - - Modelica.Blocks.Interfaces.RealInput y(...) // Additional connector not declared in the interface class - "Part load ratio"; - Modelica.Blocks.Interfaces.RealOutput T(...) // Additional connector not declared in the interface class - "Temperature of the fluid"; - Modelica.Thermal.HeatTransfer.Interfaces.HeatPort_a heatPort // Additional connector not declared in the interface class - "Heat port, can be used to connect to ambient"; +```mo title="Buildings/Fluid/Boilers/BaseClasses/PartialBoiler.mo" +extends Interfaces.TwoPortHeatMassExchanger(...); // Interface class used by the model + +Modelica.Blocks.Interfaces.RealInput y(...) // Additional connector not declared in the interface class + "Part load ratio"; +Modelica.Blocks.Interfaces.RealOutput T(...) // Additional connector not declared in the interface class + "Temperature of the fluid"; +Modelica.Thermal.HeatTransfer.Interfaces.HeatPort_a heatPort // Additional connector not declared in the interface class + "Heat port, can be used to connect to ambient"; ``` -#### Configuration parameters and system tags - -To be updated. - -#### Both the [parameter record](#parameter-record) *and* locally accessible design parameters +### Both the [Parameter Record](#parameter-record) and Locally Accessible Design Parameters The parameter record is for propagation across the instance tree. The local design parameter declarations ensure that we have a standard set of parameters available in each template or component, whatever the configuration. For instance an evaporator coil still has `mChiWat_flow_nominal` defined with a final assignment to `0`. -Most of the local design parameters will have final assignments to the parameters from the record. + +Most of the local design parameters have `final` assignments to the parameters from the record.
Example -```mo -// Interface class Buildings.Templates.AirHandlersFans.Interfaces.PartialAirHandler - +```mo title="Buildings/Templates/AirHandlersFans/Interfaces/PartialAirHandler.mo" final parameter Modelica.Units.SI.MassFlowRate mAirSup_flow_nominal= dat.mAirSup_flow_nominal "Supply air mass flow rate" @@ -103,18 +97,43 @@ extends Buildings.Templates.AirHandlersFans.Interfaces.PartialAirHandler(
+ +### Configuration Parameters + +All configuration parameters are declared in the interface class, see the [admonition below](#admonConfigParam) for the proposed structure. + + +### Nested Expandable Connectors + +The interface class of the [main controller](#main-controller) should have protected instances of all sub-buses, connected to the corresponding variables from the main control bus as follows. + +```mo title="Buildings/Templates/ChilledWaterPlants/Components/Interfaces/PartialController.mo from issue1374_template_CHW_final" + Buildings.Templates.ChilledWaterPlants.Interfaces.Bus bus + "Plant control bus"; +protected + Buildings.Templates.Components.Interfaces.Bus busValChiWatChiIso[nChi] + if typValChiWatChiIso<>Buildings.Templates.Components.Types.Valve.None + "Chiller CHW isolation valve control bus"; +equation + connect(busValChiWatChiIso, bus.valChiWatChiIso) +``` + +This is particularly important in the case of array sub-buses. We avoid pre-declaring these sub-buses in the main bus definition because this would require including structural parameters for the array size inside the bus, and thus binding these parameters for each bus instance. Instead, we use instances of sub-buses *in the interface class of the controller* and the connect statement `connect(bus, bus.)` provides a hint to Modelica compilers to assign the correct dimensions to `bus.` (which is not predeclared in the bus definition). + + ## Replaceable Component No `choicesAllMatching` annotation is currently allowed in the `Templates` package (to maximize support across various Modelica tools). Expand into an explicit `choices` annotation with proper description strings and the following rules. -- Use `redeclare replaceable` to allow - - further redeclaration by the user, - - visiting the parameter dialog box of the redeclared component (this is Dymola's behavior, although if the redeclared component contains replaceable components that behavior is enabled automatically). + +Systematically use `redeclare replaceable` in the `choices` annotation to allow +- further redeclaration by the user, +- visiting the parameter dialog box of the redeclared component (this is Dymola's behavior, although this behavior is automatically enabled if the redeclared component contains replaceable components). ## Section -A so-called section is needed anytime there is a hard constraint on the allowable choices for two replaceable components that are at the same level of composition. +A so-called section is needed whenever there is a hard constraint on the allowed choices for two replaceable components that are on the same composition level.
@@ -124,11 +143,10 @@ In the case of a multiple-zone VAV with an air economizer, a return fan should r
The interface class for a section should use the same class for the control bus as the one used by the system template. -This differs from the basic components which have a dedicated class for the control bus `Buildings.Templates.Components.Interfaces.Bus`. -The motivation is to avoid nesting expandable connectors and to enable traversing seamlessly the composition levels when connecting signal variables. +This is different from the base components, which have their own class for the control bus, that is `Buildings.Templates.Components.Interfaces.Bus`. +The motivation is to avoid nesting expandable connectors and to allow seamless traversal of the composition levels when connecting signal variables, see for instance: -```mo -// Buildings.Templates.AirHandlersFans.VAVMultiZone +```mo title="Buildings/Templates/AirHandlersFans/VAVMultiZone.mo" connect(secOutRel.bus, bus); // secOutRel is a section connect(ctl.bus, bus); // ctl is a controller @@ -139,28 +157,74 @@ connect(damRet.bus, bus.damRet); // connection to the damper bus inside t connect(ctl.yRetDamPos, bus.damRet.y); // accessing the damper control variable inside the controller ``` -## Controller Integration +## Main Controller + +### Control Section -To be updated. +We instantiate all control blocks that form the control sequence of a system into one single class that is similar to a [section](#section), see for instance [`Buildings.Templates.AirHandlersFans.Components.Controls.G36VAVMultiZone`](https://github.com/lbl-srg/modelica-buildings/blob/14449dcb92a641b48b056cedcf58f446be2249b9/Buildings/Templates/AirHandlersFans/Components/Controls/G36VAVMultiZone.mo). -- Specify hysteresis and timer use in CDL blocks -- Specify how equipment status should be computed, and the resulting constraints on CDL implementation of SOO (use of `pre`) +Particularly this control section uses the same class for the control bus as the one used by the system template. +As opposed to the CDL implementation of the SOO, we only declare design and operating parameters strictly required by the SOO and propagated by means of the [parameter record](#parameter-record)—final bindings of the local parameters with the parameters from the record are used, see Section [Interface Class](#interface-class). -### Control Section -We instantiate all control blocks that form the control sequence of a system into one single class that is similar to a [section](#section), see for instance [`Buildings.Templates.AirHandlersFans.Components.Controls.G36VAVMultiZone`](https://github.com/lbl-srg/modelica-buildings/blob/8b0d03018b18928fc9a08367e4d330e3eb711941/Buildings/Templates/AirHandlersFans/Components/Controls/G36VAVMultiZone.mo). +### Control Point Connections -Particularly this control section uses the same class for the control bus as the one used by the system template. +Connect statements between signal (control) variables do not have graphical annotations. +Instead, a dedicated section is used at the top of the `equation` section. -To be updated. +```mo title="Buildings/Templates/AirHandlersFans/VAVMultiZone.mo" +equation + /* Control point connection - start */ + // Inputs from AHU bus + connect(bus.pAirSup_rel, ctl.dpDuc); + connect(bus.TOut, ctl.TOut); + ... + // Inputs from terminal bus + connect(busTer.yReqZonPreRes, reqZonPreRes.u); + connect(busTer.yReqZonTemRes, reqZonTemRes.u); + ... + // Outputs to AHU bus + connect(ctl.yMinOutDam, bus.damOutMin.y); + connect(ctl.y1MinOutDam, bus.damOutMin.y1); + ... + // Outputs to terminal unit bus + connect(TAirSupSet.y, busTer.TAirSupSet); + connect(TAirSup.y, busTer.TAirSup); + ... + /* Control point connection - stop */ +``` -- What parameters shall be declared? +:::tip +Use the same name for the signal variable and for the component it originates from. +::: +Inside the control section, connections to variables within nested expandable connectors should be done by means of the [local instances of these sub-buses](#nested-expandable-connectors) to guarantee that Modelica compilers assign correct dimensions to these variables. +See the example in [Gautier (2023)](/more/references#Gautier23) Section 5. See also: -### Control Point Connections +```mo title="Buildings.Templates.ChilledWaterPlants.Components.Controls.G36.mo from issue1374_template_CHW_final" +equation + /* Control point connection - start */ + connect(busChi.y1ChiWatReq, ctl.uChiWatReq); // as opposed to connect(bus.chi.y1ChiWatReq, ctl.uChiWatReq) +``` -To be updated. +### Equipment Status + +Most of the component models (such as `Buildings.Templates.Components.Chillers.Compression`) computes the [status signal](/more/glossary/#status) using the `pre` operator applied to the [command signal](/more/glossary/#command). + +This is unless the equipment model that is wrapped inside the component (such as `Buildings.Fluid.Actuators.Dampers.Exponential`) already provides a status as an output (for instance `y_actual` for actuator and mover models) ***and*** `use_inputFilter=true`. +If `use_inputFilter=false` then `y_actual` is connected to the input signal `y`, which likely yields an algebraic loop if the control logic uses the equipment status. + +:::caution Open Issue + +Switching to using `pre(y)` instead of `y_actual` if `use_inputFilter=false` is being implemented through [#3499](https://github.com/lbl-srg/modelica-buildings/issues/3499). + +::: + +This convention implies the following requirement for the SOO implementation. + +> The `pre` operator should not be applied to the command signal when comparing it with the feedback signal.
+> See the issue reported at https://github.com/lbl-srg/modelica-buildings/pull/2299#issuecomment-1446417462. ## Parameter Record @@ -173,84 +237,96 @@ All design and operating parameters are declared within a Modelica record class. ### Implementation Rules -###### Use only one nesting level +#### Use Only One Nesting Level If needed, component records must extend (not instantiate) subcomponent records. For instance in `Buildings.Templates.Components.Coils.Interfaces.Data`: -- the class cannot extend `Buildings.Templates.Components.Valves.Interfaces.Data` because of the colliding declarations of `typ`, +- the class cannot extend `Buildings.Templates.Components.Valves.Interfaces.Data` because of the colliding declarations of `typ`, - so `dpValve_nominal` is declared locally and a protected record with the type `Buildings.Templates.Components.Valves.Interfaces.Data` is constructed to pass in parameters to the valve component. -###### Configuration parameters must be set through the component model, not through the record +#### Configuration Parameters Must Be Set Through the Component Model, Not Through the Record -- Structural parameters are assigned ***from*** the component model ***to*** the record, and propagated ***up*** the instance tree. +Parameter propagation is implemented as follows. + +- Structural (configuration) parameters are assigned ***from*** the component model ***to*** the record, and propagated ***up*** the instance tree. - Design and operating parameters are assigned ***from*** the record ***to*** the component model, and propagated ***down*** the instance tree. The record for the [controller section](#control-section) needs to be instantiated (not extended) in the master record because it requires many structural parameters (such as `typFanSup`) that have duplicates in the master record. +At the component level, we instantiate the component record and bind (`final`) local parameters to the record elements. + +
+ +This implementation is similar to the one from `Buildings.Fluid.Chillers.ElectricEIR`. + +However, other classes such as `Buildings.Fluid.Actuators.BaseClasses.PartialTwoWayValve` extend the parameter class `Buildings.Fluid.Actuators.BaseClasses.ValveParameters` to integrate the parameter definitions in a flat structure. + +
-At the component level, we instantiate the component record and bind (`final`) local parameters to the record elements, as in `Buildings.Fluid.Chillers.ElectricEIR` (as opposed to extending the record to integrate the parameter definitions as `Buildings.Fluid.Actuators.BaseClasses.ValveParameters`). This allows simpler propagation (only the record is passed in) which is agnostic from the parameter structure of the constraining class (for instance `mWat_flow_nominal` is not defined in `Buildings.Templates.Components.Coils.Interfaces.PartialCoil`). -###### Do not use final bindings for configuration parameters + + +:::caution Subrecord with Configuration Parameters -Use `annotation(Dialog(enable=false))` instead. +Currently, all configuration parameters are included in the master record with a flat structure. This makes binding or propagating these parameters impractical, as shown below. -This is a temporary workaround for what seems to be a bug in Dymola (SRF00860858) and to allow propagating from a top-level (whole building) record as in `Buildings.Templates.AirHandlersFans.Validation.VAVMZNoEconomizer`. +```mo title="Buildings/Templates/AirHandlersFans/Validation/UserProject/Data/AllSystems.mo" +parameter Buildings.Templates.AirHandlersFans.Data.VAVMultiZone dat_VAV_1( + final typ=VAV_1.typ, + final typFanSup=VAV_1.typFanSup, + final typFanRet=VAV_1.typFanRet, + final typFanRel=VAV_1.typFanRel, + ... + final typCtl=VAV_1.ctl.typ, + final typSecOut=VAV_1.ctl.typSecOut, + final buiPreCon=VAV_1.ctl.buiPreCon, + final stdVen=VAV_1.ctl.stdVen, ... +``` +Through issue [#3500](https://github.com/lbl-srg/modelica-buildings/issues/3500) a subrecord `cfg` will be introduced and include all configuration parameters. +This subrecord can be considered as the "signature" for a given system configuration, accessible from any component and any template. -
+Ongoing template developments should adopt the same construct with a subrecord `cfg` for configuration parameters. +::: -About outer references +#### Do Not Use Final Bindings for Configuration Parameters -Top-level models with outer references should be supported but the valid `outer replaceable` component declaration clause differs between OCT and Dymola, see [`issue1374_templates_record_outer`](https://github.com/AntoineGautier/modelica-buildings/blob/issue1374_templates_record_outer/Buildings/Templates/AirHandlersFans/Validation/UserProject/DataTopLevelDymola.mo). +This is because some Modelica tools (Dymola sometimes see SRF00860858, OCT never) trigger a "final overriding" error when a record instance contains final bindings and the record itself is propagated from a higher composition level. -At the AHU template level, switching to outer references (and using a model instead of a record—as [elements of a record shall not have `inner` nor `outer` prefixes](https://specification.modelica.org/maint/3.5/class-predefined-types-and-declarations.html#specialized-classes)) would avoid painful propagation of configuration parameters `typ*`. However, this will not support propagation from a top level (whole building) record then. -
+Use `annotation(Dialog(enable=false))` instead when declaring the parameters (configuration parameters are for development use only and should not be exposed to the user). ### Exposed Parameters -To be updated. - -### Feature Enhancement - -Implement a subrecord with configuration (structural) parameters—intantiated as `cfg`. - -That subrecord must be declared in the master record `dat` ***and*** in the components so that - -- structural parameters be propagated *up* with `dat(cfg=component.cfg)` instead of - ```mo - UserProject.Data.AllSystems dat(VAV_1( - final typ=VAV_1.typ, - final typFanSup=VAV_1.typFanSup, - final typFanRet=VAV_1.typFanRet, - final typFanRel=VAV_1.typFanRel, - final have_souChiWat=VAV_1.have_souChiWat, - final have_souHeaWat=VAV_1.have_souHeaWat, - final typCoiHeaPre=VAV_1.coiHeaPre.typ, - final typCoiCoo=VAV_1.coiCoo.typ, - final typCoiHeaReh=VAV_1.coiHeaReh.typ, - final typValCoiHeaPre=VAV_1.coiHeaPre.typVal, - final typValCoiCoo=VAV_1.coiCoo.typVal, - final typValCoiHeaReh=VAV_1.coiHeaReh.typVal, - final typDamOut=VAV_1.secOutRel.typDamOut, - final typDamOutMin=VAV_1.secOutRel.typDamOutMin, - final typDamRet=VAV_1.secOutRel.typDamRet, - final typDamRel=VAV_1.secOutRel.typDamRel, - final typCtl=VAV_1.ctl.typ, - final typSecRel=VAV_1.secOutRel.typSecRel, - final typSecOut=VAV_1.ctl.typSecOut, - final buiPreCon=VAV_1.ctl.buiPreCon, - ctl( - stdEne=VAV_1.ctl.stdEne, - stdVen=VAV_1.ctl.stdVen, - have_CO2Sen=VAV_1.ctl.have_CO2Sen))) - ``` -- design parameters be propagated *down* with `component(dat=dat)`, -- without any circular dependency. +#### Design and Operating Parameters + +In addition to the configuration parameters, the record contains all design and operating parameters required + +1. by the sequence of operation for all possible system configurations, see [ASHRAE (2021)](/more/references#Ashrae21) Section 3, +2. for sizing equipment models (most of these parameters are already included in 1.). + +Modeling and advanced parameters ***shall not be included*** in this record. +The record should be viewed as a digital avatar of the manufacturer’s data sheet for a given system, and as such, should only contain equipment and control parameters that HVAC designers are familiar with. +#### System Tags + +System tags are optional parameters that are not used for simulation but nevertheless included in the parameter record of each template to support future workflow automation (e.g., parameterization of a template by means of an external [equipment schedule](https://docs.google.com/document/d/16Z8HqTi3vNV3HUaa4ijBPVSQvA4MyGTu8bxoGTBD2YI/edit?usp=sharing)). + +```mo title="Buildings/Templates/AirHandlersFans/Data/PartialAirHandler.mo" + parameter String id="" + "System tag" + annotation (Dialog(tab="Advanced")); + parameter String id_souChiWat="" + "CHW supply system tag" + annotation (Dialog(tab="Advanced", enable=have_souChiWat)); + parameter String id_souHeaWat="" + "HHW supply system tag" + annotation (Dialog(tab="Advanced", enable=have_souHeaWat)); +``` + ## System Schematics Refer to the [specification for the generation of engineering schematics](https://lbl-srg.github.io/ctrl-flow/requirements.html#engineering-schematic) if needed. @@ -274,26 +350,26 @@ Those raw icons must be processed as described below for Inkscape `>=1.1` before The requirements below stem from the following observations. - The [Modelica Language Specification](https://specification.modelica.org/maint/3.5/annotations.html#common-definitions) specifies `type DrawingUnit = Real(final unit="mm")`. -- The default icon layer size in Dymola is *200x200* mm (`{{-100,-100},{100,100}}`). This corresponds to *10x10* cells in the icon view. So one cell corresponds to *20x20* mm. -- When instantiated, a component has its icon scaled by a factor *1/10* in the diagram layer. For instance, a `Line` object with `thickness=5` in the icon layer is rendered as a `Line` object with `thickness=0.5` in the diagram layer. -- When `thickness < 0.25`, the stroke width remains unchanged in Dymola: so *0.2* and *0.1* yield the same stroke width. -- It seems that Dymola handles Bitmap objects as squares, i.e., the objects are scaled by the minimum of the x and y dimensions. Having external SVG files with equal height and width makes it easier to position and scale the graphical objects. +- The default icon layer size in Dymola is $200 \times 200$ mm (`{{-100,-100},{100,100}}`). This corresponds to $10 \times 10$ cells in the icon view. So one cell corresponds to $20 \times 20$ mm. +- When instantiated, a component has its icon scaled by a factor $1/10$ in the diagram layer. For instance, a `Line` object with `thickness=5` in the icon layer is rendered as a `Line` object with `thickness=0.5` in the diagram layer. +- When `thickness < 0.25`, the stroke width remains unchanged in Dymola: so $0.2$ and $0.1$ yield the same stroke width. +- It seems that Dymola handles Bitmap objects as squares, i.e., the objects are scaled by the minimum of the `x` and `y` dimensions. Having external SVG files with equal height and width makes it easier to position and scale the graphical objects. - Select object, copy to new file. -- Change stroke color to black and stroke width to *1* mm. -- Account for *20* mm for each grid cell in Dymola icon layer. - - So the default icon layer size of *10x10* cells in Dymola corresponds to a page size of *200x200* mm in Inkscape. -- For most of the AHU components, lock width/height ratio and change height to *200* mm. - - For transducers, *200* mm is for the probe, *80* mm is for the sensor casing. +- Change stroke color to black and stroke width to $1$ mm. +- Account for $20$ mm for each grid cell in Dymola icon layer. + - So the default icon layer size of $10 \times 10$ cells in Dymola corresponds to a page size of $200 \times 200$ mm in Inkscape. +- For most of the AHU components, lock width/height ratio and change height to $200$ mm. + - For transducers, $200$ mm is for the probe, $80$ mm is for the sensor casing. - For polygons, the different segments will typically not be connected together (gap at each corner), so select each segment with `Node` tool and use `Node` functionalities to - `Convert selected objects to path` - `Join selected nodes` - For the last corner use `Path/Union` -- Text should be in sans-serif with font size of *120*. +- Text should be in sans-serif with font size of $120$. - If needed (typically in case of specific text orientation), select text object and transform to path with `Path/Object to Path`. -- Specify the page size with equal height and width (typically *200x200* mm) and center icons in the page. +- Set the page size with the same height and width (typically $200 \times 200$ mm) and center icons in the page. - Save as Inkscape SVG. @@ -303,11 +379,11 @@ In addition to external SVG files, the schematics may use Modelica graphical pri | Equipment | Primitive | Icon layer | Diagram layer | | ----------------------------------------------------------------- | -------------------- | ---------------------------------- | --------------------------------- | - | Supply pipe (*) | Line, solid | Thickness 0.5 | Thickness 5 | - | Return pipe (*) | Line, dashed | Thickness 0.5 | Thickness 5 | - | Duct wall | Line, solid | Default thickness (0.25) | Default thickness (0.25) | - | Capillary tube (pressure sensor) | Polygon or rectangle | Default thickness (0.25), width 10 | Default thickness (0.25), width 1 | - | Motor shaft (actuator), connection between sensor and transmitter | Line, solid | Default thickness (0.25) | Default thickness (0.25) | + | Supply pipe (*) | Line, solid | Thickness $0.5$ | Thickness $5$ | + | Return pipe (*) | Line, dashed | Thickness $0.5$ | Thickness $5$ | + | Duct wall | Line, solid | Default thickness ($0.25$) | Default thickness ($0.25$) | + | Capillary tube (pressure sensor) | Polygon or rectangle | Default thickness ($0.25$), width $10$ | Default thickness ($0.25$), width $1$ | + | Motor shaft (actuator), connection between sensor and transmitter | Line, solid | Default thickness ($0.25$) | Default thickness ($0.25$) | *(\*) This should be specified as a graphical annotation to the corresponding connect statement.* @@ -330,7 +406,7 @@ All vendor annotations are hierarchical annotations in the form of `"__ctrlFlow" :::danger FIXME -This is weird to use a hierarchical annotation here because `__ctrlFlow(template=false)` will never be used. Prefer `__ctrlFlow_template` which is also easier to test for? +It is uncanny to use a hierarchical annotation here because `__ctrlFlow(template=false)` will never be used. Prefer `__ctrlFlow_template` which is also easier to test for? ::: Ctrl-flow greps for this annotation and returns a list of files which are then treated as entry points to build the tree of system types. Both packages (corresponding to system types such as `Buildings.Templates.AirHandlersFans`) and template classes (such as `Buildings.Templates.AirHandlersFans.VAVMultiZone`) shall contain this annotation. @@ -341,8 +417,8 @@ So the file arborescence: Buildings/Templates ├── AirHandlersFans │   ├── ... -│   ├── package.mo # Contains __ctrlFlow_template=true|false -│   └── VAVMultiZone.mo # Contains __ctrlFlow_template=true|false +│   ├── package.mo # Contains __ctrlFlow_template annotation +│   └── VAVMultiZone.mo # Contains __ctrlFlow_template annotation ├── Components │   └── ... ├── Data @@ -355,9 +431,9 @@ Buildings/Templates ├── UsersGuide.mo └── ZoneEquipment ├── ... - ├── package.mo # Contains __ctrlFlow_template=true|false - ├── VAVBoxCoolingOnly.mo # Contains __ctrlFlow_template=true|false - └── VAVBoxReheat.mo # Contains __ctrlFlow_template=true|false + ├── package.mo # Contains __ctrlFlow_template annotation + ├── VAVBoxCoolingOnly.mo # Contains __ctrlFlow_template annotation + └── VAVBoxReheat.mo # Contains __ctrlFlow_template annotation ``` yields the following UI objects: @@ -367,14 +443,14 @@ yields the following UI objects: :::caution Currently patched -Currently (as of MBL commit `88b6ccdd08`) this annotation is not included in the Modelica classes but rather patched when preprocessing the Templates package to serve ctrl-flow app. +Currently, (as of MBL commit `88b6ccdd08`) this annotation is not included in the Modelica classes but rather patched when preprocessing the Templates package to serve ctrl-flow app. The necessary refactoring is tracked at [#357](https://github.com/lbl-srg/ctrl-flow-dev/issues/357). :::
-Alternative approach discussed with DEPT but not implemented. +Alternative Approach Discussed With DEPT but Not Implemented > We should rather use a flag indicating that a package (in our case `Buildings.Templates`) is to be considered as the "root" for all template URIs, for instance: `__ctrlFlow(routing="root")`. And for each template class (for instance `Buildings.Templates.AirHandlersFans.VAVMultiZone`): `__ctrlFlow(routing="template")`. The contract for the template developer will then be that the class URI dictates the explorer tree structure, starting from the "root" package (necessarily unique inside a library). So for instance the template `Buildings.Templates.AirHandlersFans.VAVMultiZone` with the above annotation would yield the following tree structure. > ```sh @@ -390,12 +466,15 @@ Alternative approach discussed with DEPT but not implemented. #### `__ctrlFlow(enable=true|false)` -Each declaration or extends statement may have a hierarchical vendor-specific annotation `"__Linkage" "(" "enable" "=" logical-expression ")"` that allows disabling input fields in ctrl-flow configuration dialog. This is similar to Modelica annotation `Dialog(enable=true|false)` but provides additional flexibility and allows disabling all parameter input fields that are brought in by an extends statement. It takes precedence on the standard annotation `Dialog(enable)`. +Each declaration or `extends` statement may have a hierarchical annotation `"__ctrlFlow" "(" "enable" "=" logical-expression ")"` that allows disabling input fields in ctrl-flow configuration dialog. This is similar to Modelica annotation `Dialog(enable=true|false)` but provides additional flexibility and allows disabling all parameter input fields that are brought in by an `extends` statement. + +It takes precedence on the standard annotation `Dialog(enable)`. + Typical use cases include classes from the Modelica Buildings Library that contain definitions of detailed simulation parameters and that are extended to define template components, or package classes used to specify the fluid properties.
-Boolean litteral or expression? +Boolean Literal or Expression? Although only Boolean literals are used in the templates as of commit 675801b669, the expression evaluation engine is invoked when parsing `__ctrlFlow(enable...)`, see https://github.com/lbl-srg/ctrl-flow-dev/blob/main/server/src/parser/parser.ts#L296-L317. So in practice, Boolean expressions could be used. @@ -405,19 +484,19 @@ Although only Boolean literals are used in the templates as of commit 675801b669 ### Git Workflow -The main feature branch for template development is [`issue1374_templates`](https://github.com/lbl-srg/modelica-buildings/tree/issue1374_templates) that currently depends on—and is periodically kept in sync with +Each new development should start by branching out from the master branch of MBL. -- MBL `master` -- MBL [`issue1913_g36_final`](https://github.com/lbl-srg/modelica-buildings/tree/issue1913_g36_final) - -Each new development should -- start by branching out from the main feature branch—so the new branch is a dependent of the main feature branch, -- be kept in sync with MBL master ***by merging the main feature branch***, as opposed to merging MBL master directly. +The current development branches are +- `issue1374_template_CHW_final` +- `issue3266_template_HW_plant` ### Code Tags -Use the code tags from [PEP 350](https://peps.python.org/pep-0350/#mnemonics) to reference issues and feature enhancements directly in the Modelica code base. All tags should include one of the tag names below in all caps, followed by the name, e-mail address, or other identifier of the person with the best context about the problem, and the GH issue number if available. +Mainly because of the dependencies on the CDL implementation of SOO, the development of templates usually requires iterations with the author of the CDL components and drags on for a long time. Code tags have proven useful in this context. + +We adopt the code tags from [PEP 350](https://peps.python.org/pep-0350/#mnemonics) to reference issues and feature enhancements directly in the Modelica code base. +All tags should include one of the tag names below in all caps, followed by the name, e-mail address, or other identifier of the person with the best context about the problem, and the GH issue number if available. We keep it simple and only use: - `BUG` for what prevents from translating or simulating a model: ***should prevent merging*** diff --git a/docs/more/glossary.md b/docs/more/glossary.md index ef522ef..b191167 100644 --- a/docs/more/glossary.md +++ b/docs/more/glossary.md @@ -4,17 +4,39 @@ sidebar_position: 1 # Glossary +## Templating + +### System + +See [below](#component-system). + +### Configuration + +A system configuration corresponds to the specification of the type and layout of the equipment and the corresponding control logic. Systems with different capacities may have the same configuration, provided they have the same control software and hardware type. + +### Parameterization + +By parameterization we mean all possible class modifications, such as changing parameter values and redeclaring components or classes, which we refer to as class parameterization. + +### Structural and value parameters + +We use the term structural parameters if a parameter affects the number and structure of the equations, and value parameters if they do not. An example of a structural parameter is a parameter used to specify an array size. + +### Template + +A template, or template class, is defined as a Modelica model that can be parameterized (as defined above) to represent a particular system configuration. + + +## HVAC Systems + ### Source, Load We adopt the definitions from [ASHRAE (2021)](./references#Ashrae21) Section 5.1.19.1. -> A component is a “source” if it provides resources to a downstream component, such as a chiller providing chilled water (CHW) to an AHU. -> -> A component is a “load” if it receives resources from an upstream component, such as an AHU that receives CHW from a chiller. -> +> A component is a “source” if it provides resources to a downstream component, such as a chiller providing chilled water (CHW) to an AHU.
+> A component is a “load” if it receives resources from an upstream component, such as an AHU that receives CHW from a chiller.
> The same component may be both a load (receiving resources from an upstream source) and a source (providing resources to a downstream load). - ### Component, System We adopt the definitions from [ASHRAE (2021)](./references#Ashrae21) Section 5.1.19.1. diff --git a/docs/more/nomenclature.md b/docs/more/nomenclature.md index c5edf92..a82fe36 100644 --- a/docs/more/nomenclature.md +++ b/docs/more/nomenclature.md @@ -4,7 +4,14 @@ sidebar_position: 2 # Nomenclature -This provides conventions mainly for variable naming, marginally for component naming. +This section provides conventions mainly for variable naming, marginally for component naming. + + +## Example of Control Point Naming + +By way of introduction, here is an example of how the following rules translate into practical nomenclature for the CHW plant template. + + ## Control Points @@ -68,7 +75,7 @@ In the CamelCase instance name: Similarly (exhaustive list): - - `TOut` (air implied) + - `TOut` or `phiOut` (air implied) - `TZon` (air implied) - `pBui_rel` (air implied) @@ -80,7 +87,7 @@ All CamelCase morphemes should be used before the first underscore—such as :::danger NO -Three-letter capital abbreviations are only allowed—and encouraged—in documentation and description strings. +3-letter capital abbreviations are only allowed—and encouraged—in documentation and description strings. ::: @@ -112,6 +119,7 @@ Tolerated exceptions:
`min` and `max` are attributes of primitive types in Modelica, same as `nominal`, and should have the same notation, not Min and Max in CamelCase. +
- For design conditions use `_nominal` not `Des` @@ -157,11 +165,11 @@ For instance a sensor for supply air temperature should be named `TAirSup` inste ### Various -`Set` for a set point, always as the last morpheme. So `TZonHeaOccSet` not `TZonHeaSetOcc`. +`Set` for a set point, always as the last morpheme: so `TZonHeaOccSet` not `TZonHeaSetOcc`. -The letter `n` is used to represent a number of something (as opposed to num). +The letter `n` is used to represent a number of something (as opposed to `num`). -The letter `y` is used to represent a fractional quantity (speed, opening, load) taking 1 as maximum value, for instance `yLoa` for PLR. +The letter `y` is used to represent a fractional quantity (speed, opening, load) taking $1$ as maximum value, for instance `yLoa` for PLR. :::tip @@ -170,6 +178,7 @@ The letter `y` is used to represent a fractional quantity (speed, opening, load - Prefer `cfg` to `con` for a configuration. - Prefer `lck` to `loc` for lock-out as the latter is too loose: local, etc. + ::: diff --git a/docs/more/references.md b/docs/more/references.md index 20a8aa2..4185fe1 100644 --- a/docs/more/references.md +++ b/docs/more/references.md @@ -10,9 +10,9 @@ sidebar_position: 3 ASHRAE (2021). Guideline 36 – High-performance sequences of operation for HVAC systems. ASHRAE. - +Gautier, A., Wetter, M., Hu, J., & Tummescheit, H. (In press). HVAC and control templates for the Modelica Buildings library. *Proceedings of the 15th International Modelica Conference*. diff --git a/docusaurus.config.js b/docusaurus.config.js index d0e4041..1d030da 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -28,6 +28,9 @@ const config = { tagline: 'Modelica Template Development Guide', favicon: 'img/favicon.ico', + onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'throw', + // Set the production url of your site here url: 'https://antoinegautier.github.io', // Set the // pathname under which your site is served @@ -64,6 +67,8 @@ const config = { sidebarPath: require.resolve('./sidebars.js'), remarkPlugins: [math], rehypePlugins: [katex], + showLastUpdateAuthor: true, + showLastUpdateTime: true, }, theme: { customCss: require.resolve('./src/css/custom.css'), diff --git a/src/components/HomepageFeatures/index.js b/src/components/HomepageFeatures/index.js index 332ed28..5d7f5ee 100644 --- a/src/components/HomepageFeatures/index.js +++ b/src/components/HomepageFeatures/index.js @@ -15,7 +15,7 @@ const FeatureList = [ title: 'Version', description: ( <> - 0.x (draft) + 1.0 (first release) ), } diff --git a/src/pages/index.js b/src/pages/index.js index 4c6b6ee..0fcbe08 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -2,6 +2,7 @@ import React from 'react'; import clsx from 'clsx'; import Link from '@docusaurus/Link'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import Heading from '@theme/Heading'; import Layout from '@theme/Layout'; import HomepageFeatures from '@site/src/components/HomepageFeatures'; @@ -18,7 +19,7 @@ function HomepageHeader() { - Go to guide + Get Started @@ -30,7 +31,7 @@ export default function Home() { const {siteConfig} = useDocusaurusContext(); return (