Introduction#

pyRadPlan is a multi-modality radiotherapy treatment planning toolkit in Python, born from the established MATLAB-based toolkit matRad. It is developed by the Radiotherapy Optimization group at the German Cancer Research Center (DKFZ).

Mission#

pyRadPlan’s mission is AI-ready research treatment planning. It is primarily aimed at:

matRad users seeking a Python-native equivalent of the matRad workflow.
Treatment planning researchers who need a flexible, extensible platform for algorithmic development and experimentation.

The toolkit keeps a clear focus on numerics while remaining easy to integrate with modern AI tooling. This translates into two foundational design choices that are consistent throughout the entire codebase:

Pydantic-based data structures — the main data structures derive from a common PyRadPlanBaseModel base class backed by pydantic. Pydantic enforces schema validation and provides consistent model dumping and matRad conversion hooks. Some objects contain SimpleITK images or sparse matrices, so fully JSON-ready serialization may still require converting those payloads explicitly.
Backend-agnostic algorithms via the Python Array API — dose calculation and optimization kernels are written against the Python Array API standard rather than NumPy directly where practical. The preferred namespace is configured through pyRadPlan.core.xp_utils, enabling NumPy, CuPy, or PyTorch-backed paths depending on which optional dependencies are installed and supported by the current workflow.

matRad Interoperability#

pyRadPlan is designed to interoperate closely with matRad:

Patient data (CT, structure set) can be loaded directly from *.mat files produced by matRad using load_patient().
All major data structures expose a to_matrad() method that serializes them back to a matRad-compatible representation, enabling round-trip workflows between the two systems.
Imported matRad data can be used in the Python planning workflow, and exported pyRadPlan structures can be handed back to matRad-compatible tooling.

Data Structures Overview#

The following table lists the main objects in a pyRadPlan workflow and the section of the concepts guide that explains them in detail.

Object	Type	Description
`ct`	`CT`	CT image in Hounsfield Units
`cst`	`StructureSet`	Segmented structures (targets, OARs) with optimization objectives
`pln`	`Plan`	Plan configuration (modality, machine, fractionation, algorithm settings)
`stf`	`SteeringInformation`	Beam geometry (gantry/couch angles, spots/bixels)
`dij`	`Dij`	Dose influence matrix (voxels × beamlets)
`fluence`	`numpy.ndarray`	Optimized beamlet weights / monitor units