11.2 The Fundamental Data Structures within FieldUtils

This sections aim to provide a detailed description of the data structures within the FieldUtils directory and how they are used by FieldConvert.

11.2.1 Overview of how modules work

A specific module is identified by a ModuleKey, a type defined as a std::pair consisting of a ModuleType and std::string. ModuleType is an enum that has members eInputModule, eProcessModule, and eOutputModule, corresponding to whether it is an input, process, or output module respectively. The std::string is referred to in this document as the module string. ¹ For example, for the InputFld module, the ModuleType is eInputModule, and the module string is fld. The instantiation of a particular module follows the factory pattern, with the ModuleKey and a shared pointer to a Field object passed as arguments to Module::GetModuleFactory().CreateInstance. This shared pointer to the Field object is stored as a member variable of Module called m_f.

Some modules have configuration options, which are stored in the m_config member variable of Module, which is a std::map with the key being a string holding the option name and the value being a ConfigOption object (described below). The configuration options for the input and output modules simply refer to the name of the input and output file respectively m_config is initialised in the module’s constructor by calling the ConfigOption constructor, and its value is set by Module::RegisterConfig. The Moduel::SetDefaults function sets default configuration options for those which have not been set.

Each module has a function named Process, whether defined in its own class definition or in that of its parent class, which implements the main functionality of the module. To run a module refers to calling Process. Process typically operates on member variables of m_f. Each module also has a certain priority, which dictates in what order it should be run in relation to other modules, which is captured by a member of the ModulePriority enum, defined in Module.h. The available module priorities are eCreateGraph, eCreateFieldData, eModifyFieldData, eCreateExp, eFillExp, eModifyExp, eBndExtraction, eCreatePts,eConvertExpToPts, eModifyPts, and eOutput.

What follows is detailed description of the member variables and functions of Module, InputModule, ProcessModule, and OutputModule.

11.2.2 Module

Member variables

• m_f: a FieldSharedPtr.
• m_config (protected): a std::map<std::string, ConfigOption> used to store the configuration option for the module.

Member functions

• A constructor takes as an argument a FieldSharedPtr, and sets m_f to it.
• The default constructor (protected) does nothing.
• Pure virtual Process(boost::program_options::variables_map) implements the main functionality of the derived class.
• Pure virtual GetModuleName() returns the name of the derived class.
• Pure virtual GetModuleDescription() returns a description of the functionality of the specific module represented by derived class.
• Virtual GetModulePriority() returns the ModulePriority of the derived class.
• RegisterConfig(std::string key, std::string value = "") looks for key in m_config, and if it exists, sets the corresponding ConfigOption to have m_beenSet = true, and m_value equal to 1 if it is a boolean option, and to value otherwise.
• PrintConfig() prints out all options for a module.
• SetDefaults() sets m_value to the default value (defined in the respective module) if m_beenSet is false.

11.2.3 InputModule

Member variables

• m_allowedFiles (protected): std::set<std::string> describing the file types that are compatible with the module.

Member functions

• A constructor takes as an argument a FieldSharedPtr, and creates a pair in m_config with key "infile" and value a ConfigOption with m_isBool = false, m_value = "", and m_desc = "Input filename.".
• AddFile(std::string fileType, std::string fileName) checks to see if fileType is in m_allowedFiles, and then adds fileName to m_f’s m_inputfiles entry with key fileType.
• GuessFormat(std::string fileName) attempts to guess the format of fileName using the characters in the file.
• PrintSummary() prints the amount of memory taken up by m_f->m_data.

11.2.4 ProcessModule

Member functions

• The default constructor does nothing.
• A constructor takes as an argument a FieldSharedPtr and does nothing.

11.2.5 OutputModule

Member variables

• m_fldFile (protected): a std::ofstream corresponding with the file that data will be output to.

Member functions

• A constructor takes as an argument a FieldSharedPtr, and creates a pair in m_config with key "outfile" and value a ConfigOption with m_isBool = false, m_value = "", and m_desc = "Output filename.".
• OpenStream() opens the output file specified by m_value in m_config’s entry with key "outfile".

11.2.6 ConfigOption

This struct is defined Module.h. It represents the properties of a module option.

Member variables

• m_isBool: a bool that is true if the option is a boolean (and so its value does not need to be specified).
• m_beenSet: a bool that is true if the option has been set using Module::RegisterConfig. If it is false, the default value will be put into m_value.
• m_value: a std::string that is the value of the option.
• defValue: a std::string that is the default value of the option.
• m_desc: a std::string that is the description of the option.

Member functions

• The default constructor sets m_isBool and m_beenSet to false.
• A constructor sets m_isBool, m_defValue, m_desc from respective arguments bool isBool, std::string defValue, and std::string desc, as well as setting m_beenSet to false.

11.2.7 The Field struct

The Field struct is essentially a container to hold information about the field variables.

Member variables

• m_fielddef: a std::vector of shared pointers to FieldDefinitions objects. The FieldDefinitions struct describes the format of binary field data, and contains parameters including the element shape type, the basis used and its order, and the field variable names.
• m_data: a std::vector of std::vector<double>s used to hold the field data.
• m_exp: a std::vector of shared pointers to ExpList objects. The ExpList classes represent the expansion over the whole domain.
• m_variables: a std::vector of std::strings that holds field variable names.
• m_numHomogeneousDir: an int that holds the number of homogeneous directions.
• m_declareExpansionAsContField: a bool that sets the expansion to be continuous, corresponding to the ContField derived classes of ExpList.
• m_declareExpansionAsDisContField: a bool that sets the expansion to be discontinuous, corresponding to the DisContField derived classes of ExpList.
• m_requireBoundaryExpansion: a bool that determines whether the expansion is needed on the boundaries.
• m_useFFT: a bool that determines whether to use a fast Fourier transform.
• m_comm: a shared pointer to a Comm object that contains the MPI communicator.
• m_session: a shared pointer to a SessionReader object, which stores information given in an XML session file.
• m_graph: a shared pointer to a MeshGraph object, which stores the mesh.
• m_inputfiles: a std::map with the key being a std::string holding the file type, and the value being a std::vector of std::strings holding the names of the files with this type.
• m_writeBndFld: a bool that determines if the field is written on the boundary.
• m_bndRegionsToWrite: a std::vector of unsigned ints that dictates which boundaries to write.
• m_addNormals: a bool that determines whether surface normals are output.
• m_fieldPts: a shared pointer to a PtsField object.
• m_fieldMetaDataMap: a shared pointer to a FieldMetaDataMap object, which stores field metadata.
• m_fld (private): a std::map with the key being a std::string holding a file type and the value being a shared pointer to a FieldIO object for this file type. The FieldIO class is used for file input/output.

Member functions

• SetUpFirstExpList(int NumHomogeneousDir, bool fldfilegiven = false) returns a shared pointer to an ExpList object based on m_session, m_graph, and m_fielddef.
• FieldIOForFile(std::string filename) constructs a shared pointer to a FieldIO object for the file named filename if there does not already exist an entry in m_fld corresponding to its file type. If one does exist, it is simply returned.
• AppendExpList(int NumHomogeneousDir, std::string var = "DefaultVar", bool NewField = false) returns a shared pointer to an ExpList object based on m_session, m_graph, m_fielddef, and m_exp[0].
• ClearField() empties m_session, m_graph, fieldPts, m_exp, m_fielddef, m_data, and m_variables.
• CreateExp(boost::program_options::variables_map &vm, bool newExp) populated m_exp. If newExp is true, the expansion is created from scratch; if false, it is updated with new field data.
• SetUpExp(boost::program_options::variables_map &vm) determines whether m_exp needs to be populated by calling CreateExp, and if so, whether it needs to be created from scratch, or just updated with new field data.