FiberNet v4

纤维网络材料计算设计平台 / 

A Computational Design Platform for Fiber Network Materials

FiberNet 是面向材料科学与生物力学研究的 Python 工具包，专为纤维网络的参数化设计、多模型物理仿真与数据驱动优化而构建。工具包以结构–性能关系的定量建模为核心，覆盖从拓扑基元参数化生成和动态仿真，到特征提取、机器学习性能预测，再到强化学习结构搜索的完整闭环。研究者可在统一 Python 环境中系统积累仿真数据、构建预测模型并驱动智能结构优化。

FiberNet is a Python toolkit for materials science and biomechanics research, purpose-built for the parametric design, multi-model physical simulation, and data-driven optimization of fiber network. The toolkit covers the complete closed loop from parametric generation and dynamic simulation through feature extraction to ML-based performance prediction and RL-driven structural search — all within a unified Python environment.

两种调用深度，同一底层引擎 / 

Two Levels of Depth, One Shared Engine

FiberNet 提供两种调用深度，均基于同一底层引擎。简洁接口用极少代码完成结构生成、仿真与可视化，适合快速探索与原型验证；完整流水线接口暴露所有配置参数与中间结果，适合系统性数据生产和精细研究分析。两种模式可自由混用，能力层面无本质差别，仅控制粒度不同。

FiberNet exposes two levels of calling depth, both built on the same underlying engine. The concise interface completes structure generation, simulation, and visualization with minimal code — ideal for rapid prototyping. The full pipeline interface exposes every configuration parameter and intermediate result, suited for systematic data production. The two modes can be freely mixed; there is no fundamental difference in capability, only in degree of control.

简洁接口 / Concise Interface

import fibernet as fn

g = fn.pattern_2d(unit='honeycomb', box=(10, 10), grid=(4, 4))
fn.show(g)                    # Jupyter 内联渲染 / renders inline in Jupyter
r = fn.simulate(g, mode='stretch', strain=1.5, backend='spring')
print(f'max force = {r.max_force:.0f} N,  max stretch = {r.max_stretch:.3f}')

完整流水线 / Full Pipeline

import fibernet as fn
import numpy as np
import matplotlib.pyplot as plt

# 1. 参数化结构生成 / Parametric structure generation (20 displacement params)
displacements = [(np.random.uniform(-0.3, 0.3), np.random.uniform(-0.3, 0.3))
                 for _ inrange(20)]
g = fn.pattern_2d(unit='square', box=(10, 10), grid=(3, 3),
                  n_pts_per_side=5, point_displacements=displacements)

# 2. 力学仿真（20% 加载斜坡 + 80% 弛豫）/ Simulation (20% ramp + 80% relaxation)
engine = fn.TaichiEngine()
r = engine.stretch_test(g, target_stretch=1.5, stiffness=1e5,
                         damping=0.3, num_steps=5000,
                         ramp_fraction=0.2, save_interval=1000)

# 3. 内联可视化（传入 ax，Jupyter 自动展示）/ Inline display — pass ax for Jupyter
fig, ax = plt.subplots()
fn.render_graph(g, ax=ax, theme='dark', color_by='uniform', line_width=1.5)

# 4. 特征提取 / Feature extraction
features = fn.GraphFeatureExtractor().extract(g)

# 5. 节点操作（RL 动作空间接口）/ Node manipulation — RL action space interface
g.displace_node(g.get_internal_nodes()[0], [0.1, 0.2])

通过 pip 安装 / 

Install via pip

核心包仅依赖少量基础库，可立即开始结构生成与基本仿真。安装 [full] 变体将一次性拉取机器学习、强化学习、GPU 加速与可视化所有扩展依赖，无需逐步补装。

The core package depends only on lightweight base libraries and lets you start immediately. Installing the [full] variant pulls in all extension dependencies for ML, RL, GPU acceleration, and visualization in one shot.

可选扩展组 / Optional Extra Groups

核心接口速查 / 

Core Interface Guide

以下各模块接口覆盖完整工作流，可独立调用或链式组合。常用入口点也可通过顶层 fibernet 命名空间直接访问。

The module interfaces below cover the complete workflow and can be called individually or chained. Every module can be imported on its own, or accessed through the top-level fibernet namespace for the most commonly used entry points.

结构生成 / Structure Generation

disps = [(np.random.uniform(-0.3, 0.3), np.random.uniform(-0.3, 0.3))
         for _ inrange(20)]

g = fn.pattern_2d(
    unit='square',               # 基元类型 / primitive type — see list_units()box=(10, 10),               # 单元格尺寸 / unit-cell sizegrid=(3, 3),               # 平铺数量 / tiling grid countn_pts_per_side=5,           # 每边内节点数 / internal nodes per edgepoint_displacements=disps,  # 参数化位移（RL动作空间）/ parametric displacementsseed=42,
)

print(fn.list_units())  # 列出所有基元 / list all available primitives

节点操作（RL 动作空间接口）/ Node Manipulation (RL Action Space)

g.displace_node(node_id, [dx, dy])                   # 相对位移 / relative displacement
g.set_node_position(node_id, [x, y])                 # 绝对坐标 / absolute coordinates
g.set_node_positions({1: [2.5, 0.5], 3: [7.5, 1.0]})  # 批量更新 / batch update
internal = g.get_internal_nodes()  # RL 可控节点列表 / RL-controllable node list
boundary = g.get_boundary_nodes()  # 边界约束节点列表 / boundary-constrained node list

力学仿真 / Mechanical Simulation

engine = fn.TaichiEngine()
r = engine.stretch_test(
    g,
    target_stretch=1.5,    # 目标拉伸比 / target stretch ratiostiffness=1e5,         # 弹簧刚度 N/m / spring stiffness (N/m)damping=0.3,           # 阻尼比 / damping rationum_steps=5000,        # 总积分步数 / total integration stepsramp_fraction=0.2,     # 20% 加载斜坡 + 80% 弛豫 / 20% ramp + 80% relaxationsave_interval=1000,
)

r.max_force             # 峰值边力 (N) / peak edge force (N)
r.edge_forces           # 各边力数组 / per-edge force array
r.edge_stretches        # 各边拉伸比 / per-edge stretch ratio array
r.positions_trajectory  # 完整轨迹 / trajectory — list of (N,3) arrays
r.deformed_positions    # 最终变形位置 / final deformed positions
r.save('result.json', detailed=True)
r2 = fn.SimResult.load('result.json')

可视化 / Visualization

# 推荐：传入 ax 对象，Jupyter 自动内联 / Pass ax for inline Jupyter display — no plt.show()
fig, ax = plt.subplots()
fn.render_graph(g, ax=ax, theme='dark', color_by='uniform',
               line_width=1.5, show_nodes=False)

# 变形前后对比 / Before/after deformation comparison
fig = fn.render_deformation(g_original, g_deformed, color_by='stress')

# 多帧拉伸轨迹 / Multi-frame stretch trajectory
fig = fn.render_trajectory(g, r.positions_trajectory, r.edge_stretches,
                           n_frames=6, title='Stretch Process')

机器学习 / Machine Learning

from fibernet.ml import predict_from_csv, train_predictor, cross_validate

# 一键流程：加载→训练→评估→可视化→保存 / One call: load → train → evaluate → visualize → save
result = predict_from_csv('sim_results.csv', target='max_force',
                          model_type='rf', output_dir='ml_out/')

# 手动流程 / Manual workflow
model, metrics = train_predictor(X, y, model_type='rf')
print(f"R² = {metrics['r2']:.3f}")
cv = cross_validate(X, y, model_type='ridge', cv=5)

强化学习 / Reinforcement Learning

from fibernet.rl import run_bayesian_optimization, plot_reward_curve, plot_convergence

# 贝叶斯优化（via scikit-optimize）/ Bayesian optimization
result = run_bayesian_optimization(
    objective_fn,
    param_space={'grid_x': (2, 5), 'stiffness': (1e4, 1e6)},
    n_iter=50,
)

plot_reward_curve(rewards, window=20, save_path='reward.png')
plot_convergence(objectives, minimize=True, save_path='conv.png')

物理模型与参数化结构控制 / 

Physical Model & Parametric Structural Control

仿真引擎 / Simulation Engine

FiberNet 力学仿真框架以 Taichi 实现 GPU 加速跨平台计算，架构支持灵活扩展至其他物理模型。当前稳定实现为质量-弹簧动力学模型：网络拓扑映射为节点（质点）与边（弹性单元）构成的图，显式时间积分在弹性回复力、阻尼力和外载共同作用下迭代更新节点速度与位置。完整仿真分两阶段：首先弛豫至无残余应力的力学平衡状态，随后以受控位移加载至目标拉伸比；全程记录节点轨迹、各边力和各边拉伸比。

FiberNet's simulation framework uses Taichi for GPU-accelerated computation and is architecturally designed for flexible extension to additional physical models. The current stable implementation is a mass-spring dynamics model: the network topology is mapped to a graph of nodes and edges, and explicit time integration iteratively updates velocities and positions. Simulations run in two phases — an initial relaxation to establish a residual-stress-free equilibrium, followed by controlled loading to the target stretch ratio. Full nodal trajectories, per-edge forces, and per-edge stretch ratios are recorded throughout.

• Nodes质点，存储位置与速度状态；边界节点施加 Dirichlet 位移约束Mass points with position and velocity state; boundary nodes carry Dirichlet displacement constraints

• Edges弹性单元，可独立配置刚度 k 与自然长度 L₀Elastic units with individually configurable stiffness k and rest length L₀

• 弛豫 / Relax加载前能量最小化阶段，消除几何构造时引入的残余应力Pre-loading energy minimization phase eliminating residual stresses introduced during geometric construction

• 加载 / Load受控位移加载至目标拉伸比 λ，完整记录变形轨迹与力场分布Controlled displacement to target stretch ratio λ; full deformation trajectory and force-field distribution recorded

• 扩展 / Extend架构支持后续集成有限元、粗粒化及其他物理模型Architecture accommodates future integration of finite-element, coarse-grained, and other physical models

参数化结构控制 / Parametric Structural Control

每条边支持 n_pts_per_side 个内节点，每个节点携带一个可编程的 (dx, dy) 位移参数。这构成一个连续动作空间，允许强化学习 agent 将网络拓扑直接编码为参数向量，从仿真器获得力学性能奖励信号，在端到端闭环中联合优化结构与性能。

Each edge supports n_pts_per_side internal nodes, each carrying a programmable (dx, dy) displacement parameter. This forms a continuous action space allowing an RL agent to encode network topology as a parameter vector, receive mechanical performance as a reward signal, and jointly optimize structure and properties in an end-to-end loop.

RL 参数化控制接口 / 

RL Parametric Control Interface

FiberNet 将每条边上每个内节点的 (dx, dy) 位移参数直接暴露为强化学习动作空间。每一步 agent 输出的参数向量完整决定网络拓扑；力学仿真输出的峰值力、能量耗散、均匀性指标等作为奖励信号返回，支持贝叶斯优化、交叉熵方法及策略梯度等多种策略，自动搜索目标力学性能下的最优结构。

FiberNet exposes the (dx, dy) displacement parameters of every internal node on every edge directly as a reinforcement learning action space. At each step, the agent outputs a parameter vector that fully determines the network topology. Mechanical simulation outputs — peak force, energy dissipation, uniformity metrics — are returned as reward signals, supporting Bayesian optimization, cross-entropy methods, and policy gradient strategies for automated structural search.

# 40 维动作向量 → 20 对 (dx,dy)，每分量 ∈ [-0.3, 0.3]# 40-dim action vector → 20 (dx,dy) pairs, each component ∈ [-0.3, 0.3]
action = agent.act(obs)                          # shape: (40,)
displacements = [(action[2*i], action[2*i+1])
                 for i inrange(20)]

g = fn.pattern_2d(unit='square', grid=(3, 3),
                  n_pts_per_side=5, point_displacements=displacements)
r = engine.stretch_test(g, target_stretch=1.5, stiffness=1e5)
reward = r.max_force

结构生成与力学分析示例 / 

Structure Generation & Mechanical Analysis Examples

变形后各基元类型 2D 结构示例 / Example 2-D structures after deformation

各类基元经参数化内节点扰动后的可视化结果（见 list_units()）。

Parameterized structures for each primitive type after programmatic internal-node displacement perturbation (see list_units()).

Voronoi 结构 1.5× 单轴拉伸 / Voronoi structure — 1.5× uniaxial stretch

Voronoi 结构在 1.5× 单轴拉伸下的变形状态与各边拉伸比分布。

Deformed state and per-edge stretch ratio distribution of a Voronoi structure under 1.5× uniaxial tension.

蜂窝拉伸轨迹 — 逐帧展示，按边拉伸比着色 / Honeycomb stretch trajectory — frame-by-frame, colored by edge stretch ratio

蜂窝结构单轴拉伸过程的 8 帧可视化；颜色编码各边拉伸比，青色为固定边界，品红色为加载边界。

Eight-frame visualization of a honeycomb structure during uniaxial stretching; color encodes per-edge stretch ratio. Cyan marks the fixed boundary; magenta marks the loaded boundary.

机器学习分析 — 混淆矩阵 / ROC 曲线 / 学习曲线 / ML analysis — confusion matrix / ROC curve / learning curve

随机森林：混淆矩阵、ROC 曲线及 OOB 学习曲线。

Random-forest: confusion matrix, ROC curve, and OOB learning curve.

强化学习 — 奖励曲线与最优奖励历史 / reinforcement learning — reward curve & best-reward history

强化学习 200 轮：逐轮奖励分布与单调递增的最优奖励历史。

reinforcement learning over 200 episodes: per-episode reward distribution and monotonically increasing best-reward history.