# 3pc-material

`3pc-material` is a Python package for material description, specifically designed to handle orthotropic materials and failure theories like Tsai-Wu.

## Installation

The package is publicly available on PyPI. You can install it using `pip`:

```bash
pip install 3pc-material
```

## API Reference

### `Orthotropic` Class

The primary component of this package is the `Orthotropic` class, which holds material properties and dynamically calculates properties for failure theories.

```python
from material.orthotropic import Orthotropic
```

#### Required Parameters

When initializing `Orthotropic` directly, the following parameters are required:

*   **`matID`** *(str)*: Orthotropic material id.
*   **`E1`** *(float)*: Elastic modulus in direction 1.
*   **`E2`** *(float)*: Elastic modulus in direction 2.
*   **`G12`** *(float)*: Shear modulus in 12 plane.
*   **`G13`** *(float)*: Transverse shear modulus in 13 plane.
*   **`G23`** *(float)*: Transverse shear modulus in 23 plane.
*   **`v12`** *(float)*: Poisson's ratio in 21 plane.

#### Optional Physical Properties (Default: `0.0`)

*   **`rho`** *(float)*: Density.
*   **`alpha1`** *(float)*: Coefficient of thermal expansion in direction 1.
*   **`alpha2`** *(float)*: Coefficient of thermal expansion in direction 2.
*   **`beta1`** *(float)*: Coefficient of hygral expansion in direction 1.
*   **`beta2`** *(float)*: Coefficient of hygral expansion in direction 2.

#### Optional Allowable Properties for Failure Theories (Default: `0.0`)

*   **`eps11_tension_allowable`** *(float)*: Allowable tensile strain in direction 1.
*   **`eps11_compression_allowable`** *(float)*: Allowable compressive strain in direction 1.
*   **`eps22_tension_allowable`** *(float)*: Allowable tensile strain in direction 2.
*   **`eps22_compression_allowable`** *(float)*: Allowable compressive strain in direction 2.
*   **`gamma12_allowable`** *(float)*: Allowable shear strain in 12 plane.
*   **`gamma23_allowable`** *(float)*: Allowable shear strain in 23 plane.
*   **`gamma13_allowable`** *(float)*: Allowable shear strain in 13 plane.
*   **`sig11_tension_allowable`** *(float)*: Allowable tensile stress in direction 1.
*   **`sig11_compression_allowable`** *(float)*: Allowable compressive stress in direction 1.
*   **`sig22_tension_allowable`** *(float)*: Allowable tensile stress in direction 2.
*   **`sig22_compression_allowable`** *(float)*: Allowable compressive stress in direction 2.
*   **`tau12_allowable`** *(float)*: Allowable shear stress in 12 plane.
*   **`tau23_allowable`** *(float)*: Allowable shear stress in 23 plane.
*   **`tau13_allowable`** *(float)*: Allowable shear stress in 13 plane.

#### Calculated Properties

The class automatically calculates the following properties lazily:

*   **`v21`**: Poisson's ratio in 21 plane. Formula: `v12 * (E2 / E1)`.
*   **`F1`**: Tsai-Wu parameter. Formula: `(1.0 / sig11_tension_allowable) + (1.0 / sig11_compression_allowable)`.
*   **`F2`**: Tsai-Wu parameter. Formula: `(1.0 / sig22_tension_allowable) + (1.0 / sig22_compression_allowable)`.
*   **`F11`**: Tsai-Wu parameter. Formula: `-1.0 / (sig11_tension_allowable * sig11_compression_allowable)`.
*   **`F22`**: Tsai-Wu parameter. Formula: `-1.0 / (sig22_tension_allowable * sig22_compression_allowable)`.
*   **`F12`**: Tsai-Wu parameter. Formula: `-0.5 * sqrt(F11 * F22)`.

### Methods

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

Initializes an `Orthotropic` instance using a dictionary of keyword arguments. This is ideal for loading configurations from JSON files or dictionaries. Defaults apply identically to standard initialization.

---

## Usage Examples

### Basic Initialization

```python
from material.orthotropic import Orthotropic

ortho = Orthotropic(
    matID="zg",
    E1=181.0,
    E2=10.3,
    G12=7.17,
    G13=7.17,
    G23=7.17,
    v12=0.28,
    sig11_tension_allowable=1500.0,
    sig11_compression_allowable=-1500.0,
    sig22_tension_allowable=50.0,
    sig22_compression_allowable=-150.0
)

print(f"Poisson's ratio v21: {ortho.v21}")
print(f"Tsai-Wu F1 parameter: {ortho.F1}")
```

### Initializing from a Dictionary

You can load your materials directly from a JSON source.

```json
// examples/material.json
{
    "materials": [
        {
            "matID": "zg",
            "E1": 181.0,
            "E2": 10.3,
            "G12": 7.17,
            "G13": 7.17,
            "G23": 7.17,
            "v12": 0.28,
            "rho": 1.6,
            "sig11_tension_allowable": 1500.0,
            "sig11_compression_allowable": -1200.0,
            "sig22_tension_allowable": 50.0,
            "sig22_compression_allowable": -250.0
        }
    ]
}
```

```python
import json
from material.orthotropic import Orthotropic

with open('examples/material.json', 'r') as f:
    data = json.load(f)

materials = [Orthotropic.fromDict(**mat_dict) for mat_dict in data["materials"]]

for mat in materials:
    print(f"Material ID: {mat.matID}")
    print(f"Calculated Tsai-Wu F11: {mat.F11}")
    print(f"Calculated Tsai-Wu F22: {mat.F22}")
    print(f"Calculated Tsai-Wu F12: {mat.F12}")
```

## Commands

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

```bash
material
```
*(Currently, this serves as an entry point defined in `material.main:main`)*