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.

#includes may be nested to a depth of 5.

For an example of the use #includes, 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/ft²-^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. 34 = 12; 3.2418.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( ZAREA0.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 (= e^val)
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 (= val^x). 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.

val	result
val \(<\) 4	1
4 \(\leq\) val \(<\) 8	.667
8 \(\leq\) val \(<\) 12	.333
val \(\geq\) 12	0