III.1.1.10 Attaching “XDB” files to a Nastran DataBase

Since version 3.4.0, FeResPost allows a random access to XDB result files. This method is more efficient than the methods that import XDB Results into the DataBase, and extracting copies of these Results. A peculiar case in which the random access methods will be more efficient is when only some small parts of the XDB file are of interest to the programmer.

The principle of random access is the same as the attachment of XDB files to a Patran DataBase:

• The XDB file is attached to the DataBase.
• Its content (lists of load cases, sub-cases and Results) is identified.
• The Results that are needed are then read from the file.

The different methods called to perform these operations are described in the following sub-sections. These methods correspond more or less to the methods described in section III.1.1.9.

III.1.1.10.1 Managing XDB file attachments

The method “attachXdb” is used to attach an XDB file to the Nastran DataBase. This method has up to two arguments:

1.

The first argument is a String containing the name of the XDB file. (Full path name must be provided.)

2.

The second argument is an optional Boolean parameter specifying whether the endianness must be swapped when XDB file content is read. If the parameter is not given, the endianness of the file is automatically detected. Note however that this check might fail. (See also page 758 for more information.)

Several other methods are used to manage the Xdb attachments to a DataBase:

• “detachXdb” is used to delete an XDB attachment. The method has one String argument corresponding to the name of the XDB file.
• “removeAllAttachments” removes all the XDB file attachments to a DataBase. This method has no argument.
• “getNbrAttachments” has no argument and returns the number of XDB files attached to the DataBase.
• “getAttachmentNames” has no argument and returns an Array of Strings containing the list of XDB files attached to the DataBase.
• “checkAttachmentExists” has one String argument containing the XDB file name, and returns “True” if the XDB file is Attached to the DataBase, and “False” otherwise.

III.1.1.10.2 Extracting information of XDB file attachments

The following methods extract information related to the Results stored in an XDB file attached to the DataBase:

• “getAttachmentWordsSize” returns the size of words in a specified XDB attachment. The size is given in bytes (4 or 8 bytes).
• “getAttachmentSwapEndianness” returns true if the reading of XDB binary data involves a swap of words endianness, and false otherwise. (A swap of endianness is required when the endian convention of the machine on which Nastran solver has been run differs from the endianness of the machine on which XDB file is read.)
• “getAttachmentLcInfos” returns information on load cases and sub-cases of Results found in the attached XDB file. The information is returned in an Array. (More information about the content of this Array is given in the description of method “getXdbLcInfos”. page 755.)
• “getAttachmentNbrLoadCases” returns the number of load cases found in an XDB file.
• “getAttachmentLcNames” returns an Array of Strings corresponding to the load case names found in the XDB file.
• “getAttachmentLcScNames” returns an Array containing two elements. The first element is an Array of String containing the load case names found in the XDB file. The second element is an Array of String containing the sub-case names found in the XDB file.
• “getAttachmentLcScResNames” returns an Array of three elements. Each element is an Array of Strings. The first element is the list of load case names. The second element is the list of sub-case names. The last element is the list of Result names.

All these methods have a single String argument containing the name of the XDB file that must have been previously attached to the DataBase. On the other hand, the following methods have one or two arguments:

• “getAttachmentNbrSubCases” returns the number of sub-cases found in an XDB file.
• “getAttachmentScNames” returns an Array of Strings corresponding to the sub-case names found in the XDB file.
• “getAttachmentNbrResults” returns the number of Result names identified in the XDB attached file.
• “getAttachmentResIds” returns an Array of Integers corresponding to the identifiers of the Results found in the XDB file.
• “getAttachmentResNames” returns an Array of Strings corresponding to the names of the Results found in the XDB file.

The first argument is the name of the XDB file that must have been previously attached to the DataBase. The second argument is optional and corresponds to the name of a load case found in the attached XDB file. If the argument is not provided, all the load cases are investigated to build the list of sub-cases or Result names or IDs. If the argument is provided, only the sub-cases or Results of the corresponding load case are considered. If the provided load case does not exist in XDB attachment an error message is issued.

III.1.1.10.3 Extracting Results From XDB file attachments

The method “getAttachmentResults” is used to read Results from the XDB file. The Results are directly returned by the method to the caller in a Hash object. They are not inserted in the DataBase from which the method is called.

The method has minimum four arguments:

1.

A String corresponding to the name of XDB file attachment from which Results are read. (This file must have been previously attached to the DataBase.)

2.

A String corresponding to the name of the load case for which Results are read.

3.

A String or an Array of Strings corresponding to the names of sub-cases for which Results are read.

4.

A String or an Array of Strings corresponding to the names of Results for which Results are read.

The other arguments are optional and correspond to the specification of target entities for which Results are read. Actually, the reading operation from an XDB combines the reading and some of the extraction operations described in section I.4.3. For example:

• The fifth argument can be a ResKeyList object. Then the Results are extracted on the keys of the ResKeyList object.
• The fifth argument can be a Result object. Then the Results are extracted on the keys of the Result object.
• Extractions can be performed on Groups. Then one specifies the target by a “Method” String argument and a “GrpTarget” Group argument. The possible values of the “Method” argument are listed in Table I.4.6 of section I.4.3.1. (Description of “extractResultOnEntities” method in the Result class.) When Results are extracted on Groups, one can also specify a list of layers for which values are extracted. This argument is optional. (See below.)
• One can also specify a list of layers by providing a parameter which is an Array of String or Integer values. Note however that the filtering on layers is done only when Results for which several layers can be read. For example, this parameter does not influence the reading of MPC Forces, Shell Forces...
• One can also specify a list of sub-layers by providing a parameter which is an Array of String or Integer values. Note that this last parameter influences only the reading of laminate stresses or strains. The reading of solid or shell element stresses and strains is not affected by this parameter.

If only four parameters are provided in the call to “getAttachmentResults” method, all the pairs of key-values found in the XDB file are inserted in the list of returned Results.

Only lists below the list of valid calls to “getAttachmentResults”:

When Results are extracted from an XDB attachment on a Group, the “Method” argument may influence the efficiency of Results extraction. When possible, a real random access is performed, otherwise, entire tables must be read to ensure that all eligible Result values are loaded. For example:

• For element Results like element stresses or element forces the “Elements”, “ElemCenters”, “ElemCorners”, “ElemNodes”, “MPCs” and “MPCNodes” extraction methods allow the use of a random access algorithm. On the other hand, the “Nodes” and “NodesOnly” methods are associated to an algorithm that sweeps sequentially the entire corresponding Result tables of XDB file.
• For nodal Results, the efficient extraction methods are “Nodes”, “ElemNodes”, “MPCNodes” and “NodesOnly”. They allow the use of a random access algorithm for the extraction of values from each suitable table.

It is the responsibility of the post-processing programmer to try to provide the arguments in order to select the most efficient algorithm for Results extraction.

Note that “Grid Point Forces” are always sorted by nodes. This is true for the applied loads, the MPC/SPC forces and moments, as well as for the internal forces and moments. (Even though these last contain forces by elements and nodes.) This mean that for the selection of extraction algorithm, “Grid Point Forces” should always be considered as nodal Results.

As several Result types, and sub-case names can be given as argument to “getAttachmentResults” method, this method can return several Results. This is why Results are returned in a Hash:

• The Hash keys are Array of three Strings corresponding to the name of the load case, the name of the sub-case, and the Result type name respectively.
• The Hash values are the Results.

For example, the list of extracted Result sizes can be printed with the following statements:

The method “getAttachmentResultsCombili” is used to extract linear combinations of elementary Results found in one or several XDB files. As for method “getAttachmentResults” the Results are directly returned by the method to the caller. They are not inserted in the DataBase from which the method is called. This method is more or less a combination of the methods “getAttachmentResults” and “buildLoadCasesCombili” of the generic DataBase class.

Practically, the main difference between “getAttachmentResults” and “getAttachmentResultsCombili” is that the first argument is no longer an Xdb file name. This argument is removed. Instead, one provides a “Combili” argument that describes the linear combination corresponding to extracted Results. This “Combili” argument is the second argument. The first argument is the “LcName” argument corresponding to the load case name attributed to the generated Results. This load case name is unsupposed to correspond to any load case name found in the attached XDB file(s).

The method has minimum four arguments:

1.

A String corresponding to the name of the load case for which Results are read.

2.

A “Combili” Array containing the description of the linear combination of elementary load case Results. The Array is an Array of Arrays. Each secondary Array contains three elements:

• A Real value corresponding to the factor in the linear combination.
• A String corresponding to the name of the XDB file from which elementary Results are read. This file must have been previously attached to the Nastran DataBase.
• A String corresponding to the name of the load case for which Results are extracted.

3.

A String or an Array of Strings corresponding to the names of sub-cases for which Results are read.

4.

A String or an Array of Strings corresponding to the names of Results for which Results are read.

The other arguments are optional and correspond to the specification of target entities for which Results are read. Actually, the reading operation from an XDB combines the reading and some of the extraction operations described in section I.4.3. For example:

• The fifth argument can be a ResKeyList object. Then the Results are extracted on the keys of the ResKeyList object.
• The fifth argument can be a Result object. Then the Results are extracted on the keys of the Result object.
• Extractions can be performed on Groups. Then one specifies the target by a “Method” String argument and a “GrpTarget” Group argument. The possible values of the “Method” argument are listed in section I.4.3.1. (Description of “extractResultOnEntities” method in the Result class.) When Results are extracted on Groups, one can also specify a list of layers for which values are extracted. This argument is optional. (See below.)
• One can also specify a list of layers by providing a parameter which is an Array of String or Integer values.

If only four parameters are provided in the call to “getAttachmentResultsCombili” method, all the pairs of key-values found in the XDB file are inserted in the returned Results.

Only lists below the list of valid calls to “getAttachmentResultsCombili”:

The Hash object returned by the method has a structure identical to the one returned by “getAttachmentResults” and can be manipulated the same way.

III.1.1.10.4 Importing Results From XDB file attachments

The method “importAttachmentResults” is used to read Results from the XDB file. Instead of being returned to the caller in a Hash object, the results are imported into the list of results stored into the Nastran DataBase. The method has four arguments:

III.1.1.10.5 Getting optimization data from XDB

It is possible to obtain some of the Nastran optimization (SOL200) results from an XDB attachment. Four methods have been defined in NastranDb class:

1.

“getAttachmentDesVarHistory” returns the history of design variables and has three parameters:

• “xdbFileName”, a String corresponding to the name of the attached XDB file.
• “iSteps”, an Array of integers corresponding to the list of steps for which one wishes to obtain results.
• “iDesVarIds”, an array of integers corresponding to the list of design variable IDs for which one wishes to obtained the results.

Parameters 2 and 3 are optional and can be omitted or replaced by a “nil” argument or a void Array. If they are not defined, all the steps or design variables are returned in the results. The method returns a N*3 array. For each line, the three columns correspond to:

• The first element is an integer corresponding to the optimization step ID.
• The second element is an integer corresponding to identifier of the design variable.
• The third element is a float containing the design variable value.

2.

“getAttachmentConstrDefinitions” returns the definition of constraints and has two arguments:

• “xdbFileName”, a String corresponding to the name of the attached XDB file.
• “iConstrIds”, an array of integers corresponding to the list of constrain IDs.

Parameters 2 is optional and can be omitted or replaced by a “nil” argument. The method returns a N*6 array. For each line, the three columns correspond to:

• The first element is an integer corresponding to an internal ID for the considered constrain equation.
• The second element is an integer, the Nastran Design Constrain ID.
• The third element is an integer corresponding to the internal response ID.
• The fourth element is an integer corresponding to RTYPE. (I dot not know what is is.)
• The fifth element is an integer corresponding to the LUFLAG. Its value is 1 or 2 (">" or ">").
• The sixth element is a float corresponding to the bound.

3.

“getAttachmentConstrHistory” returns the history of constrains and has three parameters:

• “xdbFileName”, a String corresponding to the name of the attached XDB file.
• “iSteps”, an Array of integers corresponding to the list of steps for which one wishes to obtain results.
• “iIRIds”, an array of integers corresponding to the list of internal response IDs for which one wishes to obtained the results.

Parameters 2 and 3 are optional and can be omitted or replaced by a “nil” argument. If they are not defined, all the steps or design responses are returned in the results. The method returns a N*3 array. For each line, the three columns correspond to:

• The first element is an integer corresponding to the optimization step ID.
• The second element is an integer corresponding to identifier of the design response.
• The third element is a float containing the design response value.

4.

“getAttachmentObjectiveHistory” returns the history of constrains and has two parameters:

• “xdbFileName”, a String corresponding to the name of the attached XDB file.
• “iSteps”, an Array of integers corresponding to the list of steps for which one wishes to obtain results.

Parameter 2 is optional and can be omitted or replaced by a “nil” argument. If it is not defined, all the steps are returned in the results. The method returns a N*3 array. For each line, the three columns correspond to:

• The first element is an integer corresponding to the optimization step ID.
• The second element is a float corresponding to the value of objective.
• The third element is an integer containing the identifier of an internal response.
• The fourth element is a float containing the value of the maximum constraint equation (corresponding to the previous internal response).

5.

“getAttachmentDesRespHistory” returns the history of design responses and has three parameters:

• “xdbFileName”, a String corresponding to the name of the attached XDB file.
• “iSteps”, an Array of integers corresponding to the list of steps for which one wishes to obtain results.
• “iDesRespIds”, an array of integers corresponding to the list of design responses IDs for which one wishes to obtained the results.

Parameters 2 and 3 are optional and can be omitted or replaced by a “nil” argument. If they are not defined, all the steps or design variables are returned in the results. The method returns a N*3 array. For each line, the three columns correspond to:

• The first element is an integer corresponding to the optimization step ID.
• The second element is an integer corresponding to identifier of the design response.
• The third element is a float containing the design response value.

So far, the reading of optimization results is experimental and might be changed in future version.

III.1.1.10.6 Storage buffers for XDB result files random access

In order to reduce the number of accesses to disk, it may be useful to store some of the blocks read from binary result files into memory. FeResPost provides an algorithm that allows to store the blocks most recently read for later usage. Two singleton methods of the “NastranDb” class allow the to tune the capacity of the buffer area:

• “setStorageBufferMaxCapacity” sets the capacity of storage. The method has one arguments: a real value containing the size in Megabytes of the buffer.
• “getStorageBufferMaxCapacity” returns the storage buffer current total capacity. The returned value is a real that corresponds to the capacity in Megabytes of the buffer. The method has no argument.

Note that all buffers are now common to all the methods that provide random access to XDB result files. In particular, the method is used in management of the binary file access for XDB attachment or reading. This means that if one Result file attached to one DataBase is more used, the storage will contain a majority of buffers for this Result file and progressively delete the other buffers.

The default capacity for storage buffer is 0Mb. Note that the two methods described above can be called from any class derived from the generic “DataBase” class.

III.1.1.10.7 “Raw” access to XDB file content

So far, the XDB access methods that have been described allow the extraction of Results only when the corresponding programming has been done in FeResPost source code. Sometimes, this limitation can be frustrating. For that reason, several methods allowing a “low level” or “raw access” to XDB content have been added.

Before listing these methods, one gives some information about the XDB content:

1.

The XDB file is a binary file divided in pages. Each page has a fixed size specified by a given number of words. (This number of words per page is given in the file by the first word of the file.) A word may correspond to 4 or 8 bytes depending whether the XDB file is output in single or double precision.

2.

The XDB file contains different tables corresponding to finite element model, results,... A “dictionnary” allows to identify and retrieve the different tables stored in an XDB file. In FeResPost, each XDB table is identified with a “ String-Integer key”:

• The String corresponds to the type of the table. (For example “FBARR” for the Real CBAR element forces.)
• As several tables of the same type can be defined in an XDB file, FeResPost also uses an integer index that allows to retrieve the right one.

Each table contains fields that can be distributed into several pages. A field corresponds for example to the forces and moments on one CBAR element, and for a given load case and sub-case. The naming conventions for the table types are given in MSC.Access Manual [Nas05]. The dictionnary keys allow to retrieve information from the dictionnary that can be used to retrieve the table content. This information is given in an Array of 22 integers that correspond for example to

• The index of the first page containing the table,
• The index of the last page of the table,
• The size of the fields in the table (15th element of the table, or element of index 14 when the indices numbering starts with 0),
• The number of fields,
• The minimum and maximum key IDs,
• The number of pages of the table...

(For the reading operations, one generally needs the field size.) You may find more information on the meaning of these 22 integers in MSC.Access Manual [Nas05]. The access to dictionnary is done by calling “getAttachmentDictKeys” and “getAttachmentDictionnary” methods.

3.

When results associated to elements are read from an XDB file, the values are associated to a key that corresponds to the element ID. However, this integer does not correspond to the Nastran integer ID of the element. Instead, there is in the XDB file, an “EQEXINE” table that contains the correspondence between the XDB IDs and the Nastran element IDs:

• The first argument of the method is the Access element type which does not correspond to the Nastran element type. A table of correspondence between the XDB Access element types and Nastran element types is given in section “Differences from MSC.Nastran” (sub-section of “BLOCK DATA DESCRIPTIONS”) of the MSC.Access manual [Nas05]. Part of the Access element IDs is given in the source code in method “xdb::getAccessType” (File “NASTRAN/xdb/xdb_equiv.cpp”).
• The second argument of the method is the XDB element ID. For each type of element, Nastran generates a sequential XDB numbering starting at 1. The “EQEXINE” table allows to retrieve the corresponding Nastran element ID.

Method “getAttachmentElementExtId” allows to retrieve the Nastran element ID, if you know the type of the element, and its internal ID. The type of the element is the “MSC.Access Element Type” associated to XDB file format. The numbering of element types can be found in [Nas05].

4.

Similarly, the XDB file also contains an “EQEXING” table that allows to retrieve node information. The Access internal node ID numbering starts at 1 and is also sequential. Each node internal ID is associated to three “external” integers:

(a)

The Nastran “external” ID of the node that appears in the GRID card definition.

(b)

The node type is always “1” in the tests we have done. (We presume it corresponds to usual Nastran GRIDs.)

(c)

The Analysis Coordinate System of the GRID. This information is useful as it allows to associate the vectorial results components to a coordinate system.

Method “getAttachmentNodeInfo” is used to retrieve this information when reading nodal results.

The ‘NastranDb” class methods that give a “raw” access to XDB attachment content are:

• “getAttachmentElementExtId” that allows to retrieve an element external ID if one knows its “XDB type” and its “XDB internal ID”. The method has three arguments:

  1.

  A String containing the name of the attachment file,

  2.

  An integer corresponding to the XDB element type,

  3.

  An integer corresponding to the XDB internal ID of the element.

  The method returns the integer Nastran external ID.

• “getAttachmentNodeInfo” has two arguments corresponding to the attachment file name and the node XDB internal ID. It returns an Array of three integers corresponding to the external ID, type and ACID.
• “getAttachmentDictKeys” has one String argument corresponding the XDB file name. It returns an Array of two element Arrays. Each of these two element Arrays corresponds to a dictionnary key identified by a String and an integer ID. (See the explanation above.)
• “getAttachmentDictionnary” has one String argument corresponding the XDB file name. It returns a “Hash” object that associates dictionnary keys (Arrays of two elements, String and integer) to Arrays of 22 integer elements containing information on the corresponding table.
• “each_xdbRaw” is the iterator that allows to retrieve the information from an XDB table. Iterator “each_xdbRaw” has three arguments:

  1.

  A String containing the name of XDB file attachment.

  2.

  An Array of two elements (String and integer) corresponding to the dictionnary key ID, and identifying the table on which one iterates.

  3.

  A String that specifies the translation of the words that are read for each field. Each character of the String corresponds to translation of one word or the production of one value. The correspondence is as explained in Table III.1.3.

  An example of call to the iterator follows:

      db.each_xdbRaw(xdbFileName,["SUBCASES",0],"iiiiiiii") do |tab|  
          puts tab  
      end

  The reader must read the examples to better understand the use of this iterator. The examples are discussed in section IV.2.8.

• “each_xdbRaw” iterator works fine when the types into which XDB binary data are known a priori. This is not always the case however. Sometimes, the examination of data is needed to determine whether a parameter is a real or a string, or a parameter can be optional. Therefore, is can be interesting to separate the reading of binary data from its interpretation. Iterator “each_xdbBinRaw” iterates on an XDB table and returns each item in a String containing binary data. Iterator has two or three arguments:

  1.

  A String containing the name of XDB file attachment.

  2.

  An Array of two elements (String and integer) corresponding to the dictionnary key ID, and identifying the table on which one iterates.

  3.

  An optional Boolean “BAutoSwap” parameter specifying whether the iterator swaps the endianness if the the endianness of XDB file does not match the one of the machine on which FeResPost is run. The default value of this parameter is true.

  The interpreation of binary data is meant to be done by calling “binDataToValues” singleton method of NastranDb class defined below. An example of call to the iterator follows:

      db.each_xdbBinRaw(xdbFileName,["SUBCASES",0]) do |str|  
          ...  
      end

• NastranDb class also defines the “binDataToValues”singleton method for interpretation of binary data produced by “each_xdbBinRaw” iterator. The method has four arguments:

  1.

  A String containing the binary data.

  2.

  An integer corresponding to the size of words in bytes (4 or 8 bytes per word).

  3.

  A String specifying how binary data are translated into VALUES. Each character of the String corresponds to translation of one word or the production of one value. The correspondence is as explained in Table III.1.3.

  4.

  An integer specifying the endianness swapping policy followed by the translator. Four values are possible:

  • value 0 means that binary words are never swapped befor interpretation.
  • value 1 means that binary words are swapped only if translated to a String.
  • value 2 means that binary words are swapped only if translated to something else than a String.
  • value 3 means that binary words are always swapped.

  The reason why one needs to specify a swapping policy is that “binDataToValues” is not aware of the XDB file from which the binary data have been extracted. The distinction between String and other values results from the fact that Nastran swaps the bytes of integer and real values, but not the bytes of Strings.

  We recomment to set policy to 0 if no swap is needed and to 1 if a swap is needed. (See the example in section IV.2.8.

  Note that binary String produced by “each_xdbBinRaw” iterator can also be interpreted by the “unpack” method of Ruby Strings or equivalent capabilities of other programming languages.