N2PGetFasteners User Manual#

Overview#

N2PGetFasteners is a NaxToPy module which provides geometrical information about fasteners in a model. It can be used individually in order to identify joints in a model or used before the N2PGetLoadFasteners class, which provides information about the loads that fasteners experience.

Example usage#

1. Importing the module#

import NaxToPy as NP 
from NaxToPy.Modules.Fasteners.N2PGetFasteners import N2PGetFasteners 

2. Load the model#

model = NP.load_model(r"file path")

3. Define elements#

element_list = [(57510018, '0'), (57510014, '0')] # List of elements as a tuple of element ID - part name 
n2pelem = model.get_elements(element_list) 

Warning

Introducing a list of elements is not compulsory, but recommended. If this attribute is not selected, all fasteners will be analyzed.

4. Create and configure N2PGetFasteners#

fasteners = N2PGetFasteners()
fasteners.Model = model 
fasteners.ElementList = n2pelem 

5. Run calculations#

fasteners.calculate() 

6. Access the results#

joints = fasteners.JointsList # List of all N2PJoint objects 
plates = fasteners.PlateList # List of all N2PPlate objects 
attachments = fasteners.AttachmentsList # List of all N2PAttachment objects 

7. Export results#

fasteners.ExportLocation = r"route.h5"
fasteners.export_fasteners()

For advanced usage, or extra information about the outputs of the class, see the sections below.

Setup#

Prerequisites#

Python Environment: Ensure you have a compatible Python environment with the following libraries:
- numpy
- NaxToPy modules
NaxToPy Framework: The module integrates with the NaxToPy library, which must be installed and configured in your environment.

Class Breakdown#

The class N2PGetFasteners provides geometrical information about fasteners in a model. There are four distinct elements (N2PJoints, N2PBolts, N2PPlates and N2PAttachments) that will be used in the analysis, but they will be defined later on.

Mandatory Inputs#

Property	Type	Description
`Model`	`N2PModelContent`	FEM model to be analyzed

FEM Requirements#

For this module to function properly, the FEM model must accurately represent all elements that are to be analyzed. This module is available for Nastran, Optistruct and Abaqus, and only “CFAST” and “CBUSH” elements are supported. The model can include results, but it is not mandatory.

Supported Type Files#

Solver	File Extension
Nastran	.op2
Nastran	.xdb
Nastran	.h5
Optistruct	.op2
Optistruct	.h3d

For this module to function properly, the FEM model must accurately represent all elements that are to be analyzed. This module is available for Nastran, Optistruct and Abaqus, and only "CFAST" and "CBUSH" elements are supported. The model can include results, but it is not mandatory.

Optional Inputs#

Property	Type	Description
`ElementList`	`list[N2PElement]`	List of fasteners to be analysed. By default, all fasteners will be analysed
`ExportLocation`	`str`	Location where results are to be exported. By default, nothing will be exported
`GetAttachmentsBool`	`bool`	Boolean that shows if `N2PAttachment` objects are obtained or not. By default, they will be obtained
`GetDistanceBool`	`bool`	Boolean that shows if plates’ `Distance` and `DistanceVector` atributes are obtaind or not. By default, they will not be obtained.
`Thresh`	`float`	Tolerance value used in the creation of the joints. Changing this value is not recommended

To export the obtained results to an HDF5 file, introduce the path in the ExportLocation attribute before executing the calculate() method.

fasteners.ExportLocation = "output.h5"

The results that are exported consist in a different arbitrary value being assigned to the first, last and middle (if it exists) plates in a joint.

In order to not calculate the attachments in the model (to save some time in the calculations), set the GetAttachmentsBool attribute to False.

fasteners.GetAttachmentsBool = False 

In order to calculate the distances from the plates’ intersection point to its closest free edge, set the GetDistanceBool attribute to True.

fasteners.GetDistanceBool = False 

Possible errors and warnings#

E535: the Model attribute is of the wrong instance, that is, it is not a N2PModelContent object.
E520: the ElementList attribute does not have any correct elements.
W527: an attribute is of the wrong instance, so it is not updated (for example, the GetAttachmentsBool attribute is not set to a boolean).

Expected Output#

Property	Type	Description
`JointsList`	`list[N2PJoint]`	List of N2PJoints
`PlateList`	`list[N2PPlate]`	List of N2PPlates
`BoltsList`	`list[N2PBolt]`	List of N2PBolts
`AttachmentsList`	`list[N2PAttachment]`	List of N2PAttachments (if `GetAttachmentsBool` is not set to `False`)

N2PJoints creation#

Firstly, all N2PJoints, N2PPlates and N2PBolts are created and assigned their default attributes, which is done by using the get_joints() method. The following steps are followed:

All N2Joints are created from the C# core. Only joints whose fasteners have been selected in the ElementList attribute will be created.
All N2PJoints associated to the N2Joints previously created, are also created. While creating each individual N2PJoint, its associated N2PPlates and N2PBolt are also created, and certain attributes are also assigned.
After having constructed the N2PJoint, N2PBolt and N2PPlate objects, some more attributes are assigned here, such as plate elements.
Take note that, if two fasteners pierce a plate in the same point, they are to be considered part of the same joint, but if they pierce it in different points (regardless of how close they are), they are considered part of two different joints.

Possible errors and warnings#

E521: the model has not been loaded.
W529: a joint has no associated plates (probably due to an error in its geometry), so it is removed from the list.

Intersection obtention#

Now, all N2PPlates have some of their attributes filled, namely the Distance, DistanceVector (if the GetDistanceBool attribute is set to True), Normal, Intersection, BoltDirection, BoltElementList, and CFASTFactor attributes, which is done by using the get_intersection() method. This is done by calling another module, also called get_intersection(), for each N2PJoint. The following steps are followed:

The Normal attribute is obtained, as the normal direction to each plate can be defined by three of its nodes. This attribute is the vector corresponding to the normal direction of the plate.
The Intersection attribute is obtained, as the coordinates of the nodes of the fastener are known. This attribute is the coordinates of the point in which the fastener(s) and the plate intersects.
The BoltDirection, BoltElementList and CFASTFactor attributes for N2PPlates are created:
- BoltDirection: dictionary which shows the direction in which the fastener(s) attached to the plate. Its structure is {“A”: Arrow A, “B”: Arrow B}. If the plate is attached to only one fastener, one of the arrows (the one corresponding to the non-existing fastener) will be a None. The two possible arrows are “->” and “<-” (as well as, of course, a None, as previously mentioned). The arrow tip denotes the location of the GB node.
- BoltElementList: dictionary which shows the ID of the fastener(s) attached to the plate. Its structure is {“A”: EID A, “B”: EID B}. If the plate is attached to only one fastener, one of the arrows (the one corresponding to the non-existing fastener) will be a None
- CFASTFactor: dictionary which shows the CFAST factor of the fastener(s) attached to the plate. Its structure is {“A”: FA, “B”: FB}. If the plate is attached to only one fastener, one of the arrows (the one corresponding to the non-existing fastener) will be 0. The two possible factors are +1 and -1 (as well as, of course, 0).
The algorithm used to determine which fastener is the A or B one, as well as its direction and factor is the following:
- The fastener direction (as defined by its A and B nodes) is obtained.
- If it is in the same direction of the plate’s normal (the dot product between the fastener direction and the plate’s normal is positive), the direction will be “<-” and the CFAST factor will be 1. Otherwise, the direction will be “->” and the factor will be -1.
- If the fastener direction is similar to the plate’s normal, the fastener’s IDA and IDB elements are selected from its card. If the IDA element is the same as the plate’s central element, the fastener is the “B” one. Otherwise, the fastener is the “A” one.
- If the fastener direction is the opposed to the plate’s normal (their dot product is negative), the opposite criterion is followed: if the IDA element is the same as the plate’s central element, the fastener is the “A” one, and otherwise, the fastener is the “B” one.
- If the card shows information about the element ID (the type of card is “ELEM”), the information above applies. If it shows information about the property ID (the type of card is “PROP”), instead of checking if the IDA or IDB elements are the same as the plate’s central element, their property is checked. The rest of the algorith remains unchanged.
The Distance and DistanceVector attributes are obtained, which represents the distance from the intersection point to the closest edge of the plate. This is done by defining the edge of the element and obtaining the distance through basic algebra. These attributes are the distance from the intersection point between the fastener(s) and the plate, to the closest edge of the plate, either in scalar or vector form.

Possible errors and warnings#

W532: the list of joints has not been obtained yet, as this method is being called before the previous one. The get_joints() method is now being called.
W512: the plate that is being analysed has no elements due to a problem with its geometry, so it is skipped.
W531: a correct intersection point cannot be found, so one of the fastener’s nodes is assigned instead (usually, the right intersection point will be assigned, even if this warning shows up).
W542: it is being checked if a point lies within an element that is not supported.

N2PAttachments creation#

Finally, all N2PAttachments are created and assigned certain attributes, which is done by using the get_attachments() method. Firstly, all N2PAttachments are created through another method, also called get_attachments(). In this method, the following steps are followed:

The program assesses if two joints connect the same region of the model or not by looking at its attached elements, which is done by using the model.get_elements_attached() method. If two joints connect exactly the same elements, they are considered to be part of an attachment. Two joints are also part of the same attachment if the attached elements of one joint is a subset of the attached elements of the other joint, which may happen when one joint has one fastener and the other one has two.
N2PAttachment objects are created and assigned their attributes, and plates in the attachments are given a new Attachment ID.

Next, the attachment’s pitch is calculated. A bolt’s pitch is defined as the distance to the closest bolt in the attachment, while the attachment’s pitch is the minimum pitch of all bolts in the attachment. To obtain the pitch, the get_pitch() method is used. The following steps are followed:

As the intersection point between the plates and their bolts has already been calculated, the distance is easily obtained.
Joints and attachments are assigned their Pitch attribute. For a joint, this attribute represents the minimum distance to another joint in the attachment, while, for an attachment, this attribute represents the minimum distance between two joints in the attachment.

Possible errors and warnings#

W533: the intersection points have not been obtained yet, as this method is being called before the previous one. The get_intersection() method is now being called.

Flip Plates#

The flip_plates() method is an optional one that simply switches the order of the plates in the PlateList attribute of joints that have the SwitchPlates attribute set to True. For a normal usage of the program, this method should not be called. However, if the user wants to switch the order of certain plates, they should act in the following way:

# Only the plates of the first ten joints will be switched
for joint in fasteners.JointList[0:10]: 
  joint.SwitchPlates = True 
fasteners.flip_plates() 

Assign Diameter#

The assign_diameter() method is an optional one that allows the user to assign a certain diameter to a certain number of joints. Its inputs are:

elementList: list of N2PElement that make up the joints that are to be assigned a diameter.
diameter: float representing the diameter to be assigned. The user may call this method several times to assign a different diameter to different fasteners. The method is used in the following way:

elementList1 = model.get_elements([(57510018, '0'), (57510014, '0')]) 
diameter1 = 4.8 
elementList1 = model.get_elements([(57510019, '0'), (57510022, '0')]) 
diameter1 = 5.6
fasteners.assign_diameter(elementList2, diameter2) 

Auxiliary classes#

As mentioned before, N2PGetFasteners use four main objects in its calculations: N2PJoints, N2PBolts, N2PPlates and N2PAttachments. These classes, as well as its attributes, will be explained here. As these objectes may also be used in the N2PGetLoadFasteners class, many of their attributes will not be filled in after running N2PGetFasteners.

N2PBolt#

A N2PBolt object is a part of a N2PJoint object that contains one or several fasteners (CFAST, CBUSH, etc.) that has the following properties (that are being filled in in N2PGetFasteners):

ID (int): bolt’s unique internal identifier.
Joint (N2PJoint): N2PJoint associated to the bolt.
ElementList (list[N2PElement]): list of N2PElements that correspond to the fasteners that make up the bolt.
ElementIDList (list[int]): list of the solver IDs of the bolt’s fasteners.
ElementInternalIDList (list[int]): list of the internal IDs of the bolt’s fasteners.
NodeList (list[tuple[N2PNode]]): list of the bolt’s N2PNodes.
PartID (str): part ID of the bolt’s fasteners. It is assumed that all fasteners in the bolt have the same part ID.
Cards (list[N2PCard]): list of N2PCards associated to the bolt’s fasteners.
Type (str): type of fastener (CFAST, CBUSH, etc.).
OneDimElemsIDList (list[int]): list of the internal IDs of the bolt’s fasteners.

The following properties are filled in in N2PGetLoadFasteners:

AxialForce (dict[int, dict[int, float]]): dictionary corresponding to the axial force that each fastener experience. It is expressed in the material reference frame of the first plate in the joint. Its structure is {LC ID: {EID: F}}.
ShearForce (dict[int, dict[int, float]]): dictionary corresponding to the shear force that each fastener experience. It is expressed in the material reference frame of the first plate in the joint. Its structure is {LC ID: {EID: F}}.
MaxAxialForce (dict[int, float]): dictionary corresponding to the maximum axial force that the bolt experiences. It is expressed in the material reference frame of the first plate in the joint. Its structure is {LC ID: F}.
LoadAngle (dict[int, dict[int, float]]): dictionary corresponding to the load angle of each fastener. Its structure is {LC ID: {EID: Angle}}.

N2PPlate#

A N2PPlate object is a part of a N2PJoint object that contains one or several (almost always, one) N2PElement (CQUAD, CTRIA, etc.). A N2PJoint object will always have one more plate than fasteners, so the minimum number of plates in a joint will be two. N2PPlates have the following properties:

ID (int): plate’s unique internal identifier.
Joint (N2PJoint): N2PJoint associated to the plate.
Bolt (N2PBolt): N2PBolt associated to the plate.
ElementList (list[N2PElement]): list of the N2PElements that make up the plate. Almost always, this list will have only one item.
Intersection (list[float]): coordinates of the intersection point between the plate and its bolt.
DistanceVector (np.ndarray): vector from the plate’s intersection point to its closest edge.
Distance (float): distance from the plate’s intersection point to its closest edge. It is the norm of the DistanceVector attribute.
Normal (list[float]): vector that indicates the normal direction of the plate.
ElementIDList (list[int]): list of the solver IDs of the elements that make up the plate.
ElementInternalIDList (list[int]): list of the internal IDs of the elements that make up the plate.
NodeList (list[N2PNode]): list of the plate’s N2PNodes.
PartID (list[str]): list of the part ID of the elements that make up the plate.
AttachmentID (int): internal ID of the plate inside its corresponding attachment.
GlobalID (list[int]): list of the internal IDs of the elements that make up the plate.
SolverID (list[int]): list of the solver IDs of the elements that make up the plate.
CentralElement (N2PElement): representative N2PElement of the plate.
PlateCentralCellSolverID (int): solver ID of the representative element of the plate.
Cards (list[N2PCard]): list of N2PCards corresponding to the elements that make up the plate.

The following properties are filled in in N2PGetLoadFasteners:

BearingForce (dict[int, np.ndarray]): dictionary corresponding to the bearing force that the plate experience. It is expressed in the material reference frame. Its structure is {LC ID: [FX, FY, FZ]}.
NxBypass (dict[int, float]): dictionary corresponding to the Nx bypass force. Its structure is {LC ID: Nx}.
NyBypass (dict[int, float]): dictionary corresponding to the Ny bypass force. Its structure is {LC ID: Ny}.
NxyBypass (dict[int, float]): dictionary corresponding to the Nxy bypass force. Its structure is {LC ID: Nxy}.
NxTotal (dict[int, float]): dictionary corresponding to the Nx total force. Its structure is {LC ID: Nx}.
NyTotal (dict[int, float]): dictionary corresponding to the Ny total force. Its structure is {LC ID: Ny}.
NxyTotal (dict[int, float]): dictionary corresponding to the Nxy total force. Its structure is {LC ID: Nxy}.
MxTotal (dict[int, float]): dictionary corresponding to the Nx total torque. Its structure is {LC ID: Mx}.
MyTotal (dict[int, float]): dictionary corresponding to the Ny total torque. Its structure is {LC ID: My}.
MxyTotal (dict[int, float]): dictionary corresponding to the Nxy total torque. Its structure is {LC ID: Mxy}.
BypassMax (dict[int, float]): dictionary corresponding to the maximum bypass force. Its structure is {LC ID: N}.
BypassMin (dict[int, float]): dictionary corresponding to the minimum bypass force. Its structure is {LC ID: N}.
BoxFluxes (dict[int, dict[int, list[float]]]): dictionary corresponding to the bypass flux in each point (1 through 8) of the bypass box. Its structure is {LC ID: {1: [Fx1, Fy1, Fxy1, Mx1, My1, Mxy1], 2: [Fx2, …], …, 8: [Fx8, …]}}.
BypassSides (dict[int, list[float]]): dictionary corresponding to the bypass fluxes in each side (North, South, West and East) of the bypass box. Its structure is {LC ID: [[FxN, FxS, FxW, FxE], [FyN, FyS, FyW, FyE], [FxyN, FxyS, FxyW, FxyE], [MxN, MxS, MxW, FxE], [MyN, MyS, MyW, MyE], [MxyN, MxyS, MxyW, MxyE]]}.
BoltElementList (dict[str, N2PElement]): dictionary which shows the A and B fastener of the plate. If a plate only has one fastener, the lacking fastener will be None. Its structure is {“A”: Fastener A, “B”: Fastener B}.
BoltDirection (dict[int, str]): dictionary which shows the direction of the A and B fastener of the plate. If a plate only has one fastener, the lacking fastener will be None. Its structure is {“A”: Arrow A, “B”: Arrow B}, where the arrows can be either “<-” or “->”. The arrow tip denotes the GB node of the fastener, as expressed by PAG.
CFASTFactor (dictr[str, int]): dictionary which shows the CFAST factor of the A and B fastener of the plate. If a plate only has one fastener, the lacking fastener factor will be 0. Its structure is {“A”: Factor A, “B”: Factor B}, where the factors can either be +1 or -1.
BoxDimension (float): length of the side of the bypass box.
BoxSystem (list[float]): reference frame of the bypass box. It will have 9 components, corresponding to the three unitary vectors that define the reference frame.
BoxPoints (dict[int, np.ndarray]): dictinoary which shows the coordinates of all 8 points that make up the bypass box. Its structure is {1: [X1, Y1, Z1], 2: [X2, Y2, Z2], …, 8: [X8, Y8, Z8]}.
BoxElements (dict[int, N2PElement]): dictionary which shows in which N2PElement the points of the bypass box lie in. Its structure is {1: E1, …, 8: E8}.

N2PJoint#

A N2PJoint object is the union of one N2PBolt object (which may contain more than one fastener) and several N2PPlate objects, that have the following properties:

ID (int): joint’s unique internal identifier.
Diameter (float): joint’s diameter. It can be either set by the user or obtained from the cards.
Bolt (N2PBolt): N2PBolt associated to the joint.
PlateList (list[N2PPlate]): list of N2PPlates associated to the joint.
Attachment (N2PAttachment): N2PAttachment associated to the joint.
Pitch (float): joint’s pitch, if the joint is part of an attachment.
BoltElementList (list[N2PElement]): list of N2PElements that make up the joint’s bolt.
BoltElementsIDList (list[int]): list of solver IDs of the elements that make up the joint’s bolt.
BoltElementsInternalIDList (list[int]): list of internal IDs of the elements that make up the joint’s bolt.
BoltNodeList (list[tuple[N2PNode]]): list of N2PNodes that make up the joint’s bolt.
PartID (str): part ID of the joint’s bolt.
PlateElementList (list[list[N2PElement]]): list of N2PElements that make up the joint’s plates.
PlateElementsIDList (list[list[int]]): list of solver IDs of the elements that make up the joint’s plates.
PlateElementsInternalIDList (list[list[int]]): list of internal IDs of the elements that make up the joint’s plates.
PlateNodeList (list[list[tuple[N2PNode]]]): list of N2PNodes that make up the joint’s plates.
PlatePartID (list[str]): part ID of the joint’s plates.
TypeFastener (str): type of fasteners (CFAST, CBUSH, etc.).
SwitchPlates (bool): boolean that shows whether or not the joint’s plates have to be switched in order when calling the flip_plates() method.

N2PAttachment#

A N2PAttachment object is the union of several N2PJoint objects that connect the same region of the model, and has the following properties:

ID (int): attachmen’s unique internal identifier.
AttachedPlateList (list[N2PPlate]): list of N2PPlates in the attachment.
AttachedPlatesIDList (list[int]): list of the internal ID of the plates in the attachment.
JointsList (list[N2PJoint]): list of N2PJoints in the attachment.
Pitch (float): attachment’s pitch, which is the minimum pitch of all joints in the attachment.

Differences#

In order to further show the difference between the previous objects, see the following images:

In the following image it is shown a single union, which is composed of one element (the fastener joints two plates):

Now it is shown a double union, which is composed of two elements (the fastener joints three plates):

In the next two images it is shown all plates in a joint. Each plate is made up of one single CQUAD4 element. In the first image, the joint has two plates, while in the second image, the joint has three plates.

In the following two images it is shown a single joint, which is composed of one bolt and three plates (first), or one bolt and two plates (second).

In the final image an attachment is shown, which is composed of several joints (which are made up by one or two fasteners and two or three plates). All of them are part of the same attachment, since they connect the same part of the FEM model, even if their attached elements are not exactly the same (note that the joints made up of only one fastener, the ones in the right part of the image, are not attached to the lower region of the model).

References#

No references were used in this module.