Metadata-Version: 2.4
Name: 3pc-sandfail
Version: 1.0.1
Summary: Python library for stress / strain analysis of shear deformable anisotropic sandwich plates under hygrothermal and mechanical loads.
Author: Omprakash Seresta
Author-email: oseresta@gmail.com
License: MIT
Project-URL: Blog, https://3pcomposites.com/blogs-1/f/3pcsolver005-hygrothermomechanical-analyses-of-sandwich-panels
Project-URL: Analysis Tools, https://3pcomposites.com/analysis-tools
Project-URL: Documentation, https://drive.google.com/drive/folders/1jDb-P5BOgJ-moVU20B7D8oVeHjHLAHTm
Keywords: sandwich-plates failure-analysis stress-analysis composites anisotropic aerospace-engineering mechanics fsdt clt hygrothermal
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-sandwich
Requires-Dist: 3pc-loads
Requires-Dist: 3pc-utils
Requires-Dist: numpy
Requires-Dist: scipy
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-sandfail

`3pc-sandfail` is a Python library for stress / strain analysis of shear deformable anisotropic sandwich plates under hygrothermal and mechanical loads. It provides a `Sandfail` class to perform ply-by-ply stress, strain, and margin of safety calculations, evaluating sandwich-specific failure modes such as intracellular buckling (dimpling), wrinkling, core shear crimping, core shear, core crush, and facesheet disbond.

## Installation

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

```bash
pip install 3pc-sandfail
```

## API Reference

### `Sandfail` Class

The primary component of this package is the `Sandfail` class, which takes a panel, a load case, and core properties to compute stress, strain, and margins of safety against various failure modes.

```python
from sandfail.sandfail import Sandfail
```

#### Required Parameters

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

*   **`panel`** *(Panel)*: An instance of the `Panel` class (from `3pc-panel`) containing the face sheet laminates and sandwich core definition.
*   **`loads`** *(Loads)*: An instance of the `Loads` class (from `3pc-loads`) containing the load case and environmental conditions.
*   **`core_properties`** *(dict)*: Dictionary of core-specific configuration properties (e.g., `type` - `"isotropic"` or `"orthotropic"`, `Ec`, `Gc`, `k1`, `delta0`, `FwT`).

#### Calculated Properties

The class calculates the following properties:

*   **`NT`, `NC`**: Thermal and hygral in-plane load vectors.
*   **`MT`, `MC`**: Thermal and hygral in-plane moment vectors.
*   **`ek0`**: Reference/midplane strain and curvatures.
*   **`stress`, `strain`**: Stresses and strains for the face sheets and core.
*   **`msCoreShear`**: Margin of safety for core shear.
*   **`msICBTopLaminate`, `msICBBottomLaminate`**: Margin of safety for intracellular buckling (dimpling) on the top/bottom laminates.
*   **`msWrinklingTopLaminate`, `msWrinklingBottomLaminate`**: Margin of safety for wrinkling on the top/bottom laminates.

### Methods

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

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

---

## Usage Examples

### Basic Initialization

Below is an example of performing a sandwich failure analysis.

```python
from panel.panel import Panel
from loads.loads import Loads
from sandfail.sandfail import Sandfail

# Assuming pnl (Panel) and ld (Loads) are already defined
core_props = {
    "type": "isotropic",
    "Ec": 1000.0,
    "k1": 0.5,
    "Gc": 400.0
}

sf = Sandfail(
    panel=pnl,
    loads=ld,
    core_properties=core_props
)

# Access calculations and margins of safety
print("Mid-plane strains/curvatures:", sf.ek0)
print("Core Shear Margin of Safety:", sf.msCoreShear)
```

## Commands

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

```bash
sandfail input.cfg
```

*(This entry point is defined in `sandfail.__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, cores, laminates, panels, loads, config) to the current directory.

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

The `sandfail` command requires a configuration file (typically named `sandfail.cfg`). Below is an example based on `sandfail/examples/sandfail.cfg`:

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

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

#### `[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-ply`](https://pypi.org/project/3pc-ply/).
*   **`cores`**: Path to the cores JSON file.
*   **`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-panel`](https://pypi.org/project/3pc-panel/).
*   **`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 sandwich failure analysis results will be written.

#### `[analysis]` Section

This section specifies the analysis settings:

*   **`analysis_type`**: Type of analysis (e.g. `MECHANICAL`, `HYGROTHERMAL`, `HYGROTHERMOMECHANICAL`).
*   **`failure_theory`**: Theory used for laminate strength evaluation (e.g. `MAX STRAIN`, `TSAI-WU`, `TSAI-HILL`, `MAX STRESS`).
*   **`sandwich_failure`**: Flag to enable/disable sandwich failure analysis (e.g., `yes`, `no`).

## Citation

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

**APA Format:**
> Rastogi, N., & Seresta, O. (2026). *3pc-sandfail: Python library for stress / strain analysis of shear deformable anisotropic sandwich plates under hygrothermal and mechanical loads*. PyPI. https://pypi.org/project/3pc-sandfail/

**BibTeX:**
```bibtex
@software{3pc_sandfail,
  author = {Rastogi, Naveen and Seresta, Omprakash},
  title = {3pc-sandfail: Python library for stress / strain analysis of shear deformable anisotropic sandwich plates under hygrothermal and mechanical loads},
  year = {2026},
  url = {https://pypi.org/project/3pc-sandfail/}
}
```
