Merge branch 'main' into auxfeff

Author: chipbarnaby

.github/actions/build-cse/action.yml

@@ -0,0 +1,14 @@
+name: "Build CSE"
+description: "Get git info (for version) and build CSE executable"
+runs:
+  using: composite
+  steps:
+    - name: Get branch name
+      uses: tj-actions/[email protected]
+      id: branch-name
+    - name: Save branch name
+      run: echo "CI_GIT_BRANCH=${{steps.branch-name.outputs.current_branch}}" >> $GITHUB_ENV
+      shell: bash
+    - name: Build
+      shell: cmd
+      run: build.bat

.github/actions/build-docs/action.yml

@@ -0,0 +1,21 @@
+name: "Build docs"
+description: "Install prerequisites and build CSE documentation"
+runs:
+  using: composite
+  steps:
+    - name: Install pandoc
+      run: 'cinst -y pandoc --version=1.17.2 --ia=ALLUSERS=1'
+      shell: bash
+    - name: Add pandoc to path
+      run: echo "C:\Program Files (x86)\Pandoc" >> $GITHUB_PATH
+      shell: bash
+    - name: Add MSVC developer commands to PATH
+      uses: ilammy/msvc-dev-cmd@v1
+    - name: Set build to NOT do coverage check by default
+      run: rake set_coverage_off_by_default
+      shell: bash
+      working-directory: doc
+    - name: Build docs
+      run: rake
+      shell: bash
+      working-directory: doc

.github/actions/download-cse-artifact/action.yml

@@ -0,0 +1,10 @@
+name: "Download CSE artifact"
+description: "Download CSE executable built and uploaded in a previous job"
+runs:
+  using: composite
+  steps:
+    - name: Download executable artifact
+      uses: actions/download-artifact@v3
+      with:
+        name: CSE.exe
+        path: msvc

.github/workflows/build-and-test.yml

@@ -11,17 +11,14 @@ jobs:
         shell: bash
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
-      - name: Get branch name
-        uses: tj-actions/branch-names@v5
-        id: branch-name
-      - name: Save branch name
-        run: echo "CI_GIT_BRANCH=${{steps.branch-name.outputs.current_branch}}" >> $GITHUB_ENV
-      - name: Build
-        shell: cmd
-        run: build.bat
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+          submodules: recursive
+      - name: Build CSE
+        uses: ./.github/actions/build-cse
       - name: Upload executable artifiact
-        uses: actions/upload-artifact@v2.2.4
+        uses: actions/upload-artifact@v3
         with:
           name: CSE.exe
           path: msvc/CSE.exe
@@ -31,30 +28,18 @@ jobs:
     runs-on: windows-2022
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
+        uses: actions/checkout@v3.3.0
       - name: Configure CMake
         run: cmake -P cmake/configure.cmake
       - name: Build wcmp and unit test executable
         run: cmake --build . --config Release --target wcmp cse_tests
         working-directory: msvc/build
-      - name: Download executable artifact
-        uses: actions/download-artifact@v2
-        with:
-          name: CSE.exe
-          path: msvc
-      # - name: Download Mesa3D on Windows
-      #   if: runner.os == 'Windows'
-      #   shell: cmd
-      #   run: curl.exe -L --output mesa.7z --url https://github.com/pal1000/mesa-dist-win/releases/download/20.3.2/mesa3d-20.3.2-release-msvc.7z
-      #   working-directory: msvc
-      # - name: Install Mesa3D on Windows
-      #   if: runner.os == 'Windows'
-      #   shell: cmd
-      #   run: |
-      #     "C:\Program Files\7-Zip\7z.exe" x mesa.7z
-      #     mklink opengl32.dll "x64\opengl32.dll"
-      #     mklink libglapi.dll "x64\libglapi.dll"
-      #   working-directory: msvc
+      - name: Download CSE artifact
+        uses: ./.github/actions/download-cse-artifact
+      # - name: Setup Mesa3D
+      #   uses: bigladder/github-actions/setup-mesa3d@main
+      #   with:
+      #     install-directory: msvc
       - name: Test
         run: ctest -C Release -j 2 --output-on-failure -E shadetest  # CI can't do GPU calcs at this time (the steps above get us close, but throws an exception on destruction)
         working-directory: msvc/build
@@ -64,34 +49,20 @@ jobs:
     runs-on: windows-2022
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
+        uses: actions/checkout@v3.3.0
       - name: Configure CMake
         run: cmake -P cmake/configure.cmake
-      - name: Download executable artifact
-        uses: actions/download-artifact@v2
-        with:
-          name: CSE.exe
-          path: msvc
-      - name: Install pandoc
-        run: 'cinst -y pandoc --version=1.17.2 --ia=ALLUSERS=1'
-        shell: bash
-      - name: Add pandoc to path
-        run: echo "C:\Program Files (x86)\Pandoc" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
-      - name: Add MSVC developer commands to PATH
-        uses: ilammy/msvc-dev-cmd@v1
-      - name: Set build to NOT do coverage check by default
-        run: rake set_coverage_off_by_default
-        working-directory: doc
-      - name: Build docs (without coverage check)
-        run: rake
-        working-directory: doc
+      - name: Download CSE artifact
+        uses: ./.github/actions/download-cse-artifact
+      - name: Build docs
+        uses: ./.github/actions/build-docs
       - name: Run coverage check
         run: rake coverage
         working-directory: doc
       - name: Upload documentation
-        uses: actions/upload-artifact@v2.2.4
+        uses: actions/upload-artifact@v3
         with:
           name: Documentation
-          path: | 
+          path: |
                 doc/output
                 !doc/output/.git

.github/workflows/release.yml

@@ -14,30 +14,19 @@ jobs:
         shell: bash
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
-      - name: Get branch name
-        uses: tj-actions/branch-names@v5
-        id: branch-name
-      - name: Save branch name
-        run: echo "CI_GIT_BRANCH=${{steps.branch-name.outputs.current_branch}}" >> $GITHUB_ENV
-      - name: Build
-        shell: cmd
-        run: build.bat
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+          submodules: recursive
+      - name: Build CSE
+        uses: ./.github/actions/build-cse
       - name: Upload executable to release assets
-        uses: AButler/[email protected]
+        uses: AButler/[email protected].2
         with:
           files: msvc/CSE.exe
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Install pandoc
-        run: 'cinst -y pandoc --version=1.17.2 --ia=ALLUSERS=1'
-        shell: bash
-      - name: Add pandoc to path
-        run: echo "C:\Program Files (x86)\Pandoc" >> $GITHUB_PATH
-      - name: Add MSVC developer commands to PATH
-        uses: ilammy/msvc-dev-cmd@v1
       - name: Build docs
-        run: rake
-        working-directory: doc
+        uses: ./.github/actions/build-docs
       - name: Update gh-pages
         uses: peaceiris/actions-gh-pages@v3
         with:

README.md

@@ -1,4 +1,4 @@
-[![Build and Test](https://github.com/cse-sim/cse/workflows/Build%20and%20Test/badge.svg)](https://github.com/cse-sim/cse/actions?query=branch%3Amaster)
+[![Build and Test](https://github.com/cse-sim/cse/workflows/Build%20and%20Test/badge.svg)](https://github.com/cse-sim/cse/actions?query=branch%3Amain)
 
 ## California Simulation Engine (CSE)
 

cmake/string-finder.cmake

@@ -0,0 +1,8 @@
+# string-finder: Returns an error if string is not found in the given file. Otherwise exits gracefully.
+file(READ ${file} file_content)
+
+string(FIND ${file_content} ${string} content_location)
+
+if (${content_location} LESS 0)
+    message(FATAL_ERROR "STRING-FINDER ERROR: String, \"${string}\", not found in the file, \"${file}\".")
+endif()

doc/src/input-structure.md

@@ -1414,7 +1414,7 @@ Built-in functions perform a number of useful scheduling and conditional operati
   **Syntax**   *float* **wFromDbRh**( *float tDb, float rh*)
   ------------ -----------------------------------------------------------
 
-  #### rhFromDbW
+#### rhFromDbW
 
   ------------ -----------------------------------------------------------
   **Function** Returns relative humidity (0 – 1) of moist air from dry bulb

doc/src/operation.md

@@ -11,24 +11,39 @@ 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](#top-weather-data-items)).
 
+
 *{switches}*
 :   indicates zero or more of the following:
 
 -   -D*name* 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](#the-preprocessor)".
 
 -   -D*name*=*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](#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.
 
--   -b batch mode: CSE will never stop for a response from the user when an error occurs. Error messages may thus scroll off the screen, but will all be in the error message file.
+-   -U*name* undefines the preprocessor symbol *name*.
+
+-   -i*path;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](#probes)". Use with command processor redirection operator ">" to obtain a report in a file. *Inputfile* may be given or omitted when -p is given.
 
--   -q 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).
+-   -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.
 
-<!--
-TODO: Review all command line switches and update.  See cne3() and pp.cpp:ppClargIf() at least.
--->
+-   -t*nn* 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).
+
+
 ## 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.

doc/src/output-reports.md

@@ -22,6 +22,45 @@ A Meter Report displays the energy use of a METER object, a user-defined "device
 
 Meters account for energy use in pre-defined categories, called *end uses, that are documented with METER.*
 
+## Air Flow Meter Report
+
+An Air Flow Meter Report displays air flow values accumulated by an AFMETER that is associated with one or more ZONEs.  The report provides insight into the results of the AirNet pressure model.
+
+AFMETER maintains values for subhour, hour, day, month, and year intervals.  Values are standard cfm (0.075 lb/ft3).  Values for intervals longer than subhour are averages.
+
+Flows are categorized by 1) direction of flow (+ = into zone(s), - = out of zone(s)); IZXFER izAFCat tags; and 3) type of source or sink of the flow (ambient, unconditioned zone, conditioned zone).
+
+The following items are displayed (using the abbreviations shown in the report headings).  The "+/-" notation indicates that two columns are included, one for each direction of flow.  For example, "InfX+/-" means the report includes columns "InfX+" (infiltration flows into the zone) and "InfX-" (infiltration flows out of the zone).
+
+---------- -------------------------------------------------------------
+Tot+/-     Total flows
+
+Unkn+/-    Uncategorized flows (generally this shows 0)
+
+InfX+/-    Infiltration flows from/to ambient (izAFCat = InfilEx)
+
+VntX+/-    Natural vent exchanges from/to ambient (izAFCat = VentEx)
+
+FanX+/-    Forced vent and DOAS flows to/from ambient (izAFCat = FanEx)
+
+InfU+/-    Infiltration flows from/to unconditioned zones (izAFCat = InfilIz)
+
+VntU+/-    Natural vent flows from/to unconditioned zones (izAFCat = VentIz)
+
+FanU+/-    Forced vent flows from/to unconditioned zones (izAFCat = FanIz)
+
+InfC+/-    Infiltration flows from/to conditioned zones (izAFCat = InfilIz)
+
+VntC+/-    Natural vent flows from/to conditioned zones (izAFCat = VentIz)
+
+FanC+/-    Forced vent flows from/to conditioned zones (izAFCat = FanIz)
+
+Duct+/-    Duct leakage flows
+
+HVAC+/-    HVAC air flows at zone (i.e. at registers)
+---------- -------------------------------------------------------------
+
+
 ## Energy Balance Report
 
 The Energy Balance Report displays the temperature and sensible and latent heat flows into and out of the air of a single zone. Sign conventions assume that a positive flow increases the air temperature. Heat flow from a warm mass element such as a concrete wall into the zone air is defined as a positive flow, heat flow from air into mass is negative. Solar gain into the zone is defined as a positive heat flow. Solar gain that is incident on and absorbed directly into a mass element is shown as both a positve in the SOLAR column (gain to the zone) and a negative in the MASS column (lost from the zone to the mass).