1 Introduction
1.1 Greetings
The purpose of this manual is to document the California Simulation Engine computer program, CSE. CSE is an hourly building and HVAC simulation program which calculates annual energy requirements for building space conditioning and lighting. CSE is specifically tailored for use as internal calculation machinery for compliance with the California building standards.
CSE is a batch driven program which reads its input from a text file. It is not intended for direct use by people seeking to demonstrate compliance. Instead, it will be used within a shell program or by technically oriented users. As a result, this manual is aimed at several audiences:
People testing CSE during its development.
Developers of the CSE shell program.
Researchers and standards developers who will use the program to explore possible conservation opportunities.
Each of these groups is highly sophisticated. Therefore this manual generally uses an exhaustive, one-pass approach: while a given topic is being treated, everything about that topic is presented with the emphasis on completeness and accuracy over ease of learning.
Please note that CSE is under development and will be for many more months. Things will change and from time to time this manual may be inconsistent with the program.
1.2 Manual Organization
This Introduction covers general matters, including program installation.
Operation documents the operational aspects of CSE, such as command line switches, file naming conventions, and how CSE finds files it needs.
Input Structure documents the CSE input language in general.
Input Data describes all of the specific input language statements.
Output Reports will describe the output reports.
Lastly, Probe Definitions lists all available probes.
1.3 Installation
1.3.1 Hardware and Software Requirements
CSE is a 32-bit Microsoft Windows console application. That is, it runs at the command prompt on Windows Vista, Windows 7, Windows 8, and Windows 10. Memory and disk space requirements depend on the size of projects being modeled, but are generally modest.
To prepare input files, a text editor is required. Notepad will suffice, although a text editor intended for programming is generally more capable. Alternatively, some word processors can be used in “ASCII” or “text” or “non-document” mode.
1.3.2 Installation Procedure
Create a directory on your hard disk with the name \CSE or some other name of your choice. Copy the files into that directory. Add the name of the directory to the PATH environment setting unless you intend to use CSE only from the CSE directory.
2 Operation
2.1 Command Line
CSE is invoked from the command prompt or from a batch file using the following command:
CSE *inputfile* {*switches*}
where:
- inputfile
- specifies the name of the text input file for the run(s). If the filename has an extension other than “.cse” (the default), it must be included. The name of the file with weather data for the simulation(s) is given in this file (wfName= statement, see Weather Data Items).
- {switches}
- indicates zero or more of the following:
-Dname defines the preprocessor symbol name with the value “”. Useful for testing with
#ifdef name
, to invoke variations in the simulation without changing the input file. The CSE preprocessor is described “The Preprocessor”.-Dname=value defines the preprocessor symbol name with the specified value. Name can then be used in the input file to allow varying the simulation without changing the input file – see “The Preprocessor” for more information. The entire switch should be enclosed in quotes if it contains any spaces – otherwise the command processor will divide it into two arguments and CSE will not understand it.
-Uname undefines the preprocessor symbol name.
-ipath;path;path specifies directories where CSE looks for input and include files.
-b batch mode: suppresses all prompts for user input. Currently there are no prompts implemented in CSE. -b is retained in case prompts are added in the future. It is good practice to include -b in batch script CSE invocations.
-n suppresses screen display of warning messages. When -n is specified, warning messages are reported only to the error file.
-p display all the class and member names that can be “probed” or accessed in CSE expressions. “Probes” are described in “Probes”. Use with command processor redirection operator “>” to obtain a report in a file. Inputfile may be given or omitted when -p is given.
-p1 similar to -p, but displays additional member names that cannot be probed or would not make sense to probe in an input file (development aid).
-c display all input names.
-c1 display input names with build-independent details from CSE CULT tables (development aid).
-c2 display input names with all details from CSE CULT tables (development aid).
-x specifies report test prefix; see TOP repTestPfx. The -x command line setting takes precedence over the input file value, if any.
-tnn specifies internal testing option bits (development aid). The following values should be combined bit-wise to determine nn.
1: Omit directory paths from file names in reports, yielding location-independent report files suitable for text comparison.
2: Include detailed timing information in the log file (default is summary only).
2.2 Locating Files
As with any program, in order to invoke CSE, the directory containing CSE.EXE must be the current directory, or that directory must be on the operating system path, or you must type the directory path before CSE.
A CSE simulation requires a weather file. The name of the weather file is given in the CSE input file (wfName=
statement, see Weather Data Items). The weather file must be in one of the same three places: current directory, directory containing CSE.EXE, or a directory on the operating system path; or, the directory path to the file must be given in the wfName=
statement in the usual pathName syntax. ?? Appears that file must be in current directory due to file locating bugs 2011-07
The CSE input file, named on the CSE command line, must be in the current directory or the directory path to it must be included in the command line.
Included input files, named in #include
preprocessor directives (see “The Preprocessor”) in the input file, must be in the current directory or the path to them must be given in the #include
directive. In particular, CSE will NOT automatically look for included files in the directory containing the input file. The default extension for included files is “.CSE”.
Output files created by default by CSE (error message file, primary report and export files) will be in the same directory as the input file; output files created by explicit command in the input file (additional report and/or export files) will be in the current directory unless another path is explicitly specified in the command creating the file.
2.3 Output File Names
If any error or warning messages are generated, CSE puts them in a file with the same name and path as the input file and extension .ERR, as well as on the screen and, usually, in the primary (default) report file. The exception is errors in the command line: these appear only on the screen. If there are no error or warning messages, any prior file with this name is deleted.
By default, CSE generates an output report file with the same name and path as the input file, and extension “.REP”. This file may be examined with a text editor and/or copied to an ASCII printer. If any exports are specified, they go by default into a file with the same name and path as the input file and extension “.EXP”.
In response to specifications in the input file, CSE can also generate additional report and export files with user-specified names. The default extensions for these are .REP and .CSV respectively and the default directory is the current directory; other paths and extensions may be specified. For more information on report and export files, see REPORTFILE and EXPORTFILE in “Input Data”.
2.4 Errorlevel
CSE sets the command processor ERRORLEVEL to 2 if any error occurs in the session. This should be tested in batch files that invoke CSE, to prevent use of the output reports if the run was not satisfactory. The ERRORLEVEL is NOT set if only warning messages that do not suppress or abort the run occur, but such messages DO create the .ERR file.
3 Input Structure
DRAFT: In the following, any text annotated with ?? indicates areas of uncertainty or probable change. As the program and input language develop, these matters will be resolved.
3.1 Introduction
The CSE Input Language is the fundamental interface to the CSE program. The language has been designed with three objectives in mind:
Providing direct access to all program features (including ones included for self-testing), to assist in program development.
Providing a set of parametric and expression evaluation capabilities useful for standards development and program testing.
Providing a means for other programs, such as an interactive user interface, to transmit input data and control data to the program.
Thus, the language is not intended to be used by the average compliance or simulation user. Instead, it will be used during program development for testing purposes and subsequently for highly technical parametric studies, such as those conducted for research and standards development. In all of these situations, power, reproducibility, and thorough input documentation take precedence over user-friendliness.
CSE reads its input from a file. The file may be prepared by the user with a text editor, or generated by some other program.
3.2 Form of the CSE Data
The data used by CSE consists of objects. Each object is of a class, which determines what the object represents. For example, objects of class ZONE represent thermally distinct regions of the building; each thermally distinct region has its own ZONE object. An object’s class determines what data items or members it contains. For instance, a ZONE object contains the zone’s area and volume. In addition, each object can have a name.
The objects are organized in a hierarchy, or tree-like structure. For example, under each ZONE object, there can be SURFACE objects to represent the walls, floors, and ceilings of the ZONE. Under SURFACEs there can be WINDOW objects to represent glazings in the particular wall or roof. SURFACE is said to be a subclass of the class ZONE and WINDOW a subclass of SURFACE; each individual SURFACE is said to be a subobject of its particular ZONE object. Conversely, each individual SURFACE is said to be owned by its zone, and the SURFACE class is said to be owned by the ZONE class.
The hierarchy is rooted in the one top-level object (or just Top). The top level object contains information global to the entire simulation, such as the start and end dates, as well as all of the objects that describe the building to be simulated and the reports to be printed.
Objects and their required data must be specified by the user, except that Top is predefined. This is done with input language statements. Each statement begins an object (specifying its class and object name) or gives a value for a data member of the object being created. Each object is specified with a group of statements that are usually given together, and the objects must be organized according to the hierarchy. For example, SURFACEs must be specified within ZONEs and WINDOWs within SURFACEs. Each SURFACE belongs to (is a subobject of) the ZONE within which it is specified, and each WINDOW is a subobject of its SURFACE.
The entire hierarchy of CSE classes can be represented as follows, using indentation to indicate subclasses:
TODO: review hierarchy
TOP (Top-level class; object of this class supplied automatically by CSE)
HOLIDAY
MATERIAL
CONSTRUCTION
LAYER
METER
DHWMETER
IZXFER
DHWDAYUSE
DHWUSE
DHWSYS
DHWHEATER
DHWTANK
DHWPUMP
DHWLOOP
DHWLOOPPUMP
DHWLOOPSEG
DHWLOOPBRANCH
DHWSOLARSYS
DHWSOLARCOLLECTOR
ZONE
GAIN
SURFACE
WINDOW
SHADE
SGDIST
DOOR
REPORTFILE
REPORT
REPORTCOL
EXPORTFILE
EXPORT
EXPORTCOL
3.3 Overview of CSE Input Language
The CSE Input Language consists of commands, each beginning with a particular word and, preferably, ending with a semicolon. Each command is either an action-command, which specifies some action such as starting a simulation run, or a statement, which creates or modifies an object or specifies a value for a member of an object.
3.3.1 Statements – Overview
A statement that creates an object consists basically of the class name followed by your name for the object to be created. (The name can be omitted for most classes; optional modifying clauses will be described later.) For example,
ZONE "north";
begins an object of class ZONE; the particular zone will be named “north”. This zone name will appear in reports and error messages, and will be used in other statements that operate on the zone. As well as creating the ZONE, this statement sets CSE to expect statements specifying ZONE data members or ZONE subobjects to follow.
A statement specifying a data member consists of the data member’s name, an = sign, an expression specifying the value, and a terminating semicolon. An expression is a valid combination of operands and operators as detailed later; commonly it is just a number, name, or text enclosed in quotes. For example,
znVol = 100000;
specifies that the zone has a volume of 100000 cubic feet. (If the statement occurs outside of the description of a ZONE, an error message occurs.) All of the member names for each class are described in the input data section; most of them begin with an abbreviation of the class name for clarity.
The description of a zone or any object except Top can be terminated with the word “END”; but this is not essential; CSE will assume the ZONE ends when you start another ZONE or any object not a subobject of ZONE, or when you specify a member of a higher level class (Top for ZONE), or give an action-command such as RUN.
Statements are free-form; several can be put on a line, or a single statement can occupy several lines. Indentation according to class hierarchy will help make your input file readable. Spaces may be used freely except in the middle of a word or number. Tab characters may be used. Each statement should end with a semicolon. If the semicolon is omitted and the statement and the following statement are both correctly formed, CSE will figure out your intent anyway. But when there is an error, CSE gives clearer error messages when the statements are delimited with semicolons.
Capitalization generally does not matter in input language statements; we like to capitalize class names to make them stand out. Words that differ only in capitalization are NOT distinct to CSE.
Comments (remarks) may be interspersed with commands. Comments are used to make the input file clearer to humans; they are ignored by CSE. A comment introduced with “//” ends at the end of the line; a comment introduced with “/*” continues past the next “*/”, whether on the same line, next line, or many lines down. Additional input language may follow the */ on the same line.
3.3.2 Nested Objects
The following is a brief CSE input file, annotated with comments intended to exemplify how the input language processor follows the object hierarchy when decoding input describing objects and their subobjects.
// short example file
// initially, the current object is Top.
wfName = "CZ12RV2.CEC"; // give weather file name, a Top member
begDay = Jan 1; // start and ...
endDay = Dec 31; // ...end run dates: Top members.
MATERIAL carpet; // create object of class MATERIAL
matThk = .296; // specify 'matThk' member of MATERIAL 'carpet'
matCond = 1./24; // give value of 'matCond' for 'carpet'
CONSTRUCTION slab140C; /* create object of class CONSTRUCTION, named
slab140C. Terminates MATERIAL, because
CONSTRUCTION is not a subclass of material
in the hierarchy shown in another section** */
LAYER /* start an unnamed object of class LAYER.
Since LAYER is a subclass of CONSTRUCTION,
this will be a subobject of slab140C. */
lrMat = carpet; /* member of the LAYER. Note use of name of
MATERIAL object. */
// (additional layers would be here)
METER Elec; /* create METER named Elec;
since METER is a subobject of Top,
this ends slab140C and its LAYER. */
ZONE North; // start a ZONE named North. Ends METER.
znArea = 1000; // specify data members of ZONE North.
znVol = 10; // (you don't have to capitalize these as shown.)
GAIN NorthLights /* create GAIN object named NorthLights.
Creates a subobject of ZONE North. */
gnPower = 0.01; // member of NorthLights -- numeric value
gnMeter = Elec; // member of NorthLights -- object name value
znCAir = 3.5; /* processor knows that znCAir is a member of ZONE;
thus this statement terminates the GAIN
subobject & continues ZONE 'North'. */
/*lrMat = ... would be an error here, because the current
object is not a LAYER nor a subobject of LAYER */
RUN; /* initiate simulation run with data given.
Terminates ZONE North, since action-commands
terminate all objects being constructed. */
** See Form of the CSE Data
3.3.3 Expressions – Overview
Expressions are the parts of statements that specify values – numeric values, string values, object name values, and choice values. Expressions are composed of operators and operands, in a manner similar to many programming languages. The available operators and operands will be described in the section on operators.
Unlike most programming languages, CSE expressions have Variation. Variation is how often a value changes during the simulation run – hourly, daily, monthly, yearly (i.e. does not change during run), etc. For instance, the operand $hour
represents the hour of the day and has “hourly” variation. An expression has the variation of its fastest-varying component.
Each data member of each object (and every context in which an expression may be used) has its allowed variability, which is the fastest variation it will accept. Many members allow no variability. For example, begDay
, the date on which the run starts, cannot meaningfully change during the run. On the other hand, a thermostat setting can change hourly. Thermostat settings and other scheduled values are specified in CSE with expressions that often make use of variability; there is no explicit SCHEDULE class.
For example, a heating setpoint that was 68 during business hours and 55 at night might be expressed as
select( $hour > 8 && $hour < 18, 68, default 55)
An example of a complete statement containing the above expression is:
tuTH = select( $hour > 8 && $hour < 18, 68, default 55);
The preceding is valid a statement if used in a TERMINAL description. The following:
begDay = select( $hour > 8 && $hour < 18, 68, default 55);
would always get an error message, because begDay
(the starting day of the run) will not accept hourly variation, and the expression varies hourly, since it contains $hour
. The expression’s variation is considered “hourly” even though it changes only twice a day, since CSE has no variation category between hourly and daily.
CSE’s expression capability may be used freely to make input clearer. For example,
znVol = 15 * 25 * 8;
meaning that the zone volume is 15 times 25 times 8 is the same to CSE as
znVol = 3000;
but might be useful to you to tersely indicate that the volume resulted from a width of 15, a length of 25, and a height of 8. Further, if you wished to change the ceiling height to 9 feet, the edit would be very simple and CSE would perform the volume calculation for you.
CSE computes expressions only as often as necessary, for maximum simulation speed. For example,
tuTH = 68;
causes 68 to be stored in the heating setpoint once at the start of the run only, even though tuTH will accept expressions with variability up to hourly. Furthermore, constant inner portions of variable expressions are pre-evaluated before the run begins.
CSE statements and expressions do not (yet) have user-settable variables in the usual programming language sense. They do, however, have user-defined functions to facilitate using the same computation several places, and preprocessor macros, to facilitate using the same text several places, specifying parametric values in a separate file, etc.
3.3.4 The Preprocessor – Overview
The preprocessor scans and processes input file text before the language processor sees the text. The preprocessor can include (embed) additional files in the input, include sections of input conditionally, and define and expand macros.
Macros are a mechanism to substitute a specified text for each occurrence of a word (the macro name). For example,
#define ZNWID 20
#define ZNLEN 30
. . .
znArea = ZNWID * ZNLEN;
znVol = ZNWID * ZNLEN * 8;
The first line above says that all following occurrences of “ZNWID” are to be replaced with “20” (or whatever follows ZNWID on the same line). The effect of the above is that the zone width and length are specified only one place; if the single numbers are editing, both the zone area and zone volume change to match.
Macros can be especially powerful when combined with the file inclusion feature; the generic building description could be in one file, and the specific values for multiple runs supplied by another file. By also using conditional compilation, the values-specifying file can select from a range of features available in the building description file.
The preprocessor is similar to that of the C programming language, and thus will be familiar to C programmers.
The next section describes the preprocessor in detail. The preprocessor description is followed by sections detailing statements, then expressions.
3.4 The Preprocessor
Note: The organization and wording of this section is based on section A12 of Kernigan and Richie [1988]. The reader is referred to that source for a somewhat more rigorous presentation but with the caution that the CSE input language preprocessor does not completely comply to ANSI C specifications.
The preprocessor performs macro definition and expansion, file inclusion, and conditional inclusion/exclusion of text. Lines whose first non-whitespace character is #
communicate with the preprocessor and are designated preprocessor directives. Line boundaries are significant to the preprocessor (in contrast to the rest of the input language in which a newline is simply whitespace), although adjacent lines can be spliced with \, as discussed below. The syntax of preprocessor directives is separate from that of the rest of the language. Preprocessor directives can appear anywhere in an input file and their effects last until the end of the input file. The directives that are supported by the input language preprocessor are the following:
#if
#else
#elif
#endif
#ifndef
#define
#redefine
#undef
#include
3.4.1 Line splicing
If the last character on a line is the backslash \, then the next line is spliced to that line by elimination of the backslash and the following newline. Line splicing occurs before the line is divided into tokens.
Line splicing finds its main use in defining long macros:
// hourly light gain values:
#define LIGHT_GAIN .024, .022, .021, .021, .021, .026, \
.038, .059, .056, .060, .059, .046, \
.045, .5 , .5 , .05 , .057, .064, \
.064, .052, .050, .055, .044, .027
3.4.2 Macro definition and expansion
A directive of the form
#define _identifier_ _token-sequence_
is a macro definition and causes the preprocessor to replace subsequent instances of the identifier with the given token sequence. Note that the token string can be empty (e.g. #define FLAG
).
A line of the form
#define _identifier_( _identifier-list_) _token-sequence_
where there is no space between the identifier and the (, is a macro with parameters given by the identifier list. The expansion of macros with parameters is discussed below.
Macros may also be defined on the CSE command line, making it possible to vary a run without changing the input files at all. As described in the command line section, macros are defined on the CSE command line using the -D
switch in the forms
-D_identifier_
-D_identifier_=_token-sequence_
The first form simply defines the name with no token-sequence; this is convenient for testing with #ifdef
, #ifndef
, or defined()
, as described in the section on conditional inclusion of tex. The second form allows an argument list and token sequence. The entire command line argument must be enclosed in quotes if it contains any spaces.
A macro definition is forgotten when an #undef
directive is encountered:
#undef _identifier_
It is not an error to #undef
an undefined identifier.
A macro may be re-#defined
without a prior #undef
unless the second definition is identical to the first. A combined #undef
/#define
directive is available to handle this common case:
#redefine _identifier_ _token-sequence_
#redefine _identifier_( _identifier-list_) _token-sequence_
When a macro is #redefined
, it need not agree in form with the prior definition (that is, one can have parameters even if the other does not). It is not an error to #redefine
an undefined identifier.
Macros defined in the second form (with parameters) are expanded whenever the preprocessor encounters the macro identifier followed by optional whitespace and a comma-separated parameter list enclosed in parentheses. First the comma separated token sequences are collected; any commas within quotes or nested parentheses do not separate parameters. Then each unquoted instance of the each parameter identifier in the macro definition is replaced by the collected tokens. The resulting string is then repeatedly re-scanned for more defined identifiers. The macro definition and reference must have the same number of arguments.
It is often important to include parentheses within macro definitions to make sure they evaluate properly in all situations. Suppose we define a handy area macro as follows:
#define AREA(w, h) w*h // WRONG
Consider what happens when this macro is expanded with arguments 2+3 and 4+1. The preprocessor substitutes the arguments for the parameters, then the input language processor processes the statement containing the macro expansion without regard to the beginning and end of the arguments. The expected result is 25, but as defined, the macro will produce a result of 15. Parentheses fix it:
#define AREA(w, h) ((w)*(h)) // RIGHT
The outer enclosing set of parentheses are not strictly needed in our example, but are good practice to avoid evaluation errors when the macro expands within a larger expression.
Note 1: The CSE preprocessor does not support the ANSI C stringizing (#) or concatenation (##) operators.
Note 2: Identifiers are case insensitive (unlike ANSI C). For example, the text “myHeight” will be replaced by the #defined
value of MYHEIGHT (if there is one).
The preprocessor examples at the end of this section illustrate macro definition and expansion.
3.4.3 File inclusion
Directives of the form
#include "filename"
and
#include <filename>
cause the replacement of the directive line with the entire contents of the referenced file. If the filename does not include an extension, a default extension of .INP is assumed. The filename may include path information; if it does not, the file must be in the current directory.
#include
s may be nested to a depth of 5.
For an example of the use #include
s, please see the preprocessor examples at the end of this section.
3.4.4 Conditional inclusion of text
Conditional text inclusion provides a facility for selectively including or excluding groups of input file lines. The lines so included or excluded may be either CSE input language text or other preprocessor directives. The latter capability is very powerful.
Several conditional inclusion directive involve integer constant expressions. Constant integer expressions are formed according the rules discussed in the section on expressions with the following changes:
Only constant integer operands are allowed.
All values (including intermediate values computed during expression evaluation) must remain in the 16 bit range (-32768 - 32767). The expression processor treats all integers as signed values and requires signed decimal constants – however, it requires unsigned octal and hexadecimal constants. Thus decimal constants must be in the range -32768 - 32767, octal must be in the range 0 - 0o177777, and hexadecimal in the range 0 - 0xffff. Since all arithmetic comparisons are done assuming signed values, 0xffff < 1 is true (unhappily). Care is required when using the arithmetic comparison operators (<, <=, >=, >).
The logical relational operators && and || are not available. Nearly equivalent function can be obtained with & and |.
A special operand defined( ) is provided; it is described below.
Macro expansion is performed on constant expression text, so symbolic expressions can be used (see examples below).
The basic conditional format uses the directive
#if _constant-expression_
If the constant expression has the value 0, all lines following the #if
are dropped from the input stream (the preprocessor discards them) until a matching #else
, #elif
, or #endif
directive is encountered.
The defined( identifier ) operand returns 1 if the identifier is the name of a defined macro, otherwise 0. Thus
#if defined( _identifier_ )
can be used to control text inclusion based on macro flags. Two #if
variants that test whether a macro is defined are also available. #ifdef
identifier is equivalent to #if
defined(identifier) and #ifndef
identifier is equivalent to #if
!defined(identifier).
Defined(), #ifdef
, and #ifndef
consider a macro name “defined” even if the body of its definition contains no characters; thus a macro to be tested with one of these can be defined with just
#define _identifier_
or with just “-Didentifier” on the CSE command line.
Conditional blocks are most simply terminated with #endif
, but #else
and #elif
constant-expression are also available for selecting one of two or more alternative text blocks.
The simplest use of #if
is to “turn off” sections of an input file without editing them out:
#if 0
This text is deleted from the input stream.
#endif
Or, portions of the input file can be conditionally selected:
#define FLRAREA 1000 // other values used in other runs
#if FLRAREA <= 800
CSE input language for small zones
#elif FLRAREA <= 1500
CSE input language for medium zones
#else
CSE input language for large zones
#endif
Note that if a set of #if
… #elif
… #elif
conditionals does not contain an #else
, it is possible for all lines to be excluded.
Finally, it is once again important to note that conditional directives nest, as shown in the following example (indentation is included for clarity only):
#if 0
This text is NOT included.
#if 1
This text is NOT included.
#endif
#else
This text IS included.
#endif
3.4.5 Input echo control
By default, CSE echos all input text to the input echo report (see REPORT rpType=INP). #echooff and #echoon allow disabling and re-enabling text echoing. This capability is useful reducing report file size by suppressing echo of, for example, large standard include files.
... some input ... // text sent to the input echo report
#echooff
// This text will NOT be sent to the input echo report.
// However, it IS read and used by CSE.
// Error messages will be echoed even if #echooff
... more input ...
#echoon // restore echo
Nesting is supported – each #echoon “undoes” the prior #echooff, but echoing does not resume until the topmost (earliest) #echooff is cancelled. * #echoon has no effect when echoing is already active. * Unmatched #echooffs are ignored – echoing remains disabled through the end of the input stream.
3.4.6 Preprocessor examples
This section shows a few combined examples that demonstrate the preprocessor’s capabilities.
The simplest use of macros is for run parameterization. For example, a base file is constructed that derives values from a macro named FLRAREA. Then multiple runs can be performed using #include
:
// Base file
... various input language statements ...
ZONE main
znArea = FLRAREA
znVol = 8*FLRAREA
znCAir = 2*FLRAREA ...
... various other input language statements ...
RUN
CLEAR
The actual input file would look like this:
// Run with zone area = 500, 1000, and 2000 ft2
#define FLRAREA 500
#include "base."
#redefine FLRAREA 1000
#include "base."
#redefine FLRAREA 2000
#include "base."
Macros are also useful for encapsulating standard calculations. For example, most U-values must be entered without surface conductances, yet many tabulated U-values include the effects of the standard ASHRAE winter surface conductance of 6.00 Btuh/ft2-oF. A simple macro is very helpful:
#define UWinter(u) ( 1/(1/(u)-1/6.00) )
This macro can be used whenever a U-value is required (e.g. SURFACE … sfU=UWinter(.11) … ).
3.5 CSE Input Language Statements
This section describes the general form of CSE input language statements that define objects, assign values to the data members of objects, and initiate actions. The concepts of objects and the class hierarchy were introduced in the section on form of CSE data. Information on statements for specific CSE input language classes and their members is the subject of the input data section.
3.5.1 Object Statements
As we described in a previous section, the description of an object is introduced by a statement containing at least the class name, and usually your chosen name for the particular object. In addition, this section will describe several optional qualifiers and modifying clauses that permit defining similar objects without repeating all of the member details, and reopening a previously given object description to change or add to it.
Examples of the basic object-beginning statement:
ZONE "North";
METER "Electric - Cooling";
LAYER;
As described in the section on nested objects, such a statement is followed by statements giving the object’s member values or describing subobjects of the object. The object description ends when you begin another object that is not of a subclass of the object, or when a member of an embedding (higher level) object previously begun is given, or when END is given.
3.5.1.1 Object Names
An object name consists of up to 63 characters. If you always enclose the name in quotation marks, punctuation and spaces may be used freely; if the name starts with a letter or dollar sign and consists only of letters, digits, underscore, and dollar sign, and is different from all of the words already defined in CSE input language (as listed below in this section), you may omit the quotes. Capitalization, and Leading and trailing spaces and tabs, are always disregarded by input language processor. Names of 0 length, and names containing control characters (ASCII codes 0-31) are not allowed.
Examples of valid names that do not require quotes:
North
gas_meter
slab140E
The following object names are acceptable if always enclosed in quotes:
"Front Door"
"M L King Day"
"123"
"3.5-inch wall"
We suggest always quoting object names so you won’t have to worry about disallowed words and characters.
Duplicate names result in error messages. Object names must be distinct between objects of the same class which are subobjects of the same object. For example, all ZONE names must be distinct, since all ZONEs are subobjects of Top. It is permissible to have SURFACEs with the same name in different ZONEs – but it is a good idea to keep all of your object names distinct to minimize the chance of an accidental mismatch or a confusing message regarding some other error.
For some classes, such as ZONE, a name is required for each object. This is because several other statements refer to specific ZONEs, and because a name is needed to identify ZONEs in reports. For other classes, the name is optional. The specific statement descriptions in the Input Data Section 5 say which names are required. We suggest always using object names even where not required; one reason is because they allow CSE to issue clearer error messages.
The following reserved words will not work as object names unless enclosed in quotes:
(this list needs to be assembled and typed in)
3.5.1.2 ALTER
ALTER is used to reopen a previously defined object when it is not possible or desired to give the entire description contiguously.
ALTER could be used if you wish to order the input in a special way. For example, SURFACE objects are subobjects of ZONE and are normally described with the ZONE they are part of. However, if you wanted to put all roofs together, you could use input of the general form:
ZONE "1"; . . . (zone 1 description)
ZONE "2"; . . .
. . .
ALTER ZONE "1"; // revert to specifying zone 1
SURFACE "Roof1"; . . . (describe roof of zone 1)
ALTER ZONE "2";
SURFACE "Roof2"; . . .
ALTER can be used to facilitate making similar runs. For example, to evaluate the effect of a change in the size of a window, you might use:
ZONE "South";
SURFACE "SouthWall";
...
WINDOW "BigWindow";
wnHeight = 6; wnWidth = 20;
. . .
RUN; // perform simulation and generate reports
// data from simulation is still present unless CLEAR given
ALTER ZONE "South";
ALTER SURFACE "SouthWall";
ALTER WINDOW "BigWindow";
wnHeight = 4; wnWidth = 12; // make window smaller
RUN; // perform simulation and print reports again
ALTER also lets you access the predefined “Primary” REPORTFILE and EXPORTFILE objects which will be described in the Input Data Section:
ALTER REPORTFILE "Primary"; /* open description of object automatically
supplied by CSE -- no other way to access */
rfPageFmt = NO; /* Turn off page headers and footers --
not desired when reports are to be
reviewed on screen. */
3.5.1.3 DELETE
DELETE followed by a class name and an object name removes the specified object, and any subobjects it has. You might do this after RUN when changing the data for a similar run (but to remove all data, CLEAR is handier), or you might use DELETE after COPYing (below) an object if the intent is to copy all but certain subobjects.
3.5.1.4 LIKE clause
LIKE lets you specify that an object being defined starts with the same member values as another object already defined. You then need give only those members that are different. For Example:
MATERIAL "SheetRock"; // half inch gypsum board
matCond = .0925; // conductivity per foot
matSpHt = .26; // specific heat
matDens = 50; // density
matThk = 0'0.5; // thickness 1/2 inch
MATERIAL "5/8 SheetRock" LIKE "SheetRock"; // 5/8" gypsum board
matThk = 0'0.625; // thickness 5/8 inch
// other members same as "SheetRock", need not be repeated
The object named after LIKE must be already defined and must be of the same class as the new object.
LIKE copies only the member values; it does not copy any subobjects of the prototype object. For example, LIKEing a ZONE to a previously defined ZONE does not cause the new zone to contain the surfaces of the prototype ZONE. If you want to duplicate the surfaces, use COPY instead of LIKE.
3.5.1.5 COPY clause
COPY lets you specify that the object being defined is the same as a previously defined object including all of the subobjects of that object. For example,
. . .
ZONE "West" COPY "North";
DELETE WALL "East";
ALTER WALL "South";
sfExCnd = ambient;
Specifies a ZONE named “West” which is the same as ZONE North except that it does not contain a copy of West’s East wall, and the South wall has ambient exposure.
3.5.1.6 USETYPE clause
USETYPE followed by the type name is used in creating an object of a type previously defined with DEFTYPE (next section). Example:
SURFACE "EastWall" USETYPE "IntWall"; // use interior wall TYPE (below)
sfAzm = 90; // this wall faces to the East
sfArea = 8 * 30; // area of each wall is different
sfAdjZn = "East"; // zone on other side of wall
Any differences from the type, and any required information not given in the type, must then be specified. Any member specified in the type may be respecified in the object unless FROZEN (see this section) in the type (normally, a duplicate specification for a member results in an error message).
3.5.1.7 DEFTYPE
DEFTYPE is used to begin defining a TYPE for a class. When a TYPE is created, no object is created; rather, a partial or complete object description is stored for later use with DEFTYPE. TYPES facilitate creating multiple similar objects, as well as storing commonly used descriptions in a file to be #included in several different files, or to be altered for multiple runs in comparative studies without changing the including files. Example (boldface for emphasis only):
DEFTYPE SURFACE "BaseWall" // common characteristics of all walls
sfType = WALL; // walls are walls, so say it once
sfTilt = 90; // all our walls are vertical;
// but sfAzm varies, so it is not in TYPE.
sfU = .83; // surf conductance; override if different
sfModel = QUICK;
DEFTYPE SURFACE "ExtWall" USETYPE "BaseWall";
sfExCnd = AMBIENT; // other side of wall is outdoors
sfExAbs = 0.5; // member only needed for exterior walls
DEFTYPE SURFACE "IntWall" USETYPE "BaseWall"; // interior wall
sfExCnd = ADJZN; // user must give sfAdjZn.
In a TYPE as much or as little of the description as desired may be given. Omitting normally-required members does not result in an error message in the type definition, though of course an error will occur at use if the member is not given there.
At use, member values specified in the TYPE can normally be re specified freely; to prevent this, “freeze” the desired member(s) in the type definition with
FREEZE *memberName*;
Alternately, if you wish to be sure the user of the TYPE enters a particular member even if it is normally optional, use
REQUIRE *memberName*
Sometimes in the TYPE definition, member(s) that you do not want defined are defined – for example, if the TYPE definition were itself initiated with a statement containing LIKE, COPY, or USETYPE. In such cases the member specification can be removed with
UNSET *memberName*;
3.5.1.8 END and ENDxxxx
END, optionally followed by an object name, can be used to unequivocally terminate an object. Further, as of July 1992 there is still available a specific word to terminate each type of object, such as ENDZONE to terminate a ZONE object. If the object name is given after END or ENDxxxx, an additional check is performed: if the name is not that of an object which has been begun and not terminated, an error message occurs. Generally, we have found it is not important to use END or ENDxxxx, especially since the member names in different classes are distinct.
3.5.2 Member Statements
As introduced in the section on statements, statements which assign values to members are of the general form:
*memberName* = *expression*;
The specific member names for each class of objects are given in Section 5; many have already been shown in examples.
Depending on the member, the appropriate type for the expression giving the member value may be numeric (integer or floating point), string, object name, or multiple-choice. Expressions of all types will be described in detail in the section on expressions.
Each member also has its variability (also given in the input data section), or maximum acceptable variation. This is how often the expression for the value can change during the simulation – hourly, daily, monthly, no change (constant), etc. The “variations” were introduced in the expressions overview section and will be further detailed in a section on variation frequencies.
Four special statements, AUTOSIZE, UNSET, REQUIRE, and FREEZE, add flexibility in working with members.
3.5.2.1 AUTOSIZE
AUTOSIZE followed by a member name, sets the member to be sized by CSE. The option to AUTOSIZE a member will be shown under its legal range where it is described in the input data section. AUTOSIZE is only applicable to members describing HVAC system airflows and heating/cooling capacities. If AUTOSIZE is used for any member in the input, input describing design day conditions must also be specified (see TOP Autosizing).
3.5.2.2 UNSET
UNSET followed by a member name is used when it is desired to delete a member value previously given. UNSETing a member resets the object to the same internal state it was in before the member was originally given. This makes it legal to specify a new value for the member (normally, a duplicate specification results in an error message); if the member is required (as specified in the input data section), then an error message will occur if RUN is given without re specifying the member.
Situations where you really might want to specify a member, then later remove it, include:
After a RUN command has completed one simulation run, if you wish to specify another simulation run without CLEARing and giving all the data again, you may need to UNSET some members of some objects in order to re specify them or because they need to be omitted from the new run. In this case, use ALTER(s) to reopen the object(s) before UNSETing.
In defining a TYPE (see this section), you may wish to make sure certain members are not specified so that the user must give them or omit them if desired. If the origin of the type (possibly a sequence of DEFTYPEs, LIKEs, and/or COPYs) has defined unwanted members, get rid of them with UNSET.
Note that UNSET is only for deleting members (names that would be followed with an = and a a value when being defined). To delete an entire object, use DELETE (see this section).
3.5.2.3 REQUIRE
REQUIRE followed by a member name makes entry of that member mandatory if it was otherwise optional; it is useful in defining a TYPE (see this section) when you desire to make sure the user enters a particular member, for example to be sure the TYPE is applied in the intended manner. REQUIRE by itself does not delete any previously entered value, so if the member already has a value, you will need to UNSET it. ?? verify
3.5.2.4 FREEZE
FREEZE followed by a member name makes it illegal to UNSET or redefine that member of the object. Note that FREEZE is unnecessary most of the time since CSE issues an error message for duplicate definitions without an intervening UNSET, unless the original definition came from a TYPE (see this section). Situations where you might want to FREEZE one or more members include:
When defining a TYPE (see this section). Normally, the member values in a type are like defaults; they can be freely overridden by member specifications at each use. If you wish to insure a TYPE is used as intended, you may wish to FREEZE members to prevent accidental misuse.
When your are defining objects for later use or for somebody else to use (perhaps in a file to be included) and you wish to guard against misuse, you may wish to FREEZE members. Of course, this is not foolproof, since there is at present no way to allow use of predefined objects or types without allowing access to the statements defining them.
3.5.3 Action Commands
CSE has two action commands, RUN and CLEAR.
3.5.3.1 RUN
RUN tells CSE
to do an hourly simulation with the data now in memory, that is, the data given in the preceding part of the input file.
Note that CSE does NOT automatically run the simulator; an input file containing no RUN results in no simulation (you might nevertheless wish to submit an incomplete file to CSE to check for errors in the data already entered). The explicit RUN command also makes it possible to do multiple simulation runs in one session using a single input file.
When RUN is encountered in the input file, CSE checks the data. Many error messages involving inconsistencies between member values or missing required members occur at this time. If the data is good, CSE starts the simulation. When the simulation is complete and the reports have been output, CSE continues reading the input file. Statements after the first run can add to or change the data in preparation for another RUN. Note that the data for the first run is NOT automatically removed; if you wish to start over with complete specifications, use CLEAR after RUN.
3.5.3.2 CLEAR
CLEAR removes all input data (objects and all their members) from CSE memory. CLEAR is normally used after RUN, when you wish to perform another simulation run and wish to start clean. If CLEAR is not used, the objects from the prior run’s input remain in memory and may be changed or added to produce the input data for the next simulation run.
3.6 Expressions
Probably the CSE input language’s most powerful characteristic is its ability to accept expressions anywhere a single number, string, object name, or other value would be accepted. Preceding examples have shown the inputting zone areas and volumes as numbers (some defined via preprocessor macros) with *’s between them to signify multiplication, to facilitate changes and avoid errors that might occur in manual arithmetic. Such expressions, where all operands are constants, are acceptable anywhere a constant of the same type would be allowed.
But for many object members, CSE accepts live expressions that vary according to time of day, weather, zone temperatures, etc. (etc., etc., etc.!). Live expressions permit simulation of many relationships without special-purpose features in the language. Live expressions support controlling setpoints, scheduling HVAC system operation, resetting air handler supply temperature according to outdoor temperature, and other necessary and foreseen functions without dedicated language features; they will also support many unforeseen user-generated functionalities that would otherwise be unavailable.
Additional expression flexibility is provided by the ability to access all of the input data and much of the internal data as operands in expressions (probes, see this section).
As in a programming language, CSE expressions are constructed from operators and operands; unlike most programming languages, CSE determines how often an expression’s operands change and automatically compute and store the value as often as necessary.
Expressions in which all operands are known when the statement is being decoded (for example, if all values are constants) are always allowed, because the input language processor immediately evaluates them and presents the value to the rest of the program in the same manner as if a single number had been entered. Most members also accept expressions that can be evaluated as soon as the run’s input is complete, for example expressions involving a reference to another member that has not been given yet. Expressions that vary during the run, say at hourly or daily intervals, are accepted by many members. The variability or maximum acceptable variation for each member is given in the descriptions in the input data section, and the variation of each non-constant expression component is given in its description in this section.
Interaction of expressions and the preprocessor: Generally, they don’t interact. The preprocessor is a text processor which completes its work by including specified files, deleting sections under false #if’s, remembering define definitions, replacing macro calls with the text of the definition, removing preprocessor directives from the text after interpreting them, etc., then the resulting character stream is analyzed by the input language statement compiler. However, the if statement takes an integer numeric expression argument. This expression is similar to those described here except that it can only use constant operands, since the preprocessor must evaluate it before deciding what text to feed to the input statement statement compiler.
3.6.1 Expression Types
The type of value to which an expression must evaluate is specified in each member description (see the input data section) or other context in which an expression can be used. Each expression may be a single constant or may be made up of operators and operands described in the rest of this section, so long as the result is the required type or can be converted to that type by CSE, and its variation is not too great for the context. The possible types are:
float | A real number (3.0, 5.34, -2., etc.). Approximately 7 digits are carried internally. If an int is given where a real is required, it is automatically converted. |
int | An integer or whole number (-1, 0, 1, 2 etc.). If a real is given, an error may result, but we should change it to convert it (discarding any fractional part). |
Boolean | Same as int; indicates that a 0 value will be interpreted as “false” and any non-0 value will be interpreted as “true”. |
string | A string of characters; for example, some text enclosed in quotes. |
object name | Name of an object of a specified class. Differs from string in that the name need not be enclosed in quotes if it consists only of letters, digits, _, and $, begins with a non-digit, and is different from all reserved words now in or later added to the language (see Object Names). |
The object may be defined after it is referred to. An expression using conditional operators, functions, etc. may be used provided its value is known when the RUN action command is reached.; no members requiring object names accept values that vary during the simulation. | |
choice | One of several choices; a list of the acceptable values is given wherever a choice is required. The choices are usually listed in CAPITALS but may be entered in upper or lower case as desired. As with object names, quotes are allowed but not required. |
Expressions may be used for choices, subject to the variability of the context. | |
date | May be entered as a 3-letter month abbreviation followed by an int for the day of the month, or an int for the Julian day of the year (February is assumed to have 28 days). Expressions may be used subject to variability limitations. Examples: |
Jan 23 // January 23 | |
23 // January 23 | |
32 // February 1 |
These words are used in following descriptions of contexts that can accept more than one basic type:
numeric | float or int. When floats and ints are intermixed with the same operator or function, the result is float. |
anyType | Any type; the result is the same type as the argument. If floats and ints are intermixed, the result is float. If strings and valid choice names are intermixed, the result is choice. Other mixtures of types are generally illegal, except in expressions for a few members that will accept either one of several choices or a numeric value. |
The next section describes the syntax of constants of the various data types; then, we will describe the available operators, then other operand types such as system variables and built-in functions.
3.6.2 Constants
This section reviews how to enter ordinary non-varying numbers and other values.
int | optional - sign followed by digits. Don’t use a decimal point if your intent is to give an int quantity – the decimal point indicates a float to CSE. Hexadecimal and Octal values may be given by prefixing the value with 0x and 0O respectively (yes, that really is a zero followed by an ‘O’). |
float | optional - sign, digits and decimal point. Very large or small values can be entered by following the number with an “e” and a power of ten. Examples; |
1.0 1. .1 -5534.6 123.e25 4.56e-23 | |
The decimal point indicates a float as opposed to an int. Generally it doesn’t matter as CSE converts ints to floats as required, but be careful when dividing: CSE interprets “2/3” as integer two divided by integer 3, which will produce an integer 0 before CSE notices any need to convert to float. If you mean .6666667, say 2./3, 2/3., or .6666667. | |
feet and inches | Feet and inches may be entered where a float number of feet is required by typing the feet (or a 0 if none), a single quote ’, then the inches. (Actually this is an operator meaning “divide the following value by 12 and add it to the preceding value”, so expressions can work with it.) Examples: |
3'6 0'.5 (10+20)'(2+3) | |
string | “Text” – desired characters enclosed in double quotes. Maximum length 80 characters (make 132??). To put a " within the “’s, precede it with a backslash. Certain control codes can be represented with letters preceded with a backslash as follows: |
\\e escape | |
\\t tab | |
\\f form feed | |
\\r carriage return | |
\\n newline or line feed | |
object name | Same as string, or without quotes if name consists only of letters, digits, _, and $, begins with a non-digit, and is different from all reserved words now in or later added to the language (see Object Names). Control character codes (ASCII 0-31) are not allowed. |
choice | Same as string; quotes optional on choice words valid for the member. Capitalization does not matter. |
date | Julian day of year (as int constant), or month abbreviation |
Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov De c | |
followed by the int day of month. (Actually, the month names are operators implemented to add the starting day of the month to the following int quantity). |
3.6.3 Operators
For floats and ints, the CSE input language recognizes a set of operators based closely on those found in the C programming language. The following table describes the available numeric operators. The operators are shown in the order of execution (precedence) when no ()’s are used to control the order of evaluation; thin lines separate operators of equal precedence.
Operator | Name | Notes and Examples |
---|---|---|
’ | Feet-Inches Separator | a ’ b yields a + b/12; thus 4’6 = 4.5. |
+ | Unary plus | The familiar “positive”, as in +3. Does nothing; rarely used. |
- | Unary minus | The familiar “minus”, as in -3. -(-3) = +3 etc. |
! | Logical NOT | Changes 0 to 1 and any non-0 value to 0. !0 = 1, !17 = 0. |
~ | One’s complement | Complements each bit in an int value. |
* | Multiplication | Multiplication, e.g. 3*4 = 12; 3.24*18.54 = 60.07 |
/ | Division | Division, e.g. 4/2 = 2, 3.24/1.42 = 2.28. Integer division truncates toward 0 (e.g. 3/2 = 1, 3/-2 = -1, -3/2 = -1, 2/3 = 0) CAUTION! |
% | Modulus | Yields the remainder after division, e.g. 7%2 = 1. The result has the same sign as the left operand (e.g.(-7)%2 = -1). % is defined for both integer and floating point operands (unlike ANSI C). |
+ | Addition | Yields the sum of the operands, e.g. 5+3 = 8 |
- | Subtraction | Yields the difference of the operands, e.g. 5-3 = 2 |
>> | Right shift | a >> b yields a shifted right b bit positions, e.g. 8>>2 = 2 |
<< | Left shift | a << b yields a shifted left b bit positions, e.g. 8<<2 = 32 |
< | Less than | a < b yields 1 if a is less than b, otherwise 0 |
<= | Less than or equal | a <= b yields 1 if a is less than or equal to b, otherwise 0 |
>= | Greater than or equal | a >= b yields 1 if a is greater than or equal to b, otherwise 0 |
> | Greater than | a > b yields 1 if a is greater than b, otherwise 0 |
== | Equal | a == b yields 1 if a is exactly (bit wise) equal to b, otherwise 0 |
!= | Not equal | a != b yields 1 if a is not equal to b, otherwise 0 |
& | Bitwise and | a & b yields the bitwise AND of the operands, e.g. 6 & 2 = 2. |
^ | Bitwise exclusive or | a ^ b yields the bitwise XOR of the operands, e.g. 6 ^ 2 = 4. |
| | Bitwise inclusive or | a | b yields the bitwise IOR of the operands, e.g. 6 | 2 = 6. |
&& | Logical AND | a && b yields 1 if both a and b are non-zero, otherwise 0. && guarantees left to right evaluation: if the first operand evaluates to 0, the second operand is not evaluated and the result is 0. |
|| | Logical OR | a || b yields 1 if either a or b is true (non-0), otherwise 0. || guarantees left to right evaluation: if the first operand evaluates to non-zero, the second operand in not evaluated and the result is 1. |
? : | Conditional | a ? b : c yields b if a is true (non-0), otherwise c. |
Dates are stored as ints (the value being the Julian day of the year), so all numeric operators could be used. The month abbreviations are implemented as operators that add the first day of the month to the following int value; CSE does not disallow their use in other numeric contexts.
For strings, object names, and choices, the CSE input language currently has no operators except the ?: conditional operator. A concatenation operator is being considered. Note, though, that the choose, choose1, select, and hourval functions described below work with strings, object names, and choice values as well as numbers.
3.6.4 System Variables
System Variables are built-in operands with useful values. To avoid confusion with other words, they begin with a $. Descriptions of the CSE system variables follow. Capitalization shown need not be matched. Most system variables change during a simulation run, resulting in the variations shown; they cannot be used where the context will not accept variation at least this fast. (The Input Data Section gives the variability, or maximum acceptable variation, for each object member.)
$dayOfYear | Day of year of simulation, 1 - 365; 1 corresponds to Jan-1. (Note that this is not the day of the simulation unless begDay is Jan-1.) Variation: daily. |
$month | Month of year, 1 - 12. Variation: monthly. |
$dayOfMonth | Day of month, 1 - 31. Variation: daily. |
$hour | Hour of day, 1 - 24, in local time; 1 corresponds to midnight - 1 AM. Variation: hourly. |
$hourST | Hour of day, 1 - 24, in standard time; 1 corresponds to midnight - 1 AM. Variation: hourly. |
$subhour | Subhour of hour, 1 - N (number of subhours). Variation: subhourly. |
$dayOfWeek | Day of week, 1 - 7; 1 corresponds to Sunday, 2 to Monday, etc. Variation: daily. |
$DOWH | Day of week 1-7 except 8 on every observed holiday. Variation: daily. |
$isHoliday | 1 on days that a holiday is observed (regardless of the true date of the holiday); 0 on other days. Variation: daily. |
$isHoliTrue | 1 on days that are the true date of a holiday, otherwise 0. Variation: daily. |
$isWeHol | 1 on weekend days or days that are observed as holidays. Variation: daily. |
$isWeekend | 1 on Saturday and Sunday, 0 on any day from Monday to Friday. Variation: daily. |
$isWeekday | 1 on Monday through Friday, 0 on Saturday and Sunday. Variation: daily. |
$isBegWeek | 1 for any day immediately following a weekend day or observed holiday that is neither a weekend day or an observed holiday. Variation: daily. |
$isWorkDay | 1 on non-holiday Monday through Friday, 0 on holidays, Saturday and Sunday. Variation: daily. |
$isNonWorkDay | 1 on Saturday, Sunday and observed holidays, 0 on non-holiday Monday through Friday. Variation: daily. |
$isBegWorkWeek | 1 on the first workday after a non-workday, 0 all other days. Variation: daily. |
$isDT | 1 if Daylight Saving time is in effect, 0 otherwise. Variation: hourly. |
$autoSizing | 1 during autosizing calculations, 0 during main simulation. Variation: for each phase. |
$dsDay | Design day type, 0 during main simulation, 1 during heating autosize, 2 during cool autosize. Variation: daily. |
Weather variables: the following allow access to the current hour’s weather conditions in you CSE expressions. Units of measure are shown in parentheses. All have Variation: hourly.
$radBeam | Solar beam irradiance (on a sun-tracking surface) this hour (Btu/ft2) |
$radDiff | Solar diffuse irradiance (on horizontal surface) this hour (Btu/ft2) |
$tDbO | Outdoor drybulb temperature this hour (degrees F) |
$tWbO | Outdoor wetbulb temperature this hour (degrees F) |
$wO | Outdoor humidity ratio this hour (lb H2O/lb dry air) |
$windDirDeg | Wind direction (compass degrees) |
$windSpeed | Wind speed (mph) |
3.6.5 Built-in Functions
Built-in functions perform a number of useful scheduling and conditional operations in expressions. Built-in functions have the combined variation of their arguments; for hourval, the minimum result variation is hourly. For definitions of numeric and anyType, see Expression Types.
3.6.5.1 brkt
Function | limits a value to be in a given range |
Syntax | numeric brkt( numeric min, numeric val, numeric max) |
Remark | If val is less than min, returns min; if val is greater than max, returns max; if val is in between, returns val. |
Example | In an AIRHANDLER object, the following statement would specify a supply temperature equal to 130 minus the outdoor air temperature, but not less than 55 nor greater than 80: |
ahTsSp = brkt( 55, 130 - $tDbO, 80); | |
This would produce a 55-degree setpoint in hot weather, an 80-degree setpoint in cold weather, and a transition from 55 to 70 as the outdoor temperature moved from 75 to 50. |
3.6.5.2 fix
Function | converts float to int |
Syntax | int fix( float val ) |
Remark | val is converted to int by truncation – fix( 1.3) and fix( 1.99) both return 1. fix( -4.4) returns -4. |
3.6.5.3 toFloat
Function | converts int to float |
Syntax | float toFloat( int val ) |
3.6.5.4 min
Function | returns the lowest quantity from a list of values. |
Syntax | numeric min( numeric value1, numeric value2, … numeric valuen ) |
Remark | there can be any number of arguments separated by commas; if floats and ints are intermixed, the result is float. |
3.6.5.5 max
Function | returns the highest quantity from a list of values. |
Syntax | numeric max ( numeric value1, numeric value2, … numeric valuen ) |
3.6.5.6 choose
Function | returns the nth value from a list. If arg0 is 0, value0 is returned; for 1, value1 is returned, etc. |
Syntax | anyType choose ( int arg0, anyType value0, anyType value1, … anyType valuen ) or anyType choose ( int arg0, anyType value0, … anyType valuen, default valueDef) |
Remarks | Any number of value arguments may be given. If default and another value is given, this value will be used if arg0 is less than 0 or too large; otherwise, an error will occur. |
3.6.5.7 choose1
Function | same as choose except arg0 is 1-based. Choose1 returns the second argument value1 for arg0 = 1, the third argument value2 when arg0 = 2, etc. |
Syntax | anyType choose1 ( int arg0, anyType value1, anyType value2, … anyType valuen ) or anyType choose1 ( int arg0, anyType value1, … anyType valuen, default valueDef) |
Remarks | choose1 is a function that is well suited for use with daily system variables. For example, if a user wanted to denote different values for different days of the week, the following use of choose1 could be implemented: |
tuTC = choose1(\$dayOfWeek, MonTemp, TueTemp, ...) | |
Note that for hourly data, the hourval function would be a better choice, because it doesn’t require the explicit declaration of the $hour system variable. |
3.6.5.8 select
Function | contains Boolean-value pairs; returns the value associated with the first Boolean that evaluates to true (non-0). |
Syntax | anyType ( Boolean arg1, anyType value1, Boolean arg2, anyType value2, … default anyType) (the default part is optional) |
Remark | select is a function that simulates if-then logic during simulation (for people familiar with C, it works much like a series of imbedded conditionals: (a?b:(a?b:c)) ). |
Examples | Select can be used to simulate a dynamic (run-time) if-else statement: |
gnPower = select( $isHoliday, HD_GAIN, // if ($isHolid a y) | |
default WD_GAIN) // else | |
This technique can be combined with other functions to schedule items on a hourly and daily basis. For example, an internal gain that has different schedules for holidays, weekdays, and weekends could be defined as follows: | |
// 24-hour lighting power schedules for weekend, weekda y , holiday: | |
#define WE_LIGHT hourval( .024, .022, .021, .021, .021 , . 026, \ | |
.038, .059, .056, .060, .059, .046, \ | |
.045, .005, .005, .005, .057, .064, \ | |
.064, .052, .050, .055, .044, .027 ) | |
#define WD_LIGHT hourval( .024, .022, .021, .021, .021 , . 026, \ | |
.038, .059, .056, .060, .059, .046, \ | |
.045, .005, .005, .005, .057, .064, \ | |
.064, .052, .050, .055, .044, .027 ) | |
#define HD_LIGHT hourval( .024, .022, .021, .021, .021 , . 026, \ | |
.038, .059, .056, .060, .059, .046, \ | |
.045, .005, .500, .005, .057, .064, \ | |
.064, .052, .050, .055, .044, .027 ) | |
// set power member of zone's GAIN object for lighting | |
gnPower = BTU_Elec( ZAREA*0.1 ) * // .1 kW/ft2 ti mes... | |
select( $isHoliday, HD_LIGHT, // Holidays | |
$isWeekend, WE_LIGHT, // Saturday & Sunday | |
default WD_LIGHT ); // Week Days | |
In the above, three subexpressions using hourval (next) are first defined as macros, for ease of reading and later change. Then, gnPower (the power member of a GAIN object) is set, using select to choose the appropriate one of the three hourval calls for the type of day. The expression for gnPower is a live expression with hourly variation, that is, CSE will evaluate it an set gnPower to the latest value each hour of the simulation. The variation comes from hourval, which varies hourly (also, $isHoliday and $isWeekend vary daily, but the faster variation determines the variation of the result). |
3.6.5.9 hourval
Function | from a list of 24 values, returns the value corresponding to the hour of day. |
Syntax | anyType hourval ( anyType value1, anyType value2, … anyType value24 ) |
anyType hourval ( anyType value1, anyType value2, … default anyType) | |
Remark | hourval is evaluated at runtime and uses the hour of the day being simulated to choose the corresponding value from the 24 suppplied values. |
If less than 24 value arguments are given, default and another value (or expression) should be supplied to be used for hours not explicitly specified. | |
Example | see select, just above. |
3.6.5.10 abs
Function | converts numeric to its absolute value |
Syntax | numeric abs( numeric val) |
3.6.5.11 sqrt
Function | Calculates and returns the positive square root of val ( val must be \(\geq\) 0). |
Syntax | float sqrt ( float val) |
3.6.5.12 exp
Function | Calculates and returns the exponential of val (= eval) |
Syntax | float exp( float val) |
3.6.5.13 logE
Function | Calculates and returns the base e logarithm of val ( val must be \(\geq\) 0). |
Syntax | float logE( float val) |
3.6.5.14 log10
Function | Calculates and returns the base 10 logarithm of val ( val must be \(\geq\) 0). |
Syntax | float log10( float val) |
3.6.5.15 sin
Function | Calculates and returns the sine of val (val in radians) |
Syntax | float sin( float val) |
3.6.5.16 sind
Function | Calculates and returns the sine of val (val in degrees) |
Syntax | float sind( float val) |
3.6.5.17 asin
Function | Calculates and returns (in radians) the arcsine of val |
Syntax | float asin( float val) |
3.6.5.18 asind
Function | Calculates and returns (in degrees) the arcsine of val |
Syntax | float asind( float val) |
3.6.5.19 cos
Function | Calculates and returns the cosine of val (val in radians) |
Syntax | float cos( float val) |
3.6.5.20 cosd
Function | Calculates and returns the cosine of val (val in degrees) |
Syntax | float cosd( float val) |
3.6.5.21 acos
Function | Calculates and returns (in radians) the arccosine of val |
Syntax | float acos( float val) |
3.6.5.22 acosd
Function | Calculates and returns (in degrees) the arccosine of val |
Syntax | float acosd( float val) |
3.6.5.23 tan
Function | Calculates and returns the tangent of val (val in radians) |
Syntax | float tan( float val) |
3.6.5.24 tand
Function | Calculates and returns the tangent of val (val in degrees) |
Syntax | float tand( float val) |
3.6.5.25 atan
Function | Calculates and returns (in radians) the arctangent of val |
Syntax | float atan( float val) |
3.6.5.26 atand
Function | Calculates and returns (in degrees) the arctangent of val |
Syntax | float atand( float val) |
3.6.5.27 atan2
Function | Calculates and returns (in radians) the arctangent of y/x (handling x = 0) |
Syntax | float atan2( float y, float x) |
3.6.5.28 atan2d
Function | Calculates and returns (in degrees) the arctangent of y/x (handling x = 0) |
Syntax | float atan2d( float y, float x) |
3.6.5.29 pow
Function | Calculates and returns val raised to the xth power (= valx). val and x cannot both be 0. If val < 0, x must be integral. |
Syntax | float pow( float val, numeric x) |
3.6.5.30 enthalpy
Function | Returns enthalpy of moist air (Btu/lb) for dry bulb temperature (F) and humidity ratio (lb/lb) |
Syntax | float enthalpy( float tDb, float w) |
3.6.5.31 wFromDbWb
Function | Returns humidity ratio (lb/lb) of moist air from dry bulb and wet bulb temperatures (F) |
Syntax | float wFromDbWb( float tDb, float tWb) |
3.6.5.32 wFromDbRh
Function | Returns humidity ratio (lb/lb) of moist air from dry bulb temperature (F) and relative humidity (0 – 1) |
Syntax | float wFromDbRh( float tDb, float rh) |
3.6.5.33 rhFromDbW
Function | Returns relative humidity (0 – 1) of moist air from dry bulb temperature (F) and humidity ratio (lb/lb). |
Syntax | float rhFromDbW( float tDb, float w) |
Remark | The return value is constrained to 0 <= rh <= 1 (that is, physically impossible combinations of tDb and w are silently tolerated). |
3.6.5.34 import
Function | Returns float read from an import file. |
Syntax | float import( string importFile, string colName) float import( string importFile, int colN) |
Remark | Columns can be referenced by name or 1-based index. See IMPORTFILE for details on use of import() |
3.6.5.35 importStr
**Functio n | Returns string read from an import file. |
Syntax | string importStr( string importFile, string colName) string importStr( string importFile, int colN) |
Remark | See IMPORTFILE for details on use of importStr() |
3.6.5.36 contin
Function | Returns continuous control value, e.g. for lighting control |
Syntax | float contin( float mpf, float mlf, float sp, float val) |
Remark | contin is evaluated at runtime and returns a value in the range 0 – 1 ??? |
Example | – |
3.6.5.37 stepped
Function | Returns stepped reverse-acting control value, e.g. for lighting control |
Syntax | float stepped( int nsteps, float sp, float val) |
Remark | stepped is evaluated at runtime and returns a value in the range 0 – 1. If val <= 0, 1 is returned; if val >= sp, 0 is returned; otherwise, a stepped intermediate value is returned (see example) |
example:
stepped( 3, 12, val) returns
val | result |
---|---|
val \(<\) 4 | 1 |
4 \(\leq\) val \(<\) 8 | .667 |
8 \(\leq\) val \(<\) 12 | .333 |
val \(\geq\) 12 | 0 |
3.6.6 User-defined Functions
User defined functions have the format:
type FUNCTION name ( arg decls ) = expr ;
Type indicates the type of value the function returns, and can be:
INTEGER
FLOAT
STRING
DOY (day of year date using month name and day; actually same as integer).
Arg decls indicates zero or more comma-separated argument declarations, each consisting of a type (as above) and the name used for the argument in expr.
Expr is an expression of (or convertible to) type.
The tradeoffs between using a user-defined function and a preprocessor macro (#define
) include:
Function may be slightly slower, because its code is always kept separate and called, while the macro expansion is inserted directly in the input text, resulting in inline code.
Function may use less memory, because only one copy of it is stored no matter how many times it is called.
Type checking: the declared types of the function and its arguments allow CSE to perform additional checks.
Note that while macros require line-splicing (“\”)to extend over one line, functions do not require it:
// Function returning number of days in ith month of year:
DOY FUNCTION MonthLU (integer i) = choose1 ( i , Jan 31, Feb 28, Mar 31,
Apr 30, May 31, Jun 30,
Jul 31, Aug 31, Sep 30,
Oct 31, Nov 30, Dec 31 ) ;
// Equivalent preprocessor macro:
#define MonthLU (i) = choose1 ( i , Jan 31, Feb 28, Mar 31, \
Apr 30, May 31, Jun 30, \
Jul 31, Aug 31, Sep 30, \
Oct 31, Nov 30, Dec 31 ) ;
3.6.7 Probes
Probes provide a universal means of referencing data within the simulator. Probes permit using the inputtable members of each object, as described in the Input Data Section, as operands in expressions. In addition, most internal members can be probed; we will describe how to find their names shortly.
Three general ways of using probes are:
- During input, to implement things like “make this window’s width equal to 10% of the zone floor area” by using the zone’s floor area in an expression:
wnWidth = @zone[1].znArea * 0.1;
Here “@zone[1].znArea
” is the probe.
- During simulation. Probing during simulation, to make inputs be functions of conditions in the building or HVAC systems, is limited because most of the members of interest are updated after CSE has evaluated the user’s expressions for the subhour or other time interval – this is logically necessary since the expressions are inputs. (An exception is the weather data, but this is also available through system variables such as $tDbO.)
However, a number of prior subhour values are available for probing, making it possible to implement relationships like “the local heat output of this terminal is 1000 Btuh if the zone temperature last subhour was below 65, else 500”:
tuMnLh = @znres["North"].S.prior.tAir < 65 ? 1000 : 500;
- For output reports, allowing arbitrary data to be reported at subhourly, hourly, daily, monthly, or annual intervals. The REPORT class description describes the user-defined report type (UDT), for which you write the expression for the value to be reported. With probes, you can thus report almost any datum within CSE – not just those values chosen for reporting when the program was designed. Even values calculated during the current subhour simulation can be probed and reported, because expressions for reports are evaluated after the subhour’s calculations are performed.
Examples:
colVal = @airHandler["Hot"].ts; // report air handler supply temp
colVal = @terminal[NorthHot].cz; // terminal air flow to zone (Btuh/F)
The general form of a probe is
@ className [ objName ] . member
The initial @ is always necessary. And don’t miss the period after the ].
className is the CLASS being probed
objName | is the name of the specific object of the class; alternately, a numeric subscript is allowed. Generally, the numbers correspond to the objects in the order created. [ objName ] can be omitted for the TOP class, which has only one member, Top. |
member | is the name of the particular member being probed. This must be exactly correct. For some inputtable members, the probe name is not the same as the input name given in the Input Data Section, and there are many probe-able members not described in the Input Data section. |
How do you find out what the probe-able member names are? CSE will display the a list of the latest class and member names if invoked with the -p switch. Use the command line
CSE -p >probes.txt
to put the displayed information into the file PROBES.TXT, then print the file or examine it with a text editor.
A portion of the -p
output looks like:
@exportCol[1..]. I R owner: export
name I R string constant
colHead I R string input time
colGap I R integer number input time
colWid I R integer number input time
colDec I R integer number input time
colJust I R integer number constant
colVal I R un-probe-able end of each subhour
nxColi I R integer number constant
@holiday[1..]. I
name I string constant
hdDateTrue I integer number constant
hdDateObs I integer number constant
hdOnMonday I integer number constant
In the above “exportCol” and “holiday” are class names, and “name”, “colHead”, “colGap”, . . . are member names for class exportCol. Some members have multiple names separated by .’s, or they may contain an additional subscript. To probe one of these, type all of the names and punctuation exactly as shown (except capitalization may differ); if an additional subscript is shown, give a number in the specified range. An “I” designates an “input” parameter, an R means “runtime” parameter. The “owner” is the class of which this class is a subclass.
The data type and variation of each member is also shown. Note that variation, or how often the member changes, is shown here. (Variability, or how often an expression assigned to the member may change, is given for the input table members in the Input Data Section). Members for which an “end of” variation is shown can be probed only for use in reports. A name described as “un-probe-able” is a structure or something not convertible to an integer, float, or string.
surface[].sgdist[].f[]: f[0] is winter solar coupling fraction; f[1] is summer.
3.6.8 Variation Frequencies Revisited
At risk of beating the topic to death, we’re going to review once more the frequencies with which a CSE value can change (variations), with some comments on the corresponding variabilities.
subhourly | changes in each “subhour” used in simulation. Subhours are commonly 15-minute intervals for models using znModel=CNE or 2-minute intervals for CSE znModels. |
hourly | changes every simulated hour. The simulated weather and many other aspects of the simulation change hourly; it is customary to schedule setpoint changes, HVAC system operation, etc. in whole hours. |
daily | changes at each simulated midnite. |
monthly | changes between simulated months. |
monthly-hourly, or “hourly on first day of each month” | changes once an hour on the first day of each month; the 24 hourly values from the first day of the month are used for the rest of the month. This variation and variability is used for data dependent on the sun’s position, to save calculation time over computing it every hour of every day. |
run start time | value is derived from other inputs before simulation begins, then does not change. |
Members that cannot change during the simulation but which are not needed to derive other values before the simulation begins have “run start time” variability. | |
input time | value is known before CSE starts to check data and derive “run start time” values. |
Expressions with “input time” variation may be used in many members that cannot accept any variation during the run. Many members documented in the Input Data Section as having “constant” variability may actually accept expressions with “input time” variation; to find out, try it: set the member to an expression containing a proposed probe and see if an error message results. | |
“Input time” differs from “constant” in that it includes object names (forward references are allowed, and resolved just before other data checks) and probes that are forward references to constant values. | |
constant | does not vary. But a “constant” member of a class denoted as R (with no I) in the probes report produced by CSE -p is actually not available until run start time. |
Also there are end-of varieties of all of the above; these are values computed during simulation: end of each hour, end of run, etc. Such values may be reported (using a probe in a UDT report), but will produce an error message if probed in an expression for an input member value.
4 Input Data
This section describes the input for each CSE class (object type). For each object you wish to define, the usual input consists of the class name, your name for the particular object (usually), and zero or more member value statements of the form name=expression. The name of each subsection of this section is a class name (HOLIDAY, MATERIAL, CONSTRUCTION, etc.). The object name, if given, follows the class name; it is the first thing in each description (hdName, matName, conName, etc.). Exception: no statement is used to create or begin the predefined top-level object “Top” (of class TOP); its members are given without introduction.
After the object name, each member’s description is introduced with a line of the form name=type. Type indicates the appropriate expression type for the value:
float
int
string
____name (object name for specified type of object)
choice
date
These types discussed in the section on expression types.
Each member’s description continues with a table of the form:
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x > 0 | wnHeight * wnWidth | No | constant |
where the column headers have the following meaning:
Units | units of measure (lb., ft, Btu, etc.) where applicable |
Legal | limits of valid range for numeric inputs; valid choices |
Range | for choice members, etc. |
Default | value assumed if member not given; applicable only if not required |
Required | YES if you must give this member |
Variability | how often the given expression can change: hourly, daily, etc. See sections on expressions, statements, and variation frequencies |
4.1 TOP Members
The top-level data items (TOP members) control the simulation process or contain data that applies to the modeled building as a whole. No statement is used to begin or create the TOP object; these statements can be given anywhere in the input (they do, however, terminate any other objects being specified – ZONEs, REPORTs, etc.).
4.1.1 TOP General Data Items
doMainSim=choice
Specifies whether the simulation is performed when a Run command is encountered. See also doAutoSize.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NO, YES | YES | No | constant |
begDay=date
Date specifying the beginning day of the simulation performed when a Run command is encountered. See further discussion under endDay (next).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
date | Jan 1 | No | constant |
endDay=date
Date specifying the ending day of the simulation performed when a Run command is encountered.
The program simulates 365 days at most. If begDay and endDay are the same, 1 day is simulated. If begDay precedes endDay in calendar sequence, the simulation is performed normally and covers begDay through endDay inclusive. If begDay follows endDay in calendar sequence, the simulation is performed across the year end, with Jan 1 immediately following Dec 31.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
date | Dec 31 | No | constant |
jan1DoW=choice
Day of week on which January 1 falls. jan1DoW is used in the calculation of the day of the week.
Note that “warm-up” days (see wuDays) occur before the start day specified by begDay. Thus “warm-up” days are often in the prior year. In order to preserve the day-of-week sequence, the effective jan1DoW is shifted back by one day during prior-year warmup.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
SUN, MON, TUE, WED, THU, FRI, SAT | THU | No | constant |
workDayMask=int TODO
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
constant |
wuDays=int
Number of “warm-up” days used to initialize the simulator. Simulator initialization is required because thermal mass temperatures are set to arbitrary values at the beginning of the simulation. Actual mass temperatures must be established through simulation of a few days before thermal loads are accumulated. Heavier buildings require more warm-up; the default values are adequate for conventional construction.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 365 | 7 | No | constant |
nSubSteps=int
Number of subhour steps used per hour in the simulation. 4 is the time-honored value for models using CNE zones. A value of 30 is typically for CSE zone models.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 4 | No | constant |
nSubhrTicks=int
Number of subhour ticks used per nSubSteps for DHWSYS simulation.
Note: This input is currently used only for experimental purposes.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 60/nSubSteps | No | constant |
tol=float
Endtest convergence tolerance for internal iteration in CNE models (no effect for CSE models) Small values for the tolerance cause more accurate simulations but slower performance. The user may wish to use a high number during the initial design process (to quicken the runs) and then lower the tolerance for the final design (for better accuracy). Values other than .001 have not been explored.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.001 | No | constant |
humTolF=float
Specifies the convergence tolerance for humidity calculations in CNE models (no effect in for CSE models), relative to the tolerance for temperature calculations. A value of .0001 says that a humidity difference of .0001 is about as significant as a temperature difference of one degree. Note that this is multiplied internally by “tol”; to make an overall change in tolerances, change “tol” only.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0.0001 | No | constant |
ebTolMon=float
Monthly energy balance error tolerance for internal consistency checks. Smaller values are used for testing the internal consistency of the simulator; values somewhat larger than the default may be used to avoid error messages when it is desired to continue working despite a moderate degree of internal inconsistency.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0001 | No | constant |
ebTolDay=float
Daily energy balance error tolerance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0001 | No | constant |
ebTolHour=float
Hourly energy balance error tolerance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0001 | No | constant |
ebTolSubhr=float
Sub-hourly energy balance error tolerance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0001 | No | constant |
unMetTzTol=float
Zone temperature unmet load tolerance. At the end of each subhour, if a conditioned zone temperature is more than unMetTzTol below the current heating setpoint or more than unMetTzTol above the current cooling setpoint, “unmet load” time is accumulated.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\geq\) 0 | 1 oF | No | constant |
unMetTzTolWarnHrs=float
Unmet load warning threshold. A warning message is issued for each zone having more than unMetTzTolWarnHrs unmet heating or cooling loads.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
hr | x \(\geq\) 0 | 150 | No | constant |
grndMinDim=float
The minimum cell dimension used in the two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | 0.066 | No | constant |
grndMaxGrthCoeff=float
The maximum ratio of growth between neighboring cells in the direction away from the near-field area of interest. Used in the two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 1.0 | 1.5 | No | constant |
grndTimeStep=choice
Allows the user to choose whether to calculate foundation conduction on hourly or subhourly intervals. Hourly intervals require less overall computation time, but with less accuracy.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
HOURLY, SUBHOURLY | HOURLY | No | constant |
humMeth=choice
Developmental zone humidity computation method choice for CNE models (no effect for CSE models).
ROB | Rob’s backward difference method. Works well within limitations of backward difference approach. |
PHIL | Phil’s central difference method. Should be better if perfectedcoma but initialization at air handler startup is unresolved*coma and ringing has been observed. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ROB, PHIL | ROB | No | constant |
dflExH=float
Default exterior surface (air film) conductance used for opaque and glazed surfaces exposed to ambient conditions in the absence of explicit specification.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | 2.64 | No | constant |
bldgAzm=float
Reference compass azimuth (0 = north, 90 = east, etc.). All zone orientations (and therefore surface orientations) are relative to this value, so the entire building can be rotated by changing bldgAzm only. If a value outside the range 0o \(\leq\) x \(<\) 360o is given, it is normalized to that range.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
o (degrees) | unrestricted | 0 | No | constant |
elevation=float
Elevation of the building site. Used internally for the computation of barometric pressure and air density of the location.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 (sea level) | No | constant |
runTitle=string
Run title for the simulation. Appears in report footers, export headers, and in the title lines to the INP, LOG, and ERR built-in reports (these appear by default in the primary report file; the ERR report also appears in the error message file, if one is created).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | blank (no title | No | constant |
runSerial=int
Run serial number for the simulation. Increments on each run in a session; appears in report footers.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(leq\) x \(leq\) 999 | 0 | No | constant |
4.1.2 TOP Daylight Saving Time Items
Daylight savings starts by default at 2:00 a.m. of the second Sunday in March. Internally, hour 3 (2:00-3:00 a.m.) is skipped and reports for this day show only 23 hours. Daylight savings ends by default at 2:00 a.m. of the first Sunday of November; for this day 25 hours are shown on reports. CSE fetches weather data using standard time but uses daylight savings time to calculate variable expressions (and thus all schedules).
DT=choice
Whether Daylight Savings Time is to be used for the current run.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
YES, NO | YES | No | constant |
DTbegDay=date
Start day for daylight saving time (assuming DT=Yes)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
date | second Sunday in March | No | constant |
DTendDay=date
End day for daylight saving time (assuming DT=Yes)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
date | first Sunday in November | No | constant |
4.1.3 TOP Model Control Items
ventAvail=choice
Indicates availability of outdoor ventilation strategies. CSE cannot model simultaneously-operating alternative ventilation strategies. For example, an RSYS central fan integrated (CFI) OAV system is never modeled while whole house fan ventilation is available. ventAvail controls which ventilation mode, if any, is available for the current hour. Note that mode availability means that the strategy could operate but may not operate due to other control assumptions.
Choice | Ventilation Strategy Available |
---|---|
NONE | None |
WHOLEBUILDING | IZXFER (window and whole-house fan) |
RSYSOAV | RSYS central fan integrated (CFI) outside air ventilation (OAV) |
As noted, ventAvail is evaluated hourly, permitting flexible control strategy modeling. The following example specifies that RSYSOAV (CFI) ventilation is available when the seven day moving average temperature is above 68 oF, otherwise whole building ventilation is available between 7 and 11 PM, otherwise no ventilation.
ventAvail = (@weather.taDbAvg07 > 68) ? RSYSOAV
: ($hour >= 19 && $hour <= 23) ? WHOLEBUILDING
: NONE
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Choices above | WHOLEBUILDING | No | hourly |
exShadeModel=choice
Specifies advanced exterior shading model used to evaluate shading of PVARRAYs by SHADEXs or other PVARRAYs. Advanced shading is not implemented for building surfaces and this setting has no effect on walls or windows.
Choice | Effect |
---|---|
PENUMBRA | Calculate shading using the Penumbra model |
NONE | Disable advanced shading calculations |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Choices above | PENUMBRA | No | constant |
slrInterpMeth=choice
Solar interpolation method.
Choice |
---|
CSE |
TRNSYS |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
See table above | CSE | No | constant |
ANTolAbs=float
AirNet absolute convergence tolerance. Ideally, calculated zone air pressures should be such that the net air flow into each zone is 0 – that is, there should be a perfect mass balance. The iterative AirNet solution techniques are deemed converged when netAirMassFlow < max( ANTolAbs, ANTolRel*totAirMassFlow).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lbm/sec | x \(>\) 0 | 0.00125 (about 1 cfm) | No | constant |
ANTolRel=float
AirNet relative convergence tolerance. See AnTolAbs just above.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0001 | No | constant |
ANPressWarn=float
AirNet pressure warning threshold. A warning message is issued when the absolute value of the AirNet-calculated zone pressure exceeds ANPressWarn. Note the default for ANPressWarn conservatively large. 10 lb/ft2 is about 500 pascals – a pressure that is probably impossible in a building. The intent of this value is to alert the user to incorrect modeling inputs while avoiding excessive messages.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lb/ft2 | x \(\gt\) 0 | 10 | No | constant |
ANPressErr=float
AirNet pressure error threshold. The simulation terminates with a message if the absolute value of any AirNet-calculated zone pressure exceeds ANPressErr. Note the default value for ANPressErr is physically unrealistic. 30 lb/ft2 is about 1500 pascals – a pressure that would never be possible in a building. The intent of this value is to prevent simulation crashes due to numerical errors in AirNet calculations.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lb/ft2 | x \(\gt\) 0 | 30 | No | constant |
The ASHWAT complex fenestration model used when WINDOW wnModel=ASHWAT yields several heat transfer results that are accurate over local ranges of conditions. Several values control when these value are recalculated. If any of the specified values changes more than the associated threshold, a full ASHWAT calculation is triggered. Otherwise, prior results are used. ASHWAT calculations are computationally expensive and conditions often change only incrementally between time steps.
AWTrigT=float
ASHWAT temperature change threshold – full calculation is triggered by a change of either indoor or outdoor environmental (combined air and radiant) temperature that exceeds AWTrigT.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 1 | No | constant |
AWTrigSlr=float
ASHWAT solar change threshold – full calculation is triggered by a fractional change of incident solar radiation that exceeds AWTrigSlr.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.05 | No | constant |
AWTrigH=float
ASHWAT convection coefficient change threshold – full calculation is triggered by a fractional change of inside surface convection coefficient that exceeds AWTrigH.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.1 | No | constant |
4.1.4 TOP Weather Data Items
The following system variables (4.6.4) are determined from the weather file for each simulated hour:
$radBeam | beam irradiance on tracking surface (integral for hour, Btu/ft2). |
$radDiff | diffuse irradiance on a horizontal surface (integral for hour, Btu/ft2). |
$tDbO | dry bulb temp (oF). |
$tWbO | wet bulb temp (oF). |
$wO | humidity ratio |
$windDirDeg | wind direction (degrees, NOT RADIANS; 0=N, 90=E). |
$windSpeed | wind speed (mph). |
The following are the terms determined from the weather file for internal use, and can be referenced with the probes shown.
@Top.depressWbWet bulb depression (F).
@Top.windSpeedSquaredWind speed squared (mph2).
wfName=string
Weather file path name for simulation. The file should be in the current directory, in the directory CSE.EXE was read from, or in a directory on the operating system PATH. Weather file formats supported are CSW, EPW, and ET1. Only full-year weather files are supported.
Note: Backslash (\) characters in path names must be doubled to work properly (e.g. “\\wthr\\mywthr.epw”). Forward slash (/) may be used in place of backslash without doubling.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
file name,path optional | none | Yes | constant |
skyModel=choice
Selects sky model used to determine relative amounts of direct and diffuse irradiance.
ISOTROPIC | traditional isotropic sky model |
ANISOTROPIC | Hay anisotropic model |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | ANISOTROPIC | No | constant |
skyModelLW=choice
Selects the model used to derive sky temperature used in long-wave (thermal) radiant heat exchange calculations for SURFACEs exposed to ambient conditions. See the RACM alorithms documentation for technical details.
Choice | Description |
---|---|
DEFAULT | Default: tSky from weather file if available else Berdahl-Martin |
BERDAHLMARTIN | Berdahl-Martin (tSky depends on dew point, cloud cover, and hour) |
DRYBULB | tSky = dry-bulb temperature (for testing) |
BLAST | Blast model (tSky depends on dry-bulb) |
IRHORIZ | Derives tSky from horizonal infrared data from the weather file (available on some EPW files only). Caution: minimal error checking! Missing weather file IR values are not handled correctly. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | DEFAULT | No | constant |
The reference temperature and humidity are used to calculate a humidity ratio assumed in air specific heat calculations. The small effect of changing humidity on the specific heat of air is generally ignored in the interests of speed, but the user can control the humidity whose specific heat is used through the refTemp and refRH inputs.
refTemp=float
Reference temperature (see above paragraph).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | 60o | No | constant |
refRH=float
Reference relative humidity (see above).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\leq\) x \(\leq\) 1 | 0.6 | No | constant |
grndRefl=float
Global ground reflectivity, used except where other value specified with sfGrndRefl or wnGrndRefl. This reflectivity is used in computing the reflected beam and diffuse radiation reaching the surface in question. It is also used to calculate the solar boundary conditions for the exterior grade surface in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\leq\) x \(\leq\) 1 | 0.2 | No | Monthly-Hourly |
The following values modify weather file data, permitting varying the simulation without making up special weather files. For example, to simulate without the effects of wind, use windF = 0; to halve the effects of diffuse solar radiation, use radDiffF = 0.5. Note that the default values for windSpeedMin and windF result in modification of weather file wind values unless other values are specified.
grndEmit=float
Long-wave emittance of the exterior grade surface used in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0.0 \(le\) x \(le\) 1.0 | 0.8 | No | constant |
grndRf
Ground surface roughness. Used for convection and wind speed corrections in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\geq\) 0.0 | 0.1 | No | constant |
windSpeedMin=float
Minimum value for wind speed
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
mph | x \(\ge\) 0 | 0.5 | No | constant |
windF=float
Wind Factor: multiplier for wind speeds read from weather file. windF is applied after windSpeedMin. Note that windF does not effect infiltration rates calculated by the Sherman-Grimsrud model (see e.g. ZONE.infELA). However, windF does modify AirNet flows (see IZXFER).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0.25 | No | constant |
terrainClass=int
Specifies characteristics of ground terrain in the project region.
1 | ocean or other body of water with at least 5 km unrestricted expanse |
2 | flat terrain with some isolated obstacles (buildings or trees well separated) |
3 | rural areas with low buildings, trees, etc. |
4 | urban, industrial, or forest areas |
5 | center of large city |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1 \(\leq\) x \(\leq\) 5 | 4 | No | constant |
radBeamF=float
Multiplier for direct normal (beam) irradiance
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
radDiffF=float
Multiplier for diffuse horizonal irradiance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
hConvMod=choice
Enable/disable convection convective coefficient pressure modification factor.
\[0.24 + 0.76 \cdot P_{Location}/P_{SeaLevel}\]
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
YES, NO | YES | No | constant |
soilDiff=float
Note: soilDiff is used as part of the simple ground model, which is no longer supported. Use soilCond, soilSpHt, and SoilDens instead.
Soil diffusivity, used in derivation of ground temperature. CSE calculates a ground temperature at 10 ft depth for each day of the year using dry-bulb temperatures from the weather file and soilDiff. Ground temperature is used in heat transfer calculations for SURFACEs with sfExCnd=GROUND. Note: derivation of mains water temperature for DHW calculations involves a ground temperature based on soil diffusivity = 0.025 and does not use this soilDiff.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2/hr | x \(>\) 0 | 0.025 | No | constant |
soilCond=float
Soil conductivity. Used in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
Btuh-ft/ft2-oF | x \(>\) 0 | 1.0 | No | constant |
soilSpHt=float
Soil specific heat. Used in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/lb-oF | x \(>\) 0 | 0.1 | No | constant |
soilDens=float
Soil density. Used in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lb/ft3 | x \(>\) 0 | 115 | No | constant |
farFieldWidth=float
Far-field width. Distance from foundation to the lateral, zero-flux boundary condition. Used in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | 130 | No | constant |
deepGrndCnd=choice
Deep-ground boundary condition type. Choices are WATERTABLE (i.e., a defined temperature) or ZEROFLUX.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | WATERTABLE, ZEROFLUX | ZEROFLUX | No | constant |
deepGrndDepth=float
Deep-ground depth. Distance from exterior grade to the deep-ground boundary. Used in two-dimensional finite difference calculations for FOUNDATIONs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | 130 | No | constant |
deepGrndT=float
Deep-ground temperature. Used when deepGrndCnd=WATERTABLE.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
F | x \(>\) 0 | Annual average drybulb temperature | No | hourly |
4.1.5 TOP TDV (Time Dependent Value) Items
CSE supports an optional comma-separated (CSV) text file that provides hourly TDV values for electricity and fuel. TDV values are read along with the weather file and the values merged with weather data. Several daily statistics are calculated for use via probes. The file has no other effect on the simulation. Only full-year TDV files are supported.
The format of a TDV file is the same as an IMPORTFILE with the proviso that the 4 line header is not optional and certain header items must have specified values. In the following table, non-italic items must be provided as shown (with optional quotes).
Line Contents Notes | |
---|---|
1 | TDV Data (TDV/Btu), runNumber, runNumber is not checked |
2 | timestamp optionally in quotes accessible via @TOP.TDVFileTimeStamp |
3 | title, hour title (in quotes if it contains commas) accessible via @TOP.TDVFileTitle |
4 | tdvElec, tdvFuel comma separated column names (optionally in quotes) not checked |
5 .. | valElec,valFuel comma separated numerical values (8760 or 8784 rows) tdvElec is always in column 1, tdvFuel always in column 2 column names in row 4 do not determine order |
Example TDV file –
"TDV Data (TDV/Btu)","001"
"Wed 14-Dec-16 12:30:29 pm"
"BEMCmpMgr 2019.0.0 RV (758), CZ12, Fuel NatGas", Hour
"tdvElec","tdvFuel"
7.5638,2.2311
7.4907,2.2311
7.4478,2.2311
7.4362,2.2311
7.5255,2.2311
7.5793,2.2311
7.6151,2.2311
7.6153,2.2311
7.5516,2.2311
(... continues for 8760 or 8784 data lines ...)
Note: additional columns can be included and are ignored.
The table below shows probes available for accessing TDV data in expressions. Except as noted, daily values are updated based on standard time, so they may be inaccurate by small amounts when daylight savings time is in effect.
Probe | Variability | Description |
---|---|---|
@Weather.tdvElec | Hour | current hour electricity TDV |
@Weather.tdvFuel | Hour | current hour fuel TDV |
@Weather.tdvElecPk | Day | current day peak electricity TDV (includes future hours). Updated at hour 23 during daylight savings. |
@Weather.tdvElecAvg | Day | current day average electricity TDV (includes future hours) |
@Weather.tdvElecPvPk | Day | previous day peak electricity TDV |
@Weather.tdvElecAvg01 | Day | previous day average electricity TDV |
@weather.tdvElecHrRank | Day | hour ranking of TDVElec values. tdvElecHrRank[ 1] is the hour having the highest TDVElec, tdvElecHrRank[ 2] is the next highest, etc. The hour values are adjusted when dayight savings time is in effect, so they remain consistent with system variable $hour. |
@weatherFile.tdvFileTimeStamp | Constant | TDV file timestamp (line 2 of header) |
@weatherFile.tdvFileTitle | Constant | TDV file title (line 3 of header) |
@Top.tdvFName | Constant | TDV file full path |
TDVfName=string
Note: Backslash (\) characters in path names must be doubled to work properly (e.g. “\\data\\mytdv.tdv”). Forward slash (/) may be used in place of backslash without doubling.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
file name, path optional | (no TDV file) | No | constant |
4.1.6 TOP Report Data Items
These items are used in page-formatted report output files. See REPORTFILE, Section 5.245.21, and REPORT, Section 5.25.
repHdrL=string
Report left header. Appears at the upper left of each report page unless page formatting (rfPageFmt) is OFF. If combined length of repHdrL and repHdrR is too large for the page width, one or both will be truncated.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
repHdrR=string
Report right header. Appears at the upper right of each report page unless page formatting (rfPageFmt) is OFF. If combined length of repHdrL and repHdrR is too large for the page width, one or both will be truncated.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
repLPP=int
Total lines per page to be assumed for reports. Number of lines used for text (including headers and footers) is repLPP - repTopM - repBotM.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lines | x \(\ge\) 50 | 66 | No | constant |
repTopM=int
Number of lines to be skipped at the top of each report page (prior to header).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lines | 0 \(\geq\) x \(\geq\) 12 | 3 | No | constant |
repBotM=int
Number of lines reserved at the bottom of each report page. repBotM determines the position of the footer on the page (blank lines after the footer are not actually written).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lines | 0 \(\geq\) x \(\geq\) 12 | 3 | No | constant |
repCPL=int
Characters per line for report headers and footers, user defined reports, and error messages. CSE writes simple ASCII files and assumes a fixed (not proportional) spaced printer font. Many of the built-in reports now (July 1992) assume a line width of 132 columns.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
characters | 78 \(\leq\) x \(\leq\) 132 | 78 | No | constant |
repTestPfx=string
Report test prefix. Appears at beginning of report lines that are expected to differ from prior runs. This is useful for “hiding” lines from text comparison utilities in automated testing schemes. Note: the value specified with command line -x takes precedence over this input.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
4.1.7 TOP Autosizing
doAutoSize=choice
Controls invocation of autosizing phase prior to simulation.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
YES, NO | NO, unless AUTOSIZE commands in input | No | constant |
auszTol=float
Autosize tolerance. Sized capacity results are deemed final when successive design day calculations produce results within auszTol of the prior iteration.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
.005 | No | constant |
heatDsTDbO=float
Heating outdoor dry bulb design temperature used for autosizing heating equipment.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | none | No | hourly |
heatDsTWbO=float
Heating outdoor design dry bulb temperature used for autosizing heating equipment.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | derived assuming RH=.7 | No | hourly |
CSE provides 3 mutually-exclusive methods for specifying cooling design conditions. Each resulting design day is simulated repeatedly until results (e.g. equipment capacities) converge to stable values. Multiple days are typically used to ensure the a range of temperatures and sun positions are considered.
- Design conditions. One or more DESCONDs are specified. DESCOND data is used to generate 24 hour design day weather data.
- Design days (from weather file). One or more dates are specified. Actual days from the weather file are simulated.
- Monthly design data. Deprecated method using conditions found in ET1 format weather files.
coolDsCond=list of up to 12 DESCONDs
Specifies cooling design conditions for cooling autosizing. A comma-separated list of up to 12 DESCOND names can be provided. Each day will be simulated repeatedly using weather conditions generated from DESCOND values.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of DESCOND | none | No | constant |
coolDsDay=list of up to 12 days
Specifies cooling design days for cooling autosizing. Each day will be simulated repeatedly using weather file conditions for that day.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
dates | none | No | constant |
coolDsMo=list of up to 12 months
Deprecated method for specifying design days for cooling autosizing. Design conditions are taken from ET1 weather file header, however, the limited availale ET1 files do not contain design condition information.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
months | none | No | constant |
4.1.8 TOP Debug Reporting
verbose=int
Controls verbosity of screen remarks. Most possible remarks are generated during autosizing of CNE models. Little or no effect in CSE models. TODO: document options
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 - 5 | 1 | No | constant |
The following dbgPrintMask values provide bitwise control of addition of semi-formated internal results to the run report file. The values and format of debugging reports are modified as required for testing purposes.
dbgPrintMaskC=int
Constant portion of debug reporting control.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 | No | constant |
dbgPrintMask=int
Hourly portion of debug reporting control (generally an expression that evaluates to non-0 only on days or hours of interest).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 | No | hourly |
dbgFlag=int
Allows passing an input value to ad-hoc debugging code. No permanent use; no impact on results.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 | No | subhourly |
doCoverage=choice
Enables expression code coverage reporting. Development aid.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NO, YES | NO | No | constant |
Related Probes:
4.2 HOLIDAY
HOLIDAY objects define holidays. Holidays have no inherent effect, but input expressions can test for holidays via the $DOWH, $isHoliday, $isHoliTrue, $isWeHol, and $isBegWeek system variables (4.6.4).
Examples and the list of default holidays are given after the member descriptions.
hdName
Name of holiday: must follow the word HOLIDAY.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
A holiday may be specified by date or via a rule such as “Fourth Thursday in November”. To specify by date, give hdDateTrue, and also hdDateObs or hdOnMonday if desired. To specify by rule, give all three of hdCase, hdMon, and hdDow.
hdDateTrue=date
The true date of a holiday, even if not celebrated on that day.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
date | blank | No | constant |
hdDateObs=date
The date that a holiday will be observed. Allowed only if hdDateTrue given and hdOnMonday not given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
date | hdDateTrue | No | constant |
hdOnMonday=choice
If YES, holiday is observed on the following Monday if the true date falls on a weekend. Allowed only if hdDateTrue given and hdDateObs not given.
Note: there is no provision to celebrate a holiday that falls on a Saturday on Friday (as July 4 was celebrated in 1992).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
YES/NO | YES | No | constant |
hdCase=choice
Week of the month that the holiday is observed. hdCase, hdMon, and hdDow may be given only if hdDateTrue, hdDateObs, and hdOnMonday are not given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
FIRST SECOND THIRD FOURTH LAST | FIRST | No | constant |
hdMon=choice
Month that the holiday is observed.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC | none | required if hdCase given | constant |
hdDow=choice
Day of the week that the holiday is observed.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY | MONDAY | required if hdCase given | constant |
endHoliday
Indicates the end of the holiday definition. Alternatively, the end of the holiday definition can be indicated by “END” or simply by beginning another object.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | constant |
Examples of valid HOLIDAY object specifications:
- Holiday on May first, observed date moved to following Monday if the first falls on a weekend (hdOnMonday defaults Yes).
HOLIDAY MAYDAY;
hdDateTrue = May 1;
- Holiday on May 1, observed on May 3.
HOLIDAY MAYDAY;
hdDateTrue = May 1;
hdDateObs = May 3;
- Holiday observed on May 1 even if on a weekend.
HOLIDAY MAYDAY;
hdDateTrue = May 1;
hdOnMonday = No;
- Holiday observed on Wednesday of third week of March
HOLIDAY HYPOTHET;
hdCase = third;
hdDow = Wed;
hdMon = MAR
As with reports, Holidays are automatically generated for a standard set of Holidays. The following are the default holidays automatically defined by CSE:
New Year’s Day | *January 1 |
M L King Day | *January 15 |
President’s Day | 3rd Monday in February |
Memorial Day | last Monday in May |
Fourth of July | *July 4 |
Labor Day | 1st Monday in September |
Columbus Day | 2nd Monday in October |
Veterans Day | *November 11 |
Thanksgiving | 4th Thursday in November |
Christmas | *December 25 |
* observed on the following Monday if falls on a weekend, except as otherwise noted:
If a particular default holiday is not desired, it can be removed with a DELETE statement:
DELETE HOLIDAY Thanksgiving
DELETE HOLIDAY "Columbus Day" // Quotes necessary (due to space)
DELETE HOLIDAY "VETERANS DAY" // No case-sensitivity
Note that the name must be spelled exactly as listed above.
Related Probes:
4.3 DESCOND
Specifies conditions for a cooling design day. When referenced in TOP coolDsCond (see TOP Autosizing), DESCOND members are used to generate a 24 hour design day used during cooling autosizing. Note that coolDsCond can reference more than one DESCOND, allowing multiple design conditions to be used for autosizing. For example, both summer and fall days could be specified to ensure a range of sun angles are considered. Any DESCONDs that are not referenced in coolDsCond have no effect.
desCondName
Object name, given after “DESCOND”. Required for referencing from Top coolDsCond.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
dcDay=date
Calendar date for this design cooling condition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1-365 | 200 | No | constant |
dcDB=float
Design dry-bulb temperature (maxiumum temperature on design day).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | no-limitations? | 0.0 | No | constant |
dcMCDBR=float
Coincident daily dry-bulb range.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | no-limitations? | none | No | constant |
dcMCWB=float
Coincident wet-bulb design temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | no-limitations? | none | No | constant |
dcMCWBR=float
Coincident daily wet-bulb range.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | no-limitations? | none | No | constant |
dcWindSpeed=float
Wind speed for design conditions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
mph | x \(\geq\) 0 | 0.0 | No | constant |
DESCOND provides two mutually-exclusive methods for specifying design day direct beam and diffuse horizontal irradiance values. Both use the ASHRAE clear sky model. Consult the ASHRAE Handbook of Fundamentals Climatic Data chapter for model documentation.
- Pseudo optical depth. dcTauB and dcTauD define the taub and taud parameters in the clear sky model.
- Solar noon irradiance. CSE uses dcEbnSlrNoon and dcEdhSlrNoon to back-calculate taub and taud.
At most one of these methods can be used within a given DESCOND. If all solar-related values are omitted, the generated design day has 0 irradiance for all hours.
dcTauB=float
dcTauD=float
ASHRAE clear sky model beam and diffuse pseudo optical depths. These values are available by month for many locations in ASHRAE design weather data. Cannot be given if dcEbnSlrNoon and dcEdhSlrNoon are specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 irradiance | No | constant |
dcEbnSlrNoon=float
dcEdhSlrNoon=float
Solar noon direct beam and diffuse horizontal irradiance. Cannot be given if dcTauB and dcTauD are specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2 | x \(\geq\) 0 | 0 irradiance | No | constant |
endDesCond
Optionally indicates the end of the descond definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
4.4 MATERIAL
MATERIAL constructs an object of class MATERIAL that represents a building material or component for later reference a from LAYER (see below). A MATERIAL so defined need not be referenced. MATERIAL properties are defined in a consistent set of units (all lengths in feet), which in some cases differs from units used in tabulated data. Note that the convective and air film resistances for the inside wall surface is defined within the SURFACE statements related to conductances.
matName
Name of material being defined; follows the word “MATERIAL”.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
matThk=float
Thickness of material. If specified, matThk indicates the discreet thickness of a component as used in construction assemblies. If omitted, matThk indicates that the material can be used in any thickness; the thickness is then specified in each LAYER using the material (see below).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | none | No | constant |
matCond=float
Conductivity of material. Note that conductivity is always stated for a 1 foot thickness, even when matThk is specified; if the conductance is known for a specific thickness, an expression can be used to derive matCond.
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
Btuh-ft/ft2-oF | x \(>\) 0 | none | Yes | constant |
matCondT=float
Temperature at which matCond is rated. See matCondCT (next).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 70 oF | No | constant |
matCondCT=float
Coefficient for temperature adjustment of matCond in the forward difference surface conduction model. Each hour (not subhour), the conductivity of layers using this material are adjusted as followslrCond = matCond * (1 + matCondCT*(Tlayer – matCondT))
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF-1 | 0 | No | constant |
Note: A typical value of matCondCT for fiberglass batt insulation is 0.00418 F-1
matSpHt=float
Specific heat of material.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/lb-oF | x \(\ge\) 0 | 0 (thermally massless) | No | constant |
matDens=float
Density of material.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lb/ft3 | x \(\ge\) 0 | 0 (massless) | No | constant |
matRNom=float
Nominal R-value per foot of material. Appropriate for insulation materials only and used for documentation only. If specified, the current material is taken to have a nominal R-value that contributes to the reported nominal R-value for a construction. As with matCond, matRNom is always stated for a 1 foot thickness, even when matThk is specified; if the nominal R-value is known for a specific thickness, an expression can be used to derive matRNom.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2-oF/Btuh | x \(>\) 0 | none | No | constant |
endMaterial
Optional to indicate the end of the material. Alternatively, the end of the material definition can be indicated by “END” or simply by beginning another object.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.5 CONSTRUCTION
CONSTRUCTION constructs an object of class CONSTRUCTION that represents a light weight or massive ceiling, wall, floor, or mass assembly (mass assemblies cannot, obviously, be lightweight). Once defined, CONSTRUCTIONs can be referenced from SURFACEs (below). A defined CONSTRUCTION need not be referenced. Each CONSTRUCTION is optionally followed by LAYERs, which define the constituent LAYERs of the construction.
conName
Name of construction. Required for reference from SURFACE and DOOR objects, below.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
conU=float
U-value for the construction (NOT including surface (air film) conductances; see SURFACE statements). If omitted, one or more LAYERs must immediately follow to specify the LAYERs that make up the construction. If specified, no LAYERs can follow.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | calculated from LAYERs | if omitted, LAYERs must follow | constant |
endConstruction
Optional to indicates the end of the CONSTRUCTION. Alternatively, the end of the CONSTRUCTION definition can be indicated by “END” or by beginning another object If END or endConstruction is used, it should follow the construction’s LAYER subobjects, if any.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
N/A | No | constant |
Related Probes:
4.6 FOUNDATION
Foundation describes the two-dimensional relationship between ground-contact SURFACEs (i.e., sfExCnd = GROUND) and the surrounding ground. A FOUNDATION is referenced by Floor SURFACEs (see sfFnd). FOUNDATIONs are used to describe the two-dimensional features of foundation designs that cannot be captured by the typical one-dimensional constructions. Dimensions from the one-dimensional CONSTRUCTIONs associated with ground-contact floors and walls will automatically be interpreted into the two-dimensional context.
Any wall SURFACEs in contact with the ground must refer to a Floor SURFACE object (see sfFndFloor) to indicate which floor shares the same ground domain as a boundary condition (and establish the two-dimensional context for the basis of the ground calculations).
FOUNDATION objects are used to instantiate instances of heat transfer within Kiva.
MATERIALs used in a FOUNDATION cannot have variable properties at this time.
Most of the relevant dimensions and properties in the two-dimensional context are defined in the FOUNDATION object (and FNDBLOCK subobjects) with a few exceptions specified by specific SURFACEs:
- sfFnd
- sfFndFloor
- sfHeight
- sfExpPerim
- sfCon
Some properties applying to all FOUNDATIONs are defined at the TOP level:
- soilCond
- soilSpHt
- soilDens
- grndEmiss
- grndRefl
- grndRf
- farFieldWidth
- deepGrndCnd
- deepGrndDepth
- deepGrndT
- grndMinDim
- grndMaxGrthCoeff
- grndTimeStep
The following data members describe the dimensions and properties of the foundation wall. For below-grade walls, the CONSTRUCTION (and corresponding width) of the foundation wall is defined by the Wall SURFACEs referencing the FOUNDATION object. For on-grade floors, the CONSTRUCTION of the foundation wall must be defined using fdFtCon. The actual height of the foundation wall (from the top of the wall to the top of the slab) is defined by the corresponding SURFACE objects.
Other components of the foundation design (e.g., interior/exterior insulation) as well as other variations in thermal properties within the ground are defined using FNDBLOCK (foundation block) objects. Any number of FNDBLOCKs can appear after the definition of a FOUNDATION to be properly associated.
fdName
Name of foundation; give after the word FOUNDATION. Required for reference from SURFACE objects.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | 63 characters | none | Yes | constant |
fdWlHtAbvGrd=float
Wall height above grade.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\geq\) 0 | 0.0 | No | constant |
fdWlDpBlwSlb=float
Wall depth below slab.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\geq\) 0 | 0.0 | No | constant |
fdFtCon=conName
Name of CONSTRUCTION of the footing wall. Only required IF it is a slab foundation (i.e., no wall surfaces reference this FOUNDATION object).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | Name of a Construction | none | if a slab foundation | constant |
endFoundation
Indicates the end of the foundation definition. Alternatively, the end of the foundation definition can be indicated by the declaration of another object or by END.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
4.7 FNDBLOCK
Foundation blocks are materials within the two-dimensional domain beyond those defined by the slab and wall SURFACEs. Each block is represented as a rectangle in the domain by specifying the X (lateral) and Z (vertical) coordinates of two opposite corners. The coordinate system for each point is relative to the X and Z references defined by the user. As a convention The positive X direction is away from the building, and the positive Z direction is down.
Options for X and Z references are illustrated in the figure below.
The default reference is WALLINT, WALLTOP.
An example of defining a block for interior wall insulation is shown below. Here the two points defining the block (P1 and P2) are both shown relative to their reference points (Ref1 and Ref2, respectively).
Note: X and Z point values of zero imply that a point is the same as the reference point. The default for X and Z point values is zero since points will often align with one or both of the reference values.
It does not matter which of the four corners of a block are used to define the two points as long as they are opposite corners.
fbMat=matName
Name of MATERIAL of the foundation block.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | Name of a Material | none | Yes | constant |
fbX1Ref=choice
Relative X origin for fbX1 point. Options are:
- SYMMETRY
- WALLINT
- WALLCENTER
- WALLEXT
- FARFIELD
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | WALLINT | No | constant |
fbZ1Ref=choice
Relative Z origin for fbZ1 point. Options are:
- WALLTOP
- GRADE
- SLABTOP
- SLABBOTTOM
- WALLBOTTOM
- DEEPGROUND
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | WALLTOP | No | constant |
fbX1=float
The X position of the first corner of the block relative to fbX1Ref.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | 0.0 | No | constant |
fbZ1=float
The Z position of the first corner of the block relative to fbZ1Ref.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | 0.0 | No | constant |
fbX2Ref=choice
Relative X origin for fbX2 point. Options are:
- SYMMETRY
- WALLINT
- WALLCENTER
- WALLEXT
- FARFIELD
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | WALLINT | No | constant |
fbZ2Ref=choice
Relative Z origin for fbZ2 point. Options are:
- WALLTOP
- GRADE
- SLABTOP
- SLABBOTTOM
- WALLBOTTOM
- DEEPGROUND
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | WALLTOP | No | constant |
fbX2=float
The X position of the second corner of the block relative to fbX2Ref.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | 0.0 | No | constant |
fbZ2=float
The Z position of the second corner of the block relative to fbZ2Ref.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | 0.0 | No | constant |
endFndBlock
Indicates the end of the foundation block definition. Alternatively, the end of the foundation block definition can be indicated by the declaration of another object or by END.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
4.8 LAYER
LAYER constructs a subobject of class LAYER belonging to the current CONSTRUCTION. LAYER is not recognized except immediately following CONSTRUCTION or another LAYER. The members represent one layer (that optionally includes framing) within the CONSTRUCTION.
The layers should be specified in inside to outside order. A framed layer (lrFrmMat and lrFrmFrac given) is modeled by creating a homogenized material with weighted combined conductivity and volumetric heat capacity. Caution: it is generally preferable to model framed constructions using two separate surfaces (one with framing, one without). At most one framed layer (lrFrmMat and lrFrmFrac given) is allowed per construction.
The layer thickness may be given by lrThk, or matThk of the material, or matThk of the framing material if any. The thickness must be specified at least one of these three places; if specified in more than one place and not consistent, an error message occurs.
lrName
Name of layer (follows “LAYER”). Required only if the LAYER is later referenced in another object, for example with LIKE or ALTER; however, we suggest naming all objects for clearer error messages and future flexibility.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
lrMat=matName
Name of primary MATERIAL in layer.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a MATERIAL | none | Yes | constant |
lrThk=float
Thickness of layer.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | Required if matThk not specified in referenced lrMat | No | constant |
lrFrmMat=matName
Name of framing MATERIAL in layer, if any. At most one layer with lrFrmMat is allowed per CONSTRUCTION. See caution above regarding framed-layer model.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a MATERIAL | no framed layer | No | constant |
lrFrmFrac=float
Fraction of layer that is framing. Must be specified if frmMat is specified. See caution above regarding framed-layer model.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\leq\) x \(\leq\) 1 | no framed layer | Required if lrFrmMat specified, else disallowed | constant |
endLayer
Optional end-of-LAYER indicator; LAYER definition may also be indicated by “END” or just starting the definition of another LAYER or other object.
Related Probes:
4.9 GLAZETYPE
GLAZETYPE constructs an object of class GLAZETYPE that represents a glazing type for use in WINDOWs.
gtName
Name of glazetype. Required for reference from WINDOW objects, below.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
gtModel=choice
Selects model to be used for WINDOWs based on this GLAZETYPE.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
SHGC, ASHWAT | SHGC | No | constant |
gtU=float
Glazing conductance (U-factor without surface films, therefore not actually a U-factor but a C-factor). Used as wnU default; an error message will be issued if the U value is not given in the window (wnU) nor in the glazeType (gtU). Preferred Approach: To use accurately with standard winter rated U-factor from ASHRAE or NFRC enter as:
gtU = (1/((1/U-factor)-0.85)
Where 0.85 is the sum of the interior (0.68) and exterior (0.17) design air film resistances assumed for rating window U-factors. Enter wnInH (usually 1.5=1/0.68) instead of letting it default. Enter the wnExH or let it default. It is important to use this approach if the input includes gnFrad for any gain term. Using approach 2 below will result in an inappropriate internal gain split at the window.
Approach 2. Enter gtU=U-factor and let the wnInH and wnExH default. This approach systematically underestimates the window U-factor because it adds the wnExfilm resistance to 1/U-factor thereby double counting the exterior film resistance. This approach will also yield incorrect results for gnFrad internal gain since the high wnInH will put almost all the gain back in the space.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | none | No | constant |
gtUNFRC=float
Fenestration system (including frame) U-factor evaluated at NFRC heating conditions. For ASHWAT windows, a value for the NFRC U-factor is required, set via gtUNFRC or wnUNFRC.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | none | No | constant |
gtSHGC=float
Glazing Solar Heat Gain Coefficient: fraction of normal beam insolation which gets through glass to space inside. We recommend using this to represent the glass normal transmissivity characteristic only, before shading and framing effects
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | none | Yes | constant |
gtSMSO=float
SHGC multiplier with shades open. May be overriden in the specific window input.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | 1.0 | No | Monthly - Hourly |
gtSMSC=float
SHGC multiplier with shades closed. May be overriden in the specific window input.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | gtSMSO (no shades) | No | Monthly - Hourly |
gtFMult=float
Framing multiplier used if none given in window, for example .9 if frame and mullions reduce the solar gain by 10%. Default of 1.0 implies frame/mullion effects allowed for in gtSHGC’s or always specified in Windows.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | gtSHGCO | No | Monthly - Hourly |
gtPySHGC =float
Four float values separated by commas. Coefficients for incidence angle SHGC multiplier polynomial applied to gtSHGC to determine beam transmissivity at angles of incidence other than 90 degrees. The values are coefficients for first through fourth powers of the cosine of the incidence angle; there is no constant part. An error message will be issued if the coefficients do not add to one. They are used in the following computation:
angle = incidence angle of beam radiation, measured from normal to glass.
cosI = cos( angle)
angMult = a*cosI + b*cosI^2 + c*cosI^3 + d*cosI^4
beamXmisvty = gtSHGCO * angMult (shades open)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
float | any | none | Yes | constant |
gtDMSHGC=float
SHGC diffuse multiplier, applied to gtSHGC to determine transmissivity for diffuse radiation.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | none | Yes | constant |
gtDMRBSol=float
SHGC diffuse multiplier, applied to qtSHGC to determine transmissivity for diffuse radiation reflected back out the window. Misnamed as a reflectance. Assume equal to DMSHGC if no other data available.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | none | Yes | constant |
gtNGlz=int
Number of glazings in the Glazetype (bare glass only, not including any interior or exterior shades).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) x \(\leq\) 4 | 2 | No | constant |
gtExShd=choice
Exterior shading type (ASHWAT only).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NONE INSCRN | NONE | No | constant |
gtInShd=choice
Interior shade type (ASHWAT only).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NONE DRAPEMED | NONE | No | constant |
gtDirtLoss=float
Glazing dirt loss factor.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | 0 | No | constant |
endGlazeType
Optional to indicates the end of the Glazetype. Alternatively, the end of the GLAZETYPE definition can be indicated by “END” or by beginning another object
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.10 METER
A METER object is a user-defined “device” that records energy consumption of equipment as simulated by CSE. The user defines METERs with the desired names, then assigns energy uses of specific equipment to the desired meters using commands described under each equipment type’s class description (AIRHANDLER, TERMINAL, etc.). Additional energy use from equipment not simulated by CSE (except optionally for its effect on heating and cooling loads) can also be charged to METERs (see GAIN). The data accumulated by meters can be reported at hourly, daily, monthly, and annual (run) intervals by using REPORTs and EXPORTs of type MTR.
Meters account for energy use in the following pre-defined categories, called end uses. The abbreviations in parentheses are used in MTR report headings (and for gnMeter input, below). You also get a column for the net total on the meter (abbreviated “Tot”).
Clg | Cooling |
Htg | Heating (includes heat pump compressor) |
HPBU | Heat pump resistance heating (backup and defrost) |
DHW | Domestic (service) hot water |
DHWBU | Domestic (service) hot water heating backup (HPWH resistance) |
DHWMFL | Domestic (service) hot water heating multi-family loop pumping and loss makeup |
FANC | Fans, AC and cooling ventilation |
FANH | Fans, heating |
FANV | Fans, IAQ venting |
FAN | Fans, other purposes |
AUX | HVAC auxiliaries such as pumps |
PROC | Process |
LIT | Lighting |
RCP | Receptacles |
EXT | Exterior lighting |
REFR | Refrigeration |
DISH | Dishwashing |
DRY | Clothes drying |
WASH | Clothes washing |
COOK | Cooking |
USER1 | User-defined category 1 |
USER2 | User-defined category 2 |
BT | Battery charge power |
PV | Photovoltaic power generation |
The user has complete freedom over how many meters are defined and how equipment is assigned to them. At one extreme, a single meter “Electricity” could be defined and have all of electrical uses assigned to it. On the other hand, definition of separate meters “Elect_Fan1”, “Elect_Fan2”, and so forth allows accounting of the electricity use for individual pieces of equipment. Various groupings are possible: for example, in a building with several air handlers, one could separate the energy consumption of the fans from the coils, or one could separate the energy use by air handler, or both ways, depending on the information desired from the run.
The members that assign energy use to meters include:
- GAIN: gnMeter, gnEndUse
- ZONE: xfanMtr
- IZXFER: izfanMtr
- RSYS: rsElecMtr, rsFuelMtr
- DHWSYS: wsElecMtr, wsFuelMtr
- DHWHEATER: whElectMtr, whFuelMtr
- DHWPUMP: wpElecMtr
- DHWLOOPPUMP: wlpElecMtr
- PVARRAY: pvElecMeter
- TERMINAL: tuhcMtr, tfanMtr
- AIRHANDLER: sfanMtr, rfanMtr, ahhcMtr, ahccMtr, ahhcAuxOnMtr, ahhcAuxOffMtr, ahhcAuxFullOnMtr, ahhcAuxOnAtAllMtr, ahccAuxOnMtr, ahccAuxOffMtr, ahccAuxFullOnMtr, ahccAuxOnAtAllMtr
- BOILER: blrMtr, blrpMtr, blrAuxOnMtr, blrAuxOffMtr, blrAuxFullOnMtr, blrAuxOnAtAllMtr
- CHILLER: chMtr, chppMtr, chcpMtr, chAuxOnMtr, chAuxOffMtr, chAuxFullOnMtr, chAuxOnAtAllMtr
- TOWERPLANT: tpMtr
The end use can be specified by the user only for GAINs and PVARRAYs; in other cases it is hard-wired to Clg, Htg, FanC, FanH, FanV, Fan, or Aux as appropriate.
mtrName
Name of meter: required for assigning energy uses to the meter elsewhere.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
mtrDemandRate=float
DmdCost per Btu of demand, for a month.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
N/A | No | constant |
mtrRate=float
Cost of energy use per Btu.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
N/A | No | constant |
mtrSubmeters=list of up to 50 METERs
A comma-separate list of METERs that are accumulated into this METER with optional multipliers (see mtrSubmeterMults). Submeters facilitate flexible categorization of energy results. In addition, use of mtrSubmeterMults allows energy results from a representative model to be scaled and included in overall results. For example, a typical zone could be used to represent 5 similar spaces. The energy uses of the typical zone could be assigned to a dedicated METER that is accumulated to a main METER with a multiplier of 5. Rules –
- A METER cannot reference itself as a submeter.
- A given METER can be referenced only once in the mtrSubmeters list.
- Circular references are not allowed.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
names of METERs | No | constant |
mtrSubmeterMults=list of up to 50 floats
Submeter multipliers. Use cases for multipliers include –
- Scaling results from portions of a model to approximate the behavior of multiple similar aspects (e.g. multiple floors in a high-rise building)
- Tracking energy use during selected time intervals; for example, peak-period energy use could be metered for certain hours via scheduled multipliers of 0 or 1.
A note re default values: if mtrSubmeterMults is omitted, all multipliers are defaulted to 1. However, when mtrSubmeterMults is included, a multiplier value should be provided for each METER listed in mtrSubmeters since unspecified values are set to 0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1 | No | hourly |
endMeter
Indicates the end of the meter definition. Alternatively, the end of the meter definition can be indicated by the declaration of another object or by END.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.11 DHWMETER
A DHWMETER object is a user-defined “device” that records water consumption as simulated by CSE. The data accumulated by DHWMETERs can be reported at hourly, daily, monthly, and annual (run) intervals by using REPORTs and EXPORTs of type DHWMTR. Water use is reported in gallons.
DHWMETERs account for water use in the following pre-defined end uses. The abbreviations in parentheses are used in DHWMTR report headings.
- Total water use (Total)
- Unknown end use (Unknown)
- Miscellaneous draws (Faucet)
- Shower (Shower)
- Bathtub (Bath)
- Clothes washer (CWashr)
- Dishwasher (DWashr)
DHWSYS items wsWHhwMtr and wsFXhwMtr specify the DHWMETER(s) to which water consumption is accumulated.
dhwMtrName
Name of meter: required for assigning water uses to the DHWMETER.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
endDhwMeter
Related Probes:
4.12 AFMETER
An AFMETER object is a user-defined “device” that records zone air flows as simulated by CSE. The user defines AFMETERs and assigns them to zones (see ZONE znAFMtr).
Air flow is recorded in standard air cfm (density 0.075 lb/ft3) at subhour, hour, day, month, and year intervals. At intervals of an hour and longer, values are averaged. Flows are categorized according to IZXFER izAFCat.
If any AFMETERs are defined, an additional AFMETER “sum_of_AFMETERs” is automatically created where the sums of all user-define AFMETERs are accumulated.
Note that only AirNet flows are recorded.
AFMETER results can be REPORTed using rpType=AFMTR (or EXPORTed using exType=AFMTR). See Air Flow Meter Report.
afMtrName
Name of meter: required for assigning air flows to the AFMETER.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
endAFMeter
Indicates the end of the meter definition. Alternatively, the end of the meter definition can be indicated by the declaration of another object or by END.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.13 LOADMETER
A LOADMETER object is a user-defined “device” that records heating and cooling loads as computed by CSE. The user defines LOADMETERs and assigns them to ZONEs and/or RSYSs (see ZONE znLoadMtr and RSYS rsLoadMtr).
Loads are accumulated for subhour, hour, day, month, and annual intervals. All values are in Btu. Values >0 indicated heat into the process or zone – thus heating loads are >0 and cooling loads are <0.
LOADMETER results must be reported using user-defined REPORTs or EXPORTs. For example –
REPORT rpType=UDT rpFreq=Month rpDayBeg=Jan 1 rpDayEnd=Dec 31
REPORTCOL colHead="mon" colVal=$Month colWid=3
REPORTCOL colHead="Heating" colVal=@LoadMeter[ 1].M.qHtg colDec=0 colWid=10
REPORTCOL colHead="Cooling" colVal=@LoadMeter[ 1].M.qClg colDec=0 colWid=10
ldMtrName
Name of LOADMETER: required for assigning to ZONEs and RSYSs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
lmtSubmeters=list of up to 50 LOADMETERs
A comma-separate list of LOADMETERs that are accumulated into this LOADMETER with optional multipliers (see lmtSubmeterMults). Submeters facilitate flexible categorization of loads results. In addition, use of lmtSubmeterMults allows load results from a representative model to be scaled and included in overall results. For example, a typical zone could be used to represent 5 similar spaces. The loads calculated for the typical zone could be assigned to a dedicated LOADMETER and that LOADMETER accumulated to a main LOADMETER with a multiplier of 5. Rules –
- A LOADMETER cannot reference itself as a submeter.
- A given LOADMETER can be referenced only once in the lmtSubmeters list.
- Circular references are not allowed.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
names of LOADMETERs | No | constant |
lmtSubmeterMults=list of up to 50 floats
Submeter multipliers.
A note re default values: if lmtSubmeterMults is omitted, all multipliers are defaulted to 1. However, when lmtSubmeterMults is included, a multiplier value should be provided for each LOADMETER listed in lmtSubmeters since unspecified values are set to 0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1 | No | subhourly |
endLOADMETER
Indicates the end of the meter definition. Alternatively, the end of the meter definition can be indicated by the declaration of another object or by END.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.14 ZONE
ZONE constructs an object of class ZONE, which describes an area of the building to be modeled as having a uniform condition. ZONEs are large, complex objects and can have many subobjects that describe associated surfaces, shading devices, HVAC equipment, etc.
4.14.1 ZONE General Members
znName
Name of zone. Enter after the word ZONE; no “=” is used.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
znModel=choice
Selects model for zone.
CNE | Older central difference model based on original CALPAS methods. Not fully supported and not suitable for current compliance applications. |
CZM | Conditioned zone model. Forward-difference, short time step methods are used. |
UZM | Unconditioned zone model. Identical to CZM except heating and cooling are not supported. Typically used for attics, garages, and other ancillary spaces. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | CNE | No | constant |
znArea=float
Nominal zone floor area.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(>\) 0 | none | Yes | constant |
znVol=float
Nominal zone volume.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft3 | x \(>\) 0 | none | Yes | constant |
znAzm=float
Zone azimuth with respect to bldgAzm. All surface azimuths are relative to znAzm, so that the zone can be rotated by changing this member only. Values outside the range 0o to 360o are normalized to that range.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
degrees | unrestricted | 0 | No | constant |
znFloorZ=float
Nominal zone floor height relative to arbitrary 0 level. Used re determination of vent heights
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | unrestricted | 0 | No | constant |
znCeilingHt=float
Nominal zone ceiling height relative to zone floor (typically 8 – 10 ft).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | znVol / znArea | No | constant |
znEaveZ=float
Nominal eave height above ground level. Used re calculation of local surface wind speed. This in turn influences outside convection coefficients in some surface models and wind-driven air leakage.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | znFloorZ + infStories8* | No | constant |
znCAir=float
Zone “air” heat capacity: represents heat capacity of air, furniture, “light” walls, and everything in zone except surfaces having heat capacity (that is, non-QUICK surfaces).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/oF | x \(\geq\) 0 | 3.5 znArea* | No | constant |
znHcAirX=float
Zone air exchange rate used in determination of interior surface convective coefficients. This item is generally used only for model testing.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ACH | x \(>\) 0 | as modeled | No | subhourly |
znHcFrcF=float
Zone surface forced convection factor. Interior surface convective transfer is modeled as a combination of forced and natural convection. hcFrc = znHcFrcF * znHcAirX^.8. See CSE Engineering Documentation.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | .2 | .2 | No | hourly |
znHIRatio=float
Zone hygric inertia ratio. In zone moisture balance calculations, the effective dry-air mass = znHIRatio * (zone dry air mass). This enhancement can be used to represente the moisture storage capacity of zone surfaces and contents.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
znSC=float
Zone shade closure. Determines insolation through windows (see WINDOW members wnSCSO and wnSCSC) and solar gain distribution: see SGDIST members sgFSO and sgFSC. 0 represents shades open; 1 represents shades closed; intermediate values are allowed. An hourly variable CSE expression may be used to schedule shade closure as a function of weather, time of year, previous interval HVAC use or zone temperature, etc.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\leq\) x \(\leq\) 1 | 1 when cooling was used in previous hour, else 0 | No | hourly |
znTH=float
Heating set point used (and required) when znModel=CZM and zone has no terminals.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | 0 < znTH < znTC | none | Per above | subhourly |
znTD=float
Desired set point (temperature maintained with ventilation if possible) for znModel=CZM. Must be specified when zone ventilation is active.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x > 0; znTH < znTD < znTC | none | if venting | subhourly |
znTC=float
Cooling set point used (and required) when znModel=CZM and zone has no terminals.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | 0 < znTC > znTH | none | Per above | subhourly |
znModel = CZM zone heating and cooling is provided either via an RSYS HVAC system, by “magic” heat transfers specified by znQxxx items, or via TERMINAL (s). One of these must be defined.
znRSys=rsysName
Name of RSYS providing heating, cooling, and optional central fan integrated ventilation to this zone.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
RSYS name | (no RSYS) | No | constant |
znQMxH=float
Heating capacity at current conditions
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\geq\) 0 | none | No | hourly |
znQMxHRated=float
Rated heating capacity
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\geq\) 0 | none | No | constant |
znQMxC=float
Cooling capacity at current conditions
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\leq\) 0 | none | No | hourly |
znQMxCRated=float
Rated cooling capacity
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\leq\) 0 | none | No | constant |
4.14.2 ZONE Infiltration
The following control a simplified air change plus leakage area model. The Sherman-Grimsrud model is used to derive air flow rate from leakage area and this rate is added to the air changes specified with infAC. Note that TOP.windF does not modify calculated infiltration rates, since the Sherman-Grimsrud model uses its own modifiers. See also AirNet models available via IZXFER.
infAC=float
Zone infiltration air changes per hour.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1/hr | x \(\geq\) 0 | 0.5 | No | hourly |
infELA=float
Zone effective leakage area (ELA).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
in2 | x \(\geq\) 0 | 0.0 | No | hourly |
infShld=int
Zone local shielding class, used in derivation of local wind speed for ELA infiltration model, wind-driven AirNet leakage, and exterior surface coefficients. infShld values are –
1 | no obstructions or local shielding |
2 | light local shielding with few obstructions |
3 | moderate local shielding, some obstructions within two house heights |
4 | heavy shielding, obstructions around most of the perimeter |
5 | very heavy shielding, large obstructions surrounding the perimeter within two house heights |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1 \(\leq\) x \(\leq\) 5 | 3 | No | constant |
infStories=int
Number of stories in zone, used in ELA model.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1 \(\leq\) x \(\leq\) 3 | 1 | No | constant |
znWindFLkg=float
Wind speed modifier factor. The weather file wind speed is multiplied by this factor to yield a local wind speed for use in infiltration and convection models.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | derived from znEaveZ and infShld | No | constant |
znAFMtr=afMtrName
Name of an AFMETER object, if any, to which zone AirNet air flows are recorded. ZnAFMtr defines a pressure boundary for accounting purposes. Multiple zones having the same AFMETER are treated as a single volume – interzone flows within that volume are not recorded. For example, to obtain “building total” flow data, a common AFMETER could be assigned to several conditioned zones but not to adjacent unconditioned zones such as attic spaces.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of an AFMETER | not recorded | No | constant |
znLoadMtr=ldMtrName
Name of a LOADMETER object, if any, to which zone heating and cooling loads are recorded.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a LOADMETER | not recorded | No | constant |
4.14.3 ZONE Exhaust Fan
Presence of an exhaust fan in a zone is indicated by specifying a non-zero design flow value (xfanVfDs).
Zone exhaust fan model implementation is incomplete as of July, 2011. The current code calculates energy use but does not account for the effects of air transfer on room heat balance. IZXFER provides a more complete implementation.
xfanFOn=float
Exhaust fan on fraction. On/off control assumed, so electricity requirement is proportional to run time.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | 1 | No | hourly |
Example: The following would run an exhaust fan 70% of the time between 8 AM and 5 PM:
xfanFOn = select( (\$hour >= 7 && \$hour < 5), .7,
default, 0 );
xfanVfDs=float
Exhaust fan design flow; 0 or not given indicates no fan.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\geq\) 0 | 0, no fan | If fan present | constant |
xfanPress=float
Exhaust fan external static pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
inches | 0.05 \(\leq\) x \(\leq\) 1.0 | 0.3 | No | constant |
Only one of xfanElecPwr, xfanEff, and xfanShaftBhp may be given: together with xfanVfDs and xfanPress, any one is sufficient for CSE to detemine the others and to compute the fan heat contribution to the air stream.
xfanElecPwr=float
Fan input power per unit air flow (at design flow and pressure).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | x \(>\) 0 | derived from xfanEff | If xfanEff and xfanShaftBhp not present | constant |
xfanEff=float
Exhaust fan/motor/drive combined efficiency.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | 0.08 | No | constant |
xfanShaftBhp=float
Fan shaft power at design flow and pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
BHP | x \(>\) 0 | derived from xfanElecPwr and xfanVfDs | If xfanElecPwr not present | constant |
xfanMtr=mtrName
Name of METER object, if any, by which fan’s energy use is recorded (under end use category “fan”).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
endZone
Indicates the end of the zone definition. Alternatively, the end of the zone definition can be indicated by the declaration of another object or by “END”. If END or endZone is used, it should follow the definitions of the ZONE’s subobjects such as GAINs, SURFACEs, TERMINALs, etc.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.15 GAIN
A GAIN object adds sensible and/or latent heat to the ZONE, and/or adds arbitrary energy use to a METER. GAINs may be subobjects of ZONEs and are normally given within the input for their ZONE. As many GAINs as desired (or none) may be given for each ZONE. Alternatively, GAINs may be subobjects of TOP and specify gnZone to specify their associate zone.
Each gain has an amount of power (gnPower), which may optionally be accumulated to a METER (gnMeter). The power may be distributed to the zone, plenum, or return as sensible heat with an optional fraction radiant, or to the zone as latent heat (moisture addition), or not.
4.15.1 Gain zones
The gain to the zone may be further divided into convective sensible, radiant sensible and latent heat via the gnFrRad and gnFrLat members; the plenum and return gains are assumed all convective sensible.
In the CNE zone mode, the radiant internal gain is distributed to the surfaces in the zone, rather than going directly to the zone “air” heat capacity (znCAir). A simple model is used – all surfaces are assumed to be opaque and to have the same (infrared) absorptivity – even windows. Along with the assumption that the zone is spherical (implicit in the current treatment of solar gains), this allows distribution of gains to surfaces in proportion to their area, without any absorptivity or transmissivity calculations. The gain for windows and quick-model surfaces is assigned to the znCAir, except for the portion which conducts through the surface to the other side rather than through the surface film to the adjacent zone air; the gain to massive (delayed-model) surfaces is assigned to the side of surface in the zone with the gain.
Radiant internal gains are included in the IgnS (Sensible Internal Gain) column in the zone energy balance reports. (They could easily be shown in a separate IgnR column if desired.) Any energy transfer shows two places in the ZEB report, with opposite signs, so that the result is zero – otherwise it wouldn’t be an energy balance. The rest of the reporting story for radiant internal gains turns out to be complex. The specified value of the radiant gain (gnPower * gnFrZn * gnFrRad) shows in the IgnS column. To the extent that the gain heats the zone, it also shows negatively in the Masses column, because the zone CAir is lumped with the other masses. To the extent that the gain heats massive surfaces, it also shows negatively in the masses column. To the extent that the gain conducts through windows and quick-model surfaces, it shows negatively in the Conduction column. If the gain conducts through a quick-model surface to another zone, it shows negatively in the Izone (Interzone) column, positively in the Izone column of the receiving zone, and negatively in the receiving zone’s Masses or Cond column.
gnName
Name of gain; follows the word GAIN if given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
gnZone=znName
Name of ZONE to which heat gains are added. Omitted when GAIN is given as a ZONE subobject. If a TOP subobject (i.e., not a ZONE subobject) and znZone is omitted, heat gains are discarded but energy use is still recorded to gnMeter. This feature can be used to represent energy uses that our outside of conditioned zones (e.g. exterior lighting).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of ZONE | parent zone if any | No | constant |
gnPower=float
Rate of heat addition/energy use. Negative gnPower values may be used to represent heat removal/energy generation. Expressions containing functions are commonly used with this member to schedule the gain power on a daily and/or hourly basis. Refer to the functions section in Section 4 for details and examples.
All gains, including electrical, are specified in Btuh units unless associated with DHW use (see gnCtrlDHWSYS), in which case gnPower is specified in Btuh/gal. Note that meter reporting of internal gain is in MBtu (millions of Btu) by default.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | no restrictions | none | Yes | hourly |
gnMeter=choice
Name of meter by which this GAIN’s gnPower is recorded. If omitted, gain is assigned to no meter and energy use is not accounted in CSE simulation reports; thus, gnMeter should only be omitted for “free” energy sources.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of METER | none | No | constant |
gnEndUse=choice
Meter end use to which the GAIN’s energy use should be accumulated.
Clg | Cooling |
Htg | Heating (includes heat pump compressor) |
HPBU | Heat pump resistance heating (backup and defrost) |
DHW | Domestic (service) hot water |
DHWBU | Domestic (service) hot water heating backup (HPWH resistance) |
DHWMFL | Domestic (service) hot water heating multi-family loop pumping and loss makeup |
FANC | Fans, AC and cooling ventilation |
FANH | Fans, heating |
FANV | Fans, IAQ venting |
FAN | Fans, other purposes |
AUX | HVAC auxiliaries such as pumps |
PROC | Process |
LIT | Lighting |
RCP | Receptacles |
EXT | Exterior lighting |
REFR | Refrigeration |
DISH | Dishwashing |
DRY | Clothes drying |
WASH | Clothes washing |
COOK | Cooking |
USER1 | User-defined category 1 |
USER2 | User-defined category 2 |
BT | Battery charge power |
PV | Photovoltaic power generation |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | none | Required if gnMeter is given | constant |
The gnFrZn, gnFrPl, and gnFrRtn members allow you to allocate the gain among the zone, the zone’s plenum, and the zone’s return air flow. Values that total to more than 1.0 constitute an error. If they total less than 1, the unallocated portion of the gain is recorded by the meter (if specified) but not transferred into the building. By default, all of the gain not directed to the return or plenum goes to the zone.
gnFrZn=float
Fraction of gain going to zone. gnFrLat (below) gives portion of this gain that is latent, if any; the remainder is sensible.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\leq\) x \(\leq\) 1 | 1. | No | hourly |
gnFrPl=float
Fraction of gain going to plenum.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gnFrZn + gnFrPl + gnFrRtn \(\leq\) 1 | 0. | No | hourly |
gnFrRtn=float
Fraction of gain going to return.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gnFrZn + gnFrPl + gnFrRtn \(\leq\) 1 | 0. | No | hourly |
gnFrRad=float
Fraction of total gain going to zone (gnFrZn) that is radiant rather than convective or latent.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\leq\) x \(\leq\) 1 | 0.0 | No | hourly |
gnFrLat=float
Fraction of total gain going to zone (gnFrZn) that is latent heat (moisture addition).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.0 | No | hourly |
gnDlFrPow=float
Hourly power reduction factor, typically used to modify lighting power to account for daylighting.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 1.0 | No | hourly |
gnCtrlDHWSYS=dhwsysName
Name of a DHWSYS whose water use modulates gnPower. For example, electricity use of water-using appliances (e.g. dishwasher or clothes washer) can be modeled based on water use, ensuring that the uses are synchronized. When this feature is used, gnPower should be specified in Btuh/gal.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a DHWSYS | no DHWSYS/GAIN linkage | No | constant |
gnCtrlDHWMETER=dhwMtrName
Allows gains to track water usage such as dishwashers, clothes washers, etc.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of DHWMETER | 0 | No | constant |
gnCtrlDHWEndUse=dhwEndUseName
Name of the DHWSYS end use consumption that modulates gnPower. See DHWMETER for DHW end use definitions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
DHW end use | Total | No | constant |
endGain
Optional to indicate the end of the GAIN definition. Alternatively, the end of the gain definition can be indicated by END or by the declaration of another object.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
- @gain
4.16 SURFACE
Surface constructs a ZONE subobject of class SURFACE that represents a surrounding or interior surface of the zone. Internally, SURFACE generates a QUICK surface (U-value only), a DELAYED (massive) surface (using the finite-difference mass model), interzone QUICK surface, or interzone DELAYED surface, as appropriate for the specified construction and exterior conditions.
sfName
Name of surface; give after the word SURFACE.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
sfType=choice
Type of surface:
FLOOR | Surface defines part or all of the ‘bottom’ of the zone; it is horizontal with inside facing up. The outside of the surface is not adjacent to the current zone. |
WALL | Surface defines a ‘side’ of the zone; its outside is not adjacent to the current zone. |
CEILING | Surface defines part or all of the ‘top’ of the zone with the inside facing down. The outside of the surface is not adjacent to the current zone. |
sfType is used extensively for default determination and input checking, but does not have any further internal effect. The Floor, Wall, and Ceiling choices identify surfaces that form boundaries between the zone and some other condition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
FLOOR WALL CEILING | none | Yes | constant |
sfArea=float
Gross area of surface. (CSE computes the net area for simulation by subtracting the areas of any windows and doors in the surface.).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(>\) 0 | none | Yes | constant |
sfTilt=float
Surface tilt from horizontal. Values outside the range 0 to 360 are first normalized to that range. The default and allowed range depend on sfType, as follows:
sfType = FLOOR | sfTilt=180, default = 180 (fixed value) |
sfType = WALL | 60 \(<\) sfTilt \(<\) 180, default = 90 |
sfType = CEILING | 0 \(\leq\) sfTilt \(\leq\) 60, default = 0 |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
degrees | Dependent upon sfType See above | Dependent upon sfType See above | No | constant |
sfAzm=float
Azimuth of surface with respect to znAzm. The azimuth used in simulating a surface is bldgAzm + znAzm + sfAzm; the surface is rotated if any of those are changed. Values outside the range 0 to 360 are normalized to that range. Required for non-horizontal surfaces.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
degrees | unrestricted | none | Required if sfTilt \(\neq\) 0 and sfTilt \(\neq\) 180 | constant |
sfModel=choice
Provides user control over how CSE models conduction for this surface.
QUICK | Surface is modeled using a simple conductance. Heat capacity effects are ignored. Either sfCon or sfU (next) can be specified. |
DELAYED, DELAYED_HOUR, DELAYED_SUBHOUR | Surface is modeled using a multi-layer finite difference technique that represents heat capacity effects. If the time constant of the surface is too short to accurately simulate, a warning message is issued and the Quick model is used. The program cannot use the finite difference model if sfU rather than sfCon is specified. |
AUTO | Program selects Quick or the appropriate Delayed automatically according to the time constant of the surface (if sfU is specified, Quick is selected). |
FD (or FORWARD_DIFFERENCE) | Selects the forward difference model (used with short time steps and the CZM/UZM zone model). |
KIVA | Uses a two-dimensional finite difference model to simulate heat flow through foundation surfaces. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | QUICK, DELAYED, DELAYED_HOUR, DELAYED_SUBOUR , AUTO, 2D_FND | AUTO | No | constant |
Either sfU or sfCon must be specified, but not both.
sfU=float
Surface U-value (NOT including surface (air film) conductances). For surfaces for which no heat capacity is to be modeled, allows direct entry of U-value without defining a CONSTRUCTION.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | Determined from sfCon | if sfCon not given | constant |
sfCon=conName
Name of CONSTRUCTION of the surface.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Name of a CONSTRUCTION | none | unless sfU given | constant |
sfLThkF=float
Sublayer thickness adjustment factor for FORWARD_DIFFERENCE conduction model used with sfCon surfaces. Material layers in the construction are divided into sublayers as needed for numerical stability. sfLThkF allows adjustment of the thickness criterion used for subdivision. A value of 0 prevents subdivision; the default value (0.5) uses layers with conservative thickness equal to half of an estimated safe value. Fewer (thicker) sublayers improves runtime at the expense of accurate representation of rapid changes.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0.5 | No | constant |
sfExCnd=choice
Specifies the thermal conditions assumed at surface exterior, and at exterior of any subobjects (windows or doors) belonging to current surface. The conditions accounted for are dry bulb temperature and incident solar radiation.
AMBIENT | Exterior surface is exposed to the ‘weather’ as read from the weather file. Solar gain is calculated using solar geometry, sfAzm, sfTilt, and sfExAbs. |
SPECIFIEDT | Exterior surface is exposed to solar radiation as in AMBIENT, but the dry bulb temperature is calculated with a user specified function (sfExT). sfExAbs can be set to 0 to eliminate solar effects. |
ADJZN | Exterior surface is exposed to another zone, whose name is specified by sfAdjZn. Solar gain is 0 unless gain is targeted to the surface with SGDIST below. |
GROUND | The surface is in contact with the ground. Details of the two-dimensional foundation design are defined by sfFnd. Only floor and wall surfaces may use this option. |
ADIABATIC | Exterior surface heat flow is 0. Thermal storage effects of delayed surfaces are modeled. |
sfExAbs=float
Surface exterior absorptivity.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.5 | Required if sfExCnd = AMBIENT or sfExCnd = SPECIFIEDT | monthly-hourly |
sfInAbs=float
Surface interior solar absorptivity.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(le\) 1 | sfType = CEILING, 0.2; sfType = WALL, 0.6; sfType = FLOOR, 0.8 | No | monthly-hourly |
sfExEpsLW=float
Surface exterior long wave (thermal) emittance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.9 | No | constant |
sfInEpsLW=float
Surface interior long wave (thermal) emittance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.9 | No | constant |
sfExT=float
Exterior air temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | unrestricted | none | Required if sfExCnd = SPECIFIEDT | hourly |
sfAdjZn=znName
Name of adjacent zone; used only when sfExCnd is ADJZN. Can be the same as the current zone.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | none | Required when sfExCnd = ADJZN | constant |
sfGrndRefl=float
Ground reflectivity for this surface.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | grndRefl | No | Monthly - Hourly |
sfInH=float
Inside surface (air film) conductance. Ignored for sfModel = Forward_Difference. Default depends on the surface type.
sfType = FLOOR or CEILING | 1.32 |
other | 1.5 |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | See above | No | constant |
sfExH=float
Outside combined surface (air film) conductance. Ignored for sfModel = Forward_Difference. The default value is dependent upon the exterior conditions:
sfExCnd = AMBIENT | dflExH (Top-level member, described above) |
sfExCnd = SPECIFIEDT | dflExH (described above) |
sfExCnd = ADJZN | 1.5 |
sfExCnd = ADIABATIC | not applicable |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | see above | No | constant |
When sfModel = Forward_Difference, several models are available for calculating inside and outside surface convective coefficients. Inside surface faces can be exposed only to zone conditions. Outside faces may be exposed either to ambient conditions or zone conditions, based on sfExCnd. Only UNIFIED and INPUT are typically used. The other models were used during CSE development for comparison. For details, see CSE Engineering Documentation.
Model | Exposed to ambient | Exposed to zone |
---|---|---|
UNIFIED | default CSE model | default CSE model |
INPUT | hc = sfExHcMult | hc = sfxxHcMult |
AKBARI | Akbari model | n/a |
WALTON | Walton model | n/a |
WINKELMANN | Winkelmann model | n/a |
DOE2 | DOE2 model | n/a |
MILLS | n/a | Mills model |
ASHRAE | n/a | ASHRAE handbook values |
TARP | n/a | TARP model |
sfExHcModel=choice
Selects the model used for exterior surface convection when sfModel = Forward_Difference.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | UNIFIED | No | constant |
sfExHcLChar=float
Characteristic length of surface, used in derivation of forced exterior convection coefficients in some models when outside surface is exposed to ambient. See sfExHcModel.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | 10 | No | constant |
sfExHcMult=float
Exterior convection coefficient adjustment factor. When sfExHcModel=INPUT, hc=sfExHcMult. For other sfExHcModel choices, the model-derived hc is multiplied by sfExHcMult.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | subhourly |
sfExRf=float
Exterior surface roughness factor. Used only when surface is exposed to ambient (i.e. with wind exposure). Typical values:
Roughness Index | sfExRf | Example |
---|---|---|
1 (very rough) | 2.17 | Stucco |
2 (rough) | 1.67 | Brick |
3 (medium rough) | 1.52 | Concrete |
4 (Medium smooth) | 1.13 | Clear pine |
5 (Smooth) | 1.11 | Smooth plaster |
6 (Very Smooth) | 1 | Glass |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
sfExHcModel = WINKELMANN: 1.66 else 2.17 | No | constant |
sfInHcModel=choice
Selects the model used for the inside (zone) surface convection when sfModel = Forward_Difference.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above (see sfExHcModel) | UNIFIED | No | constant |
sfInHcMult=float
Interior convection coefficient adjustment factor. When sfInHcModel=INPUT, hc=sfInHcMult. For other sfInHcModel choices, the model-derived hc is multiplied by sfInHcMult.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | subhourly |
The items below give values associated with CSE’s model for below grade surfaces (sfExCnd=GROUND). See CSE Engineering Documentation for technical details.
sfFnd=fdName
Name of FOUNDATION applied to ground-contact Floor SURFACEs; used only for Floor SURFACEs when sfExCnd is GROUND.
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
– | Name of a Foundation | none | when sfExCnd = GROUND and sfType = Floor | constant |
sfFndFloor=sfName
Name of adjacent ground-contact Floor SURFACE; used only for Wall SURFACEs when sfExCnd is GROUND.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | Name of a Surface | none | when sfExCnd = GROUND and sfType = Wall | constant |
sfHeight=float
Needed for foundation wall height, otherwise ignored. Maybe combine with sfDepthBG?
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | none | when sfType is WALL and sfExtCnd is GROUND | constant |
sfExpPerim=float
Exposed perimeter of foundation floors.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\geq\) 0 | none | when sfType is FLOOR, sfFnd is set, and sfExtCnd is GROUND | constant |
sfDepthBG=float
Note: sfDepthBG is used as part of the simple ground model, which is no longer supported. Use sfHeight with sfFnd instead.
Depth below grade of surface. For walls, sfDepthBG is measured to the lower edge. For floors, sfDepthBG is measured to the bottom face.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | none | No | constant |
Note: The following data members are part of the simple ground model, which is no longer supported. Use sfFnd instead.
sfExCTGrnd=float
sfExCTaDbAvg07=float
sfExCTaDbAvg14=float
sfExCTaDbAvg31=float
sfExCTaDbAvgYr=float
Conductances from outside face of surface to the weather file ground temperature and the moving average outdoor dry-bulb temperatures for 7, 14, 31, and 365 days.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(\ge\) 0 | see above | No | constant |
sfExRConGrnd=float
Resistance overall construction resistance. TODO: full documentation.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | none | No | constant |
endSURFACE
Optional to indicates the end of the surface definition. Alternatively, the end of the surface definition can be indicated by END, or by beginning another SURFACE or other object definition. If used, should follow the definitions of the SURFACE’s subobjects – DOORs, WINDOWs, SHADEs, SGDISTs, etc.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.17 WINDOW
WINDOW defines a subobject belonging to the current SURFACE that represents one or more identical windows. The azimuth, tilt, and exterior conditions of the window are the same as those of the surface to which it belongs. The total window area (wnHt \(\cdot\) wnWid \(\cdot\) wnMult) is deducted from the gross surface area. A surface may have any number of windows.
Windows may optionally have operable interior shading that reduces the overall shading coefficient when closed.
wnName
Name of window: follows the word “WINDOW” if given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wnHeight=float
Overall height of window (including frame).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | none | Yes | constant |
wnWidth=float
Overall width of window (including frame).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | none | Yes | constant |
wnArea=float
Overall area of window (including frame).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(>\) 0 | wnHeight wnWidth* | No | constant |
wnMult=float
Area multiplier; can be used to represent multiple identical windows.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
wnModel=choice
Selects window model
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
SHGC, ASHWAT | SHGC | No | constant |
wnGt=choice
GLAZETYPE for window. Provides many defaults for window properties as cited below.
wnU=float
Window conductance (U-factor without surface films, therefore not actually a U-factor but a C-factor).
Preferred Approach: To use accurately with standard winter rated U-factor from ASHRAE or NFRC enter as:
wnU = (1/((1/U-factor)-0.85)
Where 0.85 is the sum of the interior (0.68) and exterior (0.17) design air film resistances assumed for rating window U-factors. Enter wnInH (usually 1.5=1/0.68) instead of letting it default. Enter the wnExH or let it default. It is important to use this approach if the input includes gnFrad for any gain term. Using approach 2 below will result in an inappropriate internal gain split at the window.
Approach 2. Enter wnU=U-factor and let the wnInH and wnExH default. Tnormally this approach systematically underestimates the window U-factor because it adds the wnExfilm resistance to 1/U-factor thereby double counting the exterior film resistance. This approach will also yield incorrect results for gnFrad internal gain since the high wnInH will put almost all the gain back in the space.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | none | Yes | constant |
wnUNFRC=float
Fenestration system (including frame) U-factor evaluated at NFRC heating conditions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | gtUNFRC | Required when wnModel = ASHWAT | constant |
wnExEpsLW=float
Window exterior long wave (thermal) emittance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.84 | No | constant |
wnInEpsLW=float
Window interior long wave (thermal) emittance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.84 | No | constant |
wnInH=float
Window interior surface (air film) conductance.
Preferred Approach: Enter the appropriate value for each window, normally:
wnInH = 1.5
where 1.5 = 1/0.68 the standard ASHRAE value.
The large default value of 10,000 represents a near-0 resistance, for the convenience of those who wish to include the interior surface film in wnU according to approach 2 above.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | 10000 | No | constant |
wnExH=float
Window exterior surface (air film) conductance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | same as owning surface | No | constant |
Several models are available for calculating inside and outside surface convective coefficients. Inside surface faces can be exposed only to zone conditions. Outside faces may be exposed either to ambient conditions or zone conditions, based on wnExCnd. Only UNIFIED and INPUT are typically used. The other models were used during CSE development for comparison. For details, see CSE Engineering Documentation.
Model | Exposed to ambient | Exposed to zone |
---|---|---|
UNIFIED | default CSE model | default CSE model |
INPUT | hc = wnExHcMult | hc = wnxxHcMult |
AKBARI | Akbari model | n/a |
WALTON | Walton model | n/a |
WINKELMANN | Winkelmann model | n/a |
MILLS | n/a | Mills model |
ASHRAE | n/a | ASHRAE handbook values |
wnExHcModel=choice
Selects the model used for exterior surface convection when wnModel = Forward_Difference.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | UNIFIED | No | constant |
wnExHcLChar=float
Characteristic length of surface, used in derivation of forced exterior convection coefficients in some models when outside face is exposed to ambient (i.e. to wind).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | 10 | No | constant |
wnExHcMult=float
Exterior convection coefficient adjustment factor. When wnExHcModel=INPUT, hc=wnExHcMult. For other wnExHcModel choices, the model-derived hc is multiplied by wnExHcMult.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | subhourly |
wnInHcModel=choice
Selects the model used for the inside (zone) surface convection when wnModel = Forward_Difference.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above (see wnExHcModel) | UNIFIED | No | constant |
wnInHcMult=float
Interior convection coefficient adjustment factor. When wnInHcModel=INPUT, hc=wnInHcMult. For other wnInHcModel choices, the model-derived hc is multiplied by wnInHcMult.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | subhourly |
wnSHGC=float
Rated Solar Heat Gain Coefficient (SHGC) for the window assembly.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 < x < 1 | gtSHGC | No | constant |
wnFMult=float
Frame area multiplier = areaGlaze / areaAssembly
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 < x < 1 | gtFMult or 1 | No | constant |
wnSMSO=float
SHGC multiplier with shades open. Overrides gtSMSO.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | gtSMSO or 1 | No | Monthly - Hourly |
wnSMSC=float
SHGC multiplier with shades closed. Overrides gtSMSC
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(leq\) x \(leq\) 1 | wnSMSO or gtSMSC | No | Monthly - Hourly |
wnNGlz=int
Number of glazings in the window (bare glass only, not including any interior or exterior shades).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) x \(leq\) 4 | gtNGLZ | Required when wnModel = ASHWAT | constant |
wnExShd=choice
Exterior shading type (ASHWAT only).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NONE, INSCRN | gtExShd | No | constant |
wnInShd=choice
Interior shade type (ASHWAT only).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NONE, DRAPEMED | gtInShd | No | constant |
wnDirtLoss=float
Glazing dirt loss factor.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | none | No | constant |
wnGrndRefl=float
Ground reflectivity for this window.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | sfGrndRefl | No | Monthly - Hourly |
wnVfSkyDf=float
View factor from this window to sky for diffuse radiation. For the shading effects of an overhang, a wnVfSkyDf value smaller than the default would be used
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | 0.5 - 0.5 cos(tilt) = .5 for vertical surface | No | Monthly - Hourly |
wnVfGrndDf=float
View factor from this window to ground for diffuse radiation. For the shading effects of a fin(s), both wnVfSkyDf and wnVfGrndDf would be used.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fraction | 0 \(\leq\) x \(\leq\) 1 | 0.5 + 0.5 .5 for vertical surface | No | Monthly - Hourly |
endWINDOW
Optionally indicates the end of the window definition. Alternatively, the end of the window definition can be indicated by END or the declaration of another object. END or endWindow, if used, should follow any subobjects of the window (SHADEs and/or SGDISTs).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.18 SHADE
SHADE constructs a subobject associated with the current WINDOW that represents fixed shading devices (overhangs and/or fins). A window may have at most one SHADE and only windows in vertical surfaces may have SHADEs. A SHADE can describe an overhang, a left fin, and/or a right fin; absence of any of these is specified by omitting or giving 0 for its depth. SHADE geometry can vary on a monthly basis, allowing modeling of awnings or other seasonal shading strategies.
shName
Name of shade; follows the word “SHADE” if given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
ohDepth=float
Depth of overhang (from plane of window to outside edge of overhang). A zero value indicates no overhang.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
ohDistUp=float
Distance from top of window to bottom of overhang.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
ohExL=float
Distance from left edge of window (as viewed from the outside) to the left end of the overhang.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
ohExR=float
Distance from right edge of window (as viewed from the outside) to the right end of the overhang.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
ohFlap=float
Height of flap hanging down from outer edge of overhang.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
lfDepth=float
Depth of left fin from plane of window. A zero value indicates no fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
lfTopUp=float
Vertical distance from top of window to top of left fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
lfDistL=float
Distance from left edge of window to left fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
lfBotUp=float
Vertical distance from bottom of window to bottom of left fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
rfDepth=float
Depth of right fin from plane of window. A 0 value indicates no fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
rfTopUp=float
Vertical distance from top of window to top of right fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
rfDistR=float
Distance from right edge of window to right fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
rfBotUp=float
Vertical distance from bottom of window to bottom of right fin.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | monthly-hourly |
endShade
Optional to indicate the end of the SHADE definition. Alternatively, the end of the shade definition can be indicated by END or the declaration of another object.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.19 SGDIST
SGDIST creates a subobject of the current window that distributes a specified fraction of that window’s solar gain to a specified delayed model (massive) surface. Any remaining solar gain (all of the window’s solar gain if no SGDISTs are given) is added to the air of the zone containing the window. A window may have up to three SGDISTs; an error occurs if more than 100% of the window’s gain is distributed.
Via members sgFSO and sgFSC, the fraction of the insolation distributed to the surface can be made dependent on whether the zone’s shades are open or closed (see ZONE member znSC).
sgName
Name of solar gain distribution (follows “SGDIST” if given).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
sgSurf=sfName
Name of surface to which gain is targeted.
If there is more than surface with the specified name: if one of the surfaces is in the current zone, it is used; otherwise, an error message is issued.
The specified surface must be modeled with the Delayed model. If gain is targeted to a Quick model surface, a warning message is issued and the gain is redirected to the air of the associated zone.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a SURFACE | none | Yes | constant |
sgSide=choice
Designates the side of the surface to which the gain is to be targeted:
INTERIOR | Apply gain to interior of surface |
EXTERIOR | Apply gain to exterior of surface |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
INTERIOR, EXTERIOR | Side of surface in zone containing window; or INTERIOR if both sides are in zone containing window. | Yes | constant |
sgFSO=float
Fraction of solar gain directed to specified surface when the owning window’s interior shading is in the open position (when the window’s zone’s shade closure (znSC) is 0).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1,and sum of window’s sgFSO’s \(\le\) 1 | none | Yes | monthly-hourly |
sgFSC=float
Fraction of solar gain directed to specified surface when the owning window’s interior shading is in the closed position. If the zone’s shades are partly closed (znSC between 0 and 1), a proportional fraction between sgFSO and sgFSC is used.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1, and sum of window’s sgFSC’s \(\le\) 1 | sgFSO | No | monthly-hourly |
endSGDist
Optionally indicates the end of the solar gain distribution definition. Alternatively, the end of the solar gain distribution definition can be indicated by END or by just beginning another object.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.20 DOOR
DOOR constructs a subobject belonging to the current SURFACE. The azimuth, tilt, ground reflectivity and exterior conditions associated with the door are the same as those of the owning surface, although the exterior surface conductance and the exterior absorptivity can be altered.
drName
Name of door.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
drArea=float
Overall area of door.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(>\) 0 | none | Yes | constant |
drModel=choice
Provides user control over how CSE models conduction for this door:
QUICK | Surface is modeled using a simple conductance. Heat capacity effects are ignored. Either drCon or drU (next) can be specified. |
DELAYED, DELAYED_HOUR, DELAYED_SUBOUR | Surface is modeled using a multi-layer finite difference technique which represents heat capacity effects. If the time constant of the door is too short to accurately simulate, a warning message is issued and the Quick model is used. drCon (next) must be specified – the program cannot use the finite difference model if drU rather than drCon is specified. |
AUTO | Program selects Quick or appropriate Delayed automatically according to the time constant of the surface (if drU is specified, Quick is selected). |
FD or FORWARD_DIFFERENCE | Selects the forward difference model (used with short time steps and the CZM/UZM zone models) |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | AUTO | No | constant |
Either drU or drCon must be specified, but not both.
drU=float
Door U-value, NOT including surface (air film) conductances. Allows direct entry of U-value, without defining a CONSTRUCTION, when no heat capacity effects are to be modeled.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | Determined from drCon | if drCon not given | constant |
drCon=conName
Name of construction for door.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a CONSTRUCTION | none | unless drU given | constant |
drLThkF=float
Sublayer thickness adjustment factor for FORWARD_DIFFERENCE conduction model used with drCon surfaces. Material layers in the construction are divided into sublayers as needed for numerical stability. drLThkF allows adjustment of the thickness criterion used for subdivision. A value of 0 prevents subdivision; the default value (0.5) uses layers with conservative thickness equal to half of an estimated safe value. Fewer (thicker) sublayers improves runtime at the expense of accurate representation of rapid changes.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0.5 | No | constant |
drExAbs=float
Door exterior solar absorptivity. Applicable only if sfExCnd of owning surface is AMBIENT or SPECIFIEDT.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | same as owning surface | No | monthly-hourly |
drInAbs=float
Door interior solar absorptivity.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.5 | No | monthly-hourly |
drExEpsLW=float
Door exterior long wave (thermal) emittance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.9 | No | constant |
drInEpsLW=float
Door interior long wave (thermal) emittance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.9 | No | constant |
drInH=float
Door interior surface (air film) conductance. Ignored if drModel = Forward_Difference
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | same as owning surface | No | constant |
drExH=float
Door exterior surface (air film) conductance. Ignored if drModel = Forward_Difference
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | same as owning surface | No | constant |
When drModel = Forward_Difference, several models are available for calculating inside and outside surface convective coefficients. Inside surface faces can be exposed only to zone conditions. Outside faces may be exposed either to ambient conditions or zone conditions, based on drExCnd. Only UNIFIED and INPUT are typically used. The other models were used during CSE development for comparison. For details, see CSE Engineering Documentation.
Model | Exposed to ambient | Exposed to zone |
---|---|---|
UNIFIED | default CSE model | default CSE model |
INPUT | hc = drExHcMult | hc = drxxHcMult |
AKBARI | Akbari model | n/a |
WALTON | Walton model | n/a |
WINKELMANN | Winkelmann model | n/a |
MILLS | n/a | Mills model |
ASHRAE | n/a | ASHRAE handbook values |
drExHcModel=choice
Selects the model used for exterior surface convection when drModel = Forward_Difference.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | UNIFIED | No | constant |
drExHcLChar=float
Characteristic length of surface, used in derivation of forced exterior convection coefficients in some models when outside face is exposed to ambient (i.e. to wind).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | 10 | No | constant |
drExHcMult=float
Exterior convection coefficient adjustment factor. When drExHcModel=INPUT, hc=drExHcMult. For other drExHcModel choices, the model-derived hc is multiplied by drExHcMult.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | subhourly |
drExRf=float
Exterior roughness factor. Typical roughness values:
Roughness Index | drExRf | Example |
---|---|---|
1 (very rough) | 2.17 | Stucco |
2 (rough) | 1.67 | Brick |
3 (medium rough) | 1.52 | Concrete |
4 (Medium smooth) | 1.13 | Clear pine |
5 (Smooth) | 1.11 | Smooth plaster |
6 (Very Smooth) | 1 | Glass |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
drExHcModel = WINKELMANN: 1.66 else 2.17 | No | constant |
drInHcModel=choice
Selects the model used for the inside (zone) surface convection when drModel = Forward_Difference.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above (see drExHcModel) | UNIFIED | No | constant |
drInHcMult=float
Interior convection coefficient adjustment factor. When drInHcModel=INPUT, hc=drInHcMult. For other drInHcModel choices, the model-derived hc is multiplied by drInHcMult.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | subhourly |
endDoor
Indicates the end of the door definition. Alternatively, the end of the door definition can be indicated by the declaration of another object or by END.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.21 PERIMETER
PERIMETER defines a subobject belonging to the current zone that represents a length of exposed edge of a (slab on grade) floor.
prName
Optional name of perimeter.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
prLen=float
Length of exposed perimeter.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | none | Yes | constant |
prF2=float
Perimeter conduction per unit length.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft-oF | x \(>\) 0 | none | Yes | constant |
endPerimeter
Optionally indicates the end of the perimeter definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.22 TERMINAL
TERMINAL constructs an object to represent equipment that transfers energy to or from the current zone from a local heating device (coil, etc.) and/or one AIRHANDLER. A terminal serves a zone (and, internally, is owned by a zone). Up to three terminals can be defined for each zone.
A terminal can have local heating capability, using a simulated reheat coil, baseboard heater, etc. and/or air heating/cooling capability, using a simulated variable air volume (VAV) box connected to an AIRHANDLER (Section 0). Since a TERMINAL can only connect to a single air handler, use two terminals per zone to model systems where separate air handlers supply hot and cool air (dual duct). If a local heat capability utilizes the air flow (e.g. a reheat coil), model it in the terminal connected to the air handler; if a local heat capability is independent of air flow (e.g. electric baseboard heaters), it doesn’t matter whether you model it with a separate terminal.
Each capability can be set output, in which the output is constant or determined by external conditions such as in an outdoor reset baseboard situation or set temperature, in which the output is modulated to maintain the zone temperature at a set point. Set temperature operation is established by giving the setpoint for the capability (tuTLh, tuTH, tuTC); set output operation is established by specifying the local heat output (tuQMnLh) or air flow (tuVfMn) without specifying a setpoint.
Hourly variable expressions may be used as desired to schedule setpoints and flow limits. Figure 1 shows [need sentence describing the figure.]
tuName
Optional name of terminal; follows the word “TERMINAL” if given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | No | constant |
4.22.1 TERMINAL Local Heating
These commands establish the TERMINAL’s local heating capability and determine whether it operates in set output or set temperature fashion. Additional details of the local heating mechanism are given with commands described below under terminal heating coil.
Either tuTLh or tuQMnLh must be given to establish the TERMINAL’s local heat capability:
tuTLh=float
Local heating thermostat setpoint. Hourly expression may be used to schedule as desired. Giving this implies set temperature local heat from this terminal; omitting implies no local heat or, if tuQMnLh is given, set output local heat.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | no thermostat control | No | hourly |
tuQMnLh=float
Minimum local heat output or set local heat output. If tuTLh is given, this is the minimum output, used when the thermostat is not calling for (local) heat. If tuTLh is not given, giving tuQMnLh implies set output local heat and specifies the set output level. An hourly expression may be used to schedule as desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\ge\) 0 | 0 if tuTLh given else no local heat | For set output local heat | hourly |
The next three items are allowed only for thermostat controlled local heating (tuTLh given):
tuQMxLh=float
Maximum desired power, used when thermostat is calling for heat continuously, subject to coil capacity, and to HEATPLANT limitations where pertinent (see tuhcCaptRat description). If tuQMxLh is less than minimum power (tuQMnLh), the latter is used, effectively disabling setpoint control.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\ge\) 0 | Yes, if tuTLh given | hourly |
tuPriLh=int
Setpoint priority: when there is more than one capability with the same setpoint, that with the highest priority (lowest value) is used first. The defaults for tuPriLh (100) and tuPriH (1) cause maximum air heat to be used before local heat, if both are present and the setpoints are the same. Two or more equal setpoints with equal priorities in the ZONE cause an error, even if in different TERMINALs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 100 | No | constant |
tuLhNeedsFlow=choice
YES | local heat being modeled requires terminal air flow (e.g. reheat coil). Local heat is then disabled when there is zero air flow through the terminal (when simulated VAV damper set to 0 flow, or when air handler fan and terminal fan both off) |
NO | no local heat or does not require air flow (e.g. baseboard heaters). |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
YES, NO | NO | No | constant |
4.22.2 TERMINAL Air Heating and Cooling
These commands establish whether the TERMINAL has air capability (heat, cool, or both), and whether the capability operates in set temperature mode (tuTH and/or tuTLh given) or set output mode (tuVfMn given without tuTH and tuTLh). They further establish the setpoints, flow limits, leakages, and losses.
Caution should be exercised in using air heat and air cooling in the same terminal. The supply air for both comes from the same air handler; it is up to you to make sure the terminal only calls for heat when the air handler is blowing hot air and only calls for cooling when the air handler is blowing cold air. This is done by carefully coordinating the variable expressions for terminal air heating and cooling setpoints (tuTH and tuTC here) and the air handler supply temperature setpoint (AIRHANDLER ahTsSp, Section 0).
Note: To autosize air flows for a constant volume terminal, use the following
AUTOSIZE tuVfMxC
AUTOSIZE tuVfMxH
AUTOSIZE tuVfMn
tuVfMxHC = SAME
tuAh=ahName
Name of air handler supplying this terminal.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of an AIRHANDLER | If omitted, terminal has no air heating nor cooling capability. | No | constant |
If both of the following (tuTH and tuTC) are specified, be careful not to accidentally permit the heating setpoint to be active when the air handler is blowing cold air, or vice versa. CSE’s simulated thermostats and VAV boxes are at least as dumb as their real counterparts; if the thermostat calls for heat, the VAV damper will open even if the supply air is colder than the zone. To schedule deactivation of the air heating or cooling capability, schedule an extreme setpoint, such as 1 for heating or 199 for cooling.
Giving neither tuTH nor tuTC implies that the terminal has no set temperature air capability; it will then have set output air capability if tuVfMn is given.
tuTH=float
Air heating thermostat set point; implies set temperature air capability. May be scheduled as desired with an hourly expression; to disable set temperature operation at certain times (as when air handler is scheduled to supply cold air), schedule a low temperature such as 1.
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | No thermostat-controlled air heating | No | hourly |
tuTC=float
Air cooling thermostat set point; implies set temperature air capability. May be scheduled as desired; to disable at certain times, schedule an extreme temperature such as 199.
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | No thermostat-controlled air cooling | No | hourly |
tuVfDs=float
Design air flow rate. (“Vf” in member names stands for “Volumetric Flow”, to emphasize that flow is specified by volume at actual air temperature (cfm), not by mass (lb/hr), nor heat capacity (Btuh/F), etc.)
The design air flow rate is used to apportion the available cfm among the terminals when the total flow demand of the terminals exceeds the air handler’s supply fan capacity; it is unimportant (but may nevertheless be required) if the total of the tuVfMx’s of the terminals on the air handler is not greater than the air handler’s fan capacity including overrun.
CSE will default tuVfDs to the largest of tuVfMn, tuVfMxH, and tuVfMxC unless a variable expression is given for any of them. Thus, you must given tuVfDs only when a variable minimum or maximum flow is used, or when you wish to override the default cfm apportionment under fan overload conditions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\ge\) 0 | largest of tuVfMn, tuVfMxH, and tuVfMxC if all are constant | Yes, if tuVfmn, tuVfmxH, or tuVfMxC is variable | hourly |
tuFxVfHC=float
Sizing factor for autosized terminal air flows. Default value (1.1) specifies 10% oversizing.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1.1 | No | constant |
tuVfMxHC=choice
Determines autosizing strategy for heating and cooling air flows.
SAME | tuVfMxH and tuVfMxC are set to the larger of the autosized values |
DIFFERENT | tuVfMxH and tuVfMxC are autosized independently |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | Different | No | constant |
tuVfMn=float
Minimum terminal air flow rate or set output air flow rate. An hourly expression may be used to schedule the minimum or set output flow as desired.
If neither tuTH nor tuTC is given, giving tuVfMn implies set output air capability for the terminal; the tvVfMn value is the set output cfm.
If either setpoint (tuTH or tuTC) is given, tuVfMn is the cfm used when the thermostat is not calling for heat nor cold; it might be non-0, for example, to meet ventilation requirements. If tuVfMn is larger than tuVfMxH (when heating) or tuVfMxC (when cooling), it overrules them; thus a minimum (e.g. ventilation) requirement need not be considered in formulating expressions for the maximum flows.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | AUTOSIZE or x \(\ge\) 0 | if tuTH or tuTC given, else no air heat/cool | For set output air operation | hourly |
tuVfMxH=float
Maximum heating air flow rate, subject to air handler limitations. This terminal flow is used when the thermostat is calling for heat continuously. Hourly schedulable. If not greater than tuVfMn, the latter flow is used, thus disabling thermostat control.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | AUTOSIZE or x \(\ge\) 0 | none | If tuTH given | hourly |
tuVfMxC=float
Maximum cooling air flow rate, before air handler limitations, used when the thermostat is calling for cooling continuously. tuVfMn overrides if larger.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | AUTOSIZE or x \(\ge\) 0 | none | If tuTC given | hourly |
tuPriC=int
Cool setpoint priority. The lowest numbered priority is used first when there are equal setpoints in a zone; equal heat or cool setpoints with equal priority in same ZONE (even if on different TERMINALs) constitute an error.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
tuPriH=int
Heat setpoint priority. Lowest numbered priority is used first when there are equal setpoints in a zone. Default for tuPriLh is larger, so that by default local heat is not used unless maximum air heat is insufficient, when both local heat and air heat are present in zone and have same setpoint.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
tuSRLeak=float
Leakage of supply air to return, increasing supply volume and return temperature. Note that this is a fraction of current cfm, whereas air handler leak (before VAV dampers) is a fraction of maximum cfm. TfanOffLeak is added to this if terminal has a fan that is not running (future, 7-92).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.05 | No | constant |
tuSRLoss=float
Supply air to return plenum heat loss as a fraction of supply air to return air temperature difference. Not allowed if return is ducted (no plenum).
NOT IMPLEMENTED as of July 1992 – Plenums are unimplemented.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.1 | No | constant |
4.22.3 TERMINAL Heating Coil
These members are disallowed if terminal has no local heating capability, that is, if neither tuTLh nor tuQMnLh is given.
tuhcType=choice
Local heating coil type:
ELECTRIC | Electric coil or heater, including separate heaters such as electric baseboards. 100% efficient; rated capacity always available. |
HW | Hot water coil, using hot water from amHEATPLANT. Available capacity may be limited by HEATPLANT total capacity as well as by coil rated capacity. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ELECTRIC (future: HW) | ELECTRIC, or NONE if no local heat | No | constant |
tuhcCaptRat=float
Rated capacity of the heating coil. The coil will never supply more heat than its capacity, even if tuQMxLh and/or tuQMnLh is greater. For an ELECTRIC coil, the capacity is always the rated capacity. For an HW coil, the capacity is the rated capacity when the HEATPLANT can supply it; when the total heat demanded from the HEATPLANT by all the HW coils in TERMINALs and AIRHANDLERs exceeds the HEATPLANT’s capacity, CSE reduces the capacities of all HW coils proportionately until the plant is not overloaded.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/hr | AUTOSIZE or x \(\gt\) 0 | none | Yes | constant |
tuhcFxCap=float
Capacity factor for autosized terminal heating coil. Default value (1.1) specifies 10% oversizing.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1.1 | No | constant |
tuhcMtr=mtrName
Name of meter, if any, which accumulates input energy for this coil. End use category used is “Htg”. Not allowed when tuhcType is HW, as the energy for an HW coil comes through a HEATPLANT; the input energy is accumulated to a meter by the HEATPLANT.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
tuhcHeatplant=heatplantName
Name of HEATPLANT for HW coil; disallowed for other coil types.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a HEATPLANT | none | If tuhcType is HW | constant |
4.22.4 TERMINAL Fan
Presence of a terminal fan is indicated by specifying a tfanType value other than NONE.
Terminal fans are NOT IMPLEMENTED as of July 1992.
tfanType=choice
Choice of:
NONE | No fan in this TERMINAL (default); input for other terminal fan members disallowed. |
SERIES | Fan runs whenever scheduled ON (see tfanSched, next); if VAV cfm < terminal fan cfm (tfanVfDs), the additional flow comes from the return air. |
PARALLEL | Fan runs when scheduled ON (see tfanSched) and terminal’s simulated VAV cfm is less than tfanVfDs plus tuVfMn ?? plus tuVfMn??. Terminal fan cfm is added to VAV cfm from AIRHANDLER to get cfm to ZONE. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NONE, SERIES, PARALLEL | none | Yes, if fan present | constant |
tfanSched=choice
Terminal fan schedule. May be scheduled with an hourly variable expression.
OFF | fan does not run |
ON | fan may run |
HEATING | fan may run when local heat is in use |
VAV | fan may run when AIRHANDLER supply fan is on or when doing setback headting and ssCtrl is ZONE_HEAT or BOTH (future). |
A series fan (see tfanType) runs whenever on; a parallel fan runs only enough to keep terminal cfm at terminal minimum plus fan cfm; thus it may not run at all when the VAV flow from the AIRHANDLER is sufficient.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
OFF, ON, HEATING, VAV | none | Yes (if fan present) | hourly |
tfanOffLeak=float
Backdraft leakage when terminal fan off., as a fraction of tfanVfDs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.1 if fan present | No | constant |
tfanVfDs=float
Terminal fan design flow rate. To specify .x times zone or terminal cfm, use a CSE expression.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\le\) 0 | none | Yes (if fan present) | constant |
tfanPress=float
Terminal fan external static pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
inches H2O | x \(\ge\) 0 | 0.3 | No | constant |
tfanEff=float
Terminal fan/motor/drive combined efficiency.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(le\) x \(le\) 1 | 0.08 | No | constant |
tfanCurvePy=k0, k1, k2, k3, x0
k0 through k3 are the coefficients of a cubic polynomial for the curve relating fan relative energy consumption to relative air flow above the minimum flow x0. Up to five floats may be given, separated by commas. 0 is used for any omitted trailing values. The values are used as follows:
\[z = k_0 + k_1 \cdot (x - x_0)| + k_2 \cdot (x - x_0)|^2 + k_3 \cdot (x - x_0)|^3\]
where:
- \(x\) is the relative fan air flow (as fraction of tfanVfDs; 0 \(\le\) x \(\le\) 1);
- \(x_0\) is the minimum relative air flow (default 0);
- \((x - x_0)|\) is the “positive difference”, i.e. \((x - x_0)\) if \(x > x_0\); else 0;
- \(z\) is the relative energy consumption.
If \(z\) is not 1.0 for \(x\) = 1.0, a warning message is displayed and the coefficients are normalized by dividing by the polynomial’s value for \(x\) = 1.0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0, 1, 0, 0, 0 (linear) | No | constant |
tfanMtr=mtrName
Name of meter, if any, which is to record energy used by this terminal fan. The “fans” category is used.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
endTerminal
Optional to indicates the end of terminal definition. Alternatively, the end of the door definition can be indicated by END or by beginning another object.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | none | No | constant |
Related Probes:
4.23 IZXFER
IZXFER constructs an object that represents an interzone or zone/ambient heat transfer due to conduction and/or air transfer. The air transfer modeled by IZXFER transfers heat only; humidity transfer is not modeled as of July 2011. Note that SURFACE is the preferred way represent conduction between ZONEs.
The AIRNET types are used in a multi-cell pressure balancing model that finds zone pressures that produce net 0 mass flow into each zone. The model operates in concert with the znType=CZM or znType=UZM to represent ventilation strategies. During each time step, the pressure balance is found for two modes that can be thought of as “VentOff” (or infiltration-only) and “VentOn” (or infiltration+ventilation). The zone model then determines the ventilation fraction required to hold the desired zone temperature (if possible). AIRNET modeling methods are documented in the CSE Engineering Documentation.
Note that fan-driven types assume pressure-independent flow. That is, the specified flow is included in the zone pressure balance but the modeled fan flow does not change with zone pressure. The assumption is that in realistic configurations, zone pressure will generally be close to ambient pressure. Unbalanced fan ventilation in a zone without relief area will result in runtime termination due to excessively high or low pressure.
izName
Optional name of interzone transfer; give after the word “IZXFER” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
izNVType=choice
Choice specifying the type of ventilation or leakage model to be used.
NONE | No interzone ventilation |
ONEWAY | Uncontrolled flow from izZn1 to izZn2 when izZn1 air temperature exceeds izZn2 air temperature (using ASHRAE high/low vent model). |
TWOWAY | Uncontrolled flow in either direction (using ASHRAE high/low vent model). |
AIRNETIZ | Single opening to another zone (using pressure balance AirNet model). Flow is driven by buoyancy. |
AIRNETEXT | Single opening to ambient (using pressure balance AirNet model). Flow is driven by buoyancy and wind pressure. |
AIRNETHORIZ | Horizontal (large) opening between two zones, used to represent e.g. stairwells. Flow is driven by buoyancy; simultaneous up and down flow is modeled. |
AIRNETEXTFAN | Fan from exterior to zone (flow either direction). |
AIRNETIZFAN | Fan between two zones (flow either direction). |
AIRNETEXTFLOW | Specified flow from exterior to zone (either direction). Behaves identically to AIRNETEXTFAN except no electricity is consumed and no fan heat is added to the air stream. |
AIRNETIZFLOW | Specified flow between two zones (either direction). Behaves identically to AIRNETIZFAN except no electricity is consumed and no fan heat is added to the air stream. |
AIRNETHERV | Heat or energy recovery ventilator. Supply and exhaust air are exchanged with the exterior with heat and/or moisture exchange between the air streams. Flow may or may not be balanced. |
AIRNETDOAS | Air supplied from and/or exhausted to a centralized DOAS fans. |
Note that optional inputs izTEx, izWEx, and izWindSpeed can override the outside conditions assumed for ivNVTypes that are connected to ambient (AIRNETEXT, AIRNETEXTFAN, AIRNETEXTFLOW, and AIRNETHERV).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | none | No | constant |
izAFCat=choice
Choice indicating air flow category used only for recording air flow results to an AFMETER. izAFCat has no effect for non-AIRNET IZXFERs. izAFCat is not used unless the associated ZONE(s) specify znAFMtr.
Choices are:
InfilEx | Infiltration from ambient |
VentEx | Natural ventilation from ambient |
FanEx | Forced ventilation from ambient |
InfilIz | Interzone infiltration |
VentIz | Interzone natural ventilation |
FanIz | Interzone forced ventilation |
DuctLk | Duct leakage |
HVAC | HVAC air |
Default values for izAFCat are generally adequate except that natural ventilation IZXFERs are by default categorized as infiltration. It is thus recommended that izAfCat be omitted except that ventilation IZXFERs (e.g. representing openable windows) should include izAfCat=VentEx (or VentIz).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
choices above | derived from IZXFER characteristics | No | constant |
izZn1=znName
Name of primary zone. Flow rates \(>\) 0 are into the primary zone.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | none | Yes | constant |
izZn2=znName
Name of secondary zone.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | none | required unless constant izNVType = AIRNETEXT, AIRNETEXTFAN, AIRNETEXTFLOW, or AIRNETHERV | constant |
izDOAS=oaName
Name of DOAS where air is supplied from (izVfMin > 0), or exhausting to (izVfMin < 0).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | name of a DOAS | – | when izNVType = AIRNETDOAS | constant |
izLinkedFlowMult=float
Specifies a multiplier applied to air flow to/from any associated DOAS. This supports use of a single modeled zone to represent multiple actual zones while preserving the total DOAS air flow and energy consumption.
For example, consider a DOAS-linked IZXFER with izVfMin = 100 and izLinkedFlowMult = 5. The zone specified by izZn1 receives 100 cfm while the DOAS specified by izDOAS is modeled as if the supply flow is 500 cfm. Thus the DOAS behavior (fan energy use etc.) approximates that of a DOAS serving 5 zones, but only one zone is simulated.
Note izLinkedFlowMult has no effect on the air flow to or from the zone specified by izZn1.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | x \(\gt\) 0 | 1 | No | constant |
Give izHConst for a conductive transfer between zones. Give izNVType other than NONE and the following variables for a convective (air) transfer between the zones or between a zone and outdoors. Both may be given if desired. Not known to work properly as of July 2011
izHConst=float
Conductance between zones.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/oF | x \(\ge\) 0 | 0 | No | hourly |
izALo=float
Area of low or only vent (typically VentOff)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(\ge\) 0 | 0 | No | hourly |
izAHi=float
Additional vent area (high vent or VentOn). If used in AIRNET, izAHi > izALo typically but this is not required.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(\ge\) 0 | izALo | No | hourly |
izTEx=float
Alternative exterior air dry bulb temperature for this vent. Allowed only with izNVTypes that use outdoor air (AIRNETEXT, AIRNETEXTFAN, AIRNETEXTFLOW, and AIRNETHERV). If given, izTEx overrides the outdoor dry-bulb temperature read from the weather file or derived from design conditions.
Caution: izTEx is not checked for reasonableness.
One use of izTEx is in representation of leaks in surfaces adjacent to zones not being simulated. “Pseudo-interior” surface leakage can be created as follows (where “Z1” is the name of the leak’s zone and izALo and izHD are set to appropriate values) –
IZXFER RLF izNVTYPE=AirNetExt izZN1="Z1" izALo=.1 izHD=10 izTEx=@zone["Z1"].tzls izWEx=@zone["Z1"].wzls
This will allow Z1’s pressure to be realistic without inducing thermal loads that would occur if the leak source had outdoor conditions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | Outdoor dry-bulb | No | subhourly |
izWEx=float
Alternative exterior air humidity ratio seen by this vent. Allowed only with izNVTypes that use outdoor air (AIRNETEXT, AIRNETEXTFAN, AIRNETEXTFLOW, and AIRNETHERV). If given, izWEx overrides the outdoor humidity ratio derived from weather file data or design conditions.
Caution: izWEx is not checked against saturation – there is no verification that the value provided is physically possible.
See izTEx example just above.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(\gt\) 0 | Outdoor humidity ratio | No | subhourly |
izWindSpeed=float
Alternative windspeed seen by this vent. Allowed only with izNVTypes that use outdoor air (AIRNETEXT, AIRNETEXTFAN, AIRNETEXTFLOW, and AIRNETHERV). If given, izWindSpeed overrides the windspeed read from the weather file or derived from design conditions.
No adjustments such as TOP windF or ZONE znWindFLkg are applied to izWindSpeed when it is used in derivation of wind-driven air flow.
Note that izCpr must be non-0 for izWindSpeed to have any effect.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
mph | \(\ge\) 0 | Zone adjusted windspeed | No | subhourly |
izL1=float
Length or width of AIRNETHORIZ opening.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | none | if izNVType = AIRNETHORIZ | constant |
izL2=float
Width or length of AIRNETHORIZ opening.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | none | if izNVType = AIRNETHORIZ | constant |
izStairAngle=float
Stairway angle for AIRNETHORIZ opening. Use 90 for an open hole. Note that 0 prevents flow.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
o degrees | x \(>\) 0 | 34 | No | constant |
izHD=float
Vent center-to-center height difference (for TWOWAY) or vent height above nominal 0 level (for AirNet types)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | 0 | No | constant |
izNVEff=float
Vent discharge coefficient.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.8 | No | constant |
izfanVfDs=float
Fan design or rated flow at rated pressure. For AIRNETHERV, this is the net air flow into the zone, gross flow at the fan is derived using izEATR (see below).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\ge\) 0 | 0 (no fan) | If fan present | constant |
izCpr=float
Wind pressure coefficient (for AIRNETEXT).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0 | No | constant |
izExp=float
Opening exponent (for AIRNETEXT).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.5 | No | constant |
izVfMin=float
Minimum volume flow rate (VentOff mode).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\ge\) 0 | izfanVfDs | No | subhourly |
izVfMax=float
Maximum volume flow rate (VentOn mode)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\ge\) 0 | izVfMin | No | subhourly |
izASEF=float
Apparent sensible effectiveness for AIRNETHERV ventilator. ASEF is a commonly-reported HERV rating and is calculated as (supplyT - sourceT) / (returnT - sourceT). This formulation includes fan heat (in supplyT), hence the term “apparent”. Ignored if izSRE is given. CSE does not HRV exhaust-side condensation, so this model is approximate.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0 | No | subhourly |
izSRE=float
Sensible recovery efficiency (SRE) for AIRNETHERV ventilator. Used as the sensible effectiveness in calculation of the supply air temperature. Note that values of SRE greater than approximately 0.6 imply exhaust-side condensation under HVI rating conditions. CSE does not adjust for these effects. High values of izSRE will produce unrealistic results under mild outdoor conditions and/or dry indoor conditions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0 | No | subhourly |
izASRE=float
Adjusted sensible recovery efficiency (ASRE) for AIRNETHERV ventilator. The difference izASRE - izSRE is used to calculate fan heat added to the supply air stream. See izSRE notes. No effect when izSRE is 0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) izSRE | 0 | No | subhourly |
izEATR=float
Exhaust air transfer ratio for AIRNETHERV ventilator. NetFlow = (1 - EATR)*(grossFlow).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | 0 \(\le\) x \(\le\) 1 | 0 | No | subhourly |
izLEF=float
Latent heat recovery effectiveness for AIRNETHERV ventilator. The default value (0) results in sensible-only heat recovery.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0 | No | subhourly |
izRVFanHeatF=float
Fraction of fan heat added to supply air stream for AIRNETHERV ventilator. Used only when when izSRE is 0 (that is, when izASEF specifies the sensible effectiveness).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0 | No | subhourly |
izVfExhRat=float
Exhaust volume flow ratio for AIRNETHERV ventilator = (exhaust flow) / (supply flow). Any value other than 1 indicates unbalanced flow that effects the zone pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 (balanced) | No | constant |
izfanPress=float
Design or rated fan pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
inches H2O | x \(>\) 0 | 0.3 | No | constant |
Only one of izfanElecPwr, izfanEff, and izfanShaftBhp may be given: together with izfanVfDs and izfanPress, any one is sufficient for CSE to determine the others and to compute the fan heat contribution to the air stream.
izfanElecPwr=float
Fan input power per unit air flow (at design flow and pressure).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | x \(>\) 0 | derived from izfanEff and izfanShaftBhp | If izfanEff and izfanShaftBhp not present | constant |
izfanEff=float
Fan efficiency at design flow and pressure, as a fraction.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | derived from izfanShaftBhp if given, else 0.08 | No | constant |
izfanShaftBhp=float
Fan shaft brake horsepower at design flow and pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
bhp | x \(>\) 0 | derived from izfanEff. | No | constant |
izfanCurvePy=\(k_0\), \(k_1\), \(k_2\), \(k_3\), \(x_0\)
\(k_0\) through \(k_3\) are the coefficients of a cubic polynomial for the curve relating fan relative energy consumption to relative air flow above the minimum flow \(x_0\). Up to five floats may be given, separated by commas. 0 is used for any omitted trailing values. The values are used as follows:
\[z = k_0 + k_1 \cdot (x - x_0)| + k_2 \cdot (x - x_0)|^2 + k_3 \cdot (x - x_0)|^3\]
where:
- \(x\) is the relative fan air flow (as fraction of izfanVfDs; 0 \(\le\) \(x\) \(\le\) 1);
- \(x_0\) is the minimum relative air flow (default 0);
- \((x - x_0)|\) is the “positive difference”, i.e. \((x - x_0)\) if \(x > x_0\); else 0;
- \(z\) is the relative energy consumption.
If \(z\) is not 1.0 for \(x\) = 1.0, a warning message is displayed and the coefficients are normalized by dividing by the polynomial’s value for \(x\) = 1.0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0, 1, 0, 0, 0 (linear) | No | constant |
izFanMtr=mtrName
Name of meter, if any, to record energy used by supply fan. End use category used is specified by izFanEndUse (next).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
izFanEndUse=choice
End use to which fan energy is recorded (in METER specified by izFanMtr). See METER for available end use choices.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
end use choice | Fan | No | constant |
endIZXFER
Optionally indicates the end of the interzone transfer definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.24 DOAS
DOAS (Dedicated Outdoor Air System) provides centralized supply and/or exhuast ventilation air to IZXFER objects with the izNVType = AIRNETDOAS. The supply air may be preconditioned using heat recovery and/or tempering coils.
oaName
Name of DOAS.
4.24.1 DOAS Supply Fan Data Members
oaSupFanVfDs=float
Supply fan design or rated flow at rated pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\ge\) 0 | Sum of referencing IZXFER supply flows | No | constant |
oaSupFanPress=float
Design or rated fan pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
inches H2O | x \(>\) 0 | 0.3 | No | constant |
Only one of oaSupFanElecPwr, oaSupFanEff, and oaSupFanShaftBhp may be given.
oaSupFanElecPwr=float
Fan input power per unit air flow (at design flow and pressure).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | x \(>\) 0 | derived from oaSupFanEff and oaSupFanShaftBhp | If oaSupFanEff and oaSupFanShaftBhp not present | constant |
oaSupFanEff=float
Fan efficiency at design flow and pressure, as a fraction.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | derived from oaSupFanShaftBhp if given, else 0.08 | No | constant |
oaSupFanShaftBhp=float
Fan shaft brake horsepower at design flow and pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
bhp | x \(>\) 0 | derived from oaSupFanEff. | No | constant |
oaSupFanCurvePy=\(k_0\), \(k_1\), \(k_2\), \(k_3\), \(x_0\)
\(k_0\) through \(k_3\) are the coefficients of a cubic polynomial for the curve relating fan relative energy consumption to relative air flow above the minimum flow \(x_0\). Up to five floats may be given, separated by commas. 0 is used for any omitted trailing values. The values are used as follows:
\[z = k_0 + k_1 \cdot (x - x_0)| + k_2 \cdot (x - x_0)|^2 + k_3 \cdot (x - x_0)|^3\]
where:
- \(x\) is the relative fan air flow (as fraction of oaSupFanVfDs; 0 \(\le\) \(x\) \(\le\) 1);
- \(x_0\) is the minimum relative air flow (default 0);
- \((x - x_0)|\) is the “positive difference”, i.e. \((x - x_0)\) if \(x > x_0\); else 0;
- \(z\) is the relative energy consumption.
If \(z\) is not 1.0 for \(x\) = 1.0, a warning message is displayed and the coefficients are normalized by dividing by the polynomial’s value for \(x\) = 1.0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0, 1, 0, 0, 0 (linear) | No | constant |
oaSupFanMtr=mtrName
Name of meter, if any, to record energy used by supply fan. End use category used is specified by oaSupFanEndUse (next).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
oaSupFanEndUse=choice
End use to which fan energy is recorded (in METER specified by oaSupFanMtr). See METER for available end use choices.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
end use choice | Fan | No | constant |
oaTEx=float
Alternative supply fan source air dry bulb temperature. If given, oaTEx overrides the outdoor dry-bulb temperature read from the weather file or derived from design conditions.
Caution: oaTEx is not checked for reasonableness.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | Outdoor dry-bulb | No | subhourly |
oaWEx=float
Alternative supply fan source air air humidity ratio. If given, oaWEx overrides the outdoor humidity ratio derived from weather file data or design conditions.
Caution: oaWEx is not checked against saturation – there is no verification that the value provided is physically possible.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(\gt\) 0 | Outdoor humidity ratio | No | subhourly |
4.24.2 DOAS Exhaust Fan Data Members
oaExhFanVfDs=float
Exhaust fan design or rated flow at rated pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\ge\) 0 | Sum of referencing IZXFER exhaust flows | No | constant |
oaExhFanPress=float
Design or rated fan pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
inches H2O | x \(>\) 0 | 0.3 | No | constant |
Only one of oaExhFanElecPwr, oaExhFanEff, and oaExhFanShaftBhp may be given.
oaExhFanElecPwr=float
Fan input power per unit air flow (at design flow and pressure).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | x \(>\) 0 | derived from oaExhFanEff and oaExhFanShaftBhp | If oaExhFanEff and oaExhFanShaftBhp not present | constant |
oaExhFanEff=float
Fan efficiency at design flow and pressure, as a fraction.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | derived from oaExhFanShaftBhp if given, else 0.08 | No | constant |
oaExhFanShaftBhp=float
Fan shaft brake horsepower at design flow and pressure.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
bhp | x \(>\) 0 | derived from oaExhFanEff. | No | constant |
oaExhFanCurvePy=\(k_0\), \(k_1\), \(k_2\), \(k_3\), \(x_0\)
\(k_0\) through \(k_3\) are the coefficients of a cubic polynomial for the curve relating fan relative energy consumption to relative air flow above the minimum flow \(x_0\). Up to five floats may be given, separated by commas. 0 is used for any omitted trailing values. The values are used as follows:
\[z = k_0 + k_1 \cdot (x - x_0)| + k_2 \cdot (x - x_0)|^2 + k_3 \cdot (x - x_0)|^3\]
where:
- \(x\) is the relative fan air flow (as fraction of oaExhFanVfDs; 0 \(\le\) \(x\) \(\le\) 1);
- \(x_0\) is the minimum relative air flow (default 0);
- \((x - x_0)|\) is the “positive difference”, i.e. \((x - x_0)\) if \(x > x_0\); else 0;
- \(z\) is the relative energy consumption.
If \(z\) is not 1.0 for \(x\) = 1.0, a warning message is displayed and the coefficients are normalized by dividing by the polynomial’s value for \(x\) = 1.0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0, 1, 0, 0, 0 (linear) | No | constant |
oaExhFanMtr=mtrName
Name of meter, if any, to record energy used by exhaust fan. End use category used is specified by oaExhFanEndUse (next).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
oaExhFanEndUse=choice
End use to which fan energy is recorded (in METER specified by oaExhFanMtr). See METER for available end use choices.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
end use choice | Fan | No | constant |
4.24.3 DOAS Tempering Coils Data Members
oaSupTH=float
Heating setpoint for tempering and/or heat exchanger bypass.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | – | 68 | No | subhourly |
oaEIRH=float
Energy Input Ratio of the heating coil. This is the inverse of the coil efficiency or COP. A value of zero indicates that the coil does not use energy (e.g., hot water coils). Specifying input triggers the modeling of a heating coil.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0 | when modeling heating coil | subhourly |
oaCoilHMtr=mtrName
Name of meter, if any, to record energy used by the heating coil.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
oaSupTC=float
Cooling setpoint for tempering and/or heat exchanger bypass.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | – | 68 | No | subhourly |
oaEIRC=float
Energy Input Ratio of the cooling coil. This is the inverse of the coil efficiency or COP. A value of zero indicates that the coil does not use energy (e.g., chilled water coils). Specifying input triggers the modeling of a cooling coil.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0 | when modeling cooling coil | subhourly |
oaSHRtarget=float
Sensible Heat Ratio of the cooling coil. If the required sensible capacity of the coil and the entered SHR do not produce a valid psychrometric state, the SHR is adjusted and reported through the SHR probe.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\gt\) 0 | 1.0 | No | subhourly |
oaCoilCMtr=mtrName
Name of meter, if any, to record energy used by the cooling coil.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
oaLoadMtr=ldMtrName
Name of load meter, if any, to record load met by the heating coil or cooling coil.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a LOADMETER | not recorded | No | constant |
4.24.4 DOAS Heat Recovery Data Members
oaHXVfDs=float
Heat exchanger design or rated flow.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\gt\) 0 | Average of supply and exhaust fan design flows | No | constant |
oaHXf2=float
Heat exchanger flow fraction (of design flow) used for second set of effectivenesses.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\lt\) x \(\lt\) 1.0 | 0.75 | No | constant |
oaHXSenEffHDs=float
Heat exchanger sensible effectiveness in heating mode at the design flow rate. Specifying input triggers modeling of heat recovery.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | – | when modeling heat recovery | constant |
oaHXSenEffHf2=float
Heat exchanger sensible effectiveness in heating mode at the second flow rate (oaHXf2).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | 0 | No | constant |
oaHXLatEffHDs=float
Heat exchanger latent effectiveness in heating mode at the design flow rate.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | 0 | No | constant |
oaHXLatEffHf2=float
Heat exchanger latent effectiveness in heating mode at the second flow rate (oaHXf2).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | 0 | No | constant |
oaHXSenEffCDs=float
Heat exchanger sensible effectiveness in cooling mode at the design flow rate.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | 0 | No | constant |
oaHXSenEffCf2=float
Heat exchanger sensible effectiveness in cooling mode at the second flow rate (oaHXf2).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | 0 | No | constant |
oaHXLatEffCDs=float
Heat exchanger latent effectiveness in cooling mode at the design flow rate.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | 0 | No | constant |
oaHXLatEffCf2=float
Heat exchanger latent effectiveness in cooling mode at the second flow rate (oaHXf2).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1.0 | 0 | No | constant |
oaHXBypass=choice
Yes/No choice for enabling heat exchanger bypass. If selected, the outdoor air will bypass the heat exchanger when otherwise the heat exchanger would require more heating or cooling energy to meet the respective setpoints.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NO, YES | NO | No | constant |
oaHXAuxPwr=float
Auxiliary power required to operate the heat recovery device (e.g., wheel motor, contorls).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 0 | No | subhourly |
oaHXAuxMtr=mtrName
Name of meter, if any, to record energy used by auxiliary components of the heat recovery system.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
endDOAS
Indicates the end of the DOAS definition. Alternatively, the end of the DOAS definition can be indicated by the declaration of another object or by “END”.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | – | N/A | No | constant |
Related Probes:
- @doas
4.25 RSYS
RSYS constructs an object representing an air-based residential HVAC system.
rsName
Optional name of HVAC system; give after the word “RSYS” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
rsType=choice
Type of system.
rsType | Description |
---|---|
ACFURNACE | Compressor-based cooling modeled per SEER and EER. Fuel-fired heating. Primary heating input energy is accumulated to end use HTG of meter rsFuelMtr. |
ACPMFURNACE | Compressor-based cooling modeled per PERFORMANCEMAP specified in rsPerfMapClg. Fuel-fired heating. Primary heating input energy is accumulated to end use HTG of meter rsFuelMtr. |
ACRESISTANCE | Compressor-based cooling and electric (‘strip’) heating. Cooling performance based on SEER and EER. Primary heating input energy is accumulated to end use HTG of meter rsElecMtr. |
ACPMRESISTANCE | Cooling based on PERFORMANCEMAP specified in rsPerfMapClg. Primary heating input energy is accumulated to end use HTG of meter rsElecMtr. |
ASHP | Air-source heat pump (compressor-based heating and cooling). Primary (compressor) heating input energy is accumulated to end use HTG of meter rsElecMtr. Auxiliary and defrost heating input energy is accumulated to end use HPBU of meter rsElecMtr or meter rsFuelMtr (depending on rsTypeAuxH). |
ASHPKGROOM | Packaged room air-source heat pump. |
ASHPHYDRONIC | Air-to-water heat pump with hydronic distribution. Compressor performance is approximated using the air-to-air model with adjusted efficiencies. |
ASHPPM | Air-to-air heat pump modeled per PERFORMANCMAPs specified via rsPerfMapHtg and rsPerfMapClg. |
WSHP | Water-to-air heat pump. |
AC | Compressor-based cooling; no heating. Required ratings are SEER and capacity and EER at 95 oF outdoor dry bulb. |
ACPM | Compressor-based cooling modeled per PERFORMANCEMAP specified in rsPerfMapClg; no heating. |
ACPKGROOM | Packaged compressor-based cooling; no heating. Required ratings are capacity and EER at 95 oF outdoor dry bulb. |
FURNACE | Fuel-fired heating. Primary heating input energy is accumulated to end use HTG of meter rsFuelMtr. |
RESISTANCE | Electric heating. Primary heating input energy is accumulated to end use HTG of meter rsElecMtr. |
ACPKGROOMFURNACE | Packaged room cooling and (separate) furnace heating. |
ACPKGROOMRESISTANCE | Packaged room cooling and electric resistance heating. |
COMBINEDHEATDHW | Combined heating / DHW. Use rsCHDHWSYS to specify the DHWSYS that provides hot water to the coil in this RSYS. No cooling. |
ACCOMBINEDHEATDHW | Compressor-based cooling; COMBINEDHEATDHW heating. |
ACPMCOMBINEDHEATDHW | Compressor-based cooling modeled per PERFORMANCEMAP specified in rsPerfMapClg; COMBINEDHEATDHW heating. |
FANCOIL | Coil-based heating and cooling. No primary (fuel-using) equipment is modeled. rsLoadMtr, rsHtgLoadMtr, and rsClgLoadMtr are typically used to record loads for linking to an external model. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
one of above choices | ACFURNACE | No | constant |
rsDesc=string
Text description of system, included as documentation in debugging reports such as those triggered by rsGeneratePerfMap=YES
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
string | none | No | constant |
rsModeCtrl=choice
Specifies systems heating/cooling availability during simulation.
OFF | System is off (neither heating nor cooling is available) |
HEAT | System can heat (assuming rsType can heat) |
COOL | System can cool (assuming rsType can cool) |
AUTO | System can either heat or cool (assuming rsType compatibility). First request by any zone served by this RSYS determines mode for the current time step. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
OFF, HEAT, COOL, AUTO | AUTO | No | hourly |
rsGeneratePerfMap=choice
Generate performance map(s) for this RSYS. Comma-separated text is written to file PM_[rsName].csv. This is a debugging capability that is not necessarily maintained. The format of the generated csv text file may change and is unrelated to the PERFORMANCEMAP input scheme used via rsPerfMapHtg and rsPerfMapClg.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
YES, NO | NO | No | constant |
rsFanTy=choice
Specifies fan (blower) position relative to primary heating or cooling source (i.e. heat exchanger or heat pump coil for heating and AC coil for cooling). The blower position determines where fan heat is added to the RSYS air stream and thus influences the coil entering air temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
BLOWTHRU, DRAWTHRU | BLOWTHRU | No | constant |
rsFanMotTy=choice
Specifies type of motor driving the fan (blower). This is used in the derivation of the coil-only cooling capacity for the RSYS.
PSC | Permanent split capacitor |
BPM | Brushless permanent magnet (aka ECM) |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
PSC, BPM | PSC | No | constant |
rsAdjForFanHt=choice
Fan heat adjustment with two options Yes or no. Yes: fanHtRtd derived from rsFanTy and removed from capacity and input values. No: no rated fan heat adjustments.
rsElecMtr=mtrName
Name of METER object, if any, by which system’s electrical energy use is recorded (under appropriate end uses).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | none | No | constant |
rsFuelMtr =mtrName
Name of METER object, if any, by which system’s fuel energy use is recorded (under appropriate end uses).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | none | No | constant |
rsLoadMtr =ldMtrName
rsHtgLoadMtr =ldMtrName
rsClgLoadMtr =ldMtrName
Names of LOADMETER objects, if any, to which the system’s heating and/or cooling loads are recorded. Loads are the gross heating and cooling energy added to (or removed from) the air stream. Fan heat, auxiliary heat, and duct losses are not included in loads values.
rsLoadMtr accumulates both heating (> 0) and cooling (< 0) loads. rsHtgLoadMtr accumulates only heating loads. rsClgLoadMtr accumulates only cooling loads. This arrangement accomodates mixed heating and cooling source configurations. For example, loads can be tracked appropriately in a building that has multiple cooling sources and a single heating source.
rsLoadMtr should not specify the same LOADMETER as rsHtgLoadMtr or rsClgLoadMtr since this would result in double counting.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a LOADMETER | none | No | constant |
rsSrcSideLoadMtr=ldMtrName
rsHtgSrcSideLoadMtr =ldMtrName
rsClgSrcSideLoadMtr =ldMtrName
Name of LOADMETER objects, if any, to which the system’s source-side heat transfers are recorded. For DX systems, this is the outdoor coil heat transfer. For other types, source-side values are the same as the indoor coil loads reported via rsLoadMtr.
rsSrcSideLoadMtr accumulates both heating (> 0) and cooling (< 0) transfers. rsHtgSrcSideLoadMtr accumulates only heating transfers. rsClgSrcSideLoadMtr accumulates only cooling transfers. This arrangement accomodates mixed heating and cooling source configurations.
rsSrcSideLoadMtr should not specify the same LOADMETER as rsHtgSrcSideLoadMtr or rsClgSrcSideLoadMtr since this would result in double counting.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Name of a LOADMETER | No | constant |
rsCHDHWSYS=dhwsysName
DHWSYS hot water source for this RSYS, required when rsType is COMBINEDHEATDHW or ACCOMBINEDHEATDHW. The specified DHWSYS must include a DHWHEATER of whType=ASHPX or RESISTANCEX.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Name of a DHWSYS | none | if combined heat/DHW | constant |
rsAFUE=float
Heating Annual Fuel Utilization Efficiency (AFUE).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) x \(\le\) 1 | 0.9 if furnace, 1.0 if resistance | No | constant |
rsCapH=float
Heating capacity, used when rsType is ACFURNACE, ACRESISTANCE, FURNACE, WSHP or RESISTANCE.
If rsType=WSHP, rsCapH is at source fluid temperature = 68 oF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/hr | AUTOSIZE or x \(\ge\) 0 | 0 | No | constant |
rsTdDesH=float
Nominal heating temperature rise (across system, not at zone) used during autosizing (when capacity is not yet known) and to derive heating air flow rate from heating capacity.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 30 oF if heat pump else 50 oF | No | constant |
rsFxCapH=float
Heating autosizing capacity factor. If AUTOSIZEd, rsCapH or rsCap47 is set to rsFxCapH \(\times\) (peak design-day load). Peak design-day load is the heating capacity that holds zone temperature at the thermostat set point during the last substep of all hours of all design days.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1.4 | No | constant |
rsFanPwrH=float
Heating operating fan power. For most rsTypes, heating air flow is calculated from heating capacity and rsTdDesH. The default value of rsFanPwrH is .365 W/cfm except 0.273 W/cfm is used when rsType=COMBINEDHEATDHW and rsType=ACCOMBINEDHEATDHW.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | x \(\ge\) 0 | see above | No | constant |
rsHSPF=float
For rsType=ASHP, Heating Seasonal Performance Factor (HSPF).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/Wh | x \(>\) 0 | none | Yes if rsType=ASHP | constant |
rsCap47=float
For rsType=ASHP, rated heating capacity at outdoor dry-bulb temperature = 47 oF.
If rsType=ASHP and both rsCapC and rsCap47 are autosized, both are set to the larger consistent value using rsCapRat9547 (after application of rsFxCapH and rsFxCapC).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/Wh | AUTOSIZE or x \(>\) 0 | Calculated from rsCapC | No | constant |
rsCap35=float
For rsType=ASHP, rated heating capacity at outdoor dry-bulb temperature = 35 oF. rsCap35 typically reflects reduced capacity due to reverse (cooling) heat pump operation for defrost.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/Wh | x \(>\) 0 | Calculated from rsCap47 and rsCap17 | No | constant |
rsCap17=float
For rsType=ASHP, rated heating capacity at outdoor dry-bulb temperature = 17 oF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/Wh | x \(>\) 0 | Calculated from rsCap47 | No | constant |
rsCOP95=float
For rsType=ASHP, rated heating coefficient of performance at outdoor dry-bulb temperature = 95 oF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | Calculated from rsCap95 | No | constant |
rsCOP47=float
For rsType=ASHP, rated heating coefficient of performance at outdoor dry-bulb temperature = 47 oF. For rsType=WSHP, rated heating coefficient of performance at source fluid temperature = 68 oF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | Estimated from rsHSPF, rsCap47, and rsCap17 | No | constant |
rsCOP35=float
For rsType=ASHP, rated heating coefficient of performance at outdoor dry-bulb temperature = 35 oF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | Calculated from rsCap35, rsCap47, rsCap17, rsCOP47, and rsCOP17 | No | constant |
rsCOP17=float
For rsType=ASHP, rated heating coefficient of performance at outdoor dry-bulb temperature = 17 oF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | Calculated from rsHSPF, rsCap47, and rsCap17 | No | constant |
rsCapRat1747=float
Ratio of rsCAP17 over rsCAP47.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | Based on HSPF or other correlations | No | Start of a run |
rsCapRat9547=float
Ratio of rsCAP95 to rsCAP47. This ratio is used for inter-defaulting rsCap47 and rsCapC such that they have consistent values as is required given that a heat pump is a single device. If not given, rsCapRat9547 is determined during calculations using the relationship cap95 = 0.98 * cap47 + 180 (derived via correlation of capacities of a set of real units).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | See above | No | constant |
rsCapRatCH=float
For WSHP only: ratio of rsCapC to rsCapH. Used to derive capacity during autosizing or when only one capacity is specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
.3 \(\leq\) x \(<\) 2 | 0.8 | No | Start of a run |
rsPerfMapHtg=performanceMapName
Specifies the heating performance PERFORMANCEMAP for RSYSs having rsType=ASHPPM. The PERFORMANCEMAP must have grid variables outdoor drybulb and compressor speed (in that order) and lookup values of net capacity ratios and COP. See example in PERFORMANCEMAP.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Name of a PERFORMANCEMAP | if rsType specifies a performance map model | Start of a run |
rsPerfMapClg=performanceMapName
Specifies the cooling performance PERFORMANCEMAP for RSYSs having rsType=ASHPPM, ACPM, ACPMFURNACE, ACPMRESISTANCE, or ACPMCOMBINEDHEATDHW. The PERFORMANCEMAP must have grid variables outdoor drybulb and compressor speed (in that order) and lookup values of net capacity ratios and COP. See example in PERFORMANCEMAP.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Name of a PERFORMANCEMAP | if rsType specifies a performance map model | Start of a run |
rsTypeAuxH=choice
For rsType=ASHP, type of auxiliary heat. Auxiliary heating is used when heatpump capacity is insufficient to maintain zone temperature and during reverse-cycle defrost operation (if rsDefrostModel=REVCYCLEAUX). If rsTypeAuxH=Furnace, energy use for auxiliary heat is accumulated to end use HPBU of meter rsFuelMtr (if specified). If rsTypeAuxH=Resistance, energy use for auxiliary heat is accumulated to end use HPBU of meter rsElecMtr (if specified).
Choice | Description |
---|---|
NONE | No auxiliary heat |
RESISTANCE | Electric resistance (aka strip heat) |
FURNACE | Fuel-fired |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
See table above | RESISTANCE | No | constant |
rsCtrlAuxH=choice
For rsType=ASHP, type of auxiliary heating control.
Choice | Description |
---|---|
LOCKOUT | Compressor locked out if any auxiliary heating control |
CYCLE | Compressor runs continuously and auxiliary cycles |
ALTERNATE | Alternates between compressor and auxiliary |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
See table above | ALTERNATE if rsTypeAuxH=FURNACE else CYCLE | No | Start of a run |
rsCapAuxH=float
For rsType=ASHP, auxiliary heating capacity. If AUTOSIZEd, rsCapAuxH is set to the peak heating load evaluated at the heating design temperature (Top.heatDsTDbO).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/hr | AUTOSIZE or x \(\ge\) 0 | 0 | No | constant |
rsAFUEAuxH=float
For rsType=ASHP, auxiliary heat annualized fuel utilization efficiency.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.9 if rsTypeAuxH=FURNACE else 1 | No | constant |
rsDefrostModel=choice
Selects modeling options for ASHP outdoor coil defrosting when 17 oF < TDbO < 45 oF. In this temperature range, heating capacity and/or efficiency are typically reduced due to frost accumulation on the outdoor coil.
NONE | Defrost is not modeled. When 17 oF < TDbO < 45 oF, capacity and efficiency are determined by interpolation using unmodified 17 oF and 47 oF data. |
REVCYCLE | Reverse compressor (cooling) operation. Net capacity and efficiency is derived from rsCap17/rsCOP17 and rsCap35/rsCOP35 using linear interpolation. Auxiliary heat is not modeled. |
REVCYCLEAUX | Reverse compressor (cooling) operation with provision of sufficient auxiliary heat to make up the loss of heating capacity. Auxiliary heating is typically used to prevent cold air delivery to zones during the defrost cycle. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
one of above choices | REVCYCLEAUX | No | constant |
rsSHRtarget=float
Nominal target for sensible heat ratio (for fancoil).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.7 | No | subhour |
rsFxCapAuxH=float
Auxiliary heating autosizing capacity factor. If AUTOSIZEd, rsCapAuxH is set to rsFxCapAuxH \(\times\) (peak design-day load). Peak design-day load is the heating capacity that holds zone temperature at the thermostat set point during the last substep of all hours of all design days.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
rsSEER=float
Cooling rated Seasonal Energy Efficiency Ratio (SEER).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/Wh | x \(>\) 0 | none | Yes | constant |
rsEER=float
Cooling Energy Efficiency Ratio (EER) at standard AHRI rating conditions (outdoor drybulb of 95 oF and entering air at 80 oF drybulb and 67 oF wetbulb). For rsType=WSHP, rated EER at fluid source temperature = 86 oF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/Wh | x \(>\) 0 | Estimated from SEER unless WSHP | Yes for WSHP else No | constant |
rsCapC=float
Net cooling capacity at standard rating conditions (outdoor drybulb temperature = 95 oF for air source or fluid source temperature = 86 oF for water source).
If rsType=ASHP and both rsCapC and rsCap47 are autosized, both are set to the larger consistent value using rsCapRat9547 (after application of rsFxCapH and rsFxCapC).
If rsType=WSHP and both rsCapC and rsCapH are autosized, both are set to the larger consistent value using rsCapRatCH (after application of rsFxCapH and rsFxCapC).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/hr | AUTOSIZE or x \(\le\) 0 (x \(>\) 0 coverted to \(<\) 0) | none | Yes if rsType includes cooling | constant |
rsTdDesC=float
Nominal cooling temperature fall (across system, not zone) used during autosizing (when capacity is not yet known).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(<\) 0 | -25 | No | constant |
rsFxCapC=float
Cooling autosizing capacity factor. rsCapC is set to rsFxCapC \(\times\) (peak design-day load). Peak design-day load is the cooling capacity that holds zone temperature at the thermostat set point during the last substep of all hours of all design days.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1.4 | No | constant |
rsFChg=float
Cooling compressor capacity factor. The gross cooling capacity is adjusted by the factor rsFChg as specified by California Title 24 procedures.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 (no effect) | No | constant |
rsVFPerTon=float
Standard air volumetric flow rate per nominal ton of cooling capacity.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm/ton | 150 \(\le\) x \(\le\) 500 | 350 | No | constant |
rsFanPwrC=float
Cooling fan power.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | x \(\ge\) 0 | 0.365 | No | constant |
rsASHPLockOutT=float
Source air dry-bulb temperature below which the air source heat pump compressor does not operate.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | (no lockout) | No | hourly |
rsCdH=float
Heating cyclic degradation coefficient, valid only for compressor-based heating (heat pumps).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 0.5 | ASHPHYDRONIC: 0.25 ASHP: derived from rsHSPF | No | hourly |
rsCdC=float
Cooling cyclic degradation coefficient, valid for configurations having compressor-based cooling.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 0.5 | 0 | No | hourly |
rsFEffH=float
Heating efficiency factor. At each time step, the heating efficiency is multiplied by rsFEffH.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | subhourly |
rsFEffAuxHBackup=float
Backup auxiliary heating efficiency factor. At each time step, the backup heating efficiency is multiplied by rsFEffAuxHBackup. Backup auxiliary heating is typically provided by electric resistance “strip heat” but may be provided by a furnace (see rsTypeAuxH). If rsTypeAuxH is not “none”, backup heat operates when air source heat pump compressor capacity is insufficient to meet heating load. See also rsFEffAuxHDefrost.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | subhourly |
rsFEffAuxHDefrost=float
Defrost auxiliary heating efficiency factor. At each time step, the defrost auxiliary heating efficiency is multiplied by rsFEffAuxHDefrost. Defrost auxiliary heating is typically provided by electric resistance “strip heat” but may be provided by a furnace (see rsTypeAuxH). If rsDefrostModel=REVCYCLEAUX, defrost auxiliary heat operates during air source heat pump defrost mode. Since defrost and backup heating are generally provided by the same equipment, rsFEffAuxHDefrost and rsFEffAuxHBackup are usually set to the same value, but separate inputs are available for special cases.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | subhourly |
rsFEffC=float
Cooling efficiency factor. At each time step, the cooling efficiency is multiplied by rsEffC.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | subhourly |
rsCapNomH=float
Heating nominal capacity. Provides type-independent probe source for RSYS heating capacity. Daily variability is specified to support value changes during AUTOSIZEing. Values set via input are typically constant.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/hr | x \(\ge\) 0 | no heating: 0 heat pump: rsCap47 (input or AUTOSIZEd) other: rsCapH (input or AUTOSIZEd) | No | daily |
rsCapNomC=float
Cooling nominal capacity. Provides type-independent probe source for RSYS cooling capacity. Daily variability is specified to support value changes during AUTOSIZEing. Values set via input are typically constant.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/hr | x \(\ge\) 0 | no cooling: 0 other: rsCap95 (input or AUTOSIZEd) | No | daily |
rsDSEH=float
Heating distribution system efficiency. If given, (1-rsDSEH) of RSYS heating output is discarded. Cannot be combined with more detailed DUCTSEG model.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 < x < 1 | (use DUCTSEG model) | No | hourly |
rsDSEC=float
Cooling distribution system efficiency. If given, (1-rsDSEC) of RSYS cooling output is discarded. Cannot be combined with more detailed DUCTSEG model.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 < x < 1 | (use DUCTSEG model) | No | hourly |
rsOAVType=choice
Type of central fan integrated (CFI) outside air ventilation (OAV) included in this RSYS. OAV systems use the central system fan to circulate outdoor air (e.g. for night ventilation).
OAV cannot operate simultaneously with whole building ventilation (operable windows, whole house fans, etc.). Availability of ventilation modes is controlled on an hourly basis via Top ventAvail.
NONE | No CFI ventilation capabilities |
FIXED | Fixed-flow CFI (aka SmartVent). The specified rsOAVVfDs is used whenever the RSYS operates in OAV mode. |
VARIABLE | Variable-flow CFI (aka NightBreeze). Flow rate is determined at midnight based on prior day’s average dry-bulb temperature according to a control algorithm defined by the NightBreeze vendor. |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
NONE, FIXED, VARIABLE | none | No | constant |
rsOAVVfDs=float
Design air volume flow rate when RSYS is operating in OAV mode.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
cfm | x \(\ge\) 0 | none | if rsOAVType $ e$ NONE | constant |
rsOAVVfMinF=float
Minimum air volume flow rate fraction when RSYS is operating in OAV mode. When rsOAVType=VARIABLE, air flow rate is constrained to rsOAVVfMinF * rsOAVVfDs or greater.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.2 | No | constant |
rsOAVFanPwr=float
RSYS OAV-mode fan power.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | 0 < x \(\le\) 5 | per rsOAVTYPE FIXED: rsFanPwrC VARIABLE: NightBreeze vendor curve based on rsOAVvfDs | No | constant |
rsOAVTDbInlet=float
OAV inlet (source) air temperature. Supply air temperature at the zone is generally higher due to fan heat. Duct losses, if any, also alter the supply air temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | Dry-bulb temperature from weather file | No | hourly |
rsOAVTdiff=float
OAV temperature differential. When operating in OAV mode, the zone set point temperature is max( znTD, inletT+rsOAVTdiff). Small values can result in inadvertent zone heating, due to fan heat.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 5 oF | No | hourly |
rsOAVReliefZn=znName
Name of zone to which relief air is directed during RSYS OAV operation, typically an attic zone. Relief air flow is included in the target zone’s pressure and thermal balance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of ZONE | none | if rsOAVType $ e$ NONE | constant |
rsParElec=float
Parasitic electrical power. rsParElec is unconditionally accumulated to end use AUX of rsElecMtr (if specified) and has no other effect.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | 0 | No | hourly |
rsParFuel=float
Parasitic fuel use. rsParFuel is unconditionally accumulated to end use AUX of sFuelMtr (if specified) and has no other effect.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | 0 | No | hourly |
rsRhIn=float
Entering air relative humidity (for model testing).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W/cfm | 0 \(\le\) x \(\le\) 1 | Derived from entering air state | No | constant |
rsTdbOut=float
Air dry-bulb temperature at the outdoor portion of this system.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | From weather file | No | hourly |
endRSYS
Optionally indicates the end of the RSYS definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.26 DUCTSEG
DUCTSEG defines a duct segment. Each RSYS has at most one return duct segment and at most one supply duct segment. That is, DUCTSEG input may be completely omitted to eliminate duct losses.
dsName
Optional name of duct segment; give after the word “DUCTSEG” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
dsTy=choice
Duct segment type.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
SUPPLY, RETURN | Yes | constant |
The surface area of a DUCTSEG depends on its shape. 0 surface area is legal (leakage only). DUCTSEG shape is modeled either as flat or round –
- dsExArea specified: Flat. Interior and exterior areas are assumed to be equal (duct surfaces are flat and corner effects are neglected).
- dsExArea not specified: Round. Any two of dsInArea, dsDiameter, and dsLength must be given. Insulation thickness is derived from dsInsulR and dsInsulMat and this thickness is used to calculate the exterior surface area. Overall inside-to-outside conductance is also calculated including suitable adjustment for curvature.
dsBranchLen=float
Average branch length.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(>\) 0 | -1.0 | No | constant |
dsBranchCount=integer
Number of branches.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | -1 | No | constant |
dsBranchCFA=float
Floor area served per branch
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(>\) 0 | -1.0 | No | constant |
dsAirVelDs=float
Specified air velocity design.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
fpm | x \(>\) 0 | -1.0 | No | constant |
dsExArea=float
Duct segment surface area at outside face of insulation for flat duct shape, see above.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(\ge\) 0 | none | No | constant |
dsInArea=float
Duct segment inside surface area (at duct wall, duct wall thickness assumed negligible) for round shaped duct.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2 | x \(\ge\) 0 | Derived from dsDiameter and dsLength | (see above reduct shape) | constant |
dsDiameter=float
Duct segment round duct diameter (duct wall thickness assumed negligible)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | Derived from dsInArea and dsLength | (see above reduct shape) | constant |
dsLength=float
Duct segment length.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | Derived from dsInArea and dsDiameter | (see above reduct shape) | constant |
dsExCnd=choice
Conditions surrounding duct segment.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ADIABATIC, AMBIENT, SPECIFIEDT, ADJZN | ADJZN | No | constant |
dsAdjZn=znName
Name of zone surrounding duct segment; used only when dsExCon is ADJZN. Can be the same as a zone served by the RSYS owning the duct segment.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | none | Required when dsExCon = ADJZN | constant |
dsEpsLW=float
Exposed (i.e. insulation) outside surface exterior long wave (thermal) emittance.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 0.9 | No | constant |
dsExT=float
Air dry-bulb temperature surrounding duct segment.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | unrestricted | none | Required if sfExCnd = SPECIFIEDT | hourly |
dsInsulR=float
Insulation thermal resistance not including surface conductances. dsInsulR and dsInsulMat are used to calculate insulation thickness (see below). Duct insulation is modeled as a pure conductance (no mass).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2-oF-hr / Btu | x \(\ge\) 0 | 0 | No | constant |
dsInsulMat=matName
Name of insulation MATERIAL. The conductivity of this material at 70 oF is combined with dsInsulR to derive the duct insulation thickness. If omitted, a typical fiberglass material is assumed having conductivity of 0.025 Btu/hr-ft2-F at 70 oF and a conductivity coefficient of .00418 1/F (see MATERIAL). In addition, insulation conductivity is adjusted during the simulation in response its average temperature. As noted with dsInsulR, duct insulation is modeled as pure conductance – MATERIAL matDens and matSpHt are ignored.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a MATERIAL | fiberglass | No | constant |
dsLeakF=float
Duct leakage. Return duct leakage is modeled as if it all occurs at the segment inlet. Supply duct leakage is modeled as if it all occurs at the outlet.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) x \(\le\) 1 | none | No | constant |
dsExH=float
Outside (exposed) surface convection coefficient.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(\ge\) 0 | .54 | No | subhourly |
endDuctSeg
Optionally indicates the end of the DUCTSEG definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.27 PERFORMANCEMAP
PERFORMANCEMAP defines a multiple-dimension table of values from which models can derive performance data via interpolation. Subordinate PMGRIDAXIS and PMLOOKUPDATA allow input of performance maps of a range of dimensions and granularity.
Following ASHRAE Standard 205 terminology, sets of “grid” values are the independent variables and sets of “lookup” values are the dependent variables.
The following example defines a 2D map based on grid variables outdoor dry-bulb temperature and (arbitrary) compressor speed. For each grid value combination, lookup values are provided for capacity ratio and COP.
PERFORMANCEMAP "PMClg"
PMGRIDAXIS "ClgOutdoorDBT" pmGXType="OutdoorDBT" pmGXValues=60,82,95,115 pmGXRefValue=95
PMGRIDAXIS "ClgSpeed" pmGType="Speed" pmGXValues=1,2,3 pmGXRefValue=2
// Capacity ratio = net total capacity / net rated total capacity
PMLOOKUPDATA LUClgCapRat pmLUType = "CapRat" pmLUValues =
0.48, 1.13, 1.26, // 60F at min, mid, max speed
0.42, 1.05, 1.17, // 82F
0.39, 1.00, 1.12, // 95F
0.34, 0.92, 1.04 // 115F
// COP = net total COP
PMLOOKUPDATA LUClgCOP pmLUType = "COP" pmLUValues =
14.22, 16.44, 15.00, // 60F at min, mid, max speed
7.93, 7.59, 6.71, // 82F
6.01, 5.58, 4.91, // 95F
4.12, 3.82, 3.34 // 115F
endPERFORMANCEMAP
At OutdoorDBT=95 and Speed=2, this performance map would yield CapRat=1.00 and COP=5.58. At other (OutdoorDBT,Speed) combinations, suitable 2D interpolation is performed on each lookup variable. Lookup variables are extrapolated outside of PMGRIDAXIS ranges; adequate axis ranges must be provided to avoid unrealistic extrapolation.
pmName
Name of performance map; given after the word “PERFORMANCEMAP”. Necessary to allow reference from e.g. RSYS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
endPERFORMANCEMAP
Optionally indicates the end of PERFORMANCEMAP definition. It is good practice to include endPerformanceMap after the associated PMGRIDAXIS and PMLOOKDATA.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
4.28 PMGRIDAXIS
Defines grid values for a single dimension of the parent (preceeding) PERFORMANCEMAP.
The order of PMGRIDAXIS commands fixes the order of PMLOOKUPDATA values – later PMGRIDAXIS dimensions vary more quickly (see example above).
pmGXName
Name of grid axis; optionally given after the word “PMGRIDAXIS”. Used in error messages.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
pmGXType=string
Documents the dimension of the axis, for example “OutdoorDBT”, “Speed”, or “AirFlow”.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
at least 1 char | none | Yes | constant |
pmGXValues=float array
1 to 10 comma-separated values specifying the data points of this axis. Must be in strictly ascending order.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
various | none | Yes | constant |
pmGXRefValue=float
Defines the reference or nominal value of this PMGRIDAXIS. For example, when defining temperature points for a typical air conditioner, pmGXRefValue=95 might be used, since AC capacity is rated at 95 F.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
same as pmGXValues | none | Yes | constant |
endPMGRIDAXIS
Optionally indicates the end of PMGRIDAXIS definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
4.29 PMLOOKUPDATA
*pmLUName**
Name of lookup data; optionally given after the word “PMLOOKUPDATA”. Used in error messages.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
pmLUType=string
Documents the current lookup value, e.g. “COP” or “CapacityRatio”.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
at least 1 char | none | Yes | constant |
pmLUValues=float array
Comma-separated values specifying the lookup data. The number of values required is the product of the size of all PMGRIDAXISs in the current PEFORMANCEMAP. In the example above, there are 4 OutdoorDBTs and 3 speeds, so 12 values must be provided.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
various | none | Yes | constant |
endPMLOOKUPDATA
Optionally indicates the end of PMLOOKUPDATA definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
4.30 DHWDAYUSE
Defines an object that represents domestic hot water use for a single day. A DHWDAYUSE contains a collection of DHWUSE objects that specify the time, volume, and duration of individual draws. DHWDAYUSEs are referenced by DHWSYS wsDayUse. Unreferenced DHWDAYUSEs are allowed.
DHWDAYUSEs and their child DHWUSEs are used to construct minute-by-minute hot water use schedules in addition to aggregated hourly schedules. The minute-by-minute schedules are used for modeling resistance and heat pump storage water heaters, see DHWHEATER whType=SmallStorage whHeatSrc=ResistanceX or whHeatSrc=ASHPX.
The following illustrates some features of DHWDAYUSE / DHWUSE –
DHWDAYUSE "Sample"
// 6 AM: 7 min shower, 2 gpm @ 105 F
DHWUSE whStart=6.0 wuDuration=7 wuFlow=2 wuTemp=105 wuEndUse=Shower wuEventID=1
// 7 AM: 1 min faucet draw, 100% hot
DHWUSE whStart=7.0 wuDuration=1 wuFlow=1 wuHotF=1 whEndUse=Faucet wuEventID=2
// 12:30 PM: dishwasher start, several draws over 70 mins; note common wuEventID
DHWUSE whStart=12.5 wuDuration=2 wuFlow=2 wuHotF=1 whEndUse=DWashr wuEventID=3
DHWUSE whStart=12.8 wuDuration=1.5 wuFlow=2 wuHotF=1 whEndUse=DWashr wuEventID=3
DHWUSE whStart=13.6 wuDuration=3 wuFlow=2 wuHotF=1 whEndUse=DWashr wuEventID=3
// 7 PM every 2nd day: clothes washer runs
// even days: 0 gpm (no draw)
// odd days: 3 gpm, 22% hot
DHWUSE whStart=19 wuDuration=30 wuFlow = ($dayOfYear%2)*3 whEndUse=CWashr whHotF=.22 wuEventID=4
// 11:54 PM: 20 min bath, 1.5 gpm, 80% hot water
// Duration spans midnight: draw is wrapped to beginning of *current* day
// In this case a 12 M - 12:14 AM draw is modeled -- before (!) the bath start.
DHWUSE whStart 23.9 wuDuration=20 wuFlow=1.5 wuHotF=.8 whEndUse=Bath wuEventID=99
endDHWDAYUSE
DHWSYS "DHWSYS1"
...
wsDayUse = "Sample"
...
During the simulation, DHWUSEs are evaluated each hour. Many DHWUSE values have hourly variability and this allows complicated schemes to be constructed very flexibly. For example:
DHWDAYUSE "HourlyFaucet"
// Every hour on the half hour: 5 minute, 2 gpm draw
// Same as 24 DHWUSEs, one for each hour
DHWUSE wuStart=$hour+.5 wuDuration=5 wuFlow=2 wuEndUse=Faucet
endDAYUSE
Some DHWUSE configurations involve mixing to specified wuTemp. Hot and cold water arriving at the point of use is assumed to be at DHWSYS wsUseTemp and wsMainsTemp respectively. It is possible to set up situations where wuTemp cannot be achieved (wuTemp > wsUseTemp, for example). Runtime error messages are produced when impossible conditions are detected.
When more than one DHWSYS references the same DHWDAYUSE, DHWUSEs are allocated to DHWSYSs in wuEventID rotation. This procedure divides the water heating load approximately equally while retaining the peak demand of individual events. When detailed information is available about which loads are served by specific systems, separate DHWDAYUSEs should be given.
dhwDayUseName
Object name, given after “DHWDAYUSE”. Required for referencing from DHWSYS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | Yes | constant |
wduMult=float
Scale factor applied to all draws in this DHWDAYUSE.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
endDHWDAYUSE
Indicates the end of the DHWDAYUSE definition. endDHWDAYUSE should follow all child DHWUSEs. Alternatively, the end of the meter definition can be indicated by the declaration of another object or by END.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.31 DHWUSE
Defines a single hot water draw as part of a DHWDAYUSE. See discussion and examples under DHWDAYUSE. As noted there, most DHWUSE values have hourly variability, allowing flexible representation.
wuName
Optional name; give after the word “DHWUSE” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wuStart=float
The starting time of the hot water draw.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
hr | 0 \(\le\) x \(\le\) 24 | none | Yes | constant |
wuDuration=float
Draw duration. wuDuration = 0 is equivalent to omitting the DHWUSE. Durations that extend beyond midnight are included in the current day.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
min | 0 \(\le\) x \(\le\) 1440 | 0 | No | hourly |
wuFlow=float
Draw flow rate at the point of use (in other words, the mixed-water flow rate). wuFlow = 0 is equivalent to omitting the DHWUSE. There is no enforced upper limit on wuFlow, however, unrealistically large values can cause runtime errors.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gpm | x \(\le\) 0 | 0 | No | hourly |
wuHotF=float
Fraction of draw that is hot water. Cannot be specified with wuTemp or wuHeatRecEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 1 | No | hourly |
wuTemp=float
Mixed-water use temperature at the fixture. Cannot be specified when wuHotF is given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\le\) 0 | 0 | when wuHeatRecEF is given or parent DHWSYS includes DHWHEATREC(s) | hourly |
wuHeatRecEF=float
Heat recovery effectiveness, allows simple modeling of heat recovery devices such as drain water heat exchangers.
If non-0 (evaluated hourly), hot water use is reduced based on wuTemp, DHWSYS wsTUse, and DHWSYS wsTInlet. DHWHEATREC(s), if any, are ignored for this use. wuTemp must be specified.
If 0, detailed heat recovery modeling may apply, see DHWHEATREC.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 0.9 | 0 | No | hourly |
wuHWEndUse=choice
Hot-water end use: one of Shower, Bath, CWashr, DWashr, or Faucet. wuHWEndUse has the following functions –
- Allocation of hot water use among multiple DHWSYSs (if more than one DHWSYS references a given DHWDAYUSE).
- DHWMETER end-use accounting (via DHWSYS).
- Activation of the detailed heat recovery model (available for end use Shower when wuHeatRecEF=0 and the parent DHWSYS includes DHWHEATREC(s)).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
One of above choices | (use allocated to Unknown) | No | constant |
wuEventID=integer
User-defined identifier that associates multiple DHWUSEs with a single event or activity. For example, a dishwasher uses water at several discrete times during a 90 minute cycle and all DHWUSEs would be assigned the same wuEventID. All DHWUSEs having the same wuEventID should have the same wuHWEndUse.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0 | No | constant |
endDHWUSE
Optionally indicates the end of the DHWUSE definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
Related Probes:
4.32 DHWSYS
DHWSYS constructs an object representing a domestic hot water system consisting of one or more hot water heaters, storage tanks, loops, and pumps (DHWHEATER, DHWTANK, DHWLOOP, and DHWPUMP, see below) and a distribution system characterized by loss parameters. This model is based on Appendix B of the 2019 Residential ACM Reference Manual and the Ecotope HPWHSim air source heat pump water heater model (called HPWH herein).
The parent-child structure of DHWSYS components is determined by input order. For example, DHWHEATERs belong to the DHWSYS that precedes them in the input file. The following hierarchy shows the relationship among components. Note that any of the commands can be repeated any number of times.
- DHWSYS
- DHWHEATER
- DHWLOOPHEATER
- DHWHEATREC
- DHWTANK
- DHWPUMP
- DHWLOOP
- DHWLOOPPUMP
- DHWLOOPSEG
- DHWLOOPBRANCH
Minimal modeling is included for physically realistic controls. For example, if several DHWHEATERs are included in a DHWSYS, an equal fraction of the required hot water is assumed to be produced by each heater, even if they are different types or sizes. Thus a DHWSYS is in some ways a collection of components as opposed to an explicitly connected system. This approach avoids requiring detailed input that would impose impractical user burden, especially in compliance applications.
dhwsysName
Optional name of system; give after the word “DHWSYS” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wsCalcMode=choice
Enables preliminary simulation that derives values needed for simulation.
PRERUN | Calculate hot water heating load; at end of run, derive whLDEF for all child DHWHEATERs for which that value is required and defaulted (this emulates methods used in the T24DHW.DLL implementation of CEC DHW procedures). Also derived are average number of draws per day by end use (used in the wsDayWaste scheme). |
SIMULATE | Perform full modeling calculations |
To use PRERUN efficiently, the recommended input file structure is:
- General input
- DHWSYS(s) and child objects
- RUN
- ALTER DHWSYS input (as needed)
- Building input
- RUN
This order avoids duplicate time-consuming simulation of the full building model.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | SIMULATE | No |
wsCentralDHWSYS=dhwsysName
Name of the central DHWSYS that serves this DHWSYS, allowing representation of multiple units having distinct distribution configurations and/or water use patterns but served by a central DHWSYS. The child DHWSYS(s) may not include DHWHEATERs – they are “loads only” systems. wsCentralDHWSYS and wsLoadShareDHWSYS cannot both be given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a DHWSYS | DHWSYS is standalone | No | constant |
wsLoadShareDHWSYS=dhwsysName
Name of a DHWSYS that serves the same loads as this DHWSYS, allowing representation of multiple water heating systems within a unit. If given, wsUse and wsDayUse are not allowed, hot water requirements are derived from the referenced DHWSYS. wsCentralDHWSYS and wsLoadShareDHWSYS cannot both be given.
For example, two DHWSYSs should be defined to model two water heating systems serving a load represented by wsDayUse DayUseTyp. Each DHWSYS should include DHWHEATER(s) and other components as needed. DHWSYS Sys1 should specify wsDayUse=DayUseTyp and DHWSYS Sys2 should have wsLoadShareDHWSYS=Sys1 in place of wsDayUse.
Loads are shared by assigning DHWUSE events sequentially by end use to all DHWSYS with compatible fixtures (determined by wsFaucetCount, wsShowerCount etc., see below) in the group. This algorithm approximately divides load for each end use by the number of compatible fixtures in the group. In addition, assigning 0 to a fixture type prevents assignment of an end use load to a DHWSYS – for example, wsDWashrCount=0 could be provided for a DHWSYS that does not serve a kitchen.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a DHWSYS | No shared loads | No | constant |
wsMult=float
Number of identical systems of this type (including all child objects). Any value \(> 1\) is equivalent to repeated entry of the same DHWSYS. A value of 0 is equivalent to omitting the DHWSYS. Non-integral values scale all results; this may be useful in parameterized models, for example.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
wsFaucetCount=integer
wsShowerCount=integer
wsBathCount=integer
wsCWashrCount=integer
wsDWashrCount=integer
Specifies the count of fixtures served by this DHWSYS that can accommodate draws of each end use (see DHWUSE). These counts are used for distributing draws in shared load configurations (multiple DHWSYSs serving the same loads, see wsLoadShareDHWSYS above).
In addition, wsShowerCount participates in assignment of Shower draws to DHWHEATRECs (if any).
Unless this DHWSYS is part of a shared-load group or includes DHWHEATREC(s), these counts have no effect and need not be specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
wsTInlet=float
Specifies cold (mains) water temperature supplying this DHWSYS. DHWHEATER supply water temperature wsTInlet adjusted (increased) by any DHWHEATREC recovered heat and application of wsSSF (approximating solar preheating).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | \(>\) 32 oF | Mains temp from weather file | No | hourly |
wsTInletTest=float
Overides at the substep interval the cold (mains) water temperature supplying this DHWSYS.
CAUTION: wsTInletTest is intended for testing and model validation studies and should not be generally used. It is not fully supported for all DHWSYS configurations. wsTInletTest is allowed only for configurations using HPWH-based DHWHEATERs (whHeatSrc=ASHPX or whHeatSrc=RESISTANCEX).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | \(>\) 32 oF | No | subhourly |
wsTInletDes=float
Cold water inlet design temperature for sizing.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 32 oF | Annual minimums mains temperature | No | constant |
wsUse=float
Hourly hot water use (at the point of use). See further info under wsDayUse.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | x \(\ge\) 0 | 0 | No | hourly |
wsUseTest=float
Additional substep hot water use added to draw(s) specfied by wsHWUse and wsDayUse.
CAUTION: wsUseTest is intended for testing and model validation studies and should not be generally used. It is not fully supported for all DHWSYS configurations. wsUseTest is allowed only for configurations using HPWH-based DHWHEATERs (whHeatSrc=ASHPX or whHeatSrc=RESISTANCEX).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | x \(\ge\) 0 | No | subhourly |
wsDayUse=dhwdayuseName
Name of DHWDAYUSE object that specifies a detailed schedule of mixed water use at points of hot water use (that is, “at the tap”). The mixed water amounts are used to derive hot water requirements based on specified mixing fractions or mixed water temperature (see DHWDAYUSE and DHWUSE).
The total water use modeled by CSE is the sum of amounts given by wsUse and the DWHDAYUSE schedule. DHWDAYUSE draws are resolved to minute-by-minute bins compatible with the HPWH model and wsUse/60 is added to each minute bin. Conversely, the hour total of the DHWDAYUSE amounts is included in the draw applied to non-HPWH DHWHEATERs.
wsDayUse variability is daily, so it is possible to select different schedules as a function of day type (or any other condition), as follows –
DHWSYS "DHW1"
...
wsDayUse = choose( $isWeHol, "DUSEWeekday", "DUSEWeHol")
...
Note that while DHWDAYUSE selection is updated daily, the DHWUSE values within the DHWDAYUSE can be altered hourly, providing additional scheduling flexibility.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a DHWDAYUSE | (no scheduled draws) | No | daily |
wsFaucetDrawDurF=float
Water heater draw duration factor for faucets. Defined as the ratio of the actual draw duration (including time waiting for hot water to arrive at the fixture) to the nominal draw duration (as though hot water was instantly available).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 0.0 | No | Hourly |
wsShowerDrawDurF=float
Water heater draw duration factor for showers. Defined as the ratio of the actual draw duration (including time waiting for hot water to arrive at the fixture) to the nominal draw duration (as though hot water was instantly available).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 0.0 | No | Hourly |
wsBathDrawDurF=float
Water heater draw duration factor for baths. Defined as the ratio of the actual draw duration (including time waiting for hot water to arrive at the fixture) to the nominal draw duration (as though hot water was instantly available).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 0.0 | No | Hourly |
wsCWashrDrawDurF=float
Water heater draw duration factor for clothes washers. Defined as the ratio of the actual draw duration (including time waiting for hot water to arrive at the fixture) to the nominal draw duration (as though hot water was instantly available).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 1.0 | No | Hourly |
wsDWashrDurF=float
Water heater draw duration factor for dishwashers. Defined as the ratio of the actual draw duration (including time waiting for hot water to arrive at the fixture) to the nominal draw duration (as though hot water was instantly available).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 1.0 | No | Hourly |
wsUnkDrawDurF=float
Water heater draw duration factor for unknown end use. Defined as the ratio of the actual draw duration (including time waiting for hot water to arrive at the fixture) to the nominal draw duration (as though hot water was instantly available).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 0.0 | No | Hourly |
wsFaucetDrawWaste=float
Draw water waste for faucets. Specifies additional draw volume per DHWUSE event (at fixture, by end use). This can be used to account for water discarded during warmup or otherwise adjust the draw volume. Because the values are at the fixture, the impact on hot water demand additionally depends on DHWUSE parameters. The value is applied by lengthening (or shortening) the draw duration.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal/draw | x \(\geq\) 0 | 0.0 | No | Hourly |
wsShowerDrawWaste=float
Draw water waste for showers. Specifies additional draw volume per DHWUSE event (at fixture, by end use). This can be used to account for water discarded during warmup or otherwise adjust the draw volume. Because the values are at the fixture, the impact on hot water demand additionally depends on DHWUSE parameters. The value is applied by lengthening (or shortening) the draw duration.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal/draw | x \(\geq\) 0 | 0.0 | No | Hourly |
wsBathDrawWaste=float
Draw water waste for baths. Specifies additional draw volume per DHWUSE event (at fixture, by end use). This can be used to account for water discarded during warmup or otherwise adjust the draw volume. Because the values are at the fixture, the impact on hot water demand additionally depends on DHWUSE parameters. The value is applied by lengthening (or shortening) the draw duration.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal/draw | x \(\geq\) 0 | 0.0 | No | Hourly |
wsCWashrDrawWaste=float
Draw water waste for clothes washers. Specifies additional draw volume per DHWUSE event (at fixture, by end use). This can be used to account for water discarded during warmup or otherwise adjust the draw volume. Because the values are at the fixture, the impact on hot water demand additionally depends on DHWUSE parameters. The value is applied by lengthening (or shortening) the draw duration.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal/draw | x \(\geq\) 0 | 0.0 | No | Hourly |
wsDWashrDrawWaste=float
Draw water waste for dishwashers. Specifies additional draw volume per DHWUSE event (at fixture, by end use). This can be used to account for water discarded during warmup or otherwise adjust the draw volume. Because the values are at the fixture, the impact on hot water demand additionally depends on DHWUSE parameters. The value is applied by lengthening (or shortening) the draw duration.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal/draw | x \(\geq\) 0 | 0.0 | No | Hourly |
wsUnkDrawWaste=float
Draw water waste for unknown end use. Specifies additional draw volume per DHWUSE event (at fixture, by end use). This can be used to account for water discarded during warmup or otherwise adjust the draw volume. Because the values are at the fixture, the impact on hot water demand additionally depends on DHWUSE parameters. The value is applied by lengthening (or shortening) the draw duration.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal/draw | x \(\geq\) 0 | 0.0 | No | Hourly |
wsTRLTest=float
Circulation loop return temperature for testing and validation.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
F | x \(\geq\) 0 | 0.0 | No | Subhourly |
wsVolRLTest=float
Circulation loop volume flow rate for testing and validation.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gpm | x \(\geq\) 0 | 0.0 | No | Subhourly |
wsBranchModel=choice
Branch model selection.
wsBranchModel | Description |
---|---|
T24DHW | Model in appendix B of the Alternative Compliance Manual |
DRAWWASTE | Draw duration increase per draw waste |
DAYWASTE | draw duration increase per day waste |
wsDayWasteVol=float
Average amount of waste per day.
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
gal/day | x \(\ge\) 0 | wsDayWasteBranchVolF * (Total DHWLOOPBRANCH vol) | No | constant |
wsDayWasteBranchVolF=float
Day waste scaling factor.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
wsFaucetDayWasteF=float
Relative faucet water draw for day of waste scheme.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0 | No | subhourly |
wsShowerDayWasteF=float
Relative shower water draw for day of waste scheme.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0 | No | subhourly |
wsBathDayWasteF=float
Relative bath water draw for day of waste scheme.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0 | No | subhourly |
wsCWashrDayWasteF=float
Relative clothes washer water draw for day of waste scheme.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0 | No | subhourly |
wsDWashrDayWasteF=float
Relative dish washer water draw for day of waste scheme.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0 | No | subhourly |
wsUnkDayWasteF=float
Unknown relative water draw for day of waste scheme.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0 | No | subhourly |
wsTUse=float
Hot water delivery temperature (at output of water heater(s) and at point of use). Delivered water is mixed down to wsTUSe (with cold water) or heated to wsTUse (with extra electric resistance backup, see DHWHEATER whXBUEndUse). Note that draws defined via DHWDAYUSE / DHWUSE can specify mixing to a lower temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | \(>\) 32 oF | 120 | No | hourly |
wsTUseTest=float
Overides at the substep interval the hot water delivery temperature.
CAUTION: wsTUseTest is intended for testing and model validation studies and should not be generally used. It is not fully supported for all DHWSYS configurations. wsTUseTest is allowed only for configurations using HPWH-based DHWHEATERs (whHeatSrc=ASHPX or whHeatSrc=RESISTANCEX).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | \(>\) 32 oF | No | subhourly |
wsTSetPoint=float
Specifies the hot water setpoint temperature for all child DHWHEATERs. Used only for HPWH-based DHWHEATERs (HPWH models tank temperatures and heating controls), otherwise has no effect. wsTSetpoint can be modified hourly to achieve load-shifting effects.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | \(>\) 32 oF | wsTUse | No | hourly |
wsTSetPointLH=float
Specifies the hot water set point temperature for all child DHWLOOPHEATERs. Used only for HPWH-based DHWHLOOPEATERs (HPWH explicitly models tank temperatures and heating controls), otherwise has no effect.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | \(>\) 32 oF | wsTSetPoint | No | hourly |
wsTSetpointDes=float
Specifies the design (sizing) set point temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 32 oF | wsTUse | No | constant |
wsVolRunningDes=float
Running volume for design. Active volume (above aquastat) equals to a full tank volume, defaults from EcoSizer at end of prerun if not input. No direct use, must be passed to DHWHEATER via ALTER.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | x \(>\) 0 | 0.0 | No | constant |
wsASHPTSrcDes=float
Design (sizing) source air temperature for HPWH DHWHEATERs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 32 oF | Heating design temperature | No | At the start and at the end of interval |
wsFxDes=float
Excess size factor for domestic hot water design. wsFxDes is applied when wsHeatingCapDes and/or wsVolRunningDes are defaulted from EcoSizer at the end of the prerun. There is no effect if those values are input.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1.0 | No | constant |
wsDRMethod=choice
Selects alternative control schemes for HPWH-based DHWHEATERs. These allow shifting primary heater (compressor or resistance element) operation to times of day that have load-management advantages.
wsDRMethod | Description |
---|---|
NONE | None (default setpoint-based control) |
SCHEDULE | Demand response schedule (see wsDRSignal) |
STATEOFCHARGE | State-of-charge (see wsTargetSOC) |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
See table above | NONE | No | constant |
wsDRSignal=choice
When (and only when) wsDRMethod=SCHEDULE, wsDRSignal allows hourly specification of modified control schemes. Available signals are:
wsDRSignal | Description |
---|---|
ON | Normal operation following the water heater’s internal control logic. |
TOO | Tops off the tank once by engaging the all the available heating sources (compressor and resistive elements) in the water heater to heat the tank to setpoint (regardless of the current condition). |
TOOLOR | Tops off the tank once and locks out the resistance elements (only the compressor is used to heat the tank to setpoint). |
TOOLOC | Tops off the tank once and locks out the compressor (only the resistance elements are used to heat the tank to setpoint). |
TOT | Tops off the tank on a timer using all the available heating sources (compressor and resistive elements) in the water heater. The tank starts a timer and heating to setpoint when the call is received and repeats the heating call when the timer reaches zero. |
TOTLOR | Tops of the tank on a timer and locks out the resistance elements (only the compressor is used to heat the tank to setpoint). |
TOTLOC | Tops of the tank on a timer and locks out the compressor (only the resistance elements are used to heat the tank to setpoint). |
LOC | Locks out the compressor from the water heater’s normal internal control logic. |
LOR | Locks out the resistive elements from the water heater’s normal internal control logic. |
LOCLOR | Locks out the compressor and resistive elements from the water heater’s normal internal control logic. |
Scheduling functions can be used to construct control strategies of interest, for example:
wsDRSignal = $isWeHol
? hourval( on, on, on, on, on, on, on, on, on, on, on, on,
on, on, on, on, on, on, TOO, LOC, LOR, on, on, on)
: hourval( on, on, on, on, on, on, on, on, on, on, on, on,
on, on, on, on, TOOLOR, TOOLOR, LOC, LOR, LOR, LOR, on, on)
Note also that wsTSetpoint can be also be modified hourly to achieve load-shifting effects.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
See Table above | ON | No | hourly |
wsTargetSOC=float
When (and only when) wsDRMethod=STATEOFCHARGE, wsTargetSOC specifies the target fraction of maximum tank heat content. The tank is deemed fully charged when its entire contents is at wsTSetpoint and 0 charged at 110 oF. Schedules are used to indicate anticipated heat requirements. The STATEOFCHARGE method can be used in combined heat / DHW systems (see RSYS rsType=COMBINEDHEATDHW) when there is excess capacity during summer months, as shown in the following:
wsTargetSOC = select(
$month > 11 || $month < 3,
hourval(.70,.70,.70,.70,.70,.70,.70,.30,.95,.95,.95,.95,
.95,.95,.95,.95,.95,.70,.70,.70,.70,.70,.70,.70),
$month==3 || $month== 4,
hourval(.50,.50,.50,.50,.50,.50,.50,.30,.95,.95,.95,.95,
.95,.95,.95,.95,.95,.50,.50,.50,.50,.50,.50,.50),
default
hourval(.15,.15,.15,.15,.15,.15,.15,.15,.15,.15,.15,.15,
.15,.60,.60,.60,.15,.15,.15,.15,.15,.15,.15,.15))
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\lt\) x \(\le\) 1 | 0.9 | No | hourly |
wsSDLM=float
Specifies the standard distribution loss multiplier. See App B Eqn 4. To duplicate CEC 2019 methods, this value should be set according to the value derived with App B Eqn 5.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(>\) 0 | 1 | No | constant |
wsDSM=float
Distribution system multiplier. See RACM App B Eqn 4. To duplicate CEC 2016 methods, wsDSM should be set to the appropriate value from App B Table B-2. Note the NCF (non-compliance factor) included in App B Eqn 4 is not a CSE input and thus must be applied externally to wsDSM.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(>\) 0 | 1 | No | constant |
wsWF=float
Waste factor. See RACM App B Eqn 1. wsWF is applied to hot water draws. The default value (1) reflects the inclusion of waste in draw amounts. App B specifies wsWF=0.9 when the system has a within-unit pumped loop that reduces waste due to immediate availability of hot water at fixtures.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | hourly |
wsSSF=float
NOTE: Deprecated. Use wsSolarSys instead.
Specifies the solar savings fraction, allowing recognition of externally-calculated solar water heating energy contributions. The contributions are modeled by deriving an increased water heater feed temperature –
\[tWHFeed = tInletAdj + wsSSF*(wsTUse-tInletAdj)\]
where tInletAdj is the source cold water temperature including any DHWHEATREC tempering (that is, wsTInlet + heat recovery temperature increase, if any). This model approximates the diminishing returns associated with combined preheat strategies such as drain water heat recovery and solar.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 0.99 | No | hourly |
wsSolarSys=dhwSolarSys
Name of DHWSOLARSYS object, if any, that supplies pre-heated water to this DHWSYS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a DHWSOLARSYS | not recorded | No | constant |
wsParElec=float
Specifies electrical parasitic power to represent recirculation pumps or other system-level electrical devices. Calculated energy use is accumulated to the METER specified by wsElecMtr (end use DHW). No other effect, such as heat gain to surroundings, is modeled.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 0 | No | hourly |
wsDrawMaxDur=integer
Maximum draw duration for the sizing window.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Hr | x \(\geq\) 0 | 4 | No | constant |
wsLoadMaxDur=integer
Maximum load duration for the sizing window.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Hr | x \(\geq\) 0 | 12 | No | constant |
wsElecMtr=mtrName
Name of METER object, if any, to which DHWSYS electrical energy use is recorded (under end use DHW). In addition, wsElecMtr provides the default whElectMtr selection for all DHWHEATERs and DHWPUMPs in this DHWSYS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
wsFuelMtr =mtrName
Name of METER object, if any, to which DHWSYS fuel energy use is recorded (under end use DHW). DHWSYS fuel use is usually (always?) 0, so the primary use of this input is to specify the default whFuelMtr choice for DHWHEATERs in this DHWSYS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
wsWHhwMtr=dhwmtrName
Name of DHWMETER object, if any, to which hot water quantities (at water heater) are recorded by hot water end use.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | not recorded | No | constant |
wsFXhwMtr =dhwmtrName
Name of DHWMETER object, if any, to which mixed hot water use (at fixture) quantities are recorded by hot water end use. DHWDAYUSE and wsUse input can be verified using DHWMETER results.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | No | constant |
wsWriteDrawCSV=choice
If Yes, a comma-separated file is generated containing 1-minute interval hot water draw values for testing or linkage purposes.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Yes or No | No | No | constant |
endDHWSys
Optionally indicates the end of the DHWSYS definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
Related Probes:
4.33 DHWHEATER
DHWHEATER constructs an object representing a domestic hot water heater (or several if identical).
whName
Optional name of water heater; give after the word “DHWHEATER” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
whMult=integer
Number of identical water heaters of this type. Any value \(>1\) is equivalent to repeated entry of the same DHWHEATER.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
whType=choice
Type of water heater. This categorization is based on CEC and federal rating standards that change from time to time.
SMALLSTORAGE | A storage water heater having an energy factor (EF) rating. Generally, a gas-fired storage water heater with input of 75,000 Btuh or less, an oil-fired storage water heater with input of 105,000 Btuh or less, an electric storage water heater with input of 12 kW or less, or a heat pump water heater rated at 24 amps or less. |
LARGESTORAGE | Any storage water heater that is not SMALLSTORAGE. |
SMALLINSTANTANEOUS | A water heater that has an input rating of at least 4,000 Btuh per gallon of stored water. Small instantaneous water heaters include: gas instantaneous water heaters with an input of 200,000 Btu per hour or less, oil instantaneous water heaters with an input of 210,000 Btu per hour or less, and electric instantaneous water heaters with an input of 12 kW or less. |
LARGEINSTANTANEOUS | An instantaneous water heater that does not conform to the definition of SMALLINSTANTANEOUS, an indirect fuel-fired water heater, or a hot water supply boiler. |
INSTANTANEOUSUEF | An instantaneous water heater having a UEF rating (as opposed to EF). |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | SMALLSTORAGE | No | constant |
whHeatSrc=choice
Heat source for water heater. CSE implements uses efficiency-based models for all whTypes (as documented in RACM, App. B). In addition, the detailed Ecotope HPWH model is available for electric (air source heat pump and resistance) SMALLSTORAGE water heaters.
RESISTANCE | Electric resistance heating element Deprecated for whType=SMALLSTORAGE (use RESISTANCEX) |
RESISTANCEX | Electric resistance heating element, detailed HPWH model |
ASHP | Air source heat pump, EF model Deprecated for whType=SMALLSTORAGE (use ASHPX) |
ASHPX | Air source heat pump, detailed HPWH model |
FUEL | Fuel-fired burner |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | FUEL | No | constant |
whResType=choice
Resistance heater type, valid only if whHeatSrc is equal to RESISTANCEX, else ignored. These choices are supported by the detailed HPWH model. Except for Generic, all heater characteristics are set by HPWH based on whResType.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Typical SwingTank | Typical | No | constant |
whHeatingCap=float
Nominal heating capacity, available only for a limited HPWH types.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(>\) 0 | 0 | No | constant |
whVol=float
Storage tank volume. Must be omitted or 0 for instantaneous whTypes. Used by HPWH model (whHeatSrc=RESISTANCEX or whHeatSrc=ASHPX). Required when whHeatSrc=RESISTANCEX or whHeatSrc=ASHPX with whASHPType=GENERIC. For all other configurations, whVol is documentation-only.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | \(\ge\) 0.1 (caution: small values may cause runtime errors) | per whASHPType if HPWH else 50 | For some HPWH configurations, see above | constant |
whVolRunning=float
Running storage volume is the volume above aquastat. Requires the total volume based on aquastat position. Ecotope’s HPWH tank and heater.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | x \(>\) 0 | 0 | No | constant |
whEF=float
Rated energy factor that specifies DHWHEATER efficiency under test conditions. Used by CSE to derive annual water heating efficiency and/or other characteristics as described below. Calculation methods are documented in RACM, Appendix B.
Configuration | whEF default | Use |
---|---|---|
whType=SMALLSTORAGE, whHeatSrc=RESISTANCE or FUEL | 0.82 | Derivation of whLDEF |
whType=SMALLSTORAGE, whHeatSrc=ASHP | 0.82 | Derivation of whLDEFnote inappropriate default (deprecated, use ASHPX) |
whType=SMALLSTORAGE, whHeatSrc=ASHPX, whASHPType=GENERIC | (req’d) | Tank losses Overall efficiency |
whType=SMALLSTORAGE, whHeatSrc=RESISTANCEX | (req’d) | Tank losses Note: maximum whEF=0.98. |
whType=SMALLINSTANTANEOUS, whHeatSrc=RESISTANCE or FUEL | 0.82 | Annual efficiency = whEF*0.92 |
Any other | (unused) |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(>\) 0 Caution: maximum not checked. Unrealistic values will cause runtime errors and/or invalid results | See above | See above | constant |
whLDEF=float
Load-dependent energy factor for DHWHEATERs with whType=SMALLSTORAGE and whHeatSrc=FUEL or whHeatSrc=RESISTANCE. If not given, whLDEF is derived using a preliminary simulation activated via DHWSYS wsCalcMode=PRERUN. See RACM Appendix B.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | Calculated via DHWSYS PreRun mechanism | When whType = SMALLSTORAGE and PreRun not used | constant |
whUEF=float
Water heater Uniform Energy Factor efficiency rating, used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whAnnualElec=float
Annual electricity use assumed in UEF rating derivation. Used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
kWh | x \(\ge\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whAnnualFuel=float
Annual fuel use assumd in UEF rating derivation, used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
therms | x \(\ge\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whRatedFlow=float
Maximum flow rate assumed in UEF rating derivation. Used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gpm | x \(>\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whStbyElec=float
Instantaneous water heater standby power (electricity consumed when heater is not operating). Used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 4 | No | constant |
whLoadCFwdF=float
Instanteous water heater load carry forward factor – approximate number of hours the heater is allowed to meet water heating demand that is unmet on a 1 minute basis, used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
whZone=znName
Name of zone where water heater is located, used only in detailed HPWH models (whHeatSrc=ASHPX or whHeatSrc=RESISTANCEX), otherwise no effect. Zone conditions are used for tank heat loss calculations. Heat losses from the DHWHEATER are included in the zone heat balance. whZone also provides the default for whASHPSrcZn (see below).
whZone and whTEx cannot both be specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | Not in a zone (heat losses discarded) | No | constant |
whTEx=float
Water heater surround temperature, used only in detailed HPWH models (whHeatSrc=ASHPX or whHeatSrc=RESISTANCEX), otherwise no effect. When whTEx is specified, tank heat losses are calculated using whTEx and modify tank water temperatures, but the lost heat has no external effect.
whZone and whTEx cannot both be specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | whZone air temperature if specified, else 70 oF | No | hourly |
whASHPType=choice
Air source heat pump type, valid only if whHeatSrc=ASHPX. These choices are supported by the detailed HPWH model. Except for Generic, all heater characteristics are set by HPWH based on whASHPType.
Choice | Specified type |
---|---|
Generic | General generic (parameterized by wh_EF and wh_vol) |
AOSmithPHPT60 | 60 gallon Voltex |
AOSmithPHPT80 | 80 gallon Voltex |
AOSmithHPTU50 | 50 gallon AOSmith HPTU |
AOSmithHPTU66 | 66 gallon AOSmith HPTU |
AOSmithHPTU80 | 80 gallon AOSmith HPTU |
AOSmithHPTU80DR | 80 gallon AOSmith HPTU (demand reduction variant) |
AOSmithCAHP120 | 120 gallon AOSmith |
Sanden40 | Sanden 40 gallon CO2 external heat pump |
Sanden80 | Sanden 80 gallon CO2 external heat pump |
Sanden120 | Sanden 120 gallon CO2 external heat pump |
SandenGS3 | Sanden GS3 compressor CO2 external |
GE2012 | 2012 era GeoSpring |
GE2014 | 2014 80 gal GE model run in the efficiency mode |
GE2014_80DR | 2014 80 gal GE model run in the efficiency mode (demand reduction variant) |
GE2014StdMode | 2014 50 gal GE run in standard mode |
GE2014StdMode80 | 2014 80 gal GE run in standard mode |
RheemHB50 | newish Rheem (2014 model?) |
RheemHBDR2250 | 50 gallon, 2250 W resistance Rheem HB Duct Ready |
RheemHBDR4550 | 50 gallon, 4500 W resistance Rheem HB Duct Ready |
RheemHBDR2265 | 65 gallon, 2250 W resistance Rheem HB Duct Ready |
RheemHBDR4565 | 65 gallon, 4500 W resistance Rheem HB Duct Ready |
RheemHBDR2280 | 80 gallon, 2250 W resistance Rheem HB Duct Ready |
RheemHBDR4580 | 80 gallon, 4500 W resistance Rheem HB Duct Ready |
Rheem2020Prem40 | 40 gallon, Rheem 2020 Premium |
Rheem2020Prem50 | 50 gallon, Rheem 2020 Premium |
Rheem2020Prem65 | 65 gallon, Rheem 2020 Premium |
Rheem2020Prem80 | 80 gallon, Rheem 2020 Premium |
Rheem2020Build40 | 40 gallon, Rheem 2020 Builder |
Rheem2020Build50 | 50 gallon, Rheem 2020 Builder |
Rheem2020Build65 | 65 gallon, Rheem 2020 Builder |
Rheem2020Build80 | 80 gallon, Rheem 2020 Builder |
RheemPlugInShared40 | 40 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInShared50 | 50 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInShared65 | 65 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInShared80 | 80 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInDedicated40 | 40 gal Rheem plug-in 120V dedicated circuit (no resistance elements) |
RheemPlugInDedicated50 | 50 gal Rheem plug-in 120V dedicated circuit (no resistance elements) |
Stiebel220E | Stiebel Eltron (2014 model?) |
AOSmithSHPT50 | AOSmith add’l models (added 3-24-2017) |
AOSmithSHPT66 | AOSmith add’l models (added 3-24-2017) |
AOSmithSHPT80 | AOSmith add’l models (added 3-24-2017) |
GenericTier1 | Generic Tier 1 |
GenericTier2 | Generic Tier 2 |
GenericTier3 | Generic Tier 3 |
Generic | General generic (parameterized by EF and vol) |
UEF2Generic | Experimental UEF=2 |
WorstCaseMedium | UEF2Generic alias (supports pre-existing test cases) |
BasicIntegrated | Typical integrated HPWH |
ResTank | Resistance heater (no compressor). Superceded by whHeatSrc=RESITANCEX |
ResTankNoUA | Resistance heater (no compressor) with no tank losses. Superseded by whHeatSrc=RESISTANCEX. |
AOSmithHPTU80DR | 80 gallon AOSmith HPTU with fixed backup setpoint (experimental for demand response testing) |
AOSmithSHPT50 | 50 gal AOSmith SHPT |
AOSmithSHPT66 | 66 gal AOSmith SHPT |
AOSmithSHPT80 | 80 gal AOSmith SHPT |
AOSmithHPTS40 | 40 gal AOSmith HPTS |
AOSmithHPTS50 | 50 gal AOSmith HPTS |
AOSmithHPTS66 | 66 gal AOSmith HPTS |
AOSmithHPTS80 | 80 gal AOSmith HPTS |
ColmacCxV5_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA10_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA15_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA20_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA25_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA30_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxV5_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA10_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA15_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA20_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA25_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA30_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
NyleC25A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC60A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC90A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC125A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC185A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC250A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC60A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC90A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC125A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC185A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC250A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC60A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC90A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC125A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC185A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC250A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC60A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC90A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC125A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC185A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC250A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
Rheem_HPHD60HNU_MP | Rheem HPHD60 MP external MP HPWHs |
Rheem_HPHD60VNU_MP | Rheem HPHD60 MP external MP HPWHs |
Rheem_HPHD135HNU_MP | Rheem HPHD135 MP external MP HPWHs |
Rheem_HPHD135VNU_MP | Rheem HPHD135 MP external MP HPWHs |
Scalable_SP | single pass scalable type for autosized standard design |
Scalable_MP | multipass scalable type for autosized standard design |
AquaThermAire | Villara AquaThermAire HPWH |
GenericUEF217 | 65-gal tank meeting Federal standard minimum requirement |
AWHSTier4Generic40 | Any 40-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
AWHSTier4Generic50 | Any 50-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
AWHSTier4Generic65 | Any 65-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
AWHSTier4Generic80 | Any 80-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
BradfordWhiteAeroThermRE2H50 | Bradford White 50-gal AeroTherm2023 |
BradfordWhiteAeroThermRE2H65 | Bradford White 65-gal AeroTherm2023 |
BradfordWhiteAeroThermRE2H80 | Bradford White 80-gal AeroTherm2023 |
LG_APHWC50 | LG 50-gal integrated HPWH |
LG_APHWC80 | LG 580-gal integrated HPWH |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | none | When whHeatSrc=ASHPX | constant |
whASHPSrcZn=znName
Name of zone that serves as heat pump heat source used when whHeatSrc=ASHPX. Heat removed from the zone is added to the heated water and is included in zone heat balance (that is, heat pump operation cools the zone).
whASHPSrcZn and whASHPSrcT cannot both be specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | whZoneIf no zone is specified by input or default, heat extracted by ASHP has no effect. | No | constant |
whASHPSrcT=float
Heat pump source air temperature used when whHeatSrc=ASHPX. Heat removed from this source is added to the heated water but has no other effect.
whASHPSrcZn and whASHPSrcT cannot both be specified.
The logic to determine the temperature of the heat pump source air is:
if whASHPSrcT is specified
use whASHPSrcT
else if whASHPSRCZn is specified
use whASHPSrcZn air temp
else if whZone is specified
use whZone air temp
else
use 70 F
To model a heat pump that uses outdoor air as its heat source, omit whASHPSrcZn and specify whASHPSrcT = $tDbO.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | 70 oF (used only when whASHPSrcZn and whZone not specified) | No | hourly |
whASHPResUse=float
Specifies activation temperature difference for resistance heating, used only when whHeatSrc=ASHPX and whASHPType=GENERIC. Refer to HPWH engineering documentation for model details.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oC | x \(\ge\) 0 | 7.22 | No | constant |
whResHtPwr=float
Specifies resistance upper element power, used only with whHeatSrc=RESISTANCEX.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 4500 | No | constant |
whResHtPwr2=float
Specifies resistance lower element power, used only with whHeatSrc=RESISTANCEX.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | whResHtPwr | No | constant |
whUA=float
HPWH-type total UA (not per tank)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/F | x \(\geq\) 0 | HPWH default | No | constant |
whInsulR=float
Tank insulation resistance for heat pump water heater.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
hr-F/Btuh | x \(>\) 0 | -1 | No | constant |
whInHtSupply=float
whInHtLoopRet=float
Fractional tank height of inlets for supply water and DHWLOOP return, used only with HPWH types (whHeatSrc=RESISTANCEX or whHeatSrc=ASHPX). 0 indicates the bottom of the water heater tank and 1 specifies the top. Inlet height influences tank layer mixing and can impact heat pump COP and/or heating activation frequency.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | HPWH default (0?) | No | constant |
whtankCount=float
Number of storage tanks per DHWHEATER, re built-up whType=Builtup, does not reflect wh_mult (wh_mult=2, wh_tankCount=3 -> 6 tanks).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
# | x \(\geq\) 1 | 1 | No | constant |
whEff=float
Water heating efficiency, used in modeling whType=LARGESTORAGE and whType=LARGEINSTANTANEOUS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) whEff \(\leq\) 1 | .82 | No | constant |
whSBL=float
Standby loss, used in modeling whType=LARGESTORAGE.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\ge\) 0 | 0 | No | constant |
whPilotPwr=float
Pilot light consumption, included in fuel energy use of DHWHEATERs with whHeatSrc=FUEL.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\ge\) 0 | 0 | No | hourly |
whParElec=float
Parasitic electricity power, included in electrical energy use of all DHWHEATERs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 0 | No | hourly |
whFAdjElec=float
whFAdjFuel=float
Water heater energy use modifiers. Multiplies calculated use of electricity (whFAdjElec) and fuel (whFAdjFuel). All components of energy use – primary, backup, XBU (extra backup), and other auxiliary – are modified before they are accumulated to whElecMtr and whFuelMtr.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(\ge\) 0 | 1 | No | subhourly |
whElecMtr=mtrName
Name of METER object, if any, by which DHWHEATER electrical energy use is recorded (under end use DHW).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | Parent DHWSYS wsElecMtr | No | constant |
whxBUEndUse=choice
Specifies the whElecMtr end use, if any, to which extra backup energy is accumulated. In some water heater types, extra backup energy is modeled to maintain output temperature at wsTUse. By default, extra backup energy is included in end use dhwBU. whxBUEndUse allows specification of an alternative end use to which extra backup energy is accumulated.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
end use code | (extra backup accums to dhwBU) | No | constant |
whFuelMtr =mtrName
Name of METER object, if any, by which DHWHEATER fuel energy use is recorded (under end use DHW).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | Parent DHWSYS wsFuelMtr | No | constant |
whTankTInit =comma-separated list of 12 floats
A list of 12 initial values for HPWH tank model layer temperatures, in bottom-to-top order. If given, these values are used to initialize tank layer temperatures at the beginning of the warmup period. Initialization is not repeated at the beginning of the main simulation.
whTankTInit is allowed only for HPWH-based types (whHeatSrc=ASHPX or whHeatSrc=ResistanceX).
whTankTInit is intended for use in empirical validation studies where the initial tank state needs to match measured data. whTankTInit should not be generally used. In the absence of whTankTInit, layer temperatures are initialized to the water heater setpoint inherited from the parent DHWSYS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\gt\) 0 | No | constant |
endDHWHEATER
Optionally indicates the end of the DHWHEATER definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | none | No |
Related Probes:
4.34 DHWLOOPHEATER
DHWHEATERLOOP constructs an object representing a hot water heater dedicated to heating DHWLOOP return water (or several if identical).
whName
Optional name of water heater; give after the word “DHWHEATER” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
whMult=integer
Number of identical water heaters of this type. Any value \(>1\) is equivalent to repeated entry of the same DHWHEATER.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
whType=choice
Type of water heater. This categorization is based on CEC and federal rating standards that change from time to time.
SMALLSTORAGE | A storage water heater having an energy factor (EF) rating. Generally, a gas-fired storage water heater with input of 75,000 Btuh or less, an oil-fired storage water heater with input of 105,000 Btuh or less, an electric storage water heater with input of 12 kW or less, or a heat pump water heater rated at 24 amps or less. |
LARGESTORAGE | Any storage water heater that is not SMALLSTORAGE. |
SMALLINSTANTANEOUS | A water heater that has an input rating of at least 4,000 Btuh per gallon of stored water. Small instantaneous water heaters include: gas instantaneous water heaters with an input of 200,000 Btu per hour or less, oil instantaneous water heaters with an input of 210,000 Btu per hour or less, and electric instantaneous water heaters with an input of 12 kW or less. |
LARGEINSTANTANEOUS | An instantaneous water heater that does not conform to the definition of SMALLINSTANTANEOUS, an indirect fuel-fired water heater, or a hot water supply boiler. |
INSTANTANEOUSUEF | An instantaneous water heater having a UEF rating (as opposed to EF). |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | SMALLSTORAGE | No | constant |
whHeatSrc=choice
Heat source for water heater. CSE implements uses efficiency-based models for all whTypes (as documented in RACM, App. B). In addition, the detailed Ecotope HPWH model is available for electric (air source heat pump and resistance) SMALLSTORAGE water heaters.
RESISTANCE | Electric resistance heating element Deprecated for whType=SMALLSTORAGE (use RESISTANCEX) |
RESISTANCEX | Electric resistance heating element, detailed HPWH model |
ASHP | Air source heat pump, EF model Deprecated for whType=SMALLSTORAGE (use ASHPX) |
ASHPX | Air source heat pump, detailed HPWH model |
FUEL | Fuel-fired burner |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | FUEL | No | constant |
whResType=choice
Resistance heater type, valid only if whHeatSrc is equal to RESISTANCEX, else ignored. These choices are supported by the detailed HPWH model. Except for Generic, all heater characteristics are set by HPWH based on whResType.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Typical SwingTank | Typical | No | constant |
whHeatingCap=float
Nominal heating capacity, available only for a limited HPWH types.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(>\) 0 | 0 | No | constant |
whVol=float
Storage tank volume. Must be omitted or 0 for instantaneous whTypes. Used by HPWH model (whHeatSrc=RESISTANCEX or whHeatSrc=ASHPX). Required when whHeatSrc=RESISTANCEX or whHeatSrc=ASHPX with whASHPType=GENERIC. For all other configurations, whVol is documentation-only.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | \(\ge\) 0.1 (caution: small values may cause runtime errors) | per whASHPType if HPWH else 50 | For some HPWH configurations, see above | constant |
whVolRunning=float
Running storage volume is the volume above aquastat. Requires the total volume based on aquastat position. Ecotope’s HPWH tank and heater.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | x \(>\) 0 | 0 | No | constant |
whEF=float
Rated energy factor that specifies DHWHEATER efficiency under test conditions. Used by CSE to derive annual water heating efficiency and/or other characteristics as described below. Calculation methods are documented in RACM, Appendix B.
Configuration | whEF default | Use |
---|---|---|
whType=SMALLSTORAGE, whHeatSrc=RESISTANCE or FUEL | 0.82 | Derivation of whLDEF |
whType=SMALLSTORAGE, whHeatSrc=ASHP | 0.82 | Derivation of whLDEFnote inappropriate default (deprecated, use ASHPX) |
whType=SMALLSTORAGE, whHeatSrc=ASHPX, whASHPType=GENERIC | (req’d) | Tank losses Overall efficiency |
whType=SMALLSTORAGE, whHeatSrc=RESISTANCEX | (req’d) | Tank losses Note: maximum whEF=0.98. |
whType=SMALLINSTANTANEOUS, whHeatSrc=RESISTANCE or FUEL | 0.82 | Annual efficiency = whEF*0.92 |
Any other | (unused) |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(>\) 0 Caution: maximum not checked. Unrealistic values will cause runtime errors and/or invalid results | See above | See above | constant |
whLDEF=float
Load-dependent energy factor for DHWHEATERs with whType=SMALLSTORAGE and whHeatSrc=FUEL or whHeatSrc=RESISTANCE. If not given, whLDEF is derived using a preliminary simulation activated via DHWSYS wsCalcMode=PRERUN. See RACM Appendix B.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | Calculated via DHWSYS PreRun mechanism | When whType = SMALLSTORAGE and PreRun not used | constant |
whUEF=float
Water heater Uniform Energy Factor efficiency rating, used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whAnnualElec=float
Annual electricity use assumed in UEF rating derivation. Used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
kWh | x \(\ge\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whAnnualFuel=float
Annual fuel use assumd in UEF rating derivation, used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
therms | x \(\ge\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whRatedFlow=float
Maximum flow rate assumed in UEF rating derivation. Used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gpm | x \(>\) 0 | none | when whType= INSTANTANEOUSUEF | constant |
whStbyElec=float
Instantaneous water heater standby power (electricity consumed when heater is not operating). Used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 4 | No | constant |
whLoadCFwdF=float
Instanteous water heater load carry forward factor – approximate number of hours the heater is allowed to meet water heating demand that is unmet on a 1 minute basis, used when whType=INSTANTANEOUSUEF.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
whZone=znName
Name of zone where water heater is located, used only in detailed HPWH models (whHeatSrc=ASHPX or whHeatSrc=RESISTANCEX), otherwise no effect. Zone conditions are used for tank heat loss calculations. Heat losses from the DHWHEATER are included in the zone heat balance. whZone also provides the default for whASHPSrcZn (see below).
whZone and whTEx cannot both be specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | Not in a zone (heat losses discarded) | No | constant |
whTEx=float
Water heater surround temperature, used only in detailed HPWH models (whHeatSrc=ASHPX or whHeatSrc=RESISTANCEX), otherwise no effect. When whTEx is specified, tank heat losses are calculated using whTEx and modify tank water temperatures, but the lost heat has no external effect.
whZone and whTEx cannot both be specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | whZone air temperature if specified, else 70 oF | No | hourly |
whASHPType=choice
Air source heat pump type, valid only if whHeatSrc=ASHPX. These choices are supported by the detailed HPWH model. Except for Generic, all heater characteristics are set by HPWH based on whASHPType.
Choice | Specified type |
---|---|
Generic | General generic (parameterized by wh_EF and wh_vol) |
AOSmithPHPT60 | 60 gallon Voltex |
AOSmithPHPT80 | 80 gallon Voltex |
AOSmithHPTU50 | 50 gallon AOSmith HPTU |
AOSmithHPTU66 | 66 gallon AOSmith HPTU |
AOSmithHPTU80 | 80 gallon AOSmith HPTU |
AOSmithHPTU80DR | 80 gallon AOSmith HPTU (demand reduction variant) |
AOSmithCAHP120 | 120 gallon AOSmith |
Sanden40 | Sanden 40 gallon CO2 external heat pump |
Sanden80 | Sanden 80 gallon CO2 external heat pump |
Sanden120 | Sanden 120 gallon CO2 external heat pump |
SandenGS3 | Sanden GS3 compressor CO2 external |
GE2012 | 2012 era GeoSpring |
GE2014 | 2014 80 gal GE model run in the efficiency mode |
GE2014_80DR | 2014 80 gal GE model run in the efficiency mode (demand reduction variant) |
GE2014StdMode | 2014 50 gal GE run in standard mode |
GE2014StdMode80 | 2014 80 gal GE run in standard mode |
RheemHB50 | newish Rheem (2014 model?) |
RheemHBDR2250 | 50 gallon, 2250 W resistance Rheem HB Duct Ready |
RheemHBDR4550 | 50 gallon, 4500 W resistance Rheem HB Duct Ready |
RheemHBDR2265 | 65 gallon, 2250 W resistance Rheem HB Duct Ready |
RheemHBDR4565 | 65 gallon, 4500 W resistance Rheem HB Duct Ready |
RheemHBDR2280 | 80 gallon, 2250 W resistance Rheem HB Duct Ready |
RheemHBDR4580 | 80 gallon, 4500 W resistance Rheem HB Duct Ready |
Rheem2020Prem40 | 40 gallon, Rheem 2020 Premium |
Rheem2020Prem50 | 50 gallon, Rheem 2020 Premium |
Rheem2020Prem65 | 65 gallon, Rheem 2020 Premium |
Rheem2020Prem80 | 80 gallon, Rheem 2020 Premium |
Rheem2020Build40 | 40 gallon, Rheem 2020 Builder |
Rheem2020Build50 | 50 gallon, Rheem 2020 Builder |
Rheem2020Build65 | 65 gallon, Rheem 2020 Builder |
Rheem2020Build80 | 80 gallon, Rheem 2020 Builder |
RheemPlugInShared40 | 40 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInShared50 | 50 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInShared65 | 65 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInShared80 | 80 gal Rheem plug-in 120V shared circuit (no resistance elements) |
RheemPlugInDedicated40 | 40 gal Rheem plug-in 120V dedicated circuit (no resistance elements) |
RheemPlugInDedicated50 | 50 gal Rheem plug-in 120V dedicated circuit (no resistance elements) |
Stiebel220E | Stiebel Eltron (2014 model?) |
AOSmithSHPT50 | AOSmith add’l models (added 3-24-2017) |
AOSmithSHPT66 | AOSmith add’l models (added 3-24-2017) |
AOSmithSHPT80 | AOSmith add’l models (added 3-24-2017) |
GenericTier1 | Generic Tier 1 |
GenericTier2 | Generic Tier 2 |
GenericTier3 | Generic Tier 3 |
Generic | General generic (parameterized by EF and vol) |
UEF2Generic | Experimental UEF=2 |
WorstCaseMedium | UEF2Generic alias (supports pre-existing test cases) |
BasicIntegrated | Typical integrated HPWH |
ResTank | Resistance heater (no compressor). Superceded by whHeatSrc=RESITANCEX |
ResTankNoUA | Resistance heater (no compressor) with no tank losses. Superseded by whHeatSrc=RESISTANCEX. |
AOSmithHPTU80DR | 80 gallon AOSmith HPTU with fixed backup setpoint (experimental for demand response testing) |
AOSmithSHPT50 | 50 gal AOSmith SHPT |
AOSmithSHPT66 | 66 gal AOSmith SHPT |
AOSmithSHPT80 | 80 gal AOSmith SHPT |
AOSmithHPTS40 | 40 gal AOSmith HPTS |
AOSmithHPTS50 | 50 gal AOSmith HPTS |
AOSmithHPTS66 | 66 gal AOSmith HPTS |
AOSmithHPTS80 | 80 gal AOSmith HPTS |
ColmacCxV5_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA10_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA15_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA20_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA25_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxA30_SP | Colmac CxA-xx modular external HPWHs (single pass mode) |
ColmacCxV5_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA10_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA15_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA20_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA25_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
ColmacCxA30_MP | Colmac CxA-xx modular external HPWHs (multi-pass mode) |
NyleC25A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC60A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC90A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC125A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC185A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC250A_SP | Nyle Cxx external HPWHs (SP = single pass mode) |
NyleC60A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC90A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC125A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC185A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC250A_CWP_SP | Nyle Cxx external SP HPWHs with cold weather package |
NyleC60A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC90A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC125A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC185A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC250A_MP | Nyle Cxx external HPWHs (MP = multi-pass mode) |
NyleC60A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC90A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC125A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC185A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
NyleC250A_CWP_MP | Nyle Cxx external MP HPWHs w/ cold weather package |
Rheem_HPHD60HNU_MP | Rheem HPHD60 MP external MP HPWHs |
Rheem_HPHD60VNU_MP | Rheem HPHD60 MP external MP HPWHs |
Rheem_HPHD135HNU_MP | Rheem HPHD135 MP external MP HPWHs |
Rheem_HPHD135VNU_MP | Rheem HPHD135 MP external MP HPWHs |
Scalable_SP | single pass scalable type for autosized standard design |
Scalable_MP | multipass scalable type for autosized standard design |
AquaThermAire | Villara AquaThermAire HPWH |
GenericUEF217 | 65-gal tank meeting Federal standard minimum requirement |
AWHSTier4Generic40 | Any 40-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
AWHSTier4Generic50 | Any 50-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
AWHSTier4Generic65 | Any 65-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
AWHSTier4Generic80 | Any 80-gal tank meeting Advanced Water Heating Specification Tier-4 minimum requirements |
BradfordWhiteAeroThermRE2H50 | Bradford White 50-gal AeroTherm2023 |
BradfordWhiteAeroThermRE2H65 | Bradford White 65-gal AeroTherm2023 |
BradfordWhiteAeroThermRE2H80 | Bradford White 80-gal AeroTherm2023 |
LG_APHWC50 | LG 50-gal integrated HPWH |
LG_APHWC80 | LG 580-gal integrated HPWH |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | none | When whHeatSrc=ASHPX | constant |
whASHPSrcZn=znName
Name of zone that serves as heat pump heat source used when whHeatSrc=ASHPX. Heat removed from the zone is added to the heated water and is included in zone heat balance (that is, heat pump operation cools the zone).
whASHPSrcZn and whASHPSrcT cannot both be specified.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a ZONE | whZoneIf no zone is specified by input or default, heat extracted by ASHP has no effect. | No | constant |
whASHPSrcT=float
Heat pump source air temperature used when whHeatSrc=ASHPX. Heat removed from this source is added to the heated water but has no other effect.
whASHPSrcZn and whASHPSrcT cannot both be specified.
The logic to determine the temperature of the heat pump source air is:
if whASHPSrcT is specified
use whASHPSrcT
else if whASHPSRCZn is specified
use whASHPSrcZn air temp
else if whZone is specified
use whZone air temp
else
use 70 F
To model a heat pump that uses outdoor air as its heat source, omit whASHPSrcZn and specify whASHPSrcT = $tDbO.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | 70 oF (used only when whASHPSrcZn and whZone not specified) | No | hourly |
whASHPResUse=float
Specifies activation temperature difference for resistance heating, used only when whHeatSrc=ASHPX and whASHPType=GENERIC. Refer to HPWH engineering documentation for model details.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oC | x \(\ge\) 0 | 7.22 | No | constant |
whResHtPwr=float
Specifies resistance upper element power, used only with whHeatSrc=RESISTANCEX.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 4500 | No | constant |
whResHtPwr2=float
Specifies resistance lower element power, used only with whHeatSrc=RESISTANCEX.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | whResHtPwr | No | constant |
whUA=float
HPWH-type total UA (not per tank)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/F | x \(\geq\) 0 | HPWH default | No | constant |
whInsulR=float
Tank insulation resistance for heat pump water heater.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
hr-F/Btuh | x \(>\) 0 | -1 | No | constant |
whInHtSupply=float
whInHtLoopRet=float
Fractional tank height of inlets for supply water and DHWLOOP return, used only with HPWH types (whHeatSrc=RESISTANCEX or whHeatSrc=ASHPX). 0 indicates the bottom of the water heater tank and 1 specifies the top. Inlet height influences tank layer mixing and can impact heat pump COP and/or heating activation frequency.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | HPWH default (0?) | No | constant |
whtankCount=float
Number of storage tanks per DHWHEATER, re built-up whType=Builtup, does not reflect wh_mult (wh_mult=2, wh_tankCount=3 -> 6 tanks).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
# | x \(\geq\) 1 | 1 | No | constant |
whEff=float
Water heating efficiency, used in modeling whType=LARGESTORAGE and whType=LARGEINSTANTANEOUS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) whEff \(\leq\) 1 | .82 | No | constant |
whSBL=float
Standby loss, used in modeling whType=LARGESTORAGE.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\ge\) 0 | 0 | No | constant |
whPilotPwr=float
Pilot light consumption, included in fuel energy use of DHWHEATERs with whHeatSrc=FUEL.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | x \(\ge\) 0 | 0 | No | hourly |
whParElec=float
Parasitic electricity power, included in electrical energy use of all DHWHEATERs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 0 | No | hourly |
whFAdjElec=float
whFAdjFuel=float
Water heater energy use modifiers. Multiplies calculated use of electricity (whFAdjElec) and fuel (whFAdjFuel). All components of energy use – primary, backup, XBU (extra backup), and other auxiliary – are modified before they are accumulated to whElecMtr and whFuelMtr.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(\ge\) 0 | 1 | No | subhourly |
whElecMtr=mtrName
Name of METER object, if any, by which DHWHEATER electrical energy use is recorded (under end use DHW).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | Parent DHWSYS wsElecMtr | No | constant |
whxBUEndUse=choice
Specifies the whElecMtr end use, if any, to which extra backup energy is accumulated. In some water heater types, extra backup energy is modeled to maintain output temperature at wsTUse. By default, extra backup energy is included in end use dhwBU. whxBUEndUse allows specification of an alternative end use to which extra backup energy is accumulated.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
end use code | (extra backup accums to dhwBU) | No | constant |
whFuelMtr =mtrName
Name of METER object, if any, by which DHWHEATER fuel energy use is recorded (under end use DHW).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | Parent DHWSYS wsFuelMtr | No | constant |
whTankTInit =comma-separated list of 12 floats
A list of 12 initial values for HPWH tank model layer temperatures, in bottom-to-top order. If given, these values are used to initialize tank layer temperatures at the beginning of the warmup period. Initialization is not repeated at the beginning of the main simulation.
whTankTInit is allowed only for HPWH-based types (whHeatSrc=ASHPX or whHeatSrc=ResistanceX).
whTankTInit is intended for use in empirical validation studies where the initial tank state needs to match measured data. whTankTInit should not be generally used. In the absence of whTankTInit, layer temperatures are initialized to the water heater setpoint inherited from the parent DHWSYS.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\gt\) 0 | No | constant |
endDHWHEATER
Optionally indicates the end of the DHWHEATER definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | none | No |
Related Probes:
4.35 DHWHEATREC
DHWHEATREC constructs an object representing one or more heat recovery devices in a DHWSYS. Drain water heat recovered by the device increases parent DHWSYS wsInlet temperature and/or fixture cold water feed temperature. This reduces water heating energy consumption.
wrName
Optional name of device; give after the word “DHWHEATREC” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wrMult=integer
Number of identical heat recovery devices of this type. Any value >1 is equivalent to repeated entry of the same DHWHEATREC.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
wrHWEndUse=choice
Hot water end use to which this DHWHEATREC is applied: one of Shower, Bath, CWashr, DWashr, or Faucet. Selects DHWUSE draws for heat recovery calculations. Currently, only Shower is supported.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Shower | Shower | No | constant |
wrCountFXDrain=integer
Number of fixtures (of type wrHWEndUse) whose drain lines pass through this heat recovery device. wrCountFXDrain=0 causes this DHWHEATREC to have no effect (that is, equivalent to omitting the DHWHEATREC command).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
wrCountFXCold=integer
Number of fixtures (of type wrHWEndUse) with cold water supply connected to the DHWHEATREC potable-side outlet and thus use tempered water to mix with hot water.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
wrFeedsWH=choice
Specifies whether the potable-side outlet of the DHWHEATREC is connected to the DHWHEATER(s) inlet.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Yes, No | No | No | constant |
wrType=choice
Specifies the type of heat recovery device: Vertical, Horizontal, or SetEF. Horizontal and Vertical derive effectiveness from wrCSARatedEF, flow rates, and water temperatures. As of Feb. 2019, the same correlation is used for both Horizontal and Vertical, so these choices have no effect on results. Choice SetEF uses wrCSARatedEF without modification as the effectiveness (note hourly variability).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Vertical, Horizontal, SetEF | Vertical | No | constant |
wrCSARatedEF=float
Specifies the heat recovery effectiveness, generally determined using CSA B55.2 rating conditions. This value is modified during simulation based on water flow rates and temperatures. If wrType=SetEF, wsCSARatedEF is used without modification.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | none | Yes | hourly |
wrTDInDiff=float
Temperature drop between the fixture drain and DHWHEATREC drain-side inlet. The drain-side inlet temperature is thus DHWUSE wuTemp - wrTDInDiff.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | 4.6 oF | No | hourly |
wrTDInWarmup=float
Drain-side inlet water temperature during warmup. During the warmup portion of a draw (if any), the drain-side inlet temperature will initially be lower than that based on DHWUSE wuTemp. wrTDInWarmup allows input of user estimates for this temperature. Note wrTDInWarmup is not adjusted by wrTDInDiff.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 65 oF | No | hourly |
endDHWHEATREC
Optionally indicates the end of the DHWHEATREC definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
Related Probes:
4.36 DHWTANK
DHWTANK constructs an object representing one or more unfired water storage tanks in a DHWSYS. DHWTANK heat losses contribute to the water heating load.
wtName
Optional name of tank; give after the word “DHWTANK” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wtMult=integer
Number of identical tanks of this type. Any value \(>1\) is equivalent to repeated entry of the same DHWTANK.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
Tank heat loss is calculated hourly (note that default heat loss is 0) –
\[\text{qLoss} = \text{wtMult} \cdot (\text{wtUA} \cdot (\text{wtTTank} - \text{wtTEx}) + \text{wtXLoss})\]
wtUA=float
Tank heat loss coefficient.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/oF | x \(\ge\) 0 | Derived from wtVol and wtInsulR | No | constant |
wtVol=float
Specifies tank volume.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | x \(\ge\) 0 | 0 | No | constant |
wtInsulR=float
Specifies total tank insulation resistance. The input value should represent the total resistance from the water to the surroundings, including both built-in insulation and additional exterior wrap insulation.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2-oF/Btuh | x \(\ge\) 0.01 | 0 | No | constant |
wtZone=znName
Zone location of DHWTANK regarding tank loss. The value of zero only valid if wtTEx is being used. Half of the heat losses go to zone air and the other goes to half radiant.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Name of ZONE | 0 | No | constant |
wtTEx=float
Tank surround temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\ge\) 0 | 70 | No | hourly |
wtTTank=float
Tank average water temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | \(>\) 32 oF | Parent DHWSYSTEM wsTUse | No | hourly |
wtXLoss=float
Additional tank heat loss. To duplicate CEC 2016 procedures, this value should be used to specify the fitting loss of 61.4 Btuh.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh | (any) | 0 | No | hourly |
endDHWTank
Optionally indicates the end of the DHWTANK definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.37 DHWPUMP
DHWPUMP constructs an object representing a domestic hot water circulation pump (or more than one if identical).
wpName
Optional name of pump; give after the word “DHWPUMP” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wpMult=integer
Number of identical pumps of this type. Any value \(>1\) is equivalent to repeated entry of the same DHWPUMP.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
wpPwr=float
Pump power.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(>\) 0 | 0 | No | hourly |
wpElecMtr=mtrName
Name of METER object, if any, to which DHWPUMP electrical energy use is recorded (under end use DHW).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | Parent DHWSYS wsElecMtr | No | constant |
endDHWPump
Optionally indicates the end of the DHWPUMP definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
Related Probes:
4.38 DHWLOOP
DHWLOOP constructs one or more objects representing a domestic hot water circulation loop. The actual pipe runs in the DHWLOOP are specified by any number of DHWLOOPSEGs (see below). Circulation pumps are specified by DHWLOOPPUMPs (also below).
wlName
Optional name of loop; give after the word “DHWLOOP” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wlMult=integer
Number of identical loops of this type. Any value \(>1\) is equivalent to repeated entry of the same DHWLOOP (and all child objects).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
wlFlow=float
Loop flow rate (when operating).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gpm | x \(\ge\) 0 | 6 | No | hourly |
wlTIn1=float
Inlet temperature of first DHWLOOPSEG.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | DHWSYS wsTUse | No | hourly |
wlRunF=float
Fraction of hour that loop circulation operates.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | hourly |
wlFUA=float
DHWLOOPSEG pipe heat loss adjustment factor. DHWLOOPSEG UA is derived (from wgSize, wgLength, wgInsulK, wgInsulThk, and wgExH) and multiplied by wlFUA. Note: does not apply to child DHWLOOPBRANCHs (see wbFUA).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
wlLossMakeupPwr=float
Specifies electrical power available to make up losses from DHWLOOPSEGs (loss from DHWLOOPBRANCHs is not included). Separate loss makeup is typically used in multi-unit HPWH systems to avoid inefficiencies associated with high condenser temperatures. Loss-makeup energy is calculated hourly and is the smaller of loop losses and wlLossMakeupPwr. The resulting electricity use (including the effect of wlLossMakeupEff) is accumulated to the METER specified by wlElecMtr (end use dhwMFL). No other effect, such as heat gain to surroundings, is modeled.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(\ge\) 0 | 0 | No | hourly |
wlLossMakeupEff=float
Specifies the efficiency of loss makeup heating if any. No effect when wlLossMakeupPwr is 0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | hourly |
wlElecMtr=mtrName
Name of METER object, if any, to which DHWLOOP electrical energy use is recorded (under end use dhwMFL).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | Parent DHWSYS wsElecMtr | No | constant |
endDHWLoop
Optionally indicates the end of the DHWLOOP definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
Related Probes:
4.39 DHWLOOPPUMP
DHWLOOPPUMP constructs an object representing a pump serving part a DHWLOOP. The model is identical to DHWPUMP except that that the electricity use calculation reflects wlRunF of the parent DHWLOOP.
wlpName
Optional name of pump; give after the word “DHWLOOPPUMP” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wlpMult=integer
Number of identical pumps of this type. Any value \(>1\) is equivalent to repeated entry of the same DHWPUMP.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
wlpPwr=float
Pump power.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
W | x \(>\) 0 | 0 | No | hourly |
wlpLiqHeatF=float
Fraction of pump power that heats circulating liquid. The remainder is discarded.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 1 | 1 | No | hourly |
wlpElecMtr=mtrName
Name of METER object, if any, to which DHWLOOPPUMP electrical energy use is recorded (under end use dhwMFL).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | Parent DHWLOOP wlElecMtr | No | constant |
endDHWLOOPPUMP
Optionally indicates the end of the DHWPUMP definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes:
4.40 DHWLOOPSEG
DHWLOOPSEG constructs one or more objects representing a segment of the preceeding DHWLOOP. A DHWLOOP can have any number of DHWLOOPSEGs to represent the segments of the loop with possibly differing sizes, insulation, or surrounding conditions.
wgName
Optional name of segment; give after the word “DHWLOOPSEG” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wgTy=choice
Specifies the type of segment. RETURN segments, if any, must follow SUPPLY segments.
SUPPLY | Indicates a supply segment (flow is sum of circulation and draw flow, child DHWLOOPBRANCHs permitted). |
RETURN | Indicates a return segment (flow is only due to circulation, child DHWLOOPBRANCHs not allowed) |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | Yes | constant |
wgLength=float
Length of segment.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | constant |
wgSize=float
Nominal size of pipe. CSE assumes the pipe outside diameter = size + 0.125 in.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
in | x \(>\) 0 | 1 | Yes | constant |
wgInsulK=float
Pipe insulation conductivity
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
Btuh-ft/ft2-oF | x \(>\) 0 | 0.02167 | No | constant |
wgInsulThk=float
Pipe insulation thickness
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
in | x \(\ge\) 0 | 1 | No | constant |
wgExH=float
Combined radiant/convective exterior surface conductance between insulation (or pipe if no insulation) and surround.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | 1.5 | No | hourly |
wgExT=float
Surrounding equivalent temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 70 | No | hourly |
wgFNoDraw=float
Fraction of hour when no draw occurs.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 70 | No | hourly |
endDHWLoopSeg
Optionally indicates the end of the DHWLOOPSEG definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
Related Probes:
4.41 DHWLOOPBRANCH
DHWLOOPBRANCH constructs one or more objects representing a branch pipe from the preceding DHWLOOPSEG. A DHWLOOPSEG can have any number of DHWLOOPBRANCHs to represent pipe runs with differing sizes, insulation, or surrounding conditions.
wbName
Optional name of segment; give after the word “DHWLOOPBRANCH” if desired.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
wbMult=float
Specifies the number of identical DHWLOOPBRANCHs. Note may be non-integer.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1 | No | constant |
wbLength=float
Length of branch.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\ge\) 0 | 0 | No | constant |
wbSize=float
Nominal size of pipe. CSE assumes the pipe outside diameter = size + 0.125 in.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
in | x \(>\) 0 | none | Yes | constant |
wbInsulK=float
Pipe insulation conductivity
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
Btuh-ft/ft2-oF | x \(>\) 0 | 0.02167 | No | constant |
wbInsulThk=float
Pipe insulation thickness
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
in | x \(\ge\) 0 | 1 | No | constant |
wbExH=float
Combined radiant/convective exterior surface conductance between insulation (or pipe if no insulation) and surround.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-oF | x \(>\) 0 | 1.5 | No | hourly |
wbExCnd=choice
Specify exterior conditions.
Choice | Description |
---|---|
ADIABATIC | Adiabatic on other side |
AMBIENT | Ambient exterior |
SPECT | Specify temperature |
ADJZN | Adjacent zone |
GROUND | Ground conditions |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
See table above | SPECT | No | constant |
wbAdjZn=float
Boundary conditions for adjacent zones.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.0 | No | runly |
wbExTX=float
External boundary conditions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 70.0 | No | runly |
wbFUA=float
Adjustment factor applied to branch UA. UA is derived (from wbSize, wbLength, wbInsulK, wbInsulThk, and wbExH) and then multiplied by wbFUA. Used to represent e.g. imperfect insulation. Note that parent DHWLOOP wlFUA does not apply to DHWLOOPBRANCH (only DHWLOOPSEG)
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 1 | No | constant |
wbExT=float
Surrounding equivalent temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(>\) 0 | 70 | No | hourly |
wbFlow=float
Branch flow rate assumed during draw.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gpm | x \(\ge\) 0 | 2 | No | hourly |
wbFWaste=float
Number of times during the hour when the branch volume is discarded.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0 | No | hourly |
endDHWLOOPBRANCH
Optionally indicates the end of the DHWLOOPBRANCH definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | none | No |
Related Probes:
4.42 DHWSOLARSYS
Solar water heating system.
- DHWSOLARSYS
- DHWSOLARCOLLECTOR
- DHWSOLARTANK
May have any number of solar collectors, but only one tank.
May have no tank for direct system? What if system has multiple primary tanks?
swElecMtr=mtrName
Name of METER object, if any, to which DHWSOLARSYS electrical energy use is recorded (under end use ???).
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | name of a METER | not recorded | No | constant |
swSCFluidSpHt=float
Specific heat for the collector fluid.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/lbm-oF | x \(>\) 0 | 0.9 | No | constant |
swSCFluidDens=float
Density for the collector fluid.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lb/ft3 | x \(>\) 0 | 64.0 | No | constant |
swEndUse
End use of pump energy; defaults to “DHW”.
swParElec=float
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\ge\) 0 | 0 | No | hourly |
swTankHXEff=float
Tank heat exchanger effectiveness.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(\le\) x \(\le\) 0.99 | 0 | No | hourly |
swTankTHxLimit=float
Temperature limit for the tank collector.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\geq\) 0 | 180.0 | No | constant |
swTankUA=float
Heat transfer coefficient for the tank multiplied by area.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/oF | No | constant |
swTankVol=float
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
gal | No | constant |
swTankInsulR=float
Total tank insulation resistance, built-in plus exterior wrap.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft2-oF/Btuh | No | constant |
swTankZone=znName
Pointer to tank zone location, use sw_tankTEx if NULL
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Name of ZONE | No | constant |
swTankTEx=float
Surrounding temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | No | hourly |
endDHWSOLARSYS
Optionally indicates the end of the DHWSOLARSYS definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
4.43 DHWSOLARCOLLECTOR
Solar Collector Array. May be multiple collectors on the same DHWSOLARSYS system. All inlets come from the DHWSOLARTANK.
Uses SRCC Ratings.
scArea=float
Collector area.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft^2 | \(>\) 0 | 0 | Yes | constant |
scMult
Number of identical collectors, default 1
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
\(>\) 0 | 1 | No | constant |
scTilt=float
Array tilt.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
deg | 0 | Yes | constant |
scAzm=float
Array azimuth.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
deg | 0 | Yes | constant |
scFRUL=float
Fit slope
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btuh/ft2-o^F | -0.727 | No | constant |
scFRTA=float
Fit y-intercept
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | \(>\) 0 | 0.758 | No | constant |
scTestMassFlow=flaot
Mass flow rate for collector loop SRCC rating.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lb/h-ft2 | x \(>\) 0 | 14.79 | No | constant |
scKta60=float
Incident angle modifier at 60 degree, from SRCC rating.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 0.72 | No | constant |
scOprMassFlow=float
Collector loop operating mass flow rate.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
lb/h-ft2 | x \(>\) 0 | 0.0 | No | constant |
scPipingLength=float
Collector piping length.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | x \(\geq\) 0 | 0.0 | No | Hourly and at the end of interval |
scPipingInsulK=float
Collector piping insulation conductivity.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 0.02167 | No | Hourly and at the end of interval |
scPipingInsulThk=float
Collector piping insulation thickness.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 1.0 | No | Hourly and at the end of interval |
scPipingExH=float
Collector piping heat transfer coefficient.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(>\) 0 | 1.5 | No | Hourly and at the end of interval |
scPipingExT=float
Collector piping surround temperature.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | x \(\geq\) 32 | 70.0 | No | hourly |
scPumpPwr=float
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Btu/h | x \(\ge\) 0 | from scPumpflow | No | constant |
scPumpLiqHeatF=float
Fraction of scPumpPwr added to liquid stream, the remainder is discarded.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 1.0 | No | Every run |
scPumpOnDeltaT=float
Temperature difference between the tank and collector outlet where pump turns on
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | 10.0 | No | constant |
scPumpOffDeltaT=float
Temperature difference between the tank and collector outlet where pump turns off
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
oF | 5.0 | No | constant |
endDHWSOLARCOLLECTOR
Optionally indicates the end of the DHWSOLARCOLLECTOR definition.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No |
4.44 PVARRAY
PVARRAY describes a photovoltaic panel system. The algorithms are based on the PVWatts calculator.
pvName
Name of photovoltaic array. Give after the word PVARRAY.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
63 characters | none | No | constant |
pvElecMtr=choice
Name of meter by which this PVARRAY’s AC power out is recorded. Generated power is expressed as a negative value.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
name of a METER | none | No | constant |
pvEndUse=choice
Meter end use to which the PVARRAY’s generated energy should be accumulated.
Clg | Cooling |
Htg | Heating (includes heat pump compressor) |
HPBU | Heat pump resistance heating (backup and defrost) |
DHW | Domestic (service) hot water |
DHWBU | Domestic (service) hot water heating backup (HPWH resistance) |
DHWMFL | Domestic (service) hot water heating multi-family loop pumping and loss makeup |
FANC | Fans, AC and cooling ventilation |
FANH | Fans, heating |
FANV | Fans, IAQ venting |
FAN | Fans, other purposes |
AUX | HVAC auxiliaries such as pumps |
PROC | Process |
LIT | Lighting |
RCP | Receptacles |
EXT | Exterior lighting |
REFR | Refrigeration |
DISH | Dishwashing |
DRY | Clothes drying |
WASH | Clothes washing |
COOK | Cooking |
USER1 | User-defined category 1 |
USER2 | User-defined category 2 |
BT | Battery charge power |
PV | Photovoltaic power generation |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Codes listed above | PV | No | constant |
pvDCSysSize=float
The rated photovoltaic system DC capacity/size as indicated by the nameplate.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
kW | x \(\geq\) 0 | none | Yes | constant |
pvModuleType=choice
Type of module to model. The module type determines the refraction index and temperature coefficient used in the simulation. Alternatively, the “Custom” module type may be used in conjunction with user-defined input for pvCoverRefrInd and pvTempCoeff.
Module Type | pvCoverRefrInd | pvTempCoeff |
---|---|---|
Standard | 1.3 | -0.00206 |
Premium | 1.3 | -0.00194 |
ThinFilm | 1.3 | -0.00178 |
Custom | User-defined | User-defined |
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Standard Premium ThinFilm Custom | Standard | No | constant |
pvCoverRefrInd=float
The refraction index for the coating applied to the module cover. A value of 1.0 represents refraction through air. Coatings have higher refraction indexes that capture more solar at lower angles of incidence.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x \(\geq\) 0 | 1.3 | No | constant |
pvTempCoeff=float
The temperature coefficient how the efficiency of the module varies with the cell temperature. Values are typically negative.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
1/oF | no restrictions | -0.00206 | No | constant |
pvArrayType=choice
The type of array describes mounting and tracking options. Roof mounted arrays have a higher installed nominal operating cell temperature (INOCT) of 120 oF compared to the default of 113 oF. Array self-shading is not currently calculated for adjacent rows of modules within an array.
Units | Legal Range | Default | Required | **Variability |
---|---|---|---|---|
FixedOpenRack, FixedRoofMount, OneAxisTracking, TwoAxisTracking | FixedOpenRack | No | constant |
pvTilt=float
The tilt of the photovoltaic array from horizontal. Values outside the range 0 to 360 are first normalized to that range. For one-axis tracking, defines the tilt of the rotation axis. Not used for two-axis tracking arrays. Should be omitted if pvVertices is given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
degrees | unrestricted | from pvVertices (if given) else 0 | No | hourly |
The following figures illustrate the use of both pvTilt and pvAzm for various configurations:
pvAzm=float
Photovoltaic array azimuth (0 = north, 90 = east, etc.). If a value outside the range 0o \(\leq\) x \(<\) 360o is given, it is normalized to that range. For one-axis tracking, defines the azimuth of the rotation axis. Not used for two-axis tracking arrays. Should be omitted if pvVertices is given.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
degrees | unrestricted | from pvVertices (if given) else 0 | No | hourly |
pvVertices=list of up to 36 floats
Vertices of an optional polygon representing the position and shape of the photovoltaic array. The polygon is used to calculate the shaded fraction using an advanced shading model. Only PVARRAYs and SHADEXs are considered in the advanced shading model – PVARRAYs can be shaded by SHADEXs or other PVARRAYs. If pvVertices is omitted, the PVARRAY is assumed to be unshaded at all times. Advanced shading must be enabled via TOP exShadeModel. Note that the polygon is used only for evaluating shading; array capacity is specified by pvDCSysSize (above).
The values that follow pvVertices are a series of X, Y, and Z values for the vertices of the polygon using a coordinate system defined from a viewpoint facing north. X and Y values convey east-west and north-south location respectively relative to an arbitrary origin (positive X value are to the east; positive Y values are to the north). Z values convey height relative to the building 0 level and positive values are upward.
The vertices are specified in counter-clockwise order when facing the receiving surface of the PVARRAY. The number of values provided must be a multiple of 3. The defined polygon must be planar and have no crossing edges. When pvMounting=Building, the effective position of the polygon is modified in response to building rotation specified by TOP bldgAzm.
For example, to specify a rectangular photovoltaic array that is 10 x 20 ft, tilted 45 degrees, and facing south –
pvVertices = 0, 0, 15, 20, 0, 15, 20, 7.07, 22.07, 0, 7.07, 22.07
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
ft | unrestricted | no polygon | 9, 12, 15, 18, 21, 24, 27, 30, 33, or 36 values | constant |
pvSIF=float
Shading Impact Factor (SIF) of the array used to represent the disproportionate impact on array output of partially shaded modules at the sub-array level. This impact is applied to the effective beam irradiance on the array:
\[I_{poa,beam,eff} = \max\left(I_{poa,beam}\cdot\left(1-SIF\cdot f_{sh}\right),0\right)\]
where \(f_{sh}\) is the fraction of the array that is shaded.
Default value is 1.2, which is representative of PV systems with sub-array microinverters or DC power optimizers. For systems without sub-array power electronics, values are closer to 2.0.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
– | x \(\geq\) 1.0 | 1.2 | No | constant |
pvMounting=choice
Specified mounting location of this PVARRAY. pvMounting=Site indicates the array position is not altered by building rotation via TOP bldgAzm, while PVARRAYs with pvMounting=Building are assumed to rotate with the building.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
Building or Site | Building | No | constant |
pvGrndRefl=float
Ground reflectance used for calculating reflected solar incidence on the array.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) x \(<\) 1.0 | 0.2 | No | hourly |
pvDCtoACRatio=float
DC-to-AC ratio used to intentionally undersize the AC inverter. This is used to increase energy production in the beginning and end of the day despite the possibility of clipping peak sun hours.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
x > 0.0 | 1.2 | No | constant |
pvInverterEff=float
AC inverter efficiency at rated DC power.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) x \(<\) 1.0 | 0.96 | No | constant |
pvSysLosses=float
Fraction of total DC energy lost. The total loss from a system is aggregated from several possible causes as illustrated below:
Loss Type | Default Assumption |
---|---|
Soiling | 0.02 |
Shading | 0 (handled explicitly) |
Snow | 0 |
Mismatch | 0 (shading mismatch handled explicitly [see pvSIF]) |
Wiring | 0.02 |
Connections | 0.005 |
Light-induced degradation | 0.015 |
Nameplate rating | 0.01 |
Age | 0.05 (estimated 0.5% degradation over 20 years) |
Availability | 0.03 |
Total | 0.14 |
Italic lines indicate differences from PVWatts assumptions.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
0 \(<\) x \(<\) 1.0 | 0.14 | No | hourly |
endPVARRAY
Optionally indicates the end of the PVARRAY definition. Alternatively, the end of the definition can be indicated by END or by beginning another object.
Units | Legal Range | Default | Required | Variability |
---|---|---|---|---|
none | No | constant |
Related Probes: