Skip to content

Commit

Permalink
Updated user guide [ci skip]
Browse files Browse the repository at this point in the history
  • Loading branch information
@mwetter
mwetter committed Nov 17, 2017
1 parent 15d1158 commit aa21ae6
Show file tree
Hide file tree
Showing 13 changed files with 52 additions and 29 deletions.
6 changes: 3 additions & 3 deletions ...ings/Resources/Documentation/userGuide/build/html/_sources/bestPractice.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,7 @@ In some situation, such as the configuration below, connecting multiple connecto
Connection of three components without explicitly introducing a mixer or splitter 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
`SplitterFixedResistanceDpM <http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.SplitterFixedResistanceDpM>`_ as shown in the left figure below, which is the test model
`PressureDrop <http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop>`_ as shown in the left figure below, which is the test model
`BoilerPolynomialClosedLoop <http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_Boilers_Examples.html#Buildings.Fluid.Boilers.Examples.BoilerPolynomialClosedLoop>`_

.. figure:: img/fluidJunctionMixingSplitter.png
Expand Down Expand Up @@ -363,7 +363,7 @@ parameters in various model to help the user understand how they are used.
| ``m_flow_nominal`` | | Flow resistance models. | These parameters may be used to define a point on the flow rate |
| ``dp_nominal`` | | versus pressure drop curve. For other mass flow rates, the pressure drop |
| | | is typically adjusted using similarity laws. |
| | | See FixedResistanceDpM_. |
| | | See PressureDrop_. |
+---------------------+---------------------------+--------------------------------------------------------------------------+
| ``m_flow_nominal`` | | Sensors. | Some of these models set ``m_flow_small=1E-4*abs(m_flow_nominal)`` |
| ``m_flow_small`` | | Volumes. | as the default value. Then, m_flow_small is used to regularize, or |
Expand Down Expand Up @@ -749,5 +749,5 @@ As an extreme case, if a system is chaotic
and uncontrolled, then the global integration error will grow rapidly.


.. _FixedResistanceDpM: http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.FixedResistanceDpM
.. _PressureDrop: http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop
.. _WetCoilDiscretized: http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_HeatExchangers.html#Buildings.Fluid.HeatExchangers.WetCoilDiscretized
8 changes: 8 additions & 0 deletions ...gs/Resources/Documentation/userGuide/build/html/_sources/gettingStarted.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,14 @@ Although the `Modelica Language Tutorial <https://www.modelica.org/documents/Mod
Links to papers that describe or used the `Buildings` library are available at http://simulationresearch.lbl.gov/modelica/publications.html.
The model documentation from the download page contains user guides that describe the individual packages of the `Buildings` library.

The `IEA EBC Annex 60 <http://www.iea-annex60.org/final-report.html>`_ final report
summarizes the development of Modelica models, approaches and tools
for co-simulation based on the Functional Mockup Interface standard,
Building Information Modeling technologies based on the Industry Foundation Classes,
as well as tools for workflow automation.
It also contains numerous examples that apply these technologies to the
design and operation of building and community energy systems.


Literature for Developers
-------------------------
Expand Down
2 changes: 1 addition & 1 deletion Buildings/Resources/Documentation/userGuide/build/html/_sources/help.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,4 @@ For general questions regarding the `Buildings` library, use
https://unmethours.com/questions/.
This is an open group and everyone can join it. No invitation is needed.

For questions that are specific to Modelica but not the `Buildings` libray, see http://stackoverflow.com/search?q=modelica
For questions that are specific to Modelica but not the `Buildings` libray, see https://stackoverflow.com/search?q=modelica
4 changes: 2 additions & 2 deletions ...dings/Resources/Documentation/userGuide/build/html/_sources/workArounds.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Breaking algebraic loops
------------------------

In fluid flow systems, flow junctions where mass flow rates separate and mix can couple non-linear systems of equations. 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 splitter or mixer (model `Buildings.Fluid.FixedResistances.SplitterFixedResistanceDpM <http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.SplitterFixedResistanceDpM>`_), or in models for fans or pumps (such as the model `Buildings.Fluid.Movers.SpeedControlled_y <http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_Movers.html#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.
To decouple these systems of equations, in the model of a flow splitter or mixer (model `Buildings.Fluid.FixedResistances.PressureDrop <http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop>`_), or in models for fans or pumps (such as the model `Buildings.Fluid.Movers.SpeedControlled_y <http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_Movers.html#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.

Reducing nonlinear equations of serially connected flow resistances
-------------------------------------------------------------------
Expand Down Expand Up @@ -90,7 +90,7 @@ Suppose the parameters are

.. code-block:: modelica
Buildings.Fluid.FixedResistances.FixedResistanceDpM res(
Buildings.Fluid.FixedResistances.PressureDrop res(
redeclare package Medium = Medium,
m_flow_nominal=0.2,
dp_nominal=10000);
Expand Down
26 changes: 13 additions & 13 deletions Buildings/Resources/Documentation/userGuide/build/html/bestPractice.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,7 @@ <h3>2.4.1. Overdetermined initialization problem and inconsistent equations<a cl
<p>We will now explain how state variables, such as temperature and pressure, can be initialized.</p>
<p>Consider a model consisting of a mass flow source <code class="docutils literal"><span class="pre">Modelica.Fluid.Sources.MassFlowSource_T</span></code>, a fluid volume <code class="docutils literal"><span class="pre">Buildings.Fluid.MixingVolumes.MixingVolume</span></code> and
a fixed boundary condition <code class="docutils literal"><span class="pre">Buildings.Fluid.Sources.FixedBoundary</span></code>, connected in series as shown in the figure below. Note that the instance <code class="docutils literal"><span class="pre">bou</span></code> implements an equation that sets the medium pressure at its port, i.e., the port pressure <code class="docutils literal"><span class="pre">bou.ports.p</span></code> is fixed.</p>
<div class="figure" id="id8">
<div class="figure" id="id9">
<a class="reference internal image-reference" href="_images/MixingVolumeInitialization.png"><img alt="_images/MixingVolumeInitialization.png" src="_images/MixingVolumeInitialization.png" style="width: 371.0px; height: 161.0px;" /></a>
<p class="caption"><span class="caption-number">Fig. 2.1 </span><span class="caption-text">Schematic diagram of a flow source, a fluid volume, and a pressure source.</span></p>
</div>
Expand Down Expand Up @@ -458,14 +458,14 @@ <h3>2.4.1. Overdetermined initialization problem and inconsistent equations<a cl
<h3>2.4.2. Modeling of fluid junctions<a class="headerlink" href="#modeling-of-fluid-junctions" title="Permalink to this headline"></a></h3>
<p>In Modelica, connecting fluid ports as shown below leads to ideal mixing at the junction.
In some situation, such as the configuration below, connecting multiple connectors to a fluid port represents the physical phenomena that was intended to model.</p>
<div class="figure" id="id9">
<div class="figure" id="id10">
<a class="reference internal image-reference" href="_images/fluidJunctionMixing.png"><img alt="_images/fluidJunctionMixing.png" src="_images/fluidJunctionMixing.png" style="width: 201.0px; height: 240.0px;" /></a>
<p class="caption"><span class="caption-number">Fig. 2.2 </span><span class="caption-text">Connection of three components without explicitly introducing a mixer or splitter model.</span></p>
</div>
<p>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
<a class="reference external" href="http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.SplitterFixedResistanceDpM">SplitterFixedResistanceDpM</a> as shown in the left figure below, which is the test model
<a class="reference external" href="http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop">PressureDrop</a> as shown in the left figure below, which is the test model
<a class="reference external" href="http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_Boilers_Examples.html#Buildings.Fluid.Boilers.Examples.BoilerPolynomialClosedLoop">BoilerPolynomialClosedLoop</a></p>
<div class="figure" id="id10">
<div class="figure" id="id11">
<img alt="_images/fluidJunctionMixingSplitter.png" src="_images/fluidJunctionMixingSplitter.png" />
<p class="caption"><span class="caption-number">Fig. 2.3 </span><span class="caption-text">Correct (left) and wrong (right) connection of components with use of a mixer or splitter model.</span></p>
</div>
Expand All @@ -484,7 +484,7 @@ <h3>2.4.3. Use of sensors in fluid flow systems<a class="headerlink" href="#use-
<span id="referencepressureincompressiblefluids"></span><h3>2.4.4. Reference pressure for incompressible fluids such as water<a class="headerlink" href="#reference-pressure-for-incompressible-fluids-such-as-water" title="Permalink to this headline"></a></h3>
<p>This section explains how to set a reference pressure for incompressible fluids. For fluids that model density as a function of temperature, the section also shows how to account for the thermal expansion of the fluid.</p>
<p>Consider the flow circuit shown below that consists of a pump or fan, a flow resistance and a volume.</p>
<div class="figure" id="id11">
<div class="figure" id="id12">
<a class="reference internal image-reference" href="_images/flowCircuitNoExpansion.png"><img alt="_images/flowCircuitNoExpansion.png" src="_images/flowCircuitNoExpansion.png" style="width: 449.4px; height: 370.8px;" /></a>
<p class="caption"><span class="caption-number">Fig. 2.4 </span><span class="caption-text">Schematic diagram of a flow circuit without means
to set a reference pressure, or to account for
Expand Down Expand Up @@ -521,7 +521,7 @@ <h3>2.4.3. Use of sensors in fluid flow systems<a class="headerlink" href="#use-
For example, use
<a class="reference external" href="http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel">Buildings.Fluid.Storage.ExpansionVessel</a>
to form the system model shown below.</p>
<div class="figure" id="id12">
<div class="figure" id="id13">
<a class="reference internal image-reference" href="_images/flowCircuitWithExpansionVessel.png"><img alt="_images/flowCircuitWithExpansionVessel.png" src="_images/flowCircuitWithExpansionVessel.png" style="width: 459.6px; height: 404.4px;" /></a>
<p class="caption"><span class="caption-number">Fig. 2.5 </span><span class="caption-text">Schematic diagram of a flow circuit with expansion vessel that
adds a pressure source and accounts for the thermal expansion
Expand All @@ -537,7 +537,7 @@ <h3>2.4.3. Use of sensors in fluid flow systems<a class="headerlink" href="#use-
is at a fixed temperature, while the model
<a class="reference external" href="http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_Storage.html#Buildings.Fluid.Storage.ExpansionVessel">Buildings.Fluid.Storage.ExpansionVessel</a> conserves energy.
However, since the thermal expansion of the fluid is usually small, this effect can be neglected in most building HVAC applications.</p>
<div class="figure" id="id13">
<div class="figure" id="id14">
<a class="reference internal image-reference" href="_images/flowCircuitWithBoundary.png"><img alt="_images/flowCircuitWithBoundary.png" src="_images/flowCircuitWithBoundary.png" style="width: 475.2px; height: 415.2px;" /></a>
<p class="caption"><span class="caption-number">Fig. 2.6 </span><span class="caption-text">Schematic diagram of a flow circuit with a boundary model that adds
a fixed pressure source and accounts for any thermal expansion
Expand Down Expand Up @@ -588,7 +588,7 @@ <h3>2.4.5. Nominal Values<a class="headerlink" href="#nominal-values" title="Per
<td>These parameters may be used to define a point on the flow rate
versus pressure drop curve. For other mass flow rates, the pressure drop
is typically adjusted using similarity laws.
See <a class="reference external" href="http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.FixedResistanceDpM">FixedResistanceDpM</a>.</td>
See <a class="reference external" href="http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_Fluid_FixedResistances.html#Buildings.Fluid.FixedResistances.PressureDrop">PressureDrop</a>.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">m_flow_nominal</span></code>
<code class="docutils literal"><span class="pre">m_flow_small</span></code></td>
Expand Down Expand Up @@ -730,7 +730,7 @@ <h2>2.6. Avoiding events<a class="headerlink" href="#avoiding-events" title="Per
</div>
<div class="section" id="controls">
<h2>2.7. Controls<a class="headerlink" href="#controls" title="Permalink to this headline"></a></h2>
<div class="figure" id="id14">
<div class="figure" id="id15">
<a class="reference internal image-reference" href="_images/controlHysteresis.png"><img alt="_images/controlHysteresis.png" src="_images/controlHysteresis.png" style="width: 270.0px; height: 401.0px;" /></a>
<p class="caption"><span class="caption-number">Fig. 2.7 </span><span class="caption-text">Schematic diagram of a controller that switches a coil on and off.
In the top configuration, the hysteresis avoids numerical problems
Expand Down Expand Up @@ -805,7 +805,7 @@ <h3>2.8.1. State events<a class="headerlink" href="#state-events" title="Permali
</div>
<p>and plotted the computing time and the number of events. Around <span class="math">\(t=0.95e7\)</span> seconds,
there was a spike as shown in the figure below.</p>
<div class="figure" id="id15">
<div class="figure" id="id16">
<a class="reference internal image-reference" href="_images/DualFanDualDuct-cpu-events.png"><img alt="_images/DualFanDualDuct-cpu-events.png" src="_images/DualFanDualDuct-cpu-events.png" style="width: 352.8px; height: 244.2px;" /></a>
<p class="caption"><span class="caption-number">Fig. 2.8 </span><span class="caption-text">Computing time and number of events.</span></p>
</div>
Expand Down Expand Up @@ -844,7 +844,7 @@ <h3>2.8.1. State events<a class="headerlink" href="#state-events" title="Permali
to switch the sign of the control gain because the economizer can provide heating or cooling,
depending on the ambient and return air temperature. The problematic model is
shown in the figure below.</p>
<div class="figure" id="id16">
<div class="figure" id="id17">
<span id="fig-dualfan-eco-con-bad"></span><a class="reference internal image-reference" href="_images/EconomizerTemperatureControl-bad.svg"><img alt="_images/EconomizerTemperatureControl-bad.svg" src="_images/EconomizerTemperatureControl-bad.svg" /></a>
<p class="caption"><span class="caption-number">Fig. 2.9 </span><span class="caption-text">Block diagram of part of the economizer control that computes the outside air damper
control signal. This implementation triggers many events.</span></p>
Expand All @@ -860,7 +860,7 @@ <h3>2.8.1. State events<a class="headerlink" href="#state-events" title="Permali
which we did as shown in the figure below.
We selected a hysteresis of <span class="math">\(0.2\)</span> Kelvin, and now the model runs fine
for the whole year.</p>
<div class="figure" id="id17">
<div class="figure" id="id18">
<span id="fig-dualfan-eco-con-revised"></span><a class="reference internal image-reference" href="_images/EconomizerTemperatureControl-revised.svg"><img alt="_images/EconomizerTemperatureControl-revised.svg" src="_images/EconomizerTemperatureControl-revised.svg" /></a>
<p class="caption"><span class="caption-number">Fig. 2.10 </span><span class="caption-text">Block diagram of part of the revised economizer control that computes the outside air damper
control signal.</span></p>
Expand All @@ -873,7 +873,7 @@ <h3>2.8.2. State variables that dominate the error control<a class="headerlink"
(commit <a class="reference external" href="https://github.com/lbl-srg/modelica-buildings/commit/ef410ee8a5d1816f8b8e171da7743e15caaa3163">ef410ee</a>),
the simulation time was very slow during part of the
simulation, as shown in <a class="reference internal" href="#fig-dualfan-filtered-speed"><span class="std std-numref">Fig. 2.11</span></a>.</p>
<div class="figure" id="id18">
<div class="figure" id="id19">
<span id="fig-dualfan-filtered-speed"></span><a class="reference internal image-reference" href="_images/DualFanDualDuctWithFilteredSpeed.svg"><img alt="_images/DualFanDualDuctWithFilteredSpeed.svg" src="_images/DualFanDualDuctWithFilteredSpeed.svg" /></a>
<p class="caption"><span class="caption-number">Fig. 2.11 </span><span class="caption-text">Computing time and number of events.</span></p>
</div>
Expand Down
7 changes: 7 additions & 0 deletions Buildings/Resources/Documentation/userGuide/build/html/gettingStarted.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,13 @@ <h2>1.1. Literature for Users<a class="headerlink" href="#literature-for-users"
<p>Although the <a class="reference external" href="https://www.modelica.org/documents/ModelicaTutorial14.pdf">Modelica Language Tutorial</a> is for an older version (Modelica 1.4), it is still instructive and relevant to understand the concepts of the language.</p>
<p>Links to papers that describe or used the <cite>Buildings</cite> library are available at <a class="reference external" href="http://simulationresearch.lbl.gov/modelica/publications.html">http://simulationresearch.lbl.gov/modelica/publications.html</a>.
The model documentation from the download page contains user guides that describe the individual packages of the <cite>Buildings</cite> library.</p>
<p>The <a class="reference external" href="http://www.iea-annex60.org/final-report.html">IEA EBC Annex 60</a> final report
summarizes the development of Modelica models, approaches and tools
for co-simulation based on the Functional Mockup Interface standard,
Building Information Modeling technologies based on the Industry Foundation Classes,
as well as tools for workflow automation.
It also contains numerous examples that apply these technologies to the
design and operation of building and community energy systems.</p>
</div>
<div class="section" id="literature-for-developers">
<h2>1.2. Literature for Developers<a class="headerlink" href="#literature-for-developers" title="Permalink to this headline"></a></h2>
Expand Down
Loading

0 comments on commit aa21ae6

Please sign in to comment.