Metadata-Version: 2.4
Name: 3pc-lamfail
Version: 1.0.4
Summary: Python library for ply-wise stress, strain, and failure analysis of anisotropic laminates.
Author: Omprakash Seresta
Author-email: oseresta@gmail.com
License: MIT
Project-URL: Blog, https://3pcomposites.com/blogs-1/f/3pcsolver001
Project-URL: Analysis Tools, https://3pcomposites.com/analysis-tools
Keywords: laminate-failure composites stress-analysis strain-analysis margins-of-safety tsai-wu tsai-hill anisotropic aerospace-engineering mechanics fsdt clt
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: 3pc-material
Requires-Dist: 3pc-ply
Requires-Dist: 3pc-laminate
Requires-Dist: 3pc-panel
Requires-Dist: 3pc-loads
Requires-Dist: 3pc-utils
Requires-Dist: numpy
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 3pc-lamfail

`3pc-lamfail` is a Python library used for ply-wise stress and strain analysis of shear deformable anisotropic laminates under hygrothermal and mechanical loads. It provides a `Lamfail` class to calculate stresses, strains, and various margins of safety (MS) based on classical and first-order shear deformation theories.

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install `3pc-lamfail`. Since the package and its dependencies are available on PyPI, you can install them directly:

```bash
pip install 3pc-lamfail
```

## API Reference

### `Lamfail` Class

The primary component of this package is the `Lamfail` class, which takes a panel and a load case to compute detailed failure metrics.

```python
from lamfail.lamfail import Lamfail
```

#### Required Parameters

When initializing `Lamfail`, the following parameters are required:

*   **`panel`** *(Panel)*: An instance of the `Panel` class (from `3pc-panel`) containing the laminate definition and geometry.
*   **`loads`** *(Loads)*: An instance of the `Loads` class (from `3pc-loads`) containing the load case and environmental conditions.

#### Calculated Properties

The class automatically calculates the following properties lazily:

*   **`NT`, `MT`**: Thermal in-plane loads and moments.
*   **`NC`, `MC`**: Hygral in-plane loads and moments.
*   **`ek0`**: Mid-plane strains and curvatures `[ex0, ey0, gxy0, kx0, ky0, kxy0]`.
*   **`gT0`**: Mid-plane transverse strains `[gyz0, gxz0]`.
*   **`tauyz`, `tauxz`**: Transverse shear stresses for each ply.
*   **`stress`**: Total stress in reference coordinate axes (x-y-z) for each ply (bottom, mid, top).
*   **`stressM`, `stressT`, `stressH`**: Mechanical, thermal, and hygral components of stress in reference axes.
*   **`stress1`, `stressM1`, `stressT1`, `stressH1`**: Stresses transformed to material coordinate axes (1-2-3).
*   **`strain`, `strainM`, `strainT`, `strainH`**: Strains in reference coordinate axes.
*   **`strain1`, `strainM1`, `strainT1`, `strainH1`**: Strains in material coordinate axes.

#### Margins of Safety (MS)

The following failure theories are implemented:

*   **`stress1MS`**: Max Stress theory using total stress.
*   **`stressM1MS`**: Max Stress theory using mechanical stress.
*   **`strain1MS`**: Max Strain theory using total strain.
*   **`strainM1MS`**: Max Strain theory using mechanical strain.
*   **`tsaiHill1MS`, `tsaiHillM1MS`**: Tsai-Hill failure theory (Total/Mechanical).
*   **`tsaiWu1MS`, `tsaiWuM1MS`**: Tsai-Wu failure theory (Total/Mechanical).

### Methods

#### `Lamfail.fromDict(**kwargs)`

Initializes a `Lamfail` instance using a dictionary of keyword arguments.

---

## Usage Examples

### Basic Initialization

Below is an example of performing a failure analysis on a panel under a specific load case.

```python
from panel.panel import Panel
from loads.loads import Loads
from lamfail.lamfail import Lamfail

# Assuming pnl (Panel) and ld (Loads) are already defined
lf = Lamfail(panel=pnl, loads=ld)

# Access Margins of Safety for Ply 1 (bottom ply)
print("Max Stress MS (Material Axes):", lf.stress1MS["1"]["mid"])
print("Tsai-Wu MS:", lf.tsaiWu1MS["1"]["mid"])

# Access stresses
print("Total Stress (x-y-z):", lf.stress["1"]["top"])
```

## Commands

The package provides a command-line interface entry point. After installing, you can run the application using:

```bash
lamfail input.cfg
```

*(This entry point is defined in `lamfail.__main__:main`)*

### Options

*   **`config`** *(positional)*: Specify the configuration file (`.cfg`) to run the analysis.
*   **`-h, --help`**: Show the help message and exit.
*   **`-v, --version`**: Show the version number.
*   **`-s, --sample`**: Copy example files (materials, plies, laminates, etc.) to the current directory.

### Configuration File (`input.cfg`)

The `lamfail` command requires a configuration file (typically named `input.cfg` or `lamfail.cfg`). Below is an example based on `lamfail/examples/mechanical/max-strain/lamfail.cfg`:

```ini
[files]
materials = materials.json
plies = plies.json
laminates = laminates.json
panels = panels.json
loads = loads.json
output = output.txt

[analysis]
analysis_type = MECHANICAL
failure_theory = MAX STRAIN
```

#### `[files]` Section

This section defines the paths to the required input JSON files and the desired output file:

*   **`materials`**: Path to the materials JSON file. Follows the format expected by [`3pc-material`](https://pypi.org/project/3pc-material/).
*   **`plies`**: Path to the plies JSON file. Follows the format expected by [`3pc-plies`](https://pypi.org/project/3pc-plies/).
*   **`laminates`**: Path to the laminates JSON file. Follows the format expected by [`3pc-laminate`](https://pypi.org/project/3pc-laminate/).
*   **`panels`**: Path to the panels JSON file. Follows the format expected by [`3pc-panels`](https://pypi.org/project/3pc-panels/).
*   **`loads`**: Path to the loads JSON file. Follows the format expected by [`3pc-loads`](https://pypi.org/project/3pc-loads/).
*   **`output`**: Path to the text file where the failure analysis results will be written.

#### `[analysis]` Section

This section specifies the analysis settings:

*   **`analysis_type`**: The type of analysis to run. Supported options include `MECHANICAL`, `THERMO-MECHANICAL`, `HYGRO-MECHANICAL`, and `HYGRO-THERMO-MECHANICAL`.
*   **`failure_theory`**: The failure theory to evaluate. Supported options include `MAX STRAIN`, `MAX STRESS`, `TSAI HILL`, and `TSAI WU`.

## Citation

If you use this library in your research or work, please cite it as follows:

**APA Format:**
> Rastogi, N., & Seresta, O. (2026). *3pc-lamfail: Python library for ply-wise stress, strain, and failure analysis of anisotropic laminates*. PyPI. https://pypi.org/project/3pc-lamfail/

**BibTeX:**
```bibtex
@software{3pc_lamfail,
  author = {Rastogi, Naveen and Seresta, Omprakash},
  title = {3pc-lamfail: Python library for ply-wise stress, strain, and failure analysis of anisotropic laminates},
  year = {2026},
  url = {https://pypi.org/project/3pc-lamfail/}
}
```
