This is an annotated copy of the exemplars_list file used by prj
to test current exemplars work. Its directives are scanned by prj
and used to control the tests to be carried out.

The directives take the form of a tag followed by phrases or numbers.

The *bin_path directive will need to be edited to specify the specific 
ESP-r distribution location. 

Alter *verbose to YES to see the interactions of bps and res or NO
for minimal chatter.

Alter *model_path to specify the location of the models to be tested.
For example /home/jon/training/ points to models in a users folder
while /opt/esp-r/training would place this in the ESP-r
distribution. NOTE - permissions should be set to allow read and write
access.

As assessments are carried out bps and res generate reports which
are compared with preformance ranges included in the list file. 
After scanning the temporary files should be deleted.

If you include *output FILE then prj will not ask for the summary
file name. This can simplify automated use of the facility.

The *label entry can be used to document the tests.

Interuptions in the file for purposes of this document are shown
with a . . . 

*EXEMPLARTEST
*help	The models contained in the following sections should track
*help	the exemplars distributed with ESP-r.
*help   
*help	It is possible to run individual tests or multiple selections.
*bin_path /home/jon/esp-r/bin/
*model_path  /home/jon/training/
*report_path /home/jon/training/std_reports/
*verbose NO
*output FILE /home/jon/training/all_exemplars.txt
*label  -- distributed exemplar models --
 . . .
 
The list of models and the assessment attributes.  Each starts
with *item

A number of models can be grouped together. For example
'*group	cellular' might test the paired office & corridor models.
A *group line is followed by a *help line with can further clarify 
the group.

If *item is followed by *name then it marks the start of a model
instance. The phrase following *name is what is presented in the
prj selection menu.

The *cfg line is the name of the ESP-r configuration file.

The *root line is the path to that file. The *model_path will
be pre-pended to derive a full path.

Models to be tested are assumed to include simulation parameter
sets and the *SPS line specifies which set to use. It must match
a SPS entry in the model cfg file.  By convention a model cfg
file will have a SPS entry for 'test' which is typically for
a week in February with save level 4. 

The *PIF line is a file which includes directives that drive
the res application to generate specific reports. A PIF file
is generated by a manual invocation of res recording the users
actions to generate a report. Convention is these are held in
a model test folder along with historic extracted *.dat files.
The usual metris are [??] 

The *res line should match the building results file in the
model cfg folder. The convention is test.bres.

The *rep line is the extracted data file name via the *.pif
file. By convention these reports generated by res end in '.dat'.

Examplar models are prepared as follows:
1) a test SPS should be added creating a results file with the
name ../tmp/test.bres (and optionally ../tmp/test.mfres).
2) an assessment run with that SPS and a check that the
results are credable. Run res with the recording of selections
turned on. Select all zones. Select statistical reports:
zone energy demands, then the heating loads, then cooling loads, 
then resultant temperatures. Toggle off the selection recording.
Edit the PIF file reference to the report file to be generated
to match [the_cfg_file_root_name].dat.  Rename the PIF file to 
[the_cfg_file_root_name].pif.
3) if not already existing create a 'test' folder in the model
and shift the pif file into it.
3) invoke res with 
res -mode text -file ../tmp/test.bres -act recover silent -actf ../test/[the_pif_file]

Look at the *.dat file that was created and if it looks ok
then shift it into the ../test folder. This will be used in
subsequent tests as a comparitor.

In the examples below each model has one test assessment. 
If more than one cfg file then ?? assume that test.bres is
cleaned up at end of each run.

 . . .
*item	
*group	small office models
*help	A set of models demonstrating ESP-r's functionality.
*item
*name	small_office_shd
*cfg	small_office_shd.cfg
*root	small_office_shd/cfg/
*SPS    test
*PIF    small_office_shd.pif
*res    test.bres
*rep    small_office_shd.dat
*item
*name	small_office_daily
*cfg	small_office_daily.cfg
*root	small_office_shd/cfg/
*SPS    test
*PIF    small_office_daily.pif
*res    test.bres
*rep    small_office_daily.dat
*item
*name	small_office_tbAD
*cfg	small_office_tbAD.cfg
*root	small_office_shd/cfg/
*SPS    test
*PIF    small_office_tbAD.pif
*res    test.bres
*rep    small_office_tbAD.dat
*item
*name	small_office_tbPL
*cfg	small_office_tbPL.cfg
*root	small_office_shd/cfg/
*SPS    test
*PIF    small_office_tbPL.pif
*res    test.bres
*rep    small_office_tbPL.dat
*item
*name	cellular_earth
*cfg	cellular_earth.cfg
*root	cellular_earth/cfg/
*SPS    test
*PIF    test.pif
*res    test.bres
*rep    cellular_earth.dat
 . . .


The singnal for the end of the file is *end

When running in non-verbose mode the display in prj will look
something like this:

 . . .
  
 Assessing std: office_operations.cfg
   
 Assessing tst: office_operations.cfg
   
 Comparing office_operations_s4.dat identical
 Comparing office_operations_s4.summary within tollerance.
   
 Assessing std: office_operations.cfg
   
 Assessing tst: office_operations.cfg
   
 Comparing office_operations_s5.h3k identical
 Comparing office_operations_s5.summary within tollerance.
   
 Assessing std: obs_4_eachface.cfg
   
 Assessing tst: obs_4_eachface.cfg
   
 Comparing obs_4_eachface_s4.dat identical
 Comparing obs_4_eachface_s4.summary within tollerance.
   
 Assessing std: obs_4_eachface.cfg
   
 Assessing tst: obs_4_eachface.cfg
   
 Comparing obs_4_eachface_s5.h3k identical
 Comparing obs_4_eachface_s5.summary within tollerance.
 ASCII line differences (group)    0
 Tollerance line differences (group)    0
 ASCII line differences (overall)    0
 Tollerance line differences (overall)    0
Selftest sets:
    -- standard tester models --    e small offices                
  a basic and detailed AIM            _____________________        
  b basic and detailed basesimp     * all available models         
  c CCHT basic and detailed house     _____________________        
  d idealized HVAC                  ? help                         
  - exit menu

 Selftest sets:?> 


In this case no ASCII lines in the *dat files differed and the
difference in the values in the .summary files were within the 
tolerance requested.

Additional documentation can be found the the ESP-r Selftest
document.
