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