Introduction

This document presents the manual of FeResPost.

FeResPost

When sizing a structure with FE software, the engineer is often led to use or develop tools that automate the computation of margins of safety, reserve factors or other results from outputs obtained with a FE solver. Then the engineer is facing several problems:

• They have to take into account the possibility of modifications of the structure and of its corresponding finite element model during the project.

• Also, the allowables may change during the course of the project.

• Sometimes, the calculation methods are imposed by a client or a methodology department in the company, and these methods may also be modified, or be defined concurrently with the sizing activities.

• For long duration projects, the members of the calculation team are often displaced as the work proceeds, and time is lost to transfer the information from one engineer to another.

All these problems create difficulties in the management of automated post-processing. The scripts must be as simple and clearly written as possible to allow easy understanding by everyone. Their architecture must also be flexible to make modifications easy to implement and reduce the risk of errors.

The problems mentioned above are very similar to the kind of problems a programmer is facing when writing a large program. To help the programmer in this task, object-orientation emerged as a key programming language concept. Object-oriented languages allow the development of more flexible programs with a better architecture and allow the re-usability of code. Many object-oriented languages are now available. They can be compiled languages (C++, Fortran 90,...) or interpreted ones (Ruby, Python, Visual Basic,...).

FeResPost is a compiled library devoted to the programming of automated post-processing of finite element results. It provides the definition of several classes and one module. It uses object orientation at two levels:

1.

With object-oriented languages, it allows the writing of interpreted, object-oriented automated post-processing. An example of such an object-oriented post-processing program is given in Chapter IV.4.

2.

The FeResPost library is mainly written in C++, which is also an object-oriented language. Then a Ruby wrapping is provided around the C++ code.

During the development of FeResPost, the developer has been trying to maintain as much as possible the simplicity and clarity of the language in which post-processing programs are written.

FeResPost can be accessed from different languages and on different platforms:

• As a ruby extension. Binaries are available for Windows and Linux distributions of ruby.

• As a Python compiled library on Windows and Linux.

• As a COM component on Windows. Then, the library can be used with different languages that support COM interface: C, C++, ruby, Python, VBA...

• As a .NET assembly that allows the programming with VB.NET, C++.NET, C#...

How to learn FeResPost?

Some advice is given here to people starting to use FeResPost. The order in which knowledge is acquired matters. One of the worst ways to try to learn FeResPost is to read the manual while writing bits of code meant to solve the particular problem the user has in mind. Instead, the following sequence of knowledge acquisition is suggested:

1.

FeResPost is an extension of ruby programming language. This means that the examples provided in the document are small ruby programs. Therefore a basic knowledge of ruby is necessary. People who try to learn ruby and FeResPost simultaneously will likely struggle with both.

Very good books on ruby language are available in libraries. Internet resources are also a source of information (newsgroups, tutorials with examples...).

Note that people already familiar with one or several object-oriented programming languages will have no difficulty acquiring a basic knowledge of ruby.

2.

Then, the user may test FeResPost by running the small examples. These are provided in the sub-directories in “RUBY” directory. Note that the Nastran bdf files should first be run in order to have the op2 result files available. It may be a good idea to try first to understand the structure of the bdf files and of the organization of the finite element model.

The small examples are meant to be increasingly difficult. So, the user should first run the examples in “EX01” directory, then in “EX02”... For each example, every statement should be understood, and the corresponding pages of the user manual should be carefully read.

3.

When all the small examples have been run and understood, the user will probably have acquired a reasonable understanding of the various capabilities of FeResPost. Then it may be a good idea to start to read the user manual. For example, to read a few pages each day in such a way that the information can be digested efficiently.

4.

The two examples “PROJECTa” and “PROJECTb” illustrate the programming of more complex post-processing of Results involving loops on load-cases, on several types of post-processing calculations... These two projects should be studied at the very end.

“PROJECTa” is meant to be studied before “PROJECTb”. Indeed, “PROJECTa” is easier to understand than “PROJECTb”, because it is less object-oriented. However, it is also less complete and less elegant from a programming point of view.

The reason why the advice above is given is that many users send emails with questions or complaints because they fail to understand something about FeResPost that is clearly illustrated in the examples. Sometimes, the problems faced by users are simply related to a lack of understanding of the ruby programming language.

Structure of the document

This document is organized as follows:

• In Part I the various classes defined in the FeResPost library and their member functions are presented. Emphasis is placed on the definition of the concepts to which they correspond, and their relevance for the development of post-processing tools.

• Part II is devoted to the presentation of the classes devoted to composite calculations with the Classical Laminate Analysis Theory.

• Part III is devoted to the presentation of the preferences for the different solvers supported by FeResPost.

• In Part IV, several examples of post-processing written with the ruby library are presented.

• Part VI contains the description of FeResPost COM component. This Part is less detailed, since most methods in the COM component have the same characteristics as the corresponding methods in ruby extension.

• Examples of programs with the COM component are given in Part VII.

• Part VIII contains the description of FeResPost NET assembly. Here again, the description is shorter than for the ruby extension.

• Examples of programs with the NET assembly are given in Part IX.

• Part V contains the description of FeResPost Python library. Both the library and the examples are described in that part, which is very short as the Python and ruby languages are very similar.

• Part X contains the annexes.

• References are given in Part XI.

A list of the different classes defined in FeResPost with pointers to Tables listing the methods defined by these classes is given in Table 1.

Future developments

FeResPost is still at the very beginning of its development and much work is still necessary to cover a wider range of applications. A few examples of possible improvements are given below, roughly sorted by order of urgency or ease of implementation:

1.

Correction of bugs...

2.

Addition of specialized post-processing modules programmed at C++ level to provide efficiency. For example:

• A module devoted to fatigue and damage tolerance analysis.

• A module devoted to the calculation of stresses in bar cross-sections from the bar forces and moments.

• ...

3.

Extension of FeResPost by providing interfaces towards other FE software like Abaqus,...

4.

...

Of course, we are open to constructive remarks and comments about the ruby library in order to improve it.

Contents

Index

Part I
FeResPost Reference Manual

Chapter I.0
Introduction

FeResPost is a library that allows the manipulation of finite element entities and results. Its purpose is to ease the development of post-processing programs. The supported solvers and corresponding program preferences are discussed in Part III of the document.

The various capabilities implemented in the ruby extension are mainly inspired by Patran capabilities. Several types of objects can be manipulated:

• The “DataBase” class corresponds to the Patran concept of dataBase. It is used to store the finite element model definition, the results, the groups,... It also allows operations to be performed on the corresponding objects. This class is presented in Chapter I.1.

• The “CoordSys” class allows the definition and manipulation of coordinate systems. This class is particularly useful for some manipulations of Results. It is presented in Chapter I.2.

• The “Group” class corresponds to the Patran “group”. This class is presented in Chapter I.3.

• The “Result” class is used to retrieve, store and transform finite element results. This class is presented in Chapter I.4.

• The “ResKeyList” class is very useful to define lists of entities on which results are to be retrieved. This class is presented in Chapter I.5. Note that this class is still under construction. However, the ResKeyList objects are already used for the manipulation of Results (section I.4.3).

Finally, additional functions, not members of any class, are defined in a module called “Post”. The “Post” module is discussed in Chapter I.6. In the same chapter, other topics are also discussed, such as exceptions.

Chapter I.1
Generic “DataBase” class

Basically, a “DataBase” class is a container used to store a finite element model, Groups, Results, and other less important entities. The DataBase class also allows retrieval, manipulation and modification of these objects. The DataBase class is a generic class that cannot be instantiated. The specialized classes that inherit the generic DataBase class are described in Part III. Other solvers might be supported in the future. The class hierarchy is schematically represented in Figure I.1.1.

Figure I.1.1: Finite element DataBase classes hierarchy.

As three classes are represented in Figure I.1.1, the methods described in this Chapter may belong to the generic DataBase class or to the derived classes. A few basic principles should help the user to “guess” in which class some of the methods are defined:

• All methods related to the definition of the model stored in the DataBase are defined in the specialized classes.

• All methods related to the reading of Results from solvers output files are defined in the specialized classes.

• Most methods for the manipulation of Groups and of Results are defined in the generic “DataBase” class.

Throughout the Chapter, for each method the class in which it is defined is specified. This Chapter is divided into several sections:

• Section I.1.1 presents the methods devoted to the initialization of the finite element model in the DataBase.

• Section I.1.2 is devoted to the DataBase’s methods devoted to the manipulation of Groups.

• Section I.1.3 is devoted to the DataBase’s methods devoted to the manipulation of Results.

• In section I.1.4, the manipulation of abbreviations stored in the DataBase is described.

• The interaction of CLA classes with DataBase classes is discussed in section I.1.5.

• The iterators of Class DataBase are described in section I.1.6.

• Finally, general purpose methods are presented in section I.1.7.

A list of the methods defined in “DataBase” class is given in Table I.1.1.

I.1.1 Methods for FEM definition

No generic “DataBase” object can be created because “DataBase” class cannot be instantiated. This means that a statement like:

    db=DataBase.new()

leads to an error message. All the methods described in this section are defined in the specialized versions of the DataBase class. So no “new”, “initialize” or “clone” method is defined in DataBase class.

Three methods are defined that return the number of entities of certain types stored in the DataBase FE model:

• “NbrCoordSys” attribute returns the number of coordinate systems stored in the DataBase.

• “NbrElements” attribute returns the number of elements stored in the DataBase.

• “NbrNodes” attribute returns the number of nodes stored in the DataBase.

Each of these methods has no argument and returns an integer. Other methods allow checking the existence of finite element entities:

• “checkCoordSysExists” returns true if the specified coordinate system exists, false otherwise.

• “checkElementExists” returns true if the specified element exists, false otherwise.

• “checkNodeExists” returns true if the specified node exists, false otherwise.

• “checkRbeExists” returns true if the specified RBE exists, false otherwise.

Each of these four methods has one integer argument corresponding to the entity the existence of which is checked.

Several methods allow retrieval of element information. Each of the following methods has one integer argument corresponding to the element ID:

• “getElementType” returns an integer corresponding to the type ID of the element.

• “getElementTypeName” returns a string corresponding to the type name of the element.

• “getElementDim” returns an integer corresponding to the topological dimension of the element.

• “getElementNbrNodes” returns an integer corresponding to the number of nodes defining the element.

• “getElementNbrCornerNodes” returns an integer corresponding to the number of corner nodes defining the element.

• “getElementNodes” returns an array of integers that corresponds to the element nodes.

• “getElementCornerNodes” returns an array of integers that corresponds to the element corner nodes.

Normally one class corresponds to each solver supported by FeResPost. The preferences for the different supported solvers are described in Part III.

I.1.2 “Group” methods

Groups can be stored in, and retrieved from a DataBase object. The methods defined in generic class DataBase, or in its derived classes, that are devoted to the manipulation of Group objects, are presented here. In the DataBase, the Group objects are stored in a mapping associating their names to the Group, allowing retrieval of the Group when needed.

A distinction is made between the simple manipulation of Groups described in section I.1.2.1 and the more complicated operation where new Groups are created by association operations (section I.1.2.2). The methods related to these associative operations are often defined in the specialized versions of the Database class.

I.1.2.1 Simple manipulation of Groups

The methods that allow the manipulation of Groups stored in a generic DataBase object. All the methods described in this section are defined in generic DataBase class. These methods are described below:

• “readGroupsFromPatranSession” reads one or several Groups from a Patran session file obtained using the utility “Patran–>utilities–>groups–>exportToSessionFile”. The argument is a String corresponding to the name of the session file. The method returns nil. If some of the entities read in the session file do not exist (for example, missing elements or nodes), then the read entities will not be added to the Group. This corresponds to the behavior of Groups in Patran. Therefore the session file containing the definition of Groups should be read after the finite element model.

  Note that, even though the method is related to an MSC software, it can be used with DataBase related to different solvers. This is the reason why the method “readGroupsFromPatranSession” is defined in generic DataBase class.

  The method “readGroupsFromPatranSession” works as follows:

  • It searches in the file the statements “ga_group_entity_add” and stores the while PCL statement in a string.

  • Then, the name of the Group being initialized is scanned from the string.

  • Finally, the entity definition is scanned:

    • The statement searches words like “Node”, “Element”, “MPC”, “CoordSys”. Note that “MPC” corresponds to the definition of a list of rigid body elements (RBEs). Nastran MPC cards cannot be inserted in a Group.

    • For any of the four first words, the method builds a list of integers corresponding to the identifiers of the entities to be added to the Group. For the three last words above, the method skips the entities.

      The entities can be defined by a list of integers separated by blanks, or by pairs of integers separated by “:” which defines a range of integers, or by groups of three integers separated by two “:” which defines a range with a stepping argument.

  • Prior to storing the Group in DataBase, the method checks that the entities of the Group are defined in the DataBase. If not, they are erased from the Group.

  Note that the definition of Groups in Ruby by range specification uses the same kind of formats as ”setEntities” method in Group class. (See section I.3.3.)

• “writeGroupsToPatranSession” writes the Groups stored in the DataBase in a text file corresponding to a Patran session defining groups. This method is the reverse of method “readGroupsFromPatranSession” an has one argument: the name of the Patran session file. Note that “MPC” corresponds to the definition of a list of rigid body elements (RBEs). Nastran MPC cards cannot be inserted in a Group.

• “addGroupCopy” is used to add a Group to a DataBase. The method returns nil and has one argument: the Group object. Note that, when adding a Group to the DataBase, a check is done to verify that all its entities are present in the DataBase. If not present, then the corresponding entities are erased from the Group. As this involves the modification of the Group definition, all operations are performed on a copy of the Group argument. In the DataBase, the added Group is associated with the name of the group argument. If a Group associated with the same name existed prior to adding the new Group, the method replaces the former Group by the new one.

• “NbrGroups” attribute has no argument and returns the number of Groups stored in the DataBase.

• “getAllGroupNames” has no argument and returns an Array of String objects corresponding to the names of all the Groups contained in the DataBase on which the method is called.

• “checkGroupExists” allows to check whether a Group exists in the DataBase. The argument is a String object corresponding to the name of the Group. The returned value is true if the Group has been found, false otherwise.

• “getGroupCopy” has one argument: a String object corresponding to the name of the Group to be retrieved. The method returns a copy of the Group stored in the DataBase, if the Group with the appropriate name exists. The method returns an error if no Group with the appropriate name exists in the DataBase.

• “eraseGroup” erases a Group from the DataBase. The argument is a String object corresponding to the name of the Group to be erased. If the Group does not exist in the DataBase, nothing is done.

• “eraseAllGroups” erases all Groups stored in the DataBase. This method has no argument.

• “getGroupAllElements” returns a Group containing all the elements that define the model stored in the DataBase.

• “getGroupAllNodes” returns a Group containing all the nodes that define the model stored in the DataBase.

• “getGroupAllRbes” returns a Group containing all the RBEs that define the model stored in the DataBase.

• “getGroupAllCoordSys” returns a Group containing all the coordinate systems that define the model stored in the DataBase.

• “getGroupAllFEM” returns a Group containing all the elements, nodes, rbes and coordinate systems that define the model stored in the DataBase.

I.1.2.2 Construction of Groups by association operations

This section is devoted to methods that allow the construction of a new Group by selecting entities associated with other entities of the finite element model. For all these methods, the association is checked by inspection of the finite element model stored in the DataBase. These methods are therefore systematically defined in specialized versions of the “DataBase” class. For each supported solver, a description of these methods is given. (See Part III.)

I.1.3 “Result” methods

As explained in the introduction of this Chapter, the DataBase can be used to store Results. Internally, a mapping between keys and Results allows to associate Result objects to an identifier. Each key¹ is characterized by three String objects corresponding respectively to the load case name, to the subcase name and to the Result type name.

I.1.3.1 Manipulation of Results

The class “Result” is described in Chapter I.4. This section describes the methods of the generic “DataBase” class that deal with “Result” objects. The “Result” methods are:

• “getResultLoadCaseNames” is a method without argument that returns an Array containing the names of all the load cases for which Results are stored in the DataBase.

• “getResultSubCaseNames” is a method without argument that returns an Array containing the names of all the subcases for which Results are stored in the DataBase.

• “getResultTypeNames” is a method without argument that returns an Array containing all the Result identifiers for Results stored in the DataBase.

• “checkResultExists” is used to check whether a certain Result is present in the DataBase. The method returns a Boolean value and has three String arguments corresponding to the load case name, the subcase name, and the Result name.

• “getResultSize” returns the size of a Result object stored in the DataBase. The method returns an integer value and has three String arguments corresponding to the load case name, the subcase name, and the Result name. If the corresponding Result is not found, “-1” is returned.

• “getResultLcInfos” returns the integer and real ids associated with a Result object stored in the DataBase. The method has three String arguments corresponding to the load case name, the subcase name, and the Result name. Integer and real ids are returned in an Array of 4 elements. If specified Result is not found in the DataBase, method returns nil.

• “addResult” is used to add a Result to the DataBase. The arguments are three String objects corresponding to the key (load case name, subcase name and Result type name), and the Result object. If a Result with the same key is already present in the DataBase, it is deleted and replaced by the new one.

• “generateCoordResults” has three String arguments and builds a Result corresponding to Coordinates of elements and nodes. The arguments correspond to the key to which the Result object is associated in the DataBase. (load case name, subcase name, and Result name respectively.) If the String arguments are omitted, it is assumed that “”, “” and “Coordinates” for the Result key.

• “generateElemAxesResults” has two or three arguments. The two first arguments are the load case name and subcase name to which the produced Results will be associated. These arguments are mandatory. The method produces several vectorial Results:

  1.

  “Axis 1” corresponding to the first element axis.

  2.

  “Axis 2” corresponding to the second element axis.

  3.

  “Axis 3” corresponding to the third element axis.

  4.

  “Normals” corresponding to the normals to 2D elements.

  5.

  “Axis” corresponding to the first element axis of 1D elements.

  6.

  “Coordinates” corresponding to the coordinate Results generated by “generateCoordResults” method.

  By default, components are expressed in element axes, except for the “Coordinates” Result which follow the conventions of “generateCoordResults” method. The third argument allows to modify this default behavior by expressing the components in another coordinate system specified by a String or an integer argument. This argument is optional. The use of this option leads to a very significant increase of the computation time of the method.

  Note also that the vectorial values are associated with element centers, and element corners. For the “Coordinates” Result, values are also associated with nodes.

• “buildLoadCasesCombili” allows the definition of Result by linear combination of other Results. The selection of the new Result and elementary Results is done by load case names. The first argument is a String containing the new load case name of the Results being created. The second argument contains an Array of real numbers corresponding to the factors of the linear combination. The third argument is an Array of Strings containing the name of load cases to which elementary Results are associated. The lengths of the two Array arguments must match.

• “renameResults” is used to modify the key by which Results stored in the DataBase can be accessed. The method has two arguments:

  1.

  An Array of three String objects corresponding to the identification of the Results that must be renamed. If one of the String is void or replaced by nil, then all the Results matching the non void Strings are renamed. Of course, at least one of the three Strings must be non-void.

  2.

  An Array of three Strings containing the new key identifiers. Strings must be void or nil at the same time as the Strings of “From” argument.

• “copyResults” has the same arguments as “renameResults”, and performs nearly the same operation. The difference is that the Result stored in the DataBase is now duplicated, and not simply renamed.

• “removeResults” is used to delete Results from the DataBase. This method has two String arguments corresponding to the method of selection of Results and to an identifier respectively. The “Method” argument has three possible values: “CaseId”, “SubCaseId” or “ResId”. It specifies whether the Results to be deleted are identified by their load case name, their subcase name or their Result type name. The second String argument corresponds to the identifier of Results to be deleted.

• “removeAllResults” erases all Results stored in the DataBase. This method has no argument.

• “getResultCopy” returns a Result object containing a copy of a portion of a Result stored in the DataBase. This method has generally six arguments (see below for other possibilities):

  1.

  A String argument corresponding to the load case name.

  2.

  A String argument corresponding to the subcase name.

  3.

  A String argument corresponding to the Result type name.

  4.

  A String argument corresponding to the method of selection. Possible values of this argument are listed and explained in Table I.4.6 of section I.4.3. This “Method” string argument can be replaced by a Result or ResKeyList object. Then it correspond to the target entities on which the values are extracted. (See remark below.)

  5.

  A Group argument corresponding to the Target (selection of elements or nodes on which the Results are recovered).

  6.

  An Array corresponding to the list of layers on which results are to be recovered. This Array can be void. If not void, its elements must be String or integer objects.

  Some of the arguments given above are optional. For example, the function can be called with 3 or 4 arguments only.

  When the fourth argument is a Result or a ResKeyList object, the function must have exactly four arguments. Then, it returns a new Result obtained by extracting the pairs of key and values on the keys of the Result or ResKeyList argument.

  Valid calls to the function are illustrated below:

                res=db.getResultCopy(lcName,scName,resName,"ElemCenters",
                                            targetGrp,layersList)
                res=db.getResultCopy(lcName,scName,resName,"NodesOnly")
                res=db.getResultCopy(lcName,scName,resName,layersList)
                res=db.getResultCopy(lcName,scName,resName)
                res=db.getResultCopy(LcName,ScName,ResName,targetRes)
                res=db.getResultCopy(LcName,ScName,ResName,targetRkl)
                res=db.getResultCopy(lcName,scName,resName,"ElemCenters",
                                            targetGrp)
  

  In the third example above, the extraction is done on the list of layers only, no selection is done for the elements or nodes. In the fourth example, a copy of the Result stored in the DataBase is returned without selection on a list of elements, nodes, layers or sub-layers..

  When the method has four arguments, the fourth one is interpreted as a selection method if it is a String. As no extraction Group argument is provided, the extraction is done on all nodes or elements. Also, when four arguments are provided, a single layer cannot be specified as a String argument. It should be specified as an Array of Strings. For example:

                res=db.getResultCopy(lcName,scName,resName,["Z1"])
  

  is valid, but:

                res=db.getResultCopy(lcName,scName,resName,"Z1")
  

  is not.

Methods devoted to the importation of Results from binary Results files are specific to the specific solver that produced the Results. These methods are described in Part III.

I.1.3.2 Enabling composite Results reading operations

Four singleton methods allow enabling or disabling partially or totally the reading of composite layered Results from finite element result files. These methods influence the behavior of methods defined in the “specialized” versions of the “DataBase” class. (See Part III.) The four methods are:

• “enableLayeredResultsReading” enables the reading of layered laminate Results (stresses, strains, failure indices...). This method has no argument. In practice, this method is used to re-enable the reading of layered laminate Results as this reading is enabled by default.

• “disableLayeredResultsReading” disables the reading of layered laminate Results (inverse of the previous method). Again, the method has no argument.

• “enableSubLayersReading” enables some sub-layers for the reading of composite layered Results from result files. The method has one argument: a String or an Array of Strings chosen among “Bottom”, “Mid” and “Top”. Here, since by default all the sub-layers are enabled, the method is rather a “re-enabling” method.

• “disableSubLayersReading” disables some sub-layers for the reading of composite layered Results from result files. The method has one argument: a String or an Array of Strings chosen among “Bottom”, “Mid” and “Top”.

By default the reading of layered composite Results is enabled for all sub-layers. The disabling may help to reduce the size of Results stored in specialized DataBases. In fact, the reading of composite results is no longer mandatory as most composite results can be produced with the appropriate methods of the “CLA” classes (Part II).

I.1.4 Manipulation of abbreviations

When a Samcef banque is read into a DataBase, the abbreviations defined in the Samcef model are read as well and stored into the Samcef DataBase in a mapping of string objects. Five methods allow the manipulation of abbreviations stored in the DataBase:

1.

“clearAbbreviations” has no argument and clears all the abbreviations stored into the DataBase.

2.

“addAbbreviation” adds one abbreviation to the DataBase. The method has two String arguments: the key and the value.

3.

“addAbbreviations” adds a list of abbreviations to the DataBase. The method has one argument: A Hash object containing the correspondence between keys and values. Each pair is of course a pair of String objects.

4.

“NbrAbbreviations” attribute has no argument and returns the number of abbreviations stored in the DataBase.

5.

“getAbbreviation” returns the String value of one abbreviation. The method has one String argument: the key of the abbreviation.

6.

“checkAbbreviationExists” returns “true” if the abbreviation exists. The method has one String argument: the key of the abbreviation.

7.

“getAbbreviations” returns a Hash object containing all the abbreviations stored in the DataBase. This method has no argument.

Note that, even though no abbreviation is defined in other solver models, the abbreviation methods defined in DataBase class can also be used when working with any model. This is why the methods listed above are defined in generic “DataBase” class and not in “SamcefDb” class described in Chapter III.2.

I.1.5 Composite methods

The DataBase Class provides one method that returns a ClaDb object corresponding to the materials, plies and Laminates stored in the DataBase. This method is called “getClaDb” and has no argument. The units associated with this ClaDb object are the default units as defined in Table II.1.4. If the finite element model is defined in another unit system, it is the responsibility of the user to define correctly the units of the ClaDb database and of all its entities using the method “setUnitsAllEntities” of ClaDb class. (See section II.2.4.)

Another method corresponding to the calculation of Results related to laminate load response has been added. This method called “calcFiniteElementResponse” has the same arguments as the corresponding method defined in the “ClaLam” class. The method and the meaning of its arguments are described in section II.4.8. The method defined in “DataBase” class differs from the one defined in “ClaLam” class by the fact that the algorithm tries to retrieve the Laminate corresponding to the element to which Result values are attached. The information is found in the DataBase object. More precisely, The algorithm performs as follows:

• The property ID or laminate ID corresponding to the element is identified. Then, the algorithm tries to retrieve a laminate with the same ID from the ClaDb argument.

• If a laminate object has been identified and extracted, the algorithm performs the same operations as for the method described in section II.4.8.

• Otherwise, no Result values are produced for the current key and the next key is tried.

Similarly, the method “calcFiniteElementCriteria” is defined, which has exactly the same arguments and outputs as the corresponding method of “ClaLam” class described in section II.4.8. The difference between the two methods resides in the fact that the method in DataBase class retrieves the ClaLam object corresponding to the element to which the tensorial values are attached.

Finally, a third method allows to retrieve laminate engineering properties in the format of Result objects. The method “calcFemLamProperties” has three arguments:

1.

A ClaDb object which is used for the calculations of the different laminate properties.

2.

A ResKeyList object that corresponds to the finite element entities for which values shall be inserted in Result object. Note that the produced Result object are non layered. (Only the ElemId and NodeId of the ResKeyList keys matter.)

3.

A Hash with String keys and values corresponding to the requests. The key corresponds to the name by which the returned Result shall be referred. The value corresponds to the laminate engineering property that is requested. Presently, possible values of this parameter are: “E_f_xx”, “E_f_yy”, “E_k0_xx”, “E_k0_yy”, “E_xx”, “E_yy”, “G_f_xy”, “G_k0_xy”, “G_xy”, “nu_f_xy”, “nu_f_yx”, “nu_k0_xy”, “nu_k0_yx”, “nu_xy”, “nu_yx”, “thickness”, “surfacicMass”, “averageDensity”.

The method returns a Hash with String keys and Result values.

An example of use of this method follows:

    ...
    compDb=db.getClaDb

    res=db.getResultCopy("COORD","coord","coordinates")
    rkl=res.extractRkl

    requests={}
    requests["res1"]="thickness"
    requests["res2"]="E_xx"
    requests["res3"]="E_yy"

    resList=db.calcFemLamProperties(compDb,rkl,requests)

    resList.each do |id,res|
        Util.printRes(STDOUT,id,res)
    end
    ...

For the different “finite element” methods listed above, the units considered for the returned “Result” objects are the units of the “ClaDb” object argument. This characteristic differs from the behavior of the corresponding methods in “ClaLam” class.

I.1.6 Iterators

The iterators of the generic DataBase class only are described here. The iterators of the specialized versions of the class are described in Part III.

• “each_abbreviation” loops on the abbreviations stored in the DataBase. It produces pairs of Strings corresponding to the name of the abbreviation, and to the corresponding value respectively. Again, one should be noted that this iterator is defined in the generic DataBase class.

• “each_groupName” loops on the Groups stored in the DataBase and produces String elements containing Group names.

• The iterator “each_resultKey” produces Arrays containing the keys to which stored Results are associated. This iterator can be used in two different ways. Either:

            db.each_resultKey do |lcName,scName,tpName|
                ...
            end
  

  or:

            db.each_resultKey do |resKey|
                ...
            end
  

  In the second case, resKey is an Array containing three Strings.

• The following methods iterate on the CaseId, SubCaseId and ResultId corresponding to the Results stored in the DataBase:

  • “each_resultKeyCaseId”,

  • “each_resultKeySubCaseId”,

  • “each_resultKeyResId”.

  Each iterator produces String elements.

• “each_resultKeyLcScId” iterator produces the pairs of load case names and subcase names for which Results are stored in the DataBase. This iterator can for example be used as follows:

            db.each_resultLcScId do |lcName,scName|
                ...
            end
  

  However, if a single argument is passed in the block, it corresponds to an Array of two Strings.

I.1.7 General purpose methods

A few more methods with general purpose are defined:

• “Name” attribute “setter” and “getter” allow manipulation of the identification of the DataBase.

• Method “to_s” is used for printing the DataBase object.

These methods are defined in the generic “DataBase” class.

I.1.8 “Gmsh” methods

The “writeGmsh” method defined in generic “DataBase” class is used to create a Gmsh result file in which parts of the model and of the Results are saved for later visualization. The purpose of the method is to allow the user to visualize parts of the model and Results. An example of use of the method is as follows:

    db.writeGmsh("brol.gmsh",0,[[res,"stress","ElemCenters"],\
                                         [displ,"displ","Nodes"]],\
                                        [[skelGrp,"mesh slat"]],\
                                        [[skelGrp,"skel slat"]])

The method has six parameters:

1.

A string containing the name of the file in which the model and Results will be output.

2.

An integer corresponding to the id of a coordinate system in which the positions are located and in which the components of Result values are expressed. The coordinate system must be defined in the dataBase db and must be a rectangular one.

3.

An Array containing the Results to be stored in the Gmsh file. Each element of the Array is an Array of three elements:

• A Result object.

• A String corresponding to the name with which the Result shall be referenced in Gmsh.

• A String that can have six values: “ElemCenters”, “ElemCorners”, “Elements”, “Nodes”, “ElemCenterPoints” and “ElemNodePoints”. It corresponds to the location of values that are extracted from the Result object to be printed in the Gmsh file. Note:

  • “ElemCenterPoints” prints the values at center of elements but on a point, regardless of the topology of the element. This may be useful for the visualization of Results on zero length elements.

  • “ElemNodePoints” prints the values at nodes of elements on points, regardless of the topology of the element.

  • “Elements” output location combines the outputs at “ElemCorners” and “ElemCenters”. If no value is found at a corner, the algorithm checks whether an output is found at center of element, and uses that value if it is found.

4.

An Array containing the Meshes to be stored in the Gmsh file. Each element of the Array is an Array of two elements:

• A Group object. The elements contained in the Group will be output in the Gmsh file.

• A String corresponding to the name with which the mesh shall be referenced in Gmsh.

5.

An Array containing the parts of the model for which a “skeleton” shall be saved in the Gmsh file. (A skeleton is a representation of the mesh with only a few edges.)

• A Group object. The elements contained in the Group will be output in the Gmsh file.

• A String corresponding to the name with which the skeleton shall be referenced in Gmsh.

6.

A logical parameter specifying whether a binary output is requested. If the parameter is “true” a binary output is done, otherwise, the output is an ASCII one. The parameter is optional and binary output is the default. A binary output is significantly faster than an ASCII one.

Parameters 3, 4 and 5 are optional. They can be a void Array or replaced by nil argument. All the last nil parameters may be omitted. Parameter 6 is optional too. If no pair of key-values is found for a Result to be printed. Nothing is output in the gmsh file.

It is the responsibility of the user to provide Results that associate values to a single valid key. Otherwise, an error message is issued and exception is thrown. In particular, as Results written in GMSH files are not layered, the user should be careful not to output multi-layered Results. The details in error message output are controlled by the debugging verbosity level. (See I.6.6.)

Note also that if the values that the user tries to output are not valid, a substitution is done: Infinite float values are replaced by MAXFLOAT value, NaN values are replaced by MINFLOAT value. (Of course it is advised to output Result objects with valid values.)

The “writeGmshMesh” method defined in generic “DataBase” class saves a Gmsh mesh file. The method has up to four arguments (last argument is optional):

1.

A String containing the name of the file in which the mesh is output.

2.

An integer argument corresponding to the coordinate system in which the nodes are expressed.

3.

A Group corresponding to the entities to be saved in the mesh file.

4.

An optional Boolean argument specifying whether the mesh is output in binary format. The default value of the argument is “true” and corresponds to a binary output.

An example of use follows:

        db.writeGmshMesh("brol.msh",0,skelGrp,false)

Chapter I.2
The “CoordSys” class

It may be practical to manipulate coordinate systems at post-processing level. Therefore, a “CoordSys” class devoted to the manipulation of coordinate systems is proposed. The methods defined in that class are described in sections I.2.2 and I.2.5. A list of the methods defined in “CoordSys” class is given in Table I.2.1.

I.2.1 The CoordSys object

A CoordSys object corresponds to a coordinate system. CoordSys objects are generally created in a DataBase when a model is imported.

Besides the data corresponding to the definition of the coordinate system, the CoordSys object also contains a definition of the coordinate system with respect to the most basic coordinate system “0”. The corresponding member data are used by functions like the Result methods of modification of reference coordinate systems to perform the transformations of components (sections I.4.6.7 and I.4.6.8). Practically those functions work in two steps:

1.

The components of the Result object are expressed with respect to the basic coordinate system “0”.

2.

Then, the components are expressed with respect to the new coordinate system.

The definition of the corresponding member data is done by calling the method “updateDefWrt0” (section I.2.2.3).

I.2.2 Construction or manipulation functions

Besides the “new” class method that returns a new coordinate system initialized to the “0” structural coordinate system, several functions can be used to modify the CoordSys objects.

I.2.2.1 “initWith3Points” method

“initWith3Points” method is used to define a coordinate system with the coordinates of three points A, B and C. (See the definition of “CORD2C”, “CORD2R” and “CORD2S” in [Sof04b].) This function has 5 arguments:

• A string argument corresponding to the type of coordinate system being built. Three values are accepted: “CORDC”, “CORDR” and “CORDS”. (Note that the “2” of Nastran has been dropped.)

• A DataBase object that will allow the definition of coordinate system with respect to the base coordinate system.

• An integer argument corresponding to the reference coordinate system (coordinate system with respect to which the coordinates of points A, B and C are given). A coordinate system corresponding to this integer must be defined in the DataBase passed as previous argument.

• A vector containing the coordinates of point A. (Point A corresponds to the origin of the coordinate system.)

• A vector containing the coordinates of point B. (Point B defines the axis Z of the coordinate system. More precisely, point B is on axis Z.)

• A vector containing the coordinates of point C. (Point C defines the axis X of the coordinate system. More precisely, the axis X of the coordinate system is defined in the half-plane defined by the straight-line AB and the point C.)

The three vectors mentioned above are actually Arrays of three real values corresponding to the coordinates of points given in coordinate system identified by the integer argument.

Note that no check is made in a DataBase to ensure that the data are consistent. (For example, checking that the reference coordinate system exists.)

I.2.2.2 Six “initWithOViVj” methods

The six methods are “initWithOV1V2”, “initWithOV2V3”, “initWithOV3V1”, “initWithOV2V1”, “initWithOV3V2” and “initWithOV1V3”. They produce CoordSys objects defined by their origin and two direction vectors corresponding to vector $e_i$ and to the orientation of vector $e_j$ respectively.

The six arguments of these methods are:

• A string argument corresponding to the type of coordinate system being built. Three values are accepted: ‘CORDC”, “CORDR” and “CORDS”.

• A DataBase argument that provides the information needed to complete the definition of the coordinate system.

• An integer argument corresponding to the reference coordinate system (coordinate system with respect to which the origin and direction vectors are specified).

• A vector containing the coordinates of the origin. This origin is specified with an Array of three real values corresponding to the components of O with respect to the reference coordinate system identified with the integer argument.

• A vector (Array of three real values) corresponding to the direction $i$ of the coordinate system. The components of the vector are given with respect to to the reference coordinate system (estimated at point $0$ if the reference coordinate system is curvilinear).

• A vector (Array of three real values) corresponding to the orientation of base vector $j$ of the coordinate system. The components of the vector are given with respect to to the reference coordinate system (estimated at point $0$ if the reference coordinate system is curvilinear).

Note that the orientation vector $e_j$ is not necessarily orthogonal to $e_i$. If the vectors are not orthogonal, then $i$ is a unit vector parallel to $e_i$, and vector $j$ is the unit vector perpendicular to $i$ closest to $e_j$. The last vector $k$ of the coordinate system is a unit vector perpendicular to both $i$ and $j$.

Here again, no check is made in a DataBase to ensure that the data are consistent. (For example, checking that the reference coordinate system exists.)

I.2.2.3 “updateDefWrt0” method

“updateDefWrt0” method updates the definition of a CoordSys object with respect to to “0” (most basic coordinate system). This function has one argument: the DataBase in which the information needed to build the definition with respect to 0 is found.

Note that if one works with several DataBases, the responsibility of managing the correspondence of coordinate systems and DataBases lies with the user.

I.2.3 Transformation of point coordinates

The “CoordSys” class defines three methods devoted to the transformation of a point coordinates from one coordinate system to another.

I.2.3.1 “changeCoordsA20” method

Method “changeCoordsA20” is used to calculate the coordinates of a point with respect to basic or “0” coordinate system:

• The coordinate system on which the method is called is the coordinate system in which the initial coordinates of the point are defined. (Coordinate system “A”.)

• The method has one “CoordA” argument: an Array of three real values corresponding to the initial coordinates of the point in coordinate system “A”.

• The method returns a “Coord0” Array of three real values corresponding to the coordinate of the same point, but expressed with respect to basic coordinate system “0”.

The method is called as follows:

   coords0=csA.changeCoordsA20(coordsA)

I.2.3.2 “changeCoords02B” method

Method “changeCoords02B” is used to calculate the coordinates of a point with respect to a given coordinate system “B”:

• The coordinate system on which the method is called is the coordinate system in which one wants to express the point coordinates (Coordinate system “B”.)

• The method has one “Coord0” argument: an Array of three real values corresponding to the initial coordinates of the point in basic coordinate system “0”.

• The method returns a “CoordB” Array of three real values corresponding to the coordinate of the same point, but expressed with respect to coordinate system “B”.

The method is called as follows:

   coordsB=csB.changeCoords02B(coords0)

I.2.3.3 “changeCoordsA2B” method

Method “changeCoordsA2B” is used to calculate the coordinates of a point with respect to a given coordinate system “B”. The initial coordinate system is a given “A” coordinate system:

• The coordinate system on which the method is called is the initial coordinate system in which the point coordinates are expressed (Coordinate system “A”.)

• The first “CoordA” argument is an Array of three real values corresponding to the initial coordinates of the point in coordinate system “A”.

• The second “CsB” argument is a “CoordSys” object with respect to which one wants to calculate the new point coordinates.

• The method returns a “CoordB” Array of three real values corresponding to the coordinate of the point expressed with respect to coordinate system “B”.

The method is called as follows:

   coordsB=csA.changeCoordsA2B(coordsA,csB)

I.2.4 Transformation of vector and tensor components

The “CoordSys” class defines three methods devoted to the transformation of a vector or tensor components from one coordinate system to another. These methods are similar to the methods used to transform point coordinates in section I.2.3 but with the following differences:

• The components of a vector or of a tensor are modified.

• A vector is defined as an Array of three real values. A tensor is defined as an Array of three Arrays of three real values.

• If a vector argument is given, the method returns a vector. If a tensor argument is given, the method returns a tensor.

• For each of the methods given here, the coordinates of the point at which the vector or tensor argument is defined, are also given as argument. This means that the methods have one additional argument compared to the corresponding methods of section I.2.3.3. The position of the point matters when curvilinear coordinate systems are involved in the transformation.

I.2.4.1 “changeCompsA20” method

Method “changeCompsA20” is used to calculate the components of a vector or tensor with respect to basic or “0” coordinate system:

• The coordinate system on which the method is called is the coordinate system in which the initial components are defined. (Coordinate system “A”.)

• The first “CoordA” argument is an Array of three real values corresponding to the coordinates of the point in coordinate system “A”.

• The second “vmA” argument corresponds to the components of vector or tensor (matrix) in coordinate system “A”. (An Array of three real values, or an Array of Arrays of three real values.)

• The method returns the components of a vector or tensor, but expressed with respect to basic coordinate system “0”. (An Array of three real values, or an Array of Arrays of three real values.)

The method is called as follows:

   vm0=csA.changeCompsA20(coordsA,vmA)

I.2.4.2 “changeComps02B” method

Method “changeComps02B” is used to calculate the components of a vector or tensor expressed in a given coordinate system “B”:

• The coordinate system on which the method is called is the coordinate system in which one wants to express the components. (Coordinate system “B”.)

• The first “Coord0” argument is an Array of three real values corresponding to the coordinates of the point in coordinate system “0”.

• The second “vm0” argument corresponds to the components of vector or tensor (matrix) in coordinate system “0”. (An Array of three real values, or an Array of Arrays of three real values.)

• The method returns the components of a vector or tensor, but expressed in coordinate system “B”. (An Array of three real values, or an Array of Arrays of three real values.)

The method is called as follows:

   vmB=csB.changeComps02B(coords0,vm0)

I.2.4.3 “changeCompsA2B” method

Method “changeCompsA2B” is used to calculate the components of a vector or tensor expressed in a given coordinate system “B”:

• The coordinate system on which the method is called is the coordinate system in which the initial components are defined. (Coordinate system “A”.)

• The first “CoordA” argument is an Array of three real values corresponding to the coordinates of the point in coordinate system “A”.

• The second “vmA” argument corresponds to the components of vector or tensor (matrix) in coordinate system “A”. (An Array of three real values, or an Array of Arrays of three real values.)

• The third “CsB” argument is a “CoordSys” object with respect to which the new components are to be calculated.

• The method returns the components of a vector or tensor, but expressed in coordinate system “B”. (An Array of three real values, or an Array of Arrays of three real values.)

The method is called as follows:

   vmB=csA.changeCoordsA2B(coordsA,vmA,csB)

I.2.5 Other methods

The following methods do not fit in any of the categories listed above.

I.2.5.1 “initialize” method

Method “initialize” initializes or clears a CoordSys object. After initializing, the definition corresponds to the “0” structural coordinate system.

I.2.5.2 “clone” method

“clone” method returns a copy of the CoordSys object to which it is applied.

I.2.5.3 “to_s” method

“to_s” method is used for printing the CoordSys object.

I.2.5.4 “Id” attribute

“Id” integer attribute corresponds to the integer identifier of the CoordSys object. Both a “setter” and “getter” attribute are defined (“Id=” and “Id” methods respectively).

Chapter I.3
The “Group” class

The “Group” corresponds to the Patran notion of group. Group objects can be stored in a DataBase object, retrieved from it and manipulated outside the DataBase. The manipulation methods outside the DataBase class are described here.

A list of the methods defined in “Group” class is given in Table I.3.1.

I.3.1 The concept of “Group”

A Group is characterized by its name (a String object) and the entities it contains. Four types of entities can be contained in a FeResPost Group: coordinate systems, nodes, elements and rigid body elements (RBEs). At C++ level, for each type of entity, the class Group manages a set of integers corresponding to the identifiers of the entities.

Part of the operations dealing with Groups are done by methods defined in DataBase class. The methods of DataBase specially devoted to operations mainly related to Groups are described in section I.1.2.

I.3.2 Creation of a Group object

The singleton method “new” is used to create Group objects.

I.3.3 Manipulation of entities stored in a Group

The class “Group” provides a large choice of methods devoted to the manipulation of the list of entities in its storage. A distinction is made between operations that modify the content of a Group, and operations that allow inspection of this content.

The modification of the Group’s content can be done by calls to the following methods:

• “setEntities” takes a String argument that contains the definition of Group entities in a format similar to the format of the Patran Group session file (section I.1.2.1). All entities previously stored in the Group are erased before the conversion of the String argument. The function returns “self” (the modified Group object). As the String argument follows Patran conventions, the list of RBEs follows “MPC” keyword.

• “setEntitiesByType” has two arguments. The first argument, “TypeName” is a String object that specifies the type of entities to be added to the Group. This first argument may have four different values: “Node”, “Element”, “MPC” (for rigid body elements) or “CoordSys”. Any other argument is invalid. The second argument may have two different types:

  1.

  The second argument may be a String object containing the definition of a group in a format similar to the format of the Patran Group session file (section I.1.2.1). However, in this case, only the entities of the type selected by the “TypeName” argument are stored in the Group.

  2.

  The second argument may also be an Array of integers. Then the integers correspond to the entities added to the Group. The type of entities is specified by the “TypeName” argument.

  As for the “setEntities” method, all entities previously stored in the Group are erased before inserting the new entities.

• “addEntities” is identical to “setEntities” but the entities stored in the Group are not erased before adding the new entities. As the String argument follows Patran conventions, the list of RBEs follows “MPC” keyword.

• “addEntitiesByType” is identical to “setEntitiesByType” but the entities stored in the Group are not erased before adding the new entities.

• “removeEntities” is identical to “addEntities” but the selected entities are removed from the Group instead of being added to it. As the String argument follows Patran conventions, the list of RBEs follows “MPC” keyword.

• “removeEntitiesByType” is identical to “addEntitiesByType” but the selected entities are removed from the Group instead of being added to it.

• “clearAllEntitiesByType” has one String argument corresponding to the type of entities to be cleared from the Group. Possible arguments are “Node”, “Element”, “MPC” (for rigid body elements) or “CoordSys”.

• “importEntitiesByType” is used to insert entities in a Group by importing them from another Group, or from the entities stored in a DataBase model. The method has two or four arguments:

  • The first argument is a String corresponding to the type of entities to be inserted. Possible arguments are “Node”, “Element”, “MPC” (for rigid body elements) or “CoordSys”.

  • The second argument is either a Group, or a DataBase.

  • The third and fourth arguments are integers corresponding to the range of insertion (idMin and idMax). If omitted, then all entities of the corresponding type are inserted.

• “matchWithDbEntities” is used to ensure that a Group contains only entities that are defined in a DataBase. The function has one DataBase argument. After calling this method, the entities that do not exist in the DataBase have been removed from the Group as well.

Four methods devoted to inspecting the Group content without modifying it are also defined:

• “getEntitiesByType” receives one String argument corresponding to the type of entity and returns an Array of integers containing the corresponding entity indices. The four possible values of the argument are “Node”, “Element”, “MPC” (for rigid body elements) and “CoordSys”.

• “getNbrEntitiesByType” receives one String argument corresponding to the type of entity and returns an integer corresponding to the number of entities of the specified type contained in the Group. The four possible values of the argument are “Node”, “Element”, “MPC” (for rigid body elements) and “CoordSys”.

• “getNbrEntities” has no argument and returns an Array of four integers corresponding to the number of entities of each of the following types, in the same order as: “CoordSys”, “Element”, “Node” and “MPC” (for rigid body elements).

• “containsEntity” allows checking whether a given entity belongs to the Group. The method has two arguments:

  • The first argument is a String corresponding to the type of entities to be inserted. Possible arguments are “Node”, “Element”, “MPC” (for rigid body elements) or “CoordSys”.

  • The second integer argument is the entityId.

  The function returns a bool value.

A FeResPost Group cannot contain Nastran MPCs.

I.3.4 Group operators

Eight such operators have been defined. The meaning and behavior of the four elementary dyadic operations are first explained below.

• “+” operator returns the union of two Groups.

• “-” operator returns the difference of two Groups.

• “*” operator returns the intersection of two Groups.

• “/” operator: if $x$ and $y$ are two Groups, then $x∕y=(x+y)-(x*y)$. (The operation is equivalent to a logical “exclusive or” operation on the entities.)

I.3.5 “BLOBs”

Group objects can be saved in SQL database as “BLOB” objects.

Two methods are defined in Group class to convert object to and from Blobs:

• “toBlob” has no argument and returns the BLOB in a String object.

• “fromBlob” has one String argument corresponding to the BLOB, and initializes the Group according to Blob content.

I.3.6 Iterators of Group class

The class “Group” provides four iterators:

• method “each_element”,

• method “each_rbe”,

• method “each_node”,

• method “each_coordsys”.

These iterators iterate on the corresponding entities stored in the Group object. They produce Integer values that are passed to the block.

I.3.7 Other methods

The following methods do not fit in any of the categories listed above:

• Method “initialize” initializes or clears a Group object.

• Method “clone” returns a copy of the Group object to which it is applied.

• Attribute “Name” returns a String containing the name of the Group.

• Attribute “Name=” has one String argument and sets the name of the Group.

• Attribute “NbrElements” returns an integer containing the number of elements stored in the Group.

• Attribute “NbrNodes” returns an integer containing the number of nodes stored in the Group.

• Attribute “NbrRbes” returns an integer containing the number of RBEs stored in the Group.

• Attribute “NbrCoordSys” returns an integer containing the number of coordinate systems stored in the Group.

• Method “to_s” is used for printing the Group object.

The “Name” and “Name=” methods correspond to the “Name” attribute.

Chapter I.4
The “Result” class

The “Result” class is devoted to the manipulation of finite element Results. Examples of Results are stress tensor on volumetric or surface elements, displacements, grid point forces,... The ruby class “Result” is a wrapping around the C++ class “Result”.

Results can be read from various solver binary files. See Part III for more information.

The “Result” class allows the storage and manipulation of Real as well as Complex values. Note however that several of the methods of Result class do not allow the manipulation of Complex Results. Therefore, indications are inserted here and there in this Chapter to provide information about the “Complex capabilities” of the different methods.

An important note: Even though the results can be imported into a DataBase, this does not mean that the manipulation of the results is correct. Indeed, all manipulation that involve transformation of coordinate systems can be incorrect because geometric non-linearities are not taken into account. Methods that can be affected by this limitation are for example: “modifyRefCoordSys”, “modifyPositionRefCoordSys” and “calcResultingFM”.

A list of the methods defined in “Result” class is given in Table I.4.1.

I.4.1 The concept of “Result”

Basically, a Result may be considered as a mapping between “keys” and “values”. These two concepts are discussed in sections I.4.1.1 and I.4.1.2 respectively.

Otherwise several member data of Result objects can be accessed at ruby level. This is the case for Result name, integer and real identifiers. Those are discussed in section I.4.1.3.

I.4.1.1 “Keys”

The “keys” of Results correspond to the entities to which “values” are associated. For example, a key may be:

• The index of an element.

• The index of a node.

• A pair of integers corresponding to the indices of an element and of a node (for Results given at corners of elements).

• A pair of integers corresponding to the indices of an element and of a layer (for example, for layered Results corresponding to laminated properties).

• ...

So, at C++ level, each key is characterized by four integers:

• A 32bits integer corresponding to the element index,

• A 32bits integer corresponding to the node index,

• A 32bits integer corresponding to the layer index,

• An 8bits char corresponding to the sub-layer index (rarely used).

At ruby level, one can work with either the C++ integer ids, or their String counterparts. The correspondence between Strings and integers are given in Tables I.4.2, I.4.3, I.4.4 and I.4.5. The data given in these Tables can be completed by additional data specific to the different supported solvers. (See Part III for more information.)

In Table I.4.4, the last layer IDs cannot be assigned to Result keys. The entries correspond to groups of layers and are used to perform extraction operations:

• “Beam Points” is used to extract on layers “Point A”, “Point B”,...

• “Shell Layers” is used to extract on layers “NONE”, “Z1” and “Z2”.

• “All Plies ” is used to extract on all layers with positive Ids (i.e. laminate plies).

• “All Layers ” extracts on all layers.

Note that the notion of “key” is also closely related to the “ResKeyList” ruby class which is simply a list of key objects (see Chapter I.5).

I.4.1.2 “Values”

The values of Result are characterized by an integer value (32 bits integer) and one or several real values. The integer value corresponds to the coordinate system into which the components are expressed:

• -9999 means that the results are not attached to a coordinate system. Their value corresponds to String “NONE”.

• -2000 means that the values are expressed in a user defined coordinate system. This means a coordinate system which is not identified by an integer to be later retrieved from a DataBase. The corresponding String is “userCS”.

• -1000 means that the values are expressed in a coordinate system projected on surfacic elements. This means also that the values are no longer attached to a particular coordinate system defined in a DataBase. The corresponding String is “projCS”.

• -6 means the laminate coordinate system. The corresponding String is “lamCS”.

• -5 means the patran element IJK coordinate system which correspond to the element coordinate system for most finite element software. The corresponding String is “elemIJK”.

• -4 means the ply coordinate system when the element has laminated properties. The corresponding String is “plyCS”.

• -3 means the material coordinate system. The corresponding String is “matCS”.

• -2 means the nodal analysis coordinate system. Values must then be attached to a node (nodeId of key). The corresponding String is “nodeCS”.

• -1 means the element coordinate system. The corresponding String is “elemCS”.

• Any integer greater than or equal to zero: a coordinate system defined in a DataBase object. “0” denotes the base Cartesian coordinate system.

Obviously, for several types of coordinate system, the values must be attached to an element to make sense. This is the case for “elemIJK”, “plyCS”, “matCS”, “elemCS”,...

The real values correspond to the components:

• A “scalar” Result (res.TensorOrder=0) has one component.

• A “vectorial” Result (res.TensorOrder=1) has three components named “X”, “Y” and “Z” respectively.

• A “symmetric tensorial” Result (res.TensorOrder=2) has normally nine components. However, as all the tensors with which one deals are symmetric, only six components are stored: “XX”, “YY”, “ZZ”, “XY”, “YZ”, “ZX”.

• A “non-symmetric” Result (res.TensorOrder=-2) has nine components. The Result components corresponds to the components of the three direction vectors associated with each key and are given in the following order: “XX”, “XY”, “XZ”, “YX”, “YY”, “YZ”, “ZX”, “ZY”, “ZZ”. (See section I.4.1.5.)

Note that the name of the components given above matter, as they may be used to extract a single component out of a vectorial or tensorial Result. For Complex Result, the numbers of components mentioned above is multiplied by two. They are presented in the following order:

• First all the Real or Magnitude components are presented.

• Then all the Imaginary or Angular components follow. The angular components are expressed in ${}^{\circ }$ (Nastran convention).

The components are stored in single precision real values (float coded on 32 bits). This means that there is no advantage in using double precision real values in your programming as far as the manipulation of results is concerned.

I.4.1.3 Identification of Result objects

Besides the mapping from key to values, the Result objects contain information that allows their identification. The identification information is:

• The name of the object (a String). This name can be set or retrieved with methods “Name=” and “Name”. These methods correspond to “Name” attribute.

• Two integer identifiers that may contain information like the load case id, the mode number,... These member data can set or retrieved with methods “setIntId” and “getIntId”.

• Two real identifiers that may contain information related to the time for a transient calculation, to continuation parameters, eigen-values,... These member data can be set or retrieved with methods “setRealId” and “getRealId”.

The methods used to access these member data are described in section I.4.6.1.

I.4.1.4 Other characteristics

A Result object is also characterized by two other integer values:

• The tensorial order of the values it stores. This integer may be 0, 1, 2 or -2 corresponding to scalar, vectorial, symmetric tensorial or non-symmetric tensorial values.

• The format of the result. This value may be 1 (Real values), 2 (Complex Result in rectangular format) or 3 (Complex Result in polar format).

Methods used to manipulate these data are described in section I.4.6.1. These two integers are attributes of the class.

I.4.1.5 Tensorial Results, symmetric or non-symmetric

Most Tensorial results manipulated with FeResPost are symmetric. In a few cases, non-symmetric tensors can be useful. This is for example the case when an orthogonal tensor corresponding to a rotation in space is used to transform vectorial or tensorial components. (See section X.B.6.) In fact, orthogonal rotation tensors are so far the only application we have in mind for the non-symmetric tensors available in FeResPost. When using these tensors, one must consider that:

• The “TensorOrder” associated to the Result object is -2.

• Only “real” Format makes sense for this kind of Result.

• As explained above the non-symmetric Result has 9 components.

• For an orthogonal tensor, in each value, the three vectors corresponding to the nine components must be mutually orthogonal and have unit lengths. FeResPost user is responsible for the compliance with this rule. (No check is done by FeResPost.)

• Non-symmetric Results can be used in only a limited number of operations.

“assembleTensorFrom3Vectors” singleton method in “Result” class is specific to the construction of Non-symmetric type of Results. This method has three vectorial Result arguments. The key-value pairs of the three Result arguments must match.

I.4.2 FeResPost Results’ characteristics

When Results are read from a Result output file produced by a solver (Part III), the information found in these Result files are used to produce Results with characteristics that are defined according to FeResPost conventions. These characteristics are related to Result naming conventions, Result tensor type, sign conventions, layer associations...

The Nastran solver is considered as the reference for FeResPost solver support. Therefore, the naming conventions and other characteristics defined in section III.1.2 are considered as the reference (default) FeResPost Result’s characteristics.

Note also that the subcase names associated to Nastran Results read from XDB, OP2 or HDF files are also considered as the reference for other solvers.

I.4.3 Extraction methods

The class “Result” defines several methods allowing the construction of a new Result object, or of a “ResKeyList” object from a previously existing Result by an appropriate selection on the keys. The extraction methods defined in class Result are defined in the following sections.

I.4.3.1 “extractResultOnEntities” method

“extractResultOnEntities” method is used to extract a sub-set of keys and values from an existing Result object. The method returns the newly created Result object. The method has up to four arguments:

1.

The “Method” argument is a String object specifying the algorithm to be used to select the keys and values to be inserted in the new Result object. Possible values of this argument are provided in Table I.4.6.

2.

The “Target” argument is a Group containing the elements and/or nodes used by some of the algorithms described above to select sub-sets of Results.

3.

The “LayersList” argument is an Array containing the list of layers on which the pairs of key and value must be extracted. If the Array is void, then data corresponding to all layers are extracted. If the Array is not void, the elements must be String or integer objects

4.

The “SubLayersList” argument is an Array containing the list of sub-layers on which the pairs of key and value must be extracted. If the Array is void, then data corresponding to all sub-layers are extracted. If the Array is not void, the elements must be String or integer objects

The two last arguments are optional. Note that the “Method” argument described above is the same as the “Method” argument of the DataBase member method “getResultCopy” described in section I.1.3. Please refer to that part of the manual for more information on valid extraction data.

This method works for Real as well as for Complex Results.

I.4.3.2 “extractResultOnLayers” method

“extractResultOnLayers” method is used to extract a sub-set of keys and values from an existing Result object. The method returns the newly created Result object. The method has one “LayersList” argument: it is an Array containing the list of layers on which the pairs of key and value must be extracted. The elements of the Array argument are integers or String values.

This method works for Real as well as for Complex Results.

I.4.3.3 “extractResultOnSubLayers” method

“extractResultOnSubLayers” method is used to extract a sub-set of keys and values from an existing Result object. The method returns the newly created Result object. The method has one “SubLayersList” argument: it is an Array containing the list of sub-layers on which the pairs of key and value must be extracted. The elements of the Array argument are integers or String values.

This method works for Real as well as for Complex Results.

I.4.3.4 “extractResultOnRkl” method

“extractResultOnRkl” method returns a Result object built by extraction of the values corresponding to the keys contained in the ResKeyList “Target” argument.

This method works for Real as well as for Complex Results.

I.4.3.5 “extractResultOnResultKeys” method

“extractResultOnResultKeys” method returns a Result object built by extraction of the values corresponding to the keys contained in the Result “Target” argument. (This method is very similar to “extractResultOnRkl” method, except that the target is given by a Result argument.)

This method works for Real as well as for Complex Results.

I.4.3.6 “extractResultOnRange” method

“extractResultOnRange” method returns a Result object built by extraction of the values selected by specifying a range. This method can be applied to scalar Result objects only as the range is specified by one or two Real values. The arguments of the method are:

1.

The “Method” String argument specifies the extraction algorithm that is used. Four values are possible:

• “below”: extraction of the values below the “LowerBound” Real argument value.

• “above”: extraction of the values above the “UpperBound” Real argument value.

• “between”: extraction of the values between the “LowerBound” and “UpperBound” Real argument value.

• “outside”: extraction of the values not between the “LowerBound” and “UpperBound” Real argument value.

2.

The “LowerBound” argument is a real value specifying the lower bound of the range. For some algorithms, this value may be unused and irrelevant.

3.

The “UpperBound” argument is a real value specifying the upper bound of the range. For some algorithms, this value may be unused and irrelevant.

This method works for Real Results only.

I.4.3.7 “extractResultForNbrVals” method

“extractResultForNbrVals” method returns a Result object built by extraction of maximum “NbrVals” values. This method can be applied to scalar Result objects only and has two arguments:

1.

The “Method” String argument specifies the extraction algorithm that is used. Two values are possible:

• “smallest” causes the method to keep the smallest values of the Result object.

• “largest” causes the method to keep the largest values of the Result object.

2.

“NbrVals” is an integer argument corresponding to the number of values to be kept.

This method works for Real Results only.

I.4.3.8 “extractResultMin” method

“extractResultMin” method returns a Result object built by extraction of the minimum value and corresponding key. This method can be applied to scalar Result objects only.

This method works for Real Results only.

I.4.3.9 “extractResultMax” method

“extractResultMax” method returns a Result object built by extraction of the maximum value and corresponding key. This method can be applied to scalar Result objects only.

This method works for Real Results only.

I.4.3.10 “extractRklOnRange” method

“extractRklOnRange” method works exactly as method “extractResultOnRange” described in section I.4.3.6 but returns a ResKeyList object instead of a Result object. This means that one returns only a list of keys, but not the associated values.

This method works for Real Results only.

I.4.3.11 “extractRklForNbrVals” method

“extractRklForNbrVals” method works exactly as method “extractResultForNbrVals” described in section I.4.3.7 but returns a ResKeyList object instead of a Result object. This means that one returns only a list of keys, but not the associated values.

This method works for Real Results only.

I.4.3.12 “extractRklMin” method

“extractRklMin” method returns a ResKeyList object built by extraction of the key corresponding to the minimum value. This method can be applied to scalar Result objects only.

This method works for Real Results only.

I.4.3.13 “extractRklMax” method

“extractRklMax” method returns a ResKeyList object built by extraction of the key corresponding to the maximum value. This method can be applied to scalar Result objects only.

This method works for Real Results only.

I.4.3.14 “extractRkl” method

“extractRkl” method returns a ResKeyList object built by extraction of all the keys of the Result object to which the method is applied.

This method works for Real as well as for Complex Results.

I.4.3.15 “extractGroupOnRange” method

“extractGroupOnRange” method works exactly as method “extractResultOnRange” described in section I.4.3.6 but returns a Group object instead of a Result object. The Group contains the element and node entities for which values in the specified range have been found.

This method works for Real Results only.

I.4.3.16 “extractGroupForNbrVals” method

“extractGroupForNbrVals” method works exactly as method “extractResultForNbrVals” described in section I.4.3.7 but returns a Group object instead of a Result object. The Group contains the element and node entities for which values in the specified range have been found.

This method works for Real Results only.

I.4.3.17 “extractGroup” method

“extractGroup” method returns a Group object containing the elements and nodes that are referenced in the Result object. This method has no argument.

This method works for Real as well as for Complex Results.

I.4.3.18 “extractLayers” method

“extractLayers” method returns an Array of String and integers corresponding to the layers that are referenced in the Result object. This method has no argument.

This method works for Real as well as for Complex Results.

I.4.3.19 “extractSubLayers” method

“extractSubLayers” method returns an Array of String and integers corresponding to the sub-layers that are referenced in the Result object. This method has no argument.

This method works for Real as well as for Complex Results.

I.4.4 Derivation monadic methods

All the methods presented in this section are devoted to the production of new results by performing operations on the values of the Result object to which they are applied. Each method produces Results with as many pairs “key-values” as in the Result object to which it is applied, but the number of components associated with each key may be different from the original number of components. Indeed, the original Result and derived Result have not necessarily a same tensor order.

Most of the methods presented below have only one argument: a Method String object corresponding to the algorithm of derivation. The use of the methods defined below leads sometimes to very heavy notations for simple or very often used operations. Therefore, short-cuts to some methods have been defined in the “Post” module (Chapter I.6).

I.4.4.1 “deriveScalToScal” method

“deriveScalToScal” method builds a new Result object by performing an operation on all the values of the Result object to which it is applied. Both Result objects correspond to scalar values. The Possible values of the “Method” argument are:

• “sin”: returns $sin<!--FUNCTION\; APPLICATION-->(\text{arg})$ (angle in radians).

• “cos”: returns $cos<!--FUNCTION\; APPLICATION-->(\text{arg})$ (angle in radians).

• “tan”: returns $tan<!--FUNCTION\; APPLICATION-->(\text{arg})$ (angle in radians).

• “asin”: returns ${sin<!--FUNCTION\; APPLICATION-->}^{-1}(\text{arg})$ (angle in radians).

• “acos”: returns ${cos<!--FUNCTION\; APPLICATION-->}^{-1}(\text{arg})$ (angle in radians).

• “atan”: returns ${tan<!--FUNCTION\; APPLICATION-->}^{-1}(\text{arg})$ (angle in radians).

• “exp”: returns $e^{\text{arg}}$.

• “log”: returns ${\text{log}}_e(\text{arg})$.

• “exp10”: returns $10^{\text{arg}}$.

• “log10”: returns ${\text{log}}_{10}(\text{arg})$.

• “abs”: returns $|\text{arg}|$.

• “inv”: returns $1∕\text{arg}$.

• “sinh”: returns $\text{sinh}(\text{arg})$.

• “cosh”: returns $\text{cosh}(\text{arg})$.

• “tanh”: returns $\text{tanh}(\text{arg})$.

• “sq”: returns ${\text{arg}}^2$.

• “sqrt”: $\sqrt{\text{arg}}$.

• “sgn”: +1, 0 or -1 depending on the value of argument (arg>0, arg==0 or arg<0 respectively).

The method works for Real Results as well as Complex Results. However, some of the methods are not available for Complex Results: “asin”, “acos”, “atan” and “sgn” can be used with Real Results only. Note that when used with a Complex Result object, the method returns a Complex Result object. There is however one exception to this rule: the “abs” derivation method returns a Real Result.

I.4.4.2 “deriveScalPerComponent” method

“deriveScalPerComponent” method builds a new Result object by performing a scalar operation on all the values of the Result object to which it is applied. The Result object can be scalar, vectorial or tensorial. In case, of vectorial or tensorial Result, the scalar operation is performed component-per-component, regardless of the coordinate system in which the values are expressed. The Possible values of the “Method” argument are the same as for deriveScalToScal method. The method works for Real Results only. (Complex Results are not accepted and an exception is raised.)

I.4.4.3 “deriveVectorToOneScal” method

“deriveVectorToOneScal” method builds a new Result object by performing an operation on all the values of the Result object to which it is applied. The Result object to which the method is applied must be vectorial. The created Result object is scalar. Possible values of the “Method” String argument are: