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.

Introduction

The CSE Input Language is the fundamental interface to the CSE program. The language has been designed with three objectives in mind:

1. Providing direct access to all program features (including ones included for self-testing), to assist in program development.

2. Providing a set of parametric and expression evaluation capabilities useful for standards development and program testing.

3. 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.

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

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.

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.

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

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.

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.