fibernet 1.24.0__py3-none-any.whl

fibernet/__init__.py

@@ -0,0 +1,167 @@
+"""
+FiberNet - A comprehensive toolkit for fiber network structure research.
+
+Provides tools for:
+- Generation: 2D/3D fiber networks (ordered, disordered, chiral, bundled, woven, hierarchical)
+- Simulation: Mechanical, dynamics, fracture, thermal, electromagnetic, fluid, acoustic
+- Analysis: Topology, morphology, properties, percolation, multi-scale
+- Visualization: 3D rendering, animation, 2D plots, interactive
+- Machine Learning: Feature extraction, GNN models
+
+Homepage: https://ml-biomat.com
+GitHub: https://github.com/GellmanSparrowS/fibernet
+
+Quick Start
+-----------
+>>> import fibernet as fn
+>>> # Create a random 2D network
+>>> net = fn.create("random_2d", num_fibers=100, fiber_length=10.0, box_size=(20, 20))
+>>> # Analyze structure
+>>> stats = fn.analyze(net)
+>>> # Run mechanical simulation
+>>> result = fn.simulate_mechanics(net, strain=0.01)
+>>> # Visualize
+>>> fn.plot(net)
+
+For more examples, see the tutorials/ directory.
+"""
+
+__version__ = "1.24.0"
+__author__ = "ML-BioMat Lab"
+
+# Core data structures
+from fibernet.core.fiber import Fiber
+from fibernet.core.network import FiberNetwork
+from fibernet.core.material import Material
+from fibernet.core.copy_utils import copy_fiber, copy_material, copy_network
+
+# High-level convenience API
+from .api import (
+    create, mirror, rotate, scale, translate, merge, tile,
+    simulate_mechanics, simulate_thermal, analyze, export, load, plot,
+)
+
+# Version information
+from .version import __version__, __author__, __license__
+
+# Simulation modules (lazy imports for optional dependencies)
+from .sim.fluid import DarcySolver, PoreNetworkModel
+from .sim.acoustic import AcousticSolver
+
+# Visualization module
+from . import viz
+
+# ML module (optional)
+try:
+    from . import ml
+except ImportError:
+    ml = None
+
+# Submodules for advanced usage
+from . import gen      # Network generators
+from . import sim      # Simulators
+from . import analysis # Analyzers
+from . import io       # I/O utilities
+from . import utils    # Utilities
+
+__all__ = [
+    # Core classes
+    "Fiber",
+    "FiberNetwork", 
+    "Material",
+    "copy_fiber",
+    "copy_material",
+    "copy_network",
+    
+    # High-level API
+    "create",
+    "mirror",
+    "rotate",
+    "scale",
+    "translate",
+    "merge",
+    "tile",
+    "simulate_mechanics",
+    "simulate_thermal",
+    "analyze",
+    "export",
+    "load",
+    "plot",
+    
+    # Simulators
+    "DarcySolver",
+    "PoreNetworkModel",
+    "AcousticSolver",
+    
+    # Submodules
+    "gen",
+    "sim",
+    "analysis",
+    "io",
+    "viz",
+    "ml",
+    "utils",
+    
+    # Metadata
+    "__version__",
+    "__author__",
+    "__license__",
+]
+
+# Visualization
+from .visualization import (
+    NetworkVisualizer, PlotStyle, visualize_network
+)
+__all__.extend([
+    "NetworkVisualizer", "PlotStyle", "visualize_network"
+])
+
+# Design of Experiments
+from .doe import (
+    DesignOfExperiments, ExperimentDesign, ExperimentResult, SweepResult,
+    run_parameter_sweep
+)
+__all__.extend([
+    "DesignOfExperiments", "ExperimentDesign", "ExperimentResult", "SweepResult",
+    "run_parameter_sweep"
+])
+
+# Materials database
+from .materials import (
+    get_material, list_materials, compare_materials, get_material_database, m
+)
+__all__.extend([
+    "get_material", "list_materials", "compare_materials", "get_material_database", "m"
+])
+
+# Unit conversions
+from .units import (
+    convert_length, convert_force, convert_pressure, convert_temperature,
+    convert_energy, parse_unit_string, scale_network_properties
+)
+__all__.extend([
+    "convert_length", "convert_force", "convert_pressure", "convert_temperature",
+    "convert_energy", "parse_unit_string", "scale_network_properties"
+])
+
+# PyVista visualization (lazy import to avoid VTK segfaults in CI)
+import os as _os
+if _os.environ.get("CI") != "true":
+    from .pyvista_viz import PyVistaVisualizer, visualize_network_3d, PYVISTA_AVAILABLE
+else:
+    PYVISTA_AVAILABLE = False
+    PyVistaVisualizer = None
+    visualize_network_3d = None
+__all__.extend([
+    "PyVistaVisualizer", "visualize_network_3d", "PYVISTA_AVAILABLE"
+])
+
+# Trimesh integration
+from .trimesh_integration import (
+    TrimeshConverter, network_to_trimesh, analyze_mesh_properties,
+    boolean_operation, repair_mesh, simplify_mesh, TRIMESH_AVAILABLE
+)
+__all__.extend([
+    "TrimeshConverter", "network_to_trimesh", "analyze_mesh_properties",
+    "boolean_operation", "repair_mesh", "simplify_mesh", "TRIMESH_AVAILABLE"
+])

fibernet/analysis/__init__.py

@@ -0,0 +1,65 @@
+"""
+Analysis tools for fiber networks.
+分析工具模块，用于纤维网络结构分析。
+
+Submodules / 子模块:
+- topology: Graph-theoretic analysis / 图论分析
+- morphology: Geometric characterization / 几何表征
+- properties: Effective property estimation / 有效性能估算
+- advanced: Spectral analysis, pore distribution, anisotropy, fingerprinting
+- stress_strain: Stress-strain curve extraction and analysis
+"""
+
+from fibernet.analysis.morphology import MorphologyAnalyzer
+from fibernet.analysis.properties import PropertyEstimator
+
+# Topology requires networkx; guard import for CI minimal installs
+try:
+    from fibernet.analysis.topology import TopologyAnalyzer
+except (ImportError, NameError):
+    TopologyAnalyzer = None
+
+try:
+    from fibernet.analysis.advanced import (
+        SpectralAnalyzer, PoreAnalyzer, AnisotropyAnalyzer, StructuralFingerprint,
+    )
+except ImportError:
+    pass
+
+try:
+    from fibernet.analysis.stress_strain import (
+        StressStrainCurve, extract_stress_strain, compare_curves,
+    )
+except ImportError:
+    pass
+
+__all__ = [
+    "MorphologyAnalyzer", "PropertyEstimator",
+]
+
+if TopologyAnalyzer is not None:
+    __all__.append("TopologyAnalyzer")
+
+# Statistical analysis
+from fibernet.analysis.statistics import StatisticalAnalyzer
+
+# NetworkX integration
+try:
+    from fibernet.analysis.networkx_integration import (
+        to_networkx, compute_centrality, detect_communities,
+        compute_graph_metrics, find_shortest_path, compute_small_world_metrics,
+    )
+except ImportError:
+    pass
+
+__all__ += [
+    "StatisticalAnalyzer",
+]
+
+# Percolation analysis
+from fibernet.analysis.percolation import (
+    PercolationAnalyzer, PercolationResult, estimate_percolation_threshold,
+)
+__all__ += [
+    "PercolationAnalyzer", "PercolationResult", "estimate_percolation_threshold",
+]

fibernet/analysis/advanced.py

@@ -0,0 +1,269 @@
+"""
+Advanced analysis tools for fiber networks.
+
+Provides:
+- Spectral analysis (eigenvalues of graph Laplacian)
+- Pore size distribution estimation
+- Percolation threshold finding
+- Anisotropy tensor analysis
+- Structural fingerprinting
+"""
+
+import numpy as np
+from typing import Dict, List, Tuple, Optional
+from fibernet.core.network import FiberNetwork
+
+
+class SpectralAnalyzer:
+    """Spectral graph analysis of fiber networks."""
+    
+    def __init__(self, network: FiberNetwork):
+        self.network = network
+        self._graph = None
+        self._laplacian = None
+    
+    @property
+    def graph(self):
+        if self._graph is None:
+            self._graph = self.network.to_networkx()
+        return self._graph
+    
+    def laplacian_eigenvalues(self, k: int = None) -> np.ndarray:
+        """Compute eigenvalues of the graph Laplacian.
+        
+        Parameters
+        ----------
+        k : int, optional
+            Number of eigenvalues to compute. Defaults to min(n, 20).
+        """
+        import networkx as nx
+        
+        n = len(self.graph.nodes)
+        if n < 2:
+            return np.array([])
+        
+        if k is None:
+            k = min(n - 1, 20)
+        
+        L = nx.laplacian_matrix(self.graph).astype(float)
+        
+        if n <= 100:
+            eigenvalues = np.linalg.eigvalsh(L.toarray())
+        else:
+            from scipy.sparse.linalg import eigsh
+            eigenvalues = eigsh(L, k=min(k, n - 1), which='SM', return_eigenvectors=False)
+        
+        return np.sort(eigenvalues)
+    
+    def spectral_gap(self) -> float:
+        """Spectral gap (second smallest Laplacian eigenvalue).
+        
+        Related to algebraic connectivity and network robustness.
+        """
+        eigs = self.laplacian_eigenvalues(k=5)
+        if len(eigs) >= 2:
+            return float(eigs[1])
+        return 0.0
+    
+    def spectral_entropy(self) -> float:
+        """Spectral entropy of the Laplacian spectrum.
+        
+        Measures the complexity/disorder of the network structure.
+        """
+        eigs = self.laplacian_eigenvalues()
+        if len(eigs) == 0:
+            return 0.0
+        
+        eigs = np.maximum(eigs, 1e-12)
+        p = eigs / eigs.sum()
+        entropy = -np.sum(p * np.log(p + 1e-12))
+        return float(entropy)
+    
+    def algebraic_connectivity(self) -> float:
+        """Algebraic connectivity (Fiedler value).
+        
+        Higher values indicate better-connected networks.
+        """
+        return self.spectral_gap()
+
+
+class PoreAnalyzer:
+    """Estimate pore size distribution in fiber networks."""
+    
+    def __init__(self, network: FiberNetwork):
+        self.network = network
+    
+    def pore_size_distribution(
+        self,
+        num_samples: int = 1000,
+        seed: Optional[int] = None,
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """Estimate pore size distribution using random sampling.
+        
+        For each random point in the bounding box, finds the
+        distance to the nearest fiber surface.
+        
+        Returns
+        -------
+        radii : np.ndarray
+            Sampled pore radii.
+        histogram : np.ndarray
+            Normalized histogram values.
+        """
+        rng = np.random.default_rng(seed)
+        
+        if self.network.num_fibers == 0:
+            return np.array([]), np.array([])
+        
+        bb_min, bb_max = self.network.bounding_box()
+        
+        from scipy.spatial import cKDTree
+        
+        all_points = []
+        for fiber in self.network.fibers:
+            for pt in fiber.centerline:
+                all_points.append(pt)
+        
+        all_points = np.array(all_points)
+        tree = cKDTree(all_points)
+        
+        samples = rng.uniform(bb_min, bb_max, (num_samples, 3))
+        
+        distances, indices = tree.query(samples)
+        
+        pore_radii = np.zeros(num_samples)
+        for i, (dist, idx) in enumerate(zip(distances, indices)):
+            fiber_idx = 0
+            cum_pts = 0
+            for f in self.network.fibers:
+                if cum_pts + len(f.centerline) > idx:
+                    fiber_idx = f.fiber_id
+                    break
+                cum_pts += len(f.centerline)
+            
+            if fiber_idx < len(self.network.fibers):
+                r_fiber = self.network.fibers[fiber_idx].radius
+                pore_radii[i] = max(dist - r_fiber, 0)
+            else:
+                pore_radii[i] = dist
+        
+        return pore_radii, pore_radii
+    
+    def mean_pore_size(self) -> float:
+        """Mean pore radius."""
+        radii, _ = self.pore_size_distribution(num_samples=500, seed=42)
+        if len(radii) == 0:
+            return 0.0
+        return float(np.mean(radii))
+    
+    def pore_size_statistics(self) -> Dict[str, float]:
+        """Comprehensive pore size statistics."""
+        radii, _ = self.pore_size_distribution(num_samples=500, seed=42)
+        if len(radii) == 0:
+            return {"mean": 0, "median": 0, "std": 0, "max": 0}
+        return {
+            "mean": float(np.mean(radii)),
+            "median": float(np.median(radii)),
+            "std": float(np.std(radii)),
+            "max": float(np.max(radii)),
+            "min": float(np.min(radii[radii > 0])) if np.any(radii > 0) else 0,
+            "p95": float(np.percentile(radii, 95)),
+        }
+
+
+class AnisotropyAnalyzer:
+    """Analyze structural anisotropy of fiber networks."""
+    
+    def __init__(self, network: FiberNetwork):
+        self.network = network
+    
+    def orientation_tensor(self) -> np.ndarray:
+        """Compute the second-order orientation tensor.
+        
+        A_ij = <p_i * p_j> where p is the fiber direction vector.
+        
+        For isotropic: A = I/3 (3D) or I/2 (2D)
+        """
+        orientations = self.network.fiber_orientations()
+        if len(orientations) == 0:
+            return np.eye(3) / 3
+        
+        n = len(orientations)
+        A = np.zeros((3, 3))
+        for o in orientations:
+            A += np.outer(o, o)
+        A /= n
+        
+        return A
+    
+    def anisotropy_index(self) -> float:
+        """Anisotropy index based on orientation tensor eigenvalues.
+        
+        Returns value between 0 (isotropic) and 1 (fully aligned).
+        """
+        A = self.orientation_tensor()
+        eigenvalues = np.sort(np.linalg.eigvalsh(A))[::-1]
+        
+        if len(eigenvalues) < 3:
+            return 0.0
+        
+        a1 = eigenvalues[0]
+        iso = 1.0 / 3
+        
+        ai = (a1 - iso) / (1 - iso) if iso < 1 else 0
+        return float(max(0, min(1, ai)))
+    
+    def principal_directions(self) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Get principal directions of fiber orientation."""
+        A = self.orientation_tensor()
+        eigenvalues, eigenvectors = np.linalg.eigh(A)
+        
+        idx = np.argsort(eigenvalues)[::-1]
+        return eigenvectors[:, idx], eigenvalues[idx], eigenvectors[:, idx]
+
+
+class StructuralFingerprint:
+    """Create structural fingerprints for network comparison."""
+    
+    def __init__(self, network: FiberNetwork):
+        self.network = network
+    
+    def compute_fingerprint(self) -> Dict[str, float]:
+        """Compute a compact structural fingerprint vector."""
+        from fibernet.analysis.morphology import MorphologyAnalyzer
+        from fibernet.analysis.topology import TopologyAnalyzer
+        
+        morph = MorphologyAnalyzer(self.network)
+        topo = TopologyAnalyzer(self.network)
+        
+        fp = {
+            "num_fibers": float(self.network.num_fibers),
+            "density": self.network.density(),
+            "mean_length": self.network.mean_fiber_length,
+            "nematic_order": morph.nematic_order_parameter(),
+            "mean_tortuosity": float(np.mean(morph.tortuosity_distribution())),
+            "mean_degree": topo.degree_statistics()["mean"],
+            "clustering": topo.clustering_coefficient(),
+        }
+        
+        try:
+            spec = SpectralAnalyzer(self.network)
+            fp["spectral_gap"] = spec.spectral_gap()
+        except:
+            fp["spectral_gap"] = 0.0
+        
+        return fp
+    
+    def distance_to(self, other: "StructuralFingerprint") -> float:
+        """Compute Euclidean distance between fingerprints."""
+        fp1 = self.compute_fingerprint()
+        fp2 = other.compute_fingerprint()
+        
+        keys = sorted(set(fp1.keys()) & set(fp2.keys()))
+        v1 = np.array([fp1[k] for k in keys])
+        v2 = np.array([fp2[k] for k in keys])
+        
+        v1_norm = v1 / (np.linalg.norm(v1) + 1e-12)
+        v2_norm = v2 / (np.linalg.norm(v2) + 1e-12)
+        
+        return float(np.linalg.norm(v1_norm - v2_norm))