A community effort to develop an open standard library for Medical Physics in Python. We build high quality, transparent software together via peer review and open source distribution. Open code is better science.

PyMedPhys is an open-source Medical Physics Python library built by an open community that values code sharing, review, improvement, and learning from each other. It is inspired by the collaborative work of our physics peers in astronomy and the Astropy Project. PyMedPhys is available on PyPI and GitHub.

PyMedPhys supports three main ways of working:

• a Python library for notebooks, scripts, and clinic-specific tooling
• a command line interface (CLI) for repeatable automation
• a point-and-click app layer for selected workflows

PyMedPhys is currently within the beta stage of its life-cycle. It will stay in this stage until the version number leaves 0.x.x and enters 1.x.x. While PyMedPhys is in beta stage, no API is guaranteed to be stable from one release to the next. Upgrading pymedphys can therefore break existing scripts or workflows. We try to stay ahead of that by documenting breaking changes in the Release Notes.

If you are new to PyMedPhys, start with these four questions in order:

1. What PyMedPhys can do
2. Choose your path
3. Installation options
4. Quick Start Guide

PyMedPhys is often used to:

• compare dose or fluence-like data with gamma, interpolation, and MetersetMap
• work with DICOM and pseudonymisation workflows
• work with delivery, logfile, and iCom data
• query or integrate with Mosaiq
• use point-and-click apps for selected workflows

PyMedPhys currently supports Python 3.10, 3.11, and 3.12.

For most users, we recommend using uv to create an environment and install PyMedPhys:

uv python install 3.12
uv venv --python 3.12
uv pip install "pymedphys[user]"

If you cannot use uv on your workstation, the Quick Start Guide also includes a standard Python + venv + pip fallback path.

Use the Python library when you want notebooks, analysis, plots, and clinic-specific workflows.

Use the CLI when you want repeatable commands, scheduled jobs, or shell automation.

Use the app layer when you want the least coding and a graphical workflow.

For a fuller comparison, read Choose your path.

The PyMedPhys documentation has two overarching guides:

1. The Users Guide: where you can get started with the library, the CLI, and the app layer; read task-focused how-to guides; find background information on larger projects and concepts; and browse the Technical Reference when you already know the feature you need.
2. The Contributors Guide: for those who want to contribute to PyMedPhys. This includes the Contributors Guide landing page, detailed workstation setup guides, important repository information, and some tips & tricks for common problems.

PyMedPhys has a GitHub Discussions page to help users find their feet and to support collaboration and general discussion.

PyMedPhys' first paper in the Journal of Open Source Software contains more background information, including the Statement of Need. You can access the paper here.

When referencing PyMedPhys, please cite this paper as follows:

Biggs, S., Jennings, M., Swerdloff, S., Chlap, P., Lane, D., Rembish, J., McAloney, J., King, P., Ayala, R., Guan, F., Lambri, N., Crewson, C., Sobolewski, M. (2022). PyMedPhys: A community effort to develop an open, Python-based standard library for medical physics applications. Journal of Open Source Software, 7(78), 4555, https://doi.org/10.21105/joss.04555

PyMedPhys uses uv for package and project management.

After cloning the repository, install the PyMedPhys dependencies and set up pre-commit by running:

uv sync --extra all --group dev
uv run -- pre-commit install

Run automated tests with:

uv run -- pymedphys dev tests

PyMedPhys is what it is today due to its maintainers and contributors, both past and present. Here is our team.

• Simon Biggs

  • Anthropic PBC

• Stuart Swerdloff

  • SJS Targeted Solutions, LLP, New Zealand

• Matthew Jennings

  • Icon Group, Australia

• Phillip Chlap

  • Radformation Inc., USA
  • University of New South Wales, Australia

• Derek Lane

  • ELEKTA AB, Houston TX

• Marcelo Jordao

  • ELEKTA AB, Hong Kong SAR

• Jake Rembish

  • UT Health San Antonio, USA

• Nicola Lambri

  • IRCCS Humanitas Research Hospital, Italy
  • Humanitas University, Italy

• Cody Crewson

  • Saskatchewan Cancer Agency, Canada

• Fada Guan

  • Yale University School of Medicine, USA

• Marcus Fisk

  • Cancer Care Riverina, Australia

• Matthew Cooper
• Pedro Martinez
• Rafael Ayala
• Matthew Sobolewski
• Paul King
• Jacob McAloney