fibernet 1.25.0

A comprehensive fiber network generation and simulation toolkit for materials science research

🧬 FiberNet

A Research-Grade Python Toolkit for Fiber Network Generation, Simulation & Analysis

面向材料科学研究的纤维网络结构生成、力学模拟与分析工具包

---

Quick Start · Features · Documentation · Tutorials · Examples

Developed by ML-BioMat Lab @ BMG-FDU

---

📖 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

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

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 for full mathematical details.

Validation

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:

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

# 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	Installation, core concepts, basic workflow
02_mechanical_simulation.ipynb	FEM mechanics, stress-strain, effective properties
03_machine_learning.ipynb	Feature extraction, GNN, property prediction
metamaterial_design.ipynb	Metamaterial gallery, parametric study, ML screening
04_reinforcement_validation.ipynb	TPMS, FEM validation, Gibson-Ashby, convergence (NEW)

---

📝 Citation

If you use FiberNet in your research, please cite:

@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, SciPy, NetworkX, matplotlib, PyVista, Taichi
• Supported by the ML-BioMat research group (BMG-FDU)
• FEM validated against Gibson-Ashby cellular solid theory

---

📄 License

MIT License — free for academic and commercial use.

---

---

📖 中文概述

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

核心特点

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

快速开始

pip install fibernet

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 标度律

---

⬆ Back to Top · PyPI · Docs · GitHub