Metadata-Version: 2.4
Name: truss_analysis
Version: 2.5.0
Summary: 2D Truss Analysis Tool - scientifically validated
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: arabic_reshaper
Requires-Dist: python-bidi
Requires-Dist: numpy>=1.24.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: scienceplots>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Dynamic: license-file

# 🏗️ Truss Analysis 2D

**Read this in:** [English](README.md) | [فارسی](README.fa.md)

> **A scientific 2D truss analysis tool with thermodynamic validation.**

[![CI Pipeline](https://github.com/bmhmdyan279-png/truss-analysis-2d/actions/workflows/ci.yml/badge.svg)](https://github.com/bmhmdyan279-png/truss-analysis-2d/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-90.5%25-brightgreen)](https://github.com/bmhmdyan279-png/truss-analysis-2d)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/truss-analysis.svg)](https://pypi.org/project/truss-analysis/)
[![PyPI downloads](https://img.shields.io/pypi/dm/truss-analysis)](https://pypi.org/project/truss-analysis/)

---

## 📚 Table of Contents

- [📦 Installation](#-installation)
- [🚀 Quick Start](#-quick-start)
- [🖼️ Visual Output Example](#️-visual-output-example)
- [📖 Input JSON Format](#-input-json-format)
- [📤 Output Format](#-output-format)
- [🎯 Key Features](#-key-features)
- [🧪 Testing](#-testing)
- [📁 Project Structure](#-project-structure)
- [🤝 Contributing](#-contributing)
- [📚 Citation](#-citation)
- [📄 License](#-license)
- [🙏 Acknowledgments](#-acknowledgments)

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install truss-analysis
```

> **Note:** The package name on PyPI is `truss-analysis` (without `-2d`). The repository name is `truss-analysis-2d`.

### From Source (for development or latest changes)

```bash
git clone https://github.com/bmhmdyan279-png/truss-analysis-2d.git
cd truss-analysis-2d
pip install -e ".[dev]"
```

### Using requirements.txt

```bash
# For runtime only
pip install -r requirements.txt

# For development (includes testing & linting tools)
pip install -r requirements-dev.txt
```

### Quick Verification

```bash
# Run all tests
pytest

# Run a quick example
truss-analysis examples/example1.json
```

---

## 🚀 Quick Start

### CLI Usage

```bash
# Basic analysis
truss-analysis input.json

# With multiple outputs
truss-analysis input.json --output result.json --csv forces.csv --report report.md

# With visualization and buckling check
truss-analysis input.json --plot --check-buckling --plot-path diagram.png
```

### Python API

```python
from truss_analysis.main import run

# Run analysis
result = run("input.json", check_buckling=True)

# Access results
print(result.summary())
print(f"Displacements: {result.displacements}")
print(f"Element forces: {result.element_forces}")
print(f"Reactions: {result.reactions}")
print(f"Equilibrium valid: {result.equilibrium['is_valid']}")
```

---

## 🖼️ Visual Output Example

Below is a sample visualization generated using the `--plot` flag. The dashed lines represent the deformed shape, while the solid lines show the original truss geometry. Colors indicate element stress states (tension in blue, compression in red).

![Truss Analysis Result](docs/images/example_output.png)

*Deformed vs. original shape for `examples/example1.json`*

---

## 📖 Input JSON Format

```json
{
  "units": "SI",
  "nodes": [
    {"id": 1, "x": 0.0, "y": 0.0, "is_support": true, "support_dx": true, "support_dy": true},
    {"id": 2, "x": 3.0, "y": 0.0, "is_support": false},
    {"id": 3, "x": 0.0, "y": 4.0, "is_support": true, "support_dx": true, "support_dy": true}
  ],
  "elements": [
    {"id": 1, "node_i": 1, "node_j": 2, "E": 200e9, "A": 0.001},
    {"id": 2, "node_i": 2, "node_j": 3, "E": 200e9, "A": 0.002},
    {"id": 3, "node_i": 1, "node_j": 3, "E": 200e9, "A": 0.0015}
  ],
  "loads": [
    {"node_id": 2, "Fx": 10000.0, "Fy": -5000.0}
  ]
}
```

### Optional Element Parameters

| Parameter | Description | Unit |
|-----------|-------------|------|
| `alpha` | Thermal expansion coefficient | 1/°C |
| `delta_T` | Temperature change | °C |
| `delta_L_free` | Free length change | m |
| `I_sec` | Moment of inertia (for buckling) | m⁴ |
| `rho` | Density (for self-weight) | kg/m³ |

---

## 📤 Output Format

### JSON Output Structure

```json
{
  "status": "converged",
  "displacements": {
    "2": {"dx": 0.00234, "dy": -0.00567}
  },
  "element_forces": [
    {
      "id": "1",
      "N": 15234.5,
      "status": "tension",
      "sigma": 15.23e6,
      "strain": 7.6e-5
    }
  ],
  "reactions": {
    "1": {"Fx": -8000.0, "Fy": 3500.0}
  },
  "equilibrium": {
    "sum_fx": 1.2e-10,
    "sum_fy": 3.4e-11,
    "is_valid": true
  }
}
```

### Units

All outputs are in SI units:

| Quantity | Unit |
|----------|------|
| Displacement | m |
| Force | N |
| Stress | Pa |

---

## 🎯 Key Features

### 1. Scientific Accuracy

- **Generalized Clapeyron theorem:** `W_mech = U_strain + 0.5 * W_prestress`
- **Effect separation:** `δL_mech = δL_total - δL_prestress`
- **Static equilibrium:** ΣFx=0, ΣFy=0, ΣM=0
- **Mechanism detection:** Singular matrix error

### 2. Engineering Capabilities

- **Euler buckling:** `P_cr = π²EI/L²` for compression members
- **Slenderness ratio:** `λ = L/r` with `r = √(I/A)`
- **Self-weight:** From element density
- **SI/Imperial units:** Automatic conversion

### 3. Output Formats

- **JSON:** Complete structured results
- **CSV:** Element forces
- **Markdown:** Human-readable report
- **Plot:** Original and deformed truss

---

## 🧪 Testing

### Running Tests

```bash
# Run all tests
pytest

# With coverage report
pytest --cov=src/truss_analysis --cov-report=term-missing

# With coverage threshold enforcement (as in CI)
pytest --cov=src/truss_analysis --cov-report=term-missing --cov-fail-under=90
```

**Current status:** 39 tests passing, 90.5% coverage (threshold: 90%)

### Linting & Type Checking

```bash
# Run ruff (linter + formatter)
ruff check .
ruff format --check .

# Run mypy
mypy src/
```

---

## 📁 Project Structure

```
truss-analysis-2d/
├── src/
│   └── truss_analysis/
│       ├── __init__.py
│       ├── _version.py
│       ├── assembly.py
│       ├── exceptions.py
│       ├── fileio.py
│       ├── main.py
│       ├── model.py
│       ├── postprocess.py
│       ├── solver.py
│       ├── units.py
│       └── visualization.py
├── tests/
│   ├── test_analytical.py
│   ├── test_assembly.py
│   ├── test_dof_mapping.py
│   ├── test_e2e_cli.py
│   ├── test_exceptions.py
│   ├── test_fileio.py
│   ├── test_golden.py
│   ├── test_golden_phase3.py
│   ├── test_model.py
│   ├── test_phase2_cli_coverage.py
│   ├── test_solver.py
│   └── test_units.py
├── docs/
│   ├── theory.md
│   ├── error_codes.md
│   └── images/
│       └── example_output.png
├── examples/
│   ├── example1.json
│   ├── example2.json
│   ├── reference_problem.json
│   └── example_analysis.py
├── .github/
│   └── workflows/
│       ├── ci.yml
│       ├── publish.yml
│       └── release.yml
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── .pre-commit-config.yaml
├── CONTRIBUTING.md
├── CONTRIBUTING.fa.md
├── LICENSE
└── README.md
```

---

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
git clone https://github.com/bmhmdyan279-png/truss-analysis-2d.git
cd truss-analysis-2d
pip install -e ".[dev]"
pre-commit install
pytest
```

---

## 📚 Citation

If you use this software in your research, please cite:

```bibtex
@software{truss_analysis_2d,
  author = {bmhmdyan279-png},
  title = {Truss Analysis 2D: Scientific Truss Solver},
  year = {2026},
  url = {https://github.com/bmhmdyan279-png/truss-analysis-2d},
  version = {2.4.0}
}
```

---

## 📄 License

This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **NumPy** for matrix computations
- **Matplotlib** for visualization
- **SciPy** for sparse matrix operations
- **Pytest** for testing framework
- **Ruff** for linting and formatting
- **setuptools_scm** for automatic versioning
- **arabic-reshaper** and **python-bidi** for Persian text rendering support

## 🐳 Quick Reproducibility (Phase 11)

To independently verify the H1 test (Phase 8) on the `uniform_beta_problem.json` baseline without setting up a local Python environment, use the provided multi-stage Docker image. This guarantees exact dependency resolution (including `scienceplots`, `arabic-reshaper`, and headless Matplotlib configurations) aligned with commit `cbf1f5c`.

**1. Build the Docker Image:**
```bash
docker build -t truss-scf:phase11 .
```

**2. Run the H1 Test (Stdout Output):**
```bash
docker run --rm truss-scf:phase11
```
*Expected Behavior:* The container will execute `scripts/compute_phase8_h1_test.py`, compute the SCF vector using $\alpha$-degradation ($\alpha=0.7$), perform 5000 Bootstrap resampling iterations, and print the Gini and Log-Ratio metrics with their 95% Confidence Intervals directly to `stdout`.

**3. Extract Raw JSON Evidence:**
If you wish to inspect the raw JSON payload (`phase8_raw.json`) generated by the script for audit purposes:
```bash
docker run --rm -v $(pwd)/reproducibility_out:/app/PROJECT_DOCUMENTATION truss-scf:phase11
```
This mounts a local directory to capture the exact numerical artifacts referenced in `VALIDATION_LOG.md`.
