rustytorch/demos/shared/README.md

# rtx-hemodynamics-shared

Shared types for RustyTorch++ hemodynamics demo IPC.

## Overview

This crate provides all shared data structures for communication between the Tauri frontend and RustyTorch++ backend in the Virtual Catheter demo. All types implement `Serialize` and `Deserialize` for JSON IPC.

## Modules

| Module | Description |
|--------|-------------|
| `geometry` | Vessel geometry primitives and SDFs |
| `fields` | Velocity, pressure, and WSS field representations |
| `physics` | Fluid properties and boundary conditions |
| `ipc` | Inter-process communication message types |
| `error` | Shared error types |

## Geometry Types

```rust
// 2D point coordinate
pub type Point2D = [f64; 2];

// Vessel geometry specification
pub struct VesselGeometry {
    pub vessel_type: VesselType,
    pub length: f64,      // meters
    pub radius: f64,      // meters
    pub modifications: Vec<GeometryModification>,
}

// Vessel types
pub enum VesselType {
    Straight,
    Curved { curvature: f64 },
    Bifurcation { angle: f64, branch_ratio: f64 },
}

// Geometry modifications
pub enum GeometryModification {
    Stenosis(StenosisParams),
    Aneurysm(AneurysmParams),
    Stent(StentParams),
}

pub struct StenosisParams {
    pub center: f64,          // x position (0-1 normalized)
    pub diameter_ratio: f64,  // 0-1, smaller = more severe
    pub length: f64,          // extent
}

pub struct AneurysmParams {
    pub center: f64,          // x position
    pub diameter_ratio: f64,  // >1, larger = bigger bulge
    pub length: f64,          // extent
}

pub struct StentParams {
    pub start: f64,           // x start position
    pub end: f64,             // x end position
    pub porosity: f64,        // 0-1, flow reduction factor
}
```

## Field Types

```rust
// Query result at specific points
pub struct FieldQueryResult {
    pub u: Vec<f64>,      // x-velocity
    pub v: Vec<f64>,      // y-velocity
    pub p: Vec<f64>,      // pressure
    pub wss: Option<Vec<f64>>,  // wall shear stress (if on wall)
}

// Grid query response
pub struct GridQueryResponse {
    pub dimensions: [usize; 2],  // (nx, ny)
    pub dx: f64,                 // grid spacing x
    pub dy: f64,                 // grid spacing y
    pub x_min: f64,
    pub x_max: f64,
    pub y_min: f64,
    pub y_max: f64,
    pub u_field: Vec<f64>,       // flattened u values
    pub v_field: Vec<f64>,       // flattened v values
    pub p_field: Vec<f64>,       // flattened p values
    pub mask: Vec<bool>,         // true if inside vessel
    pub inference_time_ms: f64,
}
```

## Physics Types

```rust
// Fluid properties (blood-like)
pub struct FluidProperties {
    pub density: f64,           // kg/m³ (default: 1060)
    pub dynamic_viscosity: f64, // Pa·s (default: 0.004)
}

// Boundary condition types
pub enum BoundaryCondition {
    Inlet { velocity_profile: VelocityProfile },
    Outlet { pressure: f64 },
    Wall,  // no-slip
}

pub enum VelocityProfile {
    Parabolic { max_velocity: f64 },
    Pulsatile { amplitude: f64, frequency: f64, phase: f64 },
    Uniform { velocity: f64 },
}

// Simulation configuration
pub struct SimulationConfig {
    pub fluid: FluidProperties,
    pub inlet: BoundaryCondition,
    pub outlet: BoundaryCondition,
    pub time_dependent: bool,
}
```

## IPC Types

```rust
// Request types
pub enum IpcRequest {
    Initialize(VesselParams),
    Reset,
    QueryFields { points: Vec<Point2D>, time: f64 },
    QueryGrid { nx: usize, ny: usize, time: f64 },
    ModifyGeometry(GeometryModification),
    GetStatus,
    GetMetrics,
}

// Response status
pub struct StatusResponse {
    pub initialized: bool,
    pub trained: bool,
    pub inference_count: u64,
    pub avg_inference_time_ms: f64,
    pub uptime_secs: u64,
}

// Performance metrics
pub struct PerformanceMetrics {
    pub fps: f64,
    pub inference_time_ms: f64,
    pub gpu_utilization: Option<f64>,
    pub memory_used_mb: Option<f64>,
}

// Vessel parameters for initialization
pub struct VesselParams {
    pub length: f64,
    pub radius: f64,
    pub stenosis_ratio: Option<f64>,  // deprecated, use modifications
}
```

## Usage

```rust
use rtx_hemodynamics_shared::geometry::{VesselGeometry, Point2D};
use rtx_hemodynamics_shared::physics::SimulationConfig;
use rtx_hemodynamics_shared::ipc::IpcRequest;

// Create a straight vessel
let vessel = VesselGeometry::straight(0.1, 0.005).unwrap();

// Initialize simulation
let config = SimulationConfig::default();
let request = IpcRequest::initialize(vessel, config);
```

## Serde Serialization

All types derive `Serialize` and `Deserialize`:

```rust
use serde_json;

let params = VesselParams { length: 0.1, radius: 0.005, stenosis_ratio: None };
let json = serde_json::to_string(&params)?;
let parsed: VesselParams = serde_json::from_str(&json)?;
```

## Feature Flags

- `default` - Standard serde serialization
- `typescript` - Generate TypeScript type definitions (via `ts-rs`)