Nektar++
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
SessionReader.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////////
2 //
3 // File SessionReader.h
4 //
5 // For more information, please see: http://www.nektar.info
6 //
7 // The MIT License
8 //
9 // Copyright (c) 2006 Division of Applied Mathematics, Brown University (USA),
10 // Department of Aeronautics, Imperial College London (UK), and Scientific
11 // Computing and Imaging Institute, University of Utah (USA).
12 //
13 // License for the specific language governing rights and limitations under
14 // Permission is hereby granted, free of charge, to any person obtaining a
15 // copy of this software and associated documentation files (the "Software"),
16 // to deal in the Software without restriction, including without limitation
17 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
18 // and/or sell copies of the Software, and to permit persons to whom the
19 // Software is furnished to do so, subject to the following conditions:
20 //
21 // The above copyright notice and this permission notice shall be included
22 // in all copies or substantial portions of the Software.
23 //
24 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
25 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
27 // THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
29 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
30 // DEALINGS IN THE SOFTWARE.
31 //
32 // Description:
33 //
34 ///////////////////////////////////////////////////////////////////////////////
35 
36 #ifndef NEKTAR_LIB_UTILITIES_SESSIONREADER_H
37 #define NEKTAR_LIB_UTILITIES_SESSIONREADER_H
38 
39 #include <map>
40 #include <string>
41 
46 
47 #include <boost/algorithm/string.hpp>
48 #include <boost/enable_shared_from_this.hpp>
49 #include <boost/program_options/variables_map.hpp>
50 
51 class TiXmlElement;
52 class TiXmlDocument;
53 
54 namespace Nektar
55 {
56  namespace LibUtilities
57  {
58  typedef std::map<std::string, std::string> SolverInfoMap;
59  typedef std::map<std::string, NekDouble> ParameterMap;
60  typedef std::map<std::string, std::string> GeometricInfoMap;
61  typedef std::map<std::string, std::string> ExpressionMap;
62  typedef std::vector<std::string> VariableList;
63  typedef std::map<std::string, std::string> TagMap;
64  typedef std::map<std::string, std::string> FilterParams;
65  typedef std::vector<
66  std::pair<std::string, FilterParams> > FilterMap;
67 
68  struct CmdLineArg
69  {
70  std::string shortName;
71  std::string description;
72  bool isFlag;
73  };
74 
75  typedef std::map<std::string, CmdLineArg> CmdLineArgMap;
76 
77  typedef std::map<std::string, int> EnumMap;
78  typedef std::map<std::string, EnumMap> EnumMapList;
79 
80  typedef std::map<std::string, std::string> GloSysInfoMap;
81  typedef std::map<std::string, GloSysInfoMap> GloSysSolnInfoList;
82 
83  typedef std::map<std::string, std::string> GloSysInfoMap;
84  typedef std::map<std::string, GloSysInfoMap> GloSysSolnInfoList;
85 
87  {
92  };
93  const char* const FunctionTypeMap[] =
94  {
95  "No Function type",
96  "Expression",
97  "File"
98  };
99 
100  class Equation;
101  typedef boost::shared_ptr<Equation> EquationSharedPtr;
102 
103  typedef std::map<int, std::vector<unsigned int> > CompositeOrdering;
104  typedef std::map<int, std::vector<unsigned int> > BndRegionOrdering;
105 
107  {
109  std::string m_filename;
111  std::string m_fileVariable;
112  };
113 
114  typedef std::map<std::pair<std::string,int>, FunctionVariableDefinition>
116  typedef std::map<std::string, FunctionVariableMap >
118 
119  class SessionReader;
120  typedef boost::shared_ptr<SessionReader> SessionReaderSharedPtr;
121 
122  /// Reads and parses information from a Nektar++ XML session file.
123  class SessionReader :
124  public boost::enable_shared_from_this<SessionReader>
125  {
126  public:
127  /// Support creation through MemoryManager.
129 
130  /**
131  * @brief Creates an instance of the SessionReader class.
132  *
133  * This function should be used by an application to instantiate the
134  * session reader. It should be called at the very beginning of the
135  * application before any other processing of command-line
136  * arguments. After instantiating the class and setting up any
137  * parallel communication, it also calls the main initialisation
138  * of the object.
139  */
141  int argc, char *argv[])
142  {
144  LibUtilities::SessionReader>::AllocateSharedPtr(argc, argv);
145  p->InitSession();
146  return p;
147  }
148 
149  /**
150  * @brief Creates an instance of the SessionReader class initialised
151  * using a separate list of XML documents.
152  *
153  * This function should be used by an application to instantiate the
154  * session reader. It may be called after processing of command-line
155  * arguments. After instantiating the class and setting up any
156  * parallel communication, it also calls the main initialisation
157  * of the object.
158  */
160  int argc,
161  char *argv[],
162  std::vector<std::string> &pFilenames,
163  const CommSharedPtr &pComm = CommSharedPtr())
164  {
167  ::AllocateSharedPtr(argc, argv, pFilenames, pComm);
168  p->InitSession();
169  return p;
170  }
171 
173  int argc,
174  char *argv[],
175  const std::vector<std::string> &pFilenames,
176  const CommSharedPtr &pComm);
177 
178  /// Destructor
180 
181  /// Provides direct access to the TiXmlDocument object.
182  LIB_UTILITIES_EXPORT TiXmlDocument &GetDocument();
183  /// Provides direct access to the TiXmlElement specified.
184  LIB_UTILITIES_EXPORT TiXmlElement *GetElement(
185  const std::string& pPath);
186  /// Tests if a specified element is defined in the XML document.
188  const std::string& pPath) const;
189  /// Returns the filename of the loaded XML document.
190  LIB_UTILITIES_EXPORT const std::vector<std::string>
191  &GetFilenames() const;
192  /// Returns the session name of the loaded XML document.
193  LIB_UTILITIES_EXPORT const std::string &GetSessionName() const;
194  /// Returns the session name with process rank
195  LIB_UTILITIES_EXPORT const std::string GetSessionNameRank() const;
196  /// Returns the communication object.
198  /// Finalises the session.
200 
201  /* ------ PARAMETERS --------*/
202  /// Checks if a parameter is specified in the XML document.
204  const std::string &name) const;
205  /// Returns the value of the specified parameter.
207  const std::string &pName) const;
208  /// Load an integer parameter
210  const std::string &name,
211  int &var) const;
212  /// Check for and load an integer parameter.
214  const std::string &name,
215  int &var,
216  const int &def) const;
217  /// Load a double precision parameter
219  const std::string &name,
220  NekDouble &var) const;
221  /// Check for and load a double-precision parameter.
223  const std::string &name,
224  NekDouble &var,
225  const NekDouble &def) const;
226  /// Set an integer parameter
228  const std::string &name,
229  int &var);
230  /// Set a double precision parameter
232  const std::string &name,
233  NekDouble &var);
234 
235 
236  /* ------ SOLVER INFO ------ */
237  /// Checks if a solver info property is specified.
239  const std::string &name) const;
240  /// Returns the value of the specified solver info property.
241  LIB_UTILITIES_EXPORT const std::string& GetSolverInfo(
242  const std::string &pProperty) const;
243  /// Sets the value of the specified solver info property.
245  const std::string &pProperty, const std::string &pValue);
246  /// Returns the value of the specified solver info property as enum
247  template<typename T>
248  inline const T GetSolverInfoAsEnum(const std::string &pName) const;
249  /// Returns the value of the specified property and value as enum
250  template<typename T>
251  inline const T GetValueAsEnum(const std::string &pName,
252  const std::string &vValue) const;
253  /// Check for and load a solver info property.
255  const std::string &name,
256  std::string &var,
257  const std::string &def = "") const;
258  /// Check if the value of a solver info property matches.
260  const std::string &name,
261  const std::string &trueval,
262  bool &var,
263  const bool &def = false) const;
264  /// Check if the value of a solver info property matches.
266  const std::string &name,
267  const std::string &trueval) const;
268  /// Check if the value of a solver info property matches.
269  template<typename T>
270  inline bool MatchSolverInfoAsEnum(
271  const std::string &name,
272  const T &trueval) const;
273  /// Registers an enumeration value.
274  LIB_UTILITIES_EXPORT inline static std::string RegisterEnumValue(
275  std::string pEnum,
276  std::string pString,
277  int pEnumValue);
278  /// Registers the default string value of a solver info property.
279  LIB_UTILITIES_EXPORT inline static std::string
281  const std::string &pName,
282  const std::string &pValue);
283 
284  /* ----GlobalSysSolnInfo ----- */
285 
287  const std::string &variable,
288  const std::string &property) const;
289 
290  LIB_UTILITIES_EXPORT const std::string& GetGlobalSysSolnInfo(
291  const std::string &variable,
292  const std::string &property) const;
293 
294 
295  /* ------ GEOMETRIC INFO ------ */
296  /// Checks if a geometric info property is defined.
298  const std::string &name) const;
299  /// Checks for and load a geometric info string property.
301  const std::string &name,
302  std::string &var,
303  const std::string &def = "") const;
304  /// Checks for and loads a geometric info boolean property.
306  const std::string &name,
307  bool &var,
308  const bool &def = false) const;
309  /// Checks for and loads a geometric info double-precision property.
311  const std::string &name,
312  NekDouble &var,
313  const NekDouble &def = 0.0) const;
314  /// Check if the value of a geometric info string property matches.
316  const std::string &name,
317  const std::string &trueval,
318  bool &var,
319  const bool &def = false) const;
320 
321  /* ------ VARIABLES ------ */
322  /// Returns the name of the variable specified by the given index.
323  LIB_UTILITIES_EXPORT const std::string& GetVariable(
324  const unsigned int &idx) const;
326  const unsigned int &idx,
327  std::string newname);
328 
329  /// Returns the names of all variables.
330  LIB_UTILITIES_EXPORT std::vector<std::string> GetVariables() const;
331 
332  /* ------ FUNCTIONS ------*/
333  /// Checks if a specified function is defined in the XML document.
335  const std::string &name) const;
336  /// Checks if a specified function has a given variable defined.
338  const std::string &name,
339  const std::string &variable,
340  const int pDomain = 0) const;
341  /// Returns an EquationSharedPtr to a given function variable.
343  const std::string &name,
344  const std::string &variable,
345  const int pDomain = 0) const;
346  /// Returns an EquationSharedPtr to a given function variable index.
348  const std::string &name,
349  const unsigned int &var,
350  const int pDomain = 0) const;
351  /// Returns the type of a given function variable.
353  const std::string &name,
354  const std::string &variable,
355  const int pDomain = 0) const;
356  /// Returns the type of a given function variable index.
358  const std::string &pName,
359  const unsigned int &pVar,
360  const int pDomain = 0) const;
361  /// Returns the filename to be loaded for a given variable.
363  const std::string &name,
364  const std::string &variable,
365  const int pDomain = 0) const;
366  /// Returns the filename to be loaded for a given variable index.
368  const std::string &name,
369  const unsigned int &var,
370  const int pDomain = 0) const;
371  /// Returns the filename variable to be loaded for a given variable
372  /// index.
374  const std::string &name,
375  const std::string &variable,
376  const int pDomain = 0) const;
377 
378  /// Returns the instance of AnalyticExpressionEvaluator specific to
379  /// this session.
382 
383  /* ------ TAGS ------ */
384  /// Checks if a specified tag is defined.
386  const std::string& pName) const;
387  /// Sets a specified tag.
389  const std::string& pName,
390  const std::string& pValue);
391  /// Returns the value of a specified tag.
392  LIB_UTILITIES_EXPORT const std::string &GetTag(
393  const std::string& pName) const;
394 
395  /* ------ FILTERS ------ */
397 
398  /* ------ CMDLINE ARGUMENTS ------- */
399  /// Checks if a specified cmdline argument has been given.
401  const std::string& pName) const;
402  /// Retrieves a command-line argument value.
403  template <typename T>
405  const std::string& pName) const
406  {
407  return m_cmdLineOptions.find(pName)->second.as<T>();
408  }
409  /// Registers a command-line argument with the session reader.
410  LIB_UTILITIES_EXPORT inline static std::string
412  const std::string &pName,
413  const std::string &pShortName,
414  const std::string &pDescription);
415  /// Registers a command-line flag with the session reader.
416  LIB_UTILITIES_EXPORT inline static std::string
418  const std::string &pName,
419  const std::string &pShortName,
420  const std::string &pDescription);
421 
422  /// Substitutes expressions defined in the XML document.
423  LIB_UTILITIES_EXPORT void SubstituteExpressions(std::string &expr);
426 
428 
429  private:
430  boost::program_options::variables_map m_cmdLineOptions;
431 
432  /// Communication object.
434  /// Filenames
435  std::vector<std::string> m_filenames;
436  /// Session name of the loaded XML document (filename minus ext).
437  std::string m_sessionName;
438  /// Pointer to the loaded XML document.
439  TiXmlDocument* m_xmlDoc;
440  /// Parameters.
442  /// Solver information properties.
444  /// Geometric information properties.
446  /// Expressions.
448  /// Analytic expression evaluator instance.
450  /// Functions.
452  /// Variables.
454  /// Custom tags.
456  /// Filters map.
458  /// Be verbose
459  bool m_verbose;
460  /// Map of original composite ordering for parallel periodic bcs.
462  /// Map of original boundary region ordering for parallel periodic
463  /// bcs.
465  /// String to enumeration map for Solver Info parameters.
467  /// Default solver info options.
469  /// GlobalSysSoln Info map.
471  /// CmdLine argument map.
473 
474  /// Main constructor
476  int argc,
477  char *argv[]);
478 
480 
481  /// Returns a shared pointer to the current object.
483 
484  /// Parse the program arguments and fill #m_cmdLineOptions
485  std::vector<std::string> ParseCommandLineArguments(
486  int argc, char *argv[]);
487 
488  /// Parse the session name.
489  std::string ParseSessionName(std::vector<std::string> &filenames);
490 
491  /// Loads an xml file into a tinyxml doc and decompresses if needed
493  const std::string &pFilename,
494  TiXmlDocument* pDoc) const;
495  /// Creates an XML document from a list of input files.
496  LIB_UTILITIES_EXPORT TiXmlDocument *MergeDoc(
497  const std::vector<std::string> &pFilenames) const;
498  /// Loads and parses the specified file.
500  /// Loads the given XML document and instantiates an appropriate
501  /// communication object.
503  int &argc,
504  char* argv[]);
505 
506  /// Partitions the mesh when running in parallel.
508  /// Partitions the comm object based on session parameters.
510 
511  /// Reads the PARAMETERS section of the XML document.
512  LIB_UTILITIES_EXPORT void ReadParameters(TiXmlElement *conditions);
513  /// Reads the SOLVERINFO section of the XML document.
514  LIB_UTILITIES_EXPORT void ReadSolverInfo(TiXmlElement *conditions);
515  /// Reads the GLOBALSYSSOLNINFO section of the XML document.
517  TiXmlElement *conditions);
518  /// Reads the EXPRESSIONS section of the XML document.
519  LIB_UTILITIES_EXPORT void ReadExpressions(TiXmlElement *conditions);
520  /// Reads the VARIABLES section of the XML document.
521  LIB_UTILITIES_EXPORT void ReadVariables(TiXmlElement *conditions);
522  /// Reads the FUNCTIONS section of the XML document.
523  LIB_UTILITIES_EXPORT void ReadFunctions(TiXmlElement *conditions);
524  /// Reads the FILTERS section of the XML document.
525  LIB_UTILITIES_EXPORT void ReadFilters(TiXmlElement *filters);
526  /// Enforce parameters from command line arguments.
528 
529  /// Parse a string in the form lhs = rhs.
531  const std::string &line,
532  std::string &lhs,
533  std::string &rhs);
534  };
535 
536 
537  /**
538  *
539  */
540  template<typename T>
542  const std::string &name, const T &trueval) const
543  {
544  return (GetSolverInfoAsEnum<T>(name) == trueval);
545  }
546 
547 
548  /**
549  *
550  */
551  template<typename T>
553  const std::string &pName) const
554  {
555  std::string vName = boost::to_upper_copy(pName);
557  "Solver info '" + pName + "' not defined.");
558 
559  std::string vValue = GetSolverInfo(vName);
561  ASSERTL0((x = GetSolverInfoEnums().find(vName)) !=
562  GetSolverInfoEnums().end(),
563  "Enum for SolverInfo property '" + pName + "' not found.");
564 
566  ASSERTL0((y = x->second.find(vValue)) != x->second.end(),
567  "Value of SolverInfo property '" + pName +
568  "' is invalid.");
569 
570  return T(y->second);
571  }
572 
573 
574 
575  /**
576  *
577  */
578  template<typename T>
580  const std::string &pName,
581  const std::string &pValue) const
582  {
583  std::string vName = boost::to_upper_copy(pName);
584 
586  ASSERTL0((x = GetSolverInfoEnums().find(vName)) !=
587  GetSolverInfoEnums().end(),
588  "Enum for property '" + pName + "' not found.");
589 
591  ASSERTL0((y = x->second.find(pValue)) != x->second.end(),
592  "Value of property '" + pValue + "' is invalid.");
593  return T(y->second);
594  }
595 
596 
597 
598  /**
599  * A set of valid values for a given solver info property may be
600  * registered using this function. It must be called statically during
601  * the initialisation of a static variable. For example:
602  *
603  * @code
604  * std::string GlobalLinSys::lookupIds[2] = {
605  * LibUtilities::SessionReader::RegisterEnumValue(
606  * "GlobalSysSoln",
607  * "DirectFull",
608  * MultiRegions::eDirectFullMatrix),
609  * LibUtilities::SessionReader::RegisterEnumValue(
610  * "GlobalSysSoln",
611  * "DirectStaticCond",
612  * MultiRegions::eDirectStaticCond)
613  * }
614  * @endcode
615  *
616  * @param pEnum The name of the property.
617  * @param pString A valid value for the property.
618  * @param pEnumValue An enumeration value corresponding to this
619  * value.
620  *
621  * @return The value for the property provided by #pString.
622  */
624  std::string pEnum, std::string pString, int pEnumValue)
625  {
626  std::string vEnum = boost::to_upper_copy(pEnum);
628  if ((x = GetSolverInfoEnums().find(vEnum)) ==
629  GetSolverInfoEnums().end())
630  {
631  GetSolverInfoEnums()[vEnum] = EnumMap();
632  x = GetSolverInfoEnums().find(vEnum);
633  }
634  x->second[pString] = pEnumValue;
635  return pString;
636  }
637 
638 
639  /**
640  * A default value for a given solver info property may be registered
641  * using this function. The property will take this value until it is
642  * overwritten by a value specified in the XML document, or specified
643  * as a command-line argument. Usage has the form:
644  *
645  * @code
646  * std::string GlobalLinSys::def
647  * = LibUtilities::SessionReader::RegisterDefaultSolverInfo(
648  * "GlobalSysSoln","DirectMultiLevelStaticCond");
649  * @endcode
650  *
651  * @param pName The name of the property.
652  * @param pValue The default value of the property.
653  *
654  * @return The default value of the property provided by #pValue.
655  */
657  const std::string &pName,
658  const std::string &pValue)
659  {
660  std::string vName = boost::to_upper_copy(pName);
661  GetSolverInfoDefaults()[vName] = pValue;
662  return pValue;
663  }
664 
665 
666  /**
667  *
668  */
670  const std::string &pName,
671  const std::string &pShortName,
672  const std::string &pDescription)
673  {
674  ASSERTL0(!pName.empty(), "Empty name for cmdline argument.");
675  CmdLineArg x;
676  x.shortName = pShortName;
677  x.description = pDescription;
678  x.isFlag = false;
679  GetCmdLineArgMap()[pName] = x;
680  return pName;
681  }
682 
683 
684  /**
685  *
686  */
688  const std::string &pName,
689  const std::string &pShortName,
690  const std::string &pDescription)
691  {
692  ASSERTL0(!pName.empty(), "Empty name for cmdline argument.");
693  CmdLineArg x;
694  x.shortName = pShortName;
695  x.description = pDescription;
696  x.isFlag = true;
697  GetCmdLineArgMap()[pName] = x;
698  return pName;
699  }
700 
701 
702  /**
703  * This allows a member function to pass a shared pointer to itself
704  * during a call to another function.
705  */
707  {
708  return shared_from_this();
709  }
710  }
711 }
712 
713 #endif
714