---
title: AEGIS Pharma PK/PD Simulation
emoji: 💊
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
---

# AEGIS Pharma PK/PD Simulation Engine

Advanced Pharmacokinetic/Pharmacodynamic (PK/PD) simulation engine for Window 10 Visual Kinetic integration.

## Overview

This Hugging Face Space provides a multi-compartment PBPK (Physiologically-Based Pharmacokinetic) engine that simulates vaccine distribution through specific organs with real-time kinetic modeling.

## Features

- **Multi-Compartment PBPK Modeling**: Simulates drug distribution across tissue and blood compartments
- **Organ-Specific Parameters**: Customizable tissue volume, blood flow rates, and partition coefficients
- **Real-Time Kinetics**: 150-point time series for smooth 3D visualization
- **Pharmacodynamic Effects**: Calculates localized cellular activation and systemic vitals
- **REST API**: Simple JSON-based API for integration

## API Endpoint

### POST `/api/v1/simulate/pkpd`

Runs a PK/PD simulation for a vaccine in a specific organ.

#### Request Body

```json
{
  "initial_dose": 100.0,
  "organ": {
    "name": "Heart",
    "volume": 0.3,
    "blood_flow": 5.0,
    "partition_coefficient": 1.2
  },
  "clearance_systemic": 0.2,
  "e_max": 100.0,
  "ec_50": 10.0,
  "simulation_hours": 72
}
```

#### Parameters

- `initial_dose` (float): Administered vaccine amount in mg
- `organ` (object): Target organ parameters
  - `name` (string): Organ name
  - `volume` (float): Tissue compartment volume in Liters
  - `blood_flow` (float): Blood flow rate to tissue in L/min
  - `partition_coefficient` (float): Tissue-to-plasma partition ratio (Kp)
- `clearance_systemic` (float): Total metabolic clearance (Cl) in L/min
- `e_max` (float): Maximum pharmacodynamic response
- `ec_50` (float): Concentration causing 50% maximal effect
- `simulation_hours` (int): Simulation duration (1-336 hours)

#### Response

```json
{
  "status": "success",
  "time_series_hours": [0, 0.48, 0.96, ...],
  "kinetics": {
    "organ_amount": [...],
    "organ_concentration": [...],
    "blood_amount": [...],
    "blood_concentration": [...]
  },
  "vitals_metrics": {
    "localized_cellular_activation_percent": [...],
    "simulated_core_body_temperature": [...]
  }
}
```

## Mathematical Model

The engine uses a two-compartment ODE system:

```
dA_organ/dt = Q_organ * (C_central - C_organ/Kp)
dA_central/dt = Q_organ * (C_organ/Kp - C_central) - Cl * C_central
```

Where:
- `A_organ`: Amount in target organ
- `A_central`: Amount in central circulation
- `Q_organ`: Blood flow to organ
- `Kp`: Partition coefficient
- `Cl`: Systemic clearance

## Integration with Window 10

This space is designed to work seamlessly with the AEGIS Portal Window 10 Visual Kinetic system:

1. **Frontend**: Loads 3D organ models from `/modals` directory
2. **Backend**: Fetches vaccine data from `window8_manufacturing_protocols` table
3. **Pharma Space**: Performs PK/PD simulation with organ-specific parameters
4. **Visualization**: Results are mapped to 3D organ models using Babylon.js

## Deployment

### Prerequisites

```bash
pip install huggingface_hub
```

### Deploy to Hugging Face

```bash
# Windows
deploy-pharma-space.bat

# Linux/Mac
chmod +x deploy-pharma-space.sh
./deploy-pharma-space.sh
```

## Local Development

```bash
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
```

## Example Usage

```python
import requests

response = requests.post(
    "https://gsstec-pharma.hf.space/api/v1/simulate/pkpd",
    json={
        "initial_dose": 100.0,
        "organ": {
            "name": "Heart",
            "volume": 0.3,
            "blood_flow": 5.0,
            "partition_coefficient": 1.2
        },
        "simulation_hours": 72
    }
)

data = response.json()
print(f"Peak concentration: {max(data['kinetics']['organ_concentration'])} mg/L")
```

## Technical Stack

- **FastAPI**: High-performance web framework
- **SciPy**: ODE solver (RK45 method)
- **NumPy**: Numerical computations
- **Uvicorn**: ASGI server

## License

Gaston Software Solutions Tec, Uganda
AEGIS Bio Digital Lab 10

## Support

For issues or questions, contact the AEGIS development team.