N2PCompositeFailure User Manual#

Overview#

The N2PCompositeFailure Module is designed to compute Reserve Factor at composite materials from linear Finite Element Analysis (FEA) results.

Example of Use#

1. Importing the Module.#

import NaxToPy as n2p
from NaxToPy.Modules.static.composite import N2PCompositeFailure

2. Loading the Model.#

model = n2p.load_model(r".\model.op2")

3. Defining Elements and LoadCases#

list_elements = model.get_elements_filtered(properties=[11100004, 11100007]) # filter elements
list_elements = [e for e in model.get_elements()] # to extract all elements
list_lcs = [model.get_load_case(4001001)] # filter load cases
list_lcs = [model.get_load_case()] # to extract all load cases

4. Create and configure N2PCompositeFailure.#

my_analysis = N2PCompositeFailure()
my_analysis.Model = model
my_analysis.Elements = list_elements
my_analysis.LoadCases = list_lcs
my_analysis.FailureTheory = "TsaiWu"

5. Conditional Inputs. Allowables#

my_analysis.Materials[(3,"0")].Allowables.XTensile = 10
my_analysis.Materials[(3,"0")].Allowables.XCompressive = 10
my_analysis.Materials[(3,"0")].Allowables.YTensile = 10
my_analysis.Materials[(3,"0")].Allowables.YCompressive = 10
my_analysis.Materials[(3,"0")].Allowables.Shear = 10

6. Optional Inputs. Export File#

my_analysis.HDF5.FilePath= r".\Analysis.h5"

7. Run Calculations.#

my_analysis.calculate()

Setup#

Prerequisites#

Python Environment: Make sure to work with a compatible Python Environment including the following libraries:
- scipy
- numpy
- NaxToPy modules
NaxToPy Framework: The module integrates within the NaxToPy libray, which must be installed and configured in your environment.

Module Inputs#

Mandatory Inputs#

Property	Type	Description
.Model	`N2PModelContent`	FEM model to analyse
.ElementList	`list[N2PElement]`	List of elements to analyse
.LoadCaseList	`list[N2PLoadCase]`	List of load cases to consider
.FailureCriteria	`string`	Failure Criteria to analyse: `MaxStress` `TsaiWu` `TsaiHill` `Hashin` `Puck`
.FailureTheory	`string`	Failure Theory to compute: `FirstPly` `PlyByPly` (1)

(1) Hashin and Puck Failure Theories are not currently supported by PlyByPly failure mode

FEM Requirements#

For this module to work properly, FEM model must include forces linear results in the output requests. Module will only take active Increment into calculus considerations. Thus, if desired, user must change active Increment manually before loading the model and extracting the results. Missing or incomplete Forces data may lead to incorrect calculations. This module is available for Nastran, Optistruct FEM Models.

Conditional Inputs#

Property	Type	Description
`.Materials[MatID].Allowables.XTensile` `.Materials[MatID].Allowables.XCompressive` `.Materials[MatID].Allowables.YTensile` `.Materials[MatID].Allowables.YCompressive` `.Materials[MatID].Allowables.Shear`	`float`	Stress Allowables. This input is conditional because it might be defined in the model cards. This value can be overwritten if necessary

Optional Inputs#

Property	Type	Description
`.HDF5.FilePath`	`str`	Path to specify the location of the created HDF5 file. If no path is provided, the file is created in memory.

To export the data into a HDF5 file set the path in the property `HDF5`:

Analysis.HDF5.FilePath = "output.h5"

Tip

Exporting the data to a local HDF5 file will improve memory management.

Output Description#

This module will provide information about structural integrity for composite laminates. User will be able to select which failure mode and failure theory has to be implemented.

N2PCompositeFailure offers the user the chance to perform the analysis on full FEM models, or select specific portions of the model for determined loadcases.

Module results management is oriented towards the creation of hdf5 files to later be visualized through NaxToView. Output file will have the following structure.

FileName
├── NAXTO
│   ├── RESULTS
│   │   ├── LoadCase_ID_1
│   │   │   ├── Increment
│   │   │   │       ├── Component Initial_Results
│   │   │   │       │   ├── Section_1
│   │   │   │       │   ├── Section_2
│   │   │   │       │   ├── ...
│   │   │   │       │   ├── Section_n
│   │   │   │       ├── Component Failure_Results
│   │   │   │       │   ├── Section_All
│   │   │   │       ├── Component Order_Results
│   │   │   │       │   ├── Section_1
│   │   │   │       │   ├── Section_2
│   │   │   │       │   ├── ...
│   │   │   │       │   ├── Section_n
│   │   ├── LoadCase_ID_2
│   │   ├── ...
│   │   ├── LoadCase_ID_n

** Each Section represents a layer of the laminate. There will be as much sections as the highest number of laminas for the different laminates to be analysed.

** If some elements do not have as many layers as total number of sections. Empty sections will be filled with a NaN value for the computed Reserve Factor (RF).

Additionally user might consider the option of managing results on its own - i.e export results to .xslx or .csv files.

If this scenario occurs, user must know that N2PCompositeFailure stores the output within memory inside dictionaries where the results are classified for each load case and Element.

Results will be independently stored for each loadcase, distinguishing between three different result components. User will determine which type of result has to be provided depending on Failure Criteria selected:

Initial Failure Results will be presented both for FPF and PBP failure modes. As it marks the failure point for the most restrictive criteria, and it shows the starting point for the progressive degradation of the laminate.

A list of Reserve Factors (RF) will be given for the each one of the elements of the model to be analysed. Each value of the list will represent the Reserve Factor for a single lamina within the laminate.

Example: For a single Load Case and a laminate composed of 2 layers.

HDF5 File Output

Section 1

Element ID

RF

100001

0.84

100002

1.21

100003

0.43

100004

1.03

Section 2

Element ID

RF

100001

1.02

100002

0.62

100003

0.42

100004

0.37

Memory Output
```
{
    N2PLoadCase(ID) : 
    {
        N2PElement(100001, '0'): [0.84, 1.02], 
        N2PElement(100002, '0'): [1.21, 0.62], 
        N2PElement(100003, '0'): [0.43, 0.42], 
        N2PElement(100004, '0'): [1.03, 0.37]
    }
}
```
Failure Results : This results summarizes Ply-By-Ply failure mode. It is intended to represent the Failure Index for the whole laminate, and to locate where does the failure begin. Therefore, two different scenarios might occur:
- If the laminate fails. A tuple of the lowest RF, and its associated lamina ID for the first iteration will be given.
- If the laminate is strong enough to carry the applied loads. A tuple of the highest Failure Index of the remaining healthy layes, and its associated lamina ID will be given.
Example: For a single Load Case and a laminate composed of 2 layers.

HDF5 File Output

Section All

Element ID

RF

Lamina ID

100001

0.84

1

100002

0.62

2

100003

0.42

2

100004

0.37

2

Memory Output
```
{
    N2PLoadCase(ID) : 
    {
        N2PElement(100001, '0'): (0.84, 1),
        N2PElement(100002, '0'): (0.62, 2), 
        N2PElement(100003, '0'): (0.42, 2), 
        N2PElement(100004, '0'): (0.37, 2)
    }
}
```

Order Results: This result provides the user a detailed description of how progressive degradation develops within the laminate. It is intended to show the Reserve Factor for each lamina at the exact point where it fails. Output provides, for each lamina, its respective Reserve Factor, and the order of failure with regard to the rest of laminas.

A list of tuples - a tuple for each single layer - will describe the result of the analysis for the elements to be analysed.
- If the laminate fails. Every single tuple will have an order index greater than zero.
- If the laminate does not fully fail. Healthy laminas will carry a zero order index - meaning there is no failure on them - alongside its respective failure index - higher than one.
Example: For a single Load Case and a laminate composed of 2 layers.

HDF5 File Output

Section 1

Element ID

FI

Order

100001

0.84

1

100002

1.21

0

100003

0.43

2

100004

1.03

0

Section 2

Element ID

FI

Order

100001

1.02

0

100002

1.11

0

100003

0.42

1

100004

0.37

1

Memory Output
```
{
    N2PLoadCase(ID) : 
    {
        N2PElement(100001, '0'): [(0.84, 1), (1.02, 0)],
        N2PElement(100002, '0'): [(1.21, 0), (1.11, 0)],
        N2PElement(100003, '0'): [(0.43, 2),(0.42, 1)],
        N2PElement(100004, '0'): [(1.03, 0), (0.37, 1)]
    }
}
```

Common Errors#

E801: Invalid Element assignmet to Elements attribute.
E802: Invalid Load Case assignment to LoadCases attribute.
E803: Error raised when a Failure Criterion assigned by user is not supported by module computations.
E804: Trying to perform Failure Analysis without assigning Failure Threshold

Common Warnings#

W801: Trying to initialize a Property class with incorrect N2PProperty or N2PMaterial assignment

Methodology#

Threoreticall Background#

There is no Standard that states which exact failure criteria and theory must be used to compute failure indexes for composite structures. However, several regulations demand a minimum margin of safety for composite structure designs.

This module enables the extraction and processing of FEM results to calculate Failure Index (FI) - therefore Reserve Factor (RF) - and provide insights about structural integrity of components under various loading conditions.

Failure criterion is evaluated in composite structures based on stresses across each ply of the laminate. This module will cover two main failure criteria: First Ply Failure (FPF) and Ultimate Laminate Failure (ULF).

Composite failure occurs sequentially. When Stress is high enough for a first ply, or group of plies, laminate might be considered to fail or not. This initial point is known as First Ply Failure (FPF) which is beyond the point where the laminate is able to perform safely.

From a safety perspective. Laminates should not reach stresses high enough to cause FPF. That is the reason why even if a laminate is still able to carry the load after FPF, composite failure is diagnosed for the vast majority of scenarios in Aerospace Industry.

Once FPF occurs, laminate will keep on carrying the load on the remaining healthy plies. Failed plies will not provide stiffness to the structure anymore, therefore stresses will increase for the remaining laminate. This leads to a progressive degradation which lasts in total laminate failure, known as ultimate laminate failure (ULF).

Main theoretical tool used throughout the computations performed in this module is Classical Laminate Theory (CLT) which enables the recalculation of stresses and strains across the laminate after Failure Theories are analised for each lamina - i.e ply.

Key Features#

Failure Index Calculation: Computes FI based on various failure theories, primarily Tsai-Wu, to evaluate structural performance on composite laminates.
First-ply Failure (FPF): Determines first occurrence of failure in any lamina, or group of laminas, indicating the initiation of structural degradation.
Ply-by-ply Failure (PBP): Iteratively removes failed plies, dinamically updating laminate stiffnesses properties (ABD Matrix) and recalculating stress redistribution after each failure.
FEA Integration: Imports force-based results from FEA simulations and converts them into stresses using constitutive equations and Classical Laminate Theory (CLT).

Tsai-Wu Failure Criterion#

Tsai Wu failure criterion stands as of:

\[ F_1 \sigma_1 + F_2 \sigma_2 + F_6 \tau_{12} + F_{11} \sigma_1^2 + F_{22} \sigma_2^2 + F_{66} \tau_{12}^2 + 2F_{12} \sigma_1 \sigma_2 = 1 \]

From this formula, Reserve Factor (RF) is derived to the following expression:

\[ RF = \frac{-\left(F_1 \sigma_1 + F_2 \sigma_2\right) + \sqrt{\left(F_1 \sigma_1 + F_2 \sigma_2\right)^2 + 4 \left(F_{11} \sigma_1^2 + F_{22} \sigma_2^2 + F_{66} \tau_{12}^2 + 2F_{12} \sigma_1 \sigma_2 \right)}}{2 \left(F_{11} \sigma_1^2 + F_{22} \sigma_2^2 + F_{66} \tau_{12}^2 + 2F_{12} \sigma_1 \sigma_2 \right)} \]

Which is simplified in a more efficient way to the following equation:

\[ RF = \frac{-b + \sqrt{b^2 - 4ac}}{2a} \]

Where:

\[ a = F_{11} \sigma_1^2 + F_{22} \sigma_2^2 + F_{66} \tau_{12}^2 + 2F_{12} \sigma_1 \sigma_2,\quad b = F_1 \sigma_1 + F_2 \sigma_2, \quad c = -1 \]

\[ F_1 = \frac{1}{X_t} - \frac{1}{X_c},\quad F_2 = \frac{1}{Y_t} - \frac{1}{Y_c},\quad F_{11} = \frac{1}{X_t X_c},\quad \]

\[ F_{22} = \frac{1}{Y_t Y_c}, \quad F_{66} = \frac{1}{S^2},\quad F_{12} = -\frac{1}{2} \sqrt{F_{11} F_{22}} \]

Tsai-Hill Failure Criterion#

Tsai-Hill failure criterion stands as of:

\[ \frac{\sigma_1^2}{X_T X_C} - \frac{\sigma_1 \sigma_2}{X_T X_C} + \frac{\sigma_2^2}{Y_T Y_C} + \frac{\tau_{12}^2}{S^2} = 1 \]

From this formula, Reserve Factor (RF) is derived to the following expression:

\[ RF = \frac{1}{\sqrt{a}} \]

Where \(a\) is given by :

\[ a = \frac{1}{X_T X_C} \sigma_1^2 - \frac{1}{X_T X_C} \sigma_1 \sigma_2 + \frac{1}{Y_T Y_C} \sigma_2^2 + \frac{1}{S^2} \tau_{12}^2 \]

Max Stress Failure Criterion#

For this criterion, materials fails if any of its stresses exceeds the allowable limit:

\[ \frac{|\sigma_1|}{X_T\quad\text{or}\quad X_C},\quad \frac{|\sigma_2|}{Y_T\quad\text{or}\quad Y_C},\quad \frac{|\tau_{12}|}{S} \]

The Reserve Factor (RF) is determined by:

\[ RF = \min \left( \frac{\sigma_1}{X_T}, \frac{|\sigma_1|}{|X_C|}, \frac{\sigma_2}{Y_T}, \frac{|\sigma_2|}{|Y_C|}, \frac{|\tau_{12}|}{S} \right) \]

Hashin Failure Criterion#

This Failure Theory evaluates failure on fiber or matrix, considering whether failure occurs over tension, compression or combined loading conditions.

Fiber Failure (tension):

\[ RF = \frac{X_T}{\sigma_1} \]

Fiber Failure (compression):

\[ RF = \frac{X_C}{\sigma_2} \]

Matrix Failure (tension):

\[ RF = (\frac{\sigma_2}{Y_T})^2+(\frac{\tau_{12}}{Y_C}) ^2 \]

Matrix Failure (compression):

\[ (\frac{\tau_{12}}{Y_C}) ^2+(\frac{\sigma_2}{Y_C})^2-\frac{\sigma_2}{Y_C}=1 \]

\[ RF = \frac{-L + \sqrt{L^2 - 4Q}}{2Q} \]

\[ Q = \left( \frac{\sigma_2^2}{4S^2} + \frac{\sigma_{12}^2}{S^2} \right), \quad L = \left( \frac{\sigma_2}{4 \cdot \left( \frac{Y_c}{S^2} \right)} - \frac{1}{Y_c} \right) \cdot \sigma_2 \]

Puck Failure Criterion#

This failure theory evaluates both fiber failure (FF) and inter-fiber failure (IFF), accounting for combined failure mechanisms in tension and compression.

Fiber failure is assessed using simple strength ratios (Maximum Stress). Inter-fiber failure combines transverse and shear stresses.

In Puck’s theory, the failure plane is not necessarily aligned with the material axes. Instead, it is inclined by an angle 𝜃(typically from −90∘ to +90∘), and failure is evaluated on this plane.

According to Puck and Schürmann. A default engineering value can be used when fracture plane is unknown.

\[ f_I = 1.12 \]

Reserve Factor is derived from the following equations:

Fiber Failure (Tensile)

\[ RF_{\text{FF,tension}} = \frac{X_T}{\sigma_1} \]

Fiber Failure (Compression)

\[ RF_{\text{FF,compression}} = \frac{X_C}{|\sigma_1|} \]

Inter-Fiber Failure (Matrix Tension)

\[ RF_{\text{IFF,tension}} = \frac{1}{\sqrt{ \left( \frac{\sigma_2}{Y_T} \right)^2 + \left( \frac{\sigma_{12}}{S_L} \right)^2 }} \]

Inter-Fiber Failure (Matrix Compression)

\[ RF_{\text{IFF,compression}} = \frac{1}{\sqrt{ \left( \frac{\sigma_{12}}{S_L} \right)^2 + \left( \frac{\sigma_2}{Y_C} + f_I \cdot \frac{|\sigma_{12}|}{S_L} \right)^2 }} \]

Extra Examples#

User might want to run calculations over every available element in the model. Calculations can not be performed over those non-composite elements. To ensure a proper functioning.

The following example might serve as a guide to perform a complete analysis under those conditions.

import NaxToPy as n2p
from NaxToPy.Modules.static.composite.failure_analysis.N2PCompositeFailure import N2PCompositeFailure

model = n2p.load_model(r"model.op2")

elements = model.get_elements()
list_elements = [element for element in elements if model.PropertyDict[element.Prop].PropertyType == "PCOMP"] #gets every element associated to a composite property.
list_lcs = model.get_load_case() # calculations will be performed over every load case.

my_analysis = N2PCompositeFailure()
my_analysis.Model = model
my_analysis.Elements = list_elements
my_analysis.LoadCases = list_lcs
my_analysis.FailureCriteria = "PlyByPly"
my_analysis.FailureTheory = "TsaiHill"

# Materials[(MatID, PartID)]

my_analysis.Materials[(3,"0")].Allowables.XTensile = 10
my_analysis.Materials[(3,"0")].Allowables.XCompressive = 10
my_analysis.Materials[(3,"0")].Allowables.YTensile = 10
my_analysis.Materials[(3,"0")].Allowables.YCompressive = 10
my_analysis.Materials[(3,"0")].Allowables.Shear = 10


my_analysis.calculate()

Validation#

This Module has been validated with regard to ELAMX² software - See [Ref-7] - with a maximum deviation of 0.54% with regard to its results. For further information, please contact the Idaero Support Team.

References#

[Ref-1]: Jones, R.M. (1998). Mechanics of Composite Materials.
[Ref-2]: Daniel, I.M., & Isahi, O. (2005). Engineering Mechanics of Composite Materials.
[Ref-3]: Kaw, A. (2006). Mechanics of Composite Materials.
[Ref-4]: Tsai, S.W., & Hahn, H.T. (1980). Introduction to Composite Materials.
[Ref-5]: MIL-HDBK-17-3F (2002). Composite Materials Handbook - Volume 3: Polymer Matrix Composites Materials usage, Design and Analysis.
[Ref-6]: NASA-RP-1351 (1994). Basic Mechanics of Laminated Composite Plates.
[Ref-7]: Technische Universität Dresden (2025). ELAMX²

This guide serves as a comprehensive reference for using the N2PCompositeFailures Module in structural analysis tasks. For further information, refer to the source code comments and examples provided.

Element ID	RF
100001	0.84
100002	1.21
100003	0.43
100004	1.03

Element ID	RF
100001	1.02
100002	0.62
100003	0.42
100004	0.37

Element ID	RF	Lamina ID
100001	0.84	1
100002	0.62	2
100003	0.42	2
100004	0.37	2

Element ID	FI	Order
100001	0.84	1
100002	1.21	0
100003	0.43	2
100004	1.03	0