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.
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
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
What follows is detailed description of the member variables and functions of Module,
InputModule, ProcessModule, and OutputModule.
- m_f: a FieldSharedPtr.
- m_config (protected): a std::map<std::string, ConfigOption> used to store
the configuration option for the module.
- 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
- 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.
- m_allowedFiles (protected): std::set<std::string> describing the file types
that are compatible with the module.
- 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.
- The default constructor does nothing.
- A constructor takes as an argument a FieldSharedPtr and does nothing.
- m_fldFile (protected): a std::ofstream corresponding with the file that data
will be output to.
- 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
This struct is defined
Module.h. It represents the properties of a module option.
- 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.
- 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
The Field struct is essentially a container to hold information about the field 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.
- SetUpFirstExpList(int NumHomogeneousDir, bool fldfilegiven = false)
returns a shared pointer to an ExpList object based on m_session, m_graph, and
- 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.
- 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.