- I.4.1 The concept of ``Result''
- I.4.1.1 ``Keys''
- I.4.1.2 ``Values''
- I.4.1.3 Identification of Result objects
- I.4.1.4 Other characteristics

- I.4.2 Extraction methods
- I.4.2.1 ``Result.extractResultOnEntitiesextractResultOnEntities'' method
- I.4.2.2 ``Result.extractResultOnLayersextractResultOnLayers'' method
- I.4.2.3 ``Result.extractResultOnSubLayersextractResultOnSubLayers'' method
- I.4.2.4 ``Result.extractResultOnRklextractResultOnRkl'' method
- I.4.2.5 ``Result.extractResultOnResultKeysextractResultOnResultKeys'' method
- I.4.2.6 ``Result.extractResultOnRangeextractResultOnRange'' method
- I.4.2.7 ``Result.extractResultForNbrValsextractResultForNbrVals'' method
- I.4.2.8 ``Result.extractResultMinextractResultMin'' method
- I.4.2.9 ``Result.extractResultMaxextractResultMax'' method
- I.4.2.10 ``Result.extractRklOnRangeextractRklOnRange'' method
- I.4.2.11 ``Result.extractRklForNbrValsextractRklForNbrVals'' method
- I.4.2.12 ``Result.extractRklMinextractRklMin'' method
- I.4.2.13 ``Result.extractRklMaxextractRklMax'' method
- I.4.2.14 ``Result.extractRklextractRkl'' method
- I.4.2.15 ``Result.extractGroupOnRangeextractGroupOnRange'' method
- I.4.2.16 ``Result.extractGroupForNbrValsextractGroupForNbrVals'' method
- I.4.2.17 ``Result.extractGroupextractGroup'' method
- I.4.2.18 ``Result.extractLayersextractLayers'' method
- I.4.2.19 ``Result.extractSubLayersextractSubLayers'' method

- I.4.3 Derivation monadic methods
- I.4.3.1 ``Result.deriveScalToScalderiveScalToScal'' method
- I.4.3.2 ``Result.deriveScalPerComponentderiveScalPerComponent'' method
- I.4.3.3 ``Result.deriveVectorToOneScalderiveVectorToOneScal'' method
- I.4.3.4 ``Result.deriveVectorToVectorderiveVectorToVector'' method
- I.4.3.5 ``Result.deriveVectorToTensorderiveVectorToTensor'' method
- I.4.3.6 ``Result.deriveTensorToOneScalderiveTensorToOneScal'' method
- I.4.3.7 ``Result.deriveTensorToTwoScalsderiveTensorToTwoScals'' method
- I.4.3.8 ``Result.deriveTensorToThreeScalsderiveTensorToThreeScals'' method
- I.4.3.9 ``Result.deriveByRemappingderiveByRemapping'' method

- I.4.4 Dyadic derivation method
- I.4.5 Methods modifying the object
- I.4.5.1 Access to and modification of Result data
- I.4.5.2 ``Result.setRefCoordSyssetRefCoordSys''
- I.4.5.3 ``Result.renumberLayersrenumberLayers''
- I.4.5.4 ``Result.renumberSubLayersrenumberSubLayers''
- I.4.5.5 ``Result.removeLayersremoveLayers''
- I.4.5.6 ``Result.removeSubLayersremoveSubLayers''
- I.4.5.7 ``Result.modifyRefCoordSysmodifyRefCoordSys''
- I.4.5.8 ``Result.modifyPositionRefCoordSysmodifyPositionRefCoordSys''
- I.4.5.9 ``Result.setToCombilisetToCombili''

- I.4.6 Operators
- I.4.6.1 Addition operator
- I.4.6.2 Substraction operator
- I.4.6.3 Multiplication operator
- I.4.6.4 Division operator
- I.4.6.5 Exponent operator

- I.4.7 ``Result.calcResultingFMcalcResultingFM'' method
- I.4.8 Complex Results
- I.4.8.1 Rectangular-Polar conversions
- I.4.8.2 Conjugate Complex Result
- I.4.8.3 Rotation of Complex Result
- I.4.8.4 Extractions from Complex Results
- I.4.8.5 Assembling Complex from Real Results

- I.4.9 ``Result.getDatagetData''
- I.4.10 ``BLOBs''
- I.4.11 Iterators
- I.4.12 A few singleton (static) methods
- I.4.13 Other methods

I.4 The ``Result'' class

The ``Result'' class is devoted to the manipulation of finite element Results. Examples of Results are stress tensor on volumic or surfacic 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 comment must be done: *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.

(FeResPost list of classes is given in
Table 1
page .) |
||

Method Name |
Description |
Example |

Creation and initialization methods |
||

Result.newnew | I.4.13 | IV.2.4.6 |

Result.initializeinitialize | I.4.13 | |

Result.cloneclone | I.4.13 | IV.2.4.6 |

Manipulation of data |
||

Result.Name=Name= | I.4.5.1 | |

Result.NameName | I.4.5.1 | |

Result.clearDataclearData | I.4.5.1 | |

Result.getDatagetData | I.4.9 | IV.2.4.2 |

Result.SizeSize | I.4.13 | IV.2.4.1 |

Result.Format=Format= | I.4.5.1 | |

Result.FormatFormat | I.4.5.1 | |

Result.TensorOrder=TensorOrder= | I.4.5.1 | |

Result.TensorOrderTensorOrder | I.4.5.1 | |

Result.setIntIdsetIntId | I.4.5.1 | |

Result.getIntIdgetIntId | I.4.5.1 | |

Result.setRealIdsetRealId | I.4.5.1 | |

Result.getRealIdgetRealId | I.4.5.1 | |

Result.insertinsert | I.4.5.1 | |

Result.insertRklValsinsertRklVals | I.4.5.1 | |

Result.setComponentsetComponent | I.4.5.1 | |

Result.setRefCoordSyssetRefCoordSys | I.4.5.2 | |

Result.renumberLayersrenumberLayers | I.4.5.3 | |

Result.renumberSubLayersrenumberSubLayers | I.4.5.4 | |

Result.removeLayersremoveLayers | I.4.5.5 | |

Result.removeSubLayersremoveSubLayers | I.4.5.6 | |

Result.modifyRefCoordSysmodifyRefCoordSys | I.4.5.7 | IV.2.4.5 |

Result.modifyPositionRefCoordSysmodifyPositionRefCoordSys | I.4.5.8 | IV.2.5.2 |

Result.setToCombilisetToCombili | I.4.5.9 | |

Extraction methods |
||

Result.extractResultOnEntitiesextractResultOnEntities | I.4.2.1 | |

Result.extractResultOnLayersextractResultOnLayers | I.4.2.2 | |

Result.extractResultOnSubLayersextractResultOnSubLayers | I.4.2.3 | |

Result.extractResultOnRklextractResultOnRkl | I.4.2.4 | IV.2.4.2 |

Result.extractResultOnResultKeysextractResultOnResultKeys | I.4.2.5 | |

Result.extractResultOnRangeextractResultOnRange | I.4.2.6 | |

Result.extractResultForNbrValsextractResultForNbrVals | I.4.2.7 | |

Result.extractResultMinextractResultMin | I.4.2.8 | |

Result.extractResultMaxextractResultMax | I.4.2.9 | IV.2.4.2 |

Result.extractRklOnRangeextractRklOnRange | I.4.2.10 | |

Result.extractRklForNbrValsextractRklForNbrVals | I.4.2.11 | |

Result.extractRklMinextractRklMin | I.4.2.12 | |

Result.extractRklMaxextractRklMax | I.4.2.13 | |

Result.extractRklextractRkl | I.4.2.14 | IV.2.4.2 |

Result.extractLayersextractLayers | I.4.2.18 | |

Result.extractSubLayersextractSubLayers | I.4.2.19 | |

Result.extractGroupextractGroup | I.4.2.17 | |

Result.extractGroupOnRangeextractGroupOnRange | I.4.2.15 | |

Result.extractGroupForNbrValsextractGroupForNbrVals | I.4.2.16 | |

Derivation methods |
||

Result.deriveScalToScalderiveScalToScal | I.4.3.1 | IV.2.4.2 |

Result.deriveScalPerComponentderiveScalPerComponent | I.4.3.2 | IV.2.4.2 |

Result.deriveVectorToOneScalderiveVectorToOneScal | I.4.3.3 | IV.2.5.4 |

Result.deriveVectorToVectorderiveVectorToVector | I.4.3.4 | |

Result.deriveVectorToTensorderiveVectorToTensor | I.4.3.5 | |

Result.deriveTensorToOneScalderiveTensorToOneScal | I.4.3.6 | |

Result.deriveTensorToTwoScalsderiveTensorToTwoScals | I.4.3.7 | |

Result.deriveTensorToThreeScalsderiveTensorToThreeScals | I.4.3.8 | |

Result.deriveDyadicderiveDyadic | I.4.4 | |

Result.deriveByRemappingderiveByRemapping | I.4.3.9 | |

Global Force and Moment |
||

Result.calcResultingFMcalcResultingFM | I.4.7 | IV.2.5.3 |

Operators |
||

Result.++ | I.4.6.1 | |

Result.- | I.4.6.2 | |

Result.** | I.4.6.3 | IV.2.5.2 |

Result.// | I.4.6.4 | |

Result.**** | I.4.6.5 | |

BLOBs for SQL |
||

Result.toBlobtoBlob | I.4.10 | IV.2.6, VIII.1.5, VI.1.8 |

Result.fromBlobfromBlob | I.4.10 | |

Iterators |
||

Result.eacheach | I.4.11 | IV.2.4.4 |

Result.each_keyeach_key | I.4.11 | IV.2.4.5 |

Result.each_valueseach_values | I.4.11 | IV.2.4.5 |

Complex Results manipulation |
||

Result.set2RIset2RI | I.4.8.1 | IV.2.4.6 |

Result.set2MPset2MP | I.4.8.1 | IV.2.4.6 |

Result.conjugateconjugate | I.4.8.2 | |

Result.getRgetR | I.4.8.4 | IV.2.4.6 |

Result.getMgetM | I.4.8.4 | IV.2.4.6 |

Result.getIgetI | I.4.8.4 | IV.2.4.6 |

Result.getPgetP | I.4.8.4 | IV.2.4.6 |

Result.rotateByrotateBy | I.4.8.3 | |

Result.assembleComplexassembleComplex | I.4.8.5 | IV.2.4.6 |

A few singleton methods |
||

Result.layerStr2IntlayerStr2Int | I.4.12 | |

Result.layerInt2StrlayerInt2Str | I.4.12 | |

Result.subLayerStr2IntsubLayerStr2Int | I.4.12 | |

Result.subLayerInt2StrsubLayerInt2Str | I.4.12 | |

Attributes |
||

Result.NameName | I.4.5.1 | |

Other methods |
||

Result.to_sto_s | I.4.13 | |

Attributes |
||

Result.NameName | I.4.5.1 | |

Result.SizeSize | I.4.13 | (read only) |

Result.FormatFormat | I.4.5.1 | |

Result.TensorOrderTensorOrder | I.4.5.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).
- ...

- 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).

In Table I.4.4, the last layers IDs cannot be attributed to Result keys. The elements corresponds 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.

For unlayered Results | |

NONE |
-999 |

Undefined layer | |

UNDEF |
-300 |

For stress recovery in bars and beams | |

"PointA" | -201 |

"PointB" | -202 |

"PointC" | -203 |

"PointD" | -204 |

"PointE" | -205 |

"PointF" | -206 |

For 2D elements | |

"Z0"^{I.41} |
-100 |

"Z1" | -101 |

"Z2" | -102 |

For Results in laminates (positive layers) | |

"layer 1" | 1 |

"layer 2" | 2 |

"layer 3" | 3 |

"layer ..." | ... |

Group of layers for extraction operations | |

"Beam Points" | -2001 |

"Shell Layers" | -2002 |

"All Plies" | -2003 |

"All Layers" | -2004 |

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 peculiar 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.

The real values correspond to the components:

- A ``scalar'' Result has one component.
- A ``vectorial'' Result has three components named ``X'', ``Y'' and ``Z'' respectively.
- A ``tensorial'' Result 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''.

- First all the Real or Magnitude components are presented.
- Then all the Imaginary or Angular components follow. The angular components are expressed in (Nastran convention).

I.4.1.3 Identification of Result objects

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

- The name of the object (a String). This name can be set or retrieved with methods ``Result.Name=Name='' and ``Result.NameName''. 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 ``Result.setIntIdsetIntId'' and ``Result.getIntIdgetIntId''.
- Two real identifiers that may contain information related to the time for a transient calculation, to continuation parameters, eigen-values,... These member data can set or retrieved with methods ``Result.setRealIdsetRealId'' and ``Result.getRealIdgetRealId''.

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 or 2 corresponding to scalar, vectorial or (order 2) 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).

I.4.2 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.2.1 ``Result.extractResultOnEntitiesextractResultOnEntities'' method

This 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:

- 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:
- ``Elements'': all the values associated to the elements of Group ``Target'' are inserted in the values of the returned Result object. This means that the new Result contains both values at center of element and at corners.
- ``ElemCenters'': all the values associated to the elements of Group ``Target'' but not associated to any node are inserted in the values of the returned Result object. This means that the extraction returns only values at center of the elements.
- ``ElemCorners'': all the values associated to the elements of Group ``Target'' and associated to any node are inserted in the values of the returned Result object. The extraction returns only values at corner of the elements. Note that the list of nodes of the ``Target'' Group is irrelevant for this extraction operation.
- ``Nodes'': all the values associated to the nodes of Group ``Target'' are inserted in the values of the returned Result object.
- ``NodesOnly'': all the values associated to the nodes of Group ``Target'' but associated to no elements are inserted in the values of the returned Result object.
- ``ElemNodes'': all the values associated to the elements of Group ``Target'' AND to the nodes of the same Group are inserted in the values of the returned Result object. This means that the new Result contains only values at corners of elements.

- 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.
- 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
- 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

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

I.4.2.2 ``Result.extractResultOnLayersextractResultOnLayers'' method

This 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.2.3 ``Result.extractResultOnSubLayersextractResultOnSubLayers'' method

This 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.2.4 ``Result.extractResultOnRklextractResultOnRkl'' method

This method returns a Result object build 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.2.5 ``Result.extractResultOnResultKeysextractResultOnResultKeys'' method

This method returns a Result object build by extraction of the values corresponding to the keys contained in the Result ``Target'' argument. (This method is very similar to ``Result.extractResultOnRklextractResultOnRkl'' method, except that the target is given by a Result argument.)

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

I.4.2.6 ``Result.extractResultOnRangeextractResultOnRange'' method

This method returns a Result object build 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:

- 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.

- The ``LowerBound'' argument is a real value specifying the lower bound of the range. For some algorithms, this value may be unused and irrelevant.
- The ``UpperBound'' argument is a real value specifying the upper bound of the range. For some algorithms, this value may be unused and irrelevant.

I.4.2.7 ``Result.extractResultForNbrValsextractResultForNbrVals'' method

This method returns a Result object build by extraction of maximum ``NbrVals'' values. This method can be applied to scalar Result objects only and has two arguments:

- 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.

- ``NbrVals'' is an integer argument corresponding to the number of values to be kept.

I.4.2.8 ``Result.extractResultMinextractResultMin'' method

This method returns a Result object build 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.2.9 ``Result.extractResultMaxextractResultMax'' method

This method returns a Result object build 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.2.10 ``Result.extractRklOnRangeextractRklOnRange'' method

This method works exactly as method ``Result.extractResultOnRangeextractResultOnRange'' described in section I.4.2.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.2.11 ``Result.extractRklForNbrValsextractRklForNbrVals'' method

This method works exactly as method ``Result.extractResultForNbrValsextractResultForNbrVals'' described in section I.4.2.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.2.12 ``Result.extractRklMinextractRklMin'' method

This method returns a ResKeyList object build 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.2.13 ``Result.extractRklMaxextractRklMax'' method

This method returns a ResKeyList object build 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.2.14 ``Result.extractRklextractRkl'' method

This method returns a ResKeyList object build 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.2.15 ``Result.extractGroupOnRangeextractGroupOnRange'' method

This method works exactly as method ``Result.extractResultOnRangeextractResultOnRange'' described in section I.4.2.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.2.16 ``Result.extractGroupForNbrValsextractGroupForNbrVals'' method

This method works exactly as method ``Result.extractResultForNbrValsextractResultForNbrVals'' described in section I.4.2.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.2.17 ``Result.extractGroupextractGroup'' method

This 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.2.18 ``Result.extractLayersextractLayers'' method

This 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.2.19 ``Result.extractSubLayersextractSubLayers'' method

This 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.3 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 to each key may be different than 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.3.1 ``Result.deriveScalToScalderiveScalToScal'' method

This 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 (angle in radians).
- ``cos'': returns (angle in radians).
- ``tan'': returns (angle in radians).
- ``asin'': returns (angle in radians).
- ``acos'': returns (angle in radians).
- ``atan'': returns (angle in radians).
- ``exp'': returns .
- ``log'': returns .
- ``exp10'': return .
- ``log10'': returns .
- ``abs'': returns .
- ``inv'': returns .
- ``sinh'': returns .
- ``cosh'': returns .
- ``tanh'': returns .
- ``sq'': returns .
- ``sqrt'': .
- ``sgn'': +1, 0 or -1 depending on the value of argument (arg>0, arg==0 or arg<0 respectively).

I.4.3.2 ``Result.deriveScalPerComponentderiveScalPerComponent'' method

This 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 Result.deriveScalToScalderiveScalToScal method. The method works for Real Results only. (Complex Results are not accepted and an exception is raised.)

I.4.3.3 ``Result.deriveVectorToOneScalderiveVectorToOneScal'' method

This 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:

- ``Component X'': returns the first component of the vector.
- ``Component Y'': returns the second component of the vector.
- ``Component Z'': returns the third component of the vector.
- ``abs'': returns .
- ``sq'': returns .

- The three ``Component'' methods produce a Complex scalar Result object.
- The method ``sq'' produces the scalar product of the vector
by its conjugate. This is a
*Real*scalar Result. - The method ``abs'' produces the square root of the ``sq''
method. This is also a
*Real*scalar Result.

I.4.3.4 ``Result.deriveVectorToVectorderiveVectorToVector'' method

This 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 vectorial too. Possible values of the ``Method'' String argument are:

- ``normalize'': normalizes the vectorial values.

I.4.3.5 ``Result.deriveVectorToTensorderiveVectorToTensor'' method

This 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 tensorial too. Possible values of the ``Method'' String argument are:

- ``extSquare'': builds a tensor from a vector by calculating the
external product of the vector by himself. More precisely:

I.4.3.6 ``Result.deriveTensorToOneScalderiveTensorToOneScal'' method

This 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 tensorial. The created Result object is scalar. Possible values of the ``Method'' String argument are:

- ``Component XX'': returns the corresponding component of the tensor.
- ``Component XY'': returns the corresponding component of the tensor.
- ``Component XZ'': returns the corresponding component of the tensor.
- ``Component YX'': returns the corresponding component of the tensor.
- ``Component YY'': returns the corresponding component of the tensor.
- ``Component YZ'': returns the corresponding component of the tensor.
- ``Component ZX'': returns the corresponding component of the tensor.
- ``Component ZY'': returns the corresponding component of the tensor.
- ``Component ZZ'': returns the corresponding component of the tensor.
- ``VonMises'': returns the equivalent Von Mises stress assuming that the tensorial Result is a stress.
- ``MaxShear'': returns the maximum shear evaluated from the maximum and minimum principal values according to Mohr's theory.
- ``MaxPrincipal'': returns the maximum principal value.
- ``MinPrincipal'': returns the minimum principal value.
- ``det'' or ``abs'': returns the determinant of the tensor.
- ``2DMaxShear'': returns the maximum shear evaluated from the maximum and minimum principal values according to Mohr's theory, assuming that the tensor is a 2D tensor (all components ).
- ``2DMaxPrincipal'': returns the maximum principal value assuming that the tensor is a 2D tensor (all components ).
- ``2DMinPrincipal'': returns the minimum principal value assuming that the tensor is a 2D tensor (all components ).
- ``VonMises2D'': returns the equivalent Von Mises stress assuming that the tensorial Result is a stress. The calculation is done considering that Szz, Sxz and Syz components are zero. (It is user's responsibility to make sure that the stress tensor is expressed in a coordinate system such that the call to method makes sense.)

I.4.3.7 ``Result.deriveTensorToTwoScalsderiveTensorToTwoScals'' method

This method returns an Array of two Result objects derived from the tensorial Result object on which the method is applied. The returned Results are scalar. Possible values of the ``Method'' String argument are:

- ``Principals2D'': returns the principal values of a tensorial Result assuming that the tensor is a 2D tensor (all components ). The first Result contains minimum principal values, and the second Result contains maximum principal Values.
- ``PrincipalsMinMax'': returns the minimum and maximum principal values of a tensorial Result. The first Result contains minimum principal values, and the second Result contains maximum principal Values.

I.4.3.8 ``Result.deriveTensorToThreeScalsderiveTensorToThreeScals'' method

This method returns an Array of three Result objects derived from the tensorial Result object on which the method is applied. The returned Results are scalar. Possible values of the ``Method'' String argument are:

- ``Principals'': returns the principal values of a tensorial Result sorted by order of increasing values. (First Result contains minimum principal values, second Result corresponds to second principal value, and third Result contains the maximum principal values.)

I.4.3.9 ``Result.deriveByRemappingderiveByRemapping'' method

This method returns a Result object obtained by remapping the values of the Result object to which the method is applied. This method takes three parameters:

- ``FromTo'': a String object specifying the correspondence
between the keys of the old Result object and the keys of the new
Result object. Eleven different values of the ``FromTo'' argument are
allowed:
- ``CentersToCorners'': one selects all the values at center
of elements (
*i.e.*the key of which has an elemId, but no nodeId), then one produce a new Result object with values associated to the corners of those elements. - ``CentersToNodes'': one selects all the values at center
of elements (
*i.e.*the key of which has an elemId, but no nodeId), then one produce a new Result object with values associated to the nodes of those elements (*i.e.*the key of which has no elemId but has a nodeId). - ``NodesToCenters'': one selects all the values associated to nodes and produces a new Result in which the values are associated to the centers of the elements.
- ``NodesToCorners'': one selects all the values associated to nodes and produces a new Result in which the values are associated to the corners of the elements.
- ``CornersToCenters'': one selects all the values
associated to corners (
*i.e.*the key of which has both an elemId and a nodeId), and one builds a Result object with values associated to the center of elements. - ``CornersToNodes'': one selects all the values
associated to corners (
*i.e.*the key of which has both an elemId and a nodeId), and one builds a Result object with values associated to the corresponding nodes. - ``MergeLayers'': one produces a Result object in which
for each pair of Element, Node and SubLayer only one Layer is kept. The
layerId of each key of the produced Result object is kept
uninitialized (
*i.e.*set to -1). - ``MergeLayersKeepId'': one produces a Result object in which for each pair of Element, Node and SubLayer only one Layer is kept. The layerId of each key of the produced Result object is the one of the selected key-value of the original Result. For this option only ``min'' and ``max'' selection methods are accepted.
- ``MergeSubLayers'': one produces a Result object in which
for each pair of Element, Node and Layer only one SubLayer is kept. The
subLayerId of each key of the produced Result object is kept
uninitialized (
*i.e.*set to 0). - ``MergeSubLayersKeepId'': one produces a Result object in which for each pair of Element, Node and Layer only one SubLayer is kept. The subLayerId of each key of the produced Result object is the one of the selected key-value of the original Result. For this option only ``min'' and ``max'' selection methods are accepted.
- ``MergeAll'' merges all the keys and produces a Result object with a single ``key-value'' pair. The ``sum'', ``average'', ``min'' and ``max'' selection methods are accepted.

- ``CentersToCorners'': one selects all the values at center
of elements (
- ``Method'': a String object used to specify the way values
associated to different keys are merged into a single value (if this
happens). An example of situation in which the case may occur is for
example when one uses the ``NodesToCenters'' option and that the
values of several nodes are merged into the value of a single
element. Five values of ``Method'' argument are allowed:
- ``average'': each merged value is defined as the average of its different contributions.
- ``sum'': each merged value is defined as the sum of its different contributions.
- ``min'': one keeps the smallest value. This option can be used for scalar Results only.
- ``max'': one keeps the largest value. This option can be used for scalar Results only.
- ``NONE'': this option is used when one is sure that no merging of several values is possible.

- ``DB'': a DataBase object used by the method to recover the association of node and elements. This association is often needed to perform the remapping.

I.4.4 Dyadic derivation method

Presently, only one such method is defined: the ``Result.deriveDyadicderiveDyadic'' method. This method returns a new Result object corresponding to the dyadic derivation. This method has two arguments:

- The ``Method'' String argument corresponds to the name of the dyadic method that is used for the calculation of new Result's values.
- The ''Second'' argument can be a Result object or a real value. The Result object is always a valid argument if its tensor order is compatible of the operation being performed. The ``real'' argument is valid only if the invoked method is ``atan2'' or ``pow''.

- ``atan2'' performs the ``atan2'' operation on its argument values ( ). The object on which the method is called must be a scalar Result object. The ``Second'' argument must be either a scalar Result or a real value. For a real argument, one calculates
- ``pow'' performs the ``pow'' operation on its argument ( ). The object on which the method is called must be a scalar Result object. The ``Second'' argument must be either a scalar Result or a real value. For a real argument, one calculates for each .
- ``vectProduct'' calculates the vectorial product of its
arguments. Several types of arguments are accepted:
- The two arguments are vectorial Result objects. Then, .
- The second argument can be replaced by a vector (Array of three real elements). Then, one calculates .
- The first argument can be replaced by a vector (Array of three real elements) or a complex vector (Array of three complex elements). Then, .

- ``sumVectProduct'' calculates the sum of the vectorial product of its arguments: . The two arguments are vectorial Result objects.
- ``min'' keeps the minimum of the two values. Values must be Real. If the arguments are not scalar, they must have common tensorial order, and for each key-value pair, the coordinate system ID of the arguments must match. Then, the derivation is done component per component.
- ``max'' keeps the maximum of the two values. Values must be Real. If the arguments are not scalar, they must have common tensorial order, and for each key-value pair, the coordinate system ID of the arguments must match. Then, the derivation is done component per component.
- ``compare'' sets the value of new Result to -1, 0 or 1 depending on the relative first and second values. Values must be scalar and Real.
- ``merge'' or ``mergeKeepFirst'' keeps the value of the first Result if a given key is present in the two values. Otherwise the pair key-value of the second Result is kept.
- ``mergeKeepLast'' keeps the value of the second Result if a given key is present in the two values. Otherwise the pair key-value of the first Result is kept.

The different methods listed above are available for real Results. For Complex Results, only the methods ``vectProduct'', ``sumVectProduct'', ``merge'', ``mergeKeepFirst'' and ``mergeKeepLast'' can be used. Of course, if the ''Second'' argument is a Real object, the ``deriveDyadic'' method cannot be invoked on a Complex Result object.

Note also that all the dyadic derivation methods discussed here are invoked on a Result object which is the first argument. Dyadic derivation methods that allow to replace the first argument by a real or vector object are also defined in the Post module. (See section I.6.3.)

I.4.5 Methods modifying the object

One presents here methods that modify the Result object to which they are applied.

I.4.5.1 Access to and modification of Result data

Each Result object is also characterized by two integer and two real identifiers. Different methods allow to retrieve or modify the Result data.

- ``Result.NameName'' returns a String containing the name of the Result.
The method has no argument.
- ``Result.Name=Name='' has one String argument and sets the name of the
Result.
- ``Result.FormatFormat'' returns an integer corresponding to the format of
the Result (1="Real", 2="Real-Imaginary", 3="Magnitude-Phase").
- ``Result.Format=Format='' has one integer argument and sets the format of the
Result object. (Same possible values as for ``Format'' attribute ``getter''.)
- ``Result.TensorOrderTensorOrder'' returns an integer corresponding to the tensorial
order of the Result.
- ``Result.TensorOrder=TensorOrder='' has one integer argument and sets the tensorial
order of the object.
- ``Result.clearDataclearData'' has no argument and clears the keys and values stored in a
Result object.
- ``Result.insertinsert'' has two Array arguments corresponding to a result::key
and a result::values respectively:
- The ``Key'' argument is an Array of between 1 and 4 elements corresponding to element, node and layer identifiers respectively. These elements can be of String or integer types.
- The ``Values'' argument is an Array of elements the number of which depends on the tensorial order of the Result object that is filled. (This tensorial order must have been defined already.) The first element of the Array is always the coordinate system identifier (a String or integer object). The other elements of the Array are Real values corresponding to the components.

- ``Result.insertRklValsinsertRklVals'' has two arguments corresponding to a
ResKeyList object and a result::values object respectively:
- The ``Rkl'' is a ResKeyList object containing the list of keys for which values are inserted. This argument can be replaced by a Result object; then, only the keys of the Result are used for insertion of data.
- The ``Values'' is the same argument as in ``Result.insertinsert'' method described above. Note that one inserts identical values for the different keys of the ``Rkl'' ResKeyList object.

- ``Result.setComponentsetComponent'' has two or three arguments and allows to modify
a selected component of the values stored in the Result object on which the
method is called:
- If the method has three arguments:
- The first ``oComp'' argument is an integer corresponding to the index of the component that shall be modified.
- The second ``inRes'' argument is a Result object from which the new component values are read.
- The third ``iComp'' argument is an integer corresponding to the index of the component that is read from the ``inRes'' Result object.

- If the method has two arguments:
- The first ``oComp'' argument is an integer corresponding to the index of the component that shall be modified.
- The second ``fValue'' argument is a real value corresponding to the new component value.

- If the method has three arguments:
- ``Result.setIntIdsetIntId'' has two arguments: the index of integer ID to be
set, and its new value.
- ``Result.getIntIdgetIntId'' has one argument: the index of integer ID that is to
be retrieved.
- ``Result.setRealIdsetRealId'' has two arguments: the index of real ID to be
set, and its new value.
- ``Result.getRealIdgetRealId'' has one argument: the index of real ID that is to be retrieved.

All these methods can be used with Real Results as well as with Complex Results.

I.4.5.2 ``Result.setRefCoordSyssetRefCoordSys''

``setRefCoordSys'' is used to attribute a reference coordinate system to the values of a Result. The method has one argument that can have to types:

- An integer corresponding to the integer ID of the associated coordinate system.
- A String corresponding to the names of peculiar coordinate systems. The possible values for the String are ``NONE'', ``userCS'', ``projCS'', ``elemCS'', ``nodeCS'', ``matCS'', ``plyCS'' and ``elemIJK''.

This method can be used with Real Results as well as with Complex Results.

I.4.5.3 ``Result.renumberLayersrenumberLayers''

``renumberLayers'' is a method used to renumber the layer integer ids of Result keys. The method has one Hash argument corresponding to the pairs of ``old integers IDs'' and ``new integer IDs''.

This method can be used with Real Results as well as with Complex Results.

I.4.5.4 ``Result.renumberSubLayersrenumberSubLayers''

``renumberSubLayers'' is a method used to renumber the sub-layer integer ids of Result keys. The method has one Hash argument corresponding to the pairs of ``old integers IDs'' and ``new integer IDs''.

This method can be used with Real Results as well as with Complex Results.

I.4.5.5 ``Result.removeLayersremoveLayers''

``removeLayers'' is a method used to remove pairs of key and values selected on the basis of the layer ID of the key. The method has one ``LayersList'' argument: it is an Array containing the list of layers for which the pairs of key and value must be removed. The elements of the Array argument are integer or String values.

This method can be used with Real Results as well as with Complex Results.

I.4.5.6 ``Result.removeSubLayersremoveSubLayers''

``removeSubLayers'' is a method used to remove pairs of key and values selected on the basis of the layer ID of the key. The method has one ``SubLayersList'' argument: it is an Array containing the list of sub-layers for which the pairs of key and value must be removed. The elements of the Array argument are integer or String values.

This method can be used with Real Results as well as with Complex Results.

I.4.5.7 ``Result.modifyRefCoordSysmodifyRefCoordSys''

``modifyRefCoordSys'' is used to modify the reference coordinate system wrt which the components of a vectorial or a tensorial Result are applied. If the Result is vectorial it can represent any vectorial quantities except the coordinates. For coordinate vectorial Result, the method ``Result.modifyPositionRefCoordSysmodifyPositionRefCoordSys'' must be used. This method has no effect on scalar Results.

The methods returns nil (no new Result object is created) and takes two, three or five arguments:

- A DataBase object.
- An object corresponding to the definition of the coordinate
system to which one switches. This object may have different types:
- A String object with one of the following values: ``elemCS'',
``nodeCS'', ``matCS'', ``plyCS'', ``elemIJK'', ``lamCS''. All
those coordinate systems are local to an element or to a node.
More information about the peculiarities of ``matCS'', ``plyCS'' and ``lamCS'' coordinate system transformations is given in section IX.B.5.

- The argument may by a CoordSys object. Then it must be defined wrt a coordinate system defined in the DataBase argument.
- The argument may also be an integer larger than or equal to 0. Then the coordinate system must be defined in the DataBase.

- A String object with one of the following values: ``elemCS'',
``nodeCS'', ``matCS'', ``plyCS'', ``elemIJK'', ``lamCS''. All
those coordinate systems are local to an element or to a node.
- The third argument is the direction vector used to build the projected coordinate system on surfacic elements. The vector is given by an Array of three real objects, and is expressed wrt to the coordinate system given in second argument. If one does not wish to transform into a projected coordinate system, then the third argument must be omitted or nil. (However if arguments 4 and 5 are provided, the third argument cannot be omitted.)
- An object corresponding to the definition of the coordinate system from which one switches. This object may have the same values as the second argument.
- The last argument is a direction vector used to build the projected coordinate system on surfacic elements. The vector is given by an Array of three real objects, and is expressed wrt to the coordinate system given in second argument. If one does not wish to transform into a projected coordinate system, then the third argument must be nil.

Note that some transformation vectorial or tensorial coordinate systems cannot be reversed. For example, once a Result is expressed in a projected coordinate system. Also, if a conversion has been done in a coordinate system that is not defined in the DataBase, the conversion is impossible. After transformation, the coordinate system referenced in Result values is altered (section I.4.1.2).

If arguments 4 and 5 are provided, the method assumes that the values are expressed in that coordinate system definition. This means that the CsId found in each pair ``key-values'' pair of the Result object is totally disregarded. The use of arguments 4 and 5 may allow the modification of Results expressed in a user or projected coordinate system.

More information on the transformation of coordinate systems is given in section IX.B.4.

This method can be used with Real Results as well as with Complex Results.

I.4.5.8 ``Result.modifyPositionRefCoordSysmodifyPositionRefCoordSys''

``modifyPositionRefCoordSys'' is used to modify the reference coordinate system wrt which vectorial Results corresponding to coordinates are expressed. The Results must be vectorial.

The method returns nil (no new Result object is created) and takes two arguments:

- A DataBase object.
- An integer object corresponding to the index of the coordinate system to which one switches. This index must be larger than or equal to 0 and defined in the DataBase argument. One can also provide a CoordSys object instead of the integer argument.

This method can be used with real Results only.

I.4.5.9 ``Result.setToCombilisetToCombili''

The method fills the values of the Result object on which the method is called with the linear combination of the elementary Results given as arguments. The arguments are defined as follows:

- An Array of Real values containing the factors of the linear combination.
- An Array containing the elementary Results.

This method can be used with Real Results as well as with Complex Results. Also, the real factors of the linear combination can be replaced by Complex values. However, all the elements of the Array must be of the same type (Real or Complex).

I.4.6 Operators

Five elementary operators on Result objects have been defined. Also, their corresponding assignment method have been defined. Unless otherwise specified, in the examples given below, , and are Result objects. One of the two operands can be replaced by a ``constant'' value in most cases, but at least one of the operands must be a Result object:

By ``constant'' value, one means a scalar real value, a scalar complex value, a real vector (Array of three real values), a complex vector (Array of three complex elements), or a real matrix (Array of real values). These arguments can be used in addition, substraction and multiplication operations. Note that no constant complex matrix is supported.

For the division operation, can be replaced by a scalar real or complex argument, but not by a vector or a matrix. on the other hand, can be replaced by constant scalar, vectorial or matrix, real or complex (except for the matrix).

For the exponentiation operator, the two Results must be scalar. Either or can be replaced by a constant real value.

One can make a few general remarks:

- When the two arguments are vectorial or tensorial Results, the coordinate system ids must be the same for each corresponding values.
- The coordinate system associated to the values of the constructed
Result
is defined according the following rules:
- For a scalar Result , the cId is always set to -9999 (Result not associated to a coordinate system).
- For a vectorial or tensorial Result, the coordinate system for each value is set to the corresponding coordinate systems of the vectorial or tensorial arguments.
- When it is not possible to determine the Result coordinate system according to the preceding rules, the CID is set to 0 for all values. An example of such a case is the division of an Array by a scalar Result.

- The operators are defined in the Result class. This means that the
first operand must be a Result object. However, to the different operators
defined in Result class corresponding ``operator'' methods defined the ``Post''
module. Several of the ``Post'' methods allows to replace the first operand
by a real object or an Array. (See section I.6.4.)
Note that this rule does not apply to the .NET assembly that allows the first operand of the different operators to be replaced by constant values.

I.4.6.1 Addition operator

The addition operator can be used as follows:

In the previous expression, the Results and must have the same tensorial order. Of course, the returned object is also of the same tensor order as and .

I.4.6.2 Substraction operator

The substraction operator can be used as follows:

In the previous expression, the Results and must have the same tensorial order. Of course, the returned object is also of the same tensor order as and .

I.4.6.3 Multiplication operator

The multiplication operator can be used as follows:

The meaning of this operation depends on the tensorial orders of and . The various possibilities are summarized in Table I.4.6 with a short explanation of the meaning of the operation when deemed necessary.

meaning | |||

S | S | S | -- |

V | S | V | -- |

M | S | M | -- |

V | V | S | -- |

S | V | V | scalar product of two vectors |

V | V | M | left multiplication of a matrix by a vector |

M | M | S | -- |

V | M | V | right multiplication of a matrix by a vector |

I.4.6.4 Division operator

The division operator can be used as follows:

In the last expression can have any tensorial order. The tensorial order of the returned Result is identical to the tensorial order of . The argument can be either a scalar Result object, or a real value.

Complex Results are partially supported by the division operator. The limitations of the operator for complex arguments are the same as for the multiplication operator.

I.4.6.5 Exponent operator

The exponentiation operator can be used as follows:

In the last expression must be a scalar Result. The tensorial order of the returned Result is identical to the tensorial order of . The argument can be either a scalar Result object, or a real value. Complex Results cannot be arguments to this operator. The real values of first Result argument must also be positive.

The two following expressions are equivalent:

z=x**y z=Post.pow(x,y)

I.4.7 ``Result.calcResultingFMcalcResultingFM'' method

This is a __class method__ used to estimate the total force and
moment corresponding to a distribution of forces and moments on several
points. The method has between 4 and 6 arguments:

- A DataBase object containing the model used to calculate the total forces and moments.
- A first Result object corresponding to the vectorial forces.
- A second Result object corresponding to the vectorial moments.
- An object corresponding to the coordinate system in which results and position of recovery point are expressed. If the argument is an integer, it must correspond to the index of a CoordSys object defined in the dataBase. The argument can also be a CoordSys object, but its definition must refer a coordinate system defined in the dataBase.
- A vector (Array of three real values)
corresponding to the position of the point wrt which the total force
and moment are calculated.
*The position of the point is defined wrt the coordinate system corresponding to the previous argument.*(This may different than what other post-processing tools like Patran do.) - A Result object corresponding to the coordinates of the connections that are used to estimate the global moment. (See additional remarks below.)

- If argument 5 is omitted, the method assumes that the recovery point is located on the origin of the coordinate system.
- I argument 6 is omitted, the nodal coordinates are used to estimate the global moment
corresponding to the nodal forces (

db.generateCoordResults("COORDS","COORDS","coords")The coordinates corresponding to the forces can be obtained as follows:

coords=db.getResultCopy("COORDS","COORDS","coords",forces.extractRkl())And the global force and moment calculated as follows:

fm=Result::calcResultingFM(db,forces,moments,csId,nil,Coords)

If argument Results are in Real format, the method returns an Array containing two vectors (i.e. two Arrays of Real objects). These vectors correspond to the total force and total moment respectively. Note that the method produces no new Result object.

If argument Results are Complex, the method returns an Array containing two Complex vectors (i.e. two Arrays of Complex objects). Note However that the Complex values in the resultants are always given in rectangular format (real and imaginary parts). This is true even when the argument Results are in polar (magnitude-phase) format.

I.4.8 Complex Results

Several methods correspond to operations specific to complex Results. These methods are described below.

I.4.8.1 Rectangular-Polar conversions

Two methods allow to tranform Complex Results expressed in real-imaginary format to magnitude-phase format, and reversely:

- ``Result.set2RIset2RI'' produces a complex Result in rectangular (real-imaginary) format. The method has 0 or 1 argument. If the method has one argument, the object on which the method is called is set to the rectangular complex values of its argument. Otherwise, the object on which the methods is called is modified.
- ``Result.set2MPset2MP'' produces a Complex Result in polar (magnitude-phase) format. The method has the same characteristics as ``Result.set2RIset2RI''.

I.4.8.2 Conjugate Complex Result

``Result.conjugateconjugate'' produces a Result by initializing its values to conjugate of other values ( ). The method has 0 or 1 argument. If the method has one argument, the object on which the method is called is set to the rectangular complex values of its argument. Otherwise, the object on which the methods is called is modified. Note that the method can also be called on a Real Result but has then no effect.

I.4.8.3 Rotation of Complex Result

The method ``Result.rotateByrotateBy'' is used to modify the values of a Complex Result by adding an angle specified in degrees to the corresponding phases. However, the method can be used indifferently with Complex Results in rectangular or in polar formats. The method may have one or two arguments:

- If the method has only one argument, it is the angle that is added to the phase. The modified argument is the Result object on which the method is called.
- If the method has two arguments, the first one is a Result object, and the second one is the rotation angle in degrees. Then the Result object on which the method is applied is initialized to the rotated argument Result object.

Angle is always given in .

I.4.8.4 Extractions from Complex Results

Four methods produce Real Results from Complex Results by extracting the appropriate components:

- ``Result.getRgetR'' returns the ``Real'' components of the Result.
- ``Result.getMgetM'' returns the ``Magnitude'' components of the Result.
- ``Result.getIgetI'' returns the ``Imaginary'' components of the Result.
- ``Result.getPgetP'' returns the ``Phase'' components of the Result.

The two methods ``Result.getRgetR'' and ``Result.getIgetI'' may have an optional Real argument that correspond to a rotation applied to the Result before extracting the Real or Imaginary component Result. More precisely, each component of each value is multiplied by before extracting the real or imaginary component. Angle is always given in . Note that the Result on which the method is called is left unmodified.

I.4.8.5 Assembling Complex from Real Results

The ``Result.assembleComplexassembleComplex'' method is used to assemble a Complex Result object from two Real Results. The method is called on a Result object and has three arguments:

- An integer corresponding to the format of the new Complex Result. The accepted values are 2 (real-imaginary or rectangular format) or 3 (polar or magnitude-phase format).
- A first Result object that will correspond to the real or magnitude components of the assembled Result.
- A second Result object that will correspond to the imaginary of phase components of the assembled Result.

- They must be Real Results.
- They must have the same number of key-values pairs, with exact key matches.
- Their values must have the same number of components.
- When one pair of value objects are merged, their Coordinate System IDs must be the same.

resR=res2.getR resI=res2.getI resRI=Result.new resRI.assembleComplex(2,resR,resI)(At the end,

`resRI`

should be the same as `res2`

.)

I.4.9 ``Result.getDatagetData''

The method returns an Array of Arrays containing the data stored in a Result object. The returned Array may actually be considered as a two-dimensional Array with as many lines as there are pairs of key-value in the Result object. Each line of the Array contains five, seven or ten elements:

- The first element corresponds to the elemId.
- The second element corresponds to the nodeId of the key.
- The third element corresponds to the layerId of the key.
- The fourth element corresponds to the subLayerId of the key.
- The fifth element corresponds to the coordinate system in which the value components are associated. The possible values are summarized in Table I.4.7.
- The other elements are real values corresponding to the components (1, 3 or 6 values for a scalar, vectorial or tensorial Result respectively). For the precise meaning of the returned value corresponding to coordinate system, see also section I.4.1.2.

For element, node and layer ids, the negative values correspond to ``special'' values. (See Tables I.4.2 to I.4.4.)

integer in C++ ``value'' class | returned value in ruby |

-9999 | nil |

-2000 | "userCS" |

-1000 | "projCS" |

-5 | "elemIJK" |

-4 | "plyCS" |

-3 | "matCS" |

-2 | "nodeCS" |

-1 | "elemCS" |

any other integer | the same integer |

I.4.10 ``BLOBs''

Result objects can be saved in SQL database as ``BLOB'' objects.

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

- ``Result.toBlobtoBlob'' has no argument and returns the BLOB in a String object.
- ``Result.fromBlobfromBlob'' has one String argument corresponding to the BLOB, and initializes the Result according to Blob content.

I.4.11 Iterators

Three iterators are defined in the class:

- ``Result.eacheach'' iterates on the data and produces pairs of key and values. Each key is an Array of four elements, and each ``values'' and Array of 2 to 7 elements. The iterator may have between 0 and 5 arguments. The arguments are Strings that specify whether some of the data are to be returned in String or integer format. The consecutive arguments correspond to the formatting of element id, node id, layer id, sub-layer id and coordinate system id.
- ``Result.each_keyeach_key'' iterates on the data and produces Arrays of three elements corresponding to keys. The iterator may have between 0 and 4 argument. The arguments are Strings that specify whether some of the data are to be returned in String or integer format.
- ``Result.each_valueseach_values'' iterates on the data and produces Arrays of 2 to 7 elements. The iterator may have 1 or no String argument specifying the Type of the element corresponding to the coordinate system identifier.

strain.each("int","int","int") do |key,values| ... end ... strain.each("int","int","string","string") do |key,values| ... endNote that, as the ``Result.each_keyeach_key'' and ``Result.each_valueseach_values'' iterators return Arrays, one can indifferently recover an Array argument, or its elements in the arguments of the block that follows the iterator. For example, in the following lines:

stress.each_key do |stressKey| ... end``stressKey'' is an Array of three elements. However in the following lines:

stress.each_key("int","int","int") do |elemId,nodeId,layerId| ... endthe arguments correspond to the different identifiers of the Result key.

I.4.12 A few singleton (static) methods

Four singleton methods allow to convert layers and sub-layers string/integer IDs:

- ``Result.layerStr2IntlayerStr2Int'' converts a layer name to its corresponding layer integer ID.
- ``Result.layerInt2StrlayerInt2Str'' converts a layer integer ID to the corresponding name (String).
- ``Result.subLayerStr2IntsubLayerStr2Int'' converts a sub-layer name to its corresponding layer integer ID.
- ``Result.subLayerInt2StrsubLayerInt2Str'' converts a sub-layer integer ID to the corresponding name (String).

I.4.13 Other methods

One gives here a list of methods that do not fit in any category listed above.

This method is used to create a new Result object.

This method initializes or clears a Result object.

This method returns a Copy of the Result object to which it is applied.

this method is used to initialize a Result with zero values using the keys of an existing Result object. The Method has four arguments:

- A String corresponding to the Name of the Result.
- An integer corresponding to the tensor order (0, 1 or 2).
- An integer corresponding to the Format of the Result.
- A Result object that provides the keys to which the zero values of the new Result object will be associated.

Returns an integer containing the numbers of pairs ``key-value'' contained in the Results object. This method has no argument. It corresponds to the ``Size'' read-only attribute.

This method is used for printing the Result object.