# RTX Digital Twin - Medical Digital Twin Platform

A patient-specific organ simulation framework combining physics-based models for thermal therapy planning and treatment optimization.

## Overview

This crate provides a complete Medical Digital Twin Platform for:
- Creating patient-specific organ geometry from medical imaging segmentation
- Physics-based simulation (Pennes bioheat equation for thermal ablation)
- Intervention modeling (RFA, microwave, HIFU, laser ablation)
- What-if analysis for treatment planning
- Real-time thermal damage prediction

## Architecture

```
Medical Images (CT/MRI)
        ↓
   Segmentation → Tissue Labels
        ↓
   Organ Geometry (3D voxel grid with tissue properties)
        ↓
   Physics Model (bioheat equation with perfusion)
        ↓
   Digital Twin (simulation engine)
        ↓
   What-If Analysis → Treatment Planning
```

## Key Features

### 1. Patient-Specific Geometry
- Voxel-based 3D representation from segmentation
- Multi-tissue support (16+ tissue types)
- Physical properties database (thermal, mechanical, electrical)
- Automatic property field generation

### 2. Physics Simulation
- **Pennes Bioheat Equation**: Accounts for blood perfusion and metabolic heat
- **Steady-state solver**: Gauss-Seidel iterative method
- **Transient solver**: Explicit finite difference time stepping
- **Thermal damage**: CEM43 equivalent dose calculation

### 3. Intervention Modeling
- **Ablation Probes**: RFA, microwave, laser
- **HIFU**: Focused ultrasound with Gaussian beam model
- Customizable heat source distributions
- Active/inactive control

### 4. Treatment Planning
- Multiple scenario comparison
- Safety margin analysis
- Damage volume prediction
- Clinical report generation

## Quick Start

### Basic Usage

```rust
use rtx_digital_twin::{
    AblationProbe, DigitalTwin, OrganGeometry, TissueType, TissueLabel,
};

// Create geometry from segmentation
let mut geometry = OrganGeometry::new([30, 30, 30], [1.0, 1.0, 1.0]);

// Fill with liver tissue
for z in 5..25 {
    for y in 5..25 {
        for x in 5..25 {
            geometry.set_label(x, y, z, TissueLabel::from(TissueType::Liver));
        }
    }
}

// Add tumor
geometry.create_sphere([15.0, 15.0, 15.0], 4.0, TissueLabel::from(TissueType::Tumor));

// Create digital twin
let mut twin = DigitalTwin::new(geometry);

// Plan ablation
let probe = AblationProbe::new([15.0, 15.0, 15.0], 40.0);

// What-if analysis
let result = twin.what_if(&probe, 60.0)?;

println!("Max temp: {:.1}°C", result.max_temperature);
println!("Damaged volume: {:.1} cm³", result.total_damaged_volume / 1000.0);
```

### Running Examples

```bash
# Simple ablation planning
cargo run --example simple_ablation

# Comprehensive liver tumor ablation planning
cargo run --example liver_ablation_planning
```

## Core Types

### OrganGeometry
3D voxel grid with tissue labels and physical state at each voxel.

```rust
pub struct OrganGeometry {
    data: Vec<VoxelData>,         // Per-voxel data
    shape: [usize; 3],             // Grid dimensions
    spacing: [f32; 3],             // Voxel size in mm
    origin: [f32; 3],              // World coordinates origin
    tissue_db: TissueDatabase,     // Tissue properties
}
```

### DigitalTwin
Main simulation interface combining geometry, physics, and interventions.

```rust
pub struct DigitalTwin {
    geometry: OrganGeometry,
    config: TwinConfig,
    bioheat: BioheatModel,
    last_result: Option<SimulationResult>,
}
```

### TissueDatabase
Physical properties for 16+ human tissue types based on published literature:
- Thermal: conductivity, specific heat, density
- Perfusion: blood flow rate, metabolic heat
- Mechanical: Young's modulus, Poisson ratio
- Electrical: conductivity, permittivity

### Interventions
Trait-based system for modeling therapeutic interventions:

```rust
pub trait Intervention {
    fn intervention_type(&self) -> InterventionType;
    fn generate_heat_source(&self, geometry: &OrganGeometry) -> Result<Vec<f32>>;
    fn position(&self) -> [f32; 3];
    fn power(&self) -> f32;
}
```

Implementations:
- `AblationProbe`: RFA, microwave, laser (cylindrical heat source)
- `HifuTransducer`: Focused ultrasound (Gaussian beam)

## Physics Models

### Pennes Bioheat Equation

```
ρc ∂T/∂t = ∇·(k∇T) + ρ_b c_b ω_b (T_b - T) + Q_m + Q_ext
```

Where:
- `ρ, c`: tissue density and specific heat
- `k`: thermal conductivity
- `ρ_b, c_b`: blood density and specific heat
- `ω_b`: blood perfusion rate [1/s]
- `T_b`: arterial blood temperature
- `Q_m`: metabolic heat generation
- `Q_ext`: external heat source (ablation probe)

### Thermal Damage (Arrhenius)

Cumulative Equivalent Minutes at 43°C (CEM43):
```
damage = ∫ R^(43-T) dt
```

Where R = 0.5 for T > 43°C

## Test Coverage

### Unit Tests (27 tests)
- Geometry creation and manipulation
- Tissue property lookups
- Coordinate transformations
- Temperature field operations
- Physics model configuration
- Boundary conditions
- Intervention heat source generation

### Integration Tests (13 tests)
- Complete workflow from segmentation to treatment planning
- Multi-scenario what-if analysis
- Transient and steady-state simulations
- Damage calculation validation
- Clinical report generation

All 40 tests pass with full code coverage of core functionality.

## File Structure

```
rtx-digital-twin/
├── src/
│   ├── lib.rs              # Public API exports
│   ├── error.rs            # Error types (43 lines)
│   ├── geometry.rs         # OrganGeometry (465 lines)
│   ├── tissue.rs           # TissueDatabase (466 lines)
│   ├── physics.rs          # BioheatModel (613 lines)
│   ├── intervention.rs     # Ablation probes, HIFU (385 lines)
│   └── twin.rs             # DigitalTwin API (494 lines)
├── tests/
│   └── integration_test.rs # Integration tests (560 lines)
└── examples/
    ├── simple_ablation.rs           # Quick demo
    └── liver_ablation_planning.rs  # Full workflow
```

All files are well under the 1000-line limit (max: 613 lines).

## Dependencies

- `rtx-tensor`: Tensor operations
- `rtx-backend`: Device abstraction
- `rtx-medical-core`: Volume handling (with `volume` feature)
- `thiserror`: Error handling
- `serde`: Serialization

## Development Approach

This implementation follows strict Test-Driven Development (TDD):

1. **RED Phase**: Write failing tests first
2. **GREEN Phase**: Implement minimal code to pass tests
3. **REFACTOR Phase**: Clean up while maintaining test passage

### TDD Principles Applied
- No placeholder code or `todo!()` macros
- Full error handling with `Result<T, E>`
- Production-ready code from the start
- State-based testing (no mocks)
- Comprehensive test coverage

## Performance Considerations

### Numerical Stability
- Gauss-Seidel iteration with configurable tolerance
- Harmonic mean for interface conductivities
- Explicit time stepping with CFL stability considerations

### Grid Resolution
- Typical: 1mm voxels for clinical accuracy
- Trade-off: resolution vs. computational cost
- Recommended: 30³-60³ for real-time planning
- Research: up to 256³ for detailed analysis

### Simulation Time
- Steady-state: <1 second for 30³ grid
- Transient (60s physical time): ~2-3 seconds for 30³ grid
- Scales approximately as O(N) for N voxels

## Clinical Applications

### Tumor Ablation Planning
- Liver tumors (HCC, metastases)
- Kidney tumors
- Lung nodules
- Bone lesions

### Treatment Optimization
- Power setting selection
- Probe positioning
- Duration planning
- Safety margin verification

### Risk Assessment
- Thermal damage to adjacent structures
- Incomplete ablation prediction
- Heat sink effect analysis

## References

### Tissue Properties
- IT'IS Foundation Tissue Properties Database
- Hasgall et al., "IT'IS Database for thermal and electromagnetic parameters"
- Duck, F.A., "Physical Properties of Tissues"

### Bioheat Transfer
- Pennes, H.H., "Analysis of tissue and arterial blood temperatures in the resting human forearm" (1948)
- Weinbaum, S., et al., "A new fundamental bioheat equation for muscle tissue" (1984)

### Thermal Damage
- Sapareto, S.A., Dewey, W.C., "Thermal dose determination in cancer therapy" (1984)
- Dewhirst, M.W., et al., "Basic principles of thermal dosimetry and thermal thresholds" (2003)

## License

This project is dual-licensed under MIT OR Apache-2.0.

## Contributing

Contributions welcome! Please ensure:
- All tests pass: `cargo test`
- Code is lint-free: `cargo clippy`
- Documentation is updated
- TDD principles are followed