Input & Output Layout

Immediately under the project directory are two sub-directories, Input and Output, that store input and output data, respectively. The authoritative description of every input file, with its current format, is in Input Files; the output files are described in Outputs. This page follows the developer manual and names the function that reads each file.

The Input directory contains six subsidiary directories: Crew, HardwareReliability, Indicators, Scheduler, SupportSystemsReliability and System. The Crew directory is further divided into four subdirectories: DecisionMaker, ActionTaker, Consultant, and Procedures. All the input related files are called only at the beginning of a simulation. After these files are read, the content is stored and processed in memory. Restoring an existing branching node data to start simulating another sequence does not need to read these input files again.

The output directory contains three directories storing information of end states (i.e., in ES directory), key parameters (i.e., in KPS directory), and pivotal events (i.e., in PE directory). Each of these directories is further divided into a number of subdirectories and is dependent on the size of the DDET. Each subdirectory is designated to store no more than 1000 files of the same type of information. Additional subdirectories (at the same level) will be created automatically during simulation when the number of same type of files exceeds 1000. The number 1000 is defined by BranchRecord::size_of_subfolder.

Tables 1 and 2 show the current ADS input and output files respectively and their contents.

Table 1 Overview of the ADS input files and their storage locations.

Directory	Subdirectory	File Name and Content
Current directory of the process	--	1. ZiniADS.txt (optional) An options file. It can give the project directory and the input deck location, and any other command-line option, when they are not given on the command line.
Input/Crew	DecisionMaker	1. DecisionMaker.txt This file contains the thresholds which include “action time multiplier”, “confidence level for activating the hardwired knowledge based”, and “probability of use of memorized information” for the Decision Maker.
2. KB_ODM_System_Decomposition.txt Each piece of system information should be related to one or more high-level system hardware structure. This file provides such linkages.
3. KB_ODM_HardWired_Diagnosis.txt This file provides the linkages between the Decision Maker’s mental beliefs (or diagnoses) and the system information as well as other mental beliefs. These linkages intend to simulate the operator’s heuristic in system state perception with corresponding natural response to t=such perception. The mental beliefs identified in this file whose confidence levels are updated every time step. Once the confidence level of a mental belief exceeds the value of “confidence level for activating the hardwired knowledge based” specified in DecisionMaker.txt then the mental belief would be activated with probability specified in the KB_ODM_HardWired_Diagnosis.txt.
4. KB_ODM_Event_Matrix.txt This file provides the relationship between operator perceived symptoms and events. This file also intends to model the operator’s heuristic in assessing the system state. However, different from the mental beliefs specified in the “KB_ODM_HardWired_Diagnosis.txt” the events and symptoms provided here intend for guiding operator’s further cognitive process once the operator has sufficient confidence in an event.
ActionTaker	1. ActionTaker.txt See corresponding description for the Decision Maker.
2. KB_OAT_Event_Matrix.txt See corresponding description for the Decision Maker.
3. KB_OAT_System_Decomposition.txt See corresponding description for the Decision Maker.
4. KB_OAT_HardWired_Diagnosis.txt See corresponding description for the Decision Maker.
Consultant	Not implemented in the ADS code currently. Most of the framework for the Consultant current exists in the code. However, they are not activated due to the unclearness in the responsibilities of the Consultant.
Procedures	1. Procedures.txt This file specifies the name of procedural steps that have been coded and those have not been coded but are referred by the coded procedural steps.
2. All procedure steps enlisted in the “coded steps” section within the file “procedures.txt.” The file name format of a procedural step is ZProcedure_<procedure name>_<step name>.txt
3. ProcedureActionTimeBranches.txt This files specifies the branches to be generated due to the uncertainty of the operator’s physical actions to change the system state. The information includes the number of branches to be generated and the corresponding time ratio and probability of each branch to be generated. Each action instructed in the procedure has a nominal action time entered by the user. The time ration of nominal time is one. During simulation, only when the procedure name, step name, and action name of an action are identical to any one specified in the ProcedureActionTimeBranches.txt, branches are generated. When the action does not match any specified in the file, a branch with the nominal time will be generated. The Class is declared as BranchProcedureActionTime in theBranchRecord.
Input/HardwareReliability	--	1. SystemReliability.txt This files provides the information for branching due to hardware failure. Currently only failure on demand is implemented in the ADS code. Failure during operation currently is not implemented due to the short time window of the events of interest.
Input/Indicators	--	1. ControlPanel.txt This file identify the constitutional elements (including alarms, parameters, components’ states, and controls) of the control panel and provides information to update these elements based on the state of the system.
2. SPDS_input.txt This files provides another type of information displayed in the control panel which is not specified in the ControlPanel.txt. The SPDS intend to model the indication of the Safety Parameter Display System, which is similar to the Critical Safety Function Tree.
Input/Scheduler	--	1. ZCtrlPar.txt This file provides some sequence truncation criteria including sequence probability and sequence time. The other two parameters specified in this file are not used in current ADS. Note, sequences also can be truncated based on the state of a parameter. This can be set by specifying alarms whose name started with “A_ENDSEQ_” (e.g., A_ENDSEQ_Hi_CORE_TEMP). When any of such alarms is activated, the sequence is terminated.
Input/System	--	1. Initiating_Event.txt This files enables the user to setup the initiating time of various predefined initiating event for a simulation. 2. RELAP5_channels.txt This file contains information for the ADS code to access RELAP5 data.

Table 2 Overview of the ADS output files and their storage locations.

Directory	Subdirectory	File Name and Contain
Output/ES	ESFolder_N (N starts at zero)	1. ZESNode_M.txt The file contains the end state information of Sequence M. The first sequence is Sequence zero (0). Each subfolder holds at most 1000 files, and additional folders are created automatically during the simulation. For example, files ZESNode_0.txt to ZESNode_999.txt are saved in the folder ESFolder_0, and files ZESNode_1000.txt to ZESNode_1999.txt in the folder ESFolder_1. The value 1000 is BranchRecord::size_of_subfolder, which applies to all three output classes.
--	2. ES_summary.txt This file provides a quick summary of the end states of all sequences including sequence probabilities, time terminated, and reason of termination.
--	3. Scenario info.txt, Procedure data.txt, Scan data.txt The analysis logs. Each holds one block per sequence: the activities of the sequence in chronological order, the procedure-step data, and the scan-queue data. They provide another means than the event tree for analyzing the sequences.
Output/KPS	KPSFolder_N (N starts at zero)	1. ZKPS_M.txt This file records the time history of the parameters defined in the control panel for Sequence M. The first sequence is Sequence zero (0). Each subfolder holds the files of at most 1000 sequences. The files are tab-separated and open in a spreadsheet.
2. ZDIA_M.txt This file records the time history of the operators’ confidence in the events defined in KB_ODM_Event_Matrix.txt and KB_OAT_Event_Matrix.txt for Sequence M.
3. ZPIF_M.txt This file records the time history of the dynamic performance influencing factors for Sequence M.
Output/PE	PEFolder_N (N starts at zero)	1. ZPENode_M.txt Each ZPENode file represents a branch, not a branching node. A branching node can be followed by more than one branch. The information common to all branches of a node is stored in the file of the first sibling branch (the first of the branches that follow the same node). M is the branch id and starts at zero. Each subfolder holds at most 1000 ZPENode files. After the final renumbering of an MPI run or a resumed run, all files are in PEFolder_0 (see Output Data Handling).

The content and format of the input files are described according to the directories as the following. All these input related files are called only once at the beginning of a simulation. After these files are read, the content is stored and processed in memory. Restoring an existed branching node data to start simulating another sequence does not need to read these input files again.

• Current directory of the process
  • ZiniADS.txt (optional)
    • Calling function: Scheduler::parseOptions
    • Parameters defined in: SimConfig (g_sim.config) and class Scheduler

The engine reads ZiniADS.txt as an options file: one name=value line per option, with the same option names as the command line. An option given on the command line takes precedence over the file.

Example content of the ZiniADS.txt

project-dir=/path/to/project
input-deck=/path/to/project/deck.i

The developer manual describes a different layout for this file (the keywords Project_Directory, Input_Deck_File and Simulation_Type, each followed by its value on the next line). Scheduler::readInfoFromFile() parses that layout, but nothing calls it, so the engine does not read it.

• ActionTaker: Stores data that characterized the Action Taker. Three files are included in this folder:
  • ActionTaker.txt:
    • Calling function: Operator::initiationForSimulation
    • Parameters defined in: class Operator

Example content, in bold text shown below.

Action_Taker 3

action_time_multiplier 0.2

confidence_level_for_activating_HWKB 110.0

Use_memorized_info 0.0

• • • The number follows Action_Taker in the first line (i.e., 3) indicates the number of parameters included in this file.
      • The value for action_time_multiplier will be multiplied to the nominal time required for each activities performed by the Action Taker. For example, originally an action takes 20 seconds to be completed. The resulting action only requires 4 seconds (equals to 20 times 0.2) in this case.
      • The value of confidence_level_for_activating_HWKB (in percentage) is the threshold to active a hardwiredDiagnosis specified in the KB_OAT_HardWired_Diagnosis.txt. When the confidence level (a value between 0 and 100) of a piece of hardwired diagnosis exceeds the threshold value during simulation, the hardwired diagnosis will be activated. In this example, a threshold value is set to be 100 that will prevent all hardwired information from being activated.
      • The number following the Use_memorized_Info is the probability of applying memorized information instead of checking the system for an information update when the operator is instructed to check for a piece of information and the same piece of information has been perceived earlier.
    • KB OAT System decomposition.txt
      • Calling function: KB::readSystemDecompositionKB(int)
      • Parameters defined in: class Operator

This file provides the links between the information shown in the control panel to a high-level system decomposition. The first line within this file is a header. The text within a pair of quotation marks (“) explains the system decomposition to be associated with control panel information. Following the explanation is a list of the control panel information with their associated systems. One (control panel information) or multiple (system decompositions) linkages is allowed.

• • KB_OAT_HardWired_Diagnosis.txt - Calling function: KB:: readHardWiredDiagnosis(int) - Parameters defined in: class KBHardWiredUnit

This file specifies the “hardwired” diagnoses that operator obtained through training to capture some of the operator nature response. This file is read by the function KB::readHardWiredDiagnosis(int). Each Hard wire Unit is called by the function KBHardWiredUnit::readInfoFromFile() which in turn is called by Operator:: checkAndActivateHWKB().

An example unit of a hardwired diagnosis is shown below:

B_SG_B_LOW_PRESSURE

0.7

Number_of_expected_alarm_state 1

A_SGB_LoP 3022

Number_of_expected_component_state 0

Number_of_expected_parameter_value 0

Number_of_manipulative_control 0

Number_of_mental_belief 0

IR 1

• B_SG_B_LOW_PRESSURE: is the name of the diagnosis (or mental belief). The name could be used in procedure. The ADS program uses string comparison to determine whether the diagnoses mentioned in different places are identical. As a result, keep the unique and identical name in all places for the same diagnosis is very important.
• Probability (i.e., 0.7 in the above example): represents the probability of the operator would belief the diagnosis when the confidence of the diagnosis exceeds a pre-set threshold. The threshold value is carried by the parameter Operator: threshold_value_for_HWKB_confidence.
  
  Note: the threshold value is between zero and one hundred (100) but the probability is a value between zero and one (1). If the probability is set to greater than 0.999999 then only one branch would be generated when the confidence level of the diagnosis exceeds the threshold value. If the probability is set to be less than 0.000001 then nothing would happen even if the confidence level of the diagnosis exceeds the threshold value (See Operator::checkAndActivateHWKB).

The probability is calculated based on the ratio of the number of matched expectation to the total number of expectation. Currently, each expectation has the same weight irrespective to the type of expectation (e.g., alarm or parameter state). Each matched expectation is credit a point, and each unmatched expectation would subtract one point. As a result, negative confidence is possible. Such setting for calculating confidence level (i.e., equal weight and positive only) might need to be revised in the future.

• Number_of_expected_alarm_state: This row combines a default string “Number_of_expected_alarm_state” as a header and an integer number X. The value of X indicates the number of KBExpectedAlarmStateUnit input would follow. The content of each expected alarm state is specified in KBExpectedAlarmStateUnit::readInfoFromFile(ofstream &). Currently, the input information is

<string><integer>

The <string> is the name of the alarm. The <integer> is the expected alarm state which is either On (3022) or OFF (3023). The definitions are specified in the file TermConversions.h within the Head Files/GlobalH.

• Number_of_expected_component_state: This row combines a default string “Number_of_expected_component_state” as a header and an integer number X. The value of X indicates the number of KBExpectedComponentStateUnit input would follow. The content of each expected alarm state is specified in KBExpectedComponentStateUnit::readInfoFromFile(ofstream &). Currently, the input information is

<string><integer>

The <string> is the name of the component. The <integer> is the expected component state which is either On (3022)/OFF (3023) (e.g., for pump) or Open(3098)/Close(3099) (e.g., for valves). The definitions are specified in the file TermConversions.h within the Head Files/GlobalH.

• Number_of_expected_parameter_value: This row combines a default string “Number_of_expected_parameter_value” as a header and an integer number X. The value of X indicates the number of KBExpectedParameterValueUnit input would follow. The content of each expected alarm state is specified in KBExpectedParameterValueUnit::readInfoFromFile(ofstream &). Currently, the input information is

<string><integer><double 1><double 2>

The <string> is the name of the parameter. The <integer> is the logic operator which could be either

• • • • “Greater Than” (3006) - “Greater than or Equal To” (3007) - “Equal To” (3008) - “Less Than or Equal To” (3009) - “Less Than” (3010), and - “Between” (3032).

As defined in the file TermConversions.h within the Head Files/GlobalH. Double1 and Double2 are values for comparison. When the logic operator is everything but “Between” only Double 1 would be used. Otherwise, the value of the parameter is expected to be Double1 < Parameter Value < Double 2. The comparison is defined in KBExpectedParameterValueUnit::checkForMatch(). The Parameter_value also include the parameter trend since the parameter trend, in terms of output, is treated same as the parameter value. The Double 1 and Double 2 for the Expected Parameter Trend are the trend of the parameter. The KBExpectedParameterTrendUnit::expected_tred is not used currently.

• Number_of_manipulative_control: This row combines a default string “Number_of_expected_parameter_value” as a header and an integer number X. The value of X indicates the number of HardWiredControlActivity input would follow. The content of each expected alarm state is specified in HardWiredControlActivity::readInfoFromFile(ofstream &). Currently, the input information is

<string><double>

The <string> is the name of the control. The <double> is the control value. The rule for checking the expectation is defined in HardWiredControlActivity::checkForMatch(). NOTE: the comparison rule set in this function might need to be revised since the control values for various component are not well defined at this time.

• Number_of_Mental_Belief: This row combines a default string “Number_of_mental_belief” as a header and an integer number X. The value of X indicates the number of HardWiredMentalBelief input would follow. The content of each expected alarm state is specified in HardWiredMentalBelief::readInfoFromFile(ofstream &). Currently, the input information is

<string><integer>

The <string> is the name of the component. The <integer> is the expected state of the mental belief which is either On (3022) or OFF (3023) as specified in the file TermConversions.h within the Head Files/GlobalH.

• Response_Procedure_and_Step: This row specified the procedural step would be activated when the confidence level of this KBHardwiredUnit exceeds a preset threshold (define by operator::threshold_value_for_HWKB_confidence).

********* Notes ****************************************************

* The character between any two parameters denoted (enclosed) by “< >” could be a space (‘ ‘), tab (‘\t’) or a new line (‘\n’). For example, “<integer 1> <integer 2>” means

* <integer 1> <space, tab, or new line> <integer 2>.

*******************************************************************

• • Event Matrix.txt - Calling function: KB::readSystemDecompositionKB (int) - Parameters defined in: class EventSymptomMatrix

The file stores the relationship between symptoms and events and is read by EventSymptomMatrix::readInfoFromFile(). The content of this file first by specifying the number of symptoms and followed by the names of theses symptoms. The number of events and followed by the names of these events with the corresponding values in the matrix that specify the relationship between symptoms and events. The meaning of a value means that “given the condition that the symptom is perceived, what is the confidence level that the operator would have in the corresponding event.” The confidence of an event is represented by three values: lower_bound, upper_bound, and averaged value. The first two values (i.e., low_bound and upper_bound) are calculated with use of Fuzzy logic. The third value (i.e., averaged value) is simply an average value of the low_bound and upper_bound.

• Consultant: The Consultant is not activated in the current version of ADS code.
• Decision Maker: See discussion for the Action Taker.
• Procedures
  • Procedures.txt
    • Calling function: Procedures::readInfoFromFile ()
    • Parameters defined in: class ProcedureProcedureStepInfo.

The format of this file is:

<string header1> <integer1>

{repeat integer1 times <procedure name><step name>

<string header1> <integer2>

{repeat integer2 times <procedure name><step name>

The <header1> is “Coded-Procedures.” Integer1 is the number of coded procedure steps. The <header2> is “Non_coded_procedure.” Integer2 is the number of uncoded procedural steps but mentioned in other places of the code.

• • ZProcedure_<Procedure name>_<step name>.txt - Calling function: Procedures::readInfoFromFile () - Parameters defined in: class ProcedureStepUnit

Each of these files contains the instruction for a procedural step. The format of the file content is in Appendix E.1.

• • ProcedureActionTimeBranches.txt - Calling function: BranchProcedureAtionTime::readInfoFromFile() called by BranchRecord::initiationForSimulation() - Parameters defined in: class BranchProcedureAtionTime

The format of the file is:

<string 1><Integer 2>

{Repeat Integer2 times [<string 3><string 4><string 5><integer 6>

<string 7> repeat integer6 times [<double 8_x>]

<string 9> repeat integer6 times [<double 10_x>]}

Where

• • • String 1 is a fixed string “Procedure_Action_Time_Branches” without space between characters
      • Integer 1 is the number of actions when demanded will generate multiple branches
      • String 3 is the procedure name
      • String 4 is the step name
      • String 5 is the action name
      • Integer 6 is the number of branches to be generated if the corresponding action (i.e., specified by the String 5 in the procedure step specified by strings 3 and 4) is demanded
      • String 7 is a fix string “Time_Ratio” without quotation
      • Double 8_x are the time ratios of branches
      • Strinfg 9 is a fix string “Probability” without quotation
      • Double 10_x are the probabilities of branches.

The following is an example of the input file ProcedureActionTimeBranches.txt

****Begin of example ProcedureActionTimeBranches.txt****

Procedure_Action_Time_Branches

1

EP_1_A_1800_001 0 X_SCRAM 3

Time_Ratio 0.5 1.0 3.0

Probability 0.3 0.4 0.3

***End of example ProcedureActionTimeBranches.txt****

• HardwareReliability
  • SystemReliability.txt
    • Calling function: HWReliabilityModule::readInfoFromFile ()
    • Parameters defined in: class HWReliabilityUnit

This file specifies the interested possible hardware failure on demand. The file format is the following:

<String 1> <Integer 1>

{repeat Integer 1 times of <String 2> <String 3> <Double 1> <Double 2>}

Where

• <String 1> is a fixed header “System_Reliability”
• <Integer 1> is the number of components included in this file
• <String 2> is the component unique ID specified in the control panel
• <String 3> is the corresponding unique control ID specified in the control panel
• <Double 1> is a dummy value. This value currently is not used.
• <Double 2> is the probability that the component would fail when demanded.
• Indicators
  • ControlPanel.txt:
• Frequency called: once only at the beginning of a simulation
• Calling function: ControlPanel::initiationForSimulation ()
• Parameters defined in: class DisplayParameterValue, DisplayParameterValueRate, DisplayComponentState, DisplayHeatStructure, AlarmComponent, AlarmParameter, AlarmTwoParameterDifference, ControlState, and ControlValue.

This file contains all control panel information. See section E2 for the detailed file detail.

• • SPDS_input.txt - Calling function: SPDS::readInfoFromFile() - Parameters defined in: class SPDSUnit

This files specifies the key parameters and associated characteristics that are used to calculate the Safety Parameter Display System (i.e., a similar function of the Critical Safety Event Tree). The content format is described as the following:

<String 1> <Integer 1> <String 2> <Double 1>

{repeat Integer 1 times of <String 3><String 4><Double 2>

<Double 3><Double 4><Double 5><Double 6>}

Where

• String 1: a fixed header “SPDS_INPUT”
• Integer 1: the number of key parameters included in this file that constitute the SPDS
• String 2: a fixed header “Time_Lapse”
• Double 1: the SPDS object calculate a SPDS value and the changing rate of the SPDS value (i.e., d(SPDS)/dt). A linear regression is used to calculate the changing rate. A number of data points is required in order to calculate the changing rate. Current the number of data points used for regression calculation is a constant value (10; see SPDS::initiationForSimulation()). The time lapse is a variable specified by SPDS:: time_lapse_for_update (i.e., Double 1).
• <String 3>: the Unique SPDS name for referring to the key parameter used for this calculation
• <String 4>: the parameter’s unique ID specified in the control panel whose value is input for calculating the SPDS value.
• <Double 2>: the Low Low threshold value used for calculating the SPDS value
• <Double 3>: the Low threshold value used for calculating the SPDS value
• <Double 4>: the High threshold value used for calculating the SPDS value
• <Double 5>: the High High threshold value used for calculating the SPDS value
• <Double 6>: the weight of the parameter contributing to calculating the SPDS value.

Equation for calculating the SPDS value is in SPDSUnit::calculateSPDSUnitValue().

• Scheduler
  • ZCtrlPar.txt
• Calling function: Scheduler::readInfoFromFile
• Parameters defined in: class Scheduler

This file provides some sequence truncation criteria including sequence probability and sequence time. The other two parameters specified in this file are not used in current ADS. Note: sequences also can be truncated based on the state of a parameter. This can be set by specifying alarms whose name started with “A_ENDSEQ_” (e.g., A_ENDSEQ_Hi_CORE_TEMP). When any of such alarms is activated, the sequence is terminated.

The file format is as the follows:

<String 1>

<String 2> <Double 1>

<String 3> <Double 2>

<String 4> <Double 3>

<String 5> <Integer 1>

Where:

• String 1 is a pre-specified string “CtrlPar”. No space exists between the characters of String 1.
• String 2 is a pre-specified string “Truncated_probability”. No space exists between the characters of String 2.
• Double 1 is the user specified floating point value that sets the probability for sequence truncation.
• String 3 is a pre-specified string “Truncated_time”. No space exists between the characters of String .
• Double 2 is the user specified floating point value that sets the maximum time lapse for sequence truncation.
• String 4 is a pre-specified string “CompF_time_interval”. No space exists between the characters of String 4.
• Double 3 is the user specified floating point value that set the frequency for checking component failure rate during operation (in contrast to failure on demand). This parameter is not implemented in current ADS.
• String 5 is a pre-specified string “Output_precision”. No space exists between the characters of String 5.
• Integer 1 is the user specified positive integer value that set the precision requirement for the output floating points.

Example of file content:

CtrlPar

Truncated_probability 1E-11

Truncated_time 1200.0

CompF_time_interval 100.0

Output_precision 3

• System
  • Initiating_Event.txt
• Calling function: InitiatingEventController::readInfoFromFile()
• Parameters defined in: class InitiatingEventUnit

This files enables the user to setup the initiating time of various predefined initiating event for a simulation. Multiple initiating events activated at different times is allowed.

<String1><space><Integer1><new line>

{For I = 0; I < Integer1; I++ ; <String2x><Double1x><Double 2x><String 3x>< Double3x><new line>}

• String 1 is a pre-specified string “Initiating_Event”. No space exists between the characters of String 1.
• Integer 1 is an integer that specifies the number of initiating events to be activated during simulation.
• String 2x is the name of the initiating event specified by the user.
• Double 1x is the event frequency of the corresponding initiating event.
• Double 2x is the time at which the corresponding initiating event will be activated. When the value of this number is negative (less than zero) the corresponding initiating event will not be activated during simulation.
• String 3x is the unique name (or ID) of the corresponding within the control panel control that is activated to initiate the initiating event.
• Double 3x is the value passed to the control indicated by String 3 during simulation to initiate the initiating event.
  • RELAP5_channels.txt
• Calling function: SystemModule::readInfoFromFile()
• Parameters defined in: class SystemModule

This file provides the information needed for the ADS program to access RELAP5 data. The format of RELAP5_channels.txt is described in Appendix E3.