update

Author: masoudzp

docs/FAQ.md

@@ -0,0 +1,51 @@
+
+### **What kind of license does PortPy use?**
+PortPy code is distributed under the **Apache 2.0 license with the Commons Clause**.  
+It is available **free for non-commercial academic purposes**.  
+For commercial use, please contact the PortPy PI, Masoud Zarepisheh at [zarepism@mskcc.org](mailto:zarepism@mskcc.org).
+
+---
+
+### **How can I use my own patient data?**
+PortPy currently supports importing patient data only from the **Eclipse TPS** using its API  
+([see notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/eclipse_photon_dose_calculation.ipynb)). This includes extracting all necessary data for optimization,  
+such as the **dose influence matrix** (i.e., a 2D matrix representing 3D dose distributions  
+from thousands of beamlets).
+
+---
+
+### **Can I use other open-source software for dose calculation and PortPy for planning optimization?**
+One of PortPy’s goals is to generate **clinically usable, deliverable plans** with dose calculations  
+that match commercial TPS accuracy. Therefore, we currently do **not** support integrating  
+other open-source dose engines into PortPy.
+
+However, users are welcome to use other software for dose calculation and PortPy solely for  
+optimization **if clinical-level dose accuracy is not required** for their use case.
+
+---
+
+### **Can I do proton therapy optimization with PortPy?**
+Currently, PortPy only supports **photon therapy optimization**.  
+Proton therapy support is expected to be released in 2026.
+
+---
+
+### **I have a medical physics background but not in mathematical optimization. Can I still use PortPy?**
+Absolutely. PortPy is designed to be **user-friendly and accessible**.  
+You can get started using our ready-made **Jupyter Notebooks and tutorials** without needing  
+a deep understanding of optimization theory.
+
+---
+
+### **I have a mathematical optimization background but not in medical physics. Can I still use PortPy?**
+Yes. Many PortPy contributors come from optimization and engineering backgrounds.  
+The **benchmark datasets** and **baseline algorithms** are designed to help users without  
+medical physics expertise explore radiotherapy treatment planning.
+
+---
+
+### **I have an engineering/software development background. Can I contribute to PortPy?**
+Yes! PortPy is an open-source project and **welcomes community contributions**.  
+Please reach out to Gourav Jhanwar, Lead Developer ([jhanwarg@mskcc.org](mailto:jhanwarg@mskcc.org)).
+
+

docs/contact_us.md

@@ -0,0 +1,10 @@
+If you encounter a bug or have questions about using PortPy, we recommend creating an **Issue on GitHub**: 👉 [GitHub Issues](https://github.com/PortPy-Project/PortPy/issues)  
+This ensures your question is tracked and helps other users who may face similar issues.
+
+If you prefer to communicate via email:
+
+- For technical questions, contact the lead developer:  
+   Gourav Jhanwar — [jhanwarg@mskcc.org](mailto:jhanwarg@mskcc.org)
+
+- For general inquiries, contact the PI:  
+   Masoud Zarepisheh — [zarepism@mskcc.org](mailto:zarepism@mskcc.org)

docs/images/AI_Pyramid.png

@@ -1,44 +1,140 @@
-PortPy
+# What is PortPy?
 
-> Modern Portfolio Optimization in Python
+<img src="./images/Linac.gif" align="right" alt="Radiotherapy 101" width="30%" height="30%" margin-right="10px">
 
----
-Test7
-Welcome to **PortPy**! Effortlessly optimize, analyze, and visualize your investment portfolios with a modern, user-friendly Python library.
+**PortPy**, short for **P**lanning and **O**ptimization for **R**adiation **T**herapy, is an open-source Python library 
+designed to advance cancer radiotherapy treatment planning optimization. Radiotherapy plays a critical role in 
+treating over half of all cancer patients, whether as a standalone treatment or in combination with surgery, 
+chemotherapy, or immunotherapy. It works by delivering high-energy radiation beams to tumors, aiming to destroy 
+cancerous cells while minimizing damage to the surrounding healthy tissues. 
+Given that each patient has a unique anatomy, it is essential to customize the 
+radiation beams' shape, angle, and intensity. The goal is to maximize damage to the 
+tumor while minimizing exposure to healthy surrounding tissues. This challenge translates into modeling and 
+solving large-scale, 
+patient-specific mathematical optimization problems. PortPy aims to accelerate research 
+in this interdisciplinary field by offering **tools**, **baseline algorithms**, and **benhcmark datasets**.
 
-<div align="center">
-  <img src="https://raw.githubusercontent.com/your-org/portpy/main/assets/logo.png" alt="PortPy Logo" width="180"/>
-</div>
 
----
 
-## 🚀 Features
+## 🚀 Main Features
 
-- **Intuitive API** for portfolio construction and optimization
-- **Interactive visualizations** for risk and return analysis
-- **Jupyter notebook support** for reproducible research
-- **Extensive documentation** and real-world examples
+- **IMRT/VMAT Planning Optimization (including AI):**  
+  Includes support for IMRT fluence map optimization and leaf sequencing (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb)), 
+VMAT direct aperture optimization 
+(see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_tutorial.ipynb)), 
+AI-based dose-prediction IMRT 
+(see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_dose_prediction.ipynb)) 
+and VMAT (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_dose_prediction.ipynb)) planning. 
 
----
+- **Integration with Commercial TPS:**  
+  PortPy outputs IMRT/VMAT plans in DICOM-RT format which can be exported into commercial TPSs 
+(see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_tps_import.ipynb)). For Eclipse TPS users:
+    - PortPy outputs IMRT optimal fluence maps in an Eclipse-compatible format (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_tps_import.ipynb)).
+    - It supports automated data extraction (e.g., beamlets, voxels, dose influence matrix)  
+  from Eclipse via its scripting API in a PortPy-compatible format (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/eclipse_photon_dose_calculation.ipynb)).
 
-## Get Started
+- **Benchmark Datasets:**  
+  Provides access to a curated dataset of **100 lung cancer patients** with all necessary components for treatment planning optimization 
+(beamlet, voxel, pre-computed dose influence matrix). IMRT plans generated using our in-house automated planning 
+system, **ECHO**, are included for benchmarking  
 
-- [Installation Guide](installation.md)
-- [Quickstart Tutorial](quickstart.md)
-- [API Reference](reference/)
-- [GitHub Repository](https://github.com/your-org/portpy)
+- **Globally Optimal IMRT/VMAT Plans:**  
+  Implements slow but exact algorithms (e.g., Mixed-Integer Programming) to compute globally optimal plans, useful for benchmarking and validating heuristic algorithms.
 
----
 
-## Why PortPy?
+## 📢 News
+- **[PortPy v1.1.0 released]** The following features have been added:
+    
+     - **Eclipse users can use their own dataset**: For more info, see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/eclipse_photon_dose_calculation.ipynb).
+     - **Lung benchmark dataset expanded**: Lung dataset expanded to 100 patients and is now hosted on [HuggingFace](https://huggingface.co/datasets/PortPy-Project), 
+      making it easier to access and use them in your research (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb)).
+     - **VMAT column generation algorithm added**: It finds a "warm start" 
+      (i.e., good but not neceassirily optimal) solution quickly for the current VMAT SCP (Sequential Convex Programming) optimization algorithm (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_tutorial.ipynb)).
+     - **Enhanced visualization**: The evaluation table has been improved for better readability and analysis (see [notebook](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb)). 
 
-- Built for both beginners and professionals
-- Actively maintained and open source
-- Integrates seamlessly with the Python data science stack
+[//]: # ()
+[//]: # (## 🚀 Key Components: Benchmark Datasets, Baseline Algorithms, and PortPy Toolkit)
 
----
+[//]: # ()
+[//]: # (<img src="./images/AI_Pyramid.png" align="right" alt="Radiotherapy 101" width="50%" height="40%">)
 
-<div align="center">
-  <a href="quickstart.md"><b>Start Optimizing Your Portfolio →</b></a>
-</div>
+[//]: # (  )
+[//]: # (This pyramid figure illustrates the inspiration behind developing PortPy, drawing from )
+
+[//]: # (successful open-source practices in the AI and computer science communities. )
+
+[//]: # (Tools like PyTorch and TensorFlow, along with benchmark datasets such as )
+
+[//]: # (ImageNet and algorithms like AlexNet, have revolutionized AI and data science. )
+
+[//]: # (Our goal is to replicate this successful model in the field of radiotherapy by )
+
+[//]: # (equipping researchers with PortPy toolkit, benchmark algorithms, and datasets, )
+
+[//]: # (as outlined below:)
+
+[//]: # ()
+[//]: # (1. **PortPy Toolkit**. A set of python classes and functions allowing users to load the data, )
+
+[//]: # (generate IMRT/VMAT plans, and evaluate/visualize the results. For more info, see our Jupyter Notebooks [basic_tutorial]&#40;&#41;)
+
+[//]: # (2. **Benchmark Datasets**. We have curated and made publicly available a dataset of 100 lung cancer patients,)
+
+[//]: # (which includes all the necessary data for treatment plan optimization &#40;e.g., beamlets, voxels, pre-computed dose influence matrix&#41;. )
+
+[//]: # (These data are extracted from the commercial Eclipse treatment planning system using its API. Using your own data is currently only supported for Eclipse TPS users. For more info, see our Jupyter Notebooks &#40;[eclipse_photon_dose_calculation]&#40;https://github.com/PortPy-Project/PortPy/blob/master/examples/eclipse_photon_dose_calculation.ipynb&#41;)
+
+[//]: # (3. **Baseline Algorithms**. This includes two sets of algorithms: 1&#41; fast algorithms that can generate IMRT/VMAT plans within the clinical time-frame &#40;in oder of minutes/hours&#41;,)
+
+[//]: # (2&#41; slow algorithms that can generate globally optimal plans for benchmaking purposes. These plans could take weeks to generate and often involve some simplistic assumptions &#40;e.g., ignoring plan delivery efficiency in VMAT&#41;.)
+
+[//]: # ()
+[//]: # (> Modern Portfolio Optimization in Python)
+
+[//]: # ()
+[//]: # (---)
+
+[//]: # (Test7)
+
+[//]: # (Welcome to **PortPy**! Effortlessly optimize, analyze, and visualize your investment portfolios with a modern, user-friendly Python library.)
+
+[//]: # ()
+[//]: # (<div align="center">)
+
+[//]: # (  <img src="https://raw.githubusercontent.com/your-org/portpy/main/assets/logo.png" alt="PortPy Logo" width="180"/>)
+
+[//]: # (</div>)
+
+[//]: # ()
+[//]: # (---)
+
+[//]: # ()
+[//]: # ()
+[//]: # ()
+[//]: # (---)
+
+[//]: # ()
+[//]: # (## Get Started)
+
+[//]: # ()
+[//]: # (- [Installation Guide]&#40;installation.md&#41;)
+
+[//]: # (- [Quickstart Tutorial]&#40;quickstart.md&#41;)
+
+[//]: # (- [API Reference]&#40;reference/&#41;)
+
+[//]: # (- [GitHub Repository]&#40;https://github.com/your-org/portpy&#41;)
+
+[//]: # ()
+[//]: # (---)
+
+[//]: # ()
+[//]: # (---)
+
+[//]: # ()
+[//]: # (<div align="center">)
+
+[//]: # (  <a href="quickstart.md"><b>Start Optimizing Your Portfolio →</b></a>)
+
+[//]: # (</div>)
 

docs/images/Linac.gif

@@ -0,0 +1,64 @@
+## Installation
+1. **Using pip**:
+   
+    * Run the command
+      ```
+      pip install portpy
+      ```
+    * You can install optional packages using
+      ```
+      pip install portpy[mosek, pydicom]
+      ```
+   * For installing AI related packages
+     ```
+      pip install portpy[ai]   
+     ```
+   * For installing all the additional packages
+     ```
+      pip install portpy[all]   
+     ```
+
+2. **From source**:
+   
+    * Clone this repository using
+      ```
+      git clone https://github.com/PortPy-Project/PortPy.git
+      ```
+    * Navigate to the repository with
+      ```
+      cd portpy
+      ```
+
+    * Install the dependencies within a Python virtual environment or Anaconda environment. To set up in a Python virtual environment, install all the dependencies specified in requirements.txt as follows:
+        * Create the virtual environment with
+          ```
+          python3 -m venv venv
+          ```
+        * Activate the environment with 
+          ```
+          source venv/bin/activate
+          ```
+        * Install the requirements using
+          ```
+          pip install -r requirements.txt
+          ```
+
+
+## Quick Start Guide
+
+
+The easiest way to start is through the PorPy following Jupiter Notebook examples. 
+
+| Example File                          	                                                                                                                          | Description                                                                                                                                                           	                                                                          |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [1_basic_tutorial.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb)                	                                  | Demonstrates the main functionalities of PortPy (e.g., Access data, create an IMRT plan, visualize)                                                                   	                                                                          |
+| [eclipse_photon_dose_calculation.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/eclipse_photon_dose_calculation.ipynb)                	 | Demonstrates the capability of running dose calculation for patients outside PortPy dataset using Varian's photon dose calculation module and perform optimization in PortPy                                                                   	 |
+| [vmat_scp_tutorial.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_tutorial.ipynb)               	                                 | Creates a VMAT plan using sequential convex programming                                                                                                               	                                                                          |
+| [vmat_scp_dose_prediction.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_dose_prediction.ipynb)                                   | Predicts 3D dose distribution using deep learning and converts it into a deliverable VMAT plan                                                                        	                                                                          |
+| [3d_slicer_integration.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/3d_slicer_integration.ipynb)           	                             | Creates an IMRT plan and visualizes it in 3D-Slicer                                                                                                                   	                                                                          |
+| [imrt_tps_import.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_tps_import.ipynb)                	                                    | 1. Outputs IMRT plan in DICOM RT format and imports it into TPS. <br>2. Outputs IMRT plan optimal fluence in an Eclipse-compatable format and imports it into Eclipse 	                                                                          |
+| [vmat_tps_import.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_tps_import.ipynb)                 	                                   | Outputs VMAT plan in DICOM RT format and imports it into TPS                                                                                                          	                                                                          |
+| [imrt_dose_prediction.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_dose_prediction.ipynb)            	                              | Predicts 3D dose distribution using deep learning and converts it into a deliverable IMRT plan                                                                        	                                                                          |
+| [vmat_global_optimal.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_global_optimal.ipynb)           	                                 | Finds a globally optimal VMAT plan                                                                                                                                    	                                                                          |
+| [beam_orientation_global_optimal.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/beam_orientation_global_optimal.ipynb) 	                   | Finds globally optimal beam angles for IMRT                                                                                                                           	                                                                          |
+| [dvh_constraint_global_optimal.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/dvh_constraint_global_optimal.ipynb)  	                      | Finds a globally optimal plan meeting Dose Volume Histogram (DVH) constraints                                                                                         	                                                                          |

docs/index.md

@@ -0,0 +1,2 @@
+Additional learning materials, tutorials, and external tools will be added here soon.  
+Stay tuned!

docs/installation.md

@@ -1,5 +1,19 @@
 /* docs/extra.css */
 
+/* Top-level menu items — with or without submenus */
+.md-nav__list > .md-nav__item > .md-nav__link {
+  font-weight: bold;
+  font-size: 1.05em;
+  padding-left: 0.5em;
+}
+
+/* Sub-menu items */
+.md-nav__item--nested .md-nav__item .md-nav__link {
+  font-weight: normal;
+  font-size: 0.95em;
+  padding-left: 1.5em;
+}
+
 .md-sidebar {
     /* width: 210px !important;         Adjust this value to your liking */
     /*min-width: 180px !important;      Prevents being too small on resize */