The ContamFactorial program can be used to generate simulation input files for use in performing parametric (factorial) analysis. Although this documentation is presented using CONTAM project files, ContamFactorial can work with any text-based file. ContamFactorial utilizes two input files: a Flagged PRJ File and a Values File.
Begin with base PRJ file, which is a valid input file (e.g., CONTAM .PRJ or EnergyPlus .IDF file), i.e., an input file for which a simulation has been successfully run. You will modify this base file to create the Flagged PRJ File by replacing fields of the base file with specially formatted flag variables to indicate which values of the Flagged PRJ File are to change. Then create a separate text file, i.e., the Values File, from which ContamFactorial will obtain values with which the flagged variables are to be replaced.
The Values File is organized by Sets of Changes. You may want some changes in a Flagged PRJ File to occur simultaneously in order to properly effect a required change. For example, changing a CONTAM airflow element may require changes to the laminar and turbulent flow coefficients, or you may want to turn off a fan and activate a WTH file (as done in the example provided). You will provide each Set with a SetName that will be used as an identifier within the Flagged PRJ File. Provide each Change in a State with a Change number. These numbered changes will be replaced simultaneously when the Flagged PRJ File is processed.
HINT: You can make a change to a PRJ file with ContamW, save with a new name, and use a DIFF tool, e.g., WinMerge, to compare the two PRJ files to see exactly what changes in the PRJ file. This method will help you to identify exactly which values in the PRJ file need to be flagged to affect the desired changes.
The flag format is as follows: $(SetName ChangeNumber). For example, $(A 1) specifies ChangeNumber 1 of SetName "A". Each Set can take on a user defined number of States, and each State within a Set must have the same number of Changes.
ContamFactorial.exe is a Windows program. Upon running the program, you will be prompted to first select the name of the Values File and then the Flagged PRJ File.
Upon completion, ContamFactorial should have generated a set of files having the same extension as the Flagged PRJ File. The number of files generated should be equal to the product of the number of States in each Set. The files generated will have the name of the Flagged PRJ File followed by nStates of SetNames, each separated by an underscore "_", indicating the combination of factors used in generating the file.
HINT: Start with a simple set of changes before trying to implement a large set of factors. If the PRJ files are not generated properly, this is likely an error in the Values File, e.g., number of specified sets and/or changes not properly defined, or the Flags in the PRJ file are not properly defined, e.g., names don't match those in the Values File.
ContamFactorial will also generate a batch file to run each project with ContamX. The batch file and project files need to be in the same folder as ContamX in order to work properly. Depending on the version of ContamX, the bat file may require modification.
There is also a Python module provided that will run all PRJ files in parallel. To use run-cx-all-simple.py place it in the same folder as the PRJ files and contamx3.exe and run the module.
NOTE: You must have Python properly installed/configured on your system to run the Python module.
HINT: Be sure to account for the location of any input files, e.g., WTH, CTM, WPC, CVF, and DVF files, required for your simulations. You may want to locate them in a common folder/directory and include that directory when specifying the input files via the Values File, or you can not include a path and be sure to locate the input files alongside the PRJ files generated by ContamFactorial as done for the example provided.
The following provides the format of the Values File and an example file that accompanies this program. Like the CONTAM PRJ file, the Values File utilizes the exclamation point character "!" to denote a comment. Everything that occurs on a line after the comment marker is ignored by the ContamFactorial program.
The first non-comment line of the file must contain the total number of sets (nSets).
This must be followed by a section of information for each of the nSets. The first line of each section must provide the following three items describing the Set:
nCh - the number of Changes to be provided for each State in this Set
nStates - the number of States to be provided for this Set
! SetName - the name of this Set preceded by an exclamation point "!"
The second line of each section contains nState SetNames separated by any number of white spaces, i.e., spaces and tabs.
The second line of each section is followed by nCh lines containing nState values to be used to replace the flags within the Flagged PRJ file.
This case demonstrates the use of ContamFactorial. The files used in the case are:
This is a very simple, single-zone PRJ file meant only to demonstrate the capabilities of ContamFactorial. Ventilation and contaminant source will be varied using the features of ContamFactorial. Ventilation will be driven by a fan and/or wind via a CONTAM weather file (WTH file) and contaminant will be introduced into the zone from an interior source and/or from an ambient concentration provided via a contaminant file (CTM file). Results can be evaluated using a number of potential outputs including the exposure results file (.ebw file) as demonstrated in the example provided (See Working with Results in the CONTAM User Guide and Program Documentation).
The example contains two Sets: the first named "SOURCE" and the second "VENT". The SOURCE Set consists of 3 States each containing 2 Changes. The VENT Set consists of 4 States each containing 2 Changes. The SOURCE set controls the multiplier of the source/sink together with the use/name of the CTM File. The VENT set controls the multiplier on the flow path that references the fan (forced flow element) and the use/name of the WTH file which will provide for wind-driven ventilation.
NOTE: All changes of a given set are applied together within the same generated PRJ file. For the example provided, 12 (3 x 4) different PRJ files will be generated, i.e., the product of the number of States in each Set.
This Values File (demoCF-values.txt) along with the accompanying Flagged PRJ File (demoCF.prj) will generate the following list of 18 (3 x 6) PRJ files.
The flagged fields are highlighted in red.
The chart provides a comparison of the Average Concentration [mg/m3] obtained from the .EBW results files.
