Metadata-Version: 2.4
Name: tunnel-shield-engine
Version: 1.0.0
Summary: TUNNEL-SHIELD: AI-Augmented Monitoring System for Tunnel Boring Machine Operations
Author-email: Samir Baladi <gitdeeper@gmail.com>
License: MIT
Project-URL: Homepage, https://tunnel-shield.netlify.app
Project-URL: Dashboard, https://tunnel-shield.netlify.app/dashboard
Project-URL: Documentation, https://tunnel-shield.netlify.app/documentation
Project-URL: Repository, https://github.com/gitdeeper12/TUNNEL-SHIELD
Project-URL: GitLab, https://gitlab.com/gitdeeper12/TUNNEL-SHIELD
Project-URL: PyPI, https://pypi.org/project/tunnel-shield-engine
Project-URL: DOI, https://doi.org/10.5281/zenodo.20374106
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Civil Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: torch>=2.0.0
Requires-Dist: xgboost>=1.7.0
Requires-Dist: streamlit>=1.28.0
Requires-Dist: plotly>=5.17.0
Requires-Dist: pydantic>=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: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Provides-Extra: ai
Requires-Dist: torch>=2.0.0; extra == "ai"
Requires-Dist: xgboost>=1.7.0; extra == "ai"
Requires-Dist: scikit-learn>=1.3.0; extra == "ai"
Dynamic: license-file

<div align="center">

# TUNNEL-SHIELD

### A Critical Framework for Loosening Pressure Control, Face Plastic Deformation Mitigation, and Lining Structural Safety in Deep Shield Tunnels

**An AI-Augmented Elastoplastic Continuum Mechanics Framework for TBM Excavation Safety Governance**

---

[![PyPI version](https://img.shields.io/pypi/v/tunnel-shield-engine?color=0D2B45&label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/tunnel-shield-engine)
[![PyPI downloads](https://img.shields.io/pypi/dm/tunnel-shield-engine?color=1B4F7A&label=Downloads&logo=pypi&logoColor=white)](https://pypi.org/project/tunnel-shield-engine/#files)
[![Python versions](https://img.shields.io/pypi/pyversions/tunnel-shield-engine?color=306998&logo=python&logoColor=white)](https://pypi.org/project/tunnel-shield-engine)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20374106-blue.svg)](https://doi.org/10.5281/zenodo.20374106)
[![ORCID](https://img.shields.io/badge/ORCID-0009--0003--8903--0029-A6CE39?logo=orcid&logoColor=white)](https://orcid.org/0009-0003-8903-0029)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Domain](https://img.shields.io/badge/Domain-Systems%20Safety%20%26%20Engineering-red)](https://doi.org/10.5281/zenodo.20374106)
[![Sub-domain](https://img.shields.io/badge/Sub--domain-GEOTECH--AI--02-darkred)](https://doi.org/10.5281/zenodo.20374106)
[![Version](https://img.shields.io/badge/Version-1.0.0-orange)](https://github.com/gitdeeper12/TUNNEL-SHIELD)

</div>

---

## 📌 Overview

**TUNNEL-SHIELD** is a fully coupled, AI-augmented elastoplastic continuum mechanics framework that treats **tunnel structural safety as a continuously governed dynamic invariant** — not a static design property frozen at the completion of a finite element run.

> *"A deep shield tunnel is not a static void in rock. It is a moving boundary-value problem embedded in a continuously evolving stress field. TUNNEL-SHIELD formalizes and governs this evolution, enforcing structural integrity against loosening pressure surge, face plastic collapse, and lining buckling in real time."*

Contemporary deep tunnel design relies on rock mass rating indices (RMR, Q-system) and uncoupled finite element analyses that cannot capture the nonlinear, spatiotemporally coupled dynamics of a TBM advancing through high-stress rock. TUNNEL-SHIELD provides a principled three-module governance pipeline that classifies any TBM operational state in real time as:

| Signal | Safety Status | Action |
|---|---|---|
| 🟢 **STABILITY CERTIFIED** | `F_tunnel ≥ 1.50 · TSII ≥ 0.95` | All constraints satisfied — advance mode |
| 🟠 **MONITORING PHASE** | `1.35 ≤ F_tunnel < 1.50 · TSII ≥ 0.90` | Advance rate reduction + PINN plastic zone alert |
| 🔴 **STOP COMMAND** | `F_tunnel < 1.35 · LSII < 0.15` | TBM stop + emergency grouting + structural review |

---

## 🗂️ Table of Contents

- [Overview](#-overview)
- [Key Features](#-key-features)
- [Domain Positioning](#-domain-positioning)
- [Project Structure](#-project-structure)
- [Quick Start](#-quick-start)
- [TUNNEL-SHIELD Pipeline](#-tunnel-shield-pipeline)
- [Scoring & Safety Bounds](#-scoring--safety-bounds)
- [Platforms & Mirrors](#-platforms--mirrors)
- [Clone & Download](#-clone--download)
- [Citation](#-citation)
- [License](#-license)
- [Author](#-author)

---

## ✨ Key Features

- **Three-module coupled pipeline** — LPEC (Loosening Pressure), FPSE (Face Squeezing), LSLC (Lining Stability Lock)
- **AI-augmented governance** — Physics-Informed Neural Network (PINN) for plastic zone forecasting, XGBoost face convergence ensemble, CNN lining distortion classifier
- **3.8–5.1 diameter advance warning** — 2.8–4.7 days before critical lining section is reached
- **Closed-form + PINN plastic radius R_p** — Hoek-Brown elastoplastic formulation with 3D face proximity correction
- **Full Biot hydro-mechanical coupling** — anisotropic pore pressure field with asymmetry index (HAI)
- **Moment-thrust interaction enforcement** — per-ring M-N utilization ratio with LSII monitoring
- **Global safety factor F_tunnel** — weighted harmonic mean of three module safety factors, updated every advance increment
- **0.927–0.968 Tunnel Structural Integrity Index** — validated across 3 canonical deep tunnel scenarios
- **Full open-source distribution** — available across 5 platforms

---

## 🏛️ Domain Positioning

TUNNEL-SHIELD is the **fourth project** in the **Systems Safety & Engineering (AI-augmented)** domain portfolio, classified as **GEOTECH-AI-02**.

| Project | Sub-classification | Core Safety Mechanism |
|---|---|---|
| **OSEF** | Aviation Safety Systems | AI-augmented flight envelope protection |
| **Limit Cycle Flight Dynamics** | Aerospace Engineering | Nonlinear dynamical stability certification |
| **DAMS-SLIP v1.1.1** | GEOTECH-AI-01 | AI-augmented seepage and piping governance |
| **TUNNEL-SHIELD v1.0.0** | **GEOTECH-AI-02** | **AI-augmented TBM excavation safety governance** |

> The unifying principle across all four projects: **safety is a dynamical invariant enforced through physics-grounded AI governance, not a static design constant frozen at the point of commissioning.**

---

## 📁 Project Structure

```
TUNNEL-SHIELD/
│
├── tunnel_shield/                          # Core Python package
│   ├── __init__.py                         # Package entry point & public API
│   ├── pipeline.py                         # Main TUNNEL-SHIELD governance pipeline
│   ├── safety.py                           # Safety certification & F_tunnel logic
│   │
│   ├── modules/                            # Three governing modules
│   │   ├── __init__.py
│   │   ├── lpec.py                         # Module 1: Loosening Pressure Evaluation Core
│   │   ├── fpse.py                         # Module 2: Face Plastic Squeezing Evaluator
│   │   └── lslc.py                         # Module 3: Lining Structural Stability Lock
│   │
│   ├── ai/                                 # AI augmentation components
│   │   ├── __init__.py
│   │   ├── pinn_plastic_zone.py            # PINN: plastic zone boundary R_p forecasting
│   │   ├── xgb_face_convergence.py         # XGBoost: face convergence rate prediction
│   │   ├── cnn_distortion.py               # CNN: lining distortion pattern classifier
│   │   ├── pinn_pore_pressure.py           # PINN: asymmetric pore pressure field (Biot)
│   │   └── weights/                        # Pre-trained model checkpoints
│   │       ├── pinn_plastic_zone_v1.pt
│   │       ├── xgb_face_convergence_v1.json
│   │       ├── cnn_distortion_v1.pt
│   │       └── pinn_pore_pressure_v1.pt
│   │
│   ├── elastoplastic/                      # Elastoplastic continuum mechanics core
│   │   ├── __init__.py
│   │   ├── hoek_brown.py                   # Hoek-Brown failure criterion (GSI, m_b, s, a)
│   │   ├── mohr_coulomb.py                 # Mohr-Coulomb yield surface & linearization
│   │   ├── plastic_radius.py               # R_p formulation (2D closed-form + 3D LDP)
│   │   ├── stress_redistribution.py        # Stress field σ_r, σ_θ in elastic & plastic zones
│   │   └── constitutive.py                 # Elastoplastic constitutive integration (flow rule)
│   │
│   ├── loosening/                          # LPEC subsystem
│   │   ├── __init__.py
│   │   ├── terzaghi_pressure.py            # Terzaghi loosening pressure q_L formulation
│   │   ├── load_transfer_ratio.py          # LTR: fraction of overburden on lining
│   │   ├── arching.py                      # Ground arching mechanism (AEI, tau_arch)
│   │   └── overburden.py                   # Overburden stress redistribution σ_v(z)
│   │
│   ├── face/                               # FPSE subsystem
│   │   ├── __init__.py
│   │   ├── competence_factor.py            # CF = σ_cm / σ_v squeezing classification
│   │   ├── face_convergence.py             # Axial face displacement u_f(r, x)
│   │   ├── face_stability.py               # F_face safety factor computation
│   │   ├── volumetric_strain.py            # ε_v field in plastic zone at face
│   │   └── tbm_thrust.py                   # p_eff = F_TBM / (π R_t²) + p_slurry
│   │
│   ├── lining/                             # LSLC subsystem
│   │   ├── __init__.py
│   │   ├── segmental_ring.py               # Curved beam ring model (N, V, M equilibrium)
│   │   ├── joint_rotation.py               # Rotational stiffness k_φ and M_j,Rd capacity
│   │   ├── moment_thrust.py                # M-N interaction surface & utilization ratio UR
│   │   ├── lsii.py                         # Lining Structural Integrity Index (LSII)
│   │   ├── crown_settlement.py             # δ_crown(x) ≤ δ_max constraint enforcement
│   │   └── segment_assembly.py             # Ring stiffness matrix K_ring assembly
│   │
│   ├── hydro/                              # Hydro-mechanical coupling
│   │   ├── __init__.py
│   │   ├── biot.py                         # Biot consolidation (α_B, K_dr, k, μ_w)
│   │   ├── pore_pressure_field.py          # u_w(r, θ) asymmetric seepage field
│   │   ├── hai.py                          # Hydrostatic Asymmetry Index (HAI)
│   │   └── seepage_laplace.py              # Modified Laplace for anisotropic K_r, K_θ
│   │
│   ├── fem/                                # Finite element discretization
│   │   ├── __init__.py
│   │   ├── mesh.py                         # Adaptive tetrahedral + hexahedral mesh
│   │   ├── amr.py                          # Adaptive mesh refinement (η_el criterion)
│   │   ├── boundary_conditions.py          # In-situ stress, far-field BC, tunnel drainage
│   │   ├── solver.py                       # Nonlinear FEM solver (Newton-Raphson)
│   │   └── convergence.py                  # Convergence criteria & numerical stability
│   │
│   ├── monitoring/                         # Real-time monitoring layer
│   │   ├── __init__.py
│   │   ├── fiber_optic.py                  # Distributed fiber optic strain parser
│   │   ├── tbm_telemetry.py                # TBM operational telemetry ingestion
│   │   ├── piezometer.py                   # Piezometer array data handler
│   │   ├── total_station.py                # Automated total station displacement parser
│   │   └── aggregator.py                   # Multi-sensor temporal aggregation
│   │
│   └── utils/                              # Shared utilities
│       ├── __init__.py
│       ├── metrics.py                      # F_tunnel, TSII, LSII, F_LPEC, F_FPSE, F_LSLC
│       ├── rock_mass.py                    # GSI, m_b, s, a parameter registry
│       ├── validators.py                   # Input validation & safety bound checks
│       └── constants.py                    # Canonical parameter registry (α, β, λ, γ)
│
├── visualization/                          # Real-time visualization subsystem
│   ├── __init__.py
│   ├── app.py                              # Streamlit application entry point
│   ├── dashboard.py                        # Main TBM safety dashboard layout
│   ├── plastic_zone_map.py                 # R_p(x) evolution heatmap along tunnel axis
│   ├── lining_ring_plot.py                 # Per-ring M-N utilization + LSII display
│   ├── face_convergence_plot.py            # Face convergence profile u_f(r) renderer
│   └── components/
│       ├── signal_panel.py                 # 🔴🟠🟢 safety signal panel
│       ├── ai_forecast_panel.py            # PINN R_p + XGBoost convergence forecast
│       └── tbm_live_panel.py               # Live TBM telemetry reading display
│
├── archival/                               # Operational data archival
│   ├── __init__.py
│   ├── writer.py                           # Append-only JSON/CSV advance record writer
│   ├── checksum.py                         # SHA-256 tamper-evidence layer
│   └── partitioner.py                      # Per-ring time-window CSV partitioner
│
├── simulation/                             # Benchmark simulation environment
│   ├── __init__.py
│   ├── scenarios.py                        # Three canonical benchmark configurations
│   ├── geological_profiles.py              # GSI, σ_ci, K_0 spatial variation models
│   ├── benchmarks.py                       # Full validation suite runner
│   ├── parameters.py                       # Canonical v1.0.0 parameter registry
│   └── results/                            # Pre-computed validation outputs
│       ├── CaseA_schist_450m.json
│       ├── CaseB_limestone_310m.json
│       └── CaseC_claystone_580m.json
│
├── examples/                               # Usage examples & tutorials
│   ├── quickstart.py                       # Minimal working example
│   ├── basic_safety_check.ipynb            # Jupyter: single-advance safety evaluation
│   ├── high_squeezing_schist.ipynb         # Jupyter: Case A severe squeezing scenario
│   ├── anisotropic_limestone.ipynb         # Jupyter: Case B anisotropic stress field
│   ├── extreme_squeezing_claystone.ipynb   # Jupyter: Case C extreme squeezing scenario
│   ├── streamlit_live.py                   # Launch real-time TBM safety dashboard
│   └── ai_forecast_demo.py                 # PINN + XGBoost forecast demonstration
│
├── tests/                                  # Unit and integration tests
│   ├── test_lpec.py
│   ├── test_fpse.py
│   ├── test_lslc.py
│   ├── test_pinn_plastic_zone.py
│   ├── test_xgb_face_convergence.py
│   ├── test_cnn_distortion.py
│   ├── test_biot.py
│   ├── test_pipeline.py
│   └── test_archival.py
│
├── docs/                                   # Documentation source
│   ├── architecture.md                     # Pipeline & module architecture reference
│   ├── mathematics.md                      # Full elastoplastic mathematical formalism
│   ├── ai_modules.md                       # PINN / XGBoost / CNN documentation
│   ├── rock_mass_parameters.md             # Hoek-Brown & GSI calibration guide
│   ├── governance.md                       # Governance level protocol reference (L1/L2/L3)
│   └── api_reference.md                    # Full Python API reference
│
├── paper/                                  # Research paper artifacts
│   ├── TUNNEL_SHIELD_Research_Paper.pdf    # Published paper (PDF)
│   ├── TUNNEL_SHIELD_Research_Paper.docx   # Editable Word version
│   └── figures/
│       ├── pipeline_diagram.svg
│       ├── plastic_zone_caseA.svg
│       ├── lining_mn_interaction.svg
│       └── ai_forecast_validation.svg
│
├── .gitlab-ci.yml                          # GitLab CI/CD pipeline
├── .github/                                # GitHub Actions workflows
│   └── workflows/
│       ├── tests.yml
│       └── publish.yml
├── pyproject.toml                          # Build system configuration
├── setup.cfg                               # Package metadata
├── requirements.txt                        # Runtime dependencies
├── requirements-dev.txt                    # Development dependencies
├── CHANGELOG.md                            # Version history
├── CONTRIBUTING.md                         # Contribution guidelines
├── CODE_OF_CONDUCT.md
├── AUTHORS.md                              # Author and contributor registry
├── LICENSE                                 # MIT License
└── README.md                               # This file
```

---

## 🚀 Quick Start

### Installation

```bash
# Install from PyPI
pip install tunnel-shield-engine

# Install from source
git clone https://github.com/gitdeeper12/TUNNEL-SHIELD.git
cd TUNNEL-SHIELD
pip install -e .
```

### Minimal Example

```python
from tunnel_shield import TunnelGovernor

# Initialize the safety governor
governor = TunnelGovernor(
    rock_config="configs/high_squeezing_schist.yaml",
    depth_m=450.0,
    tunnel_radius_m=4.9,
    tbm_telemetry="live"    # or path to historical CSV
)

# Run full TUNNEL-SHIELD pipeline
result = governor.evaluate()

print(result.signal)              # "STABILITY_CERTIFIED" | "MONITORING" | "STOP_COMMAND"
print(result.f_tunnel)            # float — global safety factor (harmonic mean)
print(result.tsii)                # Tunnel Structural Integrity Index [0, 1]
print(result.lsii)                # Lining Structural Integrity Index [0, 1]
print(result.plastic_radius_m)    # R_p,3D at current face position (metres)
print(result.governance_level)    # "none" | "level_1" | "level_2" | "stop"
```

### With Full AI Augmentation

```python
from tunnel_shield import TunnelGovernor
from tunnel_shield.ai import (
    PINNPlasticZone,
    XGBFaceConvergence,
    CNNDistortionClassifier,
    PINNPorePressure
)

governor = TunnelGovernor(
    rock_config="configs/high_squeezing_schist.yaml",
    ai_modules={
        "pinn_plastic":    PINNPlasticZone.from_pretrained("default"),
        "xgb_face":        XGBFaceConvergence.from_pretrained("default"),
        "cnn_distortion":  CNNDistortionClassifier.from_pretrained("default"),
        "pinn_pore":       PINNPorePressure.from_pretrained("default"),
    }
)

result = governor.evaluate(forecast_increments=20)
print(result.rp_forecast)          # R_p,3D predicted for next 20 advance increments
print(result.face_convergence_rate) # mm/m of advance (XGBoost prediction)
print(result.ring_distortion_class) # "normal" | "crown_settlement" | "joint_opening" | "critical"
print(result.pore_pressure_field)   # u_w(r, θ) spatial array — asymmetric Biot field
```

### High-Squeezing Schist Scenario

```python
from tunnel_shield import TunnelGovernor
from tunnel_shield.simulation import SqueezeScenario

scenario = SqueezeScenario(
    depth_m=450.0,
    sigma_ci_MPa=28.0,
    gsi=35,
    k0=1.8,
    tunnel_radius_m=4.9,
    advance_rate_m_per_day=8.0
)

governor = TunnelGovernor(rock_config="configs/high_squeezing_schist.yaml")
results = governor.run_advance_sequence(scenario, n_increments=200)

print(results.min_f_tunnel)         # 1.41 (Case A validation result)
print(results.max_plastic_radius)   # 3.4 × R_t
print(results.max_crown_settlement) # 41.3 mm (< δ_max = 45 mm)
print(results.ai_warning_diameters) # 4.3 diameters advance warning
```

### Launch Real-Time TBM Safety Dashboard

```bash
# Start Streamlit safety monitoring dashboard
streamlit run examples/streamlit_live.py

# Dashboard available at: http://localhost:8501
# Live R_p(x) heatmap · F_tunnel evolution · M-N utilization ring map · 🔴🟠🟢 signal
```

---

## 🧩 TUNNEL-SHIELD Pipeline

```
┌─────────────────────────────────────────────────────────────────────────┐
│  TBM Telemetry: Thrust · Torque · Penetration Rate · Grout P · Tail Gap │
│  Monitoring: Fiber Optic Strain · Piezometers · Total Station           │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │
         ┌─────────────────────┼────────────────────┐
         │                     │                    │
         ▼                     ▼                    ▼
    LPEC                  FPSE                 LSLC
    Loosening Pressure    Face Squeezing       Lining Stability
    Evaluation Core       Evaluator            Lock
    Terzaghi + R_p        CF · F_face          Curved beam M-N
    Arching (AEI)         u_f(r, x)            UR(s) · LSII
         │                     │                    │
         └─────────────────────┼────────────────────┘
                               │
         ┌─────────────────────┼────────────────────┐
         │                     │                    │
         ▼                     ▼                    ▼
    PINN Plastic Zone     XGBoost Face         CNN Distortion
    R_p,3D Forecast       Convergence          Classifier
    Physics-constrained   52-feature vector    360-pt strain
    Every advance (2.3s)  MAE = 1.8 mm/m       5-class output
         │                     │                    │
         └─────────────────────┼────────────────────┘
                               │
                               ▼
                    Biot Hydro-Mechanical
                    Pore Pressure PINN
                    u_w(r, θ) asymmetric field
                    HAI = (p_max − p_min) / p_mean
                               │
                               ▼
                    F_tunnel Functional
                    F = 1 / [w_L/F_LPEC + w_F/F_FPSE + w_S/F_LSLC]
                    w_LPEC=0.35  w_FPSE=0.30  w_LSLC=0.35
                               │
                    ┌──────────┴──────────┐
                    ▼                     ▼
             Safety Signal         Archival & Dashboard
             🔴🟠🟢                JSON/CSV + SHA-256
             TBM Stop / Alert     Streamlit + Plotly
```

### Module Descriptions

| # | Module | Governing Equation | Description |
|---|---|---|---|
| 1 | **LPEC** | `q_L = γ_r·B·(1−c/γ_r·B) / (K_0·tanφ) · [1−exp(−K_0·tanφ·H/B)]` | Terzaghi loosening pressure with plastic zone correction |
| 2 | **FPSE** | `F_face = [c·cot(φ)·(N_φ−1) + σ_v·N_φ^0.5] / [σ_v − p_eff]` | Face stability with TBM thrust and slurry support |
| 3 | **LSLC** | `UR(s) = √[(N_Ed/N_Rd)² + (M_Ed/M_Rd)²] ≤ 1/γ_s` | Per-section M-N utilization with joint rotation model |
| AI-1 | **PINN Plastic Zone** | `L = λ_data·L_data + λ_phys·L_phys` | Physics-constrained R_p,3D forecasting from TBM telemetry |
| AI-2 | **XGBoost Face** | `ε_face(T+next) = f(thrust, torque, PR, friction, …)` | Face convergence rate prediction ensemble |
| AI-3 | **CNN Distortion** | Classification: {normal, crown, spring-line, joint, critical} | Lining distortion pattern from fiber optic strain profile |
| AI-4 | **PINN Pore** | Biot + asymmetric seepage field `u_w(r, θ, t)` | Asymmetric pore pressure forecast for LSLC loading |

---

## 📊 Scoring & Safety Bounds

```
Safety certification criteria:
  F_tunnel   (weighted harmonic mean of module safety factors)   ≥  1.35
  TSII       (Tunnel Structural Integrity Index)                  ≥  0.90
  LSII       (Lining Structural Integrity Index, per ring)        ≥  0.15
  δ_crown    (crown settlement)                                   ≤  δ_max

F_tunnel functional form:
  F_tunnel = 1 / [0.35/F_LPEC + 0.30/F_FPSE + 0.35/F_LSLC]

TSII definition:
  TSII = Φ[ min(F_LPEC, F_FPSE, F_LSLC) / F_threshold × β_target ]
  β_target = 3.0  →  P_failure ≤ 1.35 × 10⁻³ per ring

Plastic radius (Hoek-Brown elastoplastic):
  R_p = R_t · [(2σ_0·(N_φ−1) + σ_ci·m_b·s^(a−1)) / ((1+N_φ)·(2p_i·(N_φ−1) + σ_ci·m_b·s^(a−1)))]^(1/(N_φ−1))

Crown settlement constraint:
  δ_crown(x) = −u_r(r=R_t, θ=0, x) ≤ δ_max
```

**Benchmark validation results (v1.0.0):**

| Case | Description | F_tunnel | TSII | LSII | δ_crown | AI Warning |
|---|---|---|---|---|---|---|
| A | Severe squeezing schist (450 m) | 1.41 | 0.931 | 0.22 | 41.3 mm | 4.3 diameters |
| B | Anisotropic limestone (310 m) | 1.63 | 0.968 | 0.37 | 18.7 mm | 5.1 diameters |
| C | Extreme squeezing claystone (580 m) | 1.38 | 0.927 | 0.18 | 44.8 mm | 3.8 diameters |
| **Mean** | — | **1.47** | **0.942** | **0.26** | **34.9 mm** | **4.4 diameters** |

**AI module performance:**

| AI Module | Precision | Recall | AUC / MAE | False Alarm Rate |
|---|---|---|---|---|
| PINN Plastic Zone (R_p error) | — | — | 3.4% (rel. MAE) | N/A |
| XGBoost Face Convergence | — | — | 1.8 mm/m (MAE) | N/A |
| CNN Distortion Classifier | 0.96 | 0.93 | 0.98 (AUC) | 2.8% |
| Governance Response | 0.97 | 0.95 | 0.99 (AUC) | 1.9% |

**Governance decision thresholds:**

| Level | Condition | Action | Escalation |
|---|---|---|---|
| 🟢 Certified | `F_tunnel ≥ 1.50 · TSII ≥ 0.95` | Advance mode | None |
| 🟠 Level 1 | `1.35 ≤ F_tunnel < 1.50 · TSII ≥ 0.90` | Thrust / advance rate reduction | PINN forecast issued |
| 🟠 Level 2 | `F_tunnel < 1.35 · LSII ≥ 0.15` | Mandatory parameter adjustment + ring design review | Structural alert |
| 🔴 Stop | `F_tunnel < 1.20 · LSII < 0.10` | TBM stop + emergency grouting + full diagnostic report | Immediate action |

---

## 🌐 Platforms & Mirrors

| Platform | URL | Role |
|---|---|---|
| 🐙 **GitHub** (Primary) | [github.com/gitdeeper12/TUNNEL-SHIELD](https://github.com/gitdeeper12/TUNNEL-SHIELD) | Source code, issues, PRs |
| 🦊 **GitLab** (Mirror) | [gitlab.com/gitdeeper12/TUNNEL-SHIELD](https://gitlab.com/gitdeeper12/TUNNEL-SHIELD) | CI/CD mirror |
| 🪣 **Bitbucket** (Mirror) | [bitbucket.org/gitdeeper-12/TUNNEL-SHIELD](https://bitbucket.org/gitdeeper-12/TUNNEL-SHIELD) | Enterprise mirror |
| 🏔️ **Codeberg** (Mirror) | [codeberg.org/gitdeeper12/TUNNEL-SHIELD](https://codeberg.org/gitdeeper12/TUNNEL-SHIELD) | Open-source community |
| 📦 **PyPI** | [pypi.org/project/tunnel-shield-engine](https://pypi.org/project/tunnel-shield-engine) | Python package distribution |
| 🔬 **Zenodo** | [doi.org/10.5281/zenodo.20374106](https://doi.org/10.5281/zenodo.20374106) | Citable DOI, paper & data |
| 🧑‍🔬 **ORCID** | [orcid.org/0009-0003-8903-0029](https://orcid.org/0009-0003-8903-0029) | Researcher identity |

---

## 🔄 Clone & Download

### Git Clone

```bash
# GitHub (Primary)
git clone https://github.com/gitdeeper12/TUNNEL-SHIELD.git

# GitLab (Mirror)
git clone https://gitlab.com/gitdeeper12/TUNNEL-SHIELD.git

# Bitbucket (Mirror)
git clone https://bitbucket.org/gitdeeper-12/TUNNEL-SHIELD.git

# Codeberg (Mirror)
git clone https://codeberg.org/gitdeeper12/TUNNEL-SHIELD.git
```

### Direct ZIP Download

| Source | Link |
|---|---|
| GitHub | [TUNNEL-SHIELD-main.zip](https://github.com/gitdeeper12/TUNNEL-SHIELD/archive/refs/heads/main.zip) |
| GitLab | [TUNNEL-SHIELD-main.zip](https://gitlab.com/gitdeeper12/TUNNEL-SHIELD/-/archive/main/TUNNEL-SHIELD-main.zip) |
| Bitbucket | [TUNNEL-SHIELD-main.zip](https://bitbucket.org/gitdeeper-12/TUNNEL-SHIELD/get/main.zip) |
| Codeberg | [TUNNEL-SHIELD-main.zip](https://codeberg.org/gitdeeper12/TUNNEL-SHIELD/archive/main.zip) |
| PyPI files | [pypi.org/project/tunnel-shield-engine/#files](https://pypi.org/project/tunnel-shield-engine/#files) |
| Zenodo record | [doi.org/10.5281/zenodo.20374106](https://doi.org/10.5281/zenodo.20374106) |

---

## 📖 Citation

If TUNNEL-SHIELD contributes to your research, please cite using one of the following formats.

### 📦 PyPI Package

```bibtex
@software{baladi2026tunnelshield_pypi,
  author       = {Baladi, Samir},
  title        = {{TUNNEL-SHIELD}: A Critical Framework for Loosening Pressure
                  Control, Face Plastic Deformation Mitigation, and Lining
                  Structural Safety in Deep Shield Tunnels},
  year         = {2026},
  version      = {1.0.0},
  publisher    = {Python Package Index},
  url          = {https://pypi.org/project/tunnel-shield-engine},
  note         = {Python package, MIT License,
                  Systems Safety \& Engineering (AI-augmented) — GEOTECH-AI-02}
}
```

### 🔬 Zenodo Archive (Paper & Data)

```bibtex
@dataset{baladi2026tunnelshield_zenodo,
  author       = {Baladi, Samir},
  title        = {{TUNNEL-SHIELD}: A Critical Framework for Loosening Pressure
                  Control, Face Plastic Deformation Mitigation, and Lining
                  Structural Safety in Deep Shield Tunnels —
                  Research Paper and Simulation Data},
  year         = {2026},
  publisher    = {Zenodo},
  version      = {1.0.0},
  doi          = {10.5281/zenodo.20374106},
  url          = {https://doi.org/10.5281/zenodo.20374106},
  note         = {Geotechnical Engineering · Systems Safety · GEOTECH-AI-02}
}
```

### 📄 Research Paper

```bibtex
@article{baladi2026tunnelshield,
  author       = {Baladi, Samir},
  title        = {{TUNNEL-SHIELD}: A Critical Framework for Loosening Pressure
                  Control, Face Plastic Deformation Mitigation, and Lining
                  Structural Safety in Deep Shield Tunnels},
  year         = {2026},
  month        = {May},
  version      = {1.0.0},
  doi          = {10.5281/zenodo.20374106},
  url          = {https://doi.org/10.5281/zenodo.20374106},
  note         = {Ronin Institute / Rite of Renaissance,
                  Systems Safety \& Engineering (AI-augmented) — GEOTECH-AI-02}
}
```

### APA (inline)

> Baladi, S. (2026). *TUNNEL-SHIELD: A Critical Framework for Loosening Pressure Control, Face Plastic Deformation Mitigation, and Lining Structural Safety in Deep Shield Tunnels* (Version 1.0.0). Zenodo. https://doi.org/10.5281/zenodo.20374106

---

## 📜 License

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

```
MIT License

Copyright (c) 2026 Samir Baladi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
```

---

## 👤 Author

**Samir Baladi**
Interdisciplinary AI Researcher — Neural Engineering, Computational Systems Safety & Geotechnical AI
Ronin Institute / Rite of Renaissance

| Contact | Link |
|---|---|
| 📧 Email | [gitdeeper@gmail.com](mailto:gitdeeper@gmail.com) |
| 🧑‍🔬 ORCID | [0009-0003-8903-0029](https://orcid.org/0009-0003-8903-0029) |
| 🐙 GitHub | [github.com/gitdeeper12](https://github.com/gitdeeper12) |
| 🔬 Zenodo | [doi.org/10.5281/zenodo.20374106](https://doi.org/10.5281/zenodo.20374106) |

---

<div align="center">

**Systems Safety & Engineering (AI-augmented) · GEOTECH-AI-02 · Version 1.0.0 · May 2026**

[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20374106-blue.svg)](https://doi.org/10.5281/zenodo.20374106)
[![PyPI](https://img.shields.io/pypi/v/tunnel-shield-engine?color=0D2B45)](https://pypi.org/project/tunnel-shield-engine)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Domain](https://img.shields.io/badge/Domain-Systems%20Safety%20%26%20Engineering-red)](https://doi.org/10.5281/zenodo.20374106)

*"Structural integrity is not negotiated with the rock mass — it is enforced through geometry, physics, and AI-governed constraint design."*

</div>
