hermes-drh 0.1.0

HERMES: patient-specific 3D FDTD DRH simulation (MRI voxels, SAR, thermal, antenna optimization)

hermes-drh

HERMES (Hyperthermia Electromagnetic and Robust Modeling Evaluation Suite) is a Python framework for patient-specific deep regional hyperthermia (DRH) research: MRI-derived voxel models, 3D FDTD electromagnetic simulation, SAR and simplified thermal post-processing, optional four-quadrant antenna optimization, and visualization.

All CLI paths below assume your current working directory is CODE/, so relative paths like dataset/validation_data/001 resolve to CODE/dataset/validation_data/001.

Development environment (CODE/.venv)

Create an isolated venv inside CODE/ (keeps thesis dataset/ and best_model.pth reachable via relative paths):

cd path/to/thesis/CODE

# One-shot bootstrap (editable install, default extras: all)
bash scripts/bootstrap_venv.sh

source .venv/bin/activate
hermes-simulate --help

Manual equivalent:

cd path/to/thesis/CODE
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip wheel
pip install -e ".[all]"    # or [dev], [segmentation], [segmentation,dashboard]

Checkpoint and validation data (from CODE/):

export HERMES_CHECKPOINT="$PWD/best_model.pth"

hermes-simulate --modalities-dir dataset/validation_data/001 \
  --max-dim 80 --time-steps 200 --skip-animations \
  --results-dir results/smoke_001

If BraTS folders live next to CODE/ (thesis root) instead of under CODE/dataset/:

hermes-simulate --modalities-dir ../dataset/validation_data/001 \
  --max-dim 80 --time-steps 200 --skip-animations \
  --results-dir results/smoke_001

TestPyPI smoke test (clean install in CODE/.venv)

Verifies the published wheel while still using local dataset/ (run every command from CODE/):

cd path/to/thesis/CODE
rm -rf .venv && python3 -m venv .venv && source .venv/bin/activate
pip install -U pip

pip install -i https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  "hermes-drh[segmentation]==0.1.0"

export HERMES_CHECKPOINT="$PWD/best_model.pth"

hermes-simulate --modalities-dir dataset/validation_data/001 \
  --max-dim 80 --time-steps 200 --skip-animations \
  --results-dir results/testpypi_smoke

Production PyPI (after release):

pip install "hermes-drh[segmentation]==0.1.0"

Install extras

Command	Use case
pip install -e .	FDTD from existing segmentation NIfTI only
pip install -e ".[segmentation]"	--modalities-dir / --modalities (PyTorch + MONAI)
pip install -e ".[dashboard]"	Streamlit dashboard
pip install -e ".[all]"	Segmentation + dashboard
pip install -e ".[dev]"	Contributors (pytest, build, twine, ruff)

Requires Python 3.11–3.13. For MP4 animations, install ffmpeg on your system.

Quickstart (from CODE/)

source .venv/bin/activate   # after bootstrap above

# Existing segmentation NIfTI (no PyTorch)
hermes-simulate --seg path/to/labels.nii.gz --results-dir results/from_seg

# BraTS-style folder under CODE/dataset/
export HERMES_CHECKPOINT="$PWD/best_model.pth"
hermes-simulate --modalities-dir dataset/validation_data/001 --results-dir results/from_modalities

# Bundled example YAML
hermes-simulate --config configs/simulation_example.yaml \
  --modalities-dir dataset/validation_data/001 \
  --results-dir results/example_yaml

# MP4s from streamed frames
hermes-build-animations results/from_modalities --subsample 5 --skip-3d

Dashboard

source .venv/bin/activate
pip install -e ".[dashboard]"   # or ".[all]"
hermes-dashboard

Run from CODE/ so the dashboard finds results/ and can launch hermes-simulate.

Thesis paper bundle (not on PyPI)

From CODE/ (uses local hermes-simulate when the venv is active):

python run_paper_bundle.py --modalities-dir dataset/validation_data/001 --bundle-root results

License

MIT — see LICENSE.