Metadata-Version: 2.4
Name: fibernet
Version: 1.25.0
Summary: A comprehensive fiber network generation and simulation toolkit for materials science research
Author: FiberNet Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/GellmanSparrowS/fibernet
Project-URL: Documentation, https://fibernet.readthedocs.io
Project-URL: Repository, https://github.com/GellmanSparrowS/fibernet
Project-URL: Issues, https://github.com/GellmanSparrowS/fibernet/issues
Keywords: fiber networks,materials science,finite element method,simulation,mechanical properties,computational materials,polymer physics,biomechanics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Provides-Extra: viz
Requires-Dist: pyvista>=0.37; extra == "viz"
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: mesh
Requires-Dist: trimesh>=3.20; extra == "mesh"
Provides-Extra: io
Requires-Dist: h5py>=3.7; extra == "io"
Provides-Extra: accel
Requires-Dist: taichi>=1.6; extra == "accel"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.0; extra == "ml"
Requires-Dist: tqdm>=4.60; extra == "ml"
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == "graph"
Provides-Extra: full
Requires-Dist: pyvista>=0.37; extra == "full"
Requires-Dist: matplotlib>=3.5; extra == "full"
Requires-Dist: trimesh>=3.20; extra == "full"
Requires-Dist: h5py>=3.7; extra == "full"
Requires-Dist: taichi>=1.6; extra == "full"
Requires-Dist: scikit-learn>=1.0; extra == "full"
Requires-Dist: networkx>=3.0; extra == "full"
Requires-Dist: tqdm>=4.60; extra == "full"
Requires-Dist: pyyaml>=6.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: matplotlib>=3.5; extra == "dev"
Requires-Dist: networkx>=3.0; extra == "dev"
Requires-Dist: pandas>=1.5; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: sphinx>=7.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Dynamic: license-file

<div align="center">

# 🧬 FiberNet

### A Research-Grade Python Toolkit for Fiber Network Generation, Simulation & Analysis
### 面向材料科学研究的纤维网络结构生成、力学模拟与分析工具包

---

[![PyPI](https://img.shields.io/pypi/v/fibernet?label=PyPI&color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/fibernet/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CI](https://github.com/GellmanSparrowS/fibernet/actions/workflows/ci.yml/badge.svg)](https://github.com/GellmanSparrowS/fibernet/actions/workflows/ci.yml)
[![Downloads](https://img.shields.io/pypi/dm/fibernet?label=Downloads&color=brightgreen)](https://pypi.org/project/fibernet/)
[![Docs](https://readthedocs.org/projects/fibernet/badge/?version=latest)](https://fibernet.readthedocs.io/)

**[Quick Start](#-quick-start)** · **[Features](#-key-features)** · **[Documentation](https://fibernet.readthedocs.io/)** · **[Tutorials](tutorials/)** · **[Examples](examples/)**

*Developed by [ML-BioMat Lab](https://ml-biomat.com/) @ [BMG-FDU](https://github.com/BMG-FDU)*

</div>

---

## 📖 Overview

FiberNet is a comprehensive Python toolkit for computational study of **fiber network structures** — from simple random deposition to architectured metamaterials. Designed at the *Nature Materials* level, it provides:

- **79+ network generators** spanning 14 architecture families
- **Custom FEM solver** (Euler-Bernoulli beam theory, built on NumPy + SciPy, no external FEM dependencies)
- **22+ physics modules** — mechanics, dynamics, fracture, thermal, electromagnetic, fluid, acoustic
- **Gibson-Ashby validation** — analytical benchmarks for cellular solid models
- **TPMS support** — Triply Periodic Minimal Surface lattice generation
- **Optional GPU acceleration** via [Taichi](https://github.com/taichi-dev/taichi)

```bash
pip install fibernet
```

---

## ⚡ Key Features

| Category | Capabilities |
|:---------|:-------------|
| **Generators** | 79+ across 14 families: random, ordered, chiral, woven, hierarchical, **TPMS** (gyroid, diamond, primitive), bundles, curved, laminates, fractal, gradient, biomimetic, CNT |
| **FEM Solver** | Custom Euler-Bernoulli 3D beam elements (12 DOF/element), sparse direct solver (SuperLU), Tikhonov regularization, h-refinement convergence |
| **Mechanics** | Linear elastic, nonlinear (Newton-Raphson), hyperelastic (Neo-Hookean, Mooney-Rivlin), plasticity, viscoelasticity, damage/fatigue, fracture (LEFM, cohesive zone) |
| **Validation** | Gibson-Ashby benchmarks, cantilever analytical solutions, patch tests, convergence studies |
| **Multi-Physics** | Thermal, electromagnetic, acoustic, fluid (Darcy flow), rheology, DMA, diffusion, coupled fields, buckling |
| **Analysis** | Morphology, topology, spectral, percolation, pore structure, homogenization, anisotropy, effective properties |
| **ML** | Feature extraction (30+), GNN models, property prediction, dataset generation |
| **I/O** | JSON, YAML, LAMMPS, VTK, GMSH, PDB, XYZ, HDF5, pandas DataFrames |
| **Visualization** | PyVista 3D interactive, matplotlib 2D, Plotly web, animations |
| **Acceleration** | Taichi CPU/GPU parallel FEM (optional) |

---

## 🚀 Quick Start

```python
import fibernet as fn

# 1. Generate a random 2D fiber network
net = fn.create("random_2d", num_fibers=100, fiber_length=10.0,
                box_size=(30, 30), seed=42)

# 2. Analyze structural properties
stats = fn.analyze(net)
print(f"Fibers: {stats['num_fibers']}, "
      f"Nematic order: {stats['nematic_order']:.3f}")

# 3. Run mechanical simulation (CPU, custom FEM)
from fibernet.sim.mechanical import FiberFEM
fem = FiberFEM(net, segments_per_fiber=5)
E_eff = fem.effective_modulus(strain=0.001)
print(f"Effective modulus: {E_eff:.2e} Pa")

# 4. Validate against Gibson-Ashby model
from fibernet.sim.validation import gibson_ashby_honeycomb
ga = gibson_ashby_honeycomb(relative_density=0.1, E_solid=1e9)
print(f"Gibson-Ashby E*: {ga['E1']:.2e} Pa")

# 5. Generate TPMS metamaterial
from fibernet.gen.tpms import tpms_lattice
gyroid = tpms_lattice(kind='gyroid', box_size=(10, 10, 10), resolution=30)
print(f"Gyroid lattice: {len(gyroid.fibers)} struts")
```

---

## 🏗️ Architecture

```
fibernet/
├── core/              Fiber, FiberNetwork, Material, Crosslink, PBC, Transform
├── gen/               79+ network generators (14 modules)
│   ├── ordered.py       Square, triangular, honeycomb, cubic, octet, kagome
│   ├── disordered.py    Random deposition, oriented, Poisson disk
│   ├── chiral.py        Helix, double helix, braid, twisted bundle
│   ├── woven.py         Plain, twill, satin, 3D orthogonal
│   ├── hierarchical.py  Bundle, gradient, core-shell, fractal
│   ├── metamaterials.py Re-entrant, chiral, star, arrowhead, diamond, gyroid
│   ├── tpms.py          Gyroid, Diamond, Primitive, I-WP, Neovius (NEW)
│   ├── bundles.py       Parallel, twisted, braided, tendon
│   ├── curved.py        Sinusoidal, helical, Bezier, crimped
│   ├── laminates.py     Unidirectional, cross-ply, angle-ply, sandwich
│   └── ...              (advanced, fractal, gradient, specialized, variants)
├── sim/               22+ physics modules
│   ├── mechanical.py    Custom FEM (Euler-Bernoulli beam, scipy.sparse)
│   ├── nonlinear.py     Newton-Raphson, hyperelastic, plasticity
│   ├── validation.py    Gibson-Ashby benchmarks, analytical tests (NEW)
│   ├── incremental_fem.py Incremental loading with damage
│   ├── buckling_analysis.py Eigenvalue buckling
│   └── ...              (dynamics, fracture, thermal, EM, fluid, acoustic, ...)
├── analysis/          Morphology, topology, percolation, homogenization
├── ml/                Feature extraction, GNN, prediction
├── viz/               PyVista 3D, matplotlib 2D, Plotly, animations
├── io/                JSON, YAML, LAMMPS, VTK, GMSH, PDB, XYZ, HDF5
└── utils/             Config, validation, parametric, batch, geometry, units
```

---

## 🔬 Mechanical Simulation (Custom FEM)

FiberNet implements a **custom finite element solver** — it does **not** wrap or depend on any existing open-source FEM library (FEniCS, SfePy, PyFEM, etc.).

### Technical Highlights

| Aspect | Implementation |
|:-------|:---------------|
| **Element type** | 3D Euler-Bernoulli beam (12 DOF/element: 3 translations + 3 rotations per node) |
| **Stiffness matrix** | Analytical 12×12 local stiffness with coordinate transformation |
| **Sparse solver** | `scipy.sparse.linalg.spsolve` (SuperLU direct) |
| **Regularization** | Tikhonov regularization for near-singular systems |
| **Nonlinear** | Newton-Raphson iteration with arc-length control |
| **Constitutive models** | Linear elastic, bilinear plasticity, Neo-Hookean, Mooney-Rivlin, Arruda-Boyce, Maxwell, Kelvin-Voigt |
| **Dependencies** | Only NumPy + SciPy (no heavy FEM stack) |

> 📖 See [docs/fem_implementation.md](docs/fem_implementation.md) for full mathematical details.

### Validation

```python
from fibernet.sim.validation import run_all_validations, print_validation_report

results = run_all_validations(E_solid=1e9)
print(print_validation_report(results))
```

**Benchmark tests:**
- ✅ Cantilever beam vs. Euler-Bernoulli analytical solution (δ = PL³/3EI)
- ✅ Patch test (uniform strain, machine precision)
- ✅ Gibson-Ashby scaling (E* ∝ ρ³ for honeycomb, E* ∝ ρ² for foam)
- ✅ h-refinement convergence study

---

## 🧊 TPMS Metamaterials

Triply Periodic Minimal Surfaces (TPMS) are zero-mean-curvature periodic surfaces widely used in lightweight structural design. FiberNet supports:

```python
from fibernet.gen.tpms import tpms_sheet, tpms_lattice, tpms_gradient

# Sheet-based TPMS (surface network)
gyroid = tpms_sheet(kind='gyroid', box_size=(10,10,10), resolution=50)

# Lattice TPMS (skeleton extraction)
diamond = tpms_lattice(kind='diamond', box_size=(10,10,10))

# Graded TPMS (functionally graded unit cell size)
graded = tpms_gradient(kind='gyroid', gradient_range=(0.5, 2.0))
```

**Supported types:** Gyroid, Diamond, Primitive, I-WP, Neovius, Lidinoid, F-RD

---

## 📦 Installation

```bash
# Standard installation
pip install fibernet

# Full installation with all optional dependencies
pip install fibernet[full]

# Development installation
git clone https://github.com/GellmanSparrowS/fibernet.git
cd fibernet && pip install -e ".[dev,full]"
```

**Optional dependency groups:**

| Group | Description |
|:------|:------------|
| `viz` | PyVista 3D + matplotlib 2D visualization |
| `mesh` | Trimesh mesh operations |
| `io` | HDF5 support via h5py |
| `accel` | Taichi GPU acceleration |
| `ml` | scikit-learn ML integration |
| `graph` | NetworkX graph analysis |
| `full` | All optional dependencies |

---

## 📊 Tutorials

| Tutorial | Description |
|:---------|:------------|
| [`01_getting_started.ipynb`](tutorials/01_getting_started.ipynb) | Installation, core concepts, basic workflow |
| [`02_mechanical_simulation.ipynb`](tutorials/02_mechanical_simulation.ipynb) | FEM mechanics, stress-strain, effective properties |
| [`03_machine_learning.ipynb`](tutorials/03_machine_learning.ipynb) | Feature extraction, GNN, property prediction |
| [`metamaterial_design.ipynb`](tutorials/metamaterial_design.ipynb) | Metamaterial gallery, parametric study, ML screening |
| [`04_reinforcement_validation.ipynb`](tutorials/04_reinforcement_validation.ipynb) | **TPMS, FEM validation, Gibson-Ashby, convergence** (NEW) |

---

## 📝 Citation

If you use FiberNet in your research, please cite:

```bibtex
@software{fibernet2025,
  title     = {FiberNet: A Comprehensive Python Toolkit for Fiber Network
               Generation, Simulation, and Analysis},
  author    = {FiberNet Contributors},
  year      = {2025},
  publisher = {GitHub},
  url       = {https://github.com/GellmanSparrowS/fibernet},
  version   = {1.24.0}
}
```

---

## 🙏 Acknowledgments

- Built with [NumPy](https://numpy.org/), [SciPy](https://scipy.org/), [NetworkX](https://networkx.org/), [matplotlib](https://matplotlib.org/), [PyVista](https://pyvista.org/), [Taichi](https://taichi-lang.org/)
- Supported by the [**ML-BioMat**](https://ml-biomat.com/) research group ([BMG-FDU](https://github.com/BMG-FDU))
- FEM validated against Gibson-Ashby cellular solid theory

---

## 📄 License

[MIT License](LICENSE) — free for academic and commercial use.

---
---

<a id="中文"></a>

## 📖 中文概述

FiberNet 是一个面向材料科学研究的**纤维网络结构**生成、模拟与分析 Python 工具包。

### 核心特点

- **79+ 网络生成器**：涵盖 14 个结构家族（随机、有序、手性、编织、层级、TPMS 等）
- **自研 FEM 求解器**：基于 Euler-Bernoulli 梁理论，仅依赖 NumPy + SciPy，不依赖任何开源 FEM 库
- **Gibson-Ashby 验证**：提供蜂窝材料和泡沫材料的解析解基准测试
- **TPMS 超材料**：支持 Gyroid、Diamond、Primitive 等三周期极小曲面结构
- **22+ 物理模块**：力学、动力学、断裂、热传导、电磁、流体、声学
- **GPU 加速**：可选 Taichi 后端（CPU 完整运行）

### 快速开始

```bash
pip install fibernet
```

```python
import fibernet as fn

net = fn.create("random_2d", num_fibers=100, fiber_length=10.0)
stats = fn.analyze(net)
print(f"纤维数: {stats['num_fibers']}, 向序参数: {stats['nematic_order']:.3f}")
```

### 力学模拟说明

FiberNet 的力学模拟采用**完全自研的有限元实现**：
- 单元类型：3D Euler-Bernoulli 梁单元（12 DOF/单元）
- 稀疏求解：scipy.sparse + SuperLU
- 非线性：Newton-Raphson 迭代
- 本构模型：线弹性、双线性塑性、超弹性（Neo-Hookean）、粘弹性（Maxwell, Kelvin-Voigt）
- 验证：悬臂梁解析解、Patch Test、Gibson-Ashby 标度律

---

<div align="center">

**[⬆ Back to Top](#-fibernet)** · **[PyPI](https://pypi.org/project/fibernet/)** · **[Docs](https://fibernet.readthedocs.io/)** · **[GitHub](https://github.com/GellmanSparrowS/fibernet)**

</div>
