From 809ec149fb488cbba004bd04c21ad98eff2b57bc Mon Sep 17 00:00:00 2001 From: Michael Wetter Date: Tue, 5 Sep 2023 07:52:04 -0700 Subject: [PATCH] Updated users guide --- .../build/html/_sources/bestPractice.rst.txt | 42 +++++++++---------- .../build/html/_sources/development.rst.txt | 34 +++++++-------- .../html/_sources/gettingStarted.rst.txt | 4 +- .../build/html/_sources/performance.rst.txt | 16 +++---- .../userGuide/build/html/bestPractice.html | 42 +++++++++---------- .../userGuide/build/html/development.html | 34 +++++++-------- .../userGuide/build/html/gettingStarted.html | 4 +- .../userGuide/build/html/performance.html | 16 +++---- .../userGuide/source/bestPractice.rst | 42 +++++++++---------- .../userGuide/source/development.rst | 34 +++++++-------- .../userGuide/source/gettingStarted.rst | 4 +- .../userGuide/source/performance.rst | 16 +++---- 12 files changed, 144 insertions(+), 144 deletions(-) diff --git a/Buildings/Resources/Documentation/userGuide/build/html/_sources/bestPractice.rst.txt b/Buildings/Resources/Documentation/userGuide/build/html/_sources/bestPractice.rst.txt index 9f370d40591..111956cb89a 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/_sources/bestPractice.rst.txt +++ b/Buildings/Resources/Documentation/userGuide/build/html/_sources/bestPractice.rst.txt @@ -42,9 +42,9 @@ Building large system models When creating a large system model, it is typically easier to build the system model through the composition of subsystem models that can be tested in isolation. For example, the package -`Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples `_ +`Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples `_ contains small test models that are used to test individual components in the large system model -`Buildings.Examples.ChillerPlant `_. +`Buildings.Examples.ChillerPlant `_. Creating small test models typically saves time as the proper response of controls, and the proper operation of subsystems, can be tested in isolation of complex system-interactions that are often present in large models. @@ -270,9 +270,9 @@ a fluid port represents the physical phenomena that was intended to model. However, in more complex flow configurations, one may want to explicitly control what branches of a piping or duct network mix. This may be achieved by using an instance of the model -`Junction `_ +`Junction `_ as shown in the left figure below, which is derived from the test model -`BoilerPolynomialClosedLoop `_ +`BoilerPolynomialClosedLoop `_ .. _fig_flu_cor_wro: @@ -283,7 +283,7 @@ as shown in the left figure below, which is derived from the test model In :numref:`fig_flu_cor_wro` (a), the mixing points have been correctly defined by use of the model -`Junction `_. +`Junction `_. However, in :numref:`fig_flu_cor_wro` (b), all connections are made to the port of the instance ``spl2``. This results in the same configuration as is shown in :numref:`fig_flu_cor_wro` (c). This is certainly not the intention of the modeler, as this causes all flows to be mixed in the port. @@ -301,13 +301,13 @@ Use of sensors in fluid flow systems When selecting a sensor model, a distinction needs to be made whether the measured quantity depends on the direction of the flow or not. If the quantity depends on the flow direction, such as temperature or relative humidity, then sensors with two ports from the -`Buildings.Fluid.Sensors `_ +`Buildings.Fluid.Sensors `_ library should be used. These sensors have a more efficient implementation than sensors with one port for situations where the flow reverses its direction. The proper use sensors is described in the -`User's Guide `_ +`User's Guide `_ of the -`Buildings.Fluid.Sensors `_ +`Buildings.Fluid.Sensors `_ package. @@ -319,9 +319,9 @@ Reference pressure for incompressible fluids such as water This section explains how to set a reference pressure for fluids that model the flow as :term:`incompressible flow`, such as -`Buildings.Media.Water `_ +`Buildings.Media.Water `_ and -`Buildings.Media.Antifreeze.PropyleneGlycolWater `_. +`Buildings.Media.Antifreeze.PropyleneGlycolWater `_. Consider the flow circuit shown in :numref:`fig_flow_cir` that consists of a pump or fan, a flow resistance and a volume. @@ -354,7 +354,7 @@ In this situation, attempting to translate the model leads, in Dymola, to the fo The number of scalar Real equation elements are 58. Similarly, if the medium model -`Buildings.Media.Specialized.Water.TemperatureDependentDensity `_, +`Buildings.Media.Specialized.Water.TemperatureDependentDensity `_, which models density as a function of pressure and enthalpy, is used, then the model is well-defined, but the pressure increases the longer the pump runs. The reason is that the pump adds heat to the water. When the water temperature @@ -364,7 +364,7 @@ the pressure increases from :math:`1 \, \mathrm{bars}` to :math:`150 \, \mathrm{ To avoid this singularity or increase in pressure, use a model that imposes a pressure source and that accounts for the expansion of the fluid. For example, use -`Buildings.Fluid.Sources.Boundary_pT `_ +`Buildings.Fluid.Sources.Boundary_pT `_ to form the system model shown in :numref:`fig_flow_cir_wit_bou`. .. _fig_flow_cir_wit_bou: @@ -376,15 +376,15 @@ to form the system model shown in :numref:`fig_flow_cir_wit_bou`. provides a reference presssure. Alternatively, you may use -`Buildings.Fluid.Storage.ExpansionVessel `_, +`Buildings.Fluid.Storage.ExpansionVessel `_, but -`Buildings.Fluid.Sources.Boundary_pT `_ +`Buildings.Fluid.Sources.Boundary_pT `_ usually leads to simpler equations than -`Buildings.Fluid.Storage.ExpansionVessel `_. +`Buildings.Fluid.Storage.ExpansionVessel `_. Note that the medium that flows out of the fluid port of -`Buildings.Fluid.Sources.Boundary_pT `_ +`Buildings.Fluid.Sources.Boundary_pT `_ is at a fixed temperature, while the model -`Buildings.Fluid.Storage.ExpansionVessel `_ +`Buildings.Fluid.Storage.ExpansionVessel `_ conserves energy. However, since the thermal expansion of the fluid is usually small, this effect can be neglected in most building HVAC applications. @@ -393,10 +393,10 @@ this effect can be neglected in most building HVAC applications. In each water circuit, there must be exactly on instance of `Buildings.Fluid.Sources.Boundary_pT - `_, + `_, or instance of `Buildings.Fluid.Storage.ExpansionVessel - `_. + `_. If there is more than one such device, then there are multiple points in the system that set the reference static pressure. @@ -592,5 +592,5 @@ is produced. This shows the iteration variables and their start values. These start values can be overwritten in the model. -.. _PressureDrop: https://simulationresearch.lbl.gov/modelica/releases/v8.0.0/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop -.. _WetCoilDiscretized: https://simulationresearch.lbl.gov/modelica/releases/v8.0.0/help/Buildings_Fluid_HeatExchangers.html#Buildings.Fluid.HeatExchangers.WetCoilDiscretized +.. _PressureDrop: https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop +.. _WetCoilDiscretized: https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_HeatExchangers.html#Buildings.Fluid.HeatExchangers.WetCoilDiscretized diff --git a/Buildings/Resources/Documentation/userGuide/build/html/_sources/development.rst.txt b/Buildings/Resources/Documentation/userGuide/build/html/_sources/development.rst.txt index 3e5c7be5e58..703b5c3659c 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/_sources/development.rst.txt +++ b/Buildings/Resources/Documentation/userGuide/build/html/_sources/development.rst.txt @@ -24,13 +24,13 @@ Models, blocks and functions that are contributed need to adhere to the followin * They should be of general interest to other users and well documented and tested. * They need to follow the coding conventions described in - - the `Buildings library user guide `_ and + - the `Buildings library user guide `_ and - the `Style Guide` provided in subsections of :numref:`sec_sty_gui` - * They need to be made available under the `Modelica Buildings Library license `_. + * They need to be made available under the `Modelica Buildings Library license `_. * For models of thermofluid flow components, they need to be based on the base classes in - `Buildings.Fluid.Interfaces `_, - which are described in the `user guide `_ of this package. + `Buildings.Fluid.Interfaces `_, + which are described in the `user guide `_ of this package. Otherwise, it becomes difficult to ensure that the implementation is numerically robust. .. _sec_sty_gui: @@ -408,8 +408,8 @@ Adding a new class, such as a model or a function, is usually easiest by extendi In many cases, the similar component already exists. In this situation, it is recommended to copy and modify a similar component. If both components share a significant amount of similar code, then a base class should be introduced that implements the common code. -See for example `Buildings.Fluid.Sensors.BaseClasses.PartialAbsoluteSensor `_ which is shared by all sensors with one fluid port in the package -`Buildings.Fluid.Sensors `_. +See for example `Buildings.Fluid.Sensors.BaseClasses.PartialAbsoluteSensor `_ which is shared by all sensors with one fluid port in the package +`Buildings.Fluid.Sensors `_. The next sections give guidance that is specific to the implementation of thermofluid flow devices, pressure drop models and control sequences. @@ -417,20 +417,20 @@ Thermofluid flow device ~~~~~~~~~~~~~~~~~~~~~~~ To add a component of a thermofluid flow device, the package -`Buildings.Fluid.Interface `_ contains basic classes that can be extended. -See `Buildings.Fluid.Interface.UsersGuide `_ for a description of these classes. +`Buildings.Fluid.Interface `_ contains basic classes that can be extended. +See `Buildings.Fluid.Interface.UsersGuide `_ for a description of these classes. Alternatively, simple models such as the models below may be used as a starting point for implementing new models for thermofluid flow devices: -`Buildings.Fluid.HeatExchangers.HeaterCooler_u `_ +`Buildings.Fluid.HeatExchangers.HeaterCooler_u `_ For a device that adds heat to a fluid stream. -`Buildings.Fluid.Humidifiers.Humidifier_u `_ +`Buildings.Fluid.Humidifiers.Humidifier_u `_ For a device that adds humidity to a fluid stream. -`Buildings.Fluid.Chillers.Carnot_y `_ +`Buildings.Fluid.Chillers.Carnot_y `_ For a device that exchanges heat between two fluid streams. -`Buildings.Fluid.MassExchangers.ConstantEffectiveness `_ +`Buildings.Fluid.MassExchangers.ConstantEffectiveness `_ For a device that exchanges heat and humidity between two fluid streams. .. _fig_merkel: @@ -454,11 +454,11 @@ Pressure drop When implementing equations for pressure drop, it is recommended to expand the base class -`Buildings.Fluid.BaseClasses.PartialResistance `_. +`Buildings.Fluid.BaseClasses.PartialResistance `_. Models should allow computing the flow resistance as a quadratic function with regularization near zero as implemented in -`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_dp `_ and in -`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_m_flow `_. +`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_dp `_ and in +`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_m_flow `_. The governing equation is .. math:: @@ -514,7 +514,7 @@ The following rules need to be followed, in addition to the guidelines described #. The naming of parameters, inputs, outputs and instances must follow the naming conventions in - `Buildings.UsersGuide.Conventions `_. + `Buildings.UsersGuide.Conventions `_. Avoid providing duplicate information in the instance name, for example if the block is within the ``Boilers`` package, the instance name must not contain ``boi``. Ensure that the instance name is unambiguous when viewed in a top level controller block. @@ -671,7 +671,7 @@ The validation models are part of automated unit tests as described at the For simple models, the validation can be against analytic solutions. This is for example done in -`Buildings.Fluid.FixedResistances.PressureDrop `_ +`Buildings.Fluid.FixedResistances.PressureDrop `_ which uses a regression tests that checks the correct relation between mass flow rate and pressure drop. For complex thermofluid flow devices, a comparative model validation needs to be done, for example diff --git a/Buildings/Resources/Documentation/userGuide/build/html/_sources/gettingStarted.rst.txt b/Buildings/Resources/Documentation/userGuide/build/html/_sources/gettingStarted.rst.txt index 586a6a60e4d..55e1c46105b 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/_sources/gettingStarted.rst.txt +++ b/Buildings/Resources/Documentation/userGuide/build/html/_sources/gettingStarted.rst.txt @@ -40,7 +40,7 @@ or by replacing existing component models by new ones. The example models can be found in the packages `Examples`. Study the detailed tutorials with step-by-step instructions for how to build system models, -which can be found in the `Tutorial package `_. +which can be found in the `Tutorial package `_. Note that heat transfer models, which can be found in `Buildings.HeatTransfer.*.Examples` are easier to understand than fluid flow models because; @@ -51,7 +51,7 @@ are easier to understand than fluid flow models because; To get started with Spawn of EnergyPlus, we recommend to first familiarize yourself with Modelica, as described above. Next, read the -`user guide for the Spawn models `_ +`user guide for the Spawn models `_ which provides step-by-step instructions and points to various examples. diff --git a/Buildings/Resources/Documentation/userGuide/build/html/_sources/performance.rst.txt b/Buildings/Resources/Documentation/userGuide/build/html/_sources/performance.rst.txt index a079469114e..5ab89802d21 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/_sources/performance.rst.txt +++ b/Buildings/Resources/Documentation/userGuide/build/html/_sources/performance.rst.txt @@ -78,8 +78,8 @@ The default value is ``raiseTime=120`` seconds. closed loop control performance. For further information, see the -`User's Guide of the flow machine package `_, and the -`User's Guide of the actuator package `_. +`User's Guide of the flow machine package `_, and the +`User's Guide of the actuator package `_. Fluid flow systems @@ -92,9 +92,9 @@ In fluid flow systems, flow junctions where mass flow rates separate and mix can This leads to larger systems of coupled equations that need to be solved, which often causes larger computing time and can sometimes cause convergence problems. To decouple these systems of equations, in the model of a flow junction -(`Buildings.Fluid.FixedResistances.Junction `_), +(`Buildings.Fluid.FixedResistances.Junction `_), or in models for fans or pumps (such as the model -`Buildings.Fluid.Movers.SpeedControlled_y `_), +`Buildings.Fluid.Movers.SpeedControlled_y `_), the parameter ``dynamicBalance`` can be set to ``true``. This adds a control volume at the fluid junction that can decouple the system of equations. @@ -174,7 +174,7 @@ The valve model then computes the pressure drop using :math:`\bar k` and the sam Thus, the composite model has the same :term:`valve authority` and mass flow rate, but a nonlinear equation can be avoided. For more details, see the -`User's Guide of the actuator package `_. +`User's Guide of the actuator package `_. @@ -183,7 +183,7 @@ Prescribed mass flow rate For some system models, the mass flow rate can be prescribed by using an idealized pump or fan (model -`Buildings.Fluid.Movers.FlowControlled_m_flow `_) or a source element that outputs the required mass flow rate (such as the model `Buildings.Fluid.Sources.MassFlowSource_T `_). +`Buildings.Fluid.Movers.FlowControlled_m_flow `_) or a source element that outputs the required mass flow rate (such as the model `Buildings.Fluid.Sources.MassFlowSource_T `_). Using these models avoids having to compute the intersection of the fan curve and the flow resistance. In some situations, this can lead to faster and more robust simulation. @@ -258,12 +258,12 @@ Adding dynamics may be achieved using a formulation such as der(h)=(hMed-h)/tau; where ``tau``>0 is a time constant. See, for example, -`Buildings.Fluid.Sensors.SpecificEnthalpyTwoPort `_ +`Buildings.Fluid.Sensors.SpecificEnthalpyTwoPort `_ for a robust implementation. .. note:: In the package - `Buildings.Utilities.Math `_ + `Buildings.Utilities.Math `_ the functions and blocks whose names start with ``smooth`` can be used to avoid events. diff --git a/Buildings/Resources/Documentation/userGuide/build/html/bestPractice.html b/Buildings/Resources/Documentation/userGuide/build/html/bestPractice.html index e054e93783f..4fc758e02e9 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/bestPractice.html +++ b/Buildings/Resources/Documentation/userGuide/build/html/bestPractice.html @@ -212,9 +212,9 @@

2.2. Building large system modelsWhen creating a large system model, it is typically easier to build the system model through the composition of subsystem models that can be tested in isolation. For example, the package -Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples +Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples contains small test models that are used to test individual components in the large system model -Buildings.Examples.ChillerPlant. +Buildings.Examples.ChillerPlant. Creating small test models typically saves time as the proper response of controls, and the proper operation of subsystems, can be tested in isolation of complex system-interactions that are often present in large models.

@@ -482,9 +482,9 @@

2.4.2. Modeling of fluid junctions

However, in more complex flow configurations, one may want to explicitly control what branches of a piping or duct network mix. This may be achieved by using an instance of the model -Junction +Junction as shown in the left figure below, which is derived from the test model -BoilerPolynomialClosedLoop

+BoilerPolynomialClosedLoop

_images/fluidJunctionMixingSplitter.svg
@@ -493,7 +493,7 @@

2.4.2. Modeling of fluid junctions

In Fig. 2.3 (a), the mixing points have been correctly defined by use of the model -Junction. +Junction. However, in Fig. 2.3 (b), all connections are made to the port of the instance spl2. This results in the same configuration as is shown in Fig. 2.3 (c). This is certainly not the intention of the modeler, as this causes all flows to be mixed in the port. @@ -508,13 +508,13 @@

2.4.3. Use of sensors in fluid flow syst

When selecting a sensor model, a distinction needs to be made whether the measured quantity depends on the direction of the flow or not. If the quantity depends on the flow direction, such as temperature or relative humidity, then sensors with two ports from the -Buildings.Fluid.Sensors +Buildings.Fluid.Sensors library should be used. These sensors have a more efficient implementation than sensors with one port for situations where the flow reverses its direction. The proper use sensors is described in the -User’s Guide +User’s Guide of the -Buildings.Fluid.Sensors +Buildings.Fluid.Sensors package.

@@ -522,9 +522,9 @@

2.4.3. Use of sensors in fluid flow syst

This section explains how to set a reference pressure for fluids that model the flow as incompressible flow, such as -Buildings.Media.Water +Buildings.Media.Water and -Buildings.Media.Antifreeze.PropyleneGlycolWater.

+Buildings.Media.Antifreeze.PropyleneGlycolWater.

Consider the flow circuit shown in Fig. 2.4 that consists of a pump or fan, a flow resistance and a volume.

@@ -551,7 +551,7 @@

2.4.3. Use of sensors in fluid flow syst

Similarly, if the medium model -Buildings.Media.Specialized.Water.TemperatureDependentDensity, +Buildings.Media.Specialized.Water.TemperatureDependentDensity, which models density as a function of pressure and enthalpy, is used, then the model is well-defined, but the pressure increases the longer the pump runs. The reason is that the pump adds heat to the water. When the water temperature @@ -560,7 +560,7 @@

2.4.3. Use of sensors in fluid flow syst

To avoid this singularity or increase in pressure, use a model that imposes a pressure source and that accounts for the expansion of the fluid. For example, use -Buildings.Fluid.Sources.Boundary_pT +Buildings.Fluid.Sources.Boundary_pT to form the system model shown in Fig. 2.5.

_images/flowCircuitWithBoundary.svg @@ -570,24 +570,24 @@

2.4.3. Use of sensors in fluid flow syst

Alternatively, you may use -Buildings.Fluid.Storage.ExpansionVessel, +Buildings.Fluid.Storage.ExpansionVessel, but -Buildings.Fluid.Sources.Boundary_pT +Buildings.Fluid.Sources.Boundary_pT usually leads to simpler equations than -Buildings.Fluid.Storage.ExpansionVessel. +Buildings.Fluid.Storage.ExpansionVessel. Note that the medium that flows out of the fluid port of -Buildings.Fluid.Sources.Boundary_pT +Buildings.Fluid.Sources.Boundary_pT is at a fixed temperature, while the model -Buildings.Fluid.Storage.ExpansionVessel +Buildings.Fluid.Storage.ExpansionVessel conserves energy. However, since the thermal expansion of the fluid is usually small, this effect can be neglected in most building HVAC applications.

Note

In each water circuit, there must be exactly on instance of -Buildings.Fluid.Sources.Boundary_pT, +Buildings.Fluid.Sources.Boundary_pT, or instance of -Buildings.Fluid.Storage.ExpansionVessel.

+Buildings.Fluid.Storage.ExpansionVessel.

If there is more than one such device, then there are multiple points in the system that set the reference static pressure. This will affect the distribution of the mass flow rate.

@@ -642,7 +642,7 @@

2.4.5. Nominal ValuesPressureDrop.

+See PressureDrop.

m_flow_nominal m_flow_small

@@ -694,7 +694,7 @@

2.4.5. Nominal Valuestau, and where generally applicable values can be used, components already set a default value for tau. -See for example WetCoilDiscretized.

+See for example WetCoilDiscretized.

diff --git a/Buildings/Resources/Documentation/userGuide/build/html/development.html b/Buildings/Resources/Documentation/userGuide/build/html/development.html index 422eba1d75f..5a1e166f0bb 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/development.html +++ b/Buildings/Resources/Documentation/userGuide/build/html/development.html @@ -201,14 +201,14 @@

5.1. Contributing

They should be of general interest to other users and well documented and tested.

  • They need to follow the coding conventions described in
    • -

  • They need to be made available under the Modelica Buildings Library license.

    • +

  • They need to be made available under the Modelica Buildings Library license.

  • For models of thermofluid flow components, they need to be based on the base classes in -Buildings.Fluid.Interfaces, -which are described in the user guide of this package. +Buildings.Fluid.Interfaces, +which are described in the user guide of this package. Otherwise, it becomes difficult to ensure that the implementation is numerically robust.

    • @@ -557,23 +557,23 @@

    5.4. Adding a new class which is shared by all sensors with one fluid port in the package -Buildings.Fluid.Sensors.

    +See for example Buildings.Fluid.Sensors.BaseClasses.PartialAbsoluteSensor which is shared by all sensors with one fluid port in the package +Buildings.Fluid.Sensors.

    The next sections give guidance that is specific to the implementation of thermofluid flow devices, pressure drop models and control sequences.

    5.4.1. Thermofluid flow device

    To add a component of a thermofluid flow device, the package -Buildings.Fluid.Interface contains basic classes that can be extended. -See Buildings.Fluid.Interface.UsersGuide for a description of these classes. +Buildings.Fluid.Interface contains basic classes that can be extended. +See Buildings.Fluid.Interface.UsersGuide for a description of these classes. Alternatively, simple models such as the models below may be used as a starting point for implementing new models for thermofluid flow devices:

    -
    Buildings.Fluid.HeatExchangers.HeaterCooler_u

    For a device that adds heat to a fluid stream.

    +
    Buildings.Fluid.HeatExchangers.HeaterCooler_u

    For a device that adds heat to a fluid stream.

    -
    Buildings.Fluid.Humidifiers.Humidifier_u

    For a device that adds humidity to a fluid stream.

    +
    Buildings.Fluid.Humidifiers.Humidifier_u

    For a device that adds humidity to a fluid stream.

    -
    Buildings.Fluid.Chillers.Carnot_y

    For a device that exchanges heat between two fluid streams.

    +
    Buildings.Fluid.Chillers.Carnot_y

    For a device that exchanges heat between two fluid streams.

    -
    Buildings.Fluid.MassExchangers.ConstantEffectiveness

    For a device that exchanges heat and humidity between two fluid streams.

    +
    Buildings.Fluid.MassExchangers.ConstantEffectiveness

    For a device that exchanges heat and humidity between two fluid streams.

    @@ -595,11 +595,11 @@

    5.4.1. Thermofluid flow device5.4.2. Pressure drop

    When implementing equations for pressure drop, it is recommended to expand the base class -Buildings.Fluid.BaseClasses.PartialResistance. +Buildings.Fluid.BaseClasses.PartialResistance. Models should allow computing the flow resistance as a quadratic function with regularization near zero as implemented in -Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_dp and in -Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_m_flow. +Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_dp and in +Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_m_flow. The governing equation is

    \[k = \frac{\dot m}{\sqrt{\Delta p}}\]
    @@ -645,7 +645,7 @@

    5.4.3. Control sequences using the Contr

    1. The naming of parameters, inputs, outputs and instances must follow the naming conventions in -Buildings.UsersGuide.Conventions. +Buildings.UsersGuide.Conventions. Avoid providing duplicate information in the instance name, for example if the block is within the Boilers package, the instance name must not contain boi. Ensure that the instance name is unambiguous when viewed in a top level controller block. @@ -821,7 +821,7 @@

      5.4.3. Control sequences using the Contr unit tests wiki page.

      For simple models, the validation can be against analytic solutions. This is for example done in -Buildings.Fluid.FixedResistances.PressureDrop +Buildings.Fluid.FixedResistances.PressureDrop which uses a regression tests that checks the correct relation between mass flow rate and pressure drop.

      For complex thermofluid flow devices, a comparative model validation needs to be done, for example by comparing the result of the Modelica model against the results from EnergyPlus. diff --git a/Buildings/Resources/Documentation/userGuide/build/html/gettingStarted.html b/Buildings/Resources/Documentation/userGuide/build/html/gettingStarted.html index ef1359c38e2..c69191d6278 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/gettingStarted.html +++ b/Buildings/Resources/Documentation/userGuide/build/html/gettingStarted.html @@ -197,7 +197,7 @@

      1.2. Running the First SimulationsExamples.

      Study the detailed tutorials with step-by-step instructions for how to build system models, -which can be found in the Tutorial package.

      +which can be found in the Tutorial package.

      Note that heat transfer models, which can be found in Buildings.HeatTransfer.*.Examples are easier to understand than fluid flow models because;

    diff --git a/Buildings/Resources/Documentation/userGuide/build/html/performance.html b/Buildings/Resources/Documentation/userGuide/build/html/performance.html index b12666c6d56..3881dc4c9a7 100644 --- a/Buildings/Resources/Documentation/userGuide/build/html/performance.html +++ b/Buildings/Resources/Documentation/userGuide/build/html/performance.html @@ -247,8 +247,8 @@

    3.1. Unstable control loopsUser’s Guide of the flow machine package, and the -User’s Guide of the actuator package.

    +User’s Guide of the flow machine package, and the +User’s Guide of the actuator package.

    3.3. Fluid flow systems

    @@ -258,9 +258,9 @@

    3.3.1. Breaking algebraic loopsBuildings.Fluid.FixedResistances.Junction), +(Buildings.Fluid.FixedResistances.Junction), or in models for fans or pumps (such as the model -Buildings.Fluid.Movers.SpeedControlled_y), +Buildings.Fluid.Movers.SpeedControlled_y), the parameter dynamicBalance can be set to true. This adds a control volume at the fluid junction that can decouple the system of equations.

    @@ -330,13 +330,13 @@

    3.3.2. Reducing nonlinear equations of s The valve model then computes the pressure drop using \(\bar k\) and the same equations as described above for the fixed resistances. Thus, the composite model has the same valve authority and mass flow rate, but a nonlinear equation can be avoided.

    For more details, see the -User’s Guide of the actuator package.

    +User’s Guide of the actuator package.

    3.3.3. Prescribed mass flow rate

    For some system models, the mass flow rate can be prescribed by using an idealized pump or fan (model -Buildings.Fluid.Movers.FlowControlled_m_flow) or a source element that outputs the required mass flow rate (such as the model Buildings.Fluid.Sources.MassFlowSource_T). +Buildings.Fluid.Movers.FlowControlled_m_flow) or a source element that outputs the required mass flow rate (such as the model Buildings.Fluid.Sources.MassFlowSource_T). Using these models avoids having to compute the intersection of the fan curve and the flow resistance. In some situations, this can lead to faster and more robust simulation.

    @@ -399,12 +399,12 @@

    3.3.4. Avoiding eventstau>0 is a time constant. See, for example, -Buildings.Fluid.Sensors.SpecificEnthalpyTwoPort +Buildings.Fluid.Sensors.SpecificEnthalpyTwoPort for a robust implementation.

    Note

    In the package -Buildings.Utilities.Math +Buildings.Utilities.Math the functions and blocks whose names start with smooth can be used to avoid events.

    diff --git a/Buildings/Resources/Documentation/userGuide/source/bestPractice.rst b/Buildings/Resources/Documentation/userGuide/source/bestPractice.rst index 9f370d40591..111956cb89a 100644 --- a/Buildings/Resources/Documentation/userGuide/source/bestPractice.rst +++ b/Buildings/Resources/Documentation/userGuide/source/bestPractice.rst @@ -42,9 +42,9 @@ Building large system models When creating a large system model, it is typically easier to build the system model through the composition of subsystem models that can be tested in isolation. For example, the package -`Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples `_ +`Buildings.Examples.ChillerPlant.BaseClasses.Controls.Examples `_ contains small test models that are used to test individual components in the large system model -`Buildings.Examples.ChillerPlant `_. +`Buildings.Examples.ChillerPlant `_. Creating small test models typically saves time as the proper response of controls, and the proper operation of subsystems, can be tested in isolation of complex system-interactions that are often present in large models. @@ -270,9 +270,9 @@ a fluid port represents the physical phenomena that was intended to model. However, in more complex flow configurations, one may want to explicitly control what branches of a piping or duct network mix. This may be achieved by using an instance of the model -`Junction `_ +`Junction `_ as shown in the left figure below, which is derived from the test model -`BoilerPolynomialClosedLoop `_ +`BoilerPolynomialClosedLoop `_ .. _fig_flu_cor_wro: @@ -283,7 +283,7 @@ as shown in the left figure below, which is derived from the test model In :numref:`fig_flu_cor_wro` (a), the mixing points have been correctly defined by use of the model -`Junction `_. +`Junction `_. However, in :numref:`fig_flu_cor_wro` (b), all connections are made to the port of the instance ``spl2``. This results in the same configuration as is shown in :numref:`fig_flu_cor_wro` (c). This is certainly not the intention of the modeler, as this causes all flows to be mixed in the port. @@ -301,13 +301,13 @@ Use of sensors in fluid flow systems When selecting a sensor model, a distinction needs to be made whether the measured quantity depends on the direction of the flow or not. If the quantity depends on the flow direction, such as temperature or relative humidity, then sensors with two ports from the -`Buildings.Fluid.Sensors `_ +`Buildings.Fluid.Sensors `_ library should be used. These sensors have a more efficient implementation than sensors with one port for situations where the flow reverses its direction. The proper use sensors is described in the -`User's Guide `_ +`User's Guide `_ of the -`Buildings.Fluid.Sensors `_ +`Buildings.Fluid.Sensors `_ package. @@ -319,9 +319,9 @@ Reference pressure for incompressible fluids such as water This section explains how to set a reference pressure for fluids that model the flow as :term:`incompressible flow`, such as -`Buildings.Media.Water `_ +`Buildings.Media.Water `_ and -`Buildings.Media.Antifreeze.PropyleneGlycolWater `_. +`Buildings.Media.Antifreeze.PropyleneGlycolWater `_. Consider the flow circuit shown in :numref:`fig_flow_cir` that consists of a pump or fan, a flow resistance and a volume. @@ -354,7 +354,7 @@ In this situation, attempting to translate the model leads, in Dymola, to the fo The number of scalar Real equation elements are 58. Similarly, if the medium model -`Buildings.Media.Specialized.Water.TemperatureDependentDensity `_, +`Buildings.Media.Specialized.Water.TemperatureDependentDensity `_, which models density as a function of pressure and enthalpy, is used, then the model is well-defined, but the pressure increases the longer the pump runs. The reason is that the pump adds heat to the water. When the water temperature @@ -364,7 +364,7 @@ the pressure increases from :math:`1 \, \mathrm{bars}` to :math:`150 \, \mathrm{ To avoid this singularity or increase in pressure, use a model that imposes a pressure source and that accounts for the expansion of the fluid. For example, use -`Buildings.Fluid.Sources.Boundary_pT `_ +`Buildings.Fluid.Sources.Boundary_pT `_ to form the system model shown in :numref:`fig_flow_cir_wit_bou`. .. _fig_flow_cir_wit_bou: @@ -376,15 +376,15 @@ to form the system model shown in :numref:`fig_flow_cir_wit_bou`. provides a reference presssure. Alternatively, you may use -`Buildings.Fluid.Storage.ExpansionVessel `_, +`Buildings.Fluid.Storage.ExpansionVessel `_, but -`Buildings.Fluid.Sources.Boundary_pT `_ +`Buildings.Fluid.Sources.Boundary_pT `_ usually leads to simpler equations than -`Buildings.Fluid.Storage.ExpansionVessel `_. +`Buildings.Fluid.Storage.ExpansionVessel `_. Note that the medium that flows out of the fluid port of -`Buildings.Fluid.Sources.Boundary_pT `_ +`Buildings.Fluid.Sources.Boundary_pT `_ is at a fixed temperature, while the model -`Buildings.Fluid.Storage.ExpansionVessel `_ +`Buildings.Fluid.Storage.ExpansionVessel `_ conserves energy. However, since the thermal expansion of the fluid is usually small, this effect can be neglected in most building HVAC applications. @@ -393,10 +393,10 @@ this effect can be neglected in most building HVAC applications. In each water circuit, there must be exactly on instance of `Buildings.Fluid.Sources.Boundary_pT - `_, + `_, or instance of `Buildings.Fluid.Storage.ExpansionVessel - `_. + `_. If there is more than one such device, then there are multiple points in the system that set the reference static pressure. @@ -592,5 +592,5 @@ is produced. This shows the iteration variables and their start values. These start values can be overwritten in the model. -.. _PressureDrop: https://simulationresearch.lbl.gov/modelica/releases/v8.0.0/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop -.. _WetCoilDiscretized: https://simulationresearch.lbl.gov/modelica/releases/v8.0.0/help/Buildings_Fluid_HeatExchangers.html#Buildings.Fluid.HeatExchangers.WetCoilDiscretized +.. _PressureDrop: https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop +.. _WetCoilDiscretized: https://simulationresearch.lbl.gov/modelica/releases/v9.1.1/help/Buildings_Fluid_HeatExchangers.html#Buildings.Fluid.HeatExchangers.WetCoilDiscretized diff --git a/Buildings/Resources/Documentation/userGuide/source/development.rst b/Buildings/Resources/Documentation/userGuide/source/development.rst index 3e5c7be5e58..703b5c3659c 100644 --- a/Buildings/Resources/Documentation/userGuide/source/development.rst +++ b/Buildings/Resources/Documentation/userGuide/source/development.rst @@ -24,13 +24,13 @@ Models, blocks and functions that are contributed need to adhere to the followin * They should be of general interest to other users and well documented and tested. * They need to follow the coding conventions described in - - the `Buildings library user guide `_ and + - the `Buildings library user guide `_ and - the `Style Guide` provided in subsections of :numref:`sec_sty_gui` - * They need to be made available under the `Modelica Buildings Library license `_. + * They need to be made available under the `Modelica Buildings Library license `_. * For models of thermofluid flow components, they need to be based on the base classes in - `Buildings.Fluid.Interfaces `_, - which are described in the `user guide `_ of this package. + `Buildings.Fluid.Interfaces `_, + which are described in the `user guide `_ of this package. Otherwise, it becomes difficult to ensure that the implementation is numerically robust. .. _sec_sty_gui: @@ -408,8 +408,8 @@ Adding a new class, such as a model or a function, is usually easiest by extendi In many cases, the similar component already exists. In this situation, it is recommended to copy and modify a similar component. If both components share a significant amount of similar code, then a base class should be introduced that implements the common code. -See for example `Buildings.Fluid.Sensors.BaseClasses.PartialAbsoluteSensor `_ which is shared by all sensors with one fluid port in the package -`Buildings.Fluid.Sensors `_. +See for example `Buildings.Fluid.Sensors.BaseClasses.PartialAbsoluteSensor `_ which is shared by all sensors with one fluid port in the package +`Buildings.Fluid.Sensors `_. The next sections give guidance that is specific to the implementation of thermofluid flow devices, pressure drop models and control sequences. @@ -417,20 +417,20 @@ Thermofluid flow device ~~~~~~~~~~~~~~~~~~~~~~~ To add a component of a thermofluid flow device, the package -`Buildings.Fluid.Interface `_ contains basic classes that can be extended. -See `Buildings.Fluid.Interface.UsersGuide `_ for a description of these classes. +`Buildings.Fluid.Interface `_ contains basic classes that can be extended. +See `Buildings.Fluid.Interface.UsersGuide `_ for a description of these classes. Alternatively, simple models such as the models below may be used as a starting point for implementing new models for thermofluid flow devices: -`Buildings.Fluid.HeatExchangers.HeaterCooler_u `_ +`Buildings.Fluid.HeatExchangers.HeaterCooler_u `_ For a device that adds heat to a fluid stream. -`Buildings.Fluid.Humidifiers.Humidifier_u `_ +`Buildings.Fluid.Humidifiers.Humidifier_u `_ For a device that adds humidity to a fluid stream. -`Buildings.Fluid.Chillers.Carnot_y `_ +`Buildings.Fluid.Chillers.Carnot_y `_ For a device that exchanges heat between two fluid streams. -`Buildings.Fluid.MassExchangers.ConstantEffectiveness `_ +`Buildings.Fluid.MassExchangers.ConstantEffectiveness `_ For a device that exchanges heat and humidity between two fluid streams. .. _fig_merkel: @@ -454,11 +454,11 @@ Pressure drop When implementing equations for pressure drop, it is recommended to expand the base class -`Buildings.Fluid.BaseClasses.PartialResistance `_. +`Buildings.Fluid.BaseClasses.PartialResistance `_. Models should allow computing the flow resistance as a quadratic function with regularization near zero as implemented in -`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_dp `_ and in -`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_m_flow `_. +`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_dp `_ and in +`Buildings.Fluid.BaseClasses.FlowModels.basicFlowFunction_m_flow `_. The governing equation is .. math:: @@ -514,7 +514,7 @@ The following rules need to be followed, in addition to the guidelines described #. The naming of parameters, inputs, outputs and instances must follow the naming conventions in - `Buildings.UsersGuide.Conventions `_. + `Buildings.UsersGuide.Conventions `_. Avoid providing duplicate information in the instance name, for example if the block is within the ``Boilers`` package, the instance name must not contain ``boi``. Ensure that the instance name is unambiguous when viewed in a top level controller block. @@ -671,7 +671,7 @@ The validation models are part of automated unit tests as described at the For simple models, the validation can be against analytic solutions. This is for example done in -`Buildings.Fluid.FixedResistances.PressureDrop `_ +`Buildings.Fluid.FixedResistances.PressureDrop `_ which uses a regression tests that checks the correct relation between mass flow rate and pressure drop. For complex thermofluid flow devices, a comparative model validation needs to be done, for example diff --git a/Buildings/Resources/Documentation/userGuide/source/gettingStarted.rst b/Buildings/Resources/Documentation/userGuide/source/gettingStarted.rst index 586a6a60e4d..55e1c46105b 100644 --- a/Buildings/Resources/Documentation/userGuide/source/gettingStarted.rst +++ b/Buildings/Resources/Documentation/userGuide/source/gettingStarted.rst @@ -40,7 +40,7 @@ or by replacing existing component models by new ones. The example models can be found in the packages `Examples`. Study the detailed tutorials with step-by-step instructions for how to build system models, -which can be found in the `Tutorial package `_. +which can be found in the `Tutorial package `_. Note that heat transfer models, which can be found in `Buildings.HeatTransfer.*.Examples` are easier to understand than fluid flow models because; @@ -51,7 +51,7 @@ are easier to understand than fluid flow models because; To get started with Spawn of EnergyPlus, we recommend to first familiarize yourself with Modelica, as described above. Next, read the -`user guide for the Spawn models `_ +`user guide for the Spawn models `_ which provides step-by-step instructions and points to various examples. diff --git a/Buildings/Resources/Documentation/userGuide/source/performance.rst b/Buildings/Resources/Documentation/userGuide/source/performance.rst index a079469114e..5ab89802d21 100644 --- a/Buildings/Resources/Documentation/userGuide/source/performance.rst +++ b/Buildings/Resources/Documentation/userGuide/source/performance.rst @@ -78,8 +78,8 @@ The default value is ``raiseTime=120`` seconds. closed loop control performance. For further information, see the -`User's Guide of the flow machine package `_, and the -`User's Guide of the actuator package `_. +`User's Guide of the flow machine package `_, and the +`User's Guide of the actuator package `_. Fluid flow systems @@ -92,9 +92,9 @@ In fluid flow systems, flow junctions where mass flow rates separate and mix can This leads to larger systems of coupled equations that need to be solved, which often causes larger computing time and can sometimes cause convergence problems. To decouple these systems of equations, in the model of a flow junction -(`Buildings.Fluid.FixedResistances.Junction `_), +(`Buildings.Fluid.FixedResistances.Junction `_), or in models for fans or pumps (such as the model -`Buildings.Fluid.Movers.SpeedControlled_y `_), +`Buildings.Fluid.Movers.SpeedControlled_y `_), the parameter ``dynamicBalance`` can be set to ``true``. This adds a control volume at the fluid junction that can decouple the system of equations. @@ -174,7 +174,7 @@ The valve model then computes the pressure drop using :math:`\bar k` and the sam Thus, the composite model has the same :term:`valve authority` and mass flow rate, but a nonlinear equation can be avoided. For more details, see the -`User's Guide of the actuator package `_. +`User's Guide of the actuator package `_. @@ -183,7 +183,7 @@ Prescribed mass flow rate For some system models, the mass flow rate can be prescribed by using an idealized pump or fan (model -`Buildings.Fluid.Movers.FlowControlled_m_flow `_) or a source element that outputs the required mass flow rate (such as the model `Buildings.Fluid.Sources.MassFlowSource_T `_). +`Buildings.Fluid.Movers.FlowControlled_m_flow `_) or a source element that outputs the required mass flow rate (such as the model `Buildings.Fluid.Sources.MassFlowSource_T `_). Using these models avoids having to compute the intersection of the fan curve and the flow resistance. In some situations, this can lead to faster and more robust simulation. @@ -258,12 +258,12 @@ Adding dynamics may be achieved using a formulation such as der(h)=(hMed-h)/tau; where ``tau``>0 is a time constant. See, for example, -`Buildings.Fluid.Sensors.SpecificEnthalpyTwoPort `_ +`Buildings.Fluid.Sensors.SpecificEnthalpyTwoPort `_ for a robust implementation. .. note:: In the package - `Buildings.Utilities.Math `_ + `Buildings.Utilities.Math `_ the functions and blocks whose names start with ``smooth`` can be used to avoid events.